ai-foreman 1.7.12 → 1.7.14

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" });
@@ -190,6 +248,8 @@ export class CodexAdapter {
         // setup turn, then restart the app server with the provider-native ceiling
         // before any Builder or QA work is sent.
         if (!this.usage?.maximum) {
+            if (this.opts.allowAutoCompactionSetupTurn === false)
+                return;
             const toolsBefore = this.observedToolCalls;
             const setup = await this.sendTurnInternal("Rafi internal initialization only. Do not call tools or modify files. Reply briefly that the context is ready.");
             if (setup.isError)
@@ -214,6 +274,9 @@ export class CodexAdapter {
         };
         return this.preparedAutoCompactionPolicy;
     }
+    requiresAutoCompactionSetupTurn() {
+        return this.opts.autoCompactThresholdPercent !== undefined && !this.autoCompactionPrepared && !this.usage?.maximum;
+    }
     autoCompactionPolicy() { return this.preparedAutoCompactionPolicy; }
     drainNativeCompactions() {
         const pending = this.nativeCompactions;
@@ -242,6 +305,14 @@ export class CodexAdapter {
     }
     sessionId() { return this._sessionId; }
     sessionRef() { return this._sessionRef; }
+    async prepareSession() {
+        await this.ensureThread();
+        if (!this._sessionRef)
+            throw new Error("Codex did not expose a scoped thread identity during session preparation");
+        if (!this._sessionRef.validatedAt)
+            this._sessionRef = { ...this._sessionRef, validatedAt: new Date().toISOString() };
+        return this._sessionRef;
+    }
     adoptSessionRef(ref) {
         if (ref.provider !== "codex" || ref.sessionId !== this._sessionId)
             throw new Error("cannot adopt a session reference for a different Codex thread");
@@ -337,20 +408,22 @@ export class CodexAdapter {
                 availability,
             });
         }
-        this._sessionId = returnedSessionId;
-        if (!this._sessionId)
+        if (!returnedSessionId?.trim())
             throw new Error(`${method} did not return a thread ID`);
         const providerCwd = typeof thread?.cwd === "string" ? canonicalSessionPath(thread.cwd) : undefined;
-        if (this._sessionRef && providerCwd && providerCwd !== canonicalSessionPath(this._sessionRef.cwd)) {
-            const availability = { version: 1, status: "unavailable", checkedAt: new Date().toISOString(), reason: "cwd-mismatch", observedCwd: providerCwd, detail: `Codex thread cwd ${providerCwd} does not match ${this._sessionRef.cwd}`, sessionRef: this._sessionRef };
+        const expectedCwd = canonicalSessionPath(this._sessionRef?.cwd ?? this.opts.cwd);
+        if ((providerCwd && providerCwd !== expectedCwd) || (!providerCwd && this.opts.sessionRole === "qa")) {
+            const availability = { version: 1, status: "unavailable", checkedAt: new Date().toISOString(), reason: "cwd-mismatch", observedCwd: providerCwd, detail: `Codex thread cwd ${providerCwd ?? "was not returned"} does not match ${expectedCwd}`, sessionRef: this._sessionRef };
             this.sessionAvailability = availability;
             throw new SessionUnavailableError({ runtime: "codex", phase: "attach", dispatchState: "not-sent", executable: this.opts.runtimeExecutable ?? "codex", cwd: this.opts.cwd, diagnostics: availability.detail, availability });
         }
+        this._sessionId = returnedSessionId;
         if (!this._sessionRef) {
             this._sessionRef = createProviderSessionRef({
                 provider: "codex", sessionId: this._sessionId, cwd: providerCwd ?? 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,
+                validatedAt: new Date().toISOString(),
             });
         }
         else {
@@ -418,20 +491,47 @@ export class CodexAdapter {
         const params = message.params ?? {};
         if (message.method === "item/started") {
             const item = params.item;
-            if (isCodexToolItem(item))
+            if (item)
+                this.eventQueue.push({ kind: "provider-item", provider: "codex", lifecycle: "started", itemType: String(item.type ?? "unknown"), payload: exactProviderItem(item), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
+            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 (item)
+                this.eventQueue.push({ kind: "provider-item", provider: "codex", lifecycle: "completed", itemType: String(item.type ?? "unknown"), payload: exactProviderItem(item), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
+            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 +585,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 +606,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;
@@ -544,6 +662,9 @@ export class CodexAdapter {
             child.kill("SIGTERM");
     }
     buildSkillsAppendix() {
+        if (this.opts.preloadedSkillContent?.length) {
+            return ["# Preloaded Skills", "Use the following skills for this run.", ...this.opts.preloadedSkillContent.map((skill) => skill.content)].join("\n\n");
+        }
         if (!this.opts.skills?.length)
             return undefined;
         const blocks = this.opts.skills.map((skill) => loadSkillMarkdown(this.opts.cwd, skill)).filter((block) => Boolean(block));
@@ -571,6 +692,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,9 +719,18 @@ 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 exactProviderItem(item) { return structuredClone(item); }
+function exactToolInput(item) { return item ? exactProviderItem(item) : {}; }
+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))
+    const projectPath = [join(cwd, ".codex", "skills", skill, "SKILL.md"), join(cwd, ".agents", "skills", skill, "SKILL.md")].find(existsSync);
+    if (projectPath)
         return `## ${skill}\n${readFileSync(projectPath, "utf8").trim()}`;
     try {
         const bundled = loadSkill(skill);

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 {
@@ -26,10 +28,12 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     sendTurn(text: string): Promise<TurnResult>;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;
+    prepareSession(): Promise<ProviderSessionRefV1>;
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
     prepareAutoCompaction(thresholdPercent?: number): Promise<NativeAutoCompactionPolicy | void>;
+    requiresAutoCompactionSetupTurn(): boolean;
     autoCompactionPolicy(): NativeAutoCompactionPolicy | undefined;
     drainNativeCompactions(): import("./types.js").NativeCompaction[];
     restoreNativeCompactions(compactions: NativeCompaction[]): void;

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;
@@ -62,12 +72,18 @@ export class RecoveringAdapter {
         return this.adapter.sessionId();
     }
     sessionRef() { return this.adapter.sessionRef?.(); }
+    prepareSession() {
+        if (!this.adapter.prepareSession)
+            return Promise.reject(new Error("wrapped adapter cannot establish a provider session without a work turn"));
+        return this.adapter.prepareSession();
+    }
     adoptSessionRef(ref) { this.adapter.adoptSessionRef?.(ref); }
     validateSession() {
         return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped", detail: "wrapped adapter does not expose scoped session validation" });
     }
     compact() { return this.adapter.compact?.() ?? Promise.resolve({ ok: false, error: "native compaction unavailable" }); }
     prepareAutoCompaction(thresholdPercent) { return this.adapter.prepareAutoCompaction?.(thresholdPercent) ?? Promise.resolve(); }
+    requiresAutoCompactionSetupTurn() { return this.adapter.requiresAutoCompactionSetupTurn?.() ?? false; }
     autoCompactionPolicy() { return this.adapter.autoCompactionPolicy?.(); }
     drainNativeCompactions() { return this.adapter.drainNativeCompactions?.() ?? []; }
     restoreNativeCompactions(compactions) { this.adapter.restoreNativeCompactions?.(compactions); }

package/dist/adapters/types.d.ts

@@ -2,6 +2,7 @@
  * Agent-agnostic interface over a coding agent ("builder").
  */
 import type { ConfigurableAgentRole, ProviderSessionRefV1, RuntimeProbeCategory, RuntimeProbePhase, SessionAvailabilityV1 } from "rafi-spec";
+import type { RunObserver } from "../observability.js";
 /** A permission request surfaced by a builder before it runs a tool. */
 export interface PermissionRequest {
     toolName: string;
@@ -58,16 +59,61 @@ export interface TurnResult {
     costAuthoritative?: boolean;
     inputTokens?: number;
     outputTokens?: number;
+    /** Explicit counter semantics. Compatibility counters above must not be summed without this scope. */
+    usage?: {
+        scope: "turn-delta" | "session-cumulative";
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        costUsd?: number;
+    };
     failure?: RuntimeFailure;
+    /** Stable host/provider correlation ID for this turn. */
+    turnId?: string;
+    /** Exact instruction requested by the immediate host caller. */
+    hostInstruction?: string;
+    /** Exact instruction dispatched to the provider after all wrappers. */
+    providerInstruction?: string;
+    /** Exact provider response before continuity or contract cleanup. */
+    rawResponse?: string;
+    /** Effective response consumed by the host contract parser. */
+    cleanedResponse?: string;
+    providerMetadata?: {
+        provider: "claude" | "codex";
+        sessionId?: string;
+        sessionRef?: ProviderSessionRefV1;
+    };
 }
 /** Observability events emitted while a builder works. */
-export type BuilderEvent = {
+export type BuilderEvent = ({
     kind: "text";
     text: string;
+    byteCount?: number;
+    digest?: string;
 } | {
     kind: "tool";
     name: string;
     input: unknown;
+    inputCompleteness?: "complete" | "truncated" | "unavailable";
+    lifecycle?: "started" | "progress" | "completed";
+    callId?: string;
+    status?: string;
+    durationMs?: number;
+    exitCode?: number;
+    outputSummary?: string;
+    outputDigest?: string;
+    outputCompleteness?: "complete" | "truncated" | "unavailable";
+    rawOutputBytes?: number;
+    completionKnown?: boolean;
+    providerTurnId?: string;
+} | {
+    kind: "provider-item";
+    provider: "claude" | "codex";
+    lifecycle: "started" | "completed";
+    itemType: string;
+    payload: Record<string, unknown>;
+    payloadCompleteness: "complete";
+    providerTurnId?: string;
 } | {
     kind: "activity";
     state: string;
@@ -83,9 +129,12 @@ export type BuilderEvent = {
     maximum?: number;
     delayMs?: number;
     managedBy: "provider" | "rafi";
+    retryId?: string;
+    providerTurnId?: string;
 } | {
     kind: "turn-complete";
     result: TurnResult;
+    turnId?: string;
 } | {
     kind: "session-transition";
     transition: "started" | "resumed" | "compacting" | "compacted" | "fresh-fallback";
@@ -100,6 +149,9 @@ export type BuilderEvent = {
 } | {
     kind: "error";
     message: string;
+}) & {
+    eventId?: string;
+    observedAt?: string;
 };
 export interface ContextUsage {
     used: number;
@@ -183,8 +235,17 @@ export interface BuilderAdapterOptions {
     systemPromptAppend?: string;
     /** Skill names to preload for this session (Claude: lazy-loaded; Codex: flattened). */
     skills?: string[];
+    /** Exact host-frozen skill text injected into the provider instruction. */
+    preloadedSkillContent?: Array<{
+        name: string;
+        content: string;
+    }>;
     /** Provider-native context ceiling, as a percentage of that provider's model window. */
     autoCompactThresholdPercent?: number;
+    /** QA forbids an unjournaled model turn merely to discover the context window. */
+    allowAutoCompactionSetupTurn?: boolean;
+    /** Raw-adapter observability; wrapper adapters must not persist re-emitted events. */
+    observer?: RunObserver;
 }
 export interface BuilderAdapter {
     readonly agent: "claude" | "codex";
@@ -194,6 +255,11 @@ export interface BuilderAdapter {
     sessionId(): string | undefined;
     /** Current location-scoped session reference, once known. */
     sessionRef?(): ProviderSessionRefV1 | undefined;
+    /**
+     * Establish and observe the exact provider session without dispatching a
+     * role/work turn. Durable QA calls this before binding its first turn.
+     */
+    prepareSession?(): Promise<ProviderSessionRefV1>;
     /** Host-only metadata promotion after a validated handoff is accepted. */
     adoptSessionRef?(ref: ProviderSessionRefV1): void;
     /** Attach/probe a requested exact session without starting a provider turn. */
@@ -206,6 +272,8 @@ export interface BuilderAdapter {
      * tool-heavy first turn is protected too.
      */
     prepareAutoCompaction?(thresholdPercent?: number): Promise<NativeAutoCompactionPolicy | void>;
+    /** True only when a provider needs one observable, tool-free turn to learn its context window. */
+    requiresAutoCompactionSetupTurn?(): boolean;
     /** The last provider-native automatic-compaction policy verified on this transport. */
     autoCompactionPolicy?(): NativeAutoCompactionPolicy | undefined;
     /** Consume provider-native compactions observed since the prior drain. */

package/dist/agentRun.d.ts

@@ -22,6 +22,8 @@ export interface RoleBuilderOptions {
     permissionConfig?: PermissionConfig;
     extraSkills?: string[];
     sandboxMode?: BuilderAdapterOptions["sandboxMode"];
+    /** Disable recovery-session persistence for isolated, non-recoverable roles such as Manager. */
+    persistSessionBindings?: boolean;
     resumeSessionId?: string;
     /** Location-scoped exact session. Raw IDs are resolved through durable project bindings or treated as legacy candidates. */
     resumeSessionRef?: ProviderSessionRefV1;

package/dist/agentRun.js

@@ -47,6 +47,22 @@ export function readOnlyPermissionConfig() {
             "git show --stat",
             "git ls-files",
             "git grep",
+            "npm test",
+            "npm run test",
+            "npm run typecheck",
+            "npm run lint",
+            "npm run check",
+            "pnpm test",
+            "pnpm run test",
+            "pnpm typecheck",
+            "pnpm lint",
+            "pnpm --filter ",
+            "yarn test",
+            "pytest",
+            "python -m pytest",
+            "python3 -m pytest",
+            "cargo test",
+            "go test",
         ],
         escalateBash: [
             ...DEFAULT_CONFIG.permissions.escalateBash,
@@ -60,10 +76,12 @@ export function readOnlyPermissionConfig() {
             "git restore",
             "git stash",
             "npm install",
-            "npm run",
             "npm ci",
-            "pnpm ",
-            "yarn ",
+            "pnpm install",
+            "pnpm add",
+            "pnpm remove",
+            "yarn add",
+            "yarn install",
             "mkdir ",
             "touch ",
             "mv ",
@@ -199,6 +217,8 @@ export async function createRoleBuilder(opts) {
     };
     const initial = await makeAdapter(runtime, opts.resumeSessionId, requestedResumeRef);
     const persistSessionRef = (ref) => {
+        if (opts.persistSessionBindings === false)
+            return;
         const bindingDb = new WorkflowDb(opts.projectDir);
         try {
             bindingDb.recordProviderSessionBinding(ref);
@@ -240,6 +260,8 @@ function phaseForRole(role) {
         return "qa";
     if (role === "uninstaller")
         return "uninstaller";
+    if (role === "manager")
+        return "manager";
     return "builder";
 }
 export function readRoleDefaultsForExecution(projectDir, role) {
@@ -253,6 +275,8 @@ export function readRoleDefaultsForExecution(projectDir, role) {
             : undefined;
         if (!saved)
             return undefined;
+        if (role === "manager")
+            return saved;
         if (isFullyInitializedTracker(projectDir))
             return saved;
         const { make: _pendingMake, ...active } = saved;
@@ -333,7 +357,7 @@ export async function runRoleInstruction(opts) {
     }
 }
 function configurableRole(role) {
-    return ["builder", "qa", "planner", "ticket-maker", "uninstaller"].includes(role)
+    return ["builder", "qa", "planner", "ticket-maker", "uninstaller", "manager"].includes(role)
         ? role
         : "builder";
 }

package/dist/branch/currentGuard.d.ts

@@ -23,10 +23,12 @@ export declare class CurrentWorkflowGuardAdapter implements BuilderAdapter {
     sendTurn(text: string): Promise<TurnResult>;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;
+    prepareSession(): Promise<ProviderSessionRefV1>;
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
     prepareAutoCompaction(thresholdPercent?: number): Promise<NativeAutoCompactionPolicy | void>;
+    requiresAutoCompactionSetupTurn(): boolean;
     autoCompactionPolicy(): NativeAutoCompactionPolicy | undefined;
     drainNativeCompactions(): import("../adapters/types.js").NativeCompaction[];
     restoreNativeCompactions(compactions: NativeCompaction[]): void;

package/dist/branch/currentGuard.js

@@ -45,10 +45,19 @@ export class CurrentWorkflowGuardAdapter {
     }
     sessionId() { return this.adapter.sessionId(); }
     sessionRef() { return this.adapter.sessionRef?.(); }
+    async prepareSession() {
+        assertCurrentWorkflowIdentity(this.cwd, this.expected);
+        if (!this.adapter.prepareSession)
+            throw new Error("wrapped adapter cannot establish a provider session without a work turn");
+        const ref = await this.adapter.prepareSession();
+        assertCurrentWorkflowIdentity(this.cwd, this.expected);
+        return ref;
+    }
     adoptSessionRef(ref) { this.adapter.adoptSessionRef?.(ref); }
     validateSession() { assertCurrentWorkflowIdentity(this.cwd, this.expected); return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped" }); }
     async compact() { assertCurrentWorkflowIdentity(this.cwd, this.expected); const result = await (this.adapter.compact?.() ?? Promise.resolve({ ok: false, error: "native compaction unavailable" })); assertCurrentWorkflowIdentity(this.cwd, this.expected); return result; }
     prepareAutoCompaction(thresholdPercent) { return this.adapter.prepareAutoCompaction?.(thresholdPercent) ?? Promise.resolve(); }
+    requiresAutoCompactionSetupTurn() { return this.adapter.requiresAutoCompactionSetupTurn?.() ?? false; }
     autoCompactionPolicy() { return this.adapter.autoCompactionPolicy?.(); }
     drainNativeCompactions() { return this.adapter.drainNativeCompactions?.() ?? []; }
     restoreNativeCompactions(compactions) { this.adapter.restoreNativeCompactions?.(compactions); }