ai-foreman 1.7.5 → 1.7.7

package/README.md

@@ -105,15 +105,17 @@ What each part does:
 | `-y, --yes` | flag | off | Skips preflight confirmation. |
 | `--no-qa` | flag | QA on | Disables per-ticket QA review. |
 | `--continue` | flag | off | Resumes the most recent logged session. |
-| `-r, --resume <sessionId>` | session ID from `.foreman/` logs | none | Resumes a specific Claude/Codex session. |
+| `-r, --resume <sessionId>` | session ID with a stored scoped binding | none | Resumes only after provider, canonical worktree, and workspace identity validation. |
 | `--branch-per-ticket` | flag | off | Runs each selected structured ticket in its own git worktree and branch. Requires initialized `.tickets/`. |
 | `--create-pr` | flag | off | Pushes each successful ticket branch and creates a GitHub PR. Implies `--branch-per-ticket`. |
 | `--pr-ready` | flag | draft PRs | Creates ready-for-review PRs instead of draft PRs when used with `--create-pr`. |
 | `--keep-worktrees` | flag | remove successful worktrees | Keeps successful ticket worktrees for inspection. Blocked worktrees are kept automatically. |
 | `--ticket <id>` | `T001` | none | Selects a branch-mode ticket to continue. Repeatable with `--continue`. |
 | `--base <ref>` | `main` / `origin/main` / `HEAD` | current branch or `HEAD` | Base ref for root ticket branches. |
-| `--branch-prefix <prefix>` | `rafi` / `feature` | `rafi` | Prefix for generated ticket branches. |
+| `--branch-prefix <prefix>` | `feature` / `rafi` / another valid Git prefix | `feature` | Prefix for generated ticket branches. Explicit prefixes are preserved verbatim. |
 | `--max-branch-depth <n>` | positive integer | `5` | Maximum selected branch/PR stack depth (root PR is depth 1). |
+| `--show-session-cost` / `--hide-session-cost` | flags | saved role preferences | Show authoritative provider cost or trustworthy cumulative tokens for Builder and QA; does not change context occupancy display. |
+| `--auto-compact-threshold <percent>` | integer `1`–`99` | saved Builder value, then `50` | Initial run threshold override. A newer persistent settings revision wins at the next safe boundary. |
 
 Auto-detected tracker files:
 
@@ -124,6 +126,7 @@ Auto-detected tracker files:
 Resume rule:
 
 - Use either `--continue` or `--resume`.
+- Exact resume requires the original canonical worktree and its recorded identity. A deleted, recreated, cross-worktree, ambiguous, or unverifiable session is rejected with fresh/handoff recovery guidance.
 - Do not use both in the same command.
 - In branch mode, use `--continue --ticket <id>` to continue a ticket with its saved builder session.
 - For multiple branch tickets, repeat `--ticket` with `--continue`; do not reuse one explicit `--resume <sessionId>` across multiple tickets.
@@ -141,6 +144,10 @@ ai-foreman start ./my-project --steps 1 --branch-per-ticket --continue --ticket
 
 Saved `tickets.build` defaults in `rafi-config.yaml` can enable branch-per-ticket and completion behavior automatically. Use `--completion pr|auto-merge|direct-merge|none`, `--no-branch-per-ticket`, `--no-create-pr`, or `--auto-merge-wait` / `--no-auto-merge-wait` to override saved defaults for one run.
 
+With the saved `current` strategy, Foreman works in the active branch while the user owns Git. It may edit, test, run QA, and update tracker/recovery state, but all branch/worktree, commit, push, merge, rebase, and review lifecycle commands are fenced. An unexpected active ref or worktree change pauses the run. Explicit isolated flags are reported as run overrides.
+
+The active terminal line always includes the current role/provider, activity, truthful context state, successful compaction count, and handoff generation. At the Builder threshold, Foreman settles the in-flight action, verifies native compaction plus a fresh provider usage sample, and resumes the frozen action. The configured maximum defaults to ten successful compactions per location-scoped provider session; the next crossing uses a validated fresh handoff instead of exceeding it. Disposable QA snapshots never reuse a prior QA conversation in a new `/tmp/rafi-qa-*` worktree; they transfer cumulative state through an accepted handoff.
+
 ### GitHub PR Failure Recovery
 
 When `--create-pr` cannot prepare GitHub, push a branch, or create a PR, Foreman records a structured failure and blocks the affected ticket cleanly. Blocked worktrees are retained automatically so you can repair the environment and retry without losing the ticket session.
@@ -502,8 +509,14 @@ ai-foreman tickets accept-future-work 1 --project ./my-project --ticket-id T051
 ai-foreman tickets cancel T001 --project ./my-project --summary "Superseded by T002"
 ai-foreman tickets reorder T051 --project ./my-project --after T050
 ai-foreman tickets archive --project ./my-project --older-than-days 30
+
+# Inspect immutable creation groups and reset an exact approved group
+ai-foreman tickets groups list --project ./my-project
+ai-foreman tickets reset --group TG-3 --project ./my-project
 ```
 
+Ticket creation groups use stable repository-local IDs (`TG-1`, `TG-2`, …); newest-first list position is separate and may change. Missing definitions remain immutable members with a validated recovery snapshot. Non-interactive group restoration requires an explicit deleted-ticket policy, and missing dependency definitions stop the reset atomically.
+
 ## How The Loop Works
 
 Before implementation starts:
@@ -514,6 +527,8 @@ Before implementation starts:
 
 Every implementation turn must end with exactly one marker.
 
+Builder and QA turns also publish a bounded cumulative continuity delta. Automatic fresh transitions stage a versioned JSON/Markdown handoff, require `HANDOFF_ACCEPTED` plus a valid successor checkpoint, and only then move the role lease. The all-in-one `rafi` CLI exposes durable handoff inspection and cache/history maintenance commands.
+
 Marker rules:
 
 - Put the marker on the final non-empty line.

package/dist/activity.d.ts

@@ -34,6 +34,7 @@ export declare class ActivityReporter {
     private lastHeartbeatAt;
     private lineVisible;
     private paused;
+    private agentStatusLine?;
     constructor(command: string, options?: ActivityReporterOptions);
     begin(label: string): () => void;
     update(state: string, detail?: string, metadata?: {
@@ -44,6 +45,8 @@ export declare class ActivityReporter {
     pulse(detail?: string): void;
     note(message: string): void;
     writePersistent(text: string): void;
+    /** Keep role/provider/context state in the single bottom-most TTY line. */
+    setAgentStatus(line: string | undefined): void;
     pause(): () => void;
     dispose(): void;
     private startTimer;

package/dist/activity.js

@@ -23,6 +23,7 @@ export class ActivityReporter {
     lastHeartbeatAt = 0;
     lineVisible = false;
     paused = 0;
+    agentStatusLine;
     constructor(command, options = {}) {
         this.command = command;
         this.output = options.output ?? {
@@ -90,6 +91,20 @@ export class ActivityReporter {
             this.output.write("\n");
         this.render(true);
     }
+    /** Keep role/provider/context state in the single bottom-most TTY line. */
+    setAgentStatus(line) {
+        this.agentStatusLine = line ? clean(line, 500) : undefined;
+        if (this.agentStatusLine && !this.timer) {
+            this.lastSignalAt = this.now();
+            this.lastHeartbeatAt = this.lastSignalAt;
+            this.startTimer();
+        }
+        if (!this.agentStatusLine && this.phases.size === 0) {
+            this.idle();
+            return;
+        }
+        this.render(true);
+    }
     pause() {
         this.paused++;
         this.clearLine();
@@ -104,6 +119,7 @@ export class ActivityReporter {
     }
     dispose() {
         this.phases.clear();
+        this.agentStatusLine = undefined;
         this.idle();
     }
     startTimer() {
@@ -113,6 +129,14 @@ export class ActivityReporter {
         this.timer.unref();
     }
     idle() {
+        if (this.agentStatusLine) {
+            this.clearLine();
+            this.detail = undefined;
+            this.provider = undefined;
+            this.model = undefined;
+            this.render(true);
+            return;
+        }
         if (this.timer)
             clearInterval(this.timer);
         this.timer = undefined;
@@ -120,27 +144,28 @@ export class ActivityReporter {
         this.detail = undefined;
         this.provider = undefined;
         this.model = undefined;
+        this.agentStatusLine = undefined;
     }
     currentPhase() {
         return [...this.phases.values()].at(-1);
     }
     render(force) {
         const phase = this.currentPhase();
-        if (!phase || this.paused > 0)
+        if ((!phase && !this.agentStatusLine) || this.paused > 0)
             return;
         const now = this.now();
-        const elapsed = now - phase.startedAt;
+        const elapsed = phase ? now - phase.startedAt : now - this.commandStartedAt;
         if (!force && elapsed < this.displayDelayMs)
             return;
         const quietFor = now - this.lastSignalAt;
-        if (quietFor >= this.quietWarningMs && !this.quietWarningPrinted) {
+        if (phase && quietFor >= this.quietWarningMs && !this.quietWarningPrinted) {
             this.quietWarningPrinted = true;
             this.note(`rafi: ${this.provider ?? "provider"} has been quiet for ${formatDuration(quietFor)}; RAFI is still responsive and will keep waiting`);
             return;
         }
         const provider = [this.provider, this.model].filter(Boolean).join("/");
         const quiet = quietFor >= this.quietWarningMs ? `provider quiet ${formatDuration(quietFor)}; RAFI is responsive` : this.detail;
-        const body = [phase.label, provider || undefined, quiet].filter(Boolean).join(" — ");
+        const body = [phase?.label, provider || undefined, phase ? quiet : undefined, this.agentStatusLine].filter(Boolean).join(" — ");
         if (this.output.isTTY) {
             const line = `${FRAMES[this.frame++ % FRAMES.length]} RAFI working: ${body} (${formatDuration(now - this.commandStartedAt)})`;
             this.output.write(`\r\x1b[2K${line}`);

package/dist/adapters/claude.d.ts

@@ -1,14 +1,34 @@
-import type { PermissionResult } from "@anthropic-ai/claude-agent-sdk";
+import type { SDKSessionInfo, PermissionResult } from "@anthropic-ai/claude-agent-sdk";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export declare function requireClaudeSDK(): Promise<typeof import("@anthropic-ai/claude-agent-sdk")>;
-import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, PermissionDecision, ProviderSettingSwitch, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, PermissionDecision, ProviderSettingSwitch, ProviderSessionUsage, TurnResult } from "./types.js";
+import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 /**
  * Pure function: build the `options` object passed to `query()`.
  * Extracted so tests can assert on the shape without making a live SDK call.
  * `canUseTool` is omitted here — it's a closure that the constructor adds.
  */
 export declare function buildClaudeQueryOptions(opts: Omit<BuilderAdapterOptions, "permission">): Record<string, unknown>;
+export declare function probeClaudeSession(ref: ProviderSessionRefV1, input: {
+    cwd: string;
+    configRoot?: string;
+    workspaceIdentity?: string;
+    role?: ProviderSessionRefV1["role"];
+    stream?: string;
+    ticketId?: string;
+    deliveryUnitId?: string;
+    getSessionInfo?: (sessionId: string, options?: {
+        dir?: string;
+    }) => Promise<SDKSessionInfo | undefined>;
+    now?: Date;
+}): Promise<SessionAvailabilityV1>;
 export declare function permissionDecisionToClaudeResult(decision: PermissionDecision, toolUseID?: string): PermissionResult;
+/** Project one cumulative SDK result without inventing or double-counting counters. */
+export declare function mergeClaudeProviderSessionUsage(prior: ProviderSessionUsage, rawResult: Record<string, unknown>, observedAt?: string): {
+    sample: ProviderSessionUsage;
+    inputTokens?: number;
+    outputTokens?: number;
+};
 export declare function claudeApiRetryEvent(message: {
     error: string;
     attempt: number;
@@ -29,12 +49,16 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private readonly abort;
     private readonly pumpDone;
     private _sessionId?;
+    private _sessionRef?;
     private readonly stderrChunks;
     private turnSignals;
     private structuredError?;
     private apiErrorStatus?;
     private compactResult?;
+    private cumulativeUsage;
     private pending?;
+    private terminalResult?;
+    private streamEnded;
     private closed;
     static create(opts: BuilderAdapterOptions): Promise<ClaudeAdapter>;
     private constructor();
@@ -45,9 +69,16 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private sendTurnInternal;
     private captureStderr;
     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>;
+    private observeSession;
+    private settlePending;
+    private streamFailureResult;
 }

package/dist/adapters/claude.js

@@ -13,6 +13,8 @@ import { AsyncQueue } from "../util/asyncQueue.js";
 import { BuilderEventQueue, withActivityPhase } from "../activity.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 import { classifyClaudeSdkFailure, resolveExecutablePath, sanitizeDiagnostics, } from "../runtimeReadiness.js";
+import { createProviderSessionRef, validateProviderSessionScope, canonicalSessionPath } from "../sessionIdentity.js";
+import { SessionUnavailableError, sessionUnavailableResult } from "./sessionFailure.js";
 /**
  * Pure function: build the `options` object passed to `query()`.
  * Extracted so tests can assert on the shape without making a live SDK call.
@@ -24,7 +26,7 @@ export function buildClaudeQueryOptions(opts) {
         pathToClaudeCodeExecutable: opts.runtimeExecutable,
         env: { ...process.env },
         model: opts.model,
-        resume: opts.resumeSessionId,
+        resume: opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId,
         permissionMode: "acceptEdits",
         effort: opts.effort,
         extraArgs: opts.fast ? { fast: null } : undefined,
@@ -38,6 +40,38 @@ export function buildClaudeQueryOptions(opts) {
     }
     return base;
 }
+export async function probeClaudeSession(ref, input) {
+    const now = input.now ?? new Date();
+    const local = validateProviderSessionScope(ref, {
+        provider: "claude",
+        cwd: input.cwd,
+        configRoot: input.configRoot ?? input.cwd,
+        role: input.role ?? ref.role,
+        stream: input.stream ?? ref.stream,
+        workspaceIdentity: input.workspaceIdentity,
+        ticketId: input.ticketId ?? ref.ticketId,
+        deliveryUnitId: input.deliveryUnitId ?? ref.deliveryUnitId,
+    }, now);
+    if (local.status !== "available")
+        return local;
+    try {
+        const getSessionInfo = input.getSessionInfo ?? (await requireClaudeSDK()).getSessionInfo;
+        const info = await getSessionInfo(ref.sessionId, { dir: ref.cwd });
+        if (!info)
+            return { version: 1, status: "unavailable", checkedAt: now.toISOString(), reason: "not-found", detail: `Claude has no conversation ${ref.sessionId} in ${ref.cwd}`, sessionRef: ref };
+        if (info.sessionId !== ref.sessionId)
+            return { version: 1, status: "unavailable", checkedAt: now.toISOString(), reason: "not-found", detail: "Claude returned metadata for a different session", sessionRef: ref };
+        if (!info.cwd)
+            return { version: 1, status: "unknown", checkedAt: now.toISOString(), reason: "probe-failed", detail: "Claude session metadata did not include cwd", sessionRef: ref };
+        const observedCwd = canonicalSessionPath(info.cwd);
+        if (observedCwd !== canonicalSessionPath(ref.cwd))
+            return { version: 1, status: "unavailable", checkedAt: now.toISOString(), reason: "cwd-mismatch", detail: `Claude metadata cwd ${observedCwd} does not match ${ref.cwd}`, observedCwd, sessionRef: ref };
+        return { ...local, checkedAt: now.toISOString(), observedCwd, sessionRef: { ...local.sessionRef, validatedAt: now.toISOString() } };
+    }
+    catch (error) {
+        return { version: 1, status: "unknown", checkedAt: now.toISOString(), reason: "probe-failed", detail: sanitizeDiagnostics(error instanceof Error ? error.message : String(error)), sessionRef: ref };
+    }
+}
 export function permissionDecisionToClaudeResult(decision, toolUseID) {
     if (decision.behavior === "allow") {
         return {
@@ -54,6 +88,39 @@ export function permissionDecisionToClaudeResult(decision, toolUseID) {
         toolUseID,
     };
 }
+/** Project one cumulative SDK result without inventing or double-counting counters. */
+export function mergeClaudeProviderSessionUsage(prior, rawResult, observedAt = new Date().toISOString()) {
+    const rawUsage = rawResult.usage && typeof rawResult.usage === "object" ? rawResult.usage : {};
+    const directInputTokens = finiteNumber(rawUsage.input_tokens);
+    const cacheCreationInputTokens = finiteNumber(rawUsage.cache_creation_input_tokens);
+    const cacheReadInputTokens = finiteNumber(rawUsage.cache_read_input_tokens);
+    const inputTokens = [directInputTokens, cacheCreationInputTokens, cacheReadInputTokens].some((value) => value !== undefined)
+        ? (directInputTokens ?? 0) + (cacheCreationInputTokens ?? 0) + (cacheReadInputTokens ?? 0)
+        : undefined;
+    const outputTokens = finiteNumber(rawUsage.output_tokens);
+    const authoritativeCostUsd = finiteNumber(rawResult.total_cost_usd);
+    // SDK result usage and total_cost_usd are cumulative for this query
+    // conversation. Preserve the latest authoritative absolute counters;
+    // summing successive result messages would double-count prior turns.
+    const cumulativeInput = inputTokens ?? prior.inputTokens;
+    const cumulativeOutput = outputTokens ?? prior.outputTokens;
+    const cumulativeTotal = inputTokens === undefined && outputTokens === undefined
+        ? prior.totalTokens
+        : (inputTokens ?? 0) + (outputTokens ?? 0);
+    const cumulativeCost = authoritativeCostUsd ?? prior.authoritativeCostUsd;
+    return {
+        sample: {
+            ...(cumulativeInput !== undefined ? { inputTokens: cumulativeInput } : {}),
+            ...(cumulativeOutput !== undefined ? { outputTokens: cumulativeOutput } : {}),
+            ...(cumulativeTotal !== undefined ? { totalTokens: cumulativeTotal } : {}),
+            ...(cumulativeCost !== undefined ? { authoritativeCostUsd: cumulativeCost } : {}),
+            observedAt,
+            source: "provider",
+        },
+        inputTokens,
+        outputTokens,
+    };
+}
 export function claudeApiRetryEvent(message) {
     return {
         kind: "retry",
@@ -79,12 +146,16 @@ export class ClaudeAdapter {
     abort = new AbortController();
     pumpDone;
     _sessionId;
+    _sessionRef;
     stderrChunks = [];
     turnSignals = [];
     structuredError;
     apiErrorStatus;
     compactResult;
+    cumulativeUsage = { observedAt: new Date(0).toISOString(), source: "provider" };
     pending;
+    terminalResult;
+    streamEnded = false;
     closed = false;
     static async create(opts) {
         try {
@@ -92,10 +163,33 @@ export class ClaudeAdapter {
             if (!runtimeExecutable) {
                 throw new Error("Claude Code executable not found on PATH. Install your organization-approved Claude Code CLI, then retry.");
             }
-            const { query } = await requireClaudeSDK();
-            return new ClaudeAdapter({ ...opts, runtimeExecutable }, query);
+            const sdk = await requireClaudeSDK();
+            let validatedOpts = { ...opts, runtimeExecutable };
+            if (opts.resumeSessionRef) {
+                const availability = await probeClaudeSession(opts.resumeSessionRef, {
+                    cwd: opts.cwd,
+                    configRoot: opts.configRoot,
+                    workspaceIdentity: opts.workspaceIdentity,
+                    role: opts.sessionRole,
+                    stream: opts.sessionStream,
+                    ticketId: opts.ticketId,
+                    deliveryUnitId: opts.deliveryUnitId,
+                    getSessionInfo: sdk.getSessionInfo,
+                });
+                if (availability.status !== "available" || !availability.sessionRef) {
+                    throw new SessionUnavailableError({
+                        runtime: "claude", phase: "preflight", dispatchState: "not-sent", executable: runtimeExecutable,
+                        cwd: opts.cwd, diagnostics: availability.detail ?? `Claude session ${opts.resumeSessionRef.sessionId} is ${availability.status}`,
+                        availability,
+                    });
+                }
+                validatedOpts = { ...validatedOpts, resumeSessionId: availability.sessionRef.sessionId, resumeSessionRef: availability.sessionRef };
+            }
+            return new ClaudeAdapter(validatedOpts, sdk.query);
         }
         catch (err) {
+            if (err instanceof SessionUnavailableError)
+                throw err;
             const message = err instanceof Error ? err.message : String(err);
             throw new Error(normalizeRuntimeErrorText("claude", message, null, "adapter startup"), { cause: err });
         }
@@ -103,6 +197,8 @@ export class ClaudeAdapter {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     constructor(opts, query) {
         this.opts = opts;
+        this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
+        this._sessionRef = opts.resumeSessionRef;
         this.query = query({
             prompt: this.inbox,
             options: {
@@ -143,17 +239,28 @@ export class ClaudeAdapter {
                 const rawMessage = err instanceof Error ? err.message : String(err);
                 const message = normalizeRuntimeErrorText("claude", rawMessage, null, "builder stream");
                 this.eventQueue.push({ kind: "error", message });
-                this.pending?.reject(new Error(message));
-                this.pending = undefined;
+                const result = this.streamFailureResult(message, isMissingClaudeSession(rawMessage));
+                this.terminalResult = result;
+                this.settlePending(result);
             }
         }
         finally {
+            this.streamEnded = true;
+            if (!this.closed && this.pending) {
+                const result = this.streamFailureResult("Claude stream ended without a result", Boolean(this.opts.resumeSessionRef ?? this.opts.resumeSessionId));
+                this.terminalResult = result;
+                this.eventQueue.push({ kind: "error", message: result.text });
+                this.settlePending(result);
+            }
+            if (!this.closed && !this.terminalResult)
+                this.terminalResult = this.streamFailureResult("Claude stream ended without a result", Boolean(this.opts.resumeSessionRef ?? this.opts.resumeSessionId));
             this.eventQueue.close();
         }
     }
     handle(msg) {
         if ("session_id" in msg && typeof msg.session_id === "string") {
             this._sessionId = msg.session_id;
+            this.observeSession(msg.session_id);
         }
         if (msg.type === "assistant") {
             if (msg.error) {
@@ -221,24 +328,42 @@ export class ClaudeAdapter {
                 ...this.turnSignals,
                 ...this.stderrChunks,
             ].filter(Boolean).join("\n"));
-            const failure = msg.is_error ? {
-                runtime: "claude",
-                phase: this.opts.runtimePhase ?? "builder",
-                category: classifyClaudeSdkFailure(this.structuredError, this.apiErrorStatus, rawDiagnostics),
-                executable: this.opts.runtimeExecutable ?? "claude",
-                cwd: this.opts.cwd,
-                diagnostics: rawDiagnostics,
-            } : undefined;
+            const missingResumedSession = msg.is_error
+                && Boolean(this.opts.resumeSessionRef ?? this.opts.resumeSessionId)
+                && isMissingClaudeSession(rawDiagnostics);
+            const failure = msg.is_error ? missingResumedSession
+                ? new SessionUnavailableError({
+                    runtime: "claude", phase: "turn", dispatchState: "unknown",
+                    executable: this.opts.runtimeExecutable ?? "claude", cwd: this.opts.cwd,
+                    diagnostics: rawDiagnostics,
+                    availability: {
+                        version: 1, status: "unavailable", checkedAt: new Date().toISOString(), reason: "not-found",
+                        detail: rawDiagnostics, ...(this._sessionRef ? { sessionRef: this._sessionRef } : {}),
+                    },
+                }).failure
+                : {
+                    runtime: "claude",
+                    phase: this.opts.runtimePhase ?? "builder",
+                    category: classifyClaudeSdkFailure(this.structuredError, this.apiErrorStatus, rawDiagnostics),
+                    executable: this.opts.runtimeExecutable ?? "claude",
+                    cwd: this.opts.cwd,
+                    diagnostics: rawDiagnostics,
+                } : undefined;
             const result = {
                 text: failure ? formatClaudeFailure(failure) : text,
                 isError: msg.is_error,
                 numTurns: msg.num_turns,
                 costUsd: msg.total_cost_usd,
+                costAuthoritative: Number.isFinite(msg.total_cost_usd),
                 failure,
             };
+            const rawResult = msg;
+            const mergedUsage = mergeClaudeProviderSessionUsage(this.cumulativeUsage, rawResult);
+            result.inputTokens = mergedUsage.inputTokens;
+            result.outputTokens = mergedUsage.outputTokens;
+            this.cumulativeUsage = mergedUsage.sample;
             this.eventQueue.push({ kind: "turn-complete", result });
-            this.pending?.resolve(result);
-            this.pending = undefined;
+            this.settlePending(result, false);
             this.turnSignals = [];
             this.structuredError = undefined;
             this.apiErrorStatus = undefined;
@@ -251,6 +376,8 @@ export class ClaudeAdapter {
     sendTurnInternal(text) {
         if (this.closed)
             return Promise.reject(new Error("builder is closed"));
+        if (this.terminalResult || this.streamEnded)
+            return Promise.resolve(this.terminalResult ?? this.streamFailureResult("Claude stream is no longer available", Boolean(this.opts.resumeSessionRef ?? this.opts.resumeSessionId)));
         if (this.pending) {
             return Promise.reject(new Error("a turn is already in progress"));
         }
@@ -275,9 +402,31 @@ export class ClaudeAdapter {
     sessionId() {
         return this._sessionId;
     }
+    sessionRef() { return this._sessionRef; }
+    adoptSessionRef(ref) {
+        if (ref.provider !== "claude" || ref.sessionId !== this._sessionId)
+            throw new Error("cannot adopt a session reference for a different Claude conversation");
+        this._sessionRef = ref;
+    }
+    async validateSession() {
+        if (!this._sessionRef)
+            return { version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped", detail: "Claude adapter was constructed from an unscoped raw session ID" };
+        return probeClaudeSession(this._sessionRef, {
+            cwd: this.opts.cwd,
+            configRoot: this.opts.configRoot,
+            workspaceIdentity: this.opts.workspaceIdentity,
+            role: this.opts.sessionRole,
+            stream: this.opts.sessionStream,
+            ticketId: this.opts.ticketId,
+            deliveryUnitId: this.opts.deliveryUnitId,
+        });
+    }
     async compact() {
         this.compactResult = undefined;
         const result = await this.sendTurn("/compact");
+        if (result.failure?.category === "session-unavailable") {
+            return { ok: false, error: result.text || result.failure.diagnostics, failure: result.failure };
+        }
         if (this.compactResult)
             return this.compactResult;
         return { ok: false, error: sanitizeDiagnostics(result.text || "Claude did not emit an explicit compact status") };
@@ -285,7 +434,7 @@ export class ClaudeAdapter {
     async contextUsage() {
         try {
             const usage = await this.query.getContextUsage();
-            const result = { used: usage.totalTokens, maximum: usage.maxTokens, percentage: usage.percentage };
+            const result = { used: usage.totalTokens, maximum: usage.maxTokens, percentage: usage.percentage, observedAt: new Date().toISOString(), source: "provider-query" };
             this.eventQueue.push({ kind: "context-usage", ...result });
             return result;
         }
@@ -293,6 +442,9 @@ export class ClaudeAdapter {
             return undefined;
         }
     }
+    async sessionUsage() {
+        return this.cumulativeUsage.observedAt === new Date(0).toISOString() ? undefined : { ...this.cumulativeUsage };
+    }
     async switchSettings(settings) {
         if (settings.effort !== this.opts.effort || settings.fast !== this.opts.fast)
             return { ok: false, error: "Claude SDK cannot change reasoning/fast controls on an existing transport" };
@@ -300,7 +452,7 @@ export class ClaudeAdapter {
             return { ok: true };
         const result = await this.sendTurn(`/model ${settings.model ?? "default"}`);
         if (result.isError)
-            return { ok: false, error: result.text };
+            return { ok: false, error: result.text, ...(result.failure ? { failure: result.failure } : {}) };
         this.opts.model = settings.model;
         return { ok: true };
     }
@@ -321,6 +473,45 @@ export class ClaudeAdapter {
         this.abort.abort();
         await this.pumpDone.catch(() => { });
     }
+    observeSession(sessionId) {
+        if (this._sessionRef?.sessionId === sessionId)
+            return;
+        this._sessionRef = createProviderSessionRef({
+            provider: "claude", sessionId, cwd: 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,
+            source: "observed",
+        });
+    }
+    settlePending(result, emit = true) {
+        const pending = this.pending;
+        if (!pending)
+            return;
+        this.pending = undefined;
+        if (emit)
+            this.eventQueue.push({ kind: "turn-complete", result });
+        pending.resolve(result);
+    }
+    streamFailureResult(message, sessionUnavailable) {
+        if (sessionUnavailable) {
+            const availability = {
+                version: 1, status: "unavailable", checkedAt: new Date().toISOString(), reason: "not-found",
+                detail: message, ...(this._sessionRef ? { sessionRef: this._sessionRef } : {}),
+            };
+            return sessionUnavailableResult(new SessionUnavailableError({
+                runtime: "claude", phase: "turn", dispatchState: "unknown", executable: this.opts.runtimeExecutable ?? "claude",
+                cwd: this.opts.cwd, diagnostics: message, availability,
+            }));
+        }
+        return {
+            text: message, isError: true, numTurns: 0, costUsd: 0, costAuthoritative: false,
+            failure: { runtime: "claude", phase: this.opts.runtimePhase ?? "builder", category: "agent-stream", executable: this.opts.runtimeExecutable ?? "claude", cwd: this.opts.cwd, diagnostics: message, dispatchState: "unknown" },
+        };
+    }
+}
+function finiteNumber(value) { const parsed = Number(value); return value !== null && value !== undefined && value !== "" && Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined; }
+function isMissingClaudeSession(message) {
+    return /no conversation found with session id|session .* not found|conversation .* not found/i.test(message);
 }
 function activityPhase(phase) {
     if (phase === "planning")

package/dist/adapters/codex.d.ts

@@ -1,4 +1,5 @@
-import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, ProviderSettingSwitch, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, ProviderSessionUsage, ProviderSettingSwitch, TurnResult } from "./types.js";
+import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 export interface CodexLineResult {
     events: BuilderEvent[];
     sessionId?: string;
@@ -16,10 +17,15 @@ export declare class CodexAdapter implements BuilderAdapter {
     private pending;
     private notificationWaiters;
     private _sessionId?;
+    private _sessionRef?;
+    private sessionAvailability?;
     private initialized;
     private closed;
     private activeText;
     private usage?;
+    private usageRevision;
+    private providerSessionUsage?;
+    private lastTurnTokens?;
     private stderr;
     constructor(opts: BuilderAdapterOptions);
     buildInstruction(instruction: string): string;
@@ -30,8 +36,12 @@ export declare class CodexAdapter implements BuilderAdapter {
     private sendTurnInternal;
     compact(): Promise<CompactResult>;
     contextUsage(): Promise<ContextUsage | undefined>;
+    sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     sessionId(): string | undefined;
+    sessionRef(): ProviderSessionRefV1 | undefined;
+    adoptSessionRef(ref: ProviderSessionRefV1): void;
+    validateSession(): Promise<SessionAvailabilityV1>;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
     private ensureThread;