Merge origin/main into codex/migrate-pr-806-to-main

# Conflicts:
#	AGENTS.md
#	src/agent-cli-provider/adapters/claude.ts
#	src/agent-cli-provider/types.ts
#	src/agent/agent-task-executor.js
#	task-lib/attachable-watcher.js
#	task-lib/runner.js
#	task-lib/store.js
#	task-lib/watcher.js
#	tests/agent-cli-provider/parity.test.js

Author: tomdps

AGENTS.md

@@ -52,6 +52,7 @@ Destructive commands (need permission): `zeroshot kill`, `zeroshot clear`, `zero
 | Claude settings overlay      | `src/worktree-claude-config.js`                                         |
 | Detached task cleanup owner  | `task-lib/command-spec-cleanup.js`                                      |
 | Shared watcher output path   | `task-lib/watcher-output-runtime.js`                                    |
+| Provider session reuse       | `src/agent/provider-session.js`                                         |
 | Start-cluster helper         | `lib/start-cluster.js`                                                  |
 | Legacy worker facade         | `lib/cluster-worker/`                                                   |
 | Legacy worker executable     | `bin/zeroshot-cluster-worker.js`                                        |
@@ -351,13 +352,38 @@ and cleanup ownership intact; retry and cleanup stay blocked until a later kill
 Cancellation before PID publication is a durable task intent. Both watcher paths check it before
 provider spawn and immediately after publishing the owned PID boundary; callers retain their task
 handle until terminal state and command cleanup are both confirmed.
+Provider continuation is agent- and generation-owned and becomes durable only after logical output
+validation and the `onComplete` hook succeed. A requested resume is successful only when the
+watcher captures that exact same nonempty provider session ID; absent or forked identity fails the
+attempt before hooks and forces the retry to rebuild full context. Watchers track every unique
+session ID observed in a task; once two IDs differ, the persisted capture is permanently ambiguous
+even if a later event repeats the requested ID. Persist SQLite rowid high-water and applied-guidance
+cursors as canonical decimal strings, bind them to SQLite as `BigInt`, and never coerce them through
+JavaScript `Number`. Persist those cursors and a bounded SHA-256 selected-prompt identity with the
+observed provider session; never persist the selected prompt text. Restored
+continuations fail closed unless the final durable `TASK_COMPLETED` boundary and all provenance
+match. Full and continuation source/guidance reads are bounded through the captured high-water;
+continuations query strictly after their prior sequence and de-duplicate the exact triggering
+message by ledger ID. Timestamps are display/filter metadata, not continuation cursors: concurrent
+writers can share one millisecond. If the installed CLI cannot resume, rebuild full context or fail
+before launch—never send a continuation delta to a fresh provider session.
+
+Provider session reuse is explicit-ID and agent-owned. Watcher-observed IDs are distinct from
+requested resume IDs. Commit continuation only after logical/structured success and bind it to the
+completed task, agent, generation, provider, cwd, and worktree. A resumed turn sends only new
+trigger/guidance context; it never replays static prompts or ISSUE_OPENED/PLAN_READY packs already in
+the provider session. Persist continuation in that agent's `agentStates` entry, never in native
+`ClusterLedger`, never select a cwd-wide "latest" session, and never share across agents. Durable
+restore fails closed unless the last lifecycle boundary is the exact matching `TASK_COMPLETED`;
+live, failed, retry/backoff, provider-switch, unsupported, Docker, and workspace-drift states start
+fresh.
 
 ### Guidance Messaging
 
 - Topics: `USER_GUIDANCE_CLUSTER`, `USER_GUIDANCE_AGENT` (see `src/guidance-topics.js`).
 - Mailbox helper: `ledger.queryGuidanceMailbox()` with `messageBus.queryGuidanceMailbox()` passthrough.
 - Live injection: `Orchestrator.sendGuidanceToAgent()` uses `agent.injectInput()` to attempt PTY stdin; always persists `USER_GUIDANCE_AGENT` with `metadata.delivery` (`status: injected|unsupported`, `method: pty`, `taskId`, `reason`).
-- Safe-point queue fallback: `AgentWrapper._buildContext()` pulls queued guidance via `collectQueuedGuidance()` and injects a delimited block in `agent-context-builder` between Instructions and Output Schema. Cursor: `agent.lastGuidanceAppliedAt`.
+- Safe-point queue fallback: `AgentWrapper._buildContext()` pulls queued guidance via `collectQueuedGuidance()` and injects a delimited block in `agent-context-builder` between Instructions and Output Schema. Durable sequence: `agent.lastGuidanceAppliedId`.
 
 ### Agent Configuration (Minimal)
 

cli/commands/inspect.js

@@ -140,6 +140,7 @@ function buildTaskSummary(task, details) {
     error: task.error || null,
     cwd: task.cwd || null,
     sessionId: task.sessionId || null,
+    requestedResumeSessionId: task.requestedResumeSessionId || null,
     attachable: Boolean(task.attachable),
     socketPath: details.socketPath.path,
     socketPathExists: details.socketPath.exists,

cli/index.js

@@ -2837,7 +2837,7 @@ taskCmd
   .option('--model <model>', 'Model id override for the provider')
   .option('--model-level <level>', 'Model level override (level1, level2, level3)')
   .option('--reasoning-effort <effort>', 'Reasoning effort (low, medium, high, xhigh, max)')
-  .option('-r, --resume <sessionId>', 'Resume a specific Claude session (claude only)')
+  .option('-r, --resume <sessionId>', 'Resume a specific provider session (Claude or Codex)')
   .option('-c, --continue', 'Continue the most recent Claude session (claude only)')
   .option(
     '-o, --output-format <format>',

src/agent-cli-provider/adapters/claude.ts

@@ -1,4 +1,4 @@
-import { stringifyJson } from '../json';
+import { getString, isRecord, stringifyJson, tryParseJson } from '../json';
 import { contractError } from '../contract-errors';
 import {
   type BuildProviderCommandOptions,
@@ -71,6 +71,7 @@ function detectCliFeatures(helpText?: string | null): ClaudeCliFeatures {
     // fail closed before a provider process is spawned.
     supportsSettings: !unknown && /--settings/.test(help),
     supportsMcpConfig: !unknown && /--mcp-config/.test(help),
+    supportsResume: unknown ? true : /--resume/.test(help),
     unknown,
   };
 }
@@ -120,11 +121,17 @@ function addAutoApproveArgs(args: string[], options: BuildProviderCommandOptions
 }
 
 function addSessionArgs(args: string[], options: BuildProviderCommandOptions): void {
-  if (options.resumeSessionId) {
+  const features = optionFeatures(options);
+  if ((options.resumeSessionId || options.continueSession) && features.supportsResume === false) {
+    throw new Error(
+      'Claude CLI cannot safely run continuation context because this installation lacks --resume.'
+    );
+  }
+  if (options.resumeSessionId && features.supportsResume !== false) {
     args.push('--resume', options.resumeSessionId);
     return;
   }
-  if (options.continueSession) {
+  if (options.continueSession && features.supportsResume !== false) {
     args.push('--continue');
   }
 }
@@ -163,6 +170,13 @@ function failClosedUnsupportedRunConfig(options: BuildProviderCommandOptions): v
   }
 }
 
+function extractSessionId(line: string): string | null {
+  const event = tryParseJson(line.trim());
+  if (!isRecord(event)) return null;
+  const sessionId = getString(event, 'session_id');
+  return sessionId?.trim() || null;
+}
+
 function collectWarnings(options: BuildProviderCommandOptions): WarningMetadata[] {
   const features = optionFeatures(options);
   const warnings: WarningMetadata[] = [];
@@ -273,6 +287,7 @@ export const claudeAdapter: ProviderAdapter = {
   defaultMinLevel: 'level1',
   detectCliFeatures,
   buildCommand,
+  extractSessionId,
   parseEvent: parseClaudeEvent,
   createParserState: () => createParserState('claude'),
   resolveModelSpec,

src/agent-cli-provider/adapters/codex.ts

@@ -1,3 +1,4 @@
+import { getString, isRecord, tryParseJson } from '../json';
 import { appendJsonSchemaPrompt, writeStrictOutputSchemaFile } from '../schema';
 import {
   type BuildProviderCommandOptions,
@@ -18,7 +19,6 @@ import {
   createParserState,
   optionFeatures,
   resolveModelSpecWithConfig,
-  unsupportedSessionControlWarnings,
   validateModelIdFromCatalog,
   warning,
 } from './common';
@@ -58,10 +58,18 @@ function detectCliFeatures(helpText?: string | null): CodexCliFeatures {
     supportsConfigOverride: supports(help, /--config\b/),
     supportsModel: supports(help, /\s-m\b/) || supports(help, /--model\b/),
     supportsSkipGitRepoCheck: supports(help, /--skip-git-repo-check\b/),
+    supportsResume: supports(help, /\bresume\b/),
     unknown,
   };
 }
 
+function extractSessionId(line: string): string | null {
+  const event = tryParseJson(line.trim());
+  if (!isRecord(event) || getString(event, 'type') !== 'thread.started') return null;
+  const sessionId = getString(event, 'thread_id');
+  return sessionId?.trim() || null;
+}
+
 function addOutputArgs(args: string[], options: BuildProviderCommandOptions): void {
   const features = optionFeatures(options);
   if (
@@ -121,7 +129,25 @@ function applySchemaArgs(
 
 function collectWarnings(options: BuildProviderCommandOptions): WarningMetadata[] {
   const features = optionFeatures(options);
-  const warnings: WarningMetadata[] = unsupportedSessionControlWarnings('codex', options);
+  const warnings: WarningMetadata[] = [];
+  if (options.continueSession) {
+    warnings.push(
+      warning(
+        'codex',
+        'unsupported-session-control',
+        'Codex requires an explicit session ID; ignoring continueSession.'
+      )
+    );
+  }
+  if (options.resumeSessionId && features.supportsResume === false) {
+    warnings.push(
+      warning(
+        'codex',
+        'codex-session-resume-unsupported',
+        'Codex CLI does not support exec resume; starting a fresh session.'
+      )
+    );
+  }
   if (options.autoApprove && features.supportsAutoApprove === false) {
     warnings.push(
       warning(
@@ -153,16 +179,33 @@ function collectWarnings(options: BuildProviderCommandOptions): WarningMetadata[
 }
 
 function buildCommand(context: string, options: BuildProviderCommandOptions = {}): CommandSpec {
+  if (options.resumeSessionId && optionFeatures(options).supportsResume === false) {
+    throw new Error(
+      'Codex CLI cannot safely run continuation context because this installation lacks exec resume.'
+    );
+  }
   const args: string[] = ['exec'];
   const cleanup: string[] = [];
+  const resumeSessionId =
+    options.resumeSessionId && optionFeatures(options).supportsResume !== false
+      ? options.resumeSessionId
+      : null;
+  if (resumeSessionId) {
+    args.push('resume');
+  }
 
   addOutputArgs(args, options);
   addModelArgs(args, options);
-  addCwdArgs(args, options);
+  if (!resumeSessionId) {
+    addCwdArgs(args, options);
+  }
   addAutoApproveArgs(args, options);
   addSkipGitArgs(args, options);
   const finalContext = applySchemaArgs(args, cleanup, context, options);
 
+  if (resumeSessionId) {
+    args.push(resumeSessionId);
+  }
   args.push(finalContext);
 
   return commandSpec({
@@ -216,6 +259,7 @@ export const codexAdapter: ProviderAdapter = {
   defaultMinLevel: 'level1',
   detectCliFeatures,
   buildCommand,
+  extractSessionId,
   parseEvent: parseCodexEvent,
   createParserState: () => createParserState('codex'),
   resolveModelSpec,

src/agent-cli-provider/adapters/common.ts

@@ -64,7 +64,7 @@ export function unsupportedSessionControlWarnings(
     warning(
       provider,
       'unsupported-session-control',
-      'resume/continue is only supported for Claude CLI; ignoring.'
+      `Provider ${provider} does not support resume/continue session control; ignoring.`
     ),
   ];
 }

src/agent-cli-provider/adapters/index.ts

@@ -79,6 +79,16 @@ export function parseProviderChunk(
   return events;
 }
 
+export function extractProviderSessionId(
+  providerName: KnownProviderName | string,
+  line: string
+): string | null {
+  const adapter = getProviderAdapter(providerName || 'claude');
+  const content = stripTimestampPrefix(line);
+  if (!content || !adapter.extractSessionId) return null;
+  return adapter.extractSessionId(content);
+}
+
 export function resolveModelSpec(
   providerName: KnownProviderName | string,
   level: ModelLevel,

src/agent-cli-provider/contract-options.ts

@@ -43,6 +43,7 @@ const CLI_FEATURE_FIELDS = [
   'supportsNoAskUser',
   'supportsAddDir',
   'supportsMcpConfig',
+  'supportsResume',
   'supportsBundledRunner',
   'supportsAcpStdio',
   'supportsPromptImages',

src/agent-cli-provider/index.ts

@@ -3,6 +3,7 @@ export {
   classifyProviderError,
   detectProviderFatalError,
   detectProviderStreamingModeError,
+  extractProviderSessionId,
   getProviderAdapter,
   listProviderAdapters,
   parseProviderChunk,

src/agent-cli-provider/provider-registry.ts

@@ -19,6 +19,7 @@ export interface ProviderCapabilities {
   readonly streamJson: ProviderCapabilityState;
   readonly thinkingMode: ProviderCapabilityState;
   readonly reasoningEffort: ProviderCapabilityState;
+  readonly sessionResume: ProviderCapabilityState;
 }
 
 interface FixedProviderCommandSpec {
@@ -93,13 +94,22 @@ export interface ProviderRegistryEntry {
 }
 
 const STANDARD_CAPABILITIES: Readonly<
-  Pick<ProviderCapabilities, 'dockerIsolation' | 'worktreeIsolation' | 'mcpServers' | 'streamJson' | 'thinkingMode'>
+  Pick<
+    ProviderCapabilities,
+    | 'dockerIsolation'
+    | 'worktreeIsolation'
+    | 'mcpServers'
+    | 'streamJson'
+    | 'thinkingMode'
+    | 'sessionResume'
+  >
 > = {
   dockerIsolation: true,
   worktreeIsolation: true,
   mcpServers: true,
   streamJson: true,
   thinkingMode: true,
+  sessionResume: false,
 };
 
 const CLAUDE_DOCKER_ENV_PASSTHROUGH = [
@@ -161,6 +171,7 @@ export const providerRegistry = [
       ...STANDARD_CAPABILITIES,
       jsonSchema: true,
       reasoningEffort: true,
+      sessionResume: true,
     },
     docs: {
       label: 'Claude',
@@ -197,6 +208,7 @@ export const providerRegistry = [
       ...STANDARD_CAPABILITIES,
       jsonSchema: true,
       reasoningEffort: true,
+      sessionResume: true,
     },
     docs: {
       label: 'Codex',