ai-foreman 1.7.12 → 1.7.14

package/README.md

@@ -70,6 +70,7 @@ ai-foreman doctor ./my-project
 ai-foreman tickets init --project ./my-project --app-name "My App"
 ai-foreman tickets populate --project ./my-project --agent codex --model gpt-5.5 --effort xhigh
 ai-foreman start ./my-project --agent codex --model gpt-5.5 --effort xhigh --steps 5
+ai-foreman state export ./my-project --output rafi-state.rafi.gz
 ```
 
 What each part does:
@@ -89,6 +90,20 @@ What each part does:
 - ticket files
 - folders or globs containing planning notes
 
+## Move Local State Between Machines
+
+Use `ai-foreman state export` for a sequential handoff from one checkout to another:
+
+```bash
+ai-foreman state export ./my-project --output rafi-state.rafi.gz
+ai-foreman state inspect rafi-state.rafi.gz
+ai-foreman state import ./matching-checkout rafi-state.rafi.gz
+```
+
+The bundle includes the local tracker database, delivery state, workflow/recovery databases, compiled role bundles, source snapshots, interview recovery records, and diagnostic run/recovery files. It does not include source code, provider sessions, or live worktrees. Export/import refuse dirty Git checkouts, active workflow leases, incompatible branch/HEAD state, and divergent transfer lineage. Import asks before replacing existing local state unless `--yes` is supplied, keeps a backup under `.rafi/state-transfer-backups/`, and rolls back failed imports.
+
+Provider sessions are historical after import. Resume with `rafi build:resume <project> --fresh-with-handoff` or the equivalent guided recovery path when exact session recovery is unavailable.
+
 ## Primary Options
 
 ### `ai-foreman start`
@@ -148,6 +163,23 @@ With the saved `current` strategy, Foreman works in the active branch while the
 
 The current terminal status includes the role/provider, activity, truthful context state, successful compaction count, and handoff generation. At the Builder threshold, Foreman settles the in-flight action, verifies native compaction plus a fresh provider usage sample, and resumes the frozen action. The configured maximum defaults to ten successful compactions per location-scoped provider session; the next crossing uses a validated fresh handoff instead of exceeding it. Disposable QA snapshots never reuse a prior QA conversation in a new `/tmp/rafi-qa-*` worktree; they transfer cumulative state through an accepted handoff.
 
+Failed QA reviews use the versioned `RAFI_QA_FAILURE_REPORT_START` / `RAFI_QA_FAILURE_REPORT_END` JSON contract. Foreman validates the report before Builder remediation, namespaces finding IDs by run, ticket, and review, and durably indexes the exact report, remediation response, and bounded fix summary by digest. A malformed failing report receives two correction-only turns in its original session, then a validated fresh successor performs one complete source-bound review followed by up to two correction-only turns. Any later operator-requested fresh successor performs one complete source-bound review followed by five usable correction-only turns.
+
+Owner-only recovery packets under `.foreman/qa-report-recovery/` bind the review to a full frozen source digest: commit, porcelain status, staged and unstaged bytes, and untracked content. Every fresh attempt captures and compares that complete state. Drift appends the new state and forces a complete review; correction-only reconstruction is never applied to changed source. Packet revisions and the authoritative WorkflowDb recovery head advance together. A successor must have a location-scoped identity, accept a handoff containing the complete resource inventory (purpose, byte count, digest, and recovery requirement), and acknowledge the copied packet before reporting. Paused recovery resumes with `rafi build:resume <project> --run <run-id> --ticket <ticket-id> --fresh-with-handoff`.
+
+### `ai-foreman manager`
+
+Manager is a project-wide, read-only diagnostic conversation over every retained build run. It starts with a verified live run when one exists, otherwise the most recently updated run; `--run <id>` changes only that initial focus. Each question refreshes the catalog, active state, deterministic aggregates, and relevant run details.
+
+Permanent sanitized run summaries keep timing, counts, provider/model configuration, usage coverage, failure category, and terminal Git facts useful after detailed spans expire. Detailed spans retain the configured 30-day policy. Missing historical facts are reported as partial rather than reconstructed or treated as zero.
+
+When the initial bounded packet omits evidence needed for a question, Manager can request catalog rows, aggregates, comparisons, or details through a host-validated read-only lookup. Each question is limited to two rounds, six operations per round, five detailed runs per operation, and fifty catalog rows per list operation. Questions, answers, and lookup envelopes are not stored as project evidence.
+
+```bash
+ai-foreman manager ./my-project
+ai-foreman manager ./my-project --run <run-id> --ask "Compare this run with the last five successful runs"
+```
+
 ### GitHub PR Failure Recovery
 
 When `--create-pr` cannot prepare GitHub, push a branch, or create a PR, Foreman records a structured failure and blocks the affected ticket cleanly. Blocked worktrees are retained automatically so you can repair the environment and retry without losing the ticket session.
@@ -482,6 +514,11 @@ ai-foreman start ./my-project --steps 5 --no-qa
 # Resume the latest session / a specific session
 ai-foreman start ./my-project --steps 5 --continue
 ai-foreman start ./my-project --steps 5 --resume <session-id>
+
+# Export, inspect, and import local Rafi state
+ai-foreman state export ./my-project --output rafi-state.rafi.gz
+ai-foreman state inspect rafi-state.rafi.gz
+ai-foreman state import ./matching-checkout rafi-state.rafi.gz
 ```
 
 ## Ticket Lifecycle Commands
@@ -543,16 +580,24 @@ STEP_STATUS: needs_input | question="Which storage backend?" choices="SQLite|Pos
 
 Provider-native `AskUserQuestion` prompts preserve their existing input/output behavior. Hosts may also observe a question only after the user successfully supplies a non-empty answer; cancelled, denied, malformed, and empty prompts do not emit answered-question telemetry. Rafi uses this boundary to recognize machine-shaped exhaustive-planning exchanges without treating generic questions as grill-me coverage.
 
-When QA is enabled, Foreman asks the builder to review its own work:
+When QA is enabled, Foreman creates an independent read-only review snapshot. A pass ends with:
 
 ```txt
 STEP_STATUS: qa_pass | summary="tests pass and acceptance criteria are met"
+```
+
+Failure uses a structured report immediately before the status marker (the short `issues` field is only a human synopsis and fallback input):
+
+```txt
+RAFI_QA_FAILURE_REPORT_START
+{"version":1,"summary":"missing empty-config coverage","checks_run":[{"check":"tests","command":"pnpm test","outcome":"failed","evidence":"empty-config case is absent"}],"findings":[{"id":"F1","requirement":"empty config is handled","locations":["src/config.ts","test/config.test.ts"],"problem":"no regression case exists","evidence":"test search found no empty-config case","expected":"the suite covers empty config","fix_direction":"add the missing case and repair behavior if needed","verification":["pnpm test"]}],"observations":[]}
+RAFI_QA_FAILURE_REPORT_END
 STEP_STATUS: qa_fail | issues="missing test for empty config"
 ```
 
 If QA fails:
 
-- Foreman sends a fix instruction.
+- Foreman sends the Builder the complete validated report, ticket requirements, current source digest, and prior report/remediation history.
 - Foreman reruns QA.
 - QA turns do not count against `--steps`.
 

package/dist/activity.d.ts

@@ -63,7 +63,11 @@ export declare class ActivityReporter {
 export declare function currentActivity(): ActivityReporter | undefined;
 export declare function withActivityContext<T>(command: string, operation: () => Promise<T>, options?: ActivityReporterOptions): Promise<T>;
 export declare function withActivityPhase<T>(label: string, operation: () => Promise<T>): Promise<T>;
-export declare function pauseActivityForInput<T>(operation: () => Promise<T>): Promise<T>;
+export interface ActivityInputPauseMetadata {
+    label?: string;
+    context?: Record<string, unknown>;
+}
+export declare function pauseActivityForInput<T>(operation: () => Promise<T>, _metadata?: ActivityInputPauseMetadata): Promise<T>;
 export declare function reportBuilderEvent(event: BuilderEvent): void;
 /** Async event queue that also feeds the active CLI reporter without consuming the stream. */
 export declare class BuilderEventQueue extends AsyncQueue<BuilderEvent> {

package/dist/activity.js

@@ -225,7 +225,7 @@ export async function withActivityPhase(label, operation) {
         end?.();
     }
 }
-export async function pauseActivityForInput(operation) {
+export async function pauseActivityForInput(operation, _metadata = {}) {
     const resume = currentActivity()?.pause();
     try {
         return await operation();

package/dist/adapters/claude.d.ts

@@ -50,6 +50,9 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private readonly pumpDone;
     private _sessionId?;
     private _sessionRef?;
+    private readonly sessionIdentityReady;
+    private resolveSessionIdentity;
+    private rejectSessionIdentity;
     private readonly stderrChunks;
     private turnSignals;
     private structuredError?;
@@ -62,6 +65,10 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private nativeCompactions;
     private nativeCompactionSequence;
     private cumulativeUsage;
+    private priorTurnUsage;
+    private activeProviderTurnId?;
+    private activeProviderTurnSpanId?;
+    private readonly toolSpans;
     private pending?;
     private terminalResult?;
     private streamEnded;
@@ -74,11 +81,15 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     sendTurn(text: string): Promise<TurnResult>;
     private sendTurnInternal;
     private captureStderr;
+    private observationContext;
+    private observeToolResults;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;
+    prepareSession(timeoutMs?: number): Promise<ProviderSessionRefV1>;
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
+    private compactInternal;
     prepareAutoCompaction(thresholdPercent?: number | undefined): Promise<NativeAutoCompactionPolicy | void>;
     autoCompactionPolicy(): NativeAutoCompactionPolicy | undefined;
     drainNativeCompactions(): NativeCompaction[];
@@ -88,6 +99,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
+    private failSessionIdentity;
     private observeSession;
     private settlePending;
     private streamFailureResult;

package/dist/adapters/claude.js

@@ -1,3 +1,5 @@
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export async function requireClaudeSDK() {
     try {
@@ -21,25 +23,42 @@ import { SessionUnavailableError, sessionUnavailableResult } from "./sessionFail
  * `canUseTool` is omitted here — it's a closure that the constructor adds.
  */
 export function buildClaudeQueryOptions(opts) {
+    const qaReadOnly = opts.sessionRole === "qa" || opts.sandboxMode === "read-only";
     const base = {
         cwd: opts.cwd,
         pathToClaudeCodeExecutable: opts.runtimeExecutable,
-        env: { ...process.env },
+        env: qaReadOnly ? qaEnvironment(process.env, opts.cwd) : { ...process.env },
         model: opts.model,
         resume: opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId,
-        permissionMode: "acceptEdits",
+        permissionMode: qaReadOnly ? "default" : "acceptEdits",
         effort: opts.effort,
         extraArgs: opts.fast ? { fast: null } : undefined,
-        settingSources: ["user", "project", "local"],
+        settingSources: qaReadOnly ? [] : ["user", "project", "local"],
+        ...(qaReadOnly ? { disallowedTools: ["Write", "Edit", "NotebookEdit"] } : {}),
+        ...(qaReadOnly ? { sandbox: {
+                enabled: true,
+                failIfUnavailable: true,
+                autoAllowBashIfSandboxed: true,
+                allowUnsandboxedCommands: false,
+                filesystem: { allowWrite: [join(dirname(opts.cwd), "scratch")], denyWrite: [opts.cwd, ...(opts.configRoot ? [opts.configRoot] : [])] },
+            } } : {}),
     };
-    if (opts.systemPromptAppend) {
-        base.systemPrompt = { type: "preset", preset: "claude_code", append: opts.systemPromptAppend };
+    const exactSkills = opts.preloadedSkillContent?.length
+        ? ["# Preloaded Skills", "Use the following skills for this run.", ...opts.preloadedSkillContent.map((skill) => skill.content)].join("\n\n")
+        : undefined;
+    const systemAppend = [opts.systemPromptAppend, exactSkills].filter((part) => Boolean(part)).join("\n\n");
+    if (systemAppend) {
+        base.systemPrompt = { type: "preset", preset: "claude_code", append: systemAppend };
     }
     if (opts.skills !== undefined) {
         base.skills = opts.skills;
     }
     return base;
 }
+function qaEnvironment(source, cwd) {
+    const allowed = ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "TMPDIR", "LANG", "LC_ALL", "TERM", "NO_COLOR", "FORCE_COLOR", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY", "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS"];
+    return { ...Object.fromEntries(allowed.flatMap((key) => source[key] === undefined ? [] : [[key, source[key]]])), TMPDIR: join(dirname(cwd), "scratch") };
+}
 export async function probeClaudeSession(ref, input) {
     const now = input.now ?? new Date();
     const local = validateProviderSessionScope(ref, {
@@ -147,6 +166,9 @@ export class ClaudeAdapter {
     pumpDone;
     _sessionId;
     _sessionRef;
+    sessionIdentityReady;
+    resolveSessionIdentity;
+    rejectSessionIdentity;
     stderrChunks = [];
     turnSignals = [];
     structuredError;
@@ -159,6 +181,10 @@ export class ClaudeAdapter {
     nativeCompactions = [];
     nativeCompactionSequence = 0;
     cumulativeUsage = { observedAt: new Date(0).toISOString(), source: "provider" };
+    priorTurnUsage = {};
+    activeProviderTurnId;
+    activeProviderTurnSpanId;
+    toolSpans = new Map();
     pending;
     terminalResult;
     streamEnded = false;
@@ -205,11 +231,28 @@ export class ClaudeAdapter {
         this.opts = opts;
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
         this._sessionRef = opts.resumeSessionRef;
+        this.sessionIdentityReady = new Promise((resolve, reject) => {
+            this.resolveSessionIdentity = resolve;
+            this.rejectSessionIdentity = reject;
+        });
+        void this.sessionIdentityReady.catch(() => { });
         this.query = query({
             prompt: this.inbox,
             options: {
                 ...buildClaudeQueryOptions(opts),
                 abortController: this.abort,
+                hooks: { SessionStart: [{ hooks: [async (input) => {
+                                    if (input.hook_event_name !== "SessionStart" || input.agent_id)
+                                        return {};
+                                    try {
+                                        this.observeSession(input.session_id, input.cwd);
+                                    }
+                                    catch (error) {
+                                        this.failSessionIdentity(error instanceof Error ? error : new Error(String(error)));
+                                        throw error;
+                                    }
+                                    return {};
+                                }] }] },
                 stderr: (data) => this.captureStderr(data),
                 canUseTool: async (toolName, input, requestOptions = {}) => {
                     const decision = await opts.permission({
@@ -246,6 +289,7 @@ export class ClaudeAdapter {
                 const message = normalizeRuntimeErrorText("claude", rawMessage, null, "builder stream");
                 this.eventQueue.push({ kind: "error", message });
                 const result = this.streamFailureResult(message, isMissingClaudeSession(rawMessage));
+                this.rejectSessionIdentity(new Error(message));
                 this.terminalResult = result;
                 this.settlePending(result);
             }
@@ -260,13 +304,14 @@ export class ClaudeAdapter {
             }
             if (!this.closed && !this.terminalResult)
                 this.terminalResult = this.streamFailureResult("Claude stream ended without a result", Boolean(this.opts.resumeSessionRef ?? this.opts.resumeSessionId));
+            if (!this._sessionRef)
+                this.rejectSessionIdentity(new Error("Claude stream ended before exposing a scoped session identity"));
             this.eventQueue.close();
         }
     }
     handle(msg) {
         if ("session_id" in msg && typeof msg.session_id === "string") {
-            this._sessionId = msg.session_id;
-            this.observeSession(msg.session_id);
+            this.observeSession(msg.session_id, "cwd" in msg && typeof msg.cwd === "string" ? msg.cwd : undefined);
         }
         if (msg.type === "assistant") {
             if (msg.error) {
@@ -274,15 +319,30 @@ export class ClaudeAdapter {
                 this.turnSignals.push(`assistant error: ${msg.error}`);
             }
             for (const block of msg.message.content) {
+                this.eventQueue.push({ kind: "provider-item", provider: "claude", lifecycle: "completed", itemType: String(block.type ?? "unknown"), payload: structuredClone(block), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
                 if (block.type === "text" && block.text) {
-                    this.eventQueue.push({ kind: "text", text: block.text });
+                    this.eventQueue.push({ kind: "text", text: block.text, byteCount: Buffer.byteLength(block.text), digest: createHash("sha256").update(block.text).digest("hex"), eventId: randomUUID(), observedAt: new Date().toISOString() });
+                    this.opts.observer?.signal(true);
                 }
                 else if (block.type === "tool_use") {
+                    const callId = block.id;
                     this.eventQueue.push({
                         kind: "tool",
                         name: block.name,
                         input: block.input,
+                        inputCompleteness: "complete",
+                        lifecycle: "started",
+                        callId,
+                        completionKnown: false,
+                        providerTurnId: this.activeProviderTurnId,
+                        eventId: randomUUID(),
+                        observedAt: new Date().toISOString(),
                     });
+                    if (this.opts.observer) {
+                        const spanId = this.opts.observer.store.startSpan(this.observationContext(), { kind: "tool", name: block.name, providerTurnId: this.activeProviderTurnId, attributes: { callId, input: block.input } });
+                        this.toolSpans.set(callId, spanId);
+                        this.opts.observer.signal(true);
+                    }
                 }
             }
         }
@@ -309,10 +369,24 @@ export class ClaudeAdapter {
             this.structuredError = msg.error;
             this.apiErrorStatus = msg.error_status;
             this.turnSignals.push(`API retry ${msg.attempt}/${msg.max_retries}: ${msg.error}${msg.error_status === null ? "" : ` (HTTP ${msg.error_status})`}`);
-            this.eventQueue.push(claudeApiRetryEvent(msg));
+            const retryEvent = { ...claudeApiRetryEvent(msg), retryId: randomUUID(), providerTurnId: this.activeProviderTurnId, observedAt: new Date().toISOString() };
+            this.eventQueue.push(retryEvent);
+            if (this.opts.observer) {
+                const attributes = { provider: "claude", attempt: msg.attempt, maximum: msg.max_retries, reportedDelayMs: msg.retry_delay_ms, reasonDigest: createHash("sha256").update(msg.error).digest("hex") };
+                const retrySpanId = this.opts.observer.store.startSpan(this.observationContext(), { spanId: retryEvent.retryId, kind: "retry", name: "Claude provider retry", providerTurnId: this.activeProviderTurnId, attributes });
+                this.opts.observer.store.recordEvent(this.observationContext(), "retry", { eventId: retryEvent.retryId, spanId: retrySpanId, severity: "warning", attributes });
+                this.opts.observer.store.finishSpan(retrySpanId, { outcome: "reported" });
+            }
         }
         else if (msg.type === "tool_progress") {
             this.eventQueue.push({ kind: "activity", provider: "claude", state: "running tool", detail: `${msg.tool_name} (${Math.floor(msg.elapsed_time_seconds)}s)`, transient: true });
+            const progress = msg;
+            const callId = typeof progress.tool_use_id === "string" ? progress.tool_use_id : typeof progress.toolUseID === "string" ? progress.toolUseID : undefined;
+            this.eventQueue.push({ kind: "tool", name: msg.tool_name, input: {}, lifecycle: "progress", callId, durationMs: Math.max(0, msg.elapsed_time_seconds * 1000), completionKnown: false, eventId: randomUUID(), observedAt: new Date().toISOString() });
+            this.opts.observer?.signal(false);
+        }
+        else if (msg.type === "user") {
+            this.observeToolResults(msg);
         }
         else if (msg.type === "system") {
             const system = msg;
@@ -364,13 +438,20 @@ export class ClaudeAdapter {
                 costUsd: msg.total_cost_usd,
                 costAuthoritative: Number.isFinite(msg.total_cost_usd),
                 failure,
+                turnId: this.pending?.turnId ?? this.activeProviderTurnId,
+                hostInstruction: this.pending?.instruction,
+                providerInstruction: this.pending?.instruction,
+                rawResponse: text,
+                cleanedResponse: failure ? formatClaudeFailure(failure) : text,
+                providerMetadata: { provider: "claude", sessionId: this._sessionId, sessionRef: this._sessionRef },
             };
             const rawResult = msg;
             const mergedUsage = mergeClaudeProviderSessionUsage(this.cumulativeUsage, rawResult);
             result.inputTokens = mergedUsage.inputTokens;
             result.outputTokens = mergedUsage.outputTokens;
+            result.usage = { scope: "session-cumulative", inputTokens: mergedUsage.sample.inputTokens, outputTokens: mergedUsage.sample.outputTokens, totalTokens: mergedUsage.sample.totalTokens, costUsd: mergedUsage.sample.authoritativeCostUsd };
             this.cumulativeUsage = mergedUsage.sample;
-            this.eventQueue.push({ kind: "turn-complete", result });
+            this.eventQueue.push({ kind: "turn-complete", result, turnId: result.turnId });
             this.settlePending(result, false);
             this.turnSignals = [];
             this.structuredError = undefined;
@@ -378,8 +459,43 @@ export class ClaudeAdapter {
             this.stderrChunks.length = 0;
         }
     }
-    sendTurn(text) {
-        return withActivityPhase(`Claude ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(text));
+    async sendTurn(text) {
+        const turnId = randomUUID();
+        this.activeProviderTurnId = turnId;
+        const observer = this.opts.observer;
+        if (!observer) {
+            try {
+                return await withActivityPhase(`Claude ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(text));
+            }
+            finally {
+                this.activeProviderTurnId = undefined;
+            }
+        }
+        const context = this.observationContext();
+        const spanId = observer.store.startSpan(context, { spanId: turnId, kind: "provider_turn", name: `Claude ${activityPhase(this.opts.runtimePhase)}`, providerTurnId: turnId, attributes: { provider: "claude" } });
+        this.activeProviderTurnSpanId = spanId;
+        observer.store.updateCurrentState({ runId: observer.runId, role: context.role ?? "host", stream: context.stream ?? "claude", executionId: observer.executionId, ticketId: context.ticketId, deliveryUnitId: context.deliveryUnitId, providerSessionId: context.providerSessionId, phase: "provider turn", activeSpanId: spanId, activeSpanKind: "provider_turn", lastSemanticProgressAt: new Date().toISOString() });
+        try {
+            const result = await withActivityPhase(`Claude ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(text));
+            const deltaInput = nonNegativeDelta(result.usage?.inputTokens, this.priorTurnUsage.inputTokens);
+            const deltaOutput = nonNegativeDelta(result.usage?.outputTokens, this.priorTurnUsage.outputTokens);
+            const deltaCost = nonNegativeDelta(result.usage?.costUsd, this.priorTurnUsage.costUsd);
+            this.priorTurnUsage = { inputTokens: result.usage?.inputTokens, outputTokens: result.usage?.outputTokens, costUsd: result.usage?.costUsd };
+            observer.store.finishSpan(spanId, { outcome: result.isError ? "failed" : "completed", attributes: { cumulativeUsage: result.usage, turnDelta: { inputTokens: deltaInput, outputTokens: deltaOutput, costUsd: deltaCost } } });
+            return result;
+        }
+        catch (error) {
+            observer.store.finishSpan(spanId, { outcome: "failed", attributes: { error: String(error).slice(0, 500) } });
+            throw error;
+        }
+        finally {
+            for (const [callId, toolSpanId] of this.toolSpans) {
+                observer.store.finishSpan(toolSpanId, { outcome: "unknown", completionKnown: false, attributes: { callId } });
+                this.toolSpans.delete(callId);
+            }
+            this.activeProviderTurnId = undefined;
+            this.activeProviderTurnSpanId = undefined;
+        }
     }
     sendTurnInternal(text) {
         if (this.closed)
@@ -394,7 +510,7 @@ export class ClaudeAdapter {
             this.turnSignals = [];
             this.structuredError = undefined;
             this.apiErrorStatus = undefined;
-            this.pending = { resolve, reject };
+            this.pending = { resolve, reject, instruction: text, turnId: this.activeProviderTurnId ?? randomUUID() };
             this.inbox.push({
                 type: "user",
                 message: { role: "user", content: text },
@@ -407,10 +523,73 @@ export class ClaudeAdapter {
         while (this.stderrChunks.join("").length > 8 * 1024)
             this.stderrChunks.shift();
     }
+    observationContext() {
+        const observer = this.opts.observer;
+        const inherited = observer.context();
+        return { ...inherited, runId: observer.runId, executionId: observer.executionId, role: this.opts.sessionRole ?? inherited.role ?? "builder",
+            stream: this.opts.sessionStream ?? inherited.stream ?? this.opts.sessionRole ?? "builder", providerSessionId: this._sessionId,
+            ticketId: this.opts.ticketId ?? inherited.ticketId, deliveryUnitId: this.opts.deliveryUnitId ?? inherited.deliveryUnitId,
+            parentSpanId: this.activeProviderTurnSpanId ?? inherited.parentSpanId, providerTurnId: this.activeProviderTurnId ?? inherited.providerTurnId };
+    }
+    observeToolResults(message) {
+        const body = message.message;
+        if (!Array.isArray(body?.content))
+            return;
+        for (const block of body.content) {
+            if (block.type !== "tool_result")
+                continue;
+            this.eventQueue.push({ kind: "provider-item", provider: "claude", lifecycle: "completed", itemType: "tool_result", payload: structuredClone(block), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
+            const callId = typeof block.tool_use_id === "string" ? block.tool_use_id : undefined;
+            if (!callId)
+                continue;
+            const spanId = this.toolSpans.get(callId);
+            const text = typeof block.content === "string" ? block.content : JSON.stringify(block.content ?? "");
+            const sanitized = text.replace(/\b(?:token|password|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[REDACTED]");
+            const failed = block.is_error === true;
+            const outputDigest = createHash("sha256").update(text).digest("hex");
+            this.eventQueue.push({ kind: "tool", name: "tool_result", input: {}, inputCompleteness: "unavailable", lifecycle: "completed", callId, status: failed ? "failed" : "completed", outputSummary: sanitized.slice(0, 1000), outputDigest, outputCompleteness: block.is_truncated === true ? "truncated" : "complete", rawOutputBytes: Buffer.byteLength(text), completionKnown: true, providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
+            if (spanId && this.opts.observer) {
+                this.opts.observer.store.finishSpan(spanId, { outcome: failed ? "failed" : "completed", completionKnown: true, attributes: { callId, outputSummary: sanitized.slice(0, 1000), outputDigest } });
+                this.toolSpans.delete(callId);
+            }
+            this.opts.observer?.signal(true);
+        }
+    }
     sessionId() {
         return this._sessionId;
     }
     sessionRef() { return this._sessionRef; }
+    async prepareSession(timeoutMs = 30_000) {
+        if (this.closed || this.streamEnded || this.terminalResult)
+            throw new Error(this.terminalResult?.text ?? "Claude session is closed");
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new Error("Claude session initialization timeout must be positive");
+        let timer;
+        let aborted;
+        try {
+            const interrupted = new Promise((_resolve, reject) => {
+                aborted = () => reject(new Error(this.terminalResult?.text ?? "Claude session closed during initialization"));
+                this.abort.signal.addEventListener("abort", aborted, { once: true });
+                if (this.abort.signal.aborted)
+                    aborted();
+                timer = setTimeout(() => reject(new Error(`Claude did not expose a scoped session identity within ${timeoutMs}ms`)), timeoutMs);
+            });
+            const [, ref] = await Promise.race([Promise.all([this.query.initializationResult(), this.sessionIdentityReady]), interrupted]);
+            if (!ref.validatedAt)
+                throw new Error("Claude session identity was not provider-validated during initialization");
+            return ref;
+        }
+        catch (error) {
+            this.failSessionIdentity(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            if (aborted)
+                this.abort.signal.removeEventListener("abort", aborted);
+        }
+    }
     adoptSessionRef(ref) {
         if (ref.provider !== "claude" || ref.sessionId !== this._sessionId)
             throw new Error("cannot adopt a session reference for a different Claude conversation");
@@ -430,6 +609,11 @@ export class ClaudeAdapter {
         });
     }
     async compact() {
+        return this.opts.observer
+            ? this.opts.observer.span("compaction", "Claude context compaction", () => this.compactInternal())
+            : this.compactInternal();
+    }
+    async compactInternal() {
         this.compactResult = undefined;
         this.manualCompactionInFlight = true;
         let result;
@@ -528,6 +712,8 @@ export class ClaudeAdapter {
         if (this.closed)
             return;
         this.closed = true;
+        this.rejectSessionIdentity(new Error("Claude session closed during initialization"));
+        this.abort.abort();
         this.inbox.close();
         try {
             await this.query.interrupt();
@@ -535,26 +721,65 @@ export class ClaudeAdapter {
         catch {
             // interrupt is best-effort — ignore if no turn is active
         }
-        this.abort.abort();
         await this.pumpDone.catch(() => { });
     }
-    observeSession(sessionId) {
-        if (this._sessionRef?.sessionId === sessionId)
+    failSessionIdentity(error) {
+        this.rejectSessionIdentity(error);
+        const result = sessionUnavailableResult(new SessionUnavailableError({
+            runtime: "claude", phase: this.pending ? "turn" : "preflight", dispatchState: this.pending ? "unknown" : "not-sent",
+            executable: this.opts.runtimeExecutable ?? "claude", cwd: this.opts.cwd, diagnostics: error.message,
+            availability: { version: 1, status: "unavailable", checkedAt: new Date().toISOString(), reason: "attach-failed", detail: error.message, ...(this._sessionRef ? { sessionRef: this._sessionRef } : {}) },
+        }));
+        this.terminalResult = result;
+        this.settlePending(result);
+        this.inbox.close();
+        this.abort.abort();
+    }
+    observeSession(sessionId, observedCwd) {
+        const expectedId = this._sessionRef?.sessionId ?? this._sessionId;
+        if (!sessionId.trim() || (expectedId && expectedId !== sessionId)) {
+            const error = new Error(`Claude initialized session ${sessionId || "without an ID"} instead of requested session ${expectedId ?? "a nonempty ID"}`);
+            this.failSessionIdentity(error);
+            throw error;
+        }
+        if (observedCwd !== undefined && canonicalSessionPath(observedCwd) !== canonicalSessionPath(this.opts.cwd)) {
+            const error = new Error(`Claude session cwd ${observedCwd} does not match ${this.opts.cwd}`);
+            this.failSessionIdentity(error);
+            throw error;
+        }
+        this._sessionId = sessionId;
+        if (this._sessionRef?.validatedAt) {
+            this.resolveSessionIdentity(this._sessionRef);
             return;
-        this._sessionRef = createProviderSessionRef({
-            provider: "claude", sessionId, cwd: this.opts.cwd, configRoot: this.opts.configRoot ?? this.opts.cwd,
-            role: this.opts.sessionRole, stream: this.opts.sessionStream, generation: this.opts.sessionGeneration,
-            workspaceIdentity: this.opts.workspaceIdentity, ticketId: this.opts.ticketId, deliveryUnitId: this.opts.deliveryUnitId,
-            source: "observed",
-        });
+        }
+        const now = new Date().toISOString();
+        const validatedAt = observedCwd !== undefined || this.opts.sessionRole !== "qa" ? now : undefined;
+        this._sessionRef = this._sessionRef
+            ? { ...this._sessionRef, source: "observed", ...(validatedAt ? { validatedAt } : {}) }
+            : createProviderSessionRef({
+                provider: "claude", sessionId, cwd: this.opts.cwd, configRoot: this.opts.configRoot ?? this.opts.cwd,
+                role: this.opts.sessionRole, stream: this.opts.sessionStream, generation: this.opts.sessionGeneration,
+                workspaceIdentity: this.opts.workspaceIdentity, ticketId: this.opts.ticketId, deliveryUnitId: this.opts.deliveryUnitId,
+                source: "observed", validatedAt,
+            });
+        if (this._sessionRef.validatedAt)
+            this.resolveSessionIdentity(this._sessionRef);
     }
     settlePending(result, emit = true) {
         const pending = this.pending;
         if (!pending)
             return;
         this.pending = undefined;
+        if (!result.turnId) {
+            result.turnId = pending.turnId;
+            result.hostInstruction = pending.instruction;
+            result.providerInstruction = pending.instruction;
+            result.rawResponse = result.text;
+            result.cleanedResponse = result.text;
+            result.providerMetadata = { provider: "claude", sessionId: this._sessionId, sessionRef: this._sessionRef };
+        }
         if (emit)
-            this.eventQueue.push({ kind: "turn-complete", result });
+            this.eventQueue.push({ kind: "turn-complete", result, turnId: result.turnId });
         pending.resolve(result);
     }
     streamFailureResult(message, sessionUnavailable) {
@@ -575,6 +800,11 @@ export class ClaudeAdapter {
     }
 }
 function finiteNumber(value) { const parsed = Number(value); return value !== null && value !== undefined && value !== "" && Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined; }
+function nonNegativeDelta(current, prior) {
+    if (current === undefined)
+        return undefined;
+    return prior === undefined ? current : Math.max(0, current - prior);
+}
 function validThreshold(value) {
     if (!Number.isInteger(value) || value < 1 || value > 99)
         throw new Error("automatic compaction threshold must be an integer from 1 to 99");
@@ -595,6 +825,8 @@ function activityPhase(phase) {
         return "reviewing with QA";
     if (phase === "uninstaller")
         return "planning uninstall";
+    if (phase === "manager")
+        return "analyzing diagnostics";
     return "building";
 }
 function formatClaudeFailure(failure) {

package/dist/adapters/codex.d.ts

@@ -35,6 +35,9 @@ export declare class CodexAdapter implements BuilderAdapter {
     private nativeCompactionSequence;
     private manualCompactionInFlight;
     private observedToolCalls;
+    private activeProviderTurnId?;
+    private activeProviderTurnSpanId?;
+    private readonly toolSpans;
     constructor(opts: BuilderAdapterOptions);
     buildInstruction(instruction: string): string;
     buildAppServerArgs(): string[];
@@ -43,7 +46,9 @@ export declare class CodexAdapter implements BuilderAdapter {
     sendTurn(instruction: string): Promise<TurnResult>;
     private sendTurnInternal;
     compact(): Promise<CompactResult>;
+    private compactInternal;
     prepareAutoCompaction(thresholdPercent?: number | undefined): Promise<NativeAutoCompactionPolicy | void>;
+    requiresAutoCompactionSetupTurn(): boolean;
     autoCompactionPolicy(): NativeAutoCompactionPolicy | undefined;
     drainNativeCompactions(): NativeCompaction[];
     restoreNativeCompactions(compactions: NativeCompaction[]): void;
@@ -53,6 +58,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;
+    prepareSession(): Promise<ProviderSessionRefV1>;
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<SessionAvailabilityV1>;
     events(): AsyncIterable<BuilderEvent>;
@@ -63,6 +69,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     private request;
     private write;
     private handle;
+    private observationContext;
     private waitFor;
     private disconnect;
     private restartForAutoCompaction;