ai-foreman 1.7.6 → 1.7.8

package/dist/adapters/recovering.d.ts

@@ -1,5 +1,6 @@
 import type { AgentRuntime } from "../runtimeAuth.js";
-import type { BuilderAdapter, BuilderEvent, CompactResult, ContextUsage, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderEvent, CompactResult, ContextManagementPolicy, ContextUsage, InterruptResult, ManagedTurnDispatcher, PreparedContextManagement, ProviderSessionUsage, TurnResult } from "./types.js";
+import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 export type TurnRecoveryChoice = "retry" | "switch" | "cancel";
 export interface RecoveringAdapterOptions {
     initial: BuilderAdapter;
@@ -7,9 +8,10 @@ export interface RecoveringAdapterOptions {
     enabled: boolean;
     allowSwitch: boolean;
     label: string;
-    recreate: (runtime: AgentRuntime, resumeSessionId?: string) => Promise<BuilderAdapter>;
+    recreate: (runtime: AgentRuntime, resumeSessionId?: string, resumeSessionRef?: ProviderSessionRefV1) => Promise<BuilderAdapter>;
     choose?: (result: TurnResult, runtime: AgentRuntime, otherRuntime: AgentRuntime) => Promise<TurnRecoveryChoice>;
     onRuntimeChange?: (runtime: AgentRuntime) => void;
+    onSessionRef?: (ref: ProviderSessionRefV1) => void;
 }
 /** Adds interactive recovery around structured runtime turn failures. */
 export declare class RecoveringAdapter implements BuilderAdapter {
@@ -19,12 +21,21 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     private readonly eventQueue;
     private eventPump;
     private closed;
+    private turnDispatcher?;
     constructor(opts: RecoveringAdapterOptions);
     get agent(): "claude" | "codex";
     sendTurn(text: string): Promise<TurnResult>;
     sessionId(): string | undefined;
+    sessionRef(): ProviderSessionRefV1 | undefined;
+    adoptSessionRef(ref: ProviderSessionRefV1): void;
+    validateSession(): Promise<SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
+    prepareContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    updateContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    interruptTurnAtCompactionBoundary(providerEventId?: string): Promise<InterruptResult>;
+    installManagedTurnDispatcher(dispatcher: ManagedTurnDispatcher): void;
     contextUsage(): Promise<ContextUsage | undefined>;
+    sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
     private replaceAdapter;

package/dist/adapters/recovering.js

@@ -9,6 +9,7 @@ export class RecoveringAdapter {
     eventQueue = new AsyncQueue();
     eventPump;
     closed = false;
+    turnDispatcher;
     constructor(opts) {
         this.opts = opts;
         this.adapter = opts.initial;
@@ -20,9 +21,23 @@ export class RecoveringAdapter {
     }
     async sendTurn(text) {
         while (true) {
-            const result = await this.adapter.sendTurn(text);
+            const invoke = () => this.adapter.sendTurn(text);
+            const result = this.turnDispatcher ? await this.turnDispatcher(text, invoke) : await invoke();
+            const sessionRef = this.adapter.sessionRef?.();
+            if (sessionRef && this.opts.onSessionRef) {
+                try {
+                    this.opts.onSessionRef(sessionRef);
+                }
+                catch (error) {
+                    this.eventQueue.push({ kind: "error", message: `failed to persist scoped provider session binding: ${error instanceof Error ? error.message : String(error)}` });
+                }
+            }
             if (!this.opts.enabled || !result.isError || !result.failure)
                 return result;
+            // The host cannot know whether a missing exact session received this
+            // instruction. Never replay it or silently switch providers.
+            if (result.failure.category === "session-unavailable")
+                return result;
             const otherRuntime = this.runtime === "claude" ? "codex" : "claude";
             const choice = this.opts.choose
                 ? await this.opts.choose(result, this.runtime, otherRuntime)
@@ -38,7 +53,8 @@ export class RecoveringAdapter {
             reportBuilderEvent(recoveryEvent);
             const nextRuntime = choice === "switch" ? otherRuntime : this.runtime;
             const resumeSessionId = choice === "retry" ? this.adapter.sessionId() : undefined;
-            await this.replaceAdapter(nextRuntime, resumeSessionId);
+            const resumeSessionRef = choice === "retry" ? this.adapter.sessionRef?.() : undefined;
+            await this.replaceAdapter(nextRuntime, resumeSessionId, resumeSessionRef);
             if (choice === "switch") {
                 log.info(`Using ${nextRuntime} for the rest of this run. This is a fresh provider session; conversational continuity was not transferred.`);
             }
@@ -47,8 +63,20 @@ export class RecoveringAdapter {
     sessionId() {
         return this.adapter.sessionId();
     }
+    sessionRef() { return this.adapter.sessionRef?.(); }
+    adoptSessionRef(ref) { this.adapter.adoptSessionRef?.(ref); }
+    validateSession() {
+        return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped", detail: "wrapped adapter does not expose scoped session validation" });
+    }
     compact() { return this.adapter.compact?.() ?? Promise.resolve({ ok: false, error: "native compaction unavailable" }); }
+    prepareContextManagement(policy) { if (!this.adapter.prepareContextManagement)
+        return Promise.reject(new Error("native context management unavailable")); return this.adapter.prepareContextManagement(policy); }
+    updateContextManagement(policy) { if (!this.adapter.updateContextManagement)
+        return Promise.reject(new Error("native context reconfiguration unavailable")); return this.adapter.updateContextManagement(policy); }
+    interruptTurnAtCompactionBoundary(providerEventId) { return this.adapter.interruptTurnAtCompactionBoundary?.(providerEventId) ?? Promise.resolve({ ok: false, error: "compaction-boundary interruption unavailable", providerEventId }); }
+    installManagedTurnDispatcher(dispatcher) { this.turnDispatcher = dispatcher; }
     contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
+    sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
     events() {
         return this.eventQueue;
     }
@@ -60,10 +88,10 @@ export class RecoveringAdapter {
         await this.eventPump.catch(() => { });
         this.eventQueue.close();
     }
-    async replaceAdapter(runtime, resumeSessionId) {
+    async replaceAdapter(runtime, resumeSessionId, resumeSessionRef) {
         await this.adapter.close().catch(() => { });
         await this.eventPump.catch(() => { });
-        this.adapter = await this.opts.recreate(runtime, resumeSessionId);
+        this.adapter = await this.opts.recreate(runtime, resumeSessionId, resumeSessionRef);
         this.runtime = runtime;
         this.opts.onRuntimeChange?.(runtime);
         this.eventPump = this.forwardEvents(this.adapter);

package/dist/adapters/sessionFailure.d.ts

@@ -0,0 +1,18 @@
+import type { SessionAvailabilityV1 } from "rafi-spec";
+import type { RuntimeFailure, SessionFailurePhase, TurnDispatchState, TurnResult } from "./types.js";
+export declare class SessionUnavailableError extends Error {
+    readonly failure: RuntimeFailure;
+    constructor(input: {
+        runtime: "claude" | "codex";
+        phase: SessionFailurePhase;
+        dispatchState: TurnDispatchState;
+        executable: string;
+        cwd: string;
+        diagnostics: string;
+        availability?: SessionAvailabilityV1;
+        cause?: unknown;
+    });
+}
+export declare function sessionUnavailableResult(error: SessionUnavailableError): TurnResult;
+export declare function isSessionUnavailableFailure(value: unknown): boolean;
+export declare function sessionUnavailableErrorFromFailure(failure: RuntimeFailure): SessionUnavailableError;

package/dist/adapters/sessionFailure.js

@@ -0,0 +1,51 @@
+export class SessionUnavailableError extends Error {
+    failure;
+    constructor(input) {
+        super(input.diagnostics, input.cause === undefined ? undefined : { cause: input.cause });
+        this.name = "SessionUnavailableError";
+        this.failure = {
+            runtime: input.runtime,
+            phase: input.phase,
+            category: "session-unavailable",
+            executable: input.executable,
+            cwd: input.cwd,
+            diagnostics: input.diagnostics,
+            dispatchState: input.dispatchState,
+            ...(input.availability ? { availability: input.availability } : {}),
+        };
+    }
+}
+export function sessionUnavailableResult(error) {
+    return {
+        text: error.message,
+        isError: true,
+        numTurns: 0,
+        costUsd: 0,
+        costAuthoritative: false,
+        failure: error.failure,
+    };
+}
+export function isSessionUnavailableFailure(value) {
+    if (value instanceof SessionUnavailableError)
+        return true;
+    if (!value || typeof value !== "object")
+        return false;
+    const failure = "failure" in value ? value.failure : value;
+    return failure?.category === "session-unavailable";
+}
+export function sessionUnavailableErrorFromFailure(failure) {
+    if (failure.category !== "session-unavailable")
+        throw new Error("runtime failure is not a session-unavailable failure");
+    const phase = failure.phase === "preflight" || failure.phase === "attach" || failure.phase === "turn"
+        ? failure.phase
+        : "turn";
+    return new SessionUnavailableError({
+        runtime: failure.runtime,
+        phase,
+        dispatchState: failure.dispatchState ?? "unknown",
+        executable: failure.executable,
+        cwd: failure.cwd,
+        diagnostics: failure.diagnostics,
+        availability: failure.availability,
+    });
+}

package/dist/adapters/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Agent-agnostic interface over a coding agent ("builder").
  */
-import type { RuntimeProbeCategory, RuntimeProbePhase } from "rafi-spec";
+import type { ConfigurableAgentRole, ProviderSessionRefV1, RuntimeProbeCategory, RuntimeProbePhase, SessionAvailabilityV1 } from "rafi-spec";
 /** A permission request surfaced by a builder before it runs a tool. */
 export interface PermissionRequest {
     toolName: string;
@@ -36,21 +36,78 @@ export type PermissionDecision = {
 /** Decides each permission request. Supplied by the foreman, called by the adapter. */
 export type PermissionHandler = (req: PermissionRequest) => Promise<PermissionDecision>;
 /** Result of a single completed turn. */
+export type SessionFailurePhase = "preflight" | "attach" | "turn";
+export type TurnDispatchState = "not-sent" | "unknown";
+export interface RuntimeFailure {
+    runtime: "claude" | "codex";
+    phase: RuntimeProbePhase | SessionFailurePhase;
+    category: RuntimeProbeCategory;
+    executable: string;
+    cwd: string;
+    diagnostics: string;
+    dispatchState?: TurnDispatchState;
+    availability?: SessionAvailabilityV1;
+}
 export interface TurnResult {
     /** Final assistant message text — where the STEP_STATUS marker lives. */
     text: string;
     isError: boolean;
     numTurns: number;
     costUsd: number;
-    failure?: {
-        runtime: "claude" | "codex";
-        phase: RuntimeProbePhase;
-        category: RuntimeProbeCategory;
-        executable: string;
-        cwd: string;
-        diagnostics: string;
+    /** True only when the provider supplied this value; never inferred by Rafi. */
+    costAuthoritative?: boolean;
+    inputTokens?: number;
+    outputTokens?: number;
+    failure?: RuntimeFailure;
+    /** A provider turn stopped at a context-compaction boundary, not a failure. */
+    interrupted?: {
+        reason: "compaction-boundary";
+        providerEventId?: string;
     };
 }
+export type ContextCompactionOrigin = "provider-auto" | "rafi-manual" | "recovery" | "boundary";
+export type ContextCompactionPhase = "started" | "succeeded" | "failed";
+/** Native context policy installed before a Builder/QA role may do real work. */
+export interface ContextManagementPolicy {
+    role: "builder" | "qa";
+    configuredThresholdPercent: number;
+    compactMaximum: number;
+    settingsRevision: number;
+    model: string;
+    /** Continue a provider-monotonic sequence after process recovery. */
+    providerSequenceStart?: number;
+    /** A persisted, model-matched maximum may avoid a discovery turn. */
+    knownModelContextWindow?: number;
+    /** Native compaction stays enabled until the host vetoes a boundary. */
+    nativeCompactionEnabled?: boolean;
+}
+export interface PreparedContextManagement {
+    modelContextWindow: number;
+    configuredTokenLimit: number;
+    installedNativeTokenLimit: number;
+    installedNativePercent: number;
+    sample?: ContextUsage;
+}
+export interface ContextCompactionEvent {
+    kind: "context-compaction";
+    phase: ContextCompactionPhase;
+    origin: ContextCompactionOrigin;
+    providerEventId: string;
+    providerSequence: number;
+    provider: "claude" | "codex";
+    sessionId?: string;
+    sessionRef?: ProviderSessionRefV1;
+    observedAt: string;
+    postCompactSample?: ContextUsage;
+    reason?: string;
+}
+export interface InterruptResult {
+    ok: boolean;
+    error?: string;
+    providerEventId?: string;
+}
+/** Host-owned gate used by wrappers that need additional provider turns. */
+export type ManagedTurnDispatcher = (text: string, invoke: () => Promise<TurnResult>) => Promise<TurnResult>;
 /** Observability events emitted while a builder works. */
 export type BuilderEvent = {
     kind: "text";
@@ -86,7 +143,12 @@ export type BuilderEvent = {
     used: number;
     maximum?: number;
     percentage?: number;
-} | {
+    observedAt?: string;
+    source?: "provider-event" | "provider-query" | "post-compact";
+    sequence?: number;
+    sessionId?: string;
+    model?: string;
+} | ContextCompactionEvent | {
     kind: "error";
     message: string;
 };
@@ -94,10 +156,26 @@ export interface ContextUsage {
     used: number;
     maximum?: number;
     percentage?: number;
+    observedAt?: string;
+    source?: "provider-event" | "provider-query" | "post-compact";
+    /** Monotonic within one scoped provider session. */
+    sequence?: number;
+    sessionId?: string;
+    model?: string;
+}
+export interface ProviderSessionUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    authoritativeCostUsd?: number;
+    observedAt: string;
+    source: "provider" | "turn-aggregate";
 }
 export interface CompactResult {
     ok: boolean;
     error?: string;
+    /** Preserve exact-session loss so lifecycle policy never treats it as an ordinary retryable compaction failure. */
+    failure?: RuntimeFailure;
 }
 export interface ProviderSettingSwitch {
     model?: string;
@@ -115,7 +193,19 @@ export interface BuilderAdapterOptions {
     /** Permission decision callback. */
     permission: PermissionHandler;
     /** Resume a prior session instead of starting fresh. */
+    /** @deprecated Foreman-controlled recovery must use resumeSessionRef. */
     resumeSessionId?: string;
+    /** Location-scoped provider conversation to validate before exact resume. */
+    resumeSessionRef?: ProviderSessionRefV1;
+    /** Canonical Rafi configuration/recovery root. Defaults to cwd for compatibility callers. */
+    configRoot?: string;
+    /** Metadata used when the provider first reveals a fresh session identity. */
+    sessionRole?: ConfigurableAgentRole;
+    sessionStream?: string;
+    sessionGeneration?: number;
+    workspaceIdentity?: string;
+    ticketId?: string;
+    deliveryUnitId?: string;
     /** Override the model; omit for the agent's default. */
     model?: string;
     /** Reasoning effort level. Claude also accepts "max"; Codex supports up to "xhigh". */
@@ -128,6 +218,8 @@ export interface BuilderAdapterOptions {
     systemPromptAppend?: string;
     /** Skill names to preload for this session (Claude: lazy-loaded; Codex: flattened). */
     skills?: string[];
+    /** Builder/QA native policy used even for setup and handoff-acceptance turns. */
+    contextManagementPolicy?: ContextManagementPolicy;
 }
 export interface BuilderAdapter {
     readonly agent: "claude" | "codex";
@@ -135,10 +227,26 @@ export interface BuilderAdapter {
     sendTurn(text: string): Promise<TurnResult>;
     /** Current session id, once known — used for resume. */
     sessionId(): string | undefined;
+    /** Current location-scoped session reference, once known. */
+    sessionRef?(): ProviderSessionRefV1 | undefined;
+    /** Host-only metadata promotion after a validated handoff is accepted. */
+    adoptSessionRef?(ref: ProviderSessionRefV1): void;
+    /** Attach/probe a requested exact session without starting a provider turn. */
+    validateSession?(): Promise<SessionAvailabilityV1>;
     /** Provider-native compaction on the exact live conversation. */
     compact?(): Promise<CompactResult>;
+    /** Initialize the session and install native in-turn context controls. */
+    prepareContextManagement?(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    /** Safely reconfigure native in-turn controls on the same session. */
+    updateContextManagement?(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    /** Stop only at a provider-observed compaction boundary. */
+    interruptTurnAtCompactionBoundary?(providerEventId?: string): Promise<InterruptResult>;
+    /** Route wrapper-owned repair/retry/follow-up turns through the role gate. */
+    installManagedTurnDispatcher?(dispatcher: ManagedTurnDispatcher): void;
     /** Truthful provider context occupancy, when exposed by the provider. */
     contextUsage?(): Promise<ContextUsage | undefined>;
+    /** Provider/session cumulative totals; distinct from live context occupancy. */
+    sessionUsage?(): Promise<ProviderSessionUsage | undefined>;
     /** Attempt a provider-supported in-conversation model/reasoning transition. */
     switchSettings?(settings: ProviderSettingSwitch): Promise<CompactResult>;
     /** Stream of observability events. Iterate to drive a live view. */

package/dist/agentRun.d.ts

@@ -5,7 +5,7 @@ import type { BuilderAdapter, BuilderAdapterOptions, EffortLevel, TurnResult } f
 import type { AnsweredProviderQuestion } from "./providerQuestions.js";
 import { type RoleBundle } from "./roles.js";
 import type { AgentRuntime } from "./runtimeAuth.js";
-import type { AgentRoleDefaultsV1 } from "rafi-spec";
+import type { AgentRoleDefaultsV1, ProviderSessionRefV1 } from "rafi-spec";
 export type { EffortLevel } from "./adapters/types.js";
 export declare const VALID_EFFORT: readonly EffortLevel[];
 export interface RoleBuilderOptions {
@@ -23,6 +23,8 @@ export interface RoleBuilderOptions {
     extraSkills?: string[];
     sandboxMode?: BuilderAdapterOptions["sandboxMode"];
     resumeSessionId?: string;
+    /** Location-scoped exact session. Raw IDs are resolved through durable project bindings or treated as legacy candidates. */
+    resumeSessionRef?: ProviderSessionRefV1;
     /** Observe successfully answered provider-native questions. */
     onAnsweredQuestion?: (event: AnsweredProviderQuestion) => void;
     /** Observe any provider-native question attempt, including denied prompts. */
@@ -51,6 +53,7 @@ export interface RoleInstructionRunResult {
     model?: string;
     effort?: EffortLevel;
     sessionId?: string;
+    sessionRef?: ProviderSessionRefV1;
     logPath: string;
     roleBundle: RoleBundle;
     skills: string[];

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,38 @@
+import type { BuilderAdapter, BuilderEvent, CompactResult, ContextManagementPolicy, ContextUsage, InterruptResult, ManagedTurnDispatcher, PreparedContextManagement, 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>;
+    prepareContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    updateContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    interruptTurnAtCompactionBoundary(providerEventId?: string): Promise<InterruptResult>;
+    installManagedTurnDispatcher(dispatcher: ManagedTurnDispatcher): void;
+    contextUsage(): Promise<ContextUsage | undefined>;
+    sessionUsage(): Promise<ProviderSessionUsage | undefined>;
+    switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
+    events(): AsyncIterable<BuilderEvent>;
+    close(): Promise<void>;
+}