ai-foreman 1.7.13 → 1.7.15

package/README.md

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

package/dist/adapters/claude.d.ts

@@ -50,6 +50,9 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private readonly pumpDone;
     private _sessionId?;
     private _sessionRef?;
+    private readonly sessionIdentityReady;
+    private resolveSessionIdentity;
+    private rejectSessionIdentity;
     private readonly stderrChunks;
     private turnSignals;
     private structuredError?;
@@ -82,6 +85,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private observeToolResults;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;
+    prepareSession(timeoutMs?: number): Promise<ProviderSessionRefV1>;
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
@@ -95,6 +99,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
+    private failSessionIdentity;
     private observeSession;
     private settlePending;
     private streamFailureResult;

package/dist/adapters/claude.js

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export async function requireClaudeSDK() {
     try {
@@ -22,25 +23,42 @@ import { SessionUnavailableError, sessionUnavailableResult } from "./sessionFail
  * `canUseTool` is omitted here — it's a closure that the constructor adds.
  */
 export function buildClaudeQueryOptions(opts) {
+    const qaReadOnly = opts.sessionRole === "qa" || opts.sandboxMode === "read-only";
     const base = {
         cwd: opts.cwd,
         pathToClaudeCodeExecutable: opts.runtimeExecutable,
-        env: { ...process.env },
+        env: qaReadOnly ? qaEnvironment(process.env, opts.cwd) : { ...process.env },
         model: opts.model,
         resume: opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId,
-        permissionMode: "acceptEdits",
+        permissionMode: qaReadOnly ? "default" : "acceptEdits",
         effort: opts.effort,
         extraArgs: opts.fast ? { fast: null } : undefined,
-        settingSources: ["user", "project", "local"],
+        settingSources: qaReadOnly ? [] : ["user", "project", "local"],
+        ...(qaReadOnly ? { disallowedTools: ["Write", "Edit", "NotebookEdit"] } : {}),
+        ...(qaReadOnly ? { sandbox: {
+                enabled: true,
+                failIfUnavailable: true,
+                autoAllowBashIfSandboxed: true,
+                allowUnsandboxedCommands: false,
+                filesystem: { allowWrite: [join(dirname(opts.cwd), "scratch")], denyWrite: [opts.cwd, ...(opts.configRoot ? [opts.configRoot] : [])] },
+            } } : {}),
     };
-    if (opts.systemPromptAppend) {
-        base.systemPrompt = { type: "preset", preset: "claude_code", append: opts.systemPromptAppend };
+    const exactSkills = opts.preloadedSkillContent?.length
+        ? ["# Preloaded Skills", "Use the following skills for this run.", ...opts.preloadedSkillContent.map((skill) => skill.content)].join("\n\n")
+        : undefined;
+    const systemAppend = [opts.systemPromptAppend, exactSkills].filter((part) => Boolean(part)).join("\n\n");
+    if (systemAppend) {
+        base.systemPrompt = { type: "preset", preset: "claude_code", append: systemAppend };
     }
     if (opts.skills !== undefined) {
         base.skills = opts.skills;
     }
     return base;
 }
+function qaEnvironment(source, cwd) {
+    const allowed = ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "TMPDIR", "LANG", "LC_ALL", "TERM", "NO_COLOR", "FORCE_COLOR", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY", "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS"];
+    return { ...Object.fromEntries(allowed.flatMap((key) => source[key] === undefined ? [] : [[key, source[key]]])), TMPDIR: join(dirname(cwd), "scratch") };
+}
 export async function probeClaudeSession(ref, input) {
     const now = input.now ?? new Date();
     const local = validateProviderSessionScope(ref, {
@@ -148,6 +166,9 @@ export class ClaudeAdapter {
     pumpDone;
     _sessionId;
     _sessionRef;
+    sessionIdentityReady;
+    resolveSessionIdentity;
+    rejectSessionIdentity;
     stderrChunks = [];
     turnSignals = [];
     structuredError;
@@ -210,11 +231,28 @@ export class ClaudeAdapter {
         this.opts = opts;
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
         this._sessionRef = opts.resumeSessionRef;
+        this.sessionIdentityReady = new Promise((resolve, reject) => {
+            this.resolveSessionIdentity = resolve;
+            this.rejectSessionIdentity = reject;
+        });
+        void this.sessionIdentityReady.catch(() => { });
         this.query = query({
             prompt: this.inbox,
             options: {
                 ...buildClaudeQueryOptions(opts),
                 abortController: this.abort,
+                hooks: { SessionStart: [{ hooks: [async (input) => {
+                                    if (input.hook_event_name !== "SessionStart" || input.agent_id)
+                                        return {};
+                                    try {
+                                        this.observeSession(input.session_id, input.cwd);
+                                    }
+                                    catch (error) {
+                                        this.failSessionIdentity(error instanceof Error ? error : new Error(String(error)));
+                                        throw error;
+                                    }
+                                    return {};
+                                }] }] },
                 stderr: (data) => this.captureStderr(data),
                 canUseTool: async (toolName, input, requestOptions = {}) => {
                     const decision = await opts.permission({
@@ -251,6 +289,7 @@ export class ClaudeAdapter {
                 const message = normalizeRuntimeErrorText("claude", rawMessage, null, "builder stream");
                 this.eventQueue.push({ kind: "error", message });
                 const result = this.streamFailureResult(message, isMissingClaudeSession(rawMessage));
+                this.rejectSessionIdentity(new Error(message));
                 this.terminalResult = result;
                 this.settlePending(result);
             }
@@ -265,13 +304,14 @@ export class ClaudeAdapter {
             }
             if (!this.closed && !this.terminalResult)
                 this.terminalResult = this.streamFailureResult("Claude stream ended without a result", Boolean(this.opts.resumeSessionRef ?? this.opts.resumeSessionId));
+            if (!this._sessionRef)
+                this.rejectSessionIdentity(new Error("Claude stream ended before exposing a scoped session identity"));
             this.eventQueue.close();
         }
     }
     handle(msg) {
         if ("session_id" in msg && typeof msg.session_id === "string") {
-            this._sessionId = msg.session_id;
-            this.observeSession(msg.session_id);
+            this.observeSession(msg.session_id, "cwd" in msg && typeof msg.cwd === "string" ? msg.cwd : undefined);
         }
         if (msg.type === "assistant") {
             if (msg.error) {
@@ -279,6 +319,7 @@ export class ClaudeAdapter {
                 this.turnSignals.push(`assistant error: ${msg.error}`);
             }
             for (const block of msg.message.content) {
+                this.eventQueue.push({ kind: "provider-item", provider: "claude", lifecycle: "completed", itemType: String(block.type ?? "unknown"), payload: structuredClone(block), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
                 if (block.type === "text" && block.text) {
                     this.eventQueue.push({ kind: "text", text: block.text, byteCount: Buffer.byteLength(block.text), digest: createHash("sha256").update(block.text).digest("hex"), eventId: randomUUID(), observedAt: new Date().toISOString() });
                     this.opts.observer?.signal(true);
@@ -497,6 +538,7 @@ export class ClaudeAdapter {
         for (const block of body.content) {
             if (block.type !== "tool_result")
                 continue;
+            this.eventQueue.push({ kind: "provider-item", provider: "claude", lifecycle: "completed", itemType: "tool_result", payload: structuredClone(block), payloadCompleteness: "complete", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
             const callId = typeof block.tool_use_id === "string" ? block.tool_use_id : undefined;
             if (!callId)
                 continue;
@@ -517,6 +559,37 @@ export class ClaudeAdapter {
         return this._sessionId;
     }
     sessionRef() { return this._sessionRef; }
+    async prepareSession(timeoutMs = 30_000) {
+        if (this.closed || this.streamEnded || this.terminalResult)
+            throw new Error(this.terminalResult?.text ?? "Claude session is closed");
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new Error("Claude session initialization timeout must be positive");
+        let timer;
+        let aborted;
+        try {
+            const interrupted = new Promise((_resolve, reject) => {
+                aborted = () => reject(new Error(this.terminalResult?.text ?? "Claude session closed during initialization"));
+                this.abort.signal.addEventListener("abort", aborted, { once: true });
+                if (this.abort.signal.aborted)
+                    aborted();
+                timer = setTimeout(() => reject(new Error(`Claude did not expose a scoped session identity within ${timeoutMs}ms`)), timeoutMs);
+            });
+            const [, ref] = await Promise.race([Promise.all([this.query.initializationResult(), this.sessionIdentityReady]), interrupted]);
+            if (!ref.validatedAt)
+                throw new Error("Claude session identity was not provider-validated during initialization");
+            return ref;
+        }
+        catch (error) {
+            this.failSessionIdentity(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            if (aborted)
+                this.abort.signal.removeEventListener("abort", aborted);
+        }
+    }
     adoptSessionRef(ref) {
         if (ref.provider !== "claude" || ref.sessionId !== this._sessionId)
             throw new Error("cannot adopt a session reference for a different Claude conversation");
@@ -639,6 +712,8 @@ export class ClaudeAdapter {
         if (this.closed)
             return;
         this.closed = true;
+        this.rejectSessionIdentity(new Error("Claude session closed during initialization"));
+        this.abort.abort();
         this.inbox.close();
         try {
             await this.query.interrupt();
@@ -646,18 +721,49 @@ export class ClaudeAdapter {
         catch {
             // interrupt is best-effort — ignore if no turn is active
         }
-        this.abort.abort();
         await this.pumpDone.catch(() => { });
     }
-    observeSession(sessionId) {
-        if (this._sessionRef?.sessionId === sessionId)
+    failSessionIdentity(error) {
+        this.rejectSessionIdentity(error);
+        const result = sessionUnavailableResult(new SessionUnavailableError({
+            runtime: "claude", phase: this.pending ? "turn" : "preflight", dispatchState: this.pending ? "unknown" : "not-sent",
+            executable: this.opts.runtimeExecutable ?? "claude", cwd: this.opts.cwd, diagnostics: error.message,
+            availability: { version: 1, status: "unavailable", checkedAt: new Date().toISOString(), reason: "attach-failed", detail: error.message, ...(this._sessionRef ? { sessionRef: this._sessionRef } : {}) },
+        }));
+        this.terminalResult = result;
+        this.settlePending(result);
+        this.inbox.close();
+        this.abort.abort();
+    }
+    observeSession(sessionId, observedCwd) {
+        const expectedId = this._sessionRef?.sessionId ?? this._sessionId;
+        if (!sessionId.trim() || (expectedId && expectedId !== sessionId)) {
+            const error = new Error(`Claude initialized session ${sessionId || "without an ID"} instead of requested session ${expectedId ?? "a nonempty ID"}`);
+            this.failSessionIdentity(error);
+            throw error;
+        }
+        if (observedCwd !== undefined && canonicalSessionPath(observedCwd) !== canonicalSessionPath(this.opts.cwd)) {
+            const error = new Error(`Claude session cwd ${observedCwd} does not match ${this.opts.cwd}`);
+            this.failSessionIdentity(error);
+            throw error;
+        }
+        this._sessionId = sessionId;
+        if (this._sessionRef?.validatedAt) {
+            this.resolveSessionIdentity(this._sessionRef);
             return;
-        this._sessionRef = createProviderSessionRef({
-            provider: "claude", sessionId, cwd: this.opts.cwd, configRoot: this.opts.configRoot ?? this.opts.cwd,
-            role: this.opts.sessionRole, stream: this.opts.sessionStream, generation: this.opts.sessionGeneration,
-            workspaceIdentity: this.opts.workspaceIdentity, ticketId: this.opts.ticketId, deliveryUnitId: this.opts.deliveryUnitId,
-            source: "observed",
-        });
+        }
+        const now = new Date().toISOString();
+        const validatedAt = observedCwd !== undefined || this.opts.sessionRole !== "qa" ? now : undefined;
+        this._sessionRef = this._sessionRef
+            ? { ...this._sessionRef, source: "observed", ...(validatedAt ? { validatedAt } : {}) }
+            : createProviderSessionRef({
+                provider: "claude", sessionId, cwd: this.opts.cwd, configRoot: this.opts.configRoot ?? this.opts.cwd,
+                role: this.opts.sessionRole, stream: this.opts.sessionStream, generation: this.opts.sessionGeneration,
+                workspaceIdentity: this.opts.workspaceIdentity, ticketId: this.opts.ticketId, deliveryUnitId: this.opts.deliveryUnitId,
+                source: "observed", validatedAt,
+            });
+        if (this._sessionRef.validatedAt)
+            this.resolveSessionIdentity(this._sessionRef);
     }
     settlePending(result, emit = true) {
         const pending = this.pending;
@@ -721,6 +827,8 @@ function activityPhase(phase) {
         return "planning uninstall";
     if (phase === "manager")
         return "analyzing diagnostics";
+    if (phase === "discovery")
+        return "discovering project context";
     return "building";
 }
 function formatClaudeFailure(failure) {

package/dist/adapters/codex.d.ts

@@ -48,6 +48,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     compact(): Promise<CompactResult>;
     private compactInternal;
     prepareAutoCompaction(thresholdPercent?: number | undefined): Promise<NativeAutoCompactionPolicy | void>;
+    requiresAutoCompactionSetupTurn(): boolean;
     autoCompactionPolicy(): NativeAutoCompactionPolicy | undefined;
     drainNativeCompactions(): NativeCompaction[];
     restoreNativeCompactions(compactions: NativeCompaction[]): void;
@@ -57,6 +58,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;
+    prepareSession(): Promise<ProviderSessionRefV1>;
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<SessionAvailabilityV1>;
     events(): AsyncIterable<BuilderEvent>;

package/dist/adapters/codex.js

@@ -248,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)
@@ -272,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;
@@ -300,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");
@@ -395,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 {
@@ -476,6 +491,8 @@ export class CodexAdapter {
         const params = message.params ?? {};
         if (message.method === "item/started") {
             const item = params.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();
@@ -493,6 +510,8 @@ export class CodexAdapter {
         }
         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;
@@ -643,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));
@@ -672,6 +694,8 @@ function activityPhase(phase) {
         return "planning uninstall";
     if (phase === "manager")
         return "analyzing diagnostics";
+    if (phase === "discovery")
+        return "discovering project context";
     return "building";
 }
 function codexItemActivity(item, completed = false) {
@@ -699,16 +723,16 @@ function isCodexToolItem(item) {
 }
 function codexItemId(item) { const value = item?.id ?? item?.itemId ?? item?.callId; return typeof value === "string" && value ? value : undefined; }
 function codexToolName(item) { return String(item?.tool ?? item?.name ?? item?.type ?? "tool"); }
-function exactToolInput(item) { if (!item)
-    return {}; return Object.fromEntries(Object.entries(item).filter(([key]) => ["command", "tool", "name", "type", "path", "query", "arguments", "input"].includes(key))); }
+function 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

@@ -28,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

@@ -72,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

@@ -106,6 +106,14 @@ export type BuilderEvent = ({
     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;
@@ -227,8 +235,15 @@ 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;
 }
@@ -240,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. */
@@ -252,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.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 ",
@@ -244,6 +262,8 @@ function phaseForRole(role) {
         return "uninstaller";
     if (role === "manager")
         return "manager";
+    if (role === "discovery")
+        return "discovery";
     return "builder";
 }
 export function readRoleDefaultsForExecution(projectDir, role) {
@@ -339,7 +359,7 @@ export async function runRoleInstruction(opts) {
     }
 }
 function configurableRole(role) {
-    return ["builder", "qa", "planner", "ticket-maker", "uninstaller", "manager"].includes(role)
+    return ["builder", "qa", "planner", "ticket-maker", "uninstaller", "manager", "discovery"].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;