ai-foreman 1.7.6 → 1.7.7

package/dist/agentRun.js

@@ -6,12 +6,15 @@ import { PermissionPolicy } from "./permissions/policy.js";
 import { ClaudeAdapter } from "./adapters/claude.js";
 import { CodexAdapter } from "./adapters/codex.js";
 import { RecoveringAdapter } from "./adapters/recovering.js";
+import { SessionUnavailableError } from "./adapters/sessionFailure.js";
 import { Foreman, createPermissionHandler } from "./foreman.js";
 import { printEvents } from "./cli/events.js";
 import { loadRoleBundle } from "./roles.js";
 import { ensureRuntimeReadyForCommand } from "./cli/runtimeAuthPrompt.js";
 import { resolveAgentForProject } from "./cli/runtimeSelection.js";
 import { parse as parseYaml } from "yaml";
+import { captureWorkspaceIdentity, createProviderSessionRef, resolveUniqueSessionBinding } from "./sessionIdentity.js";
+import { WorkflowDb } from "./workflowDb.js";
 export const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
 export function assertEffortLevel(effort) {
     if (effort && !VALID_EFFORT.includes(effort)) {
@@ -87,10 +90,29 @@ export async function createRoleBuilder(opts) {
         throw new Error(`project directory not found: ${opts.projectDir}`);
     }
     const saved = readRoleDefaultsForExecution(opts.projectDir, opts.role);
+    if (opts.resumeSessionRef && opts.resumeSessionId && opts.resumeSessionRef.sessionId !== opts.resumeSessionId) {
+        throw new Error("resume session ID does not match the supplied location-scoped reference");
+    }
+    let requestedResumeRef = opts.resumeSessionRef;
+    if (!requestedResumeRef && opts.resumeSessionId) {
+        const bindingDb = new WorkflowDb(opts.projectDir);
+        try {
+            requestedResumeRef = resolveUniqueSessionBinding(bindingDb.providerSessionBindings(opts.resumeSessionId), opts.resumeSessionId);
+        }
+        finally {
+            bindingDb.close();
+        }
+    }
     const configuredEffort = saved?.reasoning && saved.reasoning !== "default" ? saved.reasoning : undefined;
     const effectiveEffort = opts.effort ?? (VALID_EFFORT.includes(configuredEffort) ? configuredEffort : undefined);
     assertEffortLevel(effectiveEffort);
-    let runtime = resolveAgentForProject(opts.projectDir, opts.agent ?? saved?.make);
+    let runtime = resolveAgentForProject(opts.projectDir, opts.agent ?? requestedResumeRef?.provider ?? saved?.make);
+    if (requestedResumeRef && requestedResumeRef.provider !== runtime) {
+        throw new Error(`session ${requestedResumeRef.sessionId} belongs to ${requestedResumeRef.provider}, but ${runtime} was selected`);
+    }
+    if (requestedResumeRef && requestedResumeRef.role !== configurableRole(opts.role)) {
+        throw new Error(`session ${requestedResumeRef.sessionId} belongs to role ${requestedResumeRef.role}, not ${configurableRole(opts.role)}`);
+    }
     const config = loadConfig(join(opts.projectDir, "foreman.yaml"));
     const log = opts.log ?? new Log(makeLogPath(opts.projectDir, opts.label.replace(/\s+/g, "-")));
     const roleBundle = loadRoleBundle(opts.role, { projectDir: opts.projectDir });
@@ -99,7 +121,7 @@ export async function createRoleBuilder(opts) {
     const ready = await ensureRuntimeReadyForCommand(opts.projectDir, runtime, {
         label: opts.label,
         yes: Boolean(opts.yes),
-        allowSwitch: opts.allowSwitch,
+        allowSwitch: requestedResumeRef || opts.resumeSessionId ? false : opts.allowSwitch,
         model: initialModel,
     });
     runtime = ready.runtime;
@@ -108,13 +130,42 @@ export async function createRoleBuilder(opts) {
     const policy = new PermissionPolicy(opts.permissionConfig ?? config.permissions, opts.projectDir);
     const skills = mergeSkills(roleBundle.skills, opts.extraSkills);
     const interactive = !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY);
-    const makeAdapter = async (nextRuntime, resumeSessionId) => {
+    const makeAdapter = async (nextRuntime, resumeSessionId, resumeSessionRef) => {
+        let scopedRef = resumeSessionRef;
+        if (!scopedRef && resumeSessionId) {
+            const bindingDb = new WorkflowDb(opts.projectDir);
+            try {
+                scopedRef = resolveUniqueSessionBinding(bindingDb.providerSessionBindings(resumeSessionId), resumeSessionId);
+            }
+            finally {
+                bindingDb.close();
+            }
+            scopedRef ??= createProviderSessionRef({
+                provider: nextRuntime,
+                sessionId: resumeSessionId,
+                role: configurableRole(opts.role),
+                stream: opts.role,
+                generation: 0,
+                cwd: opts.projectDir,
+                configRoot: opts.projectDir,
+                workspaceIdentity: captureWorkspaceIdentity(opts.projectDir),
+                source: "legacy-inferred",
+            });
+        }
+        if (scopedRef && scopedRef.provider !== nextRuntime) {
+            throw new Error(`session ${scopedRef.sessionId} belongs to ${scopedRef.provider}, but ${nextRuntime} was selected`);
+        }
         const adapterOpts = {
             cwd: opts.projectDir,
+            configRoot: opts.projectDir,
             runtimeExecutable,
             runtimePhase: phaseForRole(opts.role),
             model,
-            resumeSessionId,
+            ...(scopedRef ? { resumeSessionRef: scopedRef } : {}),
+            sessionRole: configurableRole(opts.role),
+            sessionStream: opts.role,
+            sessionGeneration: scopedRef?.generation ?? 0,
+            workspaceIdentity: captureWorkspaceIdentity(opts.projectDir),
             permission: createPermissionHandler(policy, log, {
                 interactive,
                 onAnsweredQuestion: opts.onAnsweredQuestion,
@@ -126,18 +177,46 @@ export async function createRoleBuilder(opts) {
             systemPromptAppend: roleBundle.system || undefined,
             skills: skills.length > 0 ? skills : undefined,
         };
-        return nextRuntime === "codex"
+        const adapter = nextRuntime === "codex"
             ? new CodexAdapter(adapterOpts)
             : await ClaudeAdapter.create(adapterOpts);
+        if (scopedRef && adapter.agent === "codex") {
+            const availability = await adapter.validateSession();
+            if (availability.status !== "available") {
+                await adapter.close().catch(() => { });
+                throw new SessionUnavailableError({
+                    runtime: "codex",
+                    phase: "preflight",
+                    dispatchState: "not-sent",
+                    executable: runtimeExecutable,
+                    cwd: opts.projectDir,
+                    diagnostics: availability.detail ?? `Codex session ${scopedRef.sessionId} is ${availability.status}`,
+                    availability,
+                });
+            }
+        }
+        return adapter;
     };
-    const initial = await makeAdapter(runtime, opts.resumeSessionId);
+    const initial = await makeAdapter(runtime, opts.resumeSessionId, requestedResumeRef);
+    const persistSessionRef = (ref) => {
+        const bindingDb = new WorkflowDb(opts.projectDir);
+        try {
+            bindingDb.recordProviderSessionBinding(ref);
+        }
+        finally {
+            bindingDb.close();
+        }
+    };
+    const initialRef = initial.sessionRef?.();
+    if (initialRef)
+        persistSessionRef(initialRef);
     const builder = new RecoveringAdapter({
         initial,
         runtime,
         label: opts.label,
         enabled: interactive,
-        allowSwitch: opts.allowSwitch !== false && !opts.resumeSessionId,
-        recreate: async (nextRuntime, resumeSessionId) => {
+        allowSwitch: opts.allowSwitch !== false && !opts.resumeSessionId && !requestedResumeRef,
+        recreate: async (nextRuntime, resumeSessionId, resumeSessionRef) => {
             const nextReady = await ensureRuntimeReadyForCommand(opts.projectDir, nextRuntime, {
                 label: opts.label,
                 allowSwitch: false,
@@ -146,8 +225,9 @@ export async function createRoleBuilder(opts) {
             runtime = nextReady.runtime;
             model = nextReady.model;
             runtimeExecutable = nextReady.executable;
-            return makeAdapter(runtime, resumeSessionId);
+            return makeAdapter(runtime, resumeSessionId, resumeSessionRef);
         },
+        onSessionRef: persistSessionRef,
     });
     return { builder, runtime, model, effort, roleBundle, skills, log };
 }
@@ -225,6 +305,7 @@ export async function runRoleInstruction(opts) {
                 model: builder.agent === roleBuilder.runtime ? roleBuilder.model : undefined,
                 effort,
                 sessionId: builder.sessionId(),
+                sessionRef: builder.sessionRef?.(),
                 statusKind: turn.status.kind,
                 summary: turn.status.summary,
                 reason: turn.status.reason,
@@ -238,6 +319,7 @@ export async function runRoleInstruction(opts) {
             model: builder.agent === roleBuilder.runtime ? roleBuilder.model : undefined,
             effort,
             sessionId: builder.sessionId(),
+            sessionRef: builder.sessionRef?.(),
             logPath,
             roleBundle,
             skills,
@@ -250,3 +332,8 @@ export async function runRoleInstruction(opts) {
         throw err;
     }
 }
+function configurableRole(role) {
+    return ["builder", "qa", "planner", "ticket-maker", "uninstaller"].includes(role)
+        ? role
+        : "builder";
+}

package/dist/branch/currentGuard.d.ts

@@ -0,0 +1,34 @@
+import type { BuilderAdapter, BuilderEvent, CompactResult, ContextUsage, ProviderSessionUsage, ProviderSettingSwitch, TurnResult } from "../adapters/types.js";
+import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
+export interface CurrentWorkflowIdentity {
+    worktree: string;
+    ref: string;
+}
+export declare class CurrentWorkflowChangedError extends Error {
+    readonly expected: CurrentWorkflowIdentity;
+    readonly actual: CurrentWorkflowIdentity;
+    constructor(expected: CurrentWorkflowIdentity, actual: CurrentWorkflowIdentity);
+}
+export declare function captureCurrentWorkflowIdentity(cwd: string): CurrentWorkflowIdentity;
+export declare function assertCurrentWorkflowIdentity(cwd: string, expected: CurrentWorkflowIdentity): void;
+export declare function currentWorkflowIdentityKey(identity: CurrentWorkflowIdentity): string;
+export declare function captureCurrentWorkflowSessionIdentity(cwd: string): string;
+/** Fence every provider boundary against an unexpected user/provider ref switch. */
+export declare class CurrentWorkflowGuardAdapter implements BuilderAdapter {
+    private readonly adapter;
+    private readonly cwd;
+    private readonly expected;
+    readonly agent: BuilderAdapter["agent"];
+    constructor(adapter: BuilderAdapter, cwd: string, expected?: CurrentWorkflowIdentity);
+    sendTurn(text: string): Promise<TurnResult>;
+    sessionId(): string | undefined;
+    sessionRef(): ProviderSessionRefV1 | undefined;
+    adoptSessionRef(ref: ProviderSessionRefV1): void;
+    validateSession(): Promise<SessionAvailabilityV1>;
+    compact(): Promise<CompactResult>;
+    contextUsage(): Promise<ContextUsage | undefined>;
+    sessionUsage(): Promise<ProviderSessionUsage | undefined>;
+    switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
+    events(): AsyncIterable<BuilderEvent>;
+    close(): Promise<void>;
+}

package/dist/branch/currentGuard.js

@@ -0,0 +1,65 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+export class CurrentWorkflowChangedError extends Error {
+    expected;
+    actual;
+    constructor(expected, actual) {
+        super(`current-branch workflow paused: active worktree/ref changed (expected ${expected.worktree} @ ${expected.ref}; found ${actual.worktree} @ ${actual.ref})`);
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+export function captureCurrentWorkflowIdentity(cwd) {
+    return { worktree: realpathSync(git(cwd, ["rev-parse", "--show-toplevel"])), ref: currentRef(cwd) };
+}
+export function assertCurrentWorkflowIdentity(cwd, expected) {
+    const actual = captureCurrentWorkflowIdentity(cwd);
+    if (actual.worktree !== expected.worktree || actual.ref !== expected.ref) {
+        throw new CurrentWorkflowChangedError(expected, actual);
+    }
+}
+export function currentWorkflowIdentityKey(identity) {
+    return `current_${createHash("sha256").update(`${identity.worktree}\0${identity.ref}`).digest("hex")}`;
+}
+export function captureCurrentWorkflowSessionIdentity(cwd) {
+    return currentWorkflowIdentityKey(captureCurrentWorkflowIdentity(cwd));
+}
+/** Fence every provider boundary against an unexpected user/provider ref switch. */
+export class CurrentWorkflowGuardAdapter {
+    adapter;
+    cwd;
+    expected;
+    agent;
+    constructor(adapter, cwd, expected = captureCurrentWorkflowIdentity(cwd)) {
+        this.adapter = adapter;
+        this.cwd = cwd;
+        this.expected = expected;
+        this.agent = adapter.agent;
+    }
+    async sendTurn(text) {
+        assertCurrentWorkflowIdentity(this.cwd, this.expected);
+        const result = await this.adapter.sendTurn(text);
+        assertCurrentWorkflowIdentity(this.cwd, this.expected);
+        return result;
+    }
+    sessionId() { return this.adapter.sessionId(); }
+    sessionRef() { return this.adapter.sessionRef?.(); }
+    adoptSessionRef(ref) { this.adapter.adoptSessionRef?.(ref); }
+    validateSession() { assertCurrentWorkflowIdentity(this.cwd, this.expected); return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped" }); }
+    async compact() { assertCurrentWorkflowIdentity(this.cwd, this.expected); const result = await (this.adapter.compact?.() ?? Promise.resolve({ ok: false, error: "native compaction unavailable" })); assertCurrentWorkflowIdentity(this.cwd, this.expected); return result; }
+    contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
+    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(); }
+    close() { return this.adapter.close(); }
+}
+function currentRef(cwd) {
+    try {
+        return `branch:${git(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"])}`;
+    }
+    catch {
+        return `detached:${git(cwd, ["rev-parse", "HEAD"])}`;
+    }
+}
+function git(cwd, args) { return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); }

package/dist/branch/planner.d.ts

@@ -24,4 +24,4 @@ export declare function applySharedDeliveryBranch(plan: BranchPlan, unitId: stri
 export declare function applySizeBranchPolicy(plan: BranchPlan, policy: TicketBuildSetupConfig["branch_policy"], delivery?: DeliveryConfig, branchPrefix?: string): BranchPlan;
 export declare function parseAuditDependencies(text: string): AuditDependency[];
 export declare function buildBranchAuditInstruction(tickets: TicketDef[]): string;
-export declare function normalizeBranchPrefix(prefix: string | undefined): string;
+export { normalizeBranchPrefix } from "./prefix.js";

package/dist/branch/planner.js

@@ -1,3 +1,4 @@
+import { normalizeBranchPrefix } from "./prefix.js";
 export function buildBranchPlan(tickets, states, opts) {
     const selected = selectTicketsForBranchRun(tickets, states, opts.steps, opts.ticketIds);
     const selectedIds = new Set(selected.map((ticket) => ticket.id));
@@ -192,13 +193,7 @@ function uniqueBranchName(prefix, ticket, used) {
     used.add(branch);
     return branch;
 }
-export function normalizeBranchPrefix(prefix) {
-    const value = prefix === undefined || prefix === "" ? "feature" : prefix;
-    if (value.startsWith("/") || value.endsWith("/") || value.includes("..") || value.includes("//") || /[~^:?*\[\\\s]/.test(value)) {
-        throw new Error(`invalid Git branch prefix: ${value}`);
-    }
-    return value;
-}
+export { normalizeBranchPrefix } from "./prefix.js";
 function detectSelectedCycles(tickets, deps) {
     const selected = new Set(tickets.map((ticket) => ticket.id));
     const visited = new Set();

package/dist/branch/prefix.d.ts

@@ -0,0 +1,8 @@
+/** Built-in prefix used only when neither a run nor project value exists. */
+export declare const BUILTIN_BRANCH_PREFIX = "feature";
+/**
+ * Validate a prefix as the leading components of a Git branch ref. Internal
+ * slashes are intentional (for example `team/feature`).
+ */
+export declare function validateBranchPrefix(value: string): string;
+export declare function normalizeBranchPrefix(prefix: string | undefined): string;

package/dist/branch/prefix.js

@@ -0,0 +1,26 @@
+/** Built-in prefix used only when neither a run nor project value exists. */
+export const BUILTIN_BRANCH_PREFIX = "feature";
+/**
+ * Validate a prefix as the leading components of a Git branch ref. Internal
+ * slashes are intentional (for example `team/feature`).
+ */
+export function validateBranchPrefix(value) {
+    const prefix = value.trim();
+    if (!prefix)
+        throw new Error("branch prefix must not be empty");
+    if (prefix === "@" || prefix.startsWith("-") || prefix.startsWith("/") || prefix.endsWith("/")) {
+        throw new Error(`invalid Git branch prefix: ${value}`);
+    }
+    if (prefix.includes("//") || prefix.includes("..") || prefix.includes("@{") || /[\x00-\x20\x7f~^:?*\[\\]/.test(prefix)) {
+        throw new Error(`invalid Git branch prefix: ${value}`);
+    }
+    for (const segment of prefix.split("/")) {
+        if (!segment || segment === "." || segment === ".." || segment.startsWith(".") || segment.endsWith(".") || segment.endsWith(".lock")) {
+            throw new Error(`invalid Git branch prefix: ${value}`);
+        }
+    }
+    return prefix;
+}
+export function normalizeBranchPrefix(prefix) {
+    return validateBranchPrefix(prefix === undefined ? BUILTIN_BRANCH_PREFIX : prefix);
+}

package/dist/branch/resume.d.ts

@@ -1,10 +1,12 @@
 import type { BranchRunSummary } from "./types.js";
+import type { ProviderSessionRefV1 } from "rafi-spec";
 export interface BranchResumeSession {
     ticket: string;
     branch: string;
     base: string;
     worktreePath: string;
     sessionId: string;
+    sessionRef?: ProviderSessionRefV1;
     logPath: string;
     agent?: string;
     model?: string;

package/dist/branch/resume.js

@@ -32,6 +32,7 @@ export function findResumableBranchSessions(foremanDir) {
                     base,
                     worktreePath,
                     sessionId,
+                    ...(isProviderSessionRef(record.sessionRef) ? { sessionRef: record.sessionRef } : {}),
                     logPath,
                     agent: stringField(record.agent),
                     model: stringField(record.model),
@@ -116,6 +117,13 @@ function stringField(value) {
 function booleanField(value) {
     return typeof value === "boolean" ? value : undefined;
 }
+function isProviderSessionRef(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const ref = value;
+    return ref.version === 1 && (ref.provider === "claude" || ref.provider === "codex") && typeof ref.sessionId === "string"
+        && typeof ref.cwd === "string" && typeof ref.configRoot === "string" && typeof ref.workspaceIdentity === "string";
+}
 function shellQuote(value) {
     if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
         return value;

package/dist/branch/runner.d.ts

@@ -1,13 +1,16 @@
 import type { BuilderAdapter, EffortLevel } from "../adapters/types.js";
-import type { SessionStrategy } from "rafi-spec";
+import type { ProviderSessionRefV1, SessionStrategy } from "rafi-spec";
 import { type QaNonconvergenceContext, type QaNonconvergenceDecision } from "../qaReview.js";
 import type { Log } from "../log.js";
 import type { BranchPlan, BranchPlanNode, BranchRunSummary, CompletionMode, MergeMethod, ReviewProvider } from "./types.js";
+import { SessionUnavailableError } from "../adapters/sessionFailure.js";
+import { SessionUnavailableContinuityError } from "../continuity.js";
 export interface DeliveryUnitSession {
     unitId: string;
     branch: string;
     worktreePath: string;
     sessionId: string;
+    sessionRef?: ProviderSessionRefV1;
     ticket: string;
 }
 export type BaseWorktreePolicy = "enforce" | "warn" | "skip";
@@ -41,13 +44,22 @@ export interface BranchRunnerOptions {
     resumeSessions?: Map<string, {
         worktreePath: string;
         sessionId: string;
+        sessionRef?: ProviderSessionRefV1;
     }>;
-    createBuilder: (cwd: string, sessionId?: string) => Promise<BuilderAdapter>;
+    createBuilder: (cwd: string, sessionId?: string, sessionRef?: ProviderSessionRefV1) => Promise<BuilderAdapter>;
+    /** Persist every observed Builder binding before later work can supersede it. */
+    recordBuilderSession?: (session: string | ProviderSessionRefV1, ticketId: string, worktreePath: string) => void;
+    recordQaSession?: (session: string | ProviderSessionRefV1, ticketId: string, worktreePath: string) => void;
+    /** Notify the host and stop the branch plan without discarding its worktree. */
+    onSessionUnavailable?: (error: SessionUnavailableError | SessionUnavailableContinuityError) => void;
     createQa?: (cwd: string, sessionId?: string) => Promise<BuilderAdapter>;
     builderSessionStrategy?: SessionStrategy;
     qaSessionStrategy?: SessionStrategy;
     observeBuilder?: (builder: BuilderAdapter) => Promise<void>;
     qaNonconvergence?: (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
+    beforeBuilderTurn?: (adapter: BuilderAdapter, frozenAction: string, cwd: string) => Promise<BuilderAdapter>;
+    builderSessionBoundary?: (adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string) => Promise<BuilderAdapter>;
+    qaSessionBoundary?: (adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string) => Promise<BuilderAdapter>;
 }
 export declare function runBranchPlan(opts: BranchRunnerOptions): Promise<BranchRunSummary[]>;
 export declare function buildBranchTicketInstruction(node: BranchPlanNode, trackerPaths?: {

package/dist/branch/runner.js

@@ -6,10 +6,12 @@ import { cmdBlock, cmdComplete, cmdUpdate } from "../tickets/commands.js";
 import { commitAll, createTicketWorktree, findWorktreeForBranch, currentWorktreeBranch, deleteLocalBranch, ensureCleanBaseWorktree, ensureForemanExcluded, hasTrackerChanges, hasWorktreeChanges, headCommitIfAhead, removeTicketWorktree, mergeBranchToLocalBase, } from "./git.js";
 import { checkGitHubPrMerged, createOrReusePr, enableGitHubAutoMerge, pushBranchForPr } from "./github.js";
 import { checkGitLabMrMerged, createOrReuseMr, enableGitLabAutoMerge, pushBranchForMr } from "./gitlab.js";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { WorkflowDb } from "../workflowDb.js";
 import { currentActivity, withActivityPhase } from "../activity.js";
+import { SessionUnavailableError } from "../adapters/sessionFailure.js";
+import { SessionUnavailableContinuityError } from "../continuity.js";
 export function readDeliveryUnitSession(projectDir, unitId) {
     const path = deliverySessionPath(projectDir, unitId);
     if (!existsSync(path))
@@ -46,7 +48,7 @@ export async function runBranchPlan(opts) {
     const summaries = [];
     const successfulBranches = new Set();
     const pushedBranches = new Set();
-    let builderStreamSession;
+    let builderStream;
     let builderWorkSessions = 0;
     const qaStream = { reviews: 0, modificationViolations: 0 };
     for (const issue of opts.plan.issues) {
@@ -138,28 +140,51 @@ export async function runBranchPlan(opts) {
                     base: node.baseBranch,
                     worktreePath,
                     sessionId: resumeSession.sessionId,
+                    sessionRef: resumeSession.sessionRef,
                 });
             }
             journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:in-progress`, { ticket: node.ticket.id, status: "in_progress" }, () => cmdUpdate(opts.projectDir, node.ticket.id, {
                 status: "in_progress", actor: "foreman",
                 summary: resumeSession ? `Resuming branch ${node.branch}` : `Starting branch ${node.branch}`,
             }));
-            const continuedBuilderSession = resumeSession?.sessionId ?? (opts.builderSessionStrategy === "compact" ? builderStreamSession : undefined);
-            builder = await opts.createBuilder(worktreePath, continuedBuilderSession);
-            if (opts.builderSessionStrategy === "compact" && builderWorkSessions > 0 && continuedBuilderSession) {
-                const compacted = await compactWithRetry(builder);
-                if (!compacted.ok) {
+            const ticketInstruction = resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths);
+            // Reattach the predecessor even for a `fresh` strategy so the host can
+            // publish and validate a cumulative handoff before creating its successor.
+            const sameWorktreeStream = builderStream && canonical(builderStream.worktreePath) === canonical(worktreePath) ? builderStream : undefined;
+            const continuedBuilderSession = resumeSession?.sessionId ?? sameWorktreeStream?.sessionId;
+            const continuedBuilderRef = resumeSession?.sessionRef ?? sameWorktreeStream?.sessionRef;
+            builder = await opts.createBuilder(worktreePath, continuedBuilderSession, continuedBuilderRef);
+            if (builderWorkSessions > 0 && continuedBuilderSession) {
+                const strategy = opts.builderSessionStrategy ?? "compact";
+                if (opts.builderSessionBoundary) {
+                    builder = await opts.builderSessionBoundary(builder, ticketInstruction, strategy, worktreePath);
+                }
+                else if (strategy === "compact") {
+                    const compacted = await compactWithRetry(builder);
+                    if (!compacted.ok) {
+                        await builder.close();
+                        builder = await opts.createBuilder(worktreePath);
+                    }
+                }
+                else {
                     await builder.close();
                     builder = await opts.createBuilder(worktreePath);
                 }
             }
             builderWorkSessions += 1;
             viewer = opts.observeBuilder?.(builder);
-            const foreman = new Foreman(builder, opts.log, opts.notificationsEnabled, opts.qaEnabled, 3, undefined);
-            const { result, status } = await foreman.runInstruction(resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths));
+            const foreman = new Foreman(builder, opts.log, opts.notificationsEnabled, opts.qaEnabled, 3, undefined, undefined, undefined, opts.qaSessionStrategy ?? "compact", undefined, opts.builderSessionStrategy ?? "compact", undefined, opts.beforeBuilderTurn ? (adapter, action) => opts.beforeBuilderTurn(adapter, action, worktreePath) : undefined);
+            const { result, status } = await foreman.runInstruction(ticketInstruction);
+            builder = foreman.builderAdapter();
             workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
             const sessionId = builder.sessionId();
-            builderStreamSession = opts.builderSessionStrategy === "compact" ? sessionId : undefined;
+            const sessionRef = builder.sessionRef?.();
+            if (sessionId)
+                builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
+            if (sessionId) {
+                opts.recordBuilderSession?.(sessionRef ?? sessionId, node.ticket.id, worktreePath);
+                workflowCheckpoint(opts.projectDir, opts.runId, "builder-session-scoped", node.ticket.id, { sessionId, sessionRef, worktree: worktreePath, branch: node.branch });
+            }
             if (sessionId) {
                 opts.log.write("branch-session", {
                     ticket: node.ticket.id,
@@ -167,6 +192,7 @@ export async function runBranchPlan(opts) {
                     base: node.baseBranch,
                     worktreePath,
                     sessionId,
+                    sessionRef: builder.sessionRef?.(),
                     agent: opts.agent,
                     model: opts.model,
                     effort: opts.effort,
@@ -183,7 +209,7 @@ export async function runBranchPlan(opts) {
                 if (node.deliveryUnitId) {
                     const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
                     mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
-                    writeFileSync(path, `${JSON.stringify({ unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, ticket: node.ticket.id }, null, 2)}\n`, "utf8");
+                    writeFileSync(path, `${JSON.stringify({ unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
                 }
             }
             opts.log.write("step", {
@@ -215,30 +241,47 @@ export async function runBranchPlan(opts) {
                 const qa = await runIsolatedQa({
                     ticket: node.ticket, builderWorktree: worktreePath, builderSummary: status.summary ?? result.text,
                     qaStrategy: opts.qaSessionStrategy ?? "compact", state: qaStream, createQa: opts.createQa, maxCycles: 3,
+                    sessionBoundary: opts.qaSessionBoundary,
                     evidence: (entry) => opts.log.write("qa-evidence", { ticket: node.ticket.id, ...entry }),
                     fix: async (issues) => {
                         if (!builder)
                             return { ok: false, detail: "Builder session unavailable" };
                         builderWorkSessions += 1;
-                        if (opts.builderSessionStrategy === "compact" && builder.sessionId()) {
+                        const digest = (await withActivityPhase("recording QA fix changes", () => changeManifestAsync(worktreePath, (state, detail) => currentActivity()?.update(state, detail), "recording QA fix changes"))).diffDigest;
+                        const fixInstruction = buildDurableQaFixHandoff(node.ticket, issues, worktreePath, result.text, digest);
+                        const strategy = opts.builderSessionStrategy ?? "compact";
+                        if (opts.builderSessionBoundary) {
+                            builder = await opts.builderSessionBoundary(builder, fixInstruction, strategy, worktreePath);
+                        }
+                        else if (strategy === "compact" && builder.sessionId()) {
                             const compacted = await compactWithRetry(builder);
                             if (!compacted.ok) {
                                 await builder.close();
                                 builder = await opts.createBuilder(worktreePath);
                             }
                         }
-                        else if (opts.builderSessionStrategy === "fresh") {
+                        else if (strategy === "fresh") {
                             await builder.close();
                             builder = await opts.createBuilder(worktreePath);
                         }
-                        const digest = (await withActivityPhase("recording QA fix changes", () => changeManifestAsync(worktreePath, (state, detail) => currentActivity()?.update(state, detail), "recording QA fix changes"))).diffDigest;
-                        const fixed = await builder.sendTurn(buildDurableQaFixHandoff(node.ticket, issues, worktreePath, result.text, digest));
+                        if (opts.beforeBuilderTurn)
+                            builder = await opts.beforeBuilderTurn(builder, fixInstruction, worktreePath);
+                        const fixed = await builder.sendTurn(fixInstruction);
                         const fixedStatus = parseStepStatus(fixed.text);
-                        builderStreamSession = opts.builderSessionStrategy === "compact" ? builder.sessionId() : undefined;
+                        const fixedSessionId = builder.sessionId();
+                        const fixedSessionRef = builder.sessionRef?.();
+                        if (fixedSessionId)
+                            builderStream = { sessionId: fixedSessionId, ...(fixedSessionRef ? { sessionRef: fixedSessionRef } : {}), worktreePath };
+                        if (fixedSessionId) {
+                            opts.recordBuilderSession?.(fixedSessionRef ?? fixedSessionId, node.ticket.id, worktreePath);
+                            workflowCheckpoint(opts.projectDir, opts.runId, "builder-session-scoped", node.ticket.id, { sessionId: fixedSessionId, sessionRef: fixedSessionRef, worktree: worktreePath, branch: node.branch });
+                        }
                         return { ok: !fixed.isError && fixedStatus.kind === "done", detail: fixedStatus.error ?? fixed.text.slice(0, 500) };
                     },
                     onNonconvergence: opts.qaNonconvergence,
                 });
+                if (qaStream.sessionId)
+                    opts.recordQaSession?.(qaStream.sessionRef ?? qaStream.sessionId, node.ticket.id, worktreePath);
                 workflowCheckpoint(opts.projectDir, opts.runId, "qa-after", node.ticket.id, { outcome: qa.outcome, detail: qa.detail });
                 if (qa.outcome !== "passed" && qa.outcome !== "waived") {
                     const detail = qa.detail ?? "QA did not pass";
@@ -444,6 +487,14 @@ export async function runBranchPlan(opts) {
                 removeTicketWorktree(opts.projectDir, worktreePath);
         }
         catch (err) {
+            if (err instanceof SessionUnavailableError || err instanceof SessionUnavailableContinuityError) {
+                const message = err.message;
+                opts.log.write("branch-issue", { ticket: node.ticket.id, code: "session_unavailable", message, blocking: true });
+                notifyIssue(opts.notificationsEnabled, `${node.ticket.id}: ${message}`);
+                summaries.push(summaryFor(node, "blocked", message));
+                opts.onSessionUnavailable?.(err);
+                return summaries;
+            }
             const message = err instanceof Error ? err.message : String(err);
             const code = message.includes("switched branch")
                 ? "branch_switch"
@@ -510,6 +561,7 @@ function workflowCheckpoint(projectDir, runId, checkpoint, ticket, payload) {
         if (!run)
             return;
         db.transition(runId, { checkpoint, state: { ...run.state, currentTicket: ticket, ...payload }, event: checkpoint, payload: { ticket, ...payload } });
+        db.appendContinuityEvent({ runId, role: "host", kind: checkpoint, payload: { ticket, ...payload }, authoritativeStateRevision: db.continuityHead(runId, "run")?.authoritativeStateRevision ?? 0 });
     }
     finally {
         db.close();
@@ -583,6 +635,14 @@ function autoMergePollMs() {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function canonical(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
 function notifyIssue(enabled, message) {
     if (enabled)
         fireNotification("Foreman branch issue", message);