ai-foreman 1.7.11 → 1.7.13

package/README.md

@@ -148,6 +148,21 @@ 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 and preserves reports by digest. A malformed failing report receives two correction-only turns, a compacted pair, then five turns in a validated fresh successor. Recovery packets are owner-only, locally Git-excluded, and stored under `.foreman/qa-report-recovery/`; the successor must acknowledge the copied packet and reviewed-state digests before reporting.
+
+### `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.

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

@@ -62,6 +62,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 +78,14 @@ 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;
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
+    private compactInternal;
     prepareAutoCompaction(thresholdPercent?: number | undefined): Promise<NativeAutoCompactionPolicy | void>;
     autoCompactionPolicy(): NativeAutoCompactionPolicy | undefined;
     drainNativeCompactions(): NativeCompaction[];

package/dist/adapters/claude.js

@@ -1,3 +1,4 @@
+import { createHash, randomUUID } from "node:crypto";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export async function requireClaudeSDK() {
     try {
@@ -159,6 +160,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;
@@ -275,14 +280,28 @@ export class ClaudeAdapter {
             }
             for (const block of msg.message.content) {
                 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 +328,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 +397,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 +418,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 +469,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,6 +482,37 @@ 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;
+            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;
     }
@@ -430,6 +536,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;
@@ -553,8 +664,16 @@ export class ClaudeAdapter {
         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 +694,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 +719,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,6 +46,7 @@ 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>;
     autoCompactionPolicy(): NativeAutoCompactionPolicy | undefined;
     drainNativeCompactions(): NativeCompaction[];
@@ -63,6 +67,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     private request;
     private write;
     private handle;
+    private observationContext;
     private waitFor;
     private disconnect;
     private restartForAutoCompaction;

package/dist/adapters/codex.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
@@ -51,6 +52,9 @@ export class CodexAdapter {
     nativeCompactionSequence = 0;
     manualCompactionInFlight = false;
     observedToolCalls = 0;
+    activeProviderTurnId;
+    activeProviderTurnSpanId;
+    toolSpans = new Map();
     constructor(opts) {
         this.opts = opts;
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
@@ -82,13 +86,45 @@ export class CodexAdapter {
         return args;
     }
     async sendTurn(instruction) {
-        return withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction));
+        const turnId = randomUUID();
+        this.activeProviderTurnId = turnId;
+        const observer = this.opts.observer;
+        if (!observer) {
+            try {
+                return await withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction));
+            }
+            finally {
+                this.activeProviderTurnId = undefined;
+            }
+        }
+        const context = this.observationContext();
+        const spanId = observer.store.startSpan(context, { spanId: turnId, kind: "provider_turn", name: `Codex ${activityPhase(this.opts.runtimePhase)}`, providerTurnId: turnId, attributes: { provider: "codex" } });
+        this.activeProviderTurnSpanId = spanId;
+        observer.store.updateCurrentState({ runId: observer.runId, role: context.role ?? "host", stream: context.stream ?? "codex", 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(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction));
+            observer.store.finishSpan(spanId, { outcome: result.isError ? "failed" : "completed", attributes: { usage: result.usage } });
+            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 });
+                this.toolSpans.delete(callId);
+            }
+            this.activeProviderTurnId = undefined;
+            this.activeProviderTurnSpanId = undefined;
+        }
     }
     async sendTurnInternal(instruction) {
         if (this.closed)
             throw new Error("builder is closed");
         this.eventQueue.push({ kind: "activity", state: "starting Codex turn", provider: "codex", model: this.opts.model });
         let turnStartDispatched = false;
+        const providerInstruction = this.buildInstruction(instruction);
         try {
             await this.ensureThread();
             this.activeText = [];
@@ -97,7 +133,7 @@ export class CodexAdapter {
             turnStartDispatched = true;
             await this.request("turn/start", {
                 threadId: this._sessionId,
-                input: [{ type: "text", text: this.buildInstruction(instruction), text_elements: [] }],
+                input: [{ type: "text", text: providerInstruction, text_elements: [] }],
                 cwd: this.opts.cwd,
                 model: this.opts.model ?? null,
                 effort: this.opts.effort ?? (this.opts.fast ? "low" : null),
@@ -110,16 +146,27 @@ export class CodexAdapter {
             const result = {
                 text: failed ? normalizeRuntimeErrorText("codex", String(error?.message ?? text), null, "app-server turn") : text,
                 isError: failed, numTurns: 1, costUsd: 0, costAuthoritative: false,
+                turnId: this.activeProviderTurnId, hostInstruction: instruction, providerInstruction,
+                rawResponse: text, cleanedResponse: failed ? normalizeRuntimeErrorText("codex", String(error?.message ?? text), null, "app-server turn") : text,
+                providerMetadata: { provider: "codex", sessionId: this._sessionId, sessionRef: this._sessionRef },
                 ...(this.lastTurnTokens ?? {}),
             };
-            this.eventQueue.push({ kind: "turn-complete", result });
+            result.usage = { scope: "turn-delta", inputTokens: result.inputTokens, outputTokens: result.outputTokens,
+                ...(result.inputTokens !== undefined || result.outputTokens !== undefined ? { totalTokens: (result.inputTokens ?? 0) + (result.outputTokens ?? 0) } : {}) };
+            this.eventQueue.push({ kind: "turn-complete", result, turnId: result.turnId });
             return result;
         }
         catch (error) {
             if (error instanceof SessionUnavailableError) {
                 const result = sessionUnavailableResult(error);
                 this.eventQueue.push({ kind: "error", message: result.text });
-                this.eventQueue.push({ kind: "turn-complete", result });
+                result.turnId = this.activeProviderTurnId;
+                result.hostInstruction = instruction;
+                result.providerInstruction = providerInstruction;
+                result.rawResponse = result.text;
+                result.cleanedResponse = result.text;
+                result.providerMetadata = { provider: "codex", sessionId: this._sessionId, sessionRef: this._sessionRef };
+                this.eventQueue.push({ kind: "turn-complete", result, turnId: result.turnId });
                 return result;
             }
             const detail = [error instanceof Error ? error.message : String(error), this.stderr].filter(Boolean).join("\n");
@@ -134,11 +181,22 @@ export class CodexAdapter {
                 }))
                 : { text, isError: true, numTurns: 1, costUsd: 0, costAuthoritative: false };
             this.eventQueue.push({ kind: "error", message: text });
-            this.eventQueue.push({ kind: "turn-complete", result });
+            result.turnId = this.activeProviderTurnId;
+            result.hostInstruction = instruction;
+            result.providerInstruction = providerInstruction;
+            result.rawResponse = result.text;
+            result.cleanedResponse = result.text;
+            result.providerMetadata = { provider: "codex", sessionId: this._sessionId, sessionRef: this._sessionRef };
+            this.eventQueue.push({ kind: "turn-complete", result, turnId: result.turnId });
             return result;
         }
     }
     async compact() {
+        return this.opts.observer
+            ? this.opts.observer.span("compaction", "Codex context compaction", () => this.compactInternal())
+            : this.compactInternal();
+    }
+    async compactInternal() {
         try {
             await this.ensureThread();
             this.eventQueue.push({ kind: "session-transition", transition: "compacting" });
@@ -418,20 +476,43 @@ export class CodexAdapter {
         const params = message.params ?? {};
         if (message.method === "item/started") {
             const item = params.item;
-            if (isCodexToolItem(item))
+            if (isCodexToolItem(item)) {
                 this.observedToolCalls += 1;
+                const callId = codexItemId(item) ?? randomUUID();
+                const name = codexToolName(item);
+                this.eventQueue.push({ kind: "tool", name, input: exactToolInput(item), 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, providerTurnId: this.activeProviderTurnId, attributes: { callId, input: boundedToolInput(item) } });
+                    this.toolSpans.set(callId, spanId);
+                    this.opts.observer.signal(true);
+                }
+            }
             const activity = codexItemActivity(item);
             if (activity)
                 this.eventQueue.push({ kind: "activity", provider: "codex", ...activity });
         }
         else if (message.method === "item/completed") {
             const item = params.item;
+            if (isCodexToolItem(item)) {
+                const callId = codexItemId(item);
+                const spanId = callId ? this.toolSpans.get(callId) : undefined;
+                const status = typeof item?.status === "string" ? item.status : undefined;
+                const exitCode = finiteNumber(item?.exitCode ?? item?.exit_code);
+                const durationMs = finiteNumber(item?.durationMs ?? item?.duration_ms);
+                const output = codexOutputSummary(item);
+                this.eventQueue.push({ kind: "tool", name: codexToolName(item), input: exactToolInput(item), inputCompleteness: "complete", lifecycle: "completed", callId, status, durationMs, exitCode, outputSummary: output?.summary, outputDigest: output?.digest, outputCompleteness: output?.completeness ?? "unavailable", rawOutputBytes: output?.bytes, completionKnown: true, providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
+                if (spanId && this.opts.observer) {
+                    this.opts.observer.store.finishSpan(spanId, { outcome: status ?? (exitCode === undefined || exitCode === 0 ? "completed" : "failed"), completionKnown: true, attributes: { callId, providerDurationMs: durationMs, exitCode, outputSummary: output?.summary, outputDigest: output?.digest } });
+                    this.toolSpans.delete(callId);
+                }
+                this.opts.observer?.signal(true);
+            }
             if (item?.type === "agentMessage" && typeof item.text === "string") {
                 this.activeText.push(item.text);
-                this.eventQueue.push({ kind: "text", text: item.text });
+                this.eventQueue.push({ kind: "text", text: item.text, byteCount: Buffer.byteLength(item.text), digest: createHash("sha256").update(item.text).digest("hex"), eventId: randomUUID(), observedAt: new Date().toISOString() });
+                this.opts.observer?.signal(true);
             }
-            else if (item?.type === "commandExecution") {
-                this.eventQueue.push({ kind: "tool", name: "command_execution", input: { command: item.command } });
+            else if (item?.type === "commandExecution") { /* tool completion was emitted above */
             }
             else if (item?.type === "contextCompaction" && !this.manualCompactionInFlight) {
                 // Completion is the provider's authoritative confirmation. Token-usage
@@ -485,8 +566,18 @@ export class CodexAdapter {
         else if (message.method === "error") {
             const error = params.error;
             const reason = String(error?.message ?? params.message ?? "Codex app-server error");
-            if (params.willRetry === true)
-                this.eventQueue.push({ kind: "retry", provider: "codex", reason, managedBy: "provider" });
+            if (params.willRetry === true) {
+                const retryId = randomUUID();
+                this.eventQueue.push(this.opts.observer
+                    ? { kind: "retry", provider: "codex", reason, managedBy: "provider", retryId, providerTurnId: this.activeProviderTurnId, eventId: retryId, observedAt: new Date().toISOString() }
+                    : { kind: "retry", provider: "codex", reason, managedBy: "provider" });
+                if (this.opts.observer) {
+                    const retrySpanId = this.opts.observer.store.startSpan(this.observationContext(), { spanId: retryId, kind: "retry", name: "Codex provider retry", providerTurnId: this.activeProviderTurnId,
+                        attributes: { provider: "codex", reasonDigest: createHash("sha256").update(reason).digest("hex") } });
+                    this.opts.observer.store.recordEvent(this.observationContext(), "retry", { eventId: retryId, spanId: retrySpanId, severity: "warning", attributes: { provider: "codex", reasonDigest: createHash("sha256").update(reason).digest("hex") } });
+                    this.opts.observer.store.finishSpan(retrySpanId, { outcome: "reported" });
+                }
+            }
             else
                 this.eventQueue.push({ kind: "error", message: reason });
         }
@@ -496,6 +587,14 @@ export class CodexAdapter {
             waiter.predicate(params) ? waiter.resolve(params) : remaining.push(waiter);
         this.notificationWaiters.set(message.method, remaining);
     }
+    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 };
+    }
     waitFor(method, predicate, timeoutMs) {
         return new Promise((resolve, reject) => {
             let timeout;
@@ -571,6 +670,8 @@ function activityPhase(phase) {
         return "reviewing with QA";
     if (phase === "uninstaller")
         return "planning uninstall";
+    if (phase === "manager")
+        return "analyzing diagnostics";
     return "building";
 }
 function codexItemActivity(item, completed = false) {
@@ -596,6 +697,15 @@ function codexItemActivity(item, completed = false) {
 function isCodexToolItem(item) {
     return item?.type === "commandExecution" || item?.type === "mcpToolCall" || item?.type === "dynamicToolCall" || item?.type === "webSearch" || item?.type === "fileChange";
 }
+function codexItemId(item) { const value = item?.id ?? item?.itemId ?? item?.callId; return typeof value === "string" && value ? value : undefined; }
+function codexToolName(item) { return String(item?.tool ?? item?.name ?? item?.type ?? "tool"); }
+function exactToolInput(item) { if (!item)
+    return {}; return Object.fromEntries(Object.entries(item).filter(([key]) => ["command", "tool", "name", "type", "path", "query", "arguments", "input"].includes(key))); }
+function boundedToolInput(item) { if (!item)
+    return {}; return Object.fromEntries(Object.entries(exactToolInput(item)).map(([key, value]) => [key, typeof value === "string" ? value.slice(0, 1000) : value])); }
+function codexOutputSummary(item) { const value = item?.aggregatedOutput ?? item?.output ?? item?.stdout; if (typeof value !== "string" || !value)
+    return undefined; const sanitized = value.replace(/\b(?:token|password|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[REDACTED]"); const providerTruncated = item?.outputTruncated === true || item?.truncated === true; return { summary: sanitized.slice(0, 1000), digest: createHash("sha256").update(value).digest("hex"), completeness: providerTruncated ? "truncated" : "complete", bytes: Buffer.byteLength(value) }; }
+function finiteNumber(value) { const result = Number(value); return Number.isFinite(result) ? result : undefined; }
 function loadSkillMarkdown(cwd, skill) {
     const projectPath = join(cwd, ".agents", "skills", skill, "SKILL.md");
     if (existsSync(projectPath))

package/dist/adapters/recovering.d.ts

@@ -1,6 +1,7 @@
 import type { AgentRuntime } from "../runtimeAuth.js";
 import type { BuilderAdapter, BuilderEvent, CompactResult, ContextUsage, NativeAutoCompactionPolicy, NativeCompaction, ProviderSessionUsage, TurnResult } from "./types.js";
 import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
+import type { RunObserver } from "../observability.js";
 export type TurnRecoveryChoice = "retry" | "switch" | "cancel";
 export interface RecoveringAdapterOptions {
     initial: BuilderAdapter;
@@ -12,6 +13,7 @@ export interface RecoveringAdapterOptions {
     choose?: (result: TurnResult, runtime: AgentRuntime, otherRuntime: AgentRuntime) => Promise<TurnRecoveryChoice>;
     onRuntimeChange?: (runtime: AgentRuntime) => void;
     onSessionRef?: (ref: ProviderSessionRefV1) => void;
+    observer?: RunObserver;
 }
 /** Adds interactive recovery around structured runtime turn failures. */
 export declare class RecoveringAdapter implements BuilderAdapter {

package/dist/adapters/recovering.js

@@ -1,6 +1,7 @@
 import { isCancel, log, select } from "@clack/prompts";
 import { AsyncQueue } from "../util/asyncQueue.js";
 import { pauseActivityForInput, reportBuilderEvent } from "../activity.js";
+import { randomUUID } from "node:crypto";
 /** Adds interactive recovery around structured runtime turn failures. */
 export class RecoveringAdapter {
     opts;
@@ -39,7 +40,9 @@ export class RecoveringAdapter {
             const otherRuntime = this.runtime === "claude" ? "codex" : "claude";
             const choice = this.opts.choose
                 ? await this.opts.choose(result, this.runtime, otherRuntime)
-                : await pauseActivityForInput(() => promptTurnRecovery(result, this.opts.label, this.runtime, otherRuntime, this.opts.allowSwitch));
+                : await (this.opts.observer
+                    ? this.opts.observer.span("user_wait", "runtime recovery choice", () => pauseActivityForInput(() => promptTurnRecovery(result, this.opts.label, this.runtime, otherRuntime, this.opts.allowSwitch)))
+                    : pauseActivityForInput(() => promptTurnRecovery(result, this.opts.label, this.runtime, otherRuntime, this.opts.allowSwitch)));
             if (choice === "cancel")
                 return result;
             if (choice === "switch" && !this.opts.allowSwitch)
@@ -49,6 +52,13 @@ export class RecoveringAdapter {
                 : { kind: "activity", provider: otherRuntime, state: `switching to ${otherRuntime}`, detail: "starting a fresh provider session" };
             this.eventQueue.push(recoveryEvent);
             reportBuilderEvent(recoveryEvent);
+            if (choice === "retry" && this.opts.observer) {
+                const retryId = randomUUID();
+                const context = this.opts.observer.context();
+                const spanId = this.opts.observer.store.startSpan(context, { spanId: retryId, kind: "retry", name: "Rafi recovery retry", attributes: { provider: this.runtime, managedBy: "rafi" } });
+                this.opts.observer.store.recordEvent(context, "retry", { eventId: retryId, spanId, severity: "warning", attributes: { provider: this.runtime, managedBy: "rafi" } });
+                this.opts.observer.store.finishSpan(spanId, { outcome: "scheduled" });
+            }
             const nextRuntime = choice === "switch" ? otherRuntime : this.runtime;
             const resumeSessionId = choice === "retry" ? this.adapter.sessionId() : undefined;
             const resumeSessionRef = choice === "retry" ? this.adapter.sessionRef?.() : undefined;