ai-foreman 1.5.0 → 1.6.0

package/dist/cli/status.js

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { resolve, join } from "node:path";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { findResumableBranchSessions, formatBranchContinueCommand } from "../branch/resume.js";
+import { recoverableBuildRuns } from "../buildRuns.js";
 function fail(message) {
     console.error(`foreman: ${message}`);
     process.exit(1);
@@ -10,65 +11,80 @@ export function buildStatusCommand() {
     return new Command("status")
         .description("Summarize the most recent foreman run for a project.")
         .argument("<project>", "path to the project directory")
-        .action((project) => {
-        const projectDir = resolve(project);
-        const dir = join(projectDir, ".foreman");
-        if (!existsSync(dir))
+        .action((project) => runStatus(project));
+}
+/** Print the existing Foreman status report for a resolved project. */
+export function runStatus(project) {
+    const projectDir = resolve(project);
+    const dir = join(projectDir, ".foreman");
+    const recoverable = recoverableBuildRuns(projectDir);
+    if (!existsSync(dir))
+        fail(`no foreman runs found under ${dir}`);
+    const logs = readdirSync(dir)
+        .filter((f) => f.endsWith(".jsonl"))
+        .sort();
+    if (logs.length === 0) {
+        if (recoverable.length === 0)
             fail(`no foreman runs found under ${dir}`);
-        const logs = readdirSync(dir)
-            .filter((f) => f.endsWith(".jsonl"))
-            .sort();
-        if (logs.length === 0)
-            fail(`no foreman runs found under ${dir}`);
-        const latest = join(dir, logs[logs.length - 1]);
-        const records = readFileSync(latest, "utf8")
-            .split("\n")
-            .filter(Boolean)
-            .map((line) => JSON.parse(line));
-        const steps = records.filter((r) => r.event === "step");
-        const escalations = records.filter((r) => r.event === "escalation");
-        const branchEvents = records.filter((r) => String(r.event).startsWith("branch-"));
-        const prEvents = records.filter((r) => ["pr-created", "pr-existing", "pr-failed"].includes(String(r.event)));
-        const latestFailure = findLatestGitHubFailure(records);
-        const batchEnd = [...records].reverse().find((r) => r.event === "batch-end");
-        console.log(`foreman: latest run ${logs[logs.length - 1]}`);
-        console.log(`foreman: ${steps.length} step record(s), ${escalations.length} escalation(s)`);
-        if (branchEvents.length || prEvents.length) {
-            const completed = branchEvents.filter((r) => r.event === "branch-complete").length;
-            const issues = branchEvents.filter((r) => r.event === "branch-issue").length;
-            const prs = prEvents.filter((r) => r.event === "pr-created" || r.event === "pr-existing").length;
-            console.log(`foreman: branch mode — ${completed} completed, ${issues} issue(s), ${prs} PR(s)`);
-        }
-        if (batchEnd) {
-            console.log(`foreman: outcome — ${batchEnd.outcome} (${batchEnd.completed}/${batchEnd.requested})`);
-            if (batchEnd.detail)
-                console.log(`foreman: ${batchEnd.detail}`);
-        }
-        else {
-            console.log("ai-foreman: run is still in progress or did not finish");
-        }
-        if (latestFailure) {
-            console.log(`foreman: latest GitHub failure — ${latestFailure.code}: ${latestFailure.message}`);
-            if (latestFailure.repairCommands.length > 0) {
-                console.log("foreman: repair and verify:");
-                for (const command of latestFailure.repairCommands) {
-                    console.log(`  ${command}`);
-                }
-            }
-            const retry = findRetryCommand(projectDir, dir, latestFailure);
-            if (retry) {
-                console.log("foreman: retry with:");
-                console.log(`  ${retry}`);
-            }
-            if (latestFailure.output) {
-                console.log("foreman: last command output:");
-                console.log(indent(limitLines(latestFailure.output, 8)));
+        printRecoverable(projectDir, recoverable);
+        return;
+    }
+    const latest = join(dir, logs[logs.length - 1]);
+    const records = readFileSync(latest, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+    const steps = records.filter((r) => r.event === "step");
+    const escalations = records.filter((r) => r.event === "escalation");
+    const branchEvents = records.filter((r) => String(r.event).startsWith("branch-"));
+    const prEvents = records.filter((r) => ["pr-created", "pr-existing", "pr-failed"].includes(String(r.event)));
+    const latestFailure = findLatestGitHubFailure(records);
+    const batchEnd = [...records].reverse().find((r) => r.event === "batch-end");
+    console.log(`foreman: latest run ${logs[logs.length - 1]}`);
+    console.log(`foreman: ${steps.length} step record(s), ${escalations.length} escalation(s)`);
+    if (branchEvents.length || prEvents.length) {
+        const completed = branchEvents.filter((r) => r.event === "branch-complete").length;
+        const issues = branchEvents.filter((r) => r.event === "branch-issue").length;
+        const prs = prEvents.filter((r) => r.event === "pr-created" || r.event === "pr-existing").length;
+        console.log(`foreman: branch mode — ${completed} completed, ${issues} issue(s), ${prs} PR(s)`);
+    }
+    if (batchEnd) {
+        console.log(`foreman: outcome — ${batchEnd.outcome} (${batchEnd.completed}/${batchEnd.requested})`);
+        if (batchEnd.detail)
+            console.log(`foreman: ${batchEnd.detail}`);
+    }
+    else {
+        console.log("ai-foreman: run is still in progress or did not finish");
+    }
+    if (latestFailure) {
+        console.log(`foreman: latest GitHub failure — ${latestFailure.code}: ${latestFailure.message}`);
+        if (latestFailure.repairCommands.length > 0) {
+            console.log("foreman: repair and verify:");
+            for (const command of latestFailure.repairCommands) {
+                console.log(`  ${command}`);
             }
         }
-        for (const esc of escalations) {
-            console.log(`  escalated: ${esc.tool} — ${esc.reason}`);
+        const retry = findRetryCommand(projectDir, dir, latestFailure);
+        if (retry) {
+            console.log("foreman: retry with:");
+            console.log(`  ${retry}`);
         }
-    });
+        if (latestFailure.output) {
+            console.log("foreman: last command output:");
+            console.log(indent(limitLines(latestFailure.output, 8)));
+        }
+    }
+    for (const esc of escalations) {
+        console.log(`  escalated: ${esc.tool} — ${esc.reason}`);
+    }
+    if (recoverable.length > 0)
+        printRecoverable(projectDir, recoverable);
+}
+function printRecoverable(projectDir, runs) {
+    console.log(`foreman: ${runs.length} unfinished/recoverable build run(s):`);
+    for (const run of runs)
+        console.log(`  ${run.runId}  ${run.currentTicket ?? run.tickets[0] ?? "unknown"}  ${run.active ? "active" : run.status}  checkpoint=${run.checkpoint}`);
+    console.log(`foreman: recover with \`rafi build:resume ${projectDir}\``);
 }
 function findLatestGitHubFailure(records) {
     for (let i = records.length - 1; i >= 0; i--) {

package/dist/cli/tickets.js

@@ -13,7 +13,8 @@ import { validateDocsRoot } from "../tickets/config.js";
 import { importExternalSources, importFromMarkdown, validateExternalSourceAccess } from "../tickets/importer.js";
 import { formatValidationIssues } from "../tickets/validate.js";
 import { assertEffortLevel, createRoleBuilder, makeLogPath, } from "../agentRun.js";
-import { DEFAULT_TICKET_SETUP, configuredPlanningSources, defaultAppName, ensureRafiConfigForTicketSetup, externalSources, hasTicketSetupConfig, loadTicketSetupConfig, loadTicketSetupConfigWithDefaults, localSourcePaths, mergeTicketSetup, recommendedBuildDefaults, saveTicketSetupConfig, } from "../tickets/setupConfig.js";
+import { DEFAULT_TICKET_SETUP, configuredPlanningSources, defaultAppName, ensureRafiConfigForTicketSetup, externalSources, hasTicketSetupConfig, loadTicketSetupConfig, loadTicketSetupConfigWithDefaults, localSourcePaths, mergeTicketSetup, recommendedBuildDefaults, saveTicketSetupConfig, urlSources, } from "../tickets/setupConfig.js";
+import { fetchAndSnapshotUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
 import { checkpointInterview, completeInterview, createInterviewRecord, failInterview, } from "../interviews.js";
 function fail(msg) {
     console.error(`foreman tickets: ${msg}`);
@@ -151,6 +152,7 @@ async function cmdSetupInitCli(opts) {
         const answers = await collectTicketSetup(dir, opts, undefined);
         if (interview)
             interview = checkpointInterview(dir, interview, { checkpoint: "save-setup", answers: { setup: answers } });
+        await validateConfiguredSourcesIfRequested(dir, answers, Boolean(opts.skipAccessCheck));
         ensureRafiConfigForTicketSetup(dir, {
             appName: opts.appName ?? defaultAppName(dir),
             docsRoot: opts.docsRoot,
@@ -162,7 +164,6 @@ async function cmdSetupInitCli(opts) {
             targets: parseRuntimeTargets(opts.runtime),
         });
         console.log(`foreman tickets setup: saved ticket setup in ${join(dir, "rafi-config.yaml")}`);
-        await validateConfiguredSourcesIfRequested(answers, Boolean(opts.skipAccessCheck));
         if (!isTicketsInitialized(dir)) {
             if (interview)
                 interview = checkpointInterview(dir, interview, { checkpoint: "initialize-tracker" });
@@ -209,6 +210,7 @@ async function cmdSetupUpdateCli(opts) {
         const next = mergeTicketSetup(current, patch);
         if (interview)
             interview = checkpointInterview(dir, interview, { checkpoint: "save-setup", answers: { setup: next } });
+        await validateConfiguredSourcesIfRequested(dir, next, Boolean(opts.skipAccessCheck));
         ensureRafiConfigForTicketSetup(dir, {
             appName: opts.appName ?? defaultAppName(dir),
             docsRoot: opts.docsRoot,
@@ -220,7 +222,6 @@ async function cmdSetupUpdateCli(opts) {
             targets: parseRuntimeTargets(opts.runtime),
         });
         console.log(`foreman tickets setup: updated ticket setup in ${join(dir, "rafi-config.yaml")}`);
-        await validateConfiguredSourcesIfRequested(next, Boolean(opts.skipAccessCheck));
         if (isTicketsInitialized(dir)) {
             const rows = cmdQueue(dir, 1);
             if (rows.length === 0) {
@@ -383,6 +384,7 @@ async function promptTicketSources(dir, current) {
             { value: "local", label: "Local docs, files, folders, or globs" },
             { value: "linear", label: "Linear" },
             { value: "jira", label: "Jira Cloud" },
+            { value: "url", label: "Public URL (HTML, text, Markdown, or PDF)" },
             { value: "none", label: "No saved source" },
         ],
     });
@@ -415,6 +417,17 @@ async function promptTicketSources(dir, current) {
                 filter: String(filter).trim() || null,
             }];
     }
+    if (kind === "url") {
+        const existing = current.find((source) => source.type === "url");
+        const answer = await text({
+            message: "Public HTTP(S) URL:",
+            initialValue: existing?.url,
+            validate: (value) => /^https?:\/\//i.test(String(value ?? "")) ? undefined : "Enter an HTTP(S) URL",
+        });
+        if (isCancel(answer))
+            process.exit(0);
+        return [{ type: "url", url: String(answer).trim() }];
+    }
     const site = await text({
         message: "Jira Cloud site URL:",
         placeholder: "https://your-domain.atlassian.net",
@@ -460,9 +473,11 @@ function sourcesFromSetupOptions(opts) {
             jql: opts.jiraJql,
         });
     }
+    for (const url of opts.urlSource ?? [])
+        sources.push({ type: "url", url });
     return sources;
 }
-async function validateConfiguredSourcesIfRequested(setup, skip) {
+async function validateConfiguredSourcesIfRequested(projectDir, setup, skip) {
     if (skip)
         return;
     for (const source of externalSources(setup)) {
@@ -474,6 +489,12 @@ async function validateConfiguredSourcesIfRequested(setup, skip) {
             console.log(`foreman tickets setup: ${source.type} access check skipped/failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    for (const source of urlSources(setup)) {
+        const fetched = await fetchAndSnapshotUrl(projectDir, source.url).catch((err) => {
+            throw new Error(`URL access validation failed for ${source.url}: ${err instanceof Error ? err.message : String(err)}`);
+        });
+        console.log(`foreman tickets setup: validated URL access (${fetched.contentType}, ${fetched.bytes} bytes)`);
+    }
 }
 function shouldPrompt(opts) {
     return !opts.defaults && !opts.yes && process.stdin.isTTY && process.stdout.isTTY;
@@ -637,12 +658,21 @@ export async function cmdPopulateCli(opts) {
     }
     const ticketsConfig = loadTicketsConfig(dir);
     const setup = loadTicketSetupConfig(dir);
-    const explicitSources = opts.sources;
+    const explicitSources = opts.sources ? await prepareDocumentSources(dir, opts.sources) : undefined;
     const configuredExternalSources = explicitSources?.length ? [] : externalSources(setup);
+    const configuredUrlSources = explicitSources?.length ? [] : urlSources(setup);
     const savedLocalSources = explicitSources?.length ? [] : localSourcePaths(setup);
-    const sourceHints = configuredExternalSources.length > 0 && savedLocalSources.length === 0
+    const selectedLocalHints = configuredExternalSources.length > 0 && savedLocalSources.length === 0 && configuredUrlSources.length === 0
         ? undefined
         : await resolvePopulateSourceSelection(dir, explicitSources, ticketsConfig, Boolean(opts.yes));
+    const localHints = selectedLocalHints ? await prepareDocumentSources(dir, selectedLocalHints) : undefined;
+    const urlHints = [];
+    for (const source of configuredUrlSources) {
+        const fetched = await fetchAndSnapshotUrl(dir, source.url);
+        urlHints.push(fetched.snapshotPath);
+        console.log(`foreman tickets: fetched ${source.url} -> ${fetched.snapshotPath}`);
+    }
+    const sourceHints = unique([...(localHints ?? []), ...urlHints]);
     const populateAgent = opts.agent
         ?? (setup?.populate.agent_preference && setup.populate.agent_preference !== "configured"
             ? setup.populate.agent_preference
@@ -678,7 +708,7 @@ export async function cmdPopulateCli(opts) {
             if (!validation.clean)
                 process.exit(1);
         }
-        if (!sourceHints?.length) {
+        if (!sourceHints.length) {
             console.log(`foreman tickets: imported external tickets and rendered ${ticketsConfig.paths.progressDoc}`);
             return;
         }
@@ -718,7 +748,7 @@ export async function cmdPopulateCli(opts) {
         console.log(`foreman tickets: project ${dir}`);
         console.log(`foreman tickets: role ${TICKET_POPULATE_ROLE}`);
         console.log(`foreman tickets: log ${logPath}\n`);
-        if (sourceHints?.length) {
+        if (sourceHints.length) {
             console.log(`foreman tickets: source hints ${sourceHints.join(" ")}`);
         }
         const turn = await foreman.runInstruction(buildPopulateInstruction(sourceHints, ticketsConfig.paths.progressDoc));
@@ -761,6 +791,21 @@ export async function cmdPopulateCli(opts) {
         fail(String(err instanceof Error ? err.message : err));
     }
 }
+async function prepareDocumentSources(projectDir, sources) {
+    const prepared = [];
+    for (const source of sources) {
+        if (/^https?:\/\//i.test(source)) {
+            prepared.push((await fetchAndSnapshotUrl(projectDir, source)).snapshotPath);
+            continue;
+        }
+        const absolute = resolve(source);
+        if (isAbsolute(source) && existsSync(absolute))
+            prepared.push(snapshotExternalLocalFile(projectDir, absolute));
+        else
+            prepared.push(source);
+    }
+    return unique(prepared);
+}
 export function buildTicketsCommand() {
     const tickets = new Command("tickets").description("Manage the structured ticket tracker for a project.");
     // ── setup:init / setup:update ─────────────────────────────────────────────
@@ -779,12 +824,13 @@ export function buildTicketsCommand() {
         .option("--linear-filter <filter>", "Linear IssueFilter JSON or title search text")
         .option("--jira-site <url>", "Jira Cloud site URL")
         .option("--jira-jql <jql>", "Jira JQL query")
+        .option("--url-source <urls...>", "add public HTTP(S) source URLs")
         .option("--agent-preference <agent>", "populate runtime preference (configured | claude | codex)")
         .option("--completion <mode>", "build completion default (pr | auto-merge | direct-merge | none)")
         .option("--provider <provider>", "PR/MR provider default (auto | github | gitlab | local)")
         .option("--auto-merge-wait", "wait for dependency PR/MRs to merge before starting dependent tickets")
         .option("--auto-merge-timeout-minutes <n>", "auto-merge dependency wait timeout in minutes (blank means no timeout)")
-        .option("--skip-access-check", "do not validate Linear/Jira access during setup")
+        .option("--skip-access-check", "do not validate configured source access during setup")
         .action(async (opts) => {
         try {
             await cmdSetupInitCli(opts);
@@ -808,12 +854,13 @@ export function buildTicketsCommand() {
         .option("--linear-filter <filter>", "Linear IssueFilter JSON or title search text")
         .option("--jira-site <url>", "Jira Cloud site URL")
         .option("--jira-jql <jql>", "Jira JQL query")
+        .option("--url-source <urls...>", "replace saved sources with public HTTP(S) URLs")
         .option("--agent-preference <agent>", "populate runtime preference (configured | claude | codex)")
         .option("--completion <mode>", "build completion default (pr | auto-merge | direct-merge | none)")
         .option("--provider <provider>", "PR/MR provider default (auto | github | gitlab | local)")
         .option("--auto-merge-wait", "wait for dependency PR/MRs to merge before starting dependent tickets")
         .option("--auto-merge-timeout-minutes <n>", "auto-merge dependency wait timeout in minutes (blank means no timeout)")
-        .option("--skip-access-check", "do not validate Linear/Jira access during setup")
+        .option("--skip-access-check", "do not validate configured source access during setup")
         .action(async (opts) => {
         try {
             await cmdSetupUpdateCli(opts);

package/dist/foreman.d.ts

@@ -49,13 +49,15 @@ export declare class Foreman {
     private readonly qaEnabled;
     private readonly qaMaxCycles;
     private readonly projectDir?;
+    private readonly qaReviewer?;
     private readonly ticketsEnabled;
-    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined);
+    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined, qaReviewer?: BuilderAdapter | undefined);
     /**
      * Send one instruction and resolve any needs_input exchanges before returning.
      * The returned result and status always reflect the final (non-needs_input) turn.
      */
     private doTurn;
+    private doTurnWith;
     /** Send a planning turn and return the builder's response text. Does not count toward steps. */
     runPreflight(n: number, ticketsContent?: string): Promise<string>;
     /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */

package/dist/foreman.js

@@ -3,6 +3,9 @@ import { MARKER_SPEC, QA_MARKER_SPEC } from "./markers.js";
 import { fireNotification } from "./notify.js";
 import { isTicketsInitialized } from "./tickets/config.js";
 import { cmdUpdate, cmdComplete, cmdBlock, cmdImplementationQueue } from "./tickets/commands.js";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
 /** Phrases that suggest the builder ended its turn by asking the human. */
 const QUESTION_HINTS = [
     "should i",
@@ -192,14 +195,16 @@ export class Foreman {
     qaEnabled;
     qaMaxCycles;
     projectDir;
+    qaReviewer;
     ticketsEnabled;
-    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir) {
+    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir, qaReviewer) {
         this.builder = builder;
         this.log = log;
         this.notificationsEnabled = notificationsEnabled;
         this.qaEnabled = qaEnabled;
         this.qaMaxCycles = qaMaxCycles;
         this.projectDir = projectDir;
+        this.qaReviewer = qaReviewer;
         this.ticketsEnabled = !!(projectDir && isTicketsInitialized(projectDir));
     }
     /**
@@ -207,7 +212,10 @@ export class Foreman {
      * The returned result and status always reflect the final (non-needs_input) turn.
      */
     async doTurn(instruction) {
-        let result = await this.builder.sendTurn(instruction);
+        return this.doTurnWith(this.builder, instruction);
+    }
+    async doTurnWith(adapter, instruction) {
+        let result = await adapter.sendTurn(instruction);
         let status = parseStepStatus(result.text);
         while (status.kind === "needs_input") {
             const question = status.question ?? "The builder has a question";
@@ -229,7 +237,7 @@ export class Foreman {
                 status = { kind: "blocked", reason: "user cancelled at input prompt" };
                 break;
             }
-            result = await this.builder.sendTurn(String(answer));
+            result = await adapter.sendTurn(String(answer));
             status = parseStepStatus(result.text);
         }
         return { result, status };
@@ -260,7 +268,15 @@ export class Foreman {
      */
     async runQa(stepIndex) {
         for (let cycle = 1; cycle <= this.qaMaxCycles; cycle++) {
-            const qa = await this.doTurn(buildQaInstruction());
+            const before = this.qaReviewer && this.projectDir ? fingerprintProtectedTree(this.projectDir) : undefined;
+            const qa = await this.doTurnWith(this.qaReviewer ?? this.builder, buildQaInstruction());
+            if (before && this.projectDir) {
+                const changes = changedProtectedFiles(before, fingerprintProtectedTree(this.projectDir));
+                if (changes.length > 0) {
+                    this.log.write("qa-protected-files-changed", { stepIndex, cycle, paths: changes });
+                    return { outcome: "needs-human", detail: `independent QA changed protected files: ${changes.join(", ")}` };
+                }
+            }
             this.log.write("qa", {
                 stepIndex,
                 cycle,
@@ -448,3 +464,29 @@ function lastLine(text) {
     const lines = text.trim().split("\n");
     return (lines[lines.length - 1] ?? "").slice(0, 200);
 }
+function fingerprintProtectedTree(root) {
+    const out = new Map();
+    const ignored = new Set([".git", "node_modules", "dist", "coverage"]);
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            const rel = relative(root, path).replace(/\\/g, "/");
+            if (entry.isDirectory()) {
+                if (ignored.has(entry.name) || rel.startsWith(".foreman/") || rel.startsWith(".rafi/cache/"))
+                    continue;
+                visit(path);
+            }
+            else if (entry.isFile() && statSync(path).size <= 10 * 1024 * 1024) {
+                out.set(rel, createHash("sha256").update(readFileSync(path)).digest("hex"));
+            }
+        }
+    };
+    if (existsSync(root))
+        visit(root);
+    return out;
+}
+function changedProtectedFiles(before, after) {
+    return [...new Set([...before.keys(), ...after.keys()])]
+        .filter((path) => before.get(path) !== after.get(path))
+        .sort();
+}

package/dist/interviews.d.ts

@@ -1,7 +1,8 @@
-export declare const INTERVIEW_STATE_VERSION = 1;
+export declare const INTERVIEW_STATE_VERSION = 2;
 export declare const INTERVIEW_DIRECTORY = ".rafi/interviews";
-export type InterviewWorkflow = "create" | "plan" | "tickets-setup-init" | "tickets-setup-update";
-export type InterviewStatus = "in_progress" | "needs_review" | "completed" | "incompatible";
+export type InterviewWorkflow = "create" | "plan" | "tickets-plan" | "tickets-setup-init" | "tickets-setup-update";
+export type InterviewStatus = "in_progress" | "paused" | "needs_review" | "completed" | "incompatible";
+export type InterviewStageStatus = "not_offered" | "offered" | "accepted" | "running" | "completed" | "skipped" | "paused" | "failed" | "cancelled";
 export interface InterviewRuntimeState {
     runtime?: "claude" | "codex";
     model?: string;
@@ -21,13 +22,31 @@ export interface InterviewFailure {
 export interface InterviewRecord {
     version: number;
     id: string;
+    journeyId: string;
+    parentId?: string;
+    childIds: string[];
     workflow: InterviewWorkflow;
     status: InterviewStatus;
     /** Arguments/context required to re-enter the runner. No environment secrets. */
     invocation: Record<string, unknown>;
     answers: Record<string, unknown>;
+    /** V2 name for compact persisted answers; `answers` remains as a compatibility alias. */
+    decisions: Record<string, unknown>;
     checkpoint: string;
+    stages: Record<string, {
+        status: InterviewStageStatus;
+        updatedAt: string;
+    }>;
+    planningMode?: "standard" | "exhaustive";
     runtime: InterviewRuntimeState;
+    runtimeAttempts: Array<{
+        runtime: "claude" | "codex";
+        at: string;
+        outcome: "ready" | "failed" | "cancelled";
+        category?: string;
+    }>;
+    sessionIds: Record<string, string>;
+    continuityLost: boolean;
     outputs: InterviewOutputFingerprint[];
     createdAt: string;
     updatedAt: string;
@@ -50,11 +69,14 @@ export declare function createInterviewRecord(input: {
     checkpoint: string;
     outputs?: string[];
     now?: Date;
+    parentId?: string;
+    journeyId?: string;
+    planningMode?: "standard" | "exhaustive";
 }): InterviewRecord;
 /** Ensure ignored local state exists without modifying unrelated gitignore text. */
 export declare function ensureInterviewGitignore(projectDir: string): void;
 export declare function saveInterviewRecord(projectDir: string, record: InterviewRecord, now?: Date): InterviewRecord;
-export declare function checkpointInterview(projectDir: string, record: InterviewRecord, update: Partial<Pick<InterviewRecord, "answers" | "checkpoint" | "runtime" | "outputs" | "invocation" | "status">>): InterviewRecord;
+export declare function checkpointInterview(projectDir: string, record: InterviewRecord, update: Partial<Pick<InterviewRecord, "answers" | "decisions" | "checkpoint" | "runtime" | "outputs" | "invocation" | "status" | "stages" | "planningMode" | "runtimeAttempts" | "sessionIds" | "continuityLost" | "childIds">>): InterviewRecord;
 export declare function failInterview(projectDir: string, record: InterviewRecord, checkpoint: string, error: unknown): InterviewRecord;
 export declare function completeInterview(projectDir: string, record: InterviewRecord, now?: Date): InterviewRecord;
 export declare function readInterviewRecords(projectDir: string): InterviewReadResult;

package/dist/interviews.js

@@ -7,7 +7,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join, relative, resolve } from "node:path";
-export const INTERVIEW_STATE_VERSION = 1;
+export const INTERVIEW_STATE_VERSION = 2;
 export const INTERVIEW_DIRECTORY = ".rafi/interviews";
 const MAX_FAILURE_LENGTH = 1_000;
 const COMPLETE_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
@@ -19,12 +19,21 @@ export function createInterviewRecord(input) {
     return {
         version: INTERVIEW_STATE_VERSION,
         id: randomUUID(),
+        journeyId: input.journeyId ?? randomUUID(),
+        parentId: input.parentId,
+        childIds: [],
         workflow: input.workflow,
         status: "in_progress",
         invocation: { ...input.invocation },
         answers: { ...(input.answers ?? {}) },
+        decisions: { ...(input.answers ?? {}) },
         checkpoint: input.checkpoint,
+        stages: { [input.checkpoint]: { status: "running", updatedAt: stamp } },
+        planningMode: input.planningMode,
         runtime: {},
+        runtimeAttempts: [],
+        sessionIds: {},
+        continuityLost: false,
         outputs: fingerprintOutputs(String(input.invocation.projectDir ?? ""), input.outputs ?? []),
         createdAt: stamp,
         updatedAt: stamp,
@@ -54,11 +63,26 @@ export function saveInterviewRecord(projectDir, record, now = new Date()) {
     return next;
 }
 export function checkpointInterview(projectDir, record, update) {
+    const nextAnswers = update.answers ?? update.decisions ?? record.answers;
+    const stamp = new Date().toISOString();
+    const stages = update.stages ?? (update.checkpoint && update.checkpoint !== record.checkpoint
+        ? {
+            ...record.stages,
+            [record.checkpoint]: { status: stageCompletionStatus(record.status), updatedAt: stamp },
+            [update.checkpoint]: { status: "running", updatedAt: stamp },
+        }
+        : record.stages);
     const next = {
         ...record,
         ...update,
-        answers: update.answers ? { ...update.answers } : record.answers,
+        answers: { ...nextAnswers },
+        decisions: { ...nextAnswers },
+        stages,
         runtime: update.runtime ? { ...update.runtime } : record.runtime,
+        sessionIds: update.runtime?.sessionId
+            ? { ...record.sessionIds, [update.runtime.runtime ?? "agent"]: update.runtime.sessionId }
+            : update.sessionIds ? { ...update.sessionIds } : record.sessionIds,
+        continuityLost: update.runtime?.continuityLost ?? update.continuityLost ?? record.continuityLost,
         invocation: update.invocation ? { ...update.invocation } : record.invocation,
         outputs: update.outputs ? update.outputs.map((output) => ({ ...output })) : record.outputs,
     };
@@ -79,6 +103,7 @@ export function completeInterview(projectDir, record, now = new Date()) {
         ...record,
         status: "completed",
         completedAt: stamp,
+        stages: { ...record.stages, [record.checkpoint]: { status: "completed", updatedAt: stamp } },
         failure: undefined,
     }, now);
 }
@@ -103,7 +128,7 @@ export function readInterviewRecords(projectDir) {
     return { records, problems };
 }
 export function unfinishedInterviews(projectDir) {
-    return readInterviewRecords(projectDir).records.filter((record) => record.status === "in_progress" || record.status === "needs_review" || record.status === "incompatible");
+    return readInterviewRecords(projectDir).records.filter((record) => record.status === "in_progress" || record.status === "paused" || record.status === "needs_review" || record.status === "incompatible");
 }
 export function findInterviewRecord(projectDir, id) {
     return readInterviewRecords(projectDir).records.find((record) => record.id === id || record.id.startsWith(id));
@@ -165,6 +190,8 @@ function parseInterviewRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("invalid interview record");
     const record = value;
+    if (record.version === 1)
+        return migrateV1Record(value);
     if (record.version !== INTERVIEW_STATE_VERSION) {
         // Preserve it on disk. The caller can show it and require an explicit discard.
         if (typeof record.id === "string" && typeof record.workflow === "string") {
@@ -175,10 +202,50 @@ function parseInterviewRecord(value) {
     validateRecord(record);
     return record;
 }
+function migrateV1Record(value) {
+    const legacy = value;
+    if (!legacy.id || !legacy.workflow || !legacy.checkpoint || !legacy.createdAt || !legacy.updatedAt) {
+        throw new Error("invalid V1 interview record");
+    }
+    const outputs = Array.isArray(legacy.outputs) ? legacy.outputs : [];
+    const evidenceIsComplete = outputs.length > 0 && outputs.every((item) => item && typeof item.path === "string" && typeof item.sha256 === "string");
+    const answers = legacy.answers && typeof legacy.answers === "object" ? legacy.answers : {};
+    const runtime = legacy.runtime && typeof legacy.runtime === "object" ? legacy.runtime : {};
+    const stamp = legacy.updatedAt;
+    return {
+        version: 2,
+        id: legacy.id,
+        journeyId: legacy.id,
+        childIds: [],
+        workflow: legacy.workflow,
+        status: legacy.status === "completed" ? "completed" : evidenceIsComplete ? "paused" : "needs_review",
+        invocation: legacy.invocation && typeof legacy.invocation === "object" ? legacy.invocation : {},
+        answers,
+        decisions: { ...answers },
+        checkpoint: legacy.checkpoint,
+        stages: { [legacy.checkpoint]: { status: evidenceIsComplete ? "paused" : "failed", updatedAt: stamp } },
+        runtime,
+        runtimeAttempts: [],
+        sessionIds: runtime.sessionId ? { [runtime.runtime ?? "agent"]: runtime.sessionId } : {},
+        continuityLost: Boolean(runtime.continuityLost || !runtime.sessionId),
+        outputs,
+        createdAt: legacy.createdAt,
+        updatedAt: legacy.updatedAt,
+        completedAt: legacy.completedAt,
+        failure: legacy.failure,
+    };
+}
+function stageCompletionStatus(status) {
+    if (status === "paused" || status === "needs_review")
+        return "paused";
+    if (status === "completed")
+        return "completed";
+    return "completed";
+}
 function validateRecord(record) {
     if (record.version !== INTERVIEW_STATE_VERSION)
         throw new Error("unsupported interview record version");
-    if (!record.id || !record.workflow || !record.checkpoint || !record.createdAt || !record.updatedAt) {
+    if (!record.id || !record.journeyId || !record.workflow || !record.checkpoint || !record.createdAt || !record.updatedAt) {
         throw new Error("invalid interview record");
     }
 }