ai-foreman 1.7.5 → 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/github.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { branchNodeFooter } from "./presentation.js";
+import { configuredReviewBody, configuredReviewTitle } from "../tickets/reviewStandards.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 15_000;
 const OUTPUT_LIMIT = 2_000;
 function runCommand(cwd, bin, args, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
@@ -134,7 +135,7 @@ export function createOrReusePr(cwd, opts) {
     const bodyPath = join(cwd, ".foreman", "pr-bodies", opts.runId, `${opts.node.ticket.id}.md`);
     try {
         mkdirSync(join(cwd, ".foreman", "pr-bodies", opts.runId), { recursive: true });
-        writeFileSync(bodyPath, buildPrBody(opts), "utf8");
+        writeFileSync(bodyPath, configuredReviewBody(cwd, opts.node, opts.qaEvidence, opts.commit), "utf8");
     }
     catch (err) {
         return prFailure(prBodyWriteFailure(opts.runId, bodyPath, err));
@@ -147,7 +148,7 @@ export function createOrReusePr(cwd, opts) {
         "--head",
         opts.node.branch,
         "--title",
-        `${opts.node.ticket.id}: ${opts.node.ticket.title}`,
+        configuredReviewTitle(cwd, opts.node.ticket),
         "--body-file",
         bodyPath,
     ];

package/dist/branch/gitlab.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { branchNodeFooter } from "./presentation.js";
+import { configuredReviewBody, configuredReviewTitle } from "../tickets/reviewStandards.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 15_000;
 const OUTPUT_LIMIT = 2_000;
 export function preflightGlab(cwd) {
@@ -55,7 +56,7 @@ export function createOrReuseMr(cwd, opts) {
     const bodyPath = join(cwd, ".foreman", "mr-bodies", opts.runId, `${opts.node.ticket.id}.md`);
     try {
         mkdirSync(join(cwd, ".foreman", "mr-bodies", opts.runId), { recursive: true });
-        writeFileSync(bodyPath, buildMrBody(opts), "utf8");
+        writeFileSync(bodyPath, configuredReviewBody(cwd, opts.node, opts.qaEvidence, opts.commit), "utf8");
     }
     catch (err) {
         return prFailure(failure("mr_create_failed", `Failed to write GitLab MR body file at ${bodyPath}.`, [
@@ -70,7 +71,7 @@ export function createOrReuseMr(cwd, opts) {
         "--target-branch",
         opts.node.baseBranch,
         "--title",
-        `${opts.node.ticket.id}: ${opts.node.ticket.title}`,
+        configuredReviewTitle(cwd, opts.node.ticket),
         "--description",
         readBodyArg(bodyPath),
         "--yes",

package/dist/branch/planner.d.ts

@@ -1,6 +1,8 @@
 import type { TicketDef } from "../tickets/ticketSchema.js";
 import type { TicketState } from "../tickets/stateDb.js";
 import type { BranchPlan } from "./types.js";
+import type { DeliveryConfig } from "../tickets/delivery.js";
+import type { TicketBuildSetupConfig } from "../tickets/setupConfig.js";
 export interface AuditDependency {
     ticket: string;
     dependsOn: string;
@@ -18,5 +20,8 @@ export interface BuildBranchPlanOptions {
 export declare function buildBranchPlan(tickets: TicketDef[], states: Map<string, TicketState>, opts: BuildBranchPlanOptions): BranchPlan;
 export declare function selectTicketsForBranchRun(tickets: TicketDef[], states: Map<string, TicketState>, steps: number, ticketIds?: string[]): TicketDef[];
 export declare function applySharedDeliveryBranch(plan: BranchPlan, unitId: string, allRemainingTicketIds: string[], branchPrefix?: string): BranchPlan;
+/** Apply branch sharing only; this deliberately never creates delivery stacks or dependency edges. */
+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 { 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));
@@ -99,11 +100,11 @@ export function selectTicketsForBranchRun(tickets, states, steps, ticketIds) {
     }
     return selected;
 }
-export function applySharedDeliveryBranch(plan, unitId, allRemainingTicketIds, branchPrefix = "rafi") {
+export function applySharedDeliveryBranch(plan, unitId, allRemainingTicketIds, branchPrefix = "feature") {
     if (plan.nodes.length === 0)
         return plan;
     const slug = unitId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "group";
-    const branch = `${branchPrefix.replace(/^\/+|\/+$/g, "") || "rafi"}/${slug}`;
+    const branch = `${normalizeBranchPrefix(branchPrefix)}/${slug}`;
     const finalSelected = plan.nodes.at(-1)?.ticket.id;
     const completesUnit = plan.nodes.length === allRemainingTicketIds.length
         && allRemainingTicketIds.every((id) => plan.nodes.some((node) => node.ticket.id === id));
@@ -118,6 +119,38 @@ export function applySharedDeliveryBranch(plan, unitId, allRemainingTicketIds, b
         })),
     };
 }
+/** Apply branch sharing only; this deliberately never creates delivery stacks or dependency edges. */
+export function applySizeBranchPolicy(plan, policy, delivery, branchPrefix = "feature") {
+    if (policy.mode !== "size" || plan.nodes.length < 2)
+        return plan;
+    const explicitlyAssigned = new Set(delivery?.units.flatMap((unit) => unit.tickets) ?? []);
+    const candidates = plan.nodes.filter((node) => policy.by_size[node.ticket.size] === "shared" && !explicitlyAssigned.has(node.ticket.id));
+    const groups = new Map();
+    for (const node of candidates) {
+        // Tickets with selected dependency edges need their existing topology. Independent
+        // tickets sharing the same base are safe to execute serially in one worktree/review.
+        if (node.dependencies.length)
+            continue;
+        const key = node.baseBranch;
+        groups.set(key, [...(groups.get(key) ?? []), node]);
+    }
+    const replacement = new Map();
+    for (const [base, nodes] of groups) {
+        if (nodes.length < 2)
+            continue;
+        const ids = nodes.map((node) => node.ticket.id.toLowerCase()).join("-");
+        const groupId = `size-small-${ids}`;
+        const branch = `${normalizeBranchPrefix(branchPrefix)}/${groupId}`.slice(0, 120).replace(/-+$/, "");
+        nodes.forEach((node, index) => replacement.set(node.ticket.id, {
+            ...node,
+            branch,
+            baseBranch: base,
+            deliveryUnitId: groupId,
+            deliveryUnitFinal: index === nodes.length - 1,
+        }));
+    }
+    return { ...plan, nodes: plan.nodes.map((node) => replacement.get(node.ticket.id) ?? node) };
+}
 export function parseAuditDependencies(text) {
     const deps = [];
     for (const line of text.split(/\r?\n/)) {
@@ -145,7 +178,7 @@ Only name dependencies where both tickets are in this selected batch. If there a
 ${body}`;
 }
 function uniqueBranchName(prefix, ticket, used) {
-    const cleanPrefix = prefix.replace(/^\/+|\/+$/g, "") || "rafi";
+    const cleanPrefix = normalizeBranchPrefix(prefix);
     const baseSlug = `${ticket.id}-${ticket.title}`
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
@@ -160,6 +193,7 @@ function uniqueBranchName(prefix, ticket, used) {
     used.add(branch);
     return branch;
 }
+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?: {