ai-foreman 1.7.19 → 1.7.21

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:
 
@@ -166,21 +166,23 @@ Build stall recovery uses current context occupancy, not lifetime token usage. T
 
 Unchanged, source-bound plan and ticket approvals are reused. Material ticket, plan, delivery, or workflow changes require a new decision, including with `--yes`. Legacy approval evidence that cannot prove unchanged scope requires review. `--steps` counts completed tickets or steps; it is neither a wall-clock limit nor a model-turn budget.
 
-Questions are persisted before prompting. Redirected or detached runs return a recoverable needs-input outcome (exit 2). Use `rafi build:attach . --run <id>` to see decisions, `rafi build:decide . --run <id> --decision <id> --choice <id>` to answer, and `rafi build:resume . --run <id>` to continue. Custom answers additionally use `--choice custom --answer "text"`. Independent eligible tickets continue around a ticket blocker; dependent and unsafe shared-delivery work stays deferred. Answered ticket questions are reconsidered at safe boundaries.
+Questions are persisted before prompting. Redirected or detached runs return a recoverable needs-input outcome (exit 2). Use `rafi build:attach . --run <id>` to see decisions, `rafi build:decide . --run <id> --decision <id> --choice <id>` to answer, and `rafi resume` to select a build and continue. Custom answers additionally use `--choice custom --answer "text"`. Independent eligible tickets continue around a ticket blocker; dependent and unsafe shared-delivery work stays deferred. Answered ticket questions are reconsidered at safe boundaries.
 
 CLI starts run under a durable parent supervisor by default. `--detach` writes output under `.rafi/logs/supervisor-<run>.log`; `--no-supervisor` retains direct execution. A preparation-only worker crash may restart within frozen budgets after proving the worker and registered readiness children are stopped. A worker crash with unresolved provider work pauses for reconciliation: it does not silently repeat a possibly completed action. `build:stop` signals only a verified supervisor process incarnation.
 
-Runtime deadlines can be overridden in `autonomy.runtime_deadlines` using positive integer milliseconds: `preparation_ms` (120000), `rpc_ms` (60000), `compaction_ms` (120000), `shutdown_ms` (10000), and `turn_ms` (3600000). They are frozen with the run policy. Transport-idle and hard active-turn deadlines have distinct meanings; neither grants permission to repeat uncertain side effects. Attached-process elapsed time includes waiting and is not provider compute time. Activity warns after five minutes without a completed tool or agent turn; intentional human waits are excluded, and the warning alone does not cancel work. Final paused output lists the durable question and exact run-scoped recovery commands.
+Runtime deadlines can be overridden in `autonomy.runtime_deadlines` using positive integer milliseconds: `preparation_ms` (120000), `rpc_ms` (60000), `compaction_ms` (120000), `shutdown_ms` (10000), and `turn_ms` (3600000). They are frozen with the run policy. Transport-idle and hard active-turn deadlines have distinct meanings; neither grants permission to repeat uncertain side effects. Attached-process elapsed time includes waiting and is not provider compute time. Activity warns after five minutes without a completed tool or agent turn; intentional human waits are excluded, and the warning alone does not cancel work. Final paused output lists the durable question, its answer command, and the short `rafi resume` recovery command.
 
 The current terminal status includes the role/provider, activity, truthful context state, successful compaction count, and handoff generation. At the Builder threshold, Foreman settles the in-flight action, verifies native compaction plus a fresh provider usage sample, and resumes the frozen action. The configured maximum defaults to ten successful compactions per location-scoped provider session; the next crossing uses a validated fresh handoff instead of exceeding it. Disposable QA snapshots never reuse a prior QA conversation in a new `/tmp/rafi-qa-*` worktree; they transfer cumulative state through an accepted handoff.
 
 Failed QA reviews use the versioned `RAFI_QA_FAILURE_REPORT_START` / `RAFI_QA_FAILURE_REPORT_END` JSON contract. Foreman validates the report before Builder remediation, namespaces finding IDs by run, ticket, and review, and durably indexes the exact report, remediation response, and bounded fix summary by digest. A malformed failing report receives two correction-only turns in its original session, then a validated fresh successor performs one complete source-bound review followed by up to two correction-only turns. Any later operator-requested fresh successor performs one complete source-bound review followed by five usable correction-only turns.
 
-Owner-only recovery packets under `.foreman/qa-report-recovery/` bind the review to a full frozen source digest: commit, porcelain status, staged and unstaged bytes, and untracked content. Every fresh attempt captures and compares that complete state. Drift appends the new state and forces a complete review; correction-only reconstruction is never applied to changed source. Packet revisions and the authoritative WorkflowDb recovery head advance together. A successor must have a location-scoped identity, accept a handoff containing the complete resource inventory (purpose, byte count, digest, and recovery requirement), and acknowledge the copied packet before reporting. Paused recovery resumes with `rafi build:resume <project> --run <run-id> --ticket <ticket-id> --fresh-with-handoff`.
+A completed QA turn with missing/invalid continuity metadata or a malformed response can trigger one automatic complete fresh review per ticket. That allowance is durable across restarts and shared across protocol failures. The old session and snapshot close before the new review starts. Exhausted same-session report correction and malformed resumed report/acknowledgement responses use this route, rather than requiring an immediate manual resume. Earlier invalid responses cannot authorize Builder work or a QA pass. Provider execution failures, uncertain dispatch, invalid acceptance receipts, and modified recovery evidence still pause. Repeated failures exhaust the allowance and preserve recoverable state; independent eligible tickets can continue.
+
+Owner-only recovery packets under `.foreman/qa-report-recovery/` bind the review to a full frozen source digest: commit, porcelain status, staged and unstaged bytes, and untracked content. Every fresh attempt captures and compares that complete state. Drift appends the new state and forces a complete review; correction-only reconstruction is never applied to changed source. Packet revisions and the authoritative WorkflowDb recovery head advance together. A successor must have a location-scoped identity, accept a handoff containing the complete resource inventory (purpose, byte count, digest, and recovery requirement), and acknowledge the copied packet before reporting. Paused recovery is available through `rafi resume` or `rafi build:resume` in the project directory. The picker resolves the ticket, current QA revision, and validated QA handoff internally; explicit recovery flags still reject stale revisions.
 
 ### `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.
 
@@ -191,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.
@@ -681,3 +693,15 @@ Package output:
 - **`special-agents`** — library (rules + skills + agents + composition)
 - **`ai-foreman`** — this runtime
 - **`@rafi-ai/cli`** — CLI for `rafi create` and `rafi compile`
+
+### Recovery ownership upgrades
+
+Stop existing workers before upgrading. The recovery database now records preparation admission, single-use launches, retry lineage, owned readiness processes and monotonic lease generations. Older binaries must not write an upgraded database; preserve these records when troubleshooting rather than deleting locks. Unknown process identity, incomplete child-launch evidence or an unresolved provider dispatch requires reconciliation. A stale heartbeat alone does not authorize another worker. Read-only resume inspection supports older storage without migrating it.
+
+Ownership schema version 2 adds bounded child registration/acknowledgement, explicit child-workflow ownership, and separate readiness/cleanup outcomes. Build readiness requires the original admission and owning project even when the command executes in an external worktree. Both the current build and competing starts wait for verified probe cleanup. Runtime snapshot, dispatch, continuity and session writes retain original authority; releasing a lease does not make those records writable by an arbitrary caller. Completed, cancelled and superseded builds cannot be reactivated by saving a snapshot.
+
+Ownership schema version 3 gates provider readiness behind registered helper authorization and records cleanup separately. Cleanup is reachable through both short resume commands even when its owning build is terminal or has no valid build snapshot. Restricted cleanup connections can update only their selected readiness records. Migration waits for local legacy execution to become safely quiescent; persistent compatibility guards then reject already-open older writers as well as new older opens. Uncertain remote provider records survive the upgrade unchanged so their owning recovery flow remains reachable. Ordinary starts remain blocked until those operations are reconciled. A lost acknowledgement cannot revoke an already-authorized helper.
+
+Standalone readiness also rejects unverified cleanup. The current process retains its cleanup evidence and checks it before another probe starts; restoring process visibility permits a retry. Standalone commands do not create a build recovery database, so this evidence does not survive process exit.
+
+On macOS/Linux, readiness cleanup checks the dedicated process group and inherited probe tags, including tagged descendants that escape the group. This is not a sandbox for descendants that deliberately remove their tag and detach. Unavailable inventory and ambiguous legacy evidence remain unresolved. The Windows readiness implementation targets Windows 10 / Server 2016 APIs, but those minimum versions have not been verified. Native Windows verification remains a release gate. Readiness providers start inside a non-breakaway Job Object with kill-on-close behavior, using built-in Windows PowerShell and `Add-Type`. Standard npm `.cmd`/`.bat` provider shims resolve to direct Node arguments; arbitrary shell shims are rejected. The Windows Job Object applies to readiness probes; it does not add containment for arbitrary Builder commands. Native regression tests are in `.github/workflows/build-recovery.yml`; the implementation plan records actual platform verification.

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;
         }
     }
@@ -341,7 +353,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;
@@ -74,6 +81,14 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     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 +101,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;
@@ -196,6 +205,11 @@ export class ClaudeAdapter {
     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 +253,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 +270,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 +289,8 @@ export class ClaudeAdapter {
                                         throw error;
                                     }
                                     return {};
-                                }] }] },
+                                }] }]
+                },
                 stderr: (data) => this.captureStderr(data),
                 canUseTool: async (toolName, input, requestOptions = {}) => {
                     if (this.responseOnlyTurn)
@@ -512,6 +536,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;

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;

package/dist/adapters/recovering.js

@@ -10,15 +10,21 @@ export class RecoveringAdapter {
     eventQueue = new AsyncQueue();
     eventPump;
     closed = false;
+    contractEnforcing = false;
     constructor(opts) {
         this.opts = opts;
         this.adapter = opts.initial;
         this.runtime = opts.runtime;
         this.eventPump = this.forwardEvents(this.adapter);
     }
+    graphRuntimeSettings() { return this.adapter.graphRuntimeSettings?.(); }
     get agent() {
         return this.adapter.agent;
     }
+    contractCapabilities() { return this.adapter.contractCapabilities?.() ?? { sameSessionAcceptance: false, nativeCompactionBarrier: false }; }
+    enableContractEnforcement() { this.contractEnforcing = true; this.adapter.enableContractEnforcement?.(); }
+    contractCompactionSequence() { return this.adapter.contractCompactionSequence?.() ?? 0; }
+    acceptContractDelivery(sequence) { this.adapter.acceptContractDelivery?.(sequence); }
     async sendTurn(text, policy) {
         while (true) {
             const result = await this.adapter.sendTurn(text, policy);
@@ -37,6 +43,10 @@ export class RecoveringAdapter {
             // instruction. Never replay it or silently switch providers.
             if (result.failure.category === "session-unavailable" || result.failure.dispatchState === "unknown")
                 return result;
+            // A replacement has new host-side barriers, even when it resumes the
+            // same native session. Only the shared build gate can renew acceptance.
+            if (this.contractEnforcing)
+                return { ...result, text: `${result.text}\nContract-enforcing runtime recovery requires an explicit host resume through the shared preparation/delivery gate; this turn was not replayed.` };
             const otherRuntime = this.runtime === "claude" ? "codex" : "claude";
             const choice = this.opts.choose
                 ? await this.opts.choose(result, this.runtime, otherRuntime)