ai-foreman 1.7.18 → 1.7.19

package/dist/adapters/codex.js

@@ -1,3 +1,4 @@
+import { OperationDeadline } from "../util/deadline.js";
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
@@ -44,6 +45,7 @@ export class CodexAdapter {
     usage;
     usageRevision = 0;
     providerSessionUsage;
+    turnUsageBaseline;
     lastTurnTokens;
     stderr = "";
     nativeAutoCompactTokenLimit;
@@ -53,6 +55,9 @@ export class CodexAdapter {
     nativeCompactions = [];
     nativeCompactionSequence = 0;
     manualCompactionInFlight = false;
+    compactionPromise;
+    compactionActive = false;
+    compactionUncertain = false;
     observedToolCalls = 0;
     activeProviderTurnId;
     activeProviderTurnSpanId;
@@ -87,13 +92,13 @@ export class CodexAdapter {
         args.push(instruction);
         return args;
     }
-    async sendTurn(instruction) {
+    async sendTurn(instruction, policy) {
         const turnId = randomUUID();
         this.activeProviderTurnId = turnId;
         const observer = this.opts.observer;
         if (!observer) {
             try {
-                return await withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction));
+                return await withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction, policy));
             }
             finally {
                 this.activeProviderTurnId = undefined;
@@ -104,7 +109,7 @@ export class CodexAdapter {
         this.activeProviderTurnSpanId = spanId;
         observer.store.updateCurrentState({ runId: observer.runId, role: context.role ?? "host", stream: context.stream ?? "codex", executionId: observer.executionId, ticketId: context.ticketId, deliveryUnitId: context.deliveryUnitId, providerSessionId: context.providerSessionId, phase: "provider turn", activeSpanId: spanId, activeSpanKind: "provider_turn", lastSemanticProgressAt: new Date().toISOString() });
         try {
-            const result = await withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction));
+            const result = await withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction, policy));
             observer.store.finishSpan(spanId, { outcome: result.isError ? "failed" : "completed", attributes: { usage: result.usage } });
             return result;
         }
@@ -121,7 +126,7 @@ export class CodexAdapter {
             this.activeProviderTurnSpanId = undefined;
         }
     }
-    async sendTurnInternal(instruction) {
+    async sendTurnInternal(instruction, policy) {
         if (this.closed)
             throw new Error("builder is closed");
         this.eventQueue.push({ kind: "activity", state: "starting Codex turn", provider: "codex", model: this.opts.model });
@@ -129,8 +134,10 @@ export class CodexAdapter {
         const providerInstruction = this.buildInstruction(instruction);
         try {
             await this.ensureThread();
+            const toolsBefore = this.observedToolCalls;
             this.activeText = [];
             this.lastTurnTokens = undefined;
+            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", {
@@ -140,16 +147,17 @@ export class CodexAdapter {
                 model: this.opts.model ?? null,
                 effort: this.opts.effort ?? (this.opts.fast ? "low" : null),
             });
-            const params = await completion;
+            const params = await new OperationDeadline("Codex active turn", this.opts.turnDeadlineMs ?? 3_600_000).run(() => completion);
             const turn = params.turn;
-            const failed = turn?.status === "failed";
+            const responseOnlyViolation = Boolean(policy?.responseOnly && this.observedToolCalls !== toolsBefore);
+            const failed = turn?.status === "failed" || responseOnlyViolation;
             const error = turn?.error;
             const text = this.activeText.join("\n");
             const result = {
-                text: failed ? normalizeRuntimeErrorText("codex", String(error?.message ?? text), null, "app-server turn") : text,
+                text: failed ? normalizeRuntimeErrorText("codex", String(responseOnlyViolation ? "Response-only correction used tools; its result cannot authorize completion" : error?.message ?? text), null, "app-server turn") : text,
                 isError: failed, numTurns: 1, costUsd: 0, costAuthoritative: false,
                 turnId: this.activeProviderTurnId, hostInstruction: instruction, providerInstruction,
-                rawResponse: text, cleanedResponse: failed ? normalizeRuntimeErrorText("codex", String(error?.message ?? text), null, "app-server turn") : text,
+                rawResponse: text, cleanedResponse: failed ? normalizeRuntimeErrorText("codex", String(responseOnlyViolation ? "Response-only correction used tools; its result cannot authorize completion" : error?.message ?? text), null, "app-server turn") : text,
                 providerMetadata: { provider: "codex", sessionId: this._sessionId, sessionRef: this._sessionRef },
                 ...(this.lastTurnTokens ?? {}),
             };
@@ -181,7 +189,7 @@ export class CodexAdapter {
                     executable: this.opts.runtimeExecutable ?? "codex", cwd: this.opts.cwd, diagnostics: text,
                     availability: { version: 1, status: turnStartDispatched ? "unknown" : "unavailable", checkedAt: new Date().toISOString(), reason: turnStartDispatched ? "probe-failed" : "attach-failed", detail: text, sessionRef: this.opts.resumeSessionRef },
                 }))
-                : { text, isError: true, numTurns: 1, costUsd: 0, costAuthoritative: false };
+                : { text, isError: true, numTurns: 1, costUsd: 0, costAuthoritative: false, failure: { runtime: "codex", phase: turnStartDispatched ? "turn" : "attach", category: "agent-stream", executable: this.opts.runtimeExecutable ?? "codex", cwd: this.opts.cwd, diagnostics: text, dispatchState: turnStartDispatched ? "unknown" : "not-sent" } };
             this.eventQueue.push({ kind: "error", message: text });
             result.turnId = this.activeProviderTurnId;
             result.hostInstruction = instruction;
@@ -194,13 +202,36 @@ export class CodexAdapter {
         }
     }
     async compact() {
-        return this.opts.observer
+        if (this.compactionPromise)
+            return this.compactionPromise;
+        const operation = this.opts.observer
             ? this.opts.observer.span("compaction", "Codex context compaction", () => this.compactInternal())
             : this.compactInternal();
+        this.compactionPromise = operation;
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.compactionPromise === operation)
+                this.compactionPromise = undefined;
+        }
     }
     async compactInternal() {
+        if (this.compactionUncertain)
+            return { ok: false, error: "Prior compaction outcome is uncertain; validate a fresh successor before further work" };
+        if (this.compactionActive)
+            return { ok: false, error: "Compaction is already in progress for this session" };
+        if (this.manualCompactionInFlight)
+            return { ok: false, error: "Codex compaction already in flight" };
+        this.compactionActive = true;
+        const controller = new AbortController();
+        const began = performance.now();
+        const timeoutMs = Math.min(180_000, Math.max(1, this.opts.compactionTimeoutMs ?? 120_000));
+        const hardTimeoutMs = Math.min(180_000, timeoutMs * 1.5);
+        this.traceLifecycle("compaction-started", { timeoutMs });
+        const deadline = new OperationDeadline("Codex compaction", timeoutMs, hardTimeoutMs);
         try {
-            await this.ensureThread();
+            await deadline.run(() => this.ensureThread());
             this.eventQueue.push({ kind: "session-transition", transition: "compacting" });
             const usageRevision = this.usageRevision;
             // A pre-compaction observation must never be mistaken for proof that the
@@ -208,36 +239,71 @@ export class CodexAdapter {
             // usage notification for the compacted thread; require it alongside the
             // explicit contextCompaction completion item.
             this.usage = undefined;
+            let compactionItemId;
+            const progress = this.waitFor("item/started", params => {
+                const item = params.item;
+                if (params.threadId !== this._sessionId || item?.type !== "contextCompaction" || typeof item.id !== "string")
+                    return false;
+                compactionItemId = item.id;
+                deadline.extendForCorrelatedProgress();
+                this.traceLifecycle("compaction-deadline-extended", { timeoutMs: hardTimeoutMs });
+                return true;
+            }, hardTimeoutMs, false, controller.signal);
+            void progress.catch(() => { });
             const done = this.waitFor("item/completed", (params) => {
                 const item = params.item;
-                return params.threadId === this._sessionId && item?.type === "contextCompaction";
-            }, 30_000);
+                return params.threadId === this._sessionId && item?.type === "contextCompaction" && (!compactionItemId || item.id === compactionItemId);
+            }, hardTimeoutMs, false, controller.signal);
             const postCompactUsage = this.waitFor("thread/tokenUsage/updated", (params) => {
-                return (params.threadId === undefined || params.threadId === this._sessionId)
+                return params.threadId === this._sessionId
                     && this.usageRevision > usageRevision
                     && this.usage !== undefined;
-            }, 30_000);
+            }, hardTimeoutMs, false, controller.signal);
             this.manualCompactionInFlight = true;
             try {
-                await Promise.all([
-                    this.request("thread/compact/start", { threadId: this._sessionId }),
-                    done,
-                    postCompactUsage,
-                ]);
+                const acknowledgementFailure = this.request("thread/compact/start", { threadId: this._sessionId }).then(() => { this.traceLifecycle("compaction-acknowledged"); return new Promise(() => { }); }, error => {
+                    // A missing acknowledgement is not failure evidence. Explicit
+                    // completion plus fresh occupancy is sufficient to reconcile it.
+                    if (/deadline|timed out/i.test(String(error)))
+                        return new Promise(() => { });
+                    throw error;
+                });
+                await deadline.run(() => Promise.race([Promise.all([done, postCompactUsage]), acknowledgementFailure]));
             }
             finally {
                 this.manualCompactionInFlight = false;
             }
             this.eventQueue.push({ kind: "session-transition", transition: "compacted" });
+            this.traceLifecycle("compaction-completed", { elapsedMs: performance.now() - began });
             return { ok: true };
         }
         catch (error) {
             if (error instanceof SessionUnavailableError)
                 return { ok: false, error: error.message, failure: error.failure };
-            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+            this.compactionUncertain = true;
+            this.usage = undefined;
+            this.traceLifecycle("compaction-failed", { elapsedMs: performance.now() - began });
+            const detail = error instanceof Error ? error.message : String(error);
+            if (/deadline|timed out/i.test(detail)) {
+                // Waiting expired, not the provider operation. Quarantine this adapter;
+                // the host must reconcile it instead of automatically starting a writer.
+                const failure = new SessionUnavailableError({ runtime: "codex", phase: "turn", dispatchState: "unknown", executable: this.opts.runtimeExecutable ?? "codex", cwd: this.opts.cwd, diagnostics: detail });
+                this.closed = true;
+                this.disconnect(failure);
+                this.eventQueue.close();
+                return { ok: false, error: detail, failure: failure.failure };
+            }
+            return { ok: false, error: detail };
+        }
+        finally {
+            controller.abort();
+            this.compactionActive = false;
         }
     }
     async prepareAutoCompaction(thresholdPercent = this.opts.autoCompactThresholdPercent) {
+        return new OperationDeadline("Codex auto-compaction preparation", this.opts.preparationTimeoutMs ?? 120_000).run(() => this.prepareAutoCompactionInternal(thresholdPercent), () => this.disconnect(new Error("Codex preparation expired")));
+    }
+    async prepareAutoCompactionInternal(thresholdPercent = this.opts.autoCompactThresholdPercent) {
         if (thresholdPercent === undefined)
             return;
         const threshold = validThreshold(thresholdPercent);
@@ -334,15 +400,35 @@ export class CodexAdapter {
             return { version: 1, status: "unknown", checkedAt, reason: "probe-failed", detail: error instanceof Error ? error.message : String(error), sessionRef: this._sessionRef };
         }
     }
+    observeEvents(listener) { return this.eventQueue.observe(listener); }
     events() { return this.eventQueue; }
     async close() {
         if (this.closed)
             return;
         this.closed = true;
+        const child = this.process;
+        let onExit;
+        const exited = child && child.exitCode === null ? new Promise(resolve => { onExit = resolve; child.once("exit", resolve); }) : Promise.resolve();
         this.disconnect(new Error("app-server closed"));
         this.eventQueue.close();
+        try {
+            try {
+                await new OperationDeadline("Codex shutdown", this.opts.shutdownTimeoutMs ?? 10_000).run(() => exited);
+            }
+            catch {
+                child?.kill("SIGKILL");
+                await new OperationDeadline("Codex forced shutdown", 5_000).run(() => exited);
+            }
+        }
+        finally {
+            if (onExit)
+                child?.off("exit", onExit);
+        }
     }
     async ensureThread() {
+        return new OperationDeadline("Codex preparation", this.opts.preparationTimeoutMs ?? 120_000).run(() => this.ensureThreadInternal(), () => this.disconnect(new Error("Codex preparation deadline exceeded")));
+    }
+    async ensureThreadInternal() {
         if (this._sessionRef && !this.threadAttached) {
             if (this._sessionRef.source === "legacy-inferred") {
                 const availability = { version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped", detail: "legacy Codex thread IDs cannot be proven exact without an observed scoped binding", sessionRef: this._sessionRef };
@@ -463,7 +549,7 @@ export class CodexAdapter {
     }
     request(method, params) {
         const id = this.nextId++;
-        return new Promise((resolve, reject) => {
+        return new OperationDeadline(`Codex RPC ${method}`, this.opts.rpcTimeoutMs ?? 60_000).run(() => new Promise((resolve, reject) => {
             this.pending.set(id, { resolve, reject });
             try {
                 this.write({ id, method, params });
@@ -472,7 +558,7 @@ export class CodexAdapter {
                 this.pending.delete(id);
                 reject(error);
             }
-        });
+        }), () => { this.pending.delete(id); });
     }
     write(message) {
         if (!this.process?.stdin.writable)
@@ -566,7 +652,9 @@ export class CodexAdapter {
             const tokenUsage = params.tokenUsage;
             const total = tokenUsage?.total;
             const last = tokenUsage?.last;
-            const used = Number(total?.totalTokens);
+            if (this._sessionId && params.threadId !== this._sessionId)
+                return;
+            const used = optionalNonNegative(last?.totalTokens);
             const maximum = Number(tokenUsage?.modelContextWindow);
             const observedAt = new Date().toISOString();
             const totalInput = optionalNonNegative(total?.inputTokens);
@@ -575,11 +663,14 @@ export class CodexAdapter {
             if (totalInput !== undefined || totalOutput !== undefined || sessionTotal !== undefined) {
                 this.providerSessionUsage = { inputTokens: totalInput, outputTokens: totalOutput, totalTokens: sessionTotal, observedAt, source: "provider" };
             }
+            if ((totalInput !== undefined && this.turnUsageBaseline?.inputTokens !== undefined && totalInput < this.turnUsageBaseline.inputTokens) || (totalOutput !== undefined && this.turnUsageBaseline?.outputTokens !== undefined && totalOutput < this.turnUsageBaseline.outputTokens))
+                this.turnUsageBaseline = undefined;
             this.lastTurnTokens = {
-                inputTokens: optionalNonNegative(last?.inputTokens),
-                outputTokens: optionalNonNegative(last?.outputTokens),
+                inputTokens: cumulativeDelta(this.turnUsageBaseline?.inputTokens, totalInput),
+                outputTokens: cumulativeDelta(this.turnUsageBaseline?.outputTokens, totalOutput),
             };
-            if (Number.isFinite(used) && used >= 0 && Number.isFinite(maximum) && maximum > 0) {
+            this.usage = undefined;
+            if (used !== undefined && Number.isFinite(maximum) && maximum > 0) {
                 this.usage = { used, maximum, percentage: used / maximum * 100, observedAt, source: "provider-event" };
                 this.usageRevision += 1;
                 this.eventQueue.push({ kind: "context-usage", ...this.usage });
@@ -617,16 +708,29 @@ export class CodexAdapter {
             ticketId: this.opts.ticketId ?? inherited.ticketId, deliveryUnitId: this.opts.deliveryUnitId ?? inherited.deliveryUnitId,
             parentSpanId: this.activeProviderTurnSpanId ?? inherited.parentSpanId, providerTurnId: this.activeProviderTurnId ?? inherited.providerTurnId };
     }
-    waitFor(method, predicate, timeoutMs, resetOnProviderActivity = false) {
+    waitFor(method, predicate, timeoutMs, resetOnProviderActivity = false, signal) {
         return new Promise((resolve, reject) => {
             let timeout;
+            const began = performance.now();
             const clear = () => { if (timeout)
-                clearTimeout(timeout); timeout = undefined; };
+                clearTimeout(timeout); timeout = undefined; signal?.removeEventListener("abort", abort); };
             const waiter = {
                 predicate,
-                resolve: (params) => { clear(); resolve(params); },
+                resolve: (params) => { clear(); this.traceLifecycle("waiter-completed", { method, elapsedMs: performance.now() - began }); resolve(params); },
                 reject: (error) => { clear(); reject(error); },
             };
+            const abort = () => {
+                this.notificationWaiters.set(method, (this.notificationWaiters.get(method) ?? []).filter(candidate => candidate !== waiter));
+                clear();
+                this.traceLifecycle("waiter-cancelled", { method });
+                reject(new Error(`Codex waiter cancelled: ${method}`));
+            };
+            if (signal?.aborted) {
+                abort();
+                return;
+            }
+            signal?.addEventListener("abort", abort, { once: true });
+            this.traceLifecycle("waiter-registered", { method, timeoutMs });
             const waiters = this.notificationWaiters.get(method) ?? [];
             waiters.push(waiter);
             this.notificationWaiters.set(method, waiters);
@@ -635,7 +739,9 @@ export class CodexAdapter {
                     timeout = setTimeout(() => {
                         const active = this.notificationWaiters.get(method) ?? [];
                         this.notificationWaiters.set(method, active.filter((candidate) => candidate !== waiter));
-                        reject(new Error(`Codex provider was silent for ${Math.round(timeoutMs / 60_000)} minutes while waiting for ${method}; the turn may have been dispatched and will not be retried automatically`));
+                        clear();
+                        this.traceLifecycle("waiter-timeout", { method, timeoutMs, elapsedMs: performance.now() - began });
+                        reject(new Error(`Codex provider wait timed out after ${timeoutMs} ms while waiting for ${method}; the turn may have been dispatched and will not be retried automatically`));
                     }, timeoutMs);
                 };
                 if (resetOnProviderActivity)
@@ -644,6 +750,12 @@ export class CodexAdapter {
             }
         });
     }
+    traceLifecycle(phase, data = {}) {
+        try {
+            this.opts.onLifecycleTrace?.({ phase, at: new Date().toISOString(), sessionId: this._sessionId, ...data });
+        }
+        catch { /* diagnostics cannot change execution */ }
+    }
     touchWaiters() {
         for (const waiters of this.notificationWaiters.values())
             for (const waiter of waiters)
@@ -689,6 +801,8 @@ export class CodexAdapter {
     }
 }
 function optionalNonNegative(value) {
+    if (value === null || value === undefined || value === "")
+        return undefined;
     const number = Number(value);
     return Number.isFinite(number) && number >= 0 ? number : undefined;
 }
@@ -759,3 +873,6 @@ function loadSkillMarkdown(cwd, skill) {
         return undefined;
     }
 }
+function cumulativeDelta(before, after) {
+    return before !== undefined && after !== undefined && after >= before ? after - before : undefined;
+}

package/dist/adapters/recovering.d.ts

@@ -25,7 +25,7 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     private closed;
     constructor(opts: RecoveringAdapterOptions);
     get agent(): "claude" | "codex";
-    sendTurn(text: string): Promise<TurnResult>;
+    sendTurn(text: string, policy?: Parameters<BuilderAdapter["sendTurn"]>[1]): Promise<TurnResult>;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;
     prepareSession(): Promise<ProviderSessionRefV1>;
@@ -41,6 +41,8 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     contextUsage(): Promise<ContextUsage | undefined>;
     sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     events(): AsyncIterable<BuilderEvent>;
+    observeEvents(listener: (event: BuilderEvent) => void): () => void;
+    acceptHandbackTurn(turn: TurnResult): void;
     close(): Promise<void>;
     private replaceAdapter;
     private forwardEvents;

package/dist/adapters/recovering.js

@@ -19,9 +19,9 @@ export class RecoveringAdapter {
     get agent() {
         return this.adapter.agent;
     }
-    async sendTurn(text) {
+    async sendTurn(text, policy) {
         while (true) {
-            const result = await this.adapter.sendTurn(text);
+            const result = await this.adapter.sendTurn(text, policy);
             const sessionRef = this.adapter.sessionRef?.();
             if (sessionRef && this.opts.onSessionRef) {
                 try {
@@ -31,11 +31,11 @@ export class RecoveringAdapter {
                     this.eventQueue.push({ kind: "error", message: `failed to persist scoped provider session binding: ${error instanceof Error ? error.message : String(error)}` });
                 }
             }
-            if (!this.opts.enabled || !result.isError || !result.failure)
+            if (policy?.handback || !this.opts.enabled || !result.isError || !result.failure)
                 return result;
             // The host cannot know whether a missing exact session received this
             // instruction. Never replay it or silently switch providers.
-            if (result.failure.category === "session-unavailable")
+            if (result.failure.category === "session-unavailable" || result.failure.dispatchState === "unknown")
                 return result;
             const otherRuntime = this.runtime === "claude" ? "codex" : "claude";
             const choice = this.opts.choose
@@ -93,6 +93,14 @@ export class RecoveringAdapter {
     events() {
         return this.eventQueue;
     }
+    observeEvents(listener) {
+        if (!this.adapter.observeEvents)
+            throw new Error("wrapped provider does not expose turn observation");
+        // Observe synchronously at the provider, before sendTurn resolves. The async
+        // display pump may still have buffered events when the journal unsubscribes.
+        return this.adapter.observeEvents(listener);
+    }
+    acceptHandbackTurn(turn) { this.adapter.acceptHandbackTurn?.(turn); }
     async close() {
         if (this.closed)
             return;

package/dist/adapters/types.d.ts

@@ -70,6 +70,8 @@ export interface TurnResult {
     failure?: RuntimeFailure;
     /** Stable host/provider correlation ID for this turn. */
     turnId?: string;
+    /** Deferred handback continuity validation; no hidden provider repair. */
+    continuityErrors?: string[];
     /** Exact instruction requested by the immediate host caller. */
     hostInstruction?: string;
     /** Exact instruction dispatched to the provider after all wrappers. */
@@ -246,6 +248,8 @@ export interface BuilderAdapterOptions {
     allowAutoCompactionSetupTurn?: boolean;
     /** Raw-adapter observability; wrapper adapters must not persist re-emitted events. */
     observer?: RunObserver;
+    /** Redacted AskUserQuestion diagnostics, independent of build observability. */
+    onQuestionTrace?: import("../questionTrace.js").QuestionTraceSink;
     /**
      * Maximum time a dispatched provider turn may remain completely silent.
      * This is an idle timeout, not a total turn limit: every provider message
@@ -253,11 +257,33 @@ export interface BuilderAdapterOptions {
      * state, so callers must never replay the instruction automatically.
      */
     providerIdleTimeoutMs?: number;
+    compactionTimeoutMs?: number;
+    preparationTimeoutMs?: number;
+    rpcTimeoutMs?: number;
+    turnDeadlineMs?: number;
+    shutdownTimeoutMs?: number;
+    /** Metadata-only lifecycle trace; no prompts, responses, credentials, or tool inputs. */
+    onLifecycleTrace?: (event: {
+        phase: string;
+        at: string;
+        elapsedMs?: number;
+        sessionId?: string;
+        method?: string;
+        timeoutMs?: number;
+    }) => void;
 }
 export interface BuilderAdapter {
     readonly agent: "claude" | "codex";
     /** Send one instruction; resolves when that turn completes. */
-    sendTurn(text: string): Promise<TurnResult>;
+    sendTurn(text: string, policy?: {
+        handback?: boolean;
+        responseOnly?: boolean;
+        logicalActionId?: string;
+    }): Promise<TurnResult>;
+    /** Synchronous observation through the event owner. Terminal precedes sendTurn resolution. */
+    observeEvents?(listener: (event: BuilderEvent) => void): () => void;
+    /** Commit a deferred handback checkpoint only after the host validates the turn. */
+    acceptHandbackTurn?(turn: TurnResult): void;
     /** Current session id, once known — used for resume. */
     sessionId(): string | undefined;
     /** Current location-scoped session reference, once known. */

package/dist/agentRun.js

@@ -178,6 +178,8 @@ export async function createRoleBuilder(opts) {
             configRoot: opts.projectDir,
             runtimeExecutable,
             runtimePhase: phaseForRole(opts.role),
+            onQuestionTrace: (trace) => log.write("question-round-trip", { ...trace }),
+            onLifecycleTrace: (trace) => log.write("provider-lifecycle", { ...trace, role: opts.role }),
             model,
             ...(scopedRef ? { resumeSessionRef: scopedRef } : {}),
             sessionRole: configurableRole(opts.role),

package/dist/branch/currentGuard.d.ts

@@ -20,7 +20,7 @@ export declare class CurrentWorkflowGuardAdapter implements BuilderAdapter {
     private readonly expected;
     readonly agent: BuilderAdapter["agent"];
     constructor(adapter: BuilderAdapter, cwd: string, expected?: CurrentWorkflowIdentity);
-    sendTurn(text: string): Promise<TurnResult>;
+    sendTurn(text: string, policy?: Parameters<BuilderAdapter["sendTurn"]>[1]): Promise<TurnResult>;
     sessionId(): string | undefined;
     sessionRef(): ProviderSessionRefV1 | undefined;
     prepareSession(): Promise<ProviderSessionRefV1>;
@@ -37,5 +37,7 @@ export declare class CurrentWorkflowGuardAdapter implements BuilderAdapter {
     sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     events(): AsyncIterable<BuilderEvent>;
+    observeEvents(listener: (event: BuilderEvent) => void): () => void;
+    acceptHandbackTurn(turn: TurnResult): void;
     close(): Promise<void>;
 }

package/dist/branch/currentGuard.js

@@ -37,9 +37,9 @@ export class CurrentWorkflowGuardAdapter {
         this.expected = expected;
         this.agent = adapter.agent;
     }
-    async sendTurn(text) {
+    async sendTurn(text, policy) {
         assertCurrentWorkflowIdentity(this.cwd, this.expected);
-        const result = await this.adapter.sendTurn(text);
+        const result = await this.adapter.sendTurn(text, policy);
         assertCurrentWorkflowIdentity(this.cwd, this.expected);
         return result;
     }
@@ -66,6 +66,15 @@ export class CurrentWorkflowGuardAdapter {
     sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
     switchSettings(settings) { return this.adapter.switchSettings?.(settings) ?? Promise.resolve({ ok: false, error: "settings switch unavailable" }); }
     events() { return this.adapter.events(); }
+    observeEvents(listener) {
+        if (!this.adapter.observeEvents)
+            throw new Error("wrapped provider does not expose turn observation");
+        return this.adapter.observeEvents(listener);
+    }
+    acceptHandbackTurn(turn) {
+        assertCurrentWorkflowIdentity(this.cwd, this.expected);
+        this.adapter.acceptHandbackTurn?.(turn);
+    }
     close() { return this.adapter.close(); }
 }
 function currentRef(cwd) {

package/dist/branch/resume.js

@@ -7,7 +7,7 @@ export function findResumableBranchSessions(foremanDir) {
     const reader = new WorkflowReader(dirname(foremanDir));
     try {
         const structured = reader.branchResumeSessions().filter(session => existsSync(session.worktreePath));
-        if (structured.length)
+        if (structured.length || reader.branchResumeSessions(false).length || reader.buildRuns().length)
             return structured.sort((a, b) => a.ticket.localeCompare(b.ticket, undefined, { numeric: true }));
     }
     finally {

package/dist/branch/runner.d.ts

@@ -8,6 +8,7 @@ import { SessionUnavailableError } from "../adapters/sessionFailure.js";
 import { SessionUnavailableContinuityError } from "../continuity.js";
 import type { QaRecoveryPacket } from "../qaRecovery.js";
 export interface DeliveryUnitSession {
+    runId?: string;
     unitId: string;
     branch: string;
     worktreePath: string;
@@ -18,6 +19,7 @@ export interface DeliveryUnitSession {
 export type BaseWorktreePolicy = "enforce" | "warn" | "skip";
 export declare function readDeliveryUnitSession(projectDir: string, unitId: string): DeliveryUnitSession | undefined;
 export interface BranchRunnerOptions {
+    continueIndependentTickets?: boolean;
     projectDir: string;
     runId: string;
     plan: BranchPlan;