ai-foreman 1.7.6 → 1.7.7

package/dist/adapters/codex.js

@@ -5,6 +5,8 @@ import { createInterface } from "node:readline";
 import { loadSkill } from "special-agents";
 import { BuilderEventQueue, withActivityPhase } from "../activity.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
+import { canonicalSessionPath, createProviderSessionRef, validateProviderSessionScope } from "../sessionIdentity.js";
+import { SessionUnavailableError, sessionUnavailableResult } from "./sessionFailure.js";
 /** Compatibility parser for recorded pre-app-server JSONL fixtures. */
 export function parseCodexLine(raw) {
     const type = raw.type;
@@ -31,14 +33,20 @@ export class CodexAdapter {
     pending = new Map();
     notificationWaiters = new Map();
     _sessionId;
+    _sessionRef;
+    sessionAvailability;
     initialized = false;
     closed = false;
     activeText = [];
     usage;
+    usageRevision = 0;
+    providerSessionUsage;
+    lastTurnTokens;
     stderr = "";
     constructor(opts) {
         this.opts = opts;
-        this._sessionId = opts.resumeSessionId;
+        this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
+        this._sessionRef = opts.resumeSessionRef;
     }
     buildInstruction(instruction) {
         return [this.opts.systemPromptAppend, this.buildSkillsAppendix(), instruction]
@@ -66,10 +74,13 @@ export class CodexAdapter {
         if (this.closed)
             throw new Error("builder is closed");
         this.eventQueue.push({ kind: "activity", state: "starting Codex turn", provider: "codex", model: this.opts.model });
+        let turnStartDispatched = false;
         try {
             await this.ensureThread();
             this.activeText = [];
+            this.lastTurnTokens = undefined;
             const completion = this.waitFor("turn/completed", (params) => params.threadId === this._sessionId);
+            turnStartDispatched = true;
             await this.request("turn/start", {
                 threadId: this._sessionId,
                 input: [{ type: "text", text: this.buildInstruction(instruction), text_elements: [] }],
@@ -82,15 +93,32 @@ export class CodexAdapter {
             const failed = turn?.status === "failed";
             const error = turn?.error;
             const text = this.activeText.join("\n");
-            const result = { text: failed ? normalizeRuntimeErrorText("codex", String(error?.message ?? text), null, "app-server turn") : text, isError: failed, numTurns: 1, costUsd: 0 };
+            const result = {
+                text: failed ? normalizeRuntimeErrorText("codex", String(error?.message ?? text), null, "app-server turn") : text,
+                isError: failed, numTurns: 1, costUsd: 0, costAuthoritative: false,
+                ...(this.lastTurnTokens ?? {}),
+            };
             this.eventQueue.push({ kind: "turn-complete", result });
             return result;
         }
         catch (error) {
+            if (error instanceof SessionUnavailableError) {
+                const result = sessionUnavailableResult(error);
+                this.eventQueue.push({ kind: "error", message: result.text });
+                this.eventQueue.push({ kind: "turn-complete", result });
+                return result;
+            }
             const detail = [error instanceof Error ? error.message : String(error), this.stderr].filter(Boolean).join("\n");
             const text = normalizeRuntimeErrorText("codex", detail, this.process?.exitCode ?? null, "builder turn");
             this.disconnect(new Error(text));
-            const result = { text, isError: true, numTurns: 1, costUsd: 0 };
+            const resumed = Boolean(this.opts.resumeSessionRef);
+            const result = resumed
+                ? sessionUnavailableResult(new SessionUnavailableError({
+                    runtime: "codex", phase: turnStartDispatched ? "turn" : "attach", dispatchState: turnStartDispatched ? "unknown" : "not-sent",
+                    executable: this.opts.runtimeExecutable ?? "codex", cwd: this.opts.cwd, diagnostics: text,
+                    availability: { version: 1, status: turnStartDispatched ? "unknown" : "unavailable", checkedAt: new Date().toISOString(), reason: turnStartDispatched ? "probe-failed" : "attach-failed", detail: text, sessionRef: this.opts.resumeSessionRef },
+                }))
+                : { text, isError: true, numTurns: 1, costUsd: 0, costAuthoritative: false };
             this.eventQueue.push({ kind: "error", message: text });
             this.eventQueue.push({ kind: "turn-complete", result });
             return result;
@@ -100,21 +128,37 @@ export class CodexAdapter {
         try {
             await this.ensureThread();
             this.eventQueue.push({ kind: "session-transition", transition: "compacting" });
+            const usageRevision = this.usageRevision;
+            // A pre-compaction observation must never be mistaken for proof that the
+            // provider reduced the live context. The app server emits a fresh token
+            // usage notification for the compacted thread; require it alongside the
+            // explicit contextCompaction completion item.
+            this.usage = undefined;
             const done = this.waitFor("item/completed", (params) => {
                 const item = params.item;
                 return params.threadId === this._sessionId && item?.type === "contextCompaction";
-            });
-            await this.request("thread/compact/start", { threadId: this._sessionId });
-            await done;
-            this.usage = undefined;
+            }, 30_000);
+            const postCompactUsage = this.waitFor("thread/tokenUsage/updated", (params) => {
+                return (params.threadId === undefined || params.threadId === this._sessionId)
+                    && this.usageRevision > usageRevision
+                    && this.usage !== undefined;
+            }, 30_000);
+            await Promise.all([
+                this.request("thread/compact/start", { threadId: this._sessionId }),
+                done,
+                postCompactUsage,
+            ]);
             this.eventQueue.push({ kind: "session-transition", transition: "compacted" });
             return { ok: true };
         }
         catch (error) {
+            if (error instanceof SessionUnavailableError)
+                return { ok: false, error: error.message, failure: error.failure };
             return { ok: false, error: error instanceof Error ? error.message : String(error) };
         }
     }
     async contextUsage() { return this.usage; }
+    async sessionUsage() { return this.providerSessionUsage ? { ...this.providerSessionUsage } : undefined; }
     async switchSettings(settings) {
         this.opts.model = settings.model;
         this.opts.effort = settings.effort;
@@ -122,6 +166,26 @@ export class CodexAdapter {
         return { ok: true };
     }
     sessionId() { return this._sessionId; }
+    sessionRef() { return this._sessionRef; }
+    adoptSessionRef(ref) {
+        if (ref.provider !== "codex" || ref.sessionId !== this._sessionId)
+            throw new Error("cannot adopt a session reference for a different Codex thread");
+        this._sessionRef = ref;
+    }
+    async validateSession() {
+        const checkedAt = new Date().toISOString();
+        if (!this._sessionRef)
+            return { version: 1, status: "unknown", checkedAt, reason: "legacy-unscoped", detail: "Codex raw thread IDs cannot be declared exact without a stored location scope" };
+        try {
+            await this.ensureThread();
+            return this.sessionAvailability ?? { version: 1, status: "available", checkedAt, observedCwd: canonicalSessionPath(this.opts.cwd), sessionRef: this._sessionRef };
+        }
+        catch (error) {
+            if (error instanceof SessionUnavailableError && error.failure.availability)
+                return error.failure.availability;
+            return { version: 1, status: "unknown", checkedAt, reason: "probe-failed", detail: error instanceof Error ? error.message : String(error), sessionRef: this._sessionRef };
+        }
+    }
     events() { return this.eventQueue; }
     async close() {
         if (this.closed)
@@ -131,20 +195,93 @@ export class CodexAdapter {
         this.eventQueue.close();
     }
     async ensureThread() {
+        if (this._sessionRef && !this.threadAttached) {
+            if (this._sessionRef.source === "legacy-inferred") {
+                const availability = { version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped", detail: "legacy Codex thread IDs cannot be proven exact without an observed scoped binding", sessionRef: this._sessionRef };
+                this.sessionAvailability = availability;
+                throw new SessionUnavailableError({ runtime: "codex", phase: "preflight", dispatchState: "not-sent", executable: this.opts.runtimeExecutable ?? "codex", cwd: this.opts.cwd, diagnostics: availability.detail, availability });
+            }
+            const scoped = validateProviderSessionScope(this._sessionRef, {
+                provider: "codex", cwd: this.opts.cwd, configRoot: this.opts.configRoot ?? this.opts.cwd,
+                role: this.opts.sessionRole ?? this._sessionRef.role, stream: this.opts.sessionStream ?? this._sessionRef.stream,
+                workspaceIdentity: this.opts.workspaceIdentity, ticketId: this.opts.ticketId, deliveryUnitId: this.opts.deliveryUnitId,
+            });
+            if (scoped.status !== "available" || !scoped.sessionRef) {
+                this.sessionAvailability = scoped;
+                throw new SessionUnavailableError({
+                    runtime: "codex", phase: "preflight", dispatchState: "not-sent", executable: this.opts.runtimeExecutable ?? "codex",
+                    cwd: this.opts.cwd, diagnostics: scoped.detail ?? `Codex session ${this._sessionRef.sessionId} is ${scoped.status}`, availability: scoped,
+                });
+            }
+            this._sessionRef = scoped.sessionRef;
+        }
         await this.ensureConnection();
         if (this._sessionId && this.initialized === true && this.threadAttached)
             return;
         const method = this._sessionId ? "thread/resume" : "thread/start";
-        const result = await this.request(method, {
-            ...(this._sessionId ? { threadId: this._sessionId } : {}), cwd: this.opts.cwd,
-            model: this.opts.model ?? null, approvalPolicy: "never",
-            sandbox: this.opts.sandboxMode === "read-only" ? "read-only" : "workspace-write",
-            developerInstructions: this.opts.systemPromptAppend ?? null,
-        });
+        let result;
+        try {
+            result = await this.request(method, {
+                ...(this._sessionId ? { threadId: this._sessionId } : {}), cwd: this.opts.cwd,
+                model: this.opts.model ?? null, approvalPolicy: "never",
+                sandbox: this.opts.sandboxMode === "read-only" ? "read-only" : "workspace-write",
+                developerInstructions: this.opts.systemPromptAppend ?? null,
+            });
+        }
+        catch (error) {
+            if (this._sessionRef) {
+                const detail = error instanceof Error ? error.message : String(error);
+                const availability = {
+                    version: 1, status: "unavailable", checkedAt: new Date().toISOString(),
+                    reason: /not found|unknown thread|no thread/i.test(detail) ? "not-found" : "attach-failed", detail, sessionRef: this._sessionRef,
+                };
+                this.sessionAvailability = availability;
+                throw new SessionUnavailableError({ runtime: "codex", phase: "attach", dispatchState: "not-sent", executable: this.opts.runtimeExecutable ?? "codex", cwd: this.opts.cwd, diagnostics: detail, availability, cause: error });
+            }
+            throw error;
+        }
         const thread = result.thread;
-        this._sessionId = String(thread?.id ?? this._sessionId ?? "") || undefined;
+        const returnedSessionId = String(thread?.id ?? this._sessionId ?? "") || undefined;
+        if (this._sessionRef && returnedSessionId !== this._sessionRef.sessionId) {
+            const availability = {
+                version: 1,
+                status: "unavailable",
+                checkedAt: new Date().toISOString(),
+                reason: "attach-failed",
+                detail: `Codex resumed thread ${returnedSessionId ?? "without an ID"} instead of requested thread ${this._sessionRef.sessionId}`,
+                sessionRef: this._sessionRef,
+            };
+            this.sessionAvailability = availability;
+            throw new SessionUnavailableError({
+                runtime: "codex",
+                phase: "attach",
+                dispatchState: "not-sent",
+                executable: this.opts.runtimeExecutable ?? "codex",
+                cwd: this.opts.cwd,
+                diagnostics: availability.detail,
+                availability,
+            });
+        }
+        this._sessionId = returnedSessionId;
         if (!this._sessionId)
             throw new Error(`${method} did not return a thread ID`);
+        const providerCwd = typeof thread?.cwd === "string" ? canonicalSessionPath(thread.cwd) : undefined;
+        if (this._sessionRef && providerCwd && providerCwd !== canonicalSessionPath(this._sessionRef.cwd)) {
+            const availability = { version: 1, status: "unavailable", checkedAt: new Date().toISOString(), reason: "cwd-mismatch", observedCwd: providerCwd, detail: `Codex thread cwd ${providerCwd} does not match ${this._sessionRef.cwd}`, sessionRef: this._sessionRef };
+            this.sessionAvailability = availability;
+            throw new SessionUnavailableError({ runtime: "codex", phase: "attach", dispatchState: "not-sent", executable: this.opts.runtimeExecutable ?? "codex", cwd: this.opts.cwd, diagnostics: availability.detail, availability });
+        }
+        if (!this._sessionRef) {
+            this._sessionRef = createProviderSessionRef({
+                provider: "codex", sessionId: this._sessionId, cwd: providerCwd ?? this.opts.cwd, configRoot: this.opts.configRoot ?? this.opts.cwd,
+                role: this.opts.sessionRole, stream: this.opts.sessionStream, generation: this.opts.sessionGeneration,
+                workspaceIdentity: this.opts.workspaceIdentity, ticketId: this.opts.ticketId, deliveryUnitId: this.opts.deliveryUnitId,
+            });
+        }
+        else {
+            this._sessionRef = { ...this._sessionRef, validatedAt: new Date().toISOString() };
+        }
+        this.sessionAvailability = { version: 1, status: "available", checkedAt: new Date().toISOString(), observedCwd: providerCwd ?? canonicalSessionPath(this.opts.cwd), sessionRef: this._sessionRef };
         this.threadAttached = true;
         this.eventQueue.push({ kind: "session-transition", transition: method === "thread/resume" ? "resumed" : "started" });
     }
@@ -233,10 +370,25 @@ export class CodexAdapter {
         else if (message.method === "thread/tokenUsage/updated") {
             const tokenUsage = params.tokenUsage;
             const total = tokenUsage?.total;
-            const used = Number(total?.totalTokens ?? 0);
-            const maximum = Number(tokenUsage?.modelContextWindow ?? 0) || undefined;
-            this.usage = { used, maximum, ...(maximum ? { percentage: used / maximum * 100 } : {}) };
-            this.eventQueue.push({ kind: "context-usage", ...this.usage });
+            const last = tokenUsage?.last;
+            const used = Number(total?.totalTokens);
+            const maximum = Number(tokenUsage?.modelContextWindow);
+            const observedAt = new Date().toISOString();
+            const totalInput = optionalNonNegative(total?.inputTokens);
+            const totalOutput = optionalNonNegative(total?.outputTokens);
+            const sessionTotal = optionalNonNegative(total?.totalTokens);
+            if (totalInput !== undefined || totalOutput !== undefined || sessionTotal !== undefined) {
+                this.providerSessionUsage = { inputTokens: totalInput, outputTokens: totalOutput, totalTokens: sessionTotal, observedAt, source: "provider" };
+            }
+            this.lastTurnTokens = {
+                inputTokens: optionalNonNegative(last?.inputTokens),
+                outputTokens: optionalNonNegative(last?.outputTokens),
+            };
+            if (Number.isFinite(used) && used >= 0 && Number.isFinite(maximum) && maximum > 0) {
+                this.usage = { used, maximum, percentage: used / maximum * 100, observedAt, source: "provider-event" };
+                this.usageRevision += 1;
+                this.eventQueue.push({ kind: "context-usage", ...this.usage });
+            }
         }
         else if (message.method === "error") {
             const error = params.error;
@@ -252,8 +404,27 @@ export class CodexAdapter {
             waiter.predicate(params) ? waiter.resolve(params) : remaining.push(waiter);
         this.notificationWaiters.set(message.method, remaining);
     }
-    waitFor(method, predicate) {
-        return new Promise((resolve, reject) => { const waiters = this.notificationWaiters.get(method) ?? []; waiters.push({ predicate, resolve, reject }); this.notificationWaiters.set(method, waiters); });
+    waitFor(method, predicate, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            let timeout;
+            const waiter = {
+                predicate,
+                resolve: (params) => { if (timeout)
+                    clearTimeout(timeout); resolve(params); },
+                reject: (error) => { if (timeout)
+                    clearTimeout(timeout); reject(error); },
+            };
+            const waiters = this.notificationWaiters.get(method) ?? [];
+            waiters.push(waiter);
+            this.notificationWaiters.set(method, waiters);
+            if (timeoutMs !== undefined) {
+                timeout = setTimeout(() => {
+                    const active = this.notificationWaiters.get(method) ?? [];
+                    this.notificationWaiters.set(method, active.filter((candidate) => candidate !== waiter));
+                    reject(new Error(`Timed out waiting for Codex app-server notification ${method}`));
+                }, timeoutMs);
+            }
+        });
     }
     disconnect(error) {
         const child = this.process;
@@ -277,6 +448,10 @@ export class CodexAdapter {
         return blocks.length ? ["# Preloaded Skills", "Use the following skills for this run.", ...blocks].join("\n\n") : undefined;
     }
 }
+function optionalNonNegative(value) {
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
 function activityPhase(phase) {
     if (phase === "planning")
         return "planning";

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, ContextUsage, 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 {
@@ -23,8 +25,12 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     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>;
     contextUsage(): Promise<ContextUsage | undefined>;
+    sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
     private replaceAdapter;

package/dist/adapters/recovering.js

@@ -21,8 +21,21 @@ export class RecoveringAdapter {
     async sendTurn(text) {
         while (true) {
             const result = await this.adapter.sendTurn(text);
+            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 +51,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 +61,14 @@ 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" }); }
     contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
+    sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
     events() {
         return this.eventQueue;
     }
@@ -60,10 +80,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,20 +36,29 @@ 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;
 }
 /** Observability events emitted while a builder works. */
 export type BuilderEvent = {
@@ -86,6 +95,8 @@ export type BuilderEvent = {
     used: number;
     maximum?: number;
     percentage?: number;
+    observedAt?: string;
+    source?: "provider-event" | "provider-query" | "post-compact";
 } | {
     kind: "error";
     message: string;
@@ -94,10 +105,22 @@ export interface ContextUsage {
     used: number;
     maximum?: number;
     percentage?: number;
+    observedAt?: string;
+    source?: "provider-event" | "provider-query" | "post-compact";
+}
+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 +138,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". */
@@ -135,10 +170,18 @@ 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>;
     /** 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[];