ai-foreman 1.7.6 → 1.7.8

package/dist/buildRuns.js

@@ -1,10 +1,13 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import Database from "better-sqlite3";
 import { WorkflowDb } from "./workflowDb.js";
+import { canonicalSessionPath, captureWorkspaceIdentity, createProviderSessionRef, latestSessionBinding, upsertSessionBinding } from "./sessionIdentity.js";
+import { resolveProviderSessionAvailability } from "./sessionAvailability.js";
+import { captureCurrentWorkflowSessionIdentity, currentWorkflowIdentityKey } from "./branch/currentGuard.js";
 import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
 import { loadTickets } from "./tickets/ticketLoader.js";
 export const BUILD_RUN_VERSION = 2;
@@ -37,6 +40,7 @@ export function createBuildRun(input) {
             baselineComplete: Boolean(snapshot.baselineHead && snapshot.startHead && snapshot.branch),
         },
         progress: { completedTickets: [], completedOperations: [], remainingTickets: [...input.tickets], nextAction: input.tickets[0] ? `Start ${input.tickets[0]}` : "Plan next work" },
+        runDecisions: input.runDecisions,
         receipts: {},
         lease: currentLease(now),
         createdAt: stamp,
@@ -65,15 +69,27 @@ export function resumeBuildRun(projectDir, runId, patch, now = new Date()) {
     finally {
         workflow.close();
     }
+    const clearBuilderSession = patch.builderSessionId === null && patch.builderSessionRef === null;
+    const builderSessionId = clearBuilderSession
+        ? undefined
+        : patch.builderSessionRef?.sessionId ?? patch.builderSessionId ?? existing.builder?.sessionId;
     return saveBuildRun(projectDir, {
         ...existing, status: "running", checkpoint: "recovery-resumed", completedAt: undefined,
-        builder: patch.builder ? { settings: normalizeCapturedSettings(patch.builder), ...(patch.builderSessionId === null ? {} : { sessionId: patch.builderSessionId ?? existing.builder?.sessionId }) } : existing.builder,
+        builder: patch.builder ? { settings: normalizeCapturedSettings(patch.builder), ...(builderSessionId ? { sessionId: builderSessionId } : {}) } : existing.builder,
         qa: patch.qa ? { settings: normalizeCapturedSettings(patch.qa), sessionId: existing.qa?.sessionId } : existing.qa,
+        sessionBindings: patch.builderSessionRef ? upsertSessionBinding(existing.sessionBindings, patch.builderSessionRef) : existing.sessionBindings,
         lease: currentLease(now),
     }, now);
 }
 function normalizeCapturedSettings(settings) {
-    return { ...settings, session_strategy: settings.session_strategy ?? (["builder", "qa", "ticket-maker"].includes(settings.role) ? "compact" : "fresh"), settings_revision: settings.settings_revision ?? 0 };
+    return {
+        ...settings,
+        session_strategy: settings.session_strategy ?? (["builder", "qa", "ticket-maker"].includes(settings.role) ? "compact" : "fresh"),
+        display_session_cost: settings.display_session_cost ?? false,
+        auto_compact_threshold_percent: settings.auto_compact_threshold_percent ?? 50,
+        compact_maximum: settings.compact_maximum ?? 10,
+        settings_revision: settings.settings_revision ?? 0,
+    };
 }
 export function saveBuildRun(projectDir, run, now = new Date()) {
     validateBuildRun(run);
@@ -104,9 +120,9 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
                 remainingWork: { tickets: remainingTickets(next) }, state: next, event: "build_snapshot",
             }, now);
         if (next.builder?.sessionId)
-            workflow.recordSession(next.runId, "builder", "builder", next.builder.sessionId, "checkpoint", next.builder.settings, now);
+            workflow.recordSession(next.runId, "builder", "builder", latestSessionBinding(next.sessionBindings, "builder", next.builder.sessionId) ?? next.builder.sessionId, "checkpoint", next.builder.settings, now);
         if (next.qa?.sessionId)
-            workflow.recordSession(next.runId, "qa", "qa", next.qa.sessionId, "checkpoint", next.qa.settings, now);
+            workflow.recordSession(next.runId, "qa", "qa", latestSessionBinding(next.sessionBindings, "qa", next.qa.sessionId) ?? next.qa.sessionId, "checkpoint", next.qa.settings, now);
     }
     finally {
         workflow.close();
@@ -116,11 +132,40 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
 export function checkpointBuildRun(projectDir, run, checkpoint, patch = {}) {
     return saveBuildRun(projectDir, { ...run, ...patch, checkpoint, receipts: patch.receipts ?? run.receipts });
 }
-export function persistBuildSession(projectDir, run, role, sessionId) {
+export function persistBuildSession(projectDir, run, role, session) {
     const current = run[role];
     if (!current)
         throw new Error(`${role} settings were not captured for run ${run.runId}`);
-    return checkpointBuildRun(projectDir, { ...run, [role]: { ...current, sessionId } }, `${role}-session-ready`);
+    const sessionId = typeof session === "string" ? session : session.sessionId;
+    const sessionBindings = typeof session === "string" ? run.sessionBindings : upsertSessionBinding(run.sessionBindings, session);
+    return checkpointBuildRun(projectDir, { ...run, sessionBindings, [role]: { ...current, sessionId } }, `${role}-session-ready`);
+}
+/** Latest scoped binding, with the narrow legacy Builder inference allowed by the recovery protocol. */
+export function buildRunSessionBinding(run, role, sessionId) {
+    const bound = latestSessionBinding(run.sessionBindings, role, sessionId);
+    if (bound)
+        return bound;
+    if (role === "qa")
+        return undefined;
+    const raw = sessionId ?? run.builder?.sessionId;
+    if (!raw || !run.builder || !existsSync(run.repository.worktree))
+        return undefined;
+    return createProviderSessionRef({
+        provider: run.builder.settings.make,
+        sessionId: raw,
+        role: "builder",
+        stream: "builder",
+        generation: 0,
+        cwd: run.repository.worktree,
+        configRoot: run.repository.root,
+        workspaceIdentity: run.branchMode === "current" && run.repository.git.branch
+            ? currentWorkflowIdentityKey({ worktree: canonicalSessionPath(run.repository.worktree), ref: `branch:${run.repository.git.branch}` })
+            : run.repository.git.worktreeIdentity ?? captureWorkspaceIdentity(run.repository.worktree),
+        ticketId: run.currentTicket,
+        deliveryUnitId: run.deliveryUnit,
+        source: "legacy-inferred",
+        createdAt: run.createdAt,
+    });
 }
 export function recordBuildReceipt(projectDir, run, operationId, detail) {
     if (run.receipts[operationId])
@@ -244,11 +289,11 @@ export function buildRecoveryPreview(run) {
         `baseline ${run.repository.baselineComplete ? `${run.repository.git.baseRef ?? "recorded"} @ ${run.repository.git.baselineHead}` : "incomplete legacy baseline"}`,
         `preserved paths ${run.repository.git.runOwnedPaths.join(", ") || run.repository.git.statusPaths.join(", ") || "none recorded"}`,
         `completed operations ${completed.length ? completed.join(", ") : "none"}`,
-        `session ${run.builder?.sessionId ? "exact Builder session available" : "fresh Builder session required"}`,
-        `QA session ${run.qa?.sessionId ? "exact QA session available" : "fresh QA session required"}`,
+        `session ${buildRunSessionBinding(run, "builder") ? "Builder session candidate requires validation" : "fresh Builder session required"}`,
+        `QA session ${buildRunSessionBinding(run, "qa") ? "QA session candidate requires validation" : "fresh QA session required"}`,
     ];
 }
-export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOverride) {
+export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOverride, sessionAvailability) {
     let operationNames = [];
     let issues = [];
     let workflowState = {};
@@ -297,6 +342,9 @@ export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOv
         ? `Resume ${ticketOverride} from ${run.checkpoint}`
         : run.progress.nextAction ?? (ticketId ? `Resume ${ticketId} from ${run.checkpoint}` : `Resume from ${run.checkpoint}`);
     const primary = ticketId ? `${ticketId}${ticketTitle ? `: ${ticketTitle}` : ""}` : "legacy run (ticket unavailable)";
+    const stateSessionId = typeof workflowState.sessionId === "string" ? workflowState.sessionId : undefined;
+    const sessionCandidateRef = buildRunSessionBinding(run, "builder", stateSessionId ?? run.builder?.sessionId);
+    const exactSessionRef = sessionAvailability?.status === "available" ? sessionAvailability.sessionRef ?? sessionCandidateRef : undefined;
     return {
         run, ticketId, ticketTitle,
         compactLabel: `${primary} — ${run.status}`,
@@ -310,9 +358,33 @@ export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOv
         nextAction,
         worktree: recoveryWorktree,
         branch: stateBranch ?? branchNow ?? run.repository.git.branch ?? run.repository.branch,
-        exactSessionId: typeof workflowState.sessionId === "string" ? workflowState.sessionId : run.builder?.sessionId,
+        ...(sessionCandidateRef ? { sessionCandidateRef } : {}),
+        ...(sessionAvailability ? { sessionAvailability } : {}),
+        ...(exactSessionRef ? { exactSessionRef, exactSessionId: exactSessionRef.sessionId } : {}),
     };
 }
+export async function resolveBuildRecoveryProjection(projectDir, run, now = new Date(), ticketOverride, probe = {}) {
+    const frozen = projectBuildRecovery(projectDir, run, now, ticketOverride);
+    const candidate = frozen.sessionCandidateRef;
+    if (!candidate)
+        return frozen;
+    const availability = await resolveProviderSessionAvailability(candidate, {
+        ...probe,
+        cwd: frozen.worktree,
+        configRoot: run.repository.root,
+        workspaceIdentity: run.branchMode === "current" ? safeCurrentIdentity(frozen.worktree) : captureWorkspaceIdentity(frozen.worktree),
+        now,
+    });
+    return projectBuildRecovery(projectDir, run, now, ticketOverride, availability);
+}
+function safeCurrentIdentity(worktree) {
+    try {
+        return captureCurrentWorkflowSessionIdentity(worktree);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function formatBuildRecoveryProjection(projection) {
     const { run } = projection;
     const lines = [
@@ -327,7 +399,7 @@ export function formatBuildRecoveryProjection(projection) {
         `validation/QA ${projection.validation}`,
         `branch ${projection.branch ?? "current"}; worktree ${projection.worktree}`,
         `baseline ${run.repository.baselineComplete ? `${run.repository.git.baseRef ?? "recorded"} @ ${run.repository.git.baselineHead}` : "incomplete; automatic rollback is unavailable"}`,
-        `session ${projection.exactSessionId ? "exact Builder session available" : "fresh Builder session required"}`,
+        `session ${projection.exactSessionId ? "exact Builder session available (validated)" : projection.sessionCandidateRef ? `exact Builder session unavailable (${projection.sessionAvailability?.reason ?? "validation pending"})` : "fresh Builder session required"}`,
         `runtime ${run.builder?.settings.make ?? "unavailable"}; model ${run.builder?.settings.model ?? "unavailable"}`,
         `updated ${run.updatedAt}`,
         `preserved expected in-progress paths ${projection.expectedChanges.join(", ") || "none currently dirty"}`,
@@ -402,13 +474,7 @@ function captureGitSnapshot(worktree, input) {
     };
 }
 function worktreeIdentity(worktree) {
-    try {
-        const stat = statSync(resolve(worktree));
-        return createHash("sha256").update(`${stat.dev}:${stat.ino}`).digest("hex");
-    }
-    catch {
-        return undefined;
-    }
+    return captureWorkspaceIdentity(worktree);
 }
 function gitValue(cwd, args) {
     try {

package/dist/cli/handoffs.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function buildHandoffsCommand(): Command;

package/dist/cli/handoffs.js

@@ -0,0 +1,74 @@
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { recoverableBuildRuns } from "../buildRuns.js";
+import { HandoffService, writeHandoffInspection } from "../handoffs.js";
+import { WorkflowDb } from "../workflowDb.js";
+export function buildHandoffsCommand() {
+    const command = new Command("handoffs").description("Inspect and explicitly manage validated cumulative handoffs.");
+    command.command("inspect")
+        .requiredOption("--run <id>", "build run ID")
+        .option("--generation <n>", "handoff generation")
+        .option("--format <format>", "markdown or json", "markdown")
+        .option("--output <path>", "write inspection to a file")
+        .option("--project <dir>", "project directory", ".")
+        .action((opts) => {
+        const format = String(opts.format);
+        if (!["markdown", "json"].includes(format))
+            throw new Error("--format must be markdown or json");
+        const generation = opts.generation === undefined ? undefined : positiveInteger(opts.generation, "--generation");
+        const service = new HandoffService(resolve(String(opts.project)));
+        const value = service.inspect(String(opts.run), generation);
+        const content = format === "json"
+            ? `${JSON.stringify({ version: 1, lineage: value.lineage, manifest: value.manifest }, null, 2)}\n`
+            : value.markdown;
+        if (opts.output) {
+            writeHandoffInspection(String(opts.output), content);
+            console.log(`rafi handoffs: wrote ${format} inspection to ${resolve(String(opts.output))}`);
+        }
+        else
+            process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+    });
+    command.command("prune-cache")
+        .requiredOption("--run <id>", "build run ID")
+        .option("--keep-latest <n>", "number of newest cache generations to keep", "1")
+        .option("--project <dir>", "project directory", ".")
+        .action((opts) => {
+        const keep = nonNegativeInteger(opts.keepLatest, "--keep-latest");
+        const removed = new HandoffService(resolve(String(opts.project))).pruneCache(String(opts.run), keep);
+        console.log(`rafi handoffs: pruned ${removed.length} disposable cache generation(s); durable history was preserved`);
+    });
+    command.command("delete-history")
+        .requiredOption("--run <id>", "build run ID")
+        .requiredOption("--yes", "confirm irreversible durable history deletion")
+        .option("--project <dir>", "project directory", ".")
+        .action((opts) => {
+        const projectDir = resolve(String(opts.project));
+        const runId = String(opts.run);
+        const recoverable = recoverableBuildRuns(projectDir).find((run) => run.runId === runId);
+        if (recoverable)
+            throw new Error(`run ${runId} is active or recoverable; finish or explicitly clean up the run before deleting durable handoff history`);
+        const db = new WorkflowDb(projectDir);
+        try {
+            const deleted = db.deleteHandoffHistory(runId);
+            console.log(`rafi handoffs: deleted ${deleted} durable handoff generation(s) for run ${runId}`);
+            console.log(`rafi handoffs: disposable copies remain until pruned; run: rafi handoffs prune-cache --run ${shellQuote(runId)} --keep-latest 1`);
+        }
+        finally {
+            db.close();
+        }
+    });
+    return command;
+}
+function positiveInteger(value, label) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 1)
+        throw new Error(`${label} must be a positive safe integer`);
+    return result;
+}
+function nonNegativeInteger(value, label) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0)
+        throw new Error(`${label} must be a non-negative safe integer`);
+    return result;
+}
+function shellQuote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }