ai-foreman 1.7.12 → 1.7.13

package/dist/tickets/output.js

@@ -0,0 +1,73 @@
+import { appendFileSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, statSync, } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
+import { DELIVERY_FILE } from "./delivery.js";
+export function appendTicketOutput(projectDir, outputFile, payload) {
+    const target = resolve(outputFile);
+    assertSafeOutputPath(projectDir, target);
+    const existed = existsSync(target);
+    if (existed && statSync(target).isDirectory()) {
+        throw new Error(`output destination is a directory: ${target}`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    const separator = existed ? separatorForExistingFile(target) : "";
+    appendFileSync(target, `${separator}${payload}`, {
+        encoding: "utf8",
+        flag: existed ? "a" : "wx",
+        mode: 0o600,
+    });
+    return { disposition: existed ? "appended" : "created", path: target };
+}
+function assertSafeOutputPath(projectDir, target) {
+    const root = resolve(projectDir);
+    const fixedProtectedPaths = [
+        join(root, ".tickets", "config.yaml"),
+        join(root, DELIVERY_FILE),
+    ];
+    rejectProtectedIdentity(target, fixedProtectedPaths);
+    const config = loadTicketsConfig(root);
+    const paths = resolveTicketPaths(config, root);
+    rejectProtectedIdentity(target, [paths.tickets, paths.stateDb]);
+}
+function rejectProtectedIdentity(target, protectedPaths) {
+    const targetIdentity = resolvedIdentity(target);
+    const protectedPath = protectedPaths.find((candidate) => resolvedIdentity(candidate) === targetIdentity);
+    if (protectedPath) {
+        throw new Error(`refusing to write ticket output to protected tracker input: ${resolve(protectedPath)}`);
+    }
+}
+function resolvedIdentity(path) {
+    const absolute = resolve(path);
+    try {
+        lstatSync(absolute);
+        return realpathSync(absolute);
+    }
+    catch {
+        let ancestor = dirname(absolute);
+        while (!existsSync(ancestor)) {
+            const parent = dirname(ancestor);
+            if (parent === ancestor)
+                return absolute;
+            ancestor = parent;
+        }
+        const suffix = relative(ancestor, absolute);
+        return resolve(realpathSync(ancestor), ...suffix.split(sep).filter(Boolean));
+    }
+}
+function separatorForExistingFile(path) {
+    const size = statSync(path).size;
+    if (size === 0)
+        return "";
+    const length = Math.min(2, size);
+    const tail = Buffer.alloc(length);
+    const fd = openSync(path, "r");
+    try {
+        readSync(fd, tail, 0, length, size - length);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (tail.length >= 2 && tail.at(-1) === 0x0a && tail.at(-2) === 0x0a)
+        return "";
+    return tail.at(-1) === 0x0a ? "\n" : "\n\n";
+}

package/dist/tickets/stateDb.d.ts

@@ -111,6 +111,7 @@ export declare class StateDb {
     deleteEvents(ids: number[]): void;
     getRecentEvents(limit: number): TicketEvent[];
     getTicketEvents(ticketId: string): TicketEvent[];
+    getAllTicketEvents(): TicketEvent[];
     insertValidationSnapshot(snap: Omit<ValidationSnapshot, "id">): void;
     getRecentValidationSnapshot(): ValidationSnapshot | undefined;
     getValidationSnapshots(scope?: string): ValidationSnapshot[];

package/dist/tickets/stateDb.js

@@ -287,6 +287,11 @@ export class StateDb {
             .prepare("SELECT * FROM ticket_events WHERE ticket_id = ? ORDER BY timestamp, id")
             .all(ticketId);
     }
+    getAllTicketEvents() {
+        return this.db
+            .prepare("SELECT * FROM ticket_events WHERE ticket_id IS NOT NULL ORDER BY timestamp, id")
+            .all();
+    }
     // ── validation_snapshots ──────────────────────────────────────────────────
     insertValidationSnapshot(snap) {
         this.db.prepare(`

package/dist/workflowDb.d.ts

@@ -1,4 +1,5 @@
-import type { BuildRecoveryDecisionReceipt, ContextSample, ContinuityCheckpoint, ContinuityDelta, ContinuityEvent, ContinuityHead, ContinuityHeadState, HandoffLineage, HandoffManifestV1, LiveSettingsAcknowledgment, OperationLifecycle, ProviderSessionRefV1, ResolvedAgentSettings, SessionUsageSample, WorkflowIssue } from "rafi-spec";
+import type { BuildRecoveryDecisionReceipt, ContextSample, ContinuityCheckpoint, ContinuityDelta, ContinuityEvent, ContinuityHead, ContinuityHeadState, HandoffLineage, HandoffManifestV1, LiveSettingsAcknowledgment, OperationLifecycle, PendingHumanDecision, ProviderSessionRefV1, RecoveryAttemptOutcome, RecoveryAttemptReceipt, ResolvedAutonomyPolicy, ResolvedAgentSettings, SessionUsageSample, StructuredInterruption, SupervisorState, WorkflowIssue } from "rafi-spec";
+import type { BranchResumeSession } from "./branch/resume.js";
 export declare const WORKFLOW_DB_FILE = ".rafi/recovery.sqlite3";
 export type WorkflowKind = "plan" | "ticket-plan" | "ticket-populate" | "uninstall" | "build" | "qa-remediation" | "recovery" | "legacy";
 export type WorkflowRunStatus = "running" | "paused" | "blocked" | "completed" | "failed" | "cancelled" | "superseded";
@@ -38,6 +39,8 @@ export interface ProjectLease {
 }
 /** Read the current project lease without creating or migrating recovery state. */
 export declare function readCurrentWorkflowLease(projectDir: string): ProjectLease | undefined;
+/** Heartbeat-only writer: one conditional UPDATE and no migrations, imports, events, or snapshots. */
+export declare function heartbeatCurrentWorkflowLease(projectDir: string, lease: ProjectLease, now?: Date): ProjectLease;
 export interface PublicationTransaction {
     transactionId: string;
     runId: string;
@@ -146,6 +149,27 @@ export declare class WorkflowDb {
     providerSessionBindings(sessionId?: string, role?: string): ProviderSessionRefV1[];
     recordIssue(runId: string, issue: WorkflowIssue): number;
     issues(runId: string): WorkflowIssue[];
+    freezeAutonomyPolicy(runId: string, policy: ResolvedAutonomyPolicy, now?: Date): ResolvedAutonomyPolicy;
+    autonomyPolicy(runId: string): ResolvedAutonomyPolicy | undefined;
+    recordInterruption(interruption: StructuredInterruption): StructuredInterruption;
+    interruptions(runId: string): StructuredInterruption[];
+    recoveryAttemptCount(runId: string, ticket: string | undefined, phase: string, cause: string, operationKey: string): number;
+    recordRecoveryAttempt(receipt: RecoveryAttemptReceipt): RecoveryAttemptReceipt;
+    updateRecoveryAttempt(attemptId: string, outcome: RecoveryAttemptOutcome, detail?: string, now?: Date): RecoveryAttemptReceipt;
+    recoveryAttempts(runId: string): RecoveryAttemptReceipt[];
+    ensureHumanDecision(input: {
+        decisionKey: string;
+        runId: string;
+        interruptionId: string;
+        prompt: string;
+        choices: PendingHumanDecision["choices"];
+        evidence?: PendingHumanDecision["evidence"];
+    }, now?: Date): PendingHumanDecision;
+    humanDecision(decisionId: string): PendingHumanDecision | undefined;
+    pendingHumanDecisions(runId: string): PendingHumanDecision[];
+    answerHumanDecision(runId: string, decisionId: string, choiceId: string, now?: Date): PendingHumanDecision;
+    putSupervisorState(runId: string, state: SupervisorState, now?: Date): SupervisorState;
+    supervisorState(runId: string): SupervisorState | undefined;
     planOperation(input: {
         runId: string;
         idempotencyKey: string;
@@ -159,7 +183,7 @@ export declare class WorkflowDb {
     }, now?: Date): OperationRecord;
     operation(idempotencyKey: string): OperationRecord | undefined;
     operations(runId: string): OperationRecord[];
-    putEvidence(kind: "handoff" | "diff" | "test", value: string | Buffer, now?: Date): string;
+    putEvidence(kind: "handoff" | "diff" | "test" | "qa", value: string | Buffer, now?: Date): string;
     getEvidence(digest: string): Buffer | undefined;
     stageHandoff(manifest: HandoffManifestV1, markdown: string): HandoffLineage;
     acceptHandoff(runId: string, generation: number, successor: string | ProviderSessionRefV1, now?: Date): HandoffLineage;
@@ -212,6 +236,11 @@ export declare class WorkflowDb {
     heartbeatLease(lease: ProjectLease, now?: Date): ProjectLease;
     releaseLease(lease: ProjectLease, now?: Date): void;
     currentLease(): ProjectLease | undefined;
+    recordBranchResumeSession(runId: string, session: BranchResumeSession, now?: Date): void;
+    completeBranchResumeSession(runId: string, ticket: string, status?: "completed" | "superseded", now?: Date): void;
+    branchResumeSessions(activeOnly?: boolean): BranchResumeSession[];
+    pruneTerminalTelemetry(retentionDays: number, now?: Date): number;
+    compactStorage(): void;
     importLegacyOnce(now?: Date): number;
     private upsertContinuityHead;
     private refreshRunContinuityHead;

package/dist/workflowDb.js

@@ -25,6 +25,24 @@ export function readCurrentWorkflowLease(projectDir) {
         db?.close();
     }
 }
+/** Heartbeat-only writer: one conditional UPDATE and no migrations, imports, events, or snapshots. */
+export function heartbeatCurrentWorkflowLease(projectDir, lease, now = new Date()) {
+    const path = join(resolve(projectDir), WORKFLOW_DB_FILE);
+    if (!existsSync(path))
+        throw new Error("workflow recovery database not found");
+    const db = new Database(path, { fileMustExist: true });
+    try {
+        const at = now.toISOString();
+        const result = db.prepare("UPDATE project_lease SET heartbeat_at=? WHERE singleton=1 AND owner=? AND generation=? AND run_id=?")
+            .run(at, lease.owner, lease.generation, lease.runId);
+        if (result.changes !== 1)
+            throw new Error("workflow lease ownership changed");
+        return { ...lease, heartbeatAt: at };
+    }
+    finally {
+        db.close();
+    }
+}
 /** Authoritative persistence for every resumable workflow in a project. */
 export class WorkflowDb {
     projectDir;
@@ -226,6 +244,11 @@ export class WorkflowDb {
         const scoped = sessionParts(typeof session === "object" ? session : undefined, typeof session === "string" ? session : undefined);
         if (scoped.ref)
             this.recordProviderSessionBinding(scoped.ref, now);
+        const duplicate = this.db.prepare(`SELECT 1 FROM provider_sessions WHERE run_id=? AND role=? AND stream=? AND provider=? AND model=?
+      AND COALESCE(session_id,'')=COALESCE(?,'') AND COALESCE(session_key,'')=COALESCE(?,'') AND transition=? AND settings_revision=? ORDER BY id DESC LIMIT 1`)
+            .get(runId, role, stream, settings.make, settings.model, scoped.id, scoped.key, transition, settings.settings_revision);
+        if (duplicate)
+            return;
         this.db.prepare(`INSERT INTO provider_sessions(run_id,role,stream,provider,model,session_id,session_key,session_ref_json,transition,settings_revision,created_at)
       VALUES(?,?,?,?,?,?,?,?,?,?,?)`).run(runId, role, stream, settings.make, settings.model, scoped.id, scoped.key, scoped.refJson, transition, settings.settings_revision, now.toISOString());
     }
@@ -266,6 +289,105 @@ export class WorkflowDb {
     issues(runId) {
         return this.db.prepare("SELECT issue_json FROM workflow_issues WHERE run_id=? ORDER BY issue_id").all(runId).map((row) => parseJson(row.issue_json));
     }
+    freezeAutonomyPolicy(runId, policy, now = new Date()) {
+        this.ensureRun(runId, "build", now);
+        this.db.prepare("INSERT INTO run_autonomy_policy(run_id,digest,policy_json,frozen_at) VALUES(?,?,?,?) ON CONFLICT(run_id) DO NOTHING")
+            .run(runId, policy.digest, json(policy), now.toISOString());
+        return this.autonomyPolicy(runId);
+    }
+    autonomyPolicy(runId) {
+        const row = this.db.prepare("SELECT policy_json FROM run_autonomy_policy WHERE run_id=?").get(runId);
+        return row ? parseJson(row.policy_json) : undefined;
+    }
+    recordInterruption(interruption) {
+        this.ensureRun(interruption.runId);
+        this.db.transaction(() => {
+            this.db.prepare(`INSERT INTO recovery_interruptions(interruption_id,run_id,code,domain,phase,cause,dispatch_state,operation_key,interruption_json,created_at)
+        VALUES(?,?,?,?,?,?,?,?,?,?) ON CONFLICT(interruption_id) DO NOTHING`).run(interruption.id, interruption.runId, interruption.code, interruption.domain, interruption.phase, interruption.cause, interruption.dispatchState, interruption.operation?.idempotencyKey ?? null, json(interruption), interruption.occurredAt);
+            this.insertEvent(interruption.runId, "recovery_interruption", interruption.phase, { interruptionId: interruption.id, code: interruption.code, domain: interruption.domain }, interruption.occurredAt);
+        })();
+        return interruption;
+    }
+    interruptions(runId) {
+        return this.db.prepare("SELECT interruption_json FROM recovery_interruptions WHERE run_id=? ORDER BY created_at,interruption_id").all(runId)
+            .map((row) => parseJson(row.interruption_json));
+    }
+    recoveryAttemptCount(runId, ticket, phase, cause, operationKey) {
+        const row = this.db.prepare(`SELECT COUNT(*) AS count FROM recovery_attempts
+      WHERE run_id=? AND ticket IS ? AND phase=? AND cause=? AND operation_key=? AND outcome IN ('intended','started','succeeded','failed')`)
+            .get(runId, ticket ?? null, phase, cause, operationKey);
+        return row.count;
+    }
+    recordRecoveryAttempt(receipt) {
+        this.ensureRun(receipt.runId);
+        this.db.transaction(() => {
+            this.db.prepare(`INSERT INTO recovery_attempts(attempt_id,run_id,ticket,phase,cause,operation_key,attempt,disposition,action,outcome,receipt_json,intended_at,updated_at)
+        VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(receipt.attemptId, receipt.runId, receipt.ticket ?? null, receipt.phase, receipt.cause, receipt.operationKey, receipt.attempt, receipt.disposition, receipt.action, receipt.outcome, json(receipt), receipt.intendedAt, receipt.intendedAt);
+            this.insertEvent(receipt.runId, "recovery_attempt_intended", receipt.phase, { attemptId: receipt.attemptId, attempt: receipt.attempt, action: receipt.action }, receipt.intendedAt);
+        })();
+        return receipt;
+    }
+    updateRecoveryAttempt(attemptId, outcome, detail, now = new Date()) {
+        const row = this.db.prepare("SELECT receipt_json FROM recovery_attempts WHERE attempt_id=?").get(attemptId);
+        if (!row)
+            throw new Error(`recovery attempt not found: ${attemptId}`);
+        const prior = parseJson(row.receipt_json);
+        const at = now.toISOString();
+        const next = { ...prior, outcome, ...(outcome === "started" ? { startedAt: at } : {}), ...(["succeeded", "failed", "cancelled"].includes(outcome) ? { completedAt: at } : {}), ...(detail ? { detail } : {}) };
+        this.db.prepare("UPDATE recovery_attempts SET outcome=?,receipt_json=?,updated_at=? WHERE attempt_id=?").run(outcome, json(next), at, attemptId);
+        this.insertEvent(next.runId, `recovery_attempt_${outcome}`, next.phase, { attemptId, detail }, at);
+        return next;
+    }
+    recoveryAttempts(runId) {
+        return this.db.prepare("SELECT receipt_json FROM recovery_attempts WHERE run_id=? ORDER BY intended_at,attempt_id").all(runId)
+            .map((row) => parseJson(row.receipt_json));
+    }
+    ensureHumanDecision(input, now = new Date()) {
+        this.ensureRun(input.runId);
+        const existing = this.db.prepare("SELECT decision_json FROM human_decisions WHERE decision_key=?").get(input.decisionKey);
+        if (existing)
+            return parseJson(existing.decision_json);
+        const decision = { decisionId: randomUUID(), runId: input.runId, interruptionId: input.interruptionId, prompt: input.prompt, choices: input.choices, status: "pending", createdAt: now.toISOString(), ...(input.evidence ? { evidence: input.evidence } : {}) };
+        this.db.transaction(() => {
+            this.db.prepare("INSERT INTO human_decisions(decision_id,decision_key,run_id,status,decision_json,created_at,updated_at) VALUES(?,?,?,'pending',?,?,?)")
+                .run(decision.decisionId, input.decisionKey, input.runId, json(decision), decision.createdAt, decision.createdAt);
+            this.insertEvent(input.runId, "human_decision_pending", "waiting-for-human", { decisionId: decision.decisionId, choices: decision.choices.map((choice) => choice.id) }, decision.createdAt);
+        })();
+        return decision;
+    }
+    humanDecision(decisionId) {
+        const row = this.db.prepare("SELECT decision_json FROM human_decisions WHERE decision_id=?").get(decisionId);
+        return row ? parseJson(row.decision_json) : undefined;
+    }
+    pendingHumanDecisions(runId) {
+        return this.db.prepare("SELECT decision_json FROM human_decisions WHERE run_id=? AND status='pending' ORDER BY created_at").all(runId)
+            .map((row) => parseJson(row.decision_json));
+    }
+    answerHumanDecision(runId, decisionId, choiceId, now = new Date()) {
+        const decision = this.humanDecision(decisionId);
+        if (!decision || decision.runId !== runId)
+            throw new Error(`pending decision not found for run ${runId}: ${decisionId}`);
+        if (decision.status !== "pending")
+            throw new Error(`decision ${decisionId} has already been answered`);
+        if (!decision.choices.some((choice) => choice.id === choiceId))
+            throw new Error(`invalid choice ${choiceId} for decision ${decisionId}`);
+        const at = now.toISOString();
+        const next = { ...decision, status: "answered", answeredAt: at, selectedChoiceId: choiceId };
+        this.db.prepare("UPDATE human_decisions SET status='answered',decision_json=?,updated_at=? WHERE decision_id=? AND status='pending'").run(json(next), at, decisionId);
+        this.insertEvent(runId, "human_decision_answered", "decision-received", { decisionId, choiceId }, at);
+        return next;
+    }
+    putSupervisorState(runId, state, now = new Date()) {
+        this.ensureRun(runId);
+        this.db.prepare(`INSERT INTO supervisor_leases(run_id,status,pid,generation,heartbeat_at,state_json,updated_at)
+      VALUES(?,?,?,?,?,?,?) ON CONFLICT(run_id) DO UPDATE SET status=excluded.status,pid=excluded.pid,generation=excluded.generation,heartbeat_at=excluded.heartbeat_at,state_json=excluded.state_json,updated_at=excluded.updated_at`)
+            .run(runId, state.status, state.pid ?? null, state.generation, state.heartbeatAt ?? null, json(state), now.toISOString());
+        return state;
+    }
+    supervisorState(runId) {
+        const row = this.db.prepare("SELECT state_json FROM supervisor_leases WHERE run_id=?").get(runId);
+        return row ? parseJson(row.state_json) : undefined;
+    }
     planOperation(input, now = new Date()) {
         const at = now.toISOString();
         this.db.prepare(`INSERT INTO operation_journal(idempotency_key,run_id,kind,status,intent_json,created_at,updated_at)
@@ -571,33 +693,70 @@ export class WorkflowDb {
         const row = this.db.prepare("SELECT * FROM project_lease WHERE singleton=1").get();
         return row ? { owner: row.owner, generation: row.generation, pid: row.pid, host: row.host, processStart: row.process_start, heartbeatAt: row.heartbeat_at, runId: row.run_id } : undefined;
     }
+    recordBranchResumeSession(runId, session, now = new Date()) {
+        this.ensureRun(runId, "build", now);
+        this.db.prepare(`INSERT INTO branch_resume_sessions(run_id,ticket,status,session_json,updated_at)
+      VALUES(?,?,'active',?,?) ON CONFLICT(run_id,ticket) DO UPDATE SET status='active',session_json=excluded.session_json,updated_at=excluded.updated_at`)
+            .run(runId, session.ticket, json(sanitizeContinuityValue(session)), now.toISOString());
+    }
+    completeBranchResumeSession(runId, ticket, status = "completed", now = new Date()) {
+        this.db.prepare("UPDATE branch_resume_sessions SET status=?,updated_at=? WHERE run_id=? AND ticket=?").run(status, now.toISOString(), runId, ticket);
+    }
+    branchResumeSessions(activeOnly = true) {
+        const rows = this.db.prepare(`SELECT session_json FROM branch_resume_sessions${activeOnly ? " WHERE status='active'" : ""} ORDER BY updated_at,ticket`).all();
+        return rows.map(row => parseJson(row.session_json));
+    }
+    pruneTerminalTelemetry(retentionDays, now = new Date()) {
+        const cutoff = new Date(now.getTime() - Math.max(1, retentionDays) * 86_400_000).toISOString();
+        const result = this.db.prepare(`DELETE FROM workflow_telemetry
+      WHERE run_id IN (SELECT run_id FROM workflow_runs WHERE status IN ('completed','failed','cancelled','superseded') AND updated_at<?)
+      AND id NOT IN (SELECT MAX(id) FROM workflow_telemetry GROUP BY run_id)`).run(cutoff);
+        this.db.pragma("incremental_vacuum(200)");
+        return result.changes;
+    }
+    compactStorage() {
+        const lease = this.currentLease();
+        if (lease && Date.now() - new Date(lease.heartbeatAt).getTime() <= 45_000)
+            throw new Error("refusing recovery database compaction while a live project lease exists");
+        this.db.pragma("wal_checkpoint(TRUNCATE)");
+        this.db.exec("VACUUM");
+    }
     importLegacyOnce(now = new Date()) {
+        const migration = "legacy-files-v1";
+        if (this.db.prepare("SELECT 1 FROM recovery_schema_migrations WHERE migration=?").get(migration))
+            return 0;
         const sources = [join(this.projectDir, ".foreman", "runs"), join(this.projectDir, ".rafi", "interviews"), join(this.projectDir, ".tickets", "delivery-sessions")];
         let count = 0;
-        for (const directory of sources) {
-            if (!existsSync(directory) || !statSync(directory).isDirectory())
-                continue;
-            for (const name of readdirSync(directory).filter((entry) => entry.endsWith(".json"))) {
-                const path = join(directory, name);
-                const digest = createHash("sha256").update(readFileSync(path)).digest("hex");
-                if (this.db.prepare("SELECT 1 FROM legacy_imports WHERE source_path=? AND digest=?").get(path, digest))
+        this.db.transaction(() => {
+            for (const directory of sources) {
+                if (!existsSync(directory) || !statSync(directory).isDirectory())
                     continue;
-                let parsed;
-                try {
-                    parsed = JSON.parse(readFileSync(path, "utf8"));
-                }
-                catch {
-                    parsed = { unreadable: true };
-                }
-                const runId = `legacy_${digest.slice(0, 24)}`;
-                if (!this.getRun(runId)) {
-                    this.createRun({ runId, kind: "legacy", checkpoint: "legacy-imported", originalWork: { source: path }, remainingWork: {}, state: { source: path, record: parsed }, legacy: true }, now);
-                    this.transition(runId, { status: "superseded", checkpoint: "legacy-imported", remainingWork: {}, event: "legacy_record_preserved" }, now);
+                for (const name of readdirSync(directory).filter((entry) => entry.endsWith(".json"))) {
+                    const path = join(directory, name);
+                    const digest = createHash("sha256").update(readFileSync(path)).digest("hex");
+                    if (this.db.prepare("SELECT 1 FROM legacy_imports WHERE source_path=? AND digest=?").get(path, digest))
+                        continue;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(readFileSync(path, "utf8"));
+                    }
+                    catch {
+                        parsed = { unreadable: true };
+                    }
+                    const record = parsed && typeof parsed === "object" ? parsed : undefined;
+                    const isBuild = (record?.version === 1 || record?.version === 2) && typeof record.runId === "string";
+                    const runId = isBuild ? String(record.runId) : `legacy_${digest.slice(0, 24)}`;
+                    if (!this.getRun(runId)) {
+                        this.createRun({ runId, kind: isBuild ? "build" : "legacy", checkpoint: isBuild && typeof record?.checkpoint === "string" ? record.checkpoint : "legacy-imported", originalWork: isBuild ? { tickets: record?.tickets ?? [] } : { source: path }, remainingWork: isBuild ? { tickets: record?.tickets ?? [] } : {}, state: isBuild ? record : { source: path, record: parsed }, legacy: true }, now);
+                        if (!isBuild)
+                            this.transition(runId, { status: "superseded", checkpoint: "legacy-imported", remainingWork: {}, event: "legacy_record_preserved" }, now);
+                    }
+                    this.db.prepare("INSERT INTO legacy_imports(source_path,digest,run_id,imported_at) VALUES(?,?,?,?)").run(path, digest, runId, now.toISOString());
+                    count += 1;
                 }
-                this.db.prepare("INSERT INTO legacy_imports(source_path,digest,run_id,imported_at) VALUES(?,?,?,?)").run(path, digest, runId, now.toISOString());
-                count += 1;
             }
-        }
+            this.db.prepare("INSERT INTO recovery_schema_migrations(migration,completed_at) VALUES(?,?)").run(migration, now.toISOString());
+        })();
         return count;
     }
     upsertContinuityHead(head) {
@@ -622,6 +781,13 @@ export class WorkflowDb {
     migrate() {
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS workflow_runs(run_id TEXT PRIMARY KEY,kind TEXT NOT NULL,status TEXT NOT NULL,checkpoint TEXT NOT NULL,original_work_json TEXT NOT NULL,remaining_work_json TEXT NOT NULL,state_json TEXT NOT NULL,lease_generation INTEGER,legacy INTEGER NOT NULL DEFAULT 0,created_at TEXT NOT NULL,updated_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS recovery_schema_migrations(migration TEXT PRIMARY KEY,completed_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS branch_resume_sessions(run_id TEXT NOT NULL,ticket TEXT NOT NULL,status TEXT NOT NULL,session_json TEXT NOT NULL,updated_at TEXT NOT NULL,PRIMARY KEY(run_id,ticket));
+      CREATE TABLE IF NOT EXISTS run_autonomy_policy(run_id TEXT PRIMARY KEY REFERENCES workflow_runs(run_id),digest TEXT NOT NULL,policy_json TEXT NOT NULL,frozen_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS recovery_interruptions(interruption_id TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),code TEXT NOT NULL,domain TEXT NOT NULL,phase TEXT NOT NULL,cause TEXT NOT NULL,dispatch_state TEXT NOT NULL,operation_key TEXT,interruption_json TEXT NOT NULL,created_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS recovery_attempts(attempt_id TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),ticket TEXT,phase TEXT NOT NULL,cause TEXT NOT NULL,operation_key TEXT NOT NULL,attempt INTEGER NOT NULL,disposition TEXT NOT NULL,action TEXT NOT NULL,outcome TEXT NOT NULL,receipt_json TEXT NOT NULL,intended_at TEXT NOT NULL,updated_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS human_decisions(decision_id TEXT PRIMARY KEY,decision_key TEXT NOT NULL UNIQUE,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),status TEXT NOT NULL,decision_json TEXT NOT NULL,created_at TEXT NOT NULL,updated_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS supervisor_leases(run_id TEXT PRIMARY KEY REFERENCES workflow_runs(run_id),status TEXT NOT NULL,pid INTEGER,generation INTEGER NOT NULL,heartbeat_at TEXT,state_json TEXT NOT NULL,updated_at TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS workflow_events(sequence INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),event_type TEXT NOT NULL,checkpoint TEXT NOT NULL,payload_json TEXT NOT NULL,created_at TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS role_settings(run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),role TEXT NOT NULL,boundary INTEGER NOT NULL,revision INTEGER NOT NULL,settings_json TEXT NOT NULL,created_at TEXT NOT NULL,PRIMARY KEY(run_id,role,boundary));
       CREATE TABLE IF NOT EXISTS project_settings_revisions(revision INTEGER PRIMARY KEY,defaults_json TEXT NOT NULL,created_at TEXT NOT NULL);
@@ -646,6 +812,8 @@ export class WorkflowDb {
       CREATE TABLE IF NOT EXISTS recovery_decisions(decision_id INTEGER PRIMARY KEY AUTOINCREMENT,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),decided_at TEXT NOT NULL,mode TEXT NOT NULL,digest TEXT NOT NULL UNIQUE,session_key TEXT,session_ref_json TEXT,receipt_json TEXT NOT NULL);
       CREATE INDEX IF NOT EXISTS workflow_events_run ON workflow_events(run_id,sequence);
       CREATE INDEX IF NOT EXISTS operations_run ON operation_journal(run_id,status);
+      CREATE INDEX IF NOT EXISTS recovery_attempt_scope ON recovery_attempts(run_id,ticket,phase,cause,operation_key,outcome);
+      CREATE INDEX IF NOT EXISTS human_decisions_run ON human_decisions(run_id,status,created_at);
       CREATE INDEX IF NOT EXISTS context_samples_run_role ON context_samples(run_id,role,sample_id);
       CREATE INDEX IF NOT EXISTS continuity_events_run ON continuity_events(run_id,sequence);
       CREATE INDEX IF NOT EXISTS continuity_checkpoints_run_role ON continuity_checkpoints(run_id,role,checkpoint_id);
@@ -676,8 +844,9 @@ export class WorkflowDb {
     }
     ensureColumn(table, column, definition) {
         const columns = this.db.prepare(`PRAGMA table_info(${table})`).all();
-        if (!columns.some((entry) => entry.name === column))
-            this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+        if (!columns.some((existing) => existing.name === column)) {
+            this.db.exec(`ALTER TABLE "${table}" ADD COLUMN "${column}" ${definition}`);
+        }
     }
 }
 function rowToRun(row) { return { runId: row.run_id, kind: row.kind, status: row.status, checkpoint: row.checkpoint, originalWork: parseJson(row.original_work_json), remainingWork: parseJson(row.remaining_work_json), state: parseJson(row.state_json), ...(row.lease_generation === null ? {} : { leaseGeneration: row.lease_generation }), legacy: Boolean(row.legacy), createdAt: row.created_at, updatedAt: row.updated_at }; }

package/dist/workflowReader.d.ts

@@ -0,0 +1,42 @@
+import type { PendingHumanDecision, RecoveryAttemptReceipt, SupervisorState, WorkflowIssue } from "rafi-spec";
+import { type OperationRecord, type ProjectLease, type WorkflowRunSnapshot } from "./workflowDb.js";
+import type { BranchResumeSession } from "./branch/resume.js";
+/** Inspection-only recovery access. It never creates `.rafi`, migrates, imports, checkpoints WAL, or updates timestamps. */
+export declare class WorkflowReader {
+    readonly path: string;
+    private readonly db?;
+    constructor(projectDir: string, path?: string);
+    close(): void;
+    available(): boolean;
+    getRun(runId: string): WorkflowRunSnapshot | undefined;
+    activeRuns(): WorkflowRunSnapshot[];
+    buildRuns(): WorkflowRunSnapshot[];
+    events(runId: string): Array<{
+        sequence: number;
+        type: string;
+        checkpoint: string;
+        payload: unknown;
+        at: string;
+    }>;
+    issues(runId: string): WorkflowIssue[];
+    operations(runId: string): OperationRecord[];
+    currentLease(): ProjectLease | undefined;
+    continuityHeads(runId: string): Array<{
+        role: string;
+        state: string;
+        sequence: number;
+        digest: string;
+        updatedAt: string;
+    }>;
+    branchResumeSessions(activeOnly?: boolean): BranchResumeSession[];
+    recoveryAttempts(runId: string): RecoveryAttemptReceipt[];
+    pendingHumanDecisions(runId: string): PendingHumanDecision[];
+    supervisorState(runId: string): SupervisorState | undefined;
+    /** Bounded bulk evidence read. Uses one query per table, never one connection or query per run. */
+    runEvidence(runIds: readonly string[], perKindLimit?: number): Record<string, {
+        events: ReturnType<WorkflowReader["events"]>;
+        issues: WorkflowIssue[];
+        operations: OperationRecord[];
+        continuity: ReturnType<WorkflowReader["continuityHeads"]>;
+    }>;
+}

package/dist/workflowReader.js

@@ -0,0 +1,171 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import Database from "better-sqlite3";
+import { WORKFLOW_DB_FILE } from "./workflowDb.js";
+/** Inspection-only recovery access. It never creates `.rafi`, migrates, imports, checkpoints WAL, or updates timestamps. */
+export class WorkflowReader {
+    path;
+    db;
+    constructor(projectDir, path = join(resolve(projectDir), WORKFLOW_DB_FILE)) {
+        this.path = path;
+        if (!existsSync(path))
+            return;
+        this.db = new Database(path, { readonly: true, fileMustExist: true });
+        this.db.pragma("query_only = ON");
+    }
+    close() { this.db?.close(); }
+    available() { return Boolean(this.db); }
+    getRun(runId) {
+        if (!this.db)
+            return undefined;
+        try {
+            const row = this.db.prepare("SELECT * FROM workflow_runs WHERE run_id=?").get(runId);
+            return row ? toRun(row) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    activeRuns() {
+        if (!this.db)
+            return [];
+        try {
+            return this.db.prepare("SELECT * FROM workflow_runs WHERE status IN ('running','paused','blocked') ORDER BY created_at").all().map(toRun);
+        }
+        catch {
+            return [];
+        }
+    }
+    buildRuns() {
+        if (!this.db)
+            return [];
+        try {
+            return this.db.prepare("SELECT * FROM workflow_runs WHERE kind='build' ORDER BY updated_at DESC").all().map(toRun);
+        }
+        catch {
+            return [];
+        }
+    }
+    events(runId) {
+        if (!this.db)
+            return [];
+        try {
+            return this.db.prepare("SELECT sequence,event_type,checkpoint,payload_json,created_at FROM workflow_events WHERE run_id=? ORDER BY sequence").all(runId).map(row => ({ sequence: Number(row.sequence), type: String(row.event_type), checkpoint: String(row.checkpoint), payload: JSON.parse(String(row.payload_json)), at: String(row.created_at) }));
+        }
+        catch {
+            return [];
+        }
+    }
+    issues(runId) {
+        if (!this.db)
+            return [];
+        try {
+            return this.db.prepare("SELECT issue_json FROM workflow_issues WHERE run_id=? ORDER BY issue_id").all(runId).map(row => JSON.parse(row.issue_json));
+        }
+        catch {
+            return [];
+        }
+    }
+    operations(runId) {
+        if (!this.db)
+            return [];
+        try {
+            return this.db.prepare("SELECT * FROM operation_journal WHERE run_id=? ORDER BY created_at,idempotency_key").all(runId).map(row => ({ idempotencyKey: String(row.idempotency_key), runId: String(row.run_id), kind: String(row.kind), status: String(row.status), intent: JSON.parse(String(row.intent_json)), ...(row.result_json ? { result: JSON.parse(String(row.result_json)) } : {}), ...(row.external_id ? { externalId: String(row.external_id) } : {}), ...(row.error ? { error: String(row.error) } : {}), createdAt: String(row.created_at), updatedAt: String(row.updated_at) }));
+        }
+        catch {
+            return [];
+        }
+    }
+    currentLease() {
+        if (!this.db)
+            return undefined;
+        try {
+            const row = this.db.prepare("SELECT * FROM project_lease WHERE singleton=1").get();
+            return row ? { owner: String(row.owner), generation: Number(row.generation), pid: Number(row.pid), host: String(row.host), processStart: String(row.process_start), heartbeatAt: String(row.heartbeat_at), runId: String(row.run_id) } : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    continuityHeads(runId) {
+        if (!this.db)
+            return [];
+        try {
+            return this.db.prepare("SELECT * FROM continuity_heads WHERE run_id=? ORDER BY role").all(runId).map(row => ({ role: String(row.role), state: String(row.state), sequence: Number(row.event_sequence), digest: String(row.digest), updatedAt: String(row.updated_at) }));
+        }
+        catch {
+            return [];
+        }
+    }
+    branchResumeSessions(activeOnly = true) {
+        if (!this.db)
+            return [];
+        try {
+            return this.db.prepare(`SELECT session_json FROM branch_resume_sessions${activeOnly ? " WHERE status='active'" : ""} ORDER BY updated_at,ticket`).all().map(row => JSON.parse(row.session_json));
+        }
+        catch {
+            return [];
+        }
+    }
+    recoveryAttempts(runId) {
+        if (!this.db)
+            return [];
+        try {
+            return this.db.prepare("SELECT receipt_json FROM recovery_attempts WHERE run_id=? ORDER BY intended_at,attempt_id").all(runId).map((row) => JSON.parse(row.receipt_json));
+        }
+        catch {
+            return [];
+        }
+    }
+    pendingHumanDecisions(runId) {
+        if (!this.db)
+            return [];
+        try {
+            return this.db.prepare("SELECT decision_json FROM human_decisions WHERE run_id=? AND status='pending' ORDER BY created_at").all(runId).map((row) => JSON.parse(row.decision_json));
+        }
+        catch {
+            return [];
+        }
+    }
+    supervisorState(runId) {
+        if (!this.db)
+            return undefined;
+        try {
+            const row = this.db.prepare("SELECT state_json FROM supervisor_leases WHERE run_id=?").get(runId);
+            return row ? JSON.parse(row.state_json) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Bounded bulk evidence read. Uses one query per table, never one connection or query per run. */
+    runEvidence(runIds, perKindLimit = 100) {
+        const result = {};
+        if (!this.db || !runIds.length)
+            return result;
+        const ids = [...new Set(runIds)].slice(0, 5);
+        for (const id of ids)
+            result[id] = { events: [], issues: [], operations: [], continuity: [] };
+        const marks = ids.map(() => "?").join(",");
+        const limit = Math.max(1, Math.min(500, perKindLimit));
+        try {
+            const events = this.db.prepare(`SELECT * FROM (SELECT run_id,sequence,event_type,checkpoint,payload_json,created_at,ROW_NUMBER() OVER(PARTITION BY run_id ORDER BY sequence DESC) rn FROM workflow_events WHERE run_id IN (${marks})) WHERE rn<=? ORDER BY run_id,sequence`).all(...ids, limit);
+            for (const row of events)
+                result[String(row.run_id)]?.events.push({ sequence: Number(row.sequence), type: String(row.event_type), checkpoint: String(row.checkpoint), payload: JSON.parse(String(row.payload_json)), at: String(row.created_at) });
+            const issues = this.db.prepare(`SELECT * FROM (SELECT run_id,issue_json,ROW_NUMBER() OVER(PARTITION BY run_id ORDER BY issue_id DESC) rn FROM workflow_issues WHERE run_id IN (${marks})) WHERE rn<=? ORDER BY run_id,rn DESC`).all(...ids, limit);
+            for (const row of issues)
+                result[String(row.run_id)]?.issues.push(JSON.parse(String(row.issue_json)));
+            const operations = this.db.prepare(`SELECT * FROM (SELECT *,ROW_NUMBER() OVER(PARTITION BY run_id ORDER BY created_at DESC,idempotency_key) rn FROM operation_journal WHERE run_id IN (${marks})) WHERE rn<=? ORDER BY run_id,created_at,idempotency_key`).all(...ids, limit);
+            for (const row of operations)
+                result[String(row.run_id)]?.operations.push({ idempotencyKey: String(row.idempotency_key), runId: String(row.run_id), kind: String(row.kind), status: String(row.status), intent: JSON.parse(String(row.intent_json)), ...(row.result_json ? { result: JSON.parse(String(row.result_json)) } : {}), ...(row.external_id ? { externalId: String(row.external_id) } : {}), ...(row.error ? { error: String(row.error) } : {}), createdAt: String(row.created_at), updatedAt: String(row.updated_at) });
+            const continuity = this.db.prepare(`SELECT * FROM continuity_heads WHERE run_id IN (${marks}) ORDER BY run_id,role`).all(...ids);
+            for (const row of continuity)
+                result[String(row.run_id)]?.continuity.push({ role: String(row.role), state: String(row.state), sequence: Number(row.event_sequence), digest: String(row.digest), updatedAt: String(row.updated_at) });
+        }
+        catch { /* an older recovery schema exposes only the legacy per-run accessors */ }
+        return result;
+    }
+}
+function toRun(row) {
+    return { runId: row.run_id, kind: row.kind, status: row.status, checkpoint: row.checkpoint, originalWork: JSON.parse(row.original_work_json), remainingWork: JSON.parse(row.remaining_work_json), state: JSON.parse(row.state_json), ...(row.lease_generation === null ? {} : { leaseGeneration: row.lease_generation }), legacy: Boolean(row.legacy), createdAt: row.created_at, updatedAt: row.updated_at };
+}