ai-foreman 1.7.19 → 1.7.21

package/dist/recoveryGuidance.d.ts

@@ -0,0 +1,17 @@
+export type RecoveryCommandFamily = "rafi" | "ai-foreman";
+export declare function withRecoveryCommandFamily<T>(family: RecoveryCommandFamily, work: () => T): T;
+export declare function shellArgument(value: string, platform?: NodeJS.Platform): string;
+/** POSIX shell command (PowerShell on Windows). The owning project is supplied explicitly, never a QA snapshot. */
+export declare function formatRecoveryCommand(projectDir: string, family?: RecoveryCommandFamily, cwd?: string, session?: {
+    id: string;
+    steps: number;
+}): string;
+/** Fixed choices are executable; custom answers use the owning CLI's input flow. */
+export declare function formatDecisionCommands(projectDir: string, runId: string, decision: {
+    decisionId: string;
+    choices: Array<{
+        id: string;
+        label: string;
+    }>;
+}, family?: RecoveryCommandFamily): string[];
+export declare function formatExactRunRecovery(projectDir: string, runId: string, family?: RecoveryCommandFamily): string;

package/dist/recoveryGuidance.js

@@ -0,0 +1,38 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+const commandFamily = new AsyncLocalStorage();
+export function withRecoveryCommandFamily(family, work) { return commandFamily.run(family, work); }
+export function shellArgument(value, platform = process.platform) {
+    if (platform === "win32")
+        return `'${value.replace(/'/g, "''")}'`;
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function canonical(path) { try {
+    return realpathSync(resolve(path));
+}
+catch {
+    return resolve(path);
+} }
+/** POSIX shell command (PowerShell on Windows). The owning project is supplied explicitly, never a QA snapshot. */
+export function formatRecoveryCommand(projectDir, family = commandFamily.getStore() ?? "rafi", cwd = process.cwd(), session) {
+    if (family === "ai-foreman") {
+        if (session)
+            return `ai-foreman start ${shellArgument(resolve(projectDir))} --steps ${session.steps} --resume ${shellArgument(session.id)}`;
+        return `ai-foreman manager ${shellArgument(resolve(projectDir))}`;
+    }
+    return canonical(projectDir) === canonical(cwd) ? "rafi resume" : `rafi resume ${shellArgument(resolve(projectDir))}`;
+}
+/** Fixed choices are executable; custom answers use the owning CLI's input flow. */
+export function formatDecisionCommands(projectDir, runId, decision, family = commandFamily.getStore() ?? "rafi") {
+    return decision.choices.flatMap(choice => choice.id === "custom"
+        ? [family === "ai-foreman"
+                ? `  Custom response: use ${family} build:decide ${shellArgument(resolve(projectDir))} --run ${shellArgument(runId)} --decision ${shellArgument(decision.decisionId)} --choice custom with --answer followed by your shell-quoted response.`
+                : `  Custom response: run ${formatExactRunRecovery(projectDir, runId, family)} in an interactive terminal.`]
+        : [`  ${choice.label}`, `  ${family} build:decide ${shellArgument(resolve(projectDir))} --run ${shellArgument(runId)} --decision ${shellArgument(decision.decisionId)} --choice ${shellArgument(choice.id)}`]);
+}
+export function formatExactRunRecovery(projectDir, runId, family = commandFamily.getStore() ?? "rafi") {
+    if (family === "ai-foreman")
+        return `ai-foreman manager ${shellArgument(resolve(projectDir))} --run ${shellArgument(runId)}`;
+    return `rafi resume ${shellArgument(resolve(projectDir))} --run ${shellArgument(runId)}`;
+}

package/dist/runtimeAuth.d.ts

@@ -14,6 +14,7 @@ export declare class RuntimeAuthError extends Error {
     readonly stdout: string;
     readonly stderr: string;
     readonly authLikely: boolean;
+    readonly cleanupUnverified: boolean;
     constructor(opts: RuntimeAuthErrorOptions);
 }
 export declare function checkRuntimeReady(projectDir: string, runtime: AgentRuntime, options?: ProbeRuntimeOptions): Promise<import("rafi-spec").RuntimeProbeResult>;

package/dist/runtimeAuth.js

@@ -1,10 +1,11 @@
-import { formatRuntimeProbeFailure, probeRuntime } from "./runtimeReadiness.js";
+import { formatRuntimeProbeFailure, probeRuntime, RuntimeCleanupError, runtimeCleanupRecoveryHelp } from "./runtimeReadiness.js";
 export class RuntimeAuthError extends Error {
     runtime;
     exitCode;
     stdout;
     stderr;
     authLikely;
+    cleanupUnverified;
     constructor(opts) {
         super(formatRuntimeAuthFailure(opts), { cause: opts.cause });
         this.name = "RuntimeAuthError";
@@ -13,6 +14,7 @@ export class RuntimeAuthError extends Error {
         this.stdout = opts.stdout ?? "";
         this.stderr = opts.stderr ?? "";
         this.authLikely = isRuntimeAuthFailure(`${this.stderr}\n${this.stdout}`);
+        this.cleanupUnverified = opts.cause instanceof RuntimeCleanupError;
     }
 }
 export async function checkRuntimeReady(projectDir, runtime, options = {}) {
@@ -67,6 +69,8 @@ export function runtimeRepairCommands(runtime) {
     ].join("\n");
 }
 export function formatRuntimeAuthFailure(opts) {
+    if (opts.cause instanceof RuntimeCleanupError)
+        return `${opts.cause.message}\n\n${opts.context} is paused before further provider work. This is a process cleanup problem; changing login or provider will not clear it.\n\n${runtimeCleanupRecoveryHelp()}`;
     const output = [opts.stderr, opts.stdout].filter(Boolean).join("\n").trim();
     const exit = opts.exitCode === undefined || opts.exitCode === null ? "unknown" : String(opts.exitCode);
     const authLine = isRuntimeAuthFailure(output)

package/dist/runtimeReadiness.d.ts

@@ -1,10 +1,22 @@
+import { type BuildAdmission } from "./buildAdmission.js";
 import type { RuntimeProbeCategory, RuntimeProbePhase, RuntimeProbeResult } from "rafi-spec";
 import type { AgentRuntime } from "./runtimeAuth.js";
 export declare const RUNTIME_PROBE_TIMEOUT_MS = 120000;
 export declare const RUNTIME_DIAGNOSTIC_LIMIT: number;
 /** Used when a supervised worker loses its parent, including detached probes. */
 export declare function cancelOwnedRuntimeProbes(): void;
+export interface BuildReadinessContext {
+    project: string;
+    runId: string;
+    authority: BuildAdmission;
+}
+export declare class RuntimeCleanupError extends Error {
+    constructor(message: string);
+}
+export declare function runtimeCleanupRecoveryHelp(): string;
 export interface ProbeRuntimeOptions {
+    /** Omit only for standalone authentication/capability commands. Build callers use probeBuildRuntime. */
+    build?: BuildReadinessContext;
     phase?: RuntimeProbePhase;
     timeoutMs?: number;
     maxDiagnosticsBytes?: number;
@@ -22,6 +34,7 @@ export interface ProbeRuntimeOptions {
 }
 /** Resolve the executable Node will launch without involving a shell. */
 export declare function resolveExecutablePath(command: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | undefined;
+export declare function probeBuildRuntime(cwd: string, runtime: AgentRuntime, build: BuildReadinessContext, opts?: Omit<ProbeRuntimeOptions, "build">): Promise<RuntimeProbeResult>;
 export declare function probeRuntime(cwd: string, runtime: AgentRuntime, opts?: ProbeRuntimeOptions): Promise<RuntimeProbeResult>;
 export declare function classifyRuntimeFailure(text: string, phase?: RuntimeProbePhase): RuntimeProbeCategory;
 export declare function classifyClaudeSdkFailure(error: string | undefined, status: number | null | undefined, diagnostics: string): RuntimeProbeCategory;

package/dist/runtimeReadiness.js

@@ -1,15 +1,35 @@
+import { fileURLToPath } from "node:url";
+import { cleanupReadiness } from "./readinessCleanup.js";
+import { windowsProbeCommand } from "./windowsProbeJob.js";
+import { randomUUID } from "node:crypto";
+import { BuildOwnershipError, canonicalProject } from "./buildAdmission.js";
+import { WorkflowDb } from "./workflowDb.js";
 import { spawn } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
 import { delimiter, isAbsolute, resolve } from "node:path";
 import { currentActivity, withActivityPhase } from "./activity.js";
-import { processStartIdentity } from "./processIdentity.js";
+import { classifyProcess, processStartIdentity } from "./processIdentity.js";
 export const RUNTIME_PROBE_TIMEOUT_MS = 120_000;
 export const RUNTIME_DIAGNOSTIC_LIMIT = 8 * 1024;
 const RELEVANT_ENV = /^(ANTHROPIC|CLAUDE|CODEX|OPENAI|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|SSL_CERT_FILE|NODE_EXTRA_CA_CERTS)(_|$)/i;
 const ownedProbes = new Set();
+const pendingStandaloneCleanup = new Map();
 /** Used when a supervised worker loses its parent, including detached probes. */
 export function cancelOwnedRuntimeProbes() { for (const cancel of ownedProbes)
     cancel(); }
+export class RuntimeCleanupError extends Error {
+    constructor(message) { super(message); this.name = "RuntimeCleanupError"; }
+}
+export function runtimeCleanupRecoveryHelp() {
+    return [
+        "Keep this Rafi process open while repairing visibility in another terminal, then choose retry.",
+        "Linux/WSL: check that /proc is mounted and readable by this user. Use a native Linux Node and provider installation in the same WSL distribution; inspect command -v node and command -v claude (or codex).",
+        "macOS: check that ps is available on PATH and process inspection is permitted by the terminal or host sandbox.",
+        "Windows: check that Windows PowerShell and process/Job Object inspection are available to the same user.",
+        "Retry first reconciles the original probe; no new provider starts until cleanup is verified. Avoid restarting Rafi to bypass this check or killing unrelated processes.",
+        "You may cancel deliberately; generated files remain available for a later create walkthrough.",
+    ].join("\n");
+}
 /** Resolve the executable Node will launch without involving a shell. */
 export function resolveExecutablePath(command, env = process.env, platform = process.platform) {
     const hasPathSeparator = command.includes("/") || command.includes("\\");
@@ -57,10 +77,24 @@ function isRunnableFile(path, platform) {
         return false;
     }
 }
+export async function probeBuildRuntime(cwd, runtime, build, opts = {}) {
+    if (!build?.authority)
+        throw new BuildOwnershipError("stale-owner", "Build readiness requires original admission authority");
+    return probeRuntime(cwd, runtime, { ...opts, build });
+}
 export async function probeRuntime(cwd, runtime, opts = {}) {
     return withActivityPhase(`checking ${runtime} runtime`, () => probeRuntimeInternal(cwd, runtime, opts));
 }
 async function probeRuntimeInternal(cwd, runtime, opts) {
+    // Do not overlap a new probe with cleanup that a previous standalone call
+    // could not verify. Keep the original identities, never manufacture authority.
+    const cleanupDeadline = Date.now() + 5000;
+    for (const [id, row] of pendingStandaloneCleanup) {
+        const evidence = await cleanupReadiness(row, cleanupDeadline);
+        if (evidence.state !== "quiescent")
+            throw new RuntimeCleanupError(`Previous standalone probe cleanup is unverified: ${evidence.reason}. Restore process visibility and retry.`);
+        pendingStandaloneCleanup.delete(id);
+    }
     const env = opts.env ?? process.env;
     const command = runtime === "claude" ? "claude" : "codex";
     const executable = resolveExecutablePath(command, env) ?? command;
@@ -70,7 +104,31 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
     const phase = opts.phase ?? "readiness";
     const limit = opts.maxDiagnosticsBytes ?? RUNTIME_DIAGNOSTIC_LIMIT;
     const timeoutMs = opts.timeoutMs ?? RUNTIME_PROBE_TIMEOUT_MS;
-    return new Promise((resolveResult) => {
+    const authority = opts.build?.authority;
+    if (opts.build && (!authority || opts.build.runId !== authority.runId || canonicalProject(opts.build.project) !== authority.project))
+        throw new BuildOwnershipError("stale-owner", "Invalid build readiness owner");
+    const ownerProject = opts.build?.project;
+    const useHost = Boolean(authority) || process.platform !== "win32";
+    const tag = randomUUID();
+    let windows;
+    if (process.platform === "win32" && !authority) {
+        try {
+            windows = windowsProbeCommand(tag, executable, args, cwd, processStartIdentity());
+        }
+        catch (error) {
+            throw new RuntimeCleanupError(`Windows process containment could not initialize: ${String(error)}`);
+        }
+    }
+    const ownership = ownerProject ? new WorkflowDb(ownerProject) : undefined;
+    let ownedProcess;
+    try {
+        if (authority && ownership)
+            ownedProcess = ownership.beginOwnedPreparationProcess(authority, tag, true);
+    }
+    finally {
+        ownership?.close();
+    }
+    return new Promise((resolveResult, rejectResult) => {
         let output = Buffer.alloc(0);
         let timedOut = false;
         let settled = false;
@@ -83,11 +141,72 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
             }
             catch { /* non-authoritative diagnostics */ }
         };
-        const spawnOpts = { cwd, env, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" };
-        const child = spawn(executable, args, spawnOpts);
+        const spawnOpts = { cwd: useHost ? process.cwd() : cwd, env: { ...(useHost ? { ...process.env, RAFI_PROBE_ENV: JSON.stringify(env) } : env), RAFI_PROBE_OWNER: tag, ...(windows ? { RAFI_WINDOWS_PROBE_CONFIG: windows.config } : {}) }, stdio: useHost ? ["ignore", "pipe", "pipe", "ipc"] : ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" };
+        const gate = fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./readinessGate.ts" : "./readinessGate.js", import.meta.url));
+        const helperNodeArgs = import.meta.url.endsWith(".ts") ? ["--import", import.meta.resolve("tsx")] : [];
+        const child = spawn(useHost ? process.execPath : windows?.executable ?? executable, useHost ? [...helperNodeArgs, gate, ownerProject ?? "--standalone", tag, executable, cwd, ...args] : windows?.args ?? args, spawnOpts);
+        const childStart = child.pid ? processStartIdentity(child.pid) : undefined;
+        let startupError;
+        let providerSpawnError;
+        let providerResult;
+        let startupTimer;
+        if (useHost) {
+            startupTimer = setTimeout(() => { startupError = new RuntimeCleanupError("Readiness helper startup timed out"); abort(); }, 15_000);
+            child.on("message", message => {
+                if (!message || typeof message !== "object" || !("kind" in message))
+                    return;
+                if (message.kind === "rafi-probe-result") {
+                    const reported = message;
+                    if ((reported.exitCode === null || Number.isInteger(reported.exitCode)) && (reported.signal === null || typeof reported.signal === "string")) {
+                        providerResult = reported;
+                        setTimeout(() => { if (!settled) {
+                            child.stdout?.destroy();
+                            child.stderr?.destroy();
+                            void finish(providerResult.exitCode, providerResult.signal);
+                        } }, 100).unref();
+                    }
+                    return;
+                }
+                if (message.kind === "rafi-probe-spawn-error") {
+                    const reported = message;
+                    providerSpawnError = Object.assign(new Error(reported.message ?? "Provider could not start"), { code: reported.code });
+                    return;
+                }
+                if (message.kind !== "rafi-probe-registered")
+                    return;
+                let journal;
+                try {
+                    if (authority && ownedProcess)
+                        journal = new WorkflowDb(ownerProject, undefined, { runId: authority.runId });
+                    if (cancelled || timedOut || settled) {
+                        if (authority && ownedProcess)
+                            journal?.revokeReadinessHelper(ownedProcess, authority);
+                        child.kill("SIGKILL");
+                        return;
+                    }
+                    if (authority && ownedProcess)
+                        journal.authorizeReadinessHelper(authority, ownedProcess, child.pid);
+                    child.send("rafi-probe-authorized", error => { if (error) {
+                        startupError = error;
+                        abort();
+                    } });
+                    clearTimeout(startupTimer);
+                }
+                catch (error) {
+                    startupError = new RuntimeCleanupError(`Readiness authorization failed: ${String(error)}`);
+                    abort();
+                }
+                finally {
+                    journal?.close();
+                }
+            });
+        }
         const notifySupervisor = (active) => {
             if (process.send && process.connected && process.env.RAFI_BUILD_WORKER_RUN && child.pid) {
-                process.send({ kind: "rafi-readiness-child", active, pid: child.pid, processStart: active ? processStartIdentity(child.pid) : undefined });
+                try {
+                    process.send({ kind: "rafi-readiness-child", active, tag, pid: child.pid, processStart: active ? processStartIdentity(child.pid) : undefined }, () => { });
+                }
+                catch { /* Durable ownership survives a disconnected supervisor. */ }
             }
         };
         notifySupervisor(true);
@@ -103,7 +222,7 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
         child.stdout?.on("data", append);
         child.stderr?.on("data", append);
         const killOwnedGroup = (signal) => {
-            if (!child.pid)
+            if (!child.pid || classifyProcess(child.pid, childStart).state !== "live")
                 return;
             try {
                 if (process.platform !== "win32")
@@ -114,6 +233,8 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
             catch { /* owned process/group already exited */ }
         };
         const stop = () => {
+            if (settled || forceTimer)
+                return;
             trace(cancelled ? "cancelled" : "timeout", { pid: child.pid });
             killOwnedGroup("SIGTERM");
             forceTimer = setTimeout(() => {
@@ -128,12 +249,14 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
         timer.unref();
         const abort = () => { cancelled = true; clearTimeout(timer); stop(); };
         ownedProbes.add(abort);
-        const finish = (exitCode, signal, spawnError) => {
+        const finish = async (exitCode, signal, spawnError) => {
             if (settled)
                 return;
             settled = true;
-            ownedProbes.delete(abort);
-            notifySupervisor(false);
+            if (providerResult) {
+                exitCode = providerResult.exitCode;
+                signal = providerResult.signal;
+            }
             clearTimeout(timer);
             // The direct child can close stdio while a descendant that ignored TERM
             // remains alive with redirected pipes. Complete cleanup before dropping
@@ -144,7 +267,71 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
             }
             clearTimeout(forceTimer);
             opts.signal?.removeEventListener("abort", abort);
+            // Probe completion and process cleanup are independent. Clean on success too.
+            clearTimeout(startupTimer);
+            let cleaned = Boolean(spawnError && !child.pid);
+            let cleanupReason = "ownership reconciliation did not verify shutdown";
+            if (authority && ownedProcess) {
+                let journal;
+                try {
+                    journal = new WorkflowDb(ownerProject, undefined, { runId: authority.runId });
+                    const record = journal.readinessProcesses(authority.runId).find(row => row.id === ownedProcess);
+                    if (record && JSON.parse(record.outcome_json ?? "{}").startup !== "authorized" && !cancelled && !timedOut)
+                        startupError ??= new RuntimeCleanupError("Readiness helper exited before authorization");
+                    const unresolved = await journal.reconcileReadiness(authority.runId, authority);
+                    cleaned = !unresolved.includes(ownedProcess);
+                }
+                catch {
+                    cleaned = false;
+                }
+                finally {
+                    journal?.close();
+                }
+            }
+            else if (child.pid) {
+                const row = { id: tag, run_id: "standalone", owner: "standalone", pid: child.pid, process_start: childStart ?? null, host: (await import("node:os")).hostname(), state: "running", outcome_json: JSON.stringify({ protocol: windows ? "windows-job-v1" : "tagged-v2" }) };
+                const evidence = await cleanupReadiness(row);
+                cleanupReason = evidence.reason;
+                if (evidence.state !== "quiescent") {
+                    pendingStandaloneCleanup.set(tag, row);
+                    // The trusted holder exits on disconnect; retain the record until OS
+                    // evidence proves it and all supported descendants have stopped.
+                    if (child.connected)
+                        child.disconnect();
+                }
+                cleaned = evidence.state === "quiescent";
+            }
+            trace("owned-child-cleanup", { pid: child.pid });
+            ownedProbes.delete(abort);
+            if (cleaned)
+                notifySupervisor(false);
             trace("settled", { exitCode, signal });
+            if (cleaned && authority && ownedProcess) {
+                let journal;
+                try {
+                    journal = new WorkflowDb(ownerProject, undefined, { runId: authority.runId });
+                    journal.finishOwnedPreparationProcess(authority, ownedProcess, Boolean(spawnError && !child.pid), { ready: !timedOut && !cancelled && exitCode === 0 && /(?:^|\s)OK(?:\s|$)/.test(output.toString("utf8")), exitCode, timedOut, cancelled });
+                    cleaned = cleaned && journal.unresolvedPreparationProcesses(authority.runId).length === 0;
+                }
+                catch (error) {
+                    cleaned = false;
+                    trace("ownership-reconciliation-required");
+                }
+                finally {
+                    journal?.close();
+                }
+            }
+            if (startupError) {
+                rejectResult(new RuntimeCleanupError(`${startupError.message}${cleaned ? "; cleanup verified; retry readiness" : authority ? "; cleanup requires rafi resume" : "; standalone cleanup is unverified; restore process visibility and retry"}`));
+                return;
+            }
+            if (!cleaned) {
+                rejectResult(new RuntimeCleanupError(authority
+                    ? "Readiness process cleanup is unverified; use rafi resume in the owning project to reconcile before continuing"
+                    : `Standalone probe cleanup is unverified (${cleanupReason}); restore process visibility and retry. No new probe will start until cleanup is verified.`));
+                return;
+            }
+            spawnError ??= providerSpawnError;
             const diagnostics = sanitizeDiagnostics(spawnError?.message
                 ? `${spawnError.message}\n${output.toString("utf8")}`
                 : output.toString("utf8"), limit);
@@ -171,7 +358,16 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
             });
         };
         child.once("error", (error) => finish(null, null, error));
-        child.once("exit", (code, signal) => trace("exit", { exitCode: code, signal }));
+        child.once("exit", (code, signal) => {
+            trace("exit", { exitCode: code, signal });
+            // Inherited pipes cannot keep a finished direct process waiting for the
+            // entire provider timeout. Drain buffered output, then clean descendants.
+            setTimeout(() => { if (!settled) {
+                child.stdout?.destroy();
+                child.stderr?.destroy();
+                void finish(code, signal);
+            } }, 100).unref();
+        });
         child.once("close", (code, signal) => { trace("stdio-closed", { exitCode: code, signal }); finish(code, signal); });
         opts.signal?.addEventListener("abort", abort, { once: true });
         if (opts.signal?.aborted)

package/dist/sessionIdentity.d.ts

@@ -23,6 +23,8 @@ export declare function canonicalSessionPath(path: string): string;
  * administrative Git directory (not in the checked-out tree), so normal edits
  * and commits do not change it while removal/recreation cannot inherit it.
  */
+/** Existing identity only: graph reads must never initialize a worktree marker. */
+export declare function readWorkspaceIdentity(cwd: string): string | undefined;
 export declare function captureWorkspaceIdentity(cwd: string): string | undefined;
 export declare function createProviderSessionRef(input: CreateProviderSessionRefInput): ProviderSessionRefV1;
 /** Identity used by accounting, compaction, settings acknowledgements, and mutation leases. */

package/dist/sessionIdentity.js

@@ -17,6 +17,20 @@ export function canonicalSessionPath(path) {
  * administrative Git directory (not in the checked-out tree), so normal edits
  * and commits do not change it while removal/recreation cannot inherit it.
  */
+/** Existing identity only: graph reads must never initialize a worktree marker. */
+export function readWorkspaceIdentity(cwd) {
+    try {
+        const canonicalCwd = canonicalSessionPath(cwd);
+        const gitDir = canonicalSessionPath(execFileSync("git", ["rev-parse", "--absolute-git-dir"], { cwd: canonicalCwd, encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim());
+        const token = readFileSync(join(gitDir, "rafi-workspace-id-v1"), "utf8").trim();
+        if (!/^[0-9a-f-]{36}$/i.test(token))
+            return undefined;
+        return createHash("sha256").update(`${canonicalCwd}\0${gitDir}\0${token}`).digest("hex");
+    }
+    catch {
+        return undefined;
+    }
+}
 export function captureWorkspaceIdentity(cwd) {
     try {
         const canonicalCwd = canonicalSessionPath(cwd);

package/dist/sessionLifecycle.js

@@ -79,7 +79,7 @@ export class RoleSessionController {
     }
     effectiveThreshold() {
         if (!this.thresholdController)
-            return this.options.settings.auto_compact_threshold_percent ?? 50;
+            return this.options.settings.auto_compact_threshold_percent ?? 65;
         return this.thresholdController.effectiveThreshold();
     }
     async next(durableHandoff, nextSettings) {
@@ -781,11 +781,11 @@ export class ThresholdCompactionController {
             ? effective
             : undefined;
     }
-    threshold() { return this.runOnlyThreshold ?? this.providerEffectiveThreshold ?? this.settings.auto_compact_threshold_percent ?? 50; }
+    threshold() { return this.runOnlyThreshold ?? this.providerEffectiveThreshold ?? this.settings.auto_compact_threshold_percent ?? 65; }
     now() { return this.options.now?.() ?? new Date(); }
 }
 function normalizeContextSettings(settings) {
-    const threshold = settings.auto_compact_threshold_percent ?? 50;
+    const threshold = settings.auto_compact_threshold_percent ?? 65;
     const maximum = settings.compact_maximum ?? 10;
     if (!Number.isInteger(threshold) || threshold < 1 || threshold > 99)
         throw new Error("auto_compact_threshold_percent must be an integer from 1 to 99");

package/dist/sources/sourceRegistry.js

@@ -1,3 +1,4 @@
+import { reconcileGraphSourceSelection } from "../graph/sources.js";
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 import { createHash } from "node:crypto";
@@ -67,6 +68,12 @@ export function saveSourceRegistry(projectDir, registry) {
     writeFileSync(configPath, stringify(raw, { lineWidth: 100 }), "utf8");
     backfillUniqueTicketSourceIds(root, registry);
     ensurePrivateCacheIgnored(root);
+    try {
+        reconcileGraphSourceSelection(root);
+    }
+    catch (error) {
+        console.error(`rafi graph: registered-source selection unavailable: ${String(error)}. Existing graph evidence must not substitute a later capture.`);
+    }
 }
 export function addPendingSourceDescription(registry, description, now = new Date()) {
     const value = description.trim();

package/dist/stateTransfer.js

@@ -1,14 +1,18 @@
+import { registerQaGraphJournalWriter } from "./qaDeliveryJournal.js";
+import { normalizeTransferredGraphState } from "./graph/storage.js";
+import { WorkflowReader } from "./workflowReader.js";
+import { classifyProcess } from "./processIdentity.js";
 import Database from "better-sqlite3";
 import { registerHandbackWriter } from "./qaHandbackMigration.js";
 import { createHash, randomUUID } from "node:crypto";
-import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
 import { gzipSync, gunzipSync } from "node:zlib";
 import { StateDb } from "./tickets/stateDb.js";
 import { DEFAULT_TICKETS_CONFIG } from "./tickets/config.js";
-import { WorkflowDb, readCurrentWorkflowLease, WORKFLOW_DB_FILE } from "./workflowDb.js";
+import { WorkflowDb, WORKFLOW_DB_FILE } from "./workflowDb.js";
 import { OBSERVABILITY_DB_FILE } from "./observability.js";
 export const STATE_BUNDLE_FORMAT = "rafi-state-bundle.v1";
 export const STATE_MANIFEST_PATH = "rafi-state-manifest.v1.json";
@@ -154,6 +158,29 @@ export async function importStateBundle(projectDir, bundleFile, opts = {}) {
             mkdirSync(dirname(out), { recursive: true });
             writeFileSync(out, Buffer.from(entry.data, "base64"));
         }
+        const workflowPath = join(staged, WORKFLOW_DB_FILE);
+        if (existsSync(workflowPath)) {
+            const preview = new Database(workflowPath, { readonly: true, fileMustExist: true });
+            try {
+                if (preview.pragma("integrity_check", { simple: true }) !== "ok" || preview.pragma("foreign_key_check").length)
+                    throw new Error("Imported workflow database integrity failure");
+                if (Number(preview.pragma("user_version", { simple: true })) > 4)
+                    throw new Error("Imported workflow requires a newer Rafi writer");
+                if (tableExists(preview, "build_work_scope"))
+                    for (const { name } of preview.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'qa_%'").all()) {
+                        if (!/^qa_[a-z_]+$/.test(name))
+                            throw new Error("Unexpected imported QA table");
+                        const columns = preview.prepare(`PRAGMA table_info(${name})`).all();
+                        if (columns.some(column => column.name === "run_id") && columns.some(column => column.name === "ticket_id") && preview.prepare(`SELECT 1 FROM ${name} q WHERE NOT EXISTS(SELECT 1 FROM build_work_scope s WHERE s.run_id=q.run_id AND s.work_id=q.ticket_id) LIMIT 1`).get())
+                            throw new Error(`Imported QA work is outside the ownership registry: ${name}`);
+                    }
+            }
+            finally {
+                preview.close();
+                rmSync(workflowPath + "-shm", { force: true });
+                rmSync(workflowPath + "-wal", { force: true });
+            }
+        }
         const backup = backupExistingState(root, opts.now ?? new Date());
         backupDir = backup?.durableBackupDir;
         rollbackDir = backup?.snapshotDir;
@@ -237,12 +264,18 @@ function assertDbBackedTickets(root) {
     }
 }
 function assertNoLiveLease(root, operation = "export") {
-    const lease = readCurrentWorkflowLease(root);
-    if (!lease)
-        return;
-    const ageMs = Date.now() - new Date(lease.heartbeatAt).getTime();
-    if (ageMs <= 45_000)
-        throw new Error(`refusing to ${operation} while live workflow lease exists for run ${lease.runId}; stop or pause the active run first, then retry the state ${operation}`);
+    const reader = new WorkflowReader(root);
+    try {
+        const admission = reader.buildAdmission();
+        if (admission && classifyProcess(admission.pid, admission.processStart, admission.host).state !== "dead")
+            throw new Error(`refusing to ${operation} while live or unknown build admission exists for run ${admission.runId}`);
+        const lease = reader.currentLease();
+        if (lease && classifyProcess(lease.pid, lease.processStart, lease.host).state !== "dead")
+            throw new Error(`refusing to ${operation} while live workflow lease exists for run ${lease.runId}; stop or pause the active run first, then retry the state ${operation}`);
+    }
+    finally {
+        reader.close();
+    }
 }
 function runCurrentMigrations(root) {
     if (existsSync(join(root, DEFAULT_TICKETS_CONFIG.paths.stateDb))) {
@@ -288,6 +321,15 @@ async function stageSqliteBackup(root, rel, dest) {
     const db = new Database(source, { readonly: true, fileMustExist: true });
     try {
         await db.backup(dest);
+        if (rel === WORKFLOW_DB_FILE) {
+            const stagedDb = new Database(dest);
+            try {
+                normalizeTransferredGraphState(stagedDb);
+            }
+            finally {
+                stagedDb.close();
+            }
+        }
     }
     finally {
         db.close();
@@ -398,8 +440,43 @@ function rewriteWorkflowDb(root, sourceRoot) {
     if (!existsSync(path))
         return;
     const db = new Database(path);
+    normalizeTransferredGraphState(db);
     registerHandbackWriter(db);
+    registerQaGraphJournalWriter(db);
+    db.function("rafi_work_authority", () => 1);
+    if (tableExists(db, "build_project_identity")) {
+        const prior = db.prepare("SELECT project_id,canonical_root FROM build_project_identity WHERE singleton=1").get();
+        db.transaction(() => {
+            db.exec("CREATE TABLE IF NOT EXISTS build_project_rebindings(sequence INTEGER PRIMARY KEY AUTOINCREMENT,project_id TEXT NOT NULL,previous_root TEXT NOT NULL,new_root TEXT NOT NULL,rebound_at TEXT NOT NULL)");
+            for (const action of ["INSERT", "UPDATE", "DELETE"])
+                db.exec(`CREATE TRIGGER IF NOT EXISTS rebinding_protocol_${action} BEFORE ${action} ON build_project_rebindings BEGIN SELECT CASE WHEN rafi_writer_protocol()<>4 THEN RAISE(ABORT,'incompatible project rebinding writer') END; END`);
+            for (const action of ["UPDATE", "DELETE"])
+                db.exec(`CREATE TRIGGER IF NOT EXISTS rebinding_immutable_${action} BEFORE ${action} ON build_project_rebindings BEGIN SELECT RAISE(ABORT,'Project rebinding history is immutable'); END`);
+            db.prepare("INSERT INTO build_project_rebindings(project_id,previous_root,new_root,rebound_at) VALUES(?,?,?,?)").run(prior.project_id, prior.canonical_root, realpathSync(root), new Date().toISOString());
+            db.prepare("UPDATE build_project_identity SET canonical_root=? WHERE singleton=1").run(realpathSync(root));
+        })();
+    }
+    // This connection only rewrites an offline imported snapshot. It cannot
+    // dispatch; preserve imported ownership as unknown instead of adopting it.
+    const importedOwner = tableExists(db, "build_admission") ? db.prepare("SELECT record_json FROM build_admission WHERE singleton=1").get() : undefined;
+    const owner = importedOwner ? JSON.parse(importedOwner.record_json) : undefined;
+    db.function("rafi_protocol_v3", () => 1);
+    db.function("rafi_build_lease_owner", () => "");
+    db.function("rafi_build_lease_generation", () => -1);
+    db.function("rafi_build_writer_run", () => "");
+    db.function("rafi_build_writer_token", () => owner?.token ?? "");
     try {
+        if (owner) {
+            db.exec("CREATE TABLE IF NOT EXISTS imported_build_ownership(record_json TEXT NOT NULL,imported_at TEXT NOT NULL)");
+            db.prepare("INSERT INTO imported_build_ownership VALUES(?,?)").run(importedOwner.record_json, new Date().toISOString());
+            db.prepare("UPDATE build_admission SET record_json=? WHERE singleton=1").run(JSON.stringify({ ...owner, project: root, host: `imported:${owner.host}` }));
+        }
+        if (tableExists(db, "build_retry_lineage"))
+            db.transaction(() => {
+                db.exec("DROP TRIGGER IF EXISTS build_lineage_immutable");
+                db.prepare("UPDATE build_retry_lineage SET project=? WHERE project=?").run(root, sourceRoot);
+                db.exec("CREATE TRIGGER build_lineage_immutable BEFORE UPDATE ON build_retry_lineage BEGIN SELECT RAISE(ABORT,'Retry lineage is immutable'); END;");
+            })();
         rewriteSqlJsonColumn(db, "workflow_runs", "run_id", ["original_work_json", "remaining_work_json", "state_json"], sourceRoot, root);
         rewriteSqlJsonColumn(db, "branch_resume_sessions", "rowid", ["session_json"], sourceRoot, root);
         if (tableExists(db, "qa_recovery_heads")) {

package/dist/statusReporter.d.ts

@@ -90,6 +90,7 @@ export declare class RoleStatusAdapter implements BuilderAdapter {
     restoreNativeCompactions(compactions: NativeCompaction[]): void;
     contextUsageAfterNativeCompaction(compaction: NativeCompaction): Promise<ContextUsage | undefined>;
     contextUsage(): Promise<ContextUsage | undefined>;
+    graphRuntimeSettings(): Pick<import("./adapters/types.js").BuilderAdapterOptions, "model" | "effort" | "fast" | "runtimeExecutable"> | undefined;
     sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     events(): AsyncIterable<BuilderEvent>;