ai-foreman 1.7.6 → 1.7.8

package/dist/branch/currentGuard.js

@@ -0,0 +1,71 @@
+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; }
+    async prepareContextManagement(policy) { assertCurrentWorkflowIdentity(this.cwd, this.expected); if (!this.adapter.prepareContextManagement)
+        throw new Error("native context management unavailable"); const result = await this.adapter.prepareContextManagement(policy); assertCurrentWorkflowIdentity(this.cwd, this.expected); return result; }
+    async updateContextManagement(policy) { assertCurrentWorkflowIdentity(this.cwd, this.expected); if (!this.adapter.updateContextManagement)
+        throw new Error("native context reconfiguration unavailable"); const result = await this.adapter.updateContextManagement(policy); assertCurrentWorkflowIdentity(this.cwd, this.expected); return result; }
+    interruptTurnAtCompactionBoundary(providerEventId) { return this.adapter.interruptTurnAtCompactionBoundary?.(providerEventId) ?? Promise.resolve({ ok: false, error: "compaction-boundary interruption unavailable", providerEventId }); }
+    installManagedTurnDispatcher(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?.(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);

package/dist/buildRuns.d.ts

@@ -1,4 +1,5 @@
-import type { BuildRunRecordV2, ResolvedAgentSettings } from "rafi-spec";
+import type { BuildRunRecordV2, ProviderSessionRefV1, ResolvedAgentSettings, SessionAvailabilityV1 } from "rafi-spec";
+import { type ResolveSessionAvailabilityOptions } from "./sessionAvailability.js";
 export declare const BUILD_RUN_VERSION = 2;
 export declare const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export declare const BUILD_HEARTBEAT_MS = 10000;
@@ -15,6 +16,7 @@ export interface CreateBuildRunInput {
     startHead?: string;
     builder?: LegacyResolvedAgentSettings;
     qa?: LegacyResolvedAgentSettings;
+    runDecisions?: BuildRunRecordV2["runDecisions"];
     now?: Date;
 }
 export declare function createBuildRun(input: CreateBuildRunInput): BuildRunRecordV2;
@@ -22,11 +24,14 @@ export declare function resumeBuildRun(projectDir: string, runId: string, patch:
     builder?: LegacyResolvedAgentSettings;
     qa?: LegacyResolvedAgentSettings;
     builderSessionId?: string | null;
+    builderSessionRef?: ProviderSessionRefV1 | null;
 }, now?: Date): BuildRunRecordV2;
-type LegacyResolvedAgentSettings = Omit<ResolvedAgentSettings, "session_strategy" | "settings_revision"> & Partial<Pick<ResolvedAgentSettings, "session_strategy" | "settings_revision">>;
+type LegacyResolvedAgentSettings = Omit<ResolvedAgentSettings, "session_strategy" | "settings_revision" | "display_session_cost" | "auto_compact_threshold_percent" | "compact_maximum"> & Partial<Pick<ResolvedAgentSettings, "session_strategy" | "settings_revision" | "display_session_cost" | "auto_compact_threshold_percent" | "compact_maximum">>;
 export declare function saveBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
 export declare function checkpointBuildRun(projectDir: string, run: BuildRunRecordV2, checkpoint: string, patch?: Partial<BuildRunRecordV2>): BuildRunRecordV2;
-export declare function persistBuildSession(projectDir: string, run: BuildRunRecordV2, role: "builder" | "qa", sessionId: string): BuildRunRecordV2;
+export declare function persistBuildSession(projectDir: string, run: BuildRunRecordV2, role: "builder" | "qa", session: string | ProviderSessionRefV1): BuildRunRecordV2;
+/** Latest scoped binding, with the narrow legacy Builder inference allowed by the recovery protocol. */
+export declare function buildRunSessionBinding(run: BuildRunRecordV2, role: "builder" | "qa", sessionId?: string): ProviderSessionRefV1 | undefined;
 export declare function recordBuildReceipt(projectDir: string, run: BuildRunRecordV2, operationId: string, detail?: {
     externalId?: string;
     detail?: string;
@@ -60,7 +65,11 @@ export interface BuildRecoveryProjection {
     worktree: string;
     branch?: string;
     exactSessionId?: string;
+    exactSessionRef?: ProviderSessionRefV1;
+    sessionCandidateRef?: ProviderSessionRefV1;
+    sessionAvailability?: SessionAvailabilityV1;
 }
-export declare function projectBuildRecovery(projectDir: string, run: BuildRunRecordV2, now?: Date, ticketOverride?: string): BuildRecoveryProjection;
+export declare function projectBuildRecovery(projectDir: string, run: BuildRunRecordV2, now?: Date, ticketOverride?: string, sessionAvailability?: SessionAvailabilityV1): BuildRecoveryProjection;
+export declare function resolveBuildRecoveryProjection(projectDir: string, run: BuildRunRecordV2, now?: Date, ticketOverride?: string, probe?: ResolveSessionAvailabilityOptions): Promise<BuildRecoveryProjection>;
 export declare function formatBuildRecoveryProjection(projection: BuildRecoveryProjection): string[];
 export {};