ai-foreman 1.7.6 → 1.7.8

package/dist/continuity.js

@@ -0,0 +1,415 @@
+import { createHash } from "node:crypto";
+import { BuilderEventQueue } from "./activity.js";
+import { WorkflowDb } from "./workflowDb.js";
+export const CONTINUITY_MARKER = "RAFI_CONTINUITY_DELTA:";
+export class ContinuityValidationError extends Error {
+    problems;
+    constructor(problems) {
+        super(`invalid continuity delta: ${problems.join("; ")}`);
+        this.problems = problems;
+    }
+}
+export class ContinuityRecoveryRequiredError extends Error {
+    runId;
+    role;
+    constructor(runId, role, message) {
+        super(`${message}; run rafi build:resume --run ${runId} --guided-recovery in a TTY`);
+        this.runId = runId;
+        this.role = role;
+    }
+}
+/**
+ * Exact-session loss is a host recovery boundary, never a continuity-repair
+ * prompt. `guidedRecovery` is true when the provider may already have received
+ * the frozen instruction, so a fresh successor must reconcile receipts first.
+ */
+export class SessionUnavailableContinuityError extends Error {
+    runId;
+    role;
+    failure;
+    guidedRecovery;
+    constructor(runId, role, failure) {
+        const guidedRecovery = failure.dispatchState === "unknown";
+        super(guidedRecovery
+            ? `the exact ${role} session became unavailable after dispatch may have begun; run rafi build:resume --run ${runId} --guided-recovery in a TTY`
+            : `the exact ${role} session is unavailable before dispatch; inspect run ${runId} and choose fresh-with-handoff recovery`);
+        this.runId = runId;
+        this.role = role;
+        this.failure = failure;
+        this.name = "SessionUnavailableContinuityError";
+        this.guidedRecovery = guidedRecovery;
+    }
+}
+export function validateContinuityDelta(value) {
+    const problems = [];
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new ContinuityValidationError(["delta must be an object"]);
+    const input = value;
+    if (input.version !== 1)
+        problems.push("version must be 1");
+    const output = {
+        version: 1,
+        decisions: strings(input.decisions, "decisions", problems),
+        constraints: strings(input.constraints, "constraints", problems),
+        discoveries: strings(input.discoveries, "discoveries", problems),
+        completedActions: strings(input.completedActions, "completedActions", problems),
+        evidence: strings(input.evidence, "evidence", problems),
+        failures: strings(input.failures, "failures", problems),
+        blockers: strings(input.blockers, "blockers", problems),
+        openWork: strings(input.openWork, "openWork", problems),
+        nextAction: typeof input.nextAction === "string" ? clean(input.nextAction, 4_000) : "",
+    };
+    if (!output.nextAction)
+        problems.push("nextAction must be a non-empty string");
+    if (JSON.stringify(output).length > 64_000)
+        problems.push("delta exceeds 64 KiB");
+    if (problems.length)
+        throw new ContinuityValidationError(problems);
+    return output;
+}
+export function parseContinuityDelta(text) {
+    const lines = text.split(/\r?\n/);
+    const markerIndexes = lines.flatMap((line, index) => line.trimStart().startsWith(CONTINUITY_MARKER) ? [index] : []);
+    const cleanText = lines.filter((_line, index) => !markerIndexes.includes(index)).join("\n").trimEnd();
+    if (markerIndexes.length !== 1)
+        return { cleanText, error: new ContinuityValidationError([markerIndexes.length ? "multiple continuity markers" : "missing continuity marker"]) };
+    const raw = lines[markerIndexes[0]].trimStart().slice(CONTINUITY_MARKER.length).trim();
+    try {
+        return { delta: validateContinuityDelta(JSON.parse(raw)), cleanText };
+    }
+    catch (error) {
+        return { cleanText, error: error instanceof ContinuityValidationError ? error : new ContinuityValidationError([`marker is not valid JSON: ${String(error)}`]) };
+    }
+}
+export function mergeContinuityDeltas(deltas) {
+    const result = baselineContinuityDelta();
+    for (const delta of deltas) {
+        for (const key of ["decisions", "constraints", "discoveries", "completedActions", "evidence", "failures", "blockers", "openWork"]) {
+            result[key] = unique([...result[key], ...delta[key]]).slice(-500);
+        }
+        if (delta.nextAction)
+            result.nextAction = delta.nextAction;
+    }
+    return result;
+}
+export function baselineContinuityDelta(nextAction = "Await the first role action.") {
+    return { version: 1, decisions: [], constraints: [], discoveries: [], completedActions: [], evidence: [], failures: [], blockers: [], openWork: [], nextAction };
+}
+export function continuityInstruction() {
+    return [
+        "Before your final STEP_STATUS line (or as the final line when STEP_STATUS is not requested), emit exactly one single-line continuity record:",
+        `${CONTINUITY_MARKER} {"version":1,"decisions":[],"constraints":[],"discoveries":[],"completedActions":[],"evidence":[],"failures":[],"blockers":[],"openWork":[],"nextAction":"specific next action"}`,
+        "Keep it concise and cumulative for facts learned this turn. Do not include credentials, hidden reasoning, or raw transcripts.",
+    ].join("\n");
+}
+/** Enforces a durable role checkpoint after every completed provider turn. */
+export class ContinuityAdapter {
+    options;
+    adapter;
+    queue = new BuilderEventQueue();
+    sourcePump;
+    recoveryLeasePending;
+    turnDispatcher;
+    constructor(options) {
+        this.options = options;
+        this.adapter = options.adapter;
+        this.recoveryLeasePending = Boolean(options.replaceRecoveryLeaseAfterCheckpoint);
+        const db = new WorkflowDb(options.projectDir);
+        try {
+            db.ensureRun(options.runId);
+            if (!db.continuityHead(options.runId, options.role)) {
+                db.appendContinuityEvent({ runId: options.runId, role: "host", kind: "role_baseline", payload: { role: options.role, provider: options.settings.make, model: options.settings.model }, authoritativeStateRevision: this.revision() });
+                db.publishContinuityCheckpoint({ runId: options.runId, role: options.role, delta: baselineContinuityDelta(), authoritativeStateRevision: this.revision() });
+            }
+            const initialSession = options.adapter.sessionRef?.() ?? options.adapter.sessionId();
+            if (initialSession)
+                db.claimInitialRoleLease(options.runId, options.role, initialSession);
+        }
+        finally {
+            db.close();
+        }
+        this.pumpEvents();
+    }
+    get agent() { return this.adapter.agent; }
+    async sendTurn(instruction) {
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            db.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "turn_started", payload: { role: this.options.role, instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) }, authoritativeStateRevision: this.revision() });
+        }
+        finally {
+            db.close();
+        }
+        const original = await this.providerTurn(`${instruction}\n\n${continuityInstruction()}`);
+        const activeSession = this.adapter.sessionRef?.() ?? this.adapter.sessionId();
+        if (activeSession) {
+            const leaseDb = new WorkflowDb(this.options.projectDir);
+            try {
+                leaseDb.claimInitialRoleLease(this.options.runId, this.options.role, activeSession);
+            }
+            finally {
+                leaseDb.close();
+            }
+        }
+        if (original.failure?.category === "session-unavailable") {
+            this.recordSessionUnavailable(original.failure, instruction);
+            throw new SessionUnavailableContinuityError(this.options.runId, this.options.role, original.failure);
+        }
+        if (original.interrupted?.reason === "compaction-boundary") {
+            // The coordinator owns the validated handoff and replay of this frozen
+            // action. A protocol-repair turn here would run in the interrupted
+            // predecessor (or race successor adoption) without a completed delta.
+            const interruptedDb = new WorkflowDb(this.options.projectDir);
+            try {
+                interruptedDb.appendContinuityEvent({
+                    runId: this.options.runId,
+                    role: "host",
+                    kind: "turn_interrupted_at_compaction_boundary",
+                    payload: {
+                        role: this.options.role,
+                        providerEventId: original.interrupted.providerEventId,
+                        instructionDigest: sha(instruction),
+                    },
+                    authoritativeStateRevision: this.revision(),
+                    sessionRef: this.adapter.sessionRef?.(),
+                });
+            }
+            finally {
+                interruptedDb.close();
+            }
+            return original;
+        }
+        const parsed = parseContinuityDelta(original.text);
+        if (parsed.delta) {
+            this.publish(parsed.delta, "turn_completed", original);
+            this.moveRecoveryLeaseAfterCheckpoint();
+            const successor = await this.options.handleHandoffRequest?.(original.text, this.adapter, instruction);
+            if (successor && successor !== this.adapter) {
+                await this.adoptValidatedSuccessor(successor);
+                return this.sendTurn([
+                    "Continue the frozen action after the accepted Rafi handoff. Do not repeat completed side effects.",
+                    instruction,
+                ].join("\n\n"));
+            }
+            return { ...original, text: parsed.cleanText };
+        }
+        const repair = await this.providerTurn([
+            "Continuity protocol repair only. Do not run tools, repeat work, or change files.",
+            `Your prior turn's continuity record was invalid: ${parsed.error?.problems.join("; ")}.`,
+            continuityInstruction(),
+            "Return only the continuity record.",
+        ].join("\n"));
+        if (repair.interrupted?.reason === "compaction-boundary") {
+            // Preserve the predecessor and let the outer managed dispatch perform
+            // the validated handoff/replay. Treating this as another invalid delta
+            // would race continuity recovery against the coordinator and could lose
+            // the original frozen action.
+            const interruptedDb = new WorkflowDb(this.options.projectDir);
+            try {
+                interruptedDb.appendContinuityEvent({
+                    runId: this.options.runId,
+                    role: "host",
+                    kind: "continuity_repair_interrupted_at_compaction_boundary",
+                    payload: {
+                        role: this.options.role,
+                        providerEventId: repair.interrupted.providerEventId,
+                        instructionDigest: sha(instruction),
+                    },
+                    authoritativeStateRevision: this.revision(),
+                    sessionRef: this.adapter.sessionRef?.(),
+                });
+            }
+            finally {
+                interruptedDb.close();
+            }
+            return repair;
+        }
+        const repaired = parseContinuityDelta(repair.text);
+        if (repaired.delta) {
+            this.publish(repaired.delta, "turn_completed_after_repair", original);
+            this.moveRecoveryLeaseAfterCheckpoint();
+            return { ...original, text: parsed.cleanText };
+        }
+        const invalidDb = new WorkflowDb(this.options.projectDir);
+        try {
+            invalidDb.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "continuity_invalid_twice", payload: { original: parsed.error?.problems, repair: repaired.error?.problems }, authoritativeStateRevision: this.revision() });
+            invalidDb.setContinuityHeadState(this.options.runId, this.options.role, "invalid");
+        }
+        finally {
+            invalidDb.close();
+        }
+        const handoff = this.reconstructionHandoff();
+        if (this.options.recoverWithHandoff) {
+            let successor;
+            try {
+                successor = await this.options.recoverWithHandoff({
+                    reason: "continuity delta and same-session repair were both invalid",
+                    reconstruction: handoff,
+                    predecessor: this.adapter,
+                });
+            }
+            catch (error) {
+                throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, `fresh validated successor also failed after the same-session repair: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (!successor.sessionId() || successor.sessionId() === this.adapter.sessionId()) {
+                await successor.close().catch(() => { });
+                throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "validated recovery callback did not return a genuinely fresh successor");
+            }
+            await this.adoptValidatedSuccessor(successor);
+            return { ...original, text: parsed.cleanText };
+        }
+        // A raw create-and-send fallback cannot install native context control,
+        // account compactions, or validate the scoped successor atomically. Refuse
+        // it instead of allowing continuity recovery to escape the managed gate.
+        throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "continuity repair failed in the original session and no lifecycle-managed recoverWithHandoff callback is configured");
+    }
+    sessionId() { return this.adapter.sessionId(); }
+    sessionRef() { return this.adapter.sessionRef?.(); }
+    adoptSessionRef(ref) { this.adapter.adoptSessionRef?.(ref); }
+    validateSession() { return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped" }); }
+    compact() { return this.adapter.compact ? this.adapter.compact() : Promise.resolve({ ok: false, error: "provider adapter does not expose native compaction" }); }
+    prepareContextManagement(policy) { if (!this.adapter.prepareContextManagement)
+        return Promise.reject(new Error("provider adapter does not expose native context management")); return this.adapter.prepareContextManagement(policy); }
+    updateContextManagement(policy) { if (!this.adapter.updateContextManagement)
+        return Promise.reject(new Error("provider adapter does not expose native context reconfiguration")); return this.adapter.updateContextManagement(policy); }
+    interruptTurnAtCompactionBoundary(providerEventId) { return this.adapter.interruptTurnAtCompactionBoundary?.(providerEventId) ?? Promise.resolve({ ok: false, error: "provider adapter does not expose compaction-boundary interruption", providerEventId }); }
+    installManagedTurnDispatcher(dispatcher) {
+        this.turnDispatcher = dispatcher;
+        this.adapter.installManagedTurnDispatcher?.(dispatcher);
+    }
+    contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
+    sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
+    switchSettings(settings) { return this.adapter.switchSettings ? this.adapter.switchSettings(settings) : Promise.resolve({ ok: false, error: "provider adapter does not support settings changes" }); }
+    events() { return this.queue; }
+    async close() { await this.adapter.close(); await this.sourcePump?.catch(() => { }); this.queue.close(); }
+    /** Keep the observable wrapper and event stream stable while moving to an accepted successor. */
+    async adoptValidatedSuccessor(successor) {
+        if (successor === this.adapter)
+            return;
+        const prior = this.adapter;
+        this.adapter = successor;
+        if (this.turnDispatcher)
+            successor.installManagedTurnDispatcher?.(this.turnDispatcher);
+        this.pumpEvents();
+        await prior.close().catch(() => { });
+    }
+    providerTurn(text) {
+        const invoke = () => this.adapter.sendTurn(text);
+        return this.turnDispatcher ? this.turnDispatcher(text, invoke) : invoke();
+    }
+    publish(delta, kind, result) {
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            const sessionRef = this.adapter.sessionRef?.();
+            db.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind, payload: { isError: result.isError, numTurns: result.numTurns, sessionId: this.adapter.sessionId(), sessionRef, delta }, authoritativeStateRevision: this.revision(), sessionRef });
+            return db.publishContinuityCheckpoint({ runId: this.options.runId, role: this.options.role, delta, authoritativeStateRevision: this.revision(), sessionRef });
+        }
+        finally {
+            db.close();
+        }
+    }
+    moveRecoveryLeaseAfterCheckpoint() {
+        if (!this.recoveryLeasePending)
+            return;
+        const session = this.adapter.sessionRef?.() ?? this.adapter.sessionId();
+        if (!session)
+            return;
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            db.moveRoleLeaseAfterValidatedRecovery(this.options.runId, this.options.role, session, "explicit fresh-recovery-only continuation");
+        }
+        finally {
+            db.close();
+        }
+        this.recoveryLeasePending = false;
+    }
+    recordSessionUnavailable(failure, instruction) {
+        const sessionRef = this.adapter.sessionRef?.();
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            db.appendContinuityEvent({
+                runId: this.options.runId,
+                role: "host",
+                kind: "session_unavailable",
+                payload: {
+                    role: this.options.role,
+                    phase: failure.phase,
+                    dispatchState: failure.dispatchState ?? "unknown",
+                    reason: failure.availability?.reason,
+                    detail: failure.diagnostics,
+                    instructionDigest: sha(instruction),
+                },
+                authoritativeStateRevision: this.revision(),
+                sessionRef,
+            });
+            if (failure.dispatchState === "unknown") {
+                db.setContinuityHeadState(this.options.runId, this.options.role, "degraded");
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    reconstructionHandoff() {
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            const checkpoints = db.continuityCheckpoints(this.options.runId, this.options.role);
+            const events = db.continuityEvents(this.options.runId, checkpoints.at(-1)?.sequence ?? 0);
+            return [
+                `Validated cumulative recovery for run ${this.options.runId}, role ${this.options.role}.`,
+                JSON.stringify(mergeContinuityDeltas(checkpoints.map((checkpoint) => checkpoint.delta))),
+                `Later host facts: ${JSON.stringify(events.map((event) => ({ kind: event.kind, payload: event.payload, digest: event.digest })))}`,
+                "The prior in-flight operation is unknown unless a host fact proves completion. Reconcile receipts before retrying side effects.",
+            ].join("\n\n");
+        }
+        finally {
+            db.close();
+        }
+    }
+    revision() { return this.options.authoritativeStateRevision?.() ?? this.options.settings.settings_revision; }
+    pumpEvents() {
+        const source = this.adapter;
+        this.sourcePump = (async () => {
+            try {
+                for await (const event of source.events()) {
+                    this.queue.push(event);
+                    if (event.kind === "tool" || event.kind === "session-transition" || event.kind === "context-usage" || event.kind === "context-compaction") {
+                        const db = new WorkflowDb(this.options.projectDir);
+                        try {
+                            const payload = event.kind === "tool"
+                                ? { name: event.name, inputDigest: sha(JSON.stringify(event.input ?? null)) }
+                                : event;
+                            db.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: `provider_${event.kind.replace(/-/g, "_")}`, payload, authoritativeStateRevision: this.revision() });
+                        }
+                        finally {
+                            db.close();
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                this.queue.push({ kind: "error", message: error instanceof Error ? error.message : String(error) });
+            }
+        })();
+    }
+}
+function strings(value, field, problems) {
+    if (!Array.isArray(value)) {
+        problems.push(`${field} must be an array`);
+        return [];
+    }
+    if (value.length > 500)
+        problems.push(`${field} exceeds 500 entries`);
+    const result = [];
+    for (const entry of value.slice(0, 500)) {
+        if (typeof entry !== "string" || !entry.trim())
+            problems.push(`${field} entries must be non-empty strings`);
+        else
+            result.push(clean(entry, 4_000));
+    }
+    return unique(result);
+}
+function clean(value, maximum) {
+    return value.replace(/\b(sk-[A-Za-z0-9_-]{12,}|(?:api[_-]?key|token|password)\s*[:=]\s*\S+)/gi, "[REDACTED]").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, "").trim().slice(0, maximum);
+}
+function unique(values) { return [...new Set(values)]; }
+function sha(value) { return createHash("sha256").update(value).digest("hex"); }

package/dist/foreman.d.ts

@@ -62,10 +62,13 @@ export declare class Foreman {
     private readonly builderFactory?;
     private readonly builderSessionStrategy;
     private readonly qaNonconvergence?;
+    private readonly beforeBuilderTurn?;
+    private readonly builderSessionBoundary?;
+    private readonly qaSessionBoundary?;
     private readonly ticketsEnabled;
     private readonly qaStream;
     private builderWorkSessions;
-    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined, qaReviewer?: BuilderAdapter | undefined, qaFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, qaSessionStrategy?: SessionStrategy, builderFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, builderSessionStrategy?: SessionStrategy, qaNonconvergence?: ((context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>) | undefined);
+    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined, qaReviewer?: BuilderAdapter | undefined, qaFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, qaSessionStrategy?: SessionStrategy, builderFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, builderSessionStrategy?: SessionStrategy, qaNonconvergence?: ((context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>) | undefined, beforeBuilderTurn?: ((adapter: BuilderAdapter, frozenAction: string) => Promise<BuilderAdapter>) | undefined, builderSessionBoundary?: ((adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy) => Promise<BuilderAdapter>) | undefined, qaSessionBoundary?: ((adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string) => Promise<BuilderAdapter>) | undefined);
     /**
      * Send one instruction and resolve any needs_input exchanges before returning.
      * The returned result and status always reflect the final (non-needs_input) turn.
@@ -94,6 +97,7 @@ export declare class Foreman {
         summary?: string;
     }>;
     qaSessionId(): string | undefined;
+    qaSessionRef(): import("rafi-spec").ProviderSessionRefV1 | undefined;
     builderSessionId(): string | undefined;
     builderAdapter(): BuilderAdapter;
     close(): Promise<void>;

package/dist/foreman.js

@@ -9,6 +9,7 @@ import { runIsolatedQa } from "./qaReview.js";
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
+import { SessionUnavailableError, sessionUnavailableErrorFromFailure } from "./adapters/sessionFailure.js";
 /** Phrases that suggest the builder ended its turn by asking the human. */
 const QUESTION_HINTS = [
     "should i",
@@ -225,10 +226,13 @@ export class Foreman {
     builderFactory;
     builderSessionStrategy;
     qaNonconvergence;
+    beforeBuilderTurn;
+    builderSessionBoundary;
+    qaSessionBoundary;
     ticketsEnabled;
     qaStream = { reviews: 0, modificationViolations: 0 };
     builderWorkSessions = 0;
-    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir, qaReviewer, qaFactory, qaSessionStrategy = "compact", builderFactory, builderSessionStrategy = "compact", qaNonconvergence) {
+    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir, qaReviewer, qaFactory, qaSessionStrategy = "compact", builderFactory, builderSessionStrategy = "compact", qaNonconvergence, beforeBuilderTurn, builderSessionBoundary, qaSessionBoundary) {
         this.builder = builder;
         this.log = log;
         this.notificationsEnabled = notificationsEnabled;
@@ -241,6 +245,9 @@ export class Foreman {
         this.builderFactory = builderFactory;
         this.builderSessionStrategy = builderSessionStrategy;
         this.qaNonconvergence = qaNonconvergence;
+        this.beforeBuilderTurn = beforeBuilderTurn;
+        this.builderSessionBoundary = builderSessionBoundary;
+        this.qaSessionBoundary = qaSessionBoundary;
         this.ticketsEnabled = !!(projectDir && isTicketsInitialized(projectDir));
     }
     /**
@@ -250,9 +257,14 @@ export class Foreman {
     async doTurn(instruction) {
         return this.doTurnWith(this.builder, instruction);
     }
-    async prepareBuilderBoundary() {
+    async prepareBuilderBoundary(frozenAction) {
         if (!this.builderFactory || !this.projectDir)
             return;
+        if (this.builderSessionBoundary) {
+            this.builder = await this.builderSessionBoundary(this.builder, frozenAction, this.builderSessionStrategy);
+            this.log.write("branch-session", { role: "builder", transition: this.builderSessionStrategy === "fresh" ? "validated-handoff" : "accounted-compaction", workSession: this.builderWorkSessions + 1, sessionId: this.builder.sessionId() });
+            return;
+        }
         if (this.builderSessionStrategy === "fresh") {
             await this.builder.close();
             this.builder = await this.builderFactory(this.projectDir);
@@ -263,7 +275,17 @@ export class Foreman {
         if (priorSession && this.builder.compact) {
             let error = "";
             for (let attempt = 1; attempt <= 2; attempt++) {
-                const result = await this.builder.compact().catch((cause) => ({ ok: false, error: cause instanceof Error ? cause.message : String(cause) }));
+                let result;
+                try {
+                    result = await this.builder.compact();
+                }
+                catch (cause) {
+                    if (cause instanceof SessionUnavailableError)
+                        throw cause;
+                    result = { ok: false, error: cause instanceof Error ? cause.message : String(cause) };
+                }
+                if (result.failure?.category === "session-unavailable")
+                    throw sessionUnavailableErrorFromFailure(result.failure);
                 if (result.ok) {
                     this.log.write("branch-session", { role: "builder", transition: attempt === 1 ? "compacted" : "compaction-retry-succeeded", workSession: this.builderWorkSessions + 1, sessionId: priorSession });
                     return;
@@ -282,8 +304,14 @@ export class Foreman {
         this.log.write("branch-session", { role: "builder", transition: "missing-session-fresh", continuityLost: true });
     }
     async doTurnWith(adapter, instruction) {
+        if (adapter === this.builder && this.beforeBuilderTurn) {
+            this.builder = await this.beforeBuilderTurn(this.builder, instruction);
+            adapter = this.builder;
+        }
         let result = await adapter.sendTurn(instruction);
         let status = parseStepStatus(result.text);
+        if (result.failure?.category === "session-unavailable")
+            return { result, status };
         if (status.kind === "unknown") {
             if (!status.error && looksLikeQuestion(result.text)) {
                 status = { kind: "needs_input", question: lastLine(result.text), choices: ["Continue", "Cancel"] };
@@ -326,6 +354,8 @@ export class Foreman {
     /** Send a planning turn and return the builder's response text. Does not count toward steps. */
     async runPreflight(n, ticketsContent, preferredTicketId) {
         const instruction = buildPlanningTurn(n, ticketsContent, preferredTicketId);
+        if (this.beforeBuilderTurn)
+            this.builder = await this.beforeBuilderTurn(this.builder, instruction);
         const result = await this.builder.sendTurn(instruction);
         this.log.write("preflight", {
             ticketsProvided: ticketsContent !== undefined,
@@ -338,6 +368,8 @@ export class Foreman {
     }
     /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */
     async sendPreflightFeedback(feedback) {
+        if (this.beforeBuilderTurn)
+            this.builder = await this.beforeBuilderTurn(this.builder, feedback);
         const result = await this.builder.sendTurn(feedback);
         this.log.write("preflight", { feedback: true, costUsd: result.costUsd, isError: result.isError });
         if (result.isError)
@@ -361,11 +393,13 @@ export class Foreman {
                 qaStrategy: this.qaSessionStrategy,
                 state: this.qaStream,
                 createQa: this.qaFactory,
+                sessionBoundary: this.qaSessionBoundary,
                 maxCycles: this.qaMaxCycles,
                 fix: async (issues) => {
-                    await this.prepareBuilderBoundary();
+                    const instruction = buildQaFixInstruction(issues);
+                    await this.prepareBuilderBoundary(instruction);
                     this.builderWorkSessions += 1;
-                    const fix = await this.doTurn(buildQaFixInstruction(issues));
+                    const fix = await this.doTurn(instruction);
                     this.log.write("qa-fix", { stepIndex, statusKind: fix.status.kind, costUsd: fix.result.costUsd, isError: fix.result.isError });
                     return fix.result.isError || fix.status.kind !== "done"
                         ? { ok: false, detail: fix.status.reason ?? fix.status.error ?? fix.result.text.slice(0, 200) }
@@ -442,6 +476,7 @@ export class Foreman {
         return this.runQa(stepIndex);
     }
     qaSessionId() { return this.qaStream.sessionId ?? this.qaReviewer?.sessionId(); }
+    qaSessionRef() { return this.qaStream.sessionRef ?? this.qaReviewer?.sessionRef?.(); }
     builderSessionId() { return this.builder.sessionId(); }
     builderAdapter() { return this.builder; }
     async close() { await this.builder.close(); }
@@ -505,7 +540,7 @@ export class Foreman {
                 ? buildPrimer(n, trackerPath, this.ticketsEnabled, preferredTicketId)
                 : buildNextStepInstruction(i, n);
             if (i > 1)
-                await this.prepareBuilderBoundary();
+                await this.prepareBuilderBoundary(instruction);
             this.builderWorkSessions += 1;
             const { result, status } = await this.doTurn(instruction);
             this.log.write("step", {

package/dist/handoffs.d.ts

@@ -0,0 +1,69 @@
+import type { ContinuityDelta, HandoffLineage, HandoffManifestV1, ProviderSessionRefV1, SessionUsageSample } from "rafi-spec";
+import type { BuilderAdapter } from "./adapters/types.js";
+export declare const HANDOFF_CACHE_RETENTION_DAYS = 30;
+export declare const HANDOFF_ACCEPTED = "HANDOFF_ACCEPTED";
+export declare const HANDOFF_REQUEST_START = "RAFI_HANDOFF_REQUEST_START";
+export declare const HANDOFF_REQUEST_END = "RAFI_HANDOFF_REQUEST_END";
+export interface BuilderHandoffRequest {
+    version: 1;
+    reason: string;
+    delta: ContinuityDelta;
+    roleState: Record<string, unknown>;
+}
+export declare function parseBuilderHandoffRequest(text: string): BuilderHandoffRequest | undefined;
+export interface CreateHandoffInput {
+    runId: string;
+    role: "builder" | "qa";
+    reason: string;
+    predecessorSessionId?: string;
+    predecessorSessionRef?: ProviderSessionRefV1;
+    roleState?: Record<string, unknown>;
+    sessionUsage?: SessionUsageSample;
+    compactionCount: number;
+    compactMaximum: number;
+    resources?: Array<{
+        label: string;
+        content: string | Buffer;
+        authoritative: boolean;
+    }>;
+    requestedByBuilder?: boolean;
+    /** Internal recovery path: use the last valid checkpoint while its head is marked degraded/invalid. */
+    allowNonCurrentContinuity?: boolean;
+}
+export interface StagedHandoff {
+    manifest: HandoffManifestV1;
+    markdown: string;
+    lineage: HandoffLineage;
+    cacheDirectory: string;
+}
+export interface HandoffTransferResult extends StagedHandoff {
+    successor: BuilderAdapter;
+    successorSessionId: string;
+    acceptanceCheckpointDigest: string;
+}
+export declare class HandoffLoopError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/** Durable, validated ownership transfer; cache copies are never authoritative. */
+export declare class HandoffService {
+    readonly projectDir: string;
+    readonly cacheRoot: string;
+    constructor(projectDir: string);
+    stage(input: CreateHandoffInput, now?: Date): StagedHandoff;
+    transfer(input: CreateHandoffInput, createSuccessor: (handoff: StagedHandoff) => Promise<BuilderAdapter>): Promise<HandoffTransferResult>;
+    acceptStaged(staged: StagedHandoff, successor: BuilderAdapter): Promise<HandoffTransferResult>;
+    inspect(runId: string, generation?: number): {
+        manifest: HandoffManifestV1;
+        markdown: string;
+        lineage: HandoffLineage;
+    };
+    loadStaged(runId: string, generation: number): StagedHandoff;
+    pruneCache(runId: string, keepLatest?: number): string[];
+    pruneExpiredCache(now?: Date, retentionDays?: number): string[];
+    private materialize;
+    private safeRunCache;
+    private consecutiveBuilderRequests;
+}
+export declare function renderHandoffMarkdown(manifest: HandoffManifestV1): string;
+export declare function writeHandoffInspection(path: string, content: string): void;