ai-foreman 1.7.20 → 1.7.22

package/README.md

@@ -131,7 +131,7 @@ Provider sessions are historical after import. Resume with `rafi build:resume <p
 | `--branch-prefix <prefix>` | `feature` / `rafi` / another valid Git prefix | `feature` | Prefix for generated ticket branches. Explicit prefixes are preserved verbatim. |
 | `--max-branch-depth <n>` | positive integer | `5` | Maximum selected branch/PR stack depth (root PR is depth 1). |
 | `--show-session-cost` / `--hide-session-cost` | flags | saved role preferences | Show authoritative provider cost or trustworthy cumulative tokens for Builder and QA; does not change context occupancy display. |
-| `--auto-compact-threshold <percent>` | integer `1`–`99` | saved Builder value, then `50` | Initial run threshold override. A newer persistent settings revision wins at the next safe boundary. |
+| `--auto-compact-threshold <percent>` | integer `1`–`99` | saved Builder value, then `65` | Initial run threshold override. A newer persistent settings revision wins at the next safe boundary. |
 
 Auto-detected tracker files:
 
@@ -182,7 +182,7 @@ Owner-only recovery packets under `.foreman/qa-report-recovery/` bind the review
 
 ### `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.
+Manager provides project-wide diagnostic conversations and explicitly authorized, scoped controls over retained build runs. 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.
 
@@ -193,6 +193,16 @@ ai-foreman manager ./my-project
 ai-foreman manager ./my-project --run <run-id> --ask "Compare this run with the last five successful runs"
 ```
 
+Full QA history is available without a provider through `--ask '/qa-work <run>'`, `/qa-attempts <run> <work>`, `/qa-report <run> <work> <attempt> [occurrence]`, and `/qa-timeline <run> <work>`. One-shot output expands all pinned pages and artifacts before exiting, independently of bounded model packets. `/qa-export <run> <work> <attempt> [occurrence]` exports exact protected report bytes with their identity and digest. Interactive `/more <cursor>` and `/artifact <handle>` continuations belong to that session; a later invocation retrieves fresh evidence. Reads do not migrate workflow state.
+
+Explicit `/guide-builder`, `/guide-qa`, and `/guide-both` commands take a run, work ID, and exact advice. The owning process delivers one-use guidance at its next safe boundary. `/pause <run> <work> [run]` waits for the active turn to finish; withdraw the pause to allow continuation. `/request-attempt <run> <work> <reason>` grants one existing-ledger attempt authorization for the current failed review or waiting Builder guidance after an unfinalized pass. Guidance alone never grants attempts. Inspect truthful delivery and verification receipts with `/qa-instruction <run> <work> <instruction>`.
+
+If QA passes while Builder guidance is waiting, explicit resume applies that guidance within the existing approved ticket scope and remaining attempt allowance, then performs a complete fresh QA review. This works on the current branch and in isolated ticket worktrees. The follow-up consumes the same durable allowance as QA remediation; neither a fresh review nor a restart resets it. When the allowance is exhausted, authorize one scoped follow-up with `/request-attempt`, then resume. Changed requirements need renewed approval, and uncertain submissions require reconciliation before another Builder turn. Saving guidance alone does not start work.
+
+Ownership schema 4 requires admitted work before Builder/QA dispatch. Legacy QA records are retained in quarantine when authorization cannot be proved. Both resume aliases assess conflicts before selecting recovery mode. Use `/qa-conflicts <run>` and `/qa-repair-plan <run> <work>` to inspect the source mapping, then submit an explicit `/qa-repair <JSON>` decision with the displayed revision, source digest, approved scope, complete path mapping, and operator attestation. Stop the existing owner first. Repairs preserve source and historical packets and require fresh verification; uncertain provider dispatch needs separate reconciliation.
+
+The upgrade stores a coherent database backup and recovery packet copy under `.rafi/backups/work-admission-v4/<database digest>/` before committing its guards. Rollback means pausing execution and preserving newer evidence for forward repair. Older writers are rejected against upgraded databases; do not down-migrate or restore a backup without accounting for subsequent provider work.
+
 ### 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

@@ -14,6 +14,8 @@ export interface ActivityReporterOptions {
     usefulProgressWarningMs?: number;
     /** Override the safe automatic TTY rendering mode for tests or embedding hosts. */
     ttyMode?: ActivityTtyMode;
+    /** Environment used for color policy; useful for isolated hosts and tests. */
+    colorEnvironment?: NodeJS.ProcessEnv;
 }
 export type ActivityTtyMode = "auto" | "cursor" | "records";
 /** One process-local live view shared by nested RAFI operations. */
@@ -30,6 +32,7 @@ export declare class ActivityReporter {
     private usefulProgressWarningPrinted;
     private pauseStartedAt;
     private readonly ttyMode;
+    private readonly colorEnvironment;
     private readonly commandStartedAt;
     private readonly phases;
     private nextPhaseId;

package/dist/activity.js

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { AsyncQueue } from "./util/asyncQueue.js";
+import { accent, error, info, sanitizeTerminalText, success, warning } from "./terminalStyle.js";
 const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 /** One process-local live view shared by nested RAFI operations. */
 export class ActivityReporter {
@@ -15,6 +16,7 @@ export class ActivityReporter {
     usefulProgressWarningPrinted = false;
     pauseStartedAt = 0;
     ttyMode;
+    colorEnvironment;
     commandStartedAt;
     phases = new Map();
     nextPhaseId = 1;
@@ -43,6 +45,7 @@ export class ActivityReporter {
         this.quietWarningMs = options.quietWarningMs ?? 60_000;
         this.usefulProgressWarningMs = options.usefulProgressWarningMs ?? 300_000;
         this.ttyMode = resolveTtyMode(options.ttyMode);
+        this.colorEnvironment = options.colorEnvironment ?? process.env;
         this.commandStartedAt = this.now();
     }
     begin(label) {
@@ -94,15 +97,16 @@ export class ActivityReporter {
     }
     note(message) {
         this.clearLine();
-        this.output.write(`${clean(message, 500)}\n`);
+        this.output.write(`${sanitizeTerminalText(message).replace(/[\r\t]+/g, " ").slice(0, 500)}\n`);
         this.render(true);
     }
     writePersistent(text) {
         if (!text)
             return;
         this.clearLine();
-        this.output.write(text);
-        if (!text.endsWith("\n"))
+        const safeText = sanitizeTerminalText(text);
+        this.output.write(safeText);
+        if (!safeText.endsWith("\n"))
             this.output.write("\n");
         this.render(true);
     }
@@ -197,7 +201,14 @@ export class ActivityReporter {
         const quiet = quietFor >= this.quietWarningMs ? `provider quiet ${formatDuration(quietFor)}; RAFI is responsive` : this.detail;
         const body = [phase?.label, provider || undefined, phase ? quiet : undefined, this.agentStatusLine].filter(Boolean).join(" — ");
         if (this.output.isTTY) {
-            const line = `${FRAMES[this.frame++ % FRAMES.length]} RAFI working: ${body} (${formatDuration(now - this.commandStartedAt)})`;
+            const color = { stream: this.output, env: this.colorEnvironment };
+            const status = phase?.label.toLowerCase() ?? "";
+            const marker = status.includes("fail") || status.includes("error") ? error("!", color)
+                : status.includes("complete") || status.includes("success") ? success("✓", color)
+                    : status.includes("warn") || status.includes("quiet") ? warning("!", color)
+                        : info(FRAMES[this.frame++ % FRAMES.length], color);
+            const safeBody = sanitizeTerminalText(body);
+            const line = `${marker} ${accent("RAFI", color)} working: ${safeBody} (${formatDuration(now - this.commandStartedAt)})`;
             const semanticKey = semanticStatusKey(body);
             if (this.ttyMode === "records") {
                 if (semanticKey === this.lastSemanticKey)
@@ -223,7 +234,8 @@ export class ActivityReporter {
             return;
         if (force || now - this.lastHeartbeatAt >= this.heartbeatMs) {
             this.lastHeartbeatAt = now;
-            this.output.write(`[${new Date(now).toISOString()}] rafi working: ${body} (${formatDuration(now - this.commandStartedAt)})\n`);
+            const color = { stream: this.output, env: this.colorEnvironment };
+            this.output.write(`[${new Date(now).toISOString()}] ${accent("rafi", color)} working: ${sanitizeTerminalText(body)} (${formatDuration(now - this.commandStartedAt)})\n`);
             this.lastSemanticKey = semanticKey;
         }
     }
@@ -286,8 +298,15 @@ export function reportBuilderEvent(event) {
                 reporter.pulse();
                 break;
             case "completed":
-                reporter.completedWork();
-                if (isFailedToolCompletion(event))
+                if (event.completionKnown !== false)
+                    reporter.completedWork();
+                if (event.status === "unknown")
+                    reporter.update("tool outcome unknown", event.name, { immediate: false });
+                else if (event.status === "timed_out")
+                    reporter.update("tool timed out", event.name);
+                else if (event.status === "cancelled")
+                    reporter.update("tool cancelled", event.name);
+                else if (isFailedToolCompletion(event))
                     reporter.update("tool failed", event.name);
                 else
                     reporter.pulse();
@@ -341,7 +360,7 @@ function isFailedToolCompletion(event) {
         || (typeof event.exitCode === "number" && Number.isFinite(event.exitCode) && event.exitCode !== 0);
 }
 function clean(value, maximum) {
-    return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maximum);
+    return sanitizeTerminalText(value).replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maximum);
 }
 function semanticStatusKey(body) {
     return body

package/dist/adapters/claude.d.ts

@@ -1,3 +1,4 @@
+import { ProviderPhaseBarrier, type ProviderTurnPurpose } from "../providerPhase.js";
 import type { SDKSessionInfo, PermissionResult } from "@anthropic-ai/claude-agent-sdk";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export declare function requireClaudeSDK(): Promise<typeof import("@anthropic-ai/claude-agent-sdk")>;
@@ -43,6 +44,12 @@ export declare function claudeApiRetryEvent(message: {
 export declare class ClaudeAdapter implements BuilderAdapter {
     private readonly opts;
     readonly agent: "claude";
+    graphRuntimeSettings(): {
+        model: string | undefined;
+        effort: import("./types.js").EffortLevel | undefined;
+        fast: boolean | undefined;
+        runtimeExecutable: string | undefined;
+    };
     private readonly inbox;
     private readonly eventQueue;
     private readonly query;
@@ -71,9 +78,20 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private activeProviderTurnId?;
     private activeProviderTurnSpanId?;
     private readonly toolSpans;
+    private readonly toolCalls;
+    private readonly completedToolCalls;
+    private readonly unknownToolResults;
     private pending?;
     private questionTrace?;
     private responseOnlyTurn;
+    readonly phaseBarrier: ProviderPhaseBarrier;
+    contractCapabilities(): {
+        sameSessionAcceptance: boolean;
+        nativeCompactionBarrier: boolean;
+    };
+    enableContractEnforcement(): void;
+    contractCompactionSequence(): number;
+    acceptContractDelivery(sequence: number): void;
     private terminalResult?;
     private streamEnded;
     private closed;
@@ -86,6 +104,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
         handback?: boolean;
         responseOnly?: boolean;
         logicalActionId?: string;
+        purpose?: ProviderTurnPurpose;
     }): Promise<TurnResult>;
     private sendTurnInternal;
     private captureStderr;

package/dist/adapters/claude.js

@@ -1,3 +1,4 @@
+import { ProviderPhaseBarrier } from "../providerPhase.js";
 import { OperationDeadline } from "../util/deadline.js";
 import { createHash, randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
@@ -27,6 +28,7 @@ const DEFAULT_PROVIDER_IDLE_TIMEOUT_MS = 30 * 60_000;
  */
 export function buildClaudeQueryOptions(opts) {
     const qaReadOnly = opts.sessionRole === "qa" || opts.sandboxMode === "read-only";
+    const confinedBuilder = opts.sessionRole === "builder";
     const base = {
         cwd: opts.cwd,
         pathToClaudeCodeExecutable: opts.runtimeExecutable,
@@ -41,18 +43,24 @@ export function buildClaudeQueryOptions(opts) {
         // settings in those roles.
         settingSources: qaReadOnly ? ["user"] : ["user", "project", "local"],
         ...(qaReadOnly ? { disallowedTools: ["Write", "Edit", "NotebookEdit"] } : {}),
+        ...(confinedBuilder && !qaReadOnly ? { sandbox: {
+                enabled: true, failIfUnavailable: true, autoAllowBashIfSandboxed: false, allowUnsandboxedCommands: false,
+                network: opts.networkAccess === true ? { allowedDomains: ["*"] } : { allowedDomains: [], deniedDomains: ["*"] },
+                filesystem: { allowWrite: [opts.cwd] },
+            } } : {}),
         ...(qaReadOnly ? { sandbox: {
                 enabled: true,
                 failIfUnavailable: true,
                 autoAllowBashIfSandboxed: true,
                 allowUnsandboxedCommands: false,
+                network: { allowedDomains: [], deniedDomains: ["*"] },
                 filesystem: { allowWrite: [join(dirname(opts.cwd), "scratch")], denyWrite: [opts.cwd, ...(opts.configRoot ? [opts.configRoot] : [])] },
             } } : {}),
     };
     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");
+    const systemAppend = [opts.systemPromptAppend, opts.sessionRole === "builder" ? `Builder runtime contract: shell network ${opts.networkAccess === true ? "explicitly approved for this build" : "disabled"}; sandbox fallback disabled. If acquisition requires unavailable access, request input first or use a provenance-verified local bundle. A ticket answer does not grant runtime permissions.` : undefined, exactSkills].filter((part) => Boolean(part)).join("\n\n");
     if (systemAppend) {
         base.systemPrompt = { type: "preset", preset: "claude_code", append: systemAppend };
     }
@@ -165,6 +173,7 @@ export function claudeApiRetryEvent(message) {
 export class ClaudeAdapter {
     opts;
     agent = "claude";
+    graphRuntimeSettings() { return { model: this.opts.model, effort: this.opts.effort, fast: this.opts.fast, runtimeExecutable: this.opts.runtimeExecutable }; }
     inbox = new AsyncQueue();
     eventQueue = new BuilderEventQueue();
     query;
@@ -193,9 +202,17 @@ export class ClaudeAdapter {
     activeProviderTurnId;
     activeProviderTurnSpanId;
     toolSpans = new Map();
+    toolCalls = new Map();
+    completedToolCalls = new Set();
+    unknownToolResults = new Map();
     pending;
     questionTrace;
     responseOnlyTurn = false;
+    phaseBarrier = new ProviderPhaseBarrier();
+    contractCapabilities() { return { sameSessionAcceptance: true, nativeCompactionBarrier: true }; }
+    enableContractEnforcement() { this.phaseBarrier.enableEnforcement(); }
+    contractCompactionSequence() { return this.phaseBarrier.compactionSequence; }
+    acceptContractDelivery(sequence) { this.phaseBarrier.accept(sequence); }
     terminalResult;
     streamEnded = false;
     closed = false;
@@ -239,6 +256,7 @@ export class ClaudeAdapter {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     constructor(opts, query) {
         this.opts = opts;
+        this.phaseBarrier.begin("initialization");
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
         this._sessionRef = opts.resumeSessionRef;
         this.sessionIdentityReady = new Promise((resolve, reject) => {
@@ -255,7 +273,15 @@ export class ClaudeAdapter {
             options: {
                 ...buildClaudeQueryOptions(opts),
                 abortController: this.abort,
-                hooks: { SessionStart: [{ hooks: [async (input) => {
+                hooks: {
+                    PreToolUse: [{ hooks: [async (input) => {
+                                    if (input.hook_event_name !== "PreToolUse")
+                                        return {};
+                                    const reason = this.phaseBarrier.denial(input.tool_name);
+                                    return reason ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } } : {};
+                                }] }],
+                    PreCompact: [{ hooks: [async () => { this.phaseBarrier.compact(); return {}; }] }],
+                    SessionStart: [{ hooks: [async (input) => {
                                     if (input.hook_event_name !== "SessionStart" || input.agent_id)
                                         return {};
                                     try {
@@ -266,7 +292,8 @@ export class ClaudeAdapter {
                                         throw error;
                                     }
                                     return {};
-                                }] }] },
+                                }] }]
+                },
                 stderr: (data) => this.captureStderr(data),
                 canUseTool: async (toolName, input, requestOptions = {}) => {
                     if (this.responseOnlyTurn)
@@ -372,6 +399,9 @@ export class ClaudeAdapter {
                 }
                 else if (block.type === "tool_use") {
                     const callId = block.id;
+                    this.toolCalls.set(callId, { name: block.name, input: block.input });
+                    if (this.toolCalls.size > 1000)
+                        this.toolCalls.delete(this.toolCalls.keys().next().value);
                     this.eventQueue.push({
                         kind: "tool",
                         name: block.name,
@@ -512,6 +542,7 @@ export class ClaudeAdapter {
         if (this.pending)
             throw new Error("a turn is already in progress");
         this.responseOnlyTurn = Boolean(policy?.responseOnly);
+        this.phaseBarrier.begin(policy?.purpose ?? (policy?.responseOnly ? "response-repair" : "implementation"));
         const turnId = randomUUID();
         this.activeProviderTurnId = turnId;
         const observer = this.opts.observer;
@@ -597,14 +628,35 @@ export class ClaudeAdapter {
             const callId = typeof block.tool_use_id === "string" ? block.tool_use_id : undefined;
             if (!callId)
                 continue;
+            if (this.completedToolCalls.has(callId))
+                continue;
+            const call = this.toolCalls.get(callId);
             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 sanitized = text.replace(/\b(token|password|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[REDACTED]");
             const failed = block.is_error === true;
+            // TIME_ELAPSED alone does not establish success or failure. Preserve it as unknown.
+            const elapsedOnly = /^\s*TIME_ELAPSED\s*$/.test(text);
+            const status = failed && /timed?\s*out|timeout/i.test(text) ? "timed_out" : failed && /cancel(?:led|ed)/i.test(text) ? "cancelled" : elapsedOnly ? "unknown" : failed ? "failed" : "completed";
+            if (status !== "unknown") {
+                this.completedToolCalls.add(callId);
+                if (this.completedToolCalls.size > 1000)
+                    this.completedToolCalls.delete(this.completedToolCalls.values().next().value);
+                this.toolCalls.delete(callId);
+            }
             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 } });
+            if (status === "unknown") {
+                if (this.unknownToolResults.get(callId) === outputDigest)
+                    continue;
+                this.unknownToolResults.set(callId, outputDigest);
+                if (this.unknownToolResults.size > 1000)
+                    this.unknownToolResults.delete(this.unknownToolResults.keys().next().value);
+            }
+            else
+                this.unknownToolResults.delete(callId);
+            this.eventQueue.push({ kind: "tool", name: call?.name ?? "unidentified tool", input: call?.input ?? {}, inputCompleteness: call ? "complete" : "unavailable", lifecycle: "completed", callId, status, outputSummary: sanitized.slice(0, 1000), outputDigest, outputCompleteness: block.is_truncated === true ? "truncated" : "complete", rawOutputBytes: Buffer.byteLength(text), completionKnown: status !== "unknown", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
+            if (spanId && this.opts.observer && status !== "unknown") {
+                this.opts.observer.store.finishSpan(spanId, { outcome: status, completionKnown: true, attributes: { callId, outputSummary: sanitized.slice(0, 1000), outputDigest } });
                 this.toolSpans.delete(callId);
             }
             this.opts.observer?.signal(true);

package/dist/adapters/codex.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderTurnPurpose } from "../providerPhase.js";
 import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, NativeAutoCompactionPolicy, NativeCompaction, ProviderSessionUsage, ProviderSettingSwitch, TurnResult } from "./types.js";
 import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 export interface CodexLineResult {
@@ -11,6 +12,12 @@ export declare function parseCodexLine(raw: Record<string, unknown>): CodexLineR
 export declare class CodexAdapter implements BuilderAdapter {
     private readonly opts;
     readonly agent: "codex";
+    graphRuntimeSettings(): {
+        model: string | undefined;
+        effort: import("./types.js").EffortLevel | undefined;
+        fast: boolean | undefined;
+        runtimeExecutable: string | undefined;
+    };
     private readonly eventQueue;
     private process?;
     private nextId;
@@ -40,9 +47,17 @@ export declare class CodexAdapter implements BuilderAdapter {
     private compactionUncertain;
     private observedToolCalls;
     private activeProviderTurnId?;
+    private activeNativeTurnId?;
+    private connectionGeneration;
+    private readonly approvalRequests;
+    private readonly answeredApprovalRequests;
     private activeProviderTurnSpanId?;
     private readonly toolSpans;
     constructor(opts: BuilderAdapterOptions);
+    contractCapabilities(): {
+        sameSessionAcceptance: boolean;
+        nativeCompactionBarrier: boolean;
+    };
     buildInstruction(instruction: string): string;
     buildAppServerArgs(): string[];
     /** Deprecated fixture helper. Runtime execution uses only app-server. */
@@ -51,6 +66,7 @@ export declare class CodexAdapter implements BuilderAdapter {
         handback?: boolean;
         responseOnly?: boolean;
         logicalActionId?: string;
+        purpose?: ProviderTurnPurpose;
     }): Promise<TurnResult>;
     private sendTurnInternal;
     compact(): Promise<CompactResult>;
@@ -85,6 +101,10 @@ export declare class CodexAdapter implements BuilderAdapter {
     private traceLifecycle;
     private touchWaiters;
     private providerIdleTimeoutMs;
+    private effectiveNetworkAccess;
+    private effectiveApprovalPolicy;
+    /** Fail closed; approval is for this operation only, never a session cache or policy amendment. */
+    private handleServerRequest;
     private disconnect;
     private restartForAutoCompaction;
     private buildSkillsAppendix;

package/dist/adapters/codex.js

@@ -31,6 +31,7 @@ const DEFAULT_PROVIDER_IDLE_TIMEOUT_MS = 30 * 60_000;
 export class CodexAdapter {
     opts;
     agent = "codex";
+    graphRuntimeSettings() { return { model: this.opts.model, effort: this.opts.effort, fast: this.opts.fast, runtimeExecutable: this.opts.runtimeExecutable }; }
     eventQueue = new BuilderEventQueue();
     process;
     nextId = 1;
@@ -60,6 +61,10 @@ export class CodexAdapter {
     compactionUncertain = false;
     observedToolCalls = 0;
     activeProviderTurnId;
+    activeNativeTurnId;
+    connectionGeneration = 0;
+    approvalRequests = new Map();
+    answeredApprovalRequests = new Set();
     activeProviderTurnSpanId;
     toolSpans = new Map();
     constructor(opts) {
@@ -67,8 +72,11 @@ export class CodexAdapter {
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
         this._sessionRef = opts.resumeSessionRef;
     }
+    contractCapabilities() { return { sameSessionAcceptance: true, nativeCompactionBarrier: false }; }
     buildInstruction(instruction) {
-        return [this.opts.systemPromptAppend, this.buildSkillsAppendix(), instruction]
+        return [this.opts.systemPromptAppend,
+            this.opts.sessionRole === "builder" ? `Builder runtime contract: shell network ${this.effectiveNetworkAccess() ? "explicitly approved for this build" : "disabled"}; sandbox escalation ${this.effectiveApprovalPolicy() === "on-request" ? "requires separate approval for each exact operation" : "disabled"}. Web tools do not establish shell network access. If acquisition needs unavailable capabilities, request input before running acquisition, or use a local source/dependency bundle with verified provenance. A ticket answer does not change runtime permissions.` : undefined,
+            this.buildSkillsAppendix(), instruction]
             .filter((part) => Boolean(part)).join("\n\n");
     }
     buildAppServerArgs() {
@@ -102,6 +110,7 @@ export class CodexAdapter {
             }
             finally {
                 this.activeProviderTurnId = undefined;
+                this.activeNativeTurnId = undefined;
             }
         }
         const context = this.observationContext();
@@ -123,6 +132,7 @@ export class CodexAdapter {
                 this.toolSpans.delete(callId);
             }
             this.activeProviderTurnId = undefined;
+            this.activeNativeTurnId = undefined;
             this.activeProviderTurnSpanId = undefined;
         }
     }
@@ -140,13 +150,18 @@ export class CodexAdapter {
             this.turnUsageBaseline = this.providerSessionUsage ? { ...this.providerSessionUsage } : undefined;
             const completion = this.waitFor("turn/completed", (params) => params.threadId === this._sessionId, this.providerIdleTimeoutMs(), true);
             turnStartDispatched = true;
-            await this.request("turn/start", {
+            const started = await this.request("turn/start", {
                 threadId: this._sessionId,
                 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),
+                approvalPolicy: policy?.responseOnly || policy?.purpose && policy.purpose !== "implementation" ? "never" : this.effectiveApprovalPolicy(),
+                sandboxPolicy: policy?.responseOnly || policy?.purpose && policy.purpose !== "implementation" || this.opts.sandboxMode === "read-only" || this.opts.sessionRole === "qa"
+                    ? { type: "readOnly", networkAccess: false }
+                    : { type: "workspaceWrite", writableRoots: [this.opts.cwd], networkAccess: this.effectiveNetworkAccess() },
             });
+            this.activeNativeTurnId = String(started.turn?.id ?? "") || undefined;
             const params = await new OperationDeadline("Codex active turn", this.opts.turnDeadlineMs ?? 3_600_000).run(() => completion);
             const turn = params.turn;
             const responseOnlyViolation = Boolean(policy?.responseOnly && this.observedToolCalls !== toolsBefore);
@@ -319,7 +334,7 @@ export class CodexAdapter {
             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.");
+            const setup = await this.sendTurnInternal("Rafi internal initialization only. Do not call tools or modify files. Reply briefly that the context is ready.", { purpose: "initialization", responseOnly: true });
             if (setup.isError)
                 throw new Error(`Codex automatic-compaction setup failed: ${setup.text.slice(0, 240)}`);
             if (this.observedToolCalls !== toolsBefore)
@@ -457,8 +472,9 @@ export class CodexAdapter {
         try {
             result = await this.request(method, {
                 ...(this._sessionId ? { threadId: this._sessionId } : {}), cwd: this.opts.cwd,
-                model: this.opts.model ?? null, approvalPolicy: "never",
-                sandbox: this.opts.sandboxMode === "read-only" ? "read-only" : "workspace-write",
+                model: this.opts.model ?? null, approvalPolicy: this.effectiveApprovalPolicy(),
+                config: { sandbox_workspace_write: { network_access: this.effectiveNetworkAccess() } },
+                sandbox: this.opts.sandboxMode === "read-only" || this.opts.sessionRole === "qa" ? "read-only" : "workspace-write",
                 developerInstructions: this.opts.systemPromptAppend ?? null,
             });
         }
@@ -474,6 +490,17 @@ export class CodexAdapter {
             }
             throw error;
         }
+        const effective = result.sandbox;
+        if (this.effectiveNetworkAccess() && !effective)
+            throw new Error("Codex did not report an effective sandbox policy for the requested network grant; no turn dispatched");
+        const requestedSandbox = this.opts.sandboxMode === "read-only" || this.opts.sessionRole === "qa" ? "readOnly" : "workspaceWrite";
+        if (effective && (effective.type !== requestedSandbox || effective.networkAccess === true && !this.effectiveNetworkAccess()))
+            throw new Error("Codex effective sandbox exceeds the authorized role policy; no turn dispatched");
+        if (effective && this.effectiveNetworkAccess() && effective.networkAccess !== true)
+            throw new Error("Codex did not enable the explicitly approved builder network; use an offline bundle or correct provider policy before implementation");
+        if (result.approvalPolicy !== undefined && result.approvalPolicy !== this.effectiveApprovalPolicy())
+            throw new Error("Codex effective approval policy differs from the requested role policy; no turn dispatched");
+        this.eventQueue.push({ kind: "activity", state: "Codex role capabilities", provider: "codex", detail: JSON.stringify({ requested: { sandbox: requestedSandbox, networkAccess: this.effectiveNetworkAccess(), approvalPolicy: this.effectiveApprovalPolicy() }, effective: effective ?? "unknown", approvalPolicy: result.approvalPolicy ?? "unknown" }) });
         const thread = result.thread;
         const returnedSessionId = String(thread?.id ?? this._sessionId ?? "") || undefined;
         if (this._sessionRef && returnedSessionId !== this._sessionRef.sessionId) {
@@ -567,6 +594,10 @@ export class CodexAdapter {
     }
     handle(message) {
         this.touchWaiters();
+        if (message.id !== undefined && message.method) {
+            void this.handleServerRequest(message);
+            return;
+        }
         if (message.id !== undefined) {
             const pending = this.pending.get(message.id);
             if (pending) {
@@ -737,6 +768,11 @@ export class CodexAdapter {
             if (timeoutMs !== undefined) {
                 const arm = () => {
                     timeout = setTimeout(() => {
+                        // Human approval has its own bounded deadline; it is not provider idleness.
+                        if (resetOnProviderActivity && this.approvalRequests.size > 0) {
+                            arm();
+                            return;
+                        }
                         const active = this.notificationWaiters.get(method) ?? [];
                         this.notificationWaiters.set(method, active.filter((candidate) => candidate !== waiter));
                         clear();
@@ -765,7 +801,65 @@ export class CodexAdapter {
         const configured = this.opts.providerIdleTimeoutMs;
         return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_PROVIDER_IDLE_TIMEOUT_MS;
     }
+    effectiveNetworkAccess() {
+        return this.opts.sandboxMode !== "read-only" && this.opts.sessionRole !== "qa" && this.opts.networkAccess === true;
+    }
+    effectiveApprovalPolicy() {
+        return this.opts.sandboxMode === "read-only" || this.opts.sessionRole === "qa" ? "never" : this.opts.approvalPolicy ?? "never";
+    }
+    /** Fail closed; approval is for this operation only, never a session cache or policy amendment. */
+    async handleServerRequest(message) {
+        await Promise.resolve();
+        const id = message.id;
+        const identity = `${typeof id}:${id}`;
+        if (this.approvalRequests.has(identity) || this.answeredApprovalRequests.has(identity))
+            return;
+        const params = message.params ?? {};
+        const command = message.method === "item/commandExecution/requestApproval";
+        const fileChange = message.method === "item/fileChange/requestApproval";
+        if (!command && !fileChange) {
+            this.write({ id, error: { code: -32601, message: `Unsupported server request: ${message.method}` } });
+            return;
+        }
+        const connection = this.process;
+        const generation = this.connectionGeneration;
+        const hostTurnId = this.activeProviderTurnId;
+        const controller = new AbortController();
+        this.approvalRequests.set(identity, controller);
+        let decision = "decline";
+        try {
+            if (this.effectiveApprovalPolicy() === "on-request" && params.threadId === this._sessionId && this.activeProviderTurnId && typeof params.turnId === "string" && typeof params.itemId === "string" && params.turnId === this.activeNativeTurnId && (params.cwd === undefined || canonicalSessionPath(String(params.cwd)) === canonicalSessionPath(this.opts.cwd))) {
+                const verdict = await new OperationDeadline("Codex approval", this.opts.approvalTimeoutMs ?? 300_000).run(() => this.opts.permission({
+                    toolName: command ? "Bash" : "Write",
+                    input: { ...params, providerSandboxEscalation: true, requestedCommand: params.command },
+                    signal: controller.signal, toolUseID: String(params.itemId),
+                    title: "Approve this exact sandbox escalation?", description: String(params.reason ?? "Provider requests access beyond the offline workspace sandbox"),
+                }), () => controller.abort());
+                if (!controller.signal.aborted && verdict.behavior === "allow" && params.threadId === this._sessionId && this.activeProviderTurnId === hostTurnId && params.turnId === this.activeNativeTurnId)
+                    decision = "accept";
+            }
+        }
+        catch {
+            controller.abort();
+        }
+        finally {
+            this.approvalRequests.delete(identity);
+            this.touchWaiters();
+            this.answeredApprovalRequests.add(identity);
+            if (generation === this.connectionGeneration && connection === this.process && !this.closed) {
+                try {
+                    this.write({ id, result: { decision } });
+                }
+                catch { /* disconnected: no stale reply on another connection */ }
+            }
+        }
+    }
     disconnect(error) {
+        this.connectionGeneration++;
+        for (const controller of this.approvalRequests.values())
+            controller.abort();
+        this.approvalRequests.clear();
+        this.answeredApprovalRequests.clear();
         const child = this.process;
         this.process = undefined;
         this.initialized = false;

package/dist/adapters/recovering.d.ts

@@ -23,8 +23,17 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     private readonly eventQueue;
     private eventPump;
     private closed;
+    private contractEnforcing;
     constructor(opts: RecoveringAdapterOptions);
+    graphRuntimeSettings(): Pick<import("./types.js").BuilderAdapterOptions, "model" | "effort" | "fast" | "runtimeExecutable"> | undefined;
     get agent(): "claude" | "codex";
+    contractCapabilities(): {
+        sameSessionAcceptance: boolean;
+        nativeCompactionBarrier: boolean;
+    };
+    enableContractEnforcement(): void;
+    contractCompactionSequence(): number;
+    acceptContractDelivery(sequence: number): void;
     sendTurn(text: string, policy?: Parameters<BuilderAdapter["sendTurn"]>[1]): Promise<TurnResult>;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;