ai-foreman 1.7.29 → 2.0.1

package/dist/runtimePreflight.js

@@ -0,0 +1,77 @@
+/**
+ * Runtime environment checks that must run before Rafi's main modules load.
+ * Uses only Node built-ins so it still reports clearly on an unsupported
+ * Node, where importing the CLI itself fails with an opaque SyntaxError.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const REINSTALL_FIX = "reinstall Rafi under the active Node (npm install -g @rafi-ai/cli); in a Rafi workspace run `corepack pnpm install --frozen-lockfile`";
+function packageJson() {
+    try {
+        return JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Minimal semver check for the range forms Rafi declares: "24.x", "^13.0.3", "13.0.3". */
+export function satisfiesRange(version, range) {
+    const parse = (value) => value.replace(/^[v^~=]/, "").split(".").map(part => Number.parseInt(part, 10));
+    const [major, minor = 0, patch = 0] = parse(version);
+    const spec = range.trim();
+    if (/^\d+\.x(\.x)?$/.test(spec))
+        return major === Number.parseInt(spec, 10);
+    const [wantMajor, wantMinor = 0, wantPatch = 0] = parse(spec);
+    if (spec.startsWith("^"))
+        return major === wantMajor && (minor > wantMinor || minor === wantMinor && patch >= wantPatch);
+    return major === wantMajor && minor === wantMinor && patch === wantPatch;
+}
+export function checkRuntimeEnvironment() {
+    const pkg = packageJson();
+    const checks = [];
+    const nodeRange = pkg.engines?.node;
+    const nodeSupported = !nodeRange || satisfiesRange(process.versions.node, nodeRange);
+    if (nodeRange) {
+        const ok = nodeSupported;
+        checks.push({ ok, label: `node ${nodeRange}`, detail: `${process.version} (${process.execPath})`,
+            ...(ok ? {} : { fix: `run Rafi with Node ${nodeRange}, e.g. \`nvm use 24\`, and reinstall it there` }) });
+    }
+    const sqliteRange = pkg.dependencies?.["better-sqlite3"];
+    const require = createRequire(import.meta.url);
+    let installed;
+    try {
+        installed = require("better-sqlite3/package.json").version;
+    }
+    catch { /* reported below */ }
+    if (sqliteRange) {
+        const ok = Boolean(installed && satisfiesRange(installed, sqliteRange));
+        checks.push({ ok, label: `better-sqlite3 ${sqliteRange}`, detail: installed ? `installed ${installed}` : "not installed",
+            ...(ok ? {} : { fix: `the installed native SQLite module does not match the declared version; ${REINSTALL_FIX}` }) });
+    }
+    // Only probe the native binding on a supported Node with the declared
+    // version: under an unsupported Node the probe can abort the process
+    // (uncatchable N-API fatal error, seen on Node 18), and a mismatched module
+    // may load and then crash later (seen with 12.10 under Node 24).
+    if (nodeSupported && installed && (!sqliteRange || satisfiesRange(installed, sqliteRange))) {
+        try {
+            const Database = require("better-sqlite3");
+            new Database(":memory:").close();
+            checks.push({ ok: true, label: "native SQLite loads", detail: `Node ABI ${process.versions.modules}` });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const abi = /NODE_MODULE_VERSION (\d+)/.exec(message)?.[1];
+            checks.push({ ok: false, label: "native SQLite loads", detail: abi ? `built for Node ABI ${abi}, active Node ABI ${process.versions.modules}` : message.split("\n")[0],
+                fix: `rebuild the native module for this Node: ${REINSTALL_FIX}` });
+        }
+    }
+    return checks;
+}
+/** Text for a failed preflight, or undefined when every check passed. */
+export function runtimePreflightFailure(checks = checkRuntimeEnvironment()) {
+    const failed = checks.filter(check => !check.ok);
+    if (!failed.length)
+        return undefined;
+    return ["rafi: this runtime environment cannot run Rafi:", ...failed.map(check => `  - ${check.label}: ${check.detail}${check.fix ? `\n    fix: ${check.fix}` : ""}`)].join("\n");
+}

package/dist/runtimeReadiness.js

@@ -1,3 +1,4 @@
+import { ProbeIpcTracker } from "./probeIpc.js";
 import { fileURLToPath } from "node:url";
 import { cleanupReadiness } from "./readinessCleanup.js";
 import { windowsProbeCommand } from "./windowsProbeJob.js";
@@ -150,26 +151,31 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
         let providerSpawnError;
         let providerResult;
         let startupTimer;
+        const probeMessages = new ProbeIpcTracker(tag, child.pid);
         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))
+            child.on("message", raw => {
+                if (settled)
+                    return;
+                const message = probeMessages.accept(raw);
+                if (message === "conflict") {
+                    startupError = new RuntimeCleanupError("Readiness helper sent conflicting terminal results");
+                    abort();
+                    return;
+                }
+                if (!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();
-                    }
+                    providerResult = { exitCode: message.exitCode, signal: message.signal };
+                    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 });
+                    providerSpawnError = Object.assign(new Error(message.message), { code: message.code ?? undefined });
                     return;
                 }
                 if (message.kind !== "rafi-probe-registered")
@@ -186,7 +192,7 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
                     }
                     if (authority && ownedProcess)
                         journal.authorizeReadinessHelper(authority, ownedProcess, child.pid);
-                    child.send("rafi-probe-authorized", error => { if (error) {
+                    child.send({ version: 1, kind: "rafi-probe-authorized", id: tag, pid: child.pid }, error => { if (error) {
                         startupError = error;
                         abort();
                     } });
@@ -204,7 +210,7 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
         const notifySupervisor = (active) => {
             if (process.send && process.connected && process.env.RAFI_BUILD_WORKER_RUN && child.pid) {
                 try {
-                    process.send({ kind: "rafi-readiness-child", active, tag, pid: child.pid, processStart: active ? processStartIdentity(child.pid) : undefined }, () => { });
+                    process.send({ version: 1, kind: "rafi-readiness-child", runId: process.env.RAFI_BUILD_WORKER_RUN, generation: Number(process.env.RAFI_BUILD_WORKER_GENERATION), workerPid: process.pid, active, tag, pid: child.pid, processStart: active ? processStartIdentity(child.pid) ?? null : null }, () => { });
                 }
                 catch { /* Durable ownership survives a disconnected supervisor. */ }
             }
@@ -253,6 +259,8 @@ async function probeRuntimeInternal(cwd, runtime, opts) {
             if (settled)
                 return;
             settled = true;
+            if (useHost && !probeMessages.terminal && !cancelled && !timedOut && !spawnError)
+                startupError ??= new RuntimeCleanupError("Readiness helper exited without a correlated terminal result");
             if (providerResult) {
                 exitCode = providerResult.exitCode;
                 signal = providerResult.signal;

package/dist/sources/sourceRegistry.d.ts

@@ -1,6 +1,4 @@
 import type { ProjectSourceEntry, ProjectSourceLocator, ProjectSourceType, SourceRegistryConfig, SourceSnapshotStorage, TicketSetupSource } from "rafi-spec";
-export declare const SOURCE_REQUEST_START = "RAFI_SOURCE_REQUEST_START";
-export declare const SOURCE_REQUEST_END = "RAFI_SOURCE_REQUEST_END";
 export interface StructuredSourceRequest {
     type?: ProjectSourceType;
     description?: string;
@@ -38,7 +36,6 @@ export declare function removeSource(registry: SourceRegistryConfig, id: string)
 export declare function discardStagedSourceCaptures(projectDir: string, original: SourceRegistryConfig, staged: SourceRegistryConfig): void;
 /** Compatibility bridge for legacy ticket setup callers. Existing entries and versions are retained. */
 export declare function appendLegacyTicketSources(registry: SourceRegistryConfig, sources: TicketSetupSource[]): SourceRegistryConfig;
-export declare function extractSourceRequests(output: string): StructuredSourceRequest[];
 /** Deterministically recognize only an entire obvious locator; all other language stays pending for agent interpretation. */
 export declare function sourceRequestFromAnswer(answer: string, projectDir: string): StructuredSourceRequest;
 export declare function registerSourceRequests(projectDir: string, registry: SourceRegistryConfig, requests: StructuredSourceRequest[], opts?: {

package/dist/sources/sourceRegistry.js

@@ -8,10 +8,7 @@ import { parse, stringify } from "yaml";
 import { fetchAndSnapshotUrl, normalizePublicHttpUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
 import { fetchJiraIssues, fetchLinearIssues } from "../tickets/importer.js";
 import { withActivityPhase } from "../activity.js";
-import { structuredSourceRequestSchema, zodIssues } from "rafi-spec";
 const execFileAsync = promisify(execFile);
-export const SOURCE_REQUEST_START = "RAFI_SOURCE_REQUEST_START";
-export const SOURCE_REQUEST_END = "RAFI_SOURCE_REQUEST_END";
 const CONFIG_FILE = "rafi-config.yaml";
 const DEFAULT_REGISTRY = { version: 1, snapshot_storage: "local", entries: [] };
 export function emptySourceRegistry(storage = "local") {
@@ -138,45 +135,6 @@ export function appendLegacyTicketSources(registry, sources) {
         migrateTicketSource(next, source, warnings);
     return next;
 }
-export function extractSourceRequests(output) {
-    const requests = [];
-    let cursor = 0;
-    while (true) {
-        const start = output.indexOf(SOURCE_REQUEST_START, cursor);
-        if (start < 0)
-            break;
-        const end = output.indexOf(SOURCE_REQUEST_END, start + SOURCE_REQUEST_START.length);
-        if (end < 0)
-            throw new Error(`source request is missing ${SOURCE_REQUEST_END}`);
-        const body = output.slice(start + SOURCE_REQUEST_START.length, end).trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
-        let value;
-        try {
-            value = JSON.parse(body);
-        }
-        catch (error) {
-            throw new Error(`source request is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        const values = Array.isArray(value) ? value : [value];
-        for (const item of values) {
-            const parsed = structuredSourceRequestSchema.safeParse(item);
-            if (!parsed.success)
-                throw new Error(`source request contract validation failed:\n${zodIssues(parsed.error).map((issue) => `- ${issue}`).join("\n")}`);
-            requests.push(parsed.data);
-        }
-        cursor = end + SOURCE_REQUEST_END.length;
-    }
-    // Compatibility with the original single-line protocol. Preserve the complete remainder.
-    for (const match of output.matchAll(/^SOURCE_REQUEST:\s*(.+)$/gim)) {
-        const legacy = structuredSourceRequestSchema.safeParse({ description: match[1].trim() });
-        // Legacy lines are intentionally converted into the same typed contract;
-        // they remain description-only pending requests after registration, but
-        // they no longer bypass shape validation.
-        if (!legacy.success)
-            throw new Error(`legacy source request contract validation failed:\n${zodIssues(legacy.error).map((issue) => `- ${issue}`).join("\n")}`);
-        requests.push(legacy.data);
-    }
-    return requests;
-}
 /** Deterministically recognize only an entire obvious locator; all other language stays pending for agent interpretation. */
 export function sourceRequestFromAnswer(answer, projectDir) {
     const value = answer.trim();

package/dist/statusReporter.d.ts

@@ -74,6 +74,8 @@ export declare class RoleStatusAdapter implements BuilderAdapter {
     private readonly adapter;
     private readonly onActive;
     private readonly onClose;
+    postConfirmedDispatch(reference: import("./adapters/types.js").ConfirmedDispatchReference): Promise<TurnResult | void>;
+    structuredDispatchRequirement(): import("./adapters/types.js").StructuredDispatchRequirement | undefined;
     readonly agent: "claude" | "codex";
     constructor(adapter: BuilderAdapter, onActive: (adapter: BuilderAdapter) => void, onClose: () => void);
     contractCapabilities(): {

package/dist/statusReporter.js

@@ -164,6 +164,8 @@ export class RoleStatusAdapter {
     adapter;
     onActive;
     onClose;
+    postConfirmedDispatch(reference) { return this.adapter.postConfirmedDispatch?.(reference) ?? Promise.resolve(); }
+    structuredDispatchRequirement() { return this.adapter.structuredDispatchRequirement?.(); }
     agent;
     constructor(adapter, onActive, onClose) {
         this.adapter = adapter;

package/dist/structuredCutover.d.ts

@@ -0,0 +1,31 @@
+import type Database from "better-sqlite3";
+export declare const STRUCTURED_CUTOVER = "003_structured_communication_v2_cutover";
+export declare const STRUCTURED_AUDIT_CLOSURE = "004_structured_communication_audit_closure";
+export declare const STRUCTURED_CUTOVER_MATRIX_VERSION = 3;
+export declare const STRUCTURED_CUTOVER_REASON = "structured-communication-v2-cutover";
+export declare const STRUCTURED_AUTHORITY_TABLES: readonly string[];
+type Row = Record<string, any>;
+type ForeignKey = {
+    id: number;
+    seq: number;
+    table: string;
+    from: string;
+    to: string;
+};
+export interface CutoverOwnershipEntry {
+    table: string;
+    disposition: "retain" | "purge-owned";
+    columns: string[];
+    foreignKeys: ForeignKey[];
+    jsonColumns: string[];
+    owner: "retained-artifact" | "run-id" | "foreign-key" | "session-key" | "contract-id" | "json-run-id";
+    evidenceReferenceExtractor: "normalized-refs-with-conservative-unknown-retention";
+    deletionOrder: number | null;
+}
+export declare function cutoverOwnershipMatrix(db: Database.Database): CutoverOwnershipEntry[];
+export declare function assertStructuredCutoverComplete(db: Database.Database): void;
+/** Classification is structural; JSON spelling or merely containing a tuple key is never proof. */
+export declare function invalidStructuredRun(db: Database.Database, run: Row, projectDir?: string): boolean;
+/** Archive then delete only selected rows. Foreign-key closure computes child ownership and deletion order. */
+export declare function purgeStructuredRun(db: Database.Database, runId: string, matrix: CutoverOwnershipEntry[], fileReferences?: ReadonlySet<string>): number;
+export {};