ai-foreman 1.7.5 → 1.7.7

package/dist/branch/runner.js

@@ -6,10 +6,12 @@ import { cmdBlock, cmdComplete, cmdUpdate } from "../tickets/commands.js";
 import { commitAll, createTicketWorktree, findWorktreeForBranch, currentWorktreeBranch, deleteLocalBranch, ensureCleanBaseWorktree, ensureForemanExcluded, hasTrackerChanges, hasWorktreeChanges, headCommitIfAhead, removeTicketWorktree, mergeBranchToLocalBase, } from "./git.js";
 import { checkGitHubPrMerged, createOrReusePr, enableGitHubAutoMerge, pushBranchForPr } from "./github.js";
 import { checkGitLabMrMerged, createOrReuseMr, enableGitLabAutoMerge, pushBranchForMr } from "./gitlab.js";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { WorkflowDb } from "../workflowDb.js";
 import { currentActivity, withActivityPhase } from "../activity.js";
+import { SessionUnavailableError } from "../adapters/sessionFailure.js";
+import { SessionUnavailableContinuityError } from "../continuity.js";
 export function readDeliveryUnitSession(projectDir, unitId) {
     const path = deliverySessionPath(projectDir, unitId);
     if (!existsSync(path))
@@ -46,7 +48,7 @@ export async function runBranchPlan(opts) {
     const summaries = [];
     const successfulBranches = new Set();
     const pushedBranches = new Set();
-    let builderStreamSession;
+    let builderStream;
     let builderWorkSessions = 0;
     const qaStream = { reviews: 0, modificationViolations: 0 };
     for (const issue of opts.plan.issues) {
@@ -138,28 +140,51 @@ export async function runBranchPlan(opts) {
                     base: node.baseBranch,
                     worktreePath,
                     sessionId: resumeSession.sessionId,
+                    sessionRef: resumeSession.sessionRef,
                 });
             }
             journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:in-progress`, { ticket: node.ticket.id, status: "in_progress" }, () => cmdUpdate(opts.projectDir, node.ticket.id, {
                 status: "in_progress", actor: "foreman",
                 summary: resumeSession ? `Resuming branch ${node.branch}` : `Starting branch ${node.branch}`,
             }));
-            const continuedBuilderSession = resumeSession?.sessionId ?? (opts.builderSessionStrategy === "compact" ? builderStreamSession : undefined);
-            builder = await opts.createBuilder(worktreePath, continuedBuilderSession);
-            if (opts.builderSessionStrategy === "compact" && builderWorkSessions > 0 && continuedBuilderSession) {
-                const compacted = await compactWithRetry(builder);
-                if (!compacted.ok) {
+            const ticketInstruction = resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths);
+            // Reattach the predecessor even for a `fresh` strategy so the host can
+            // publish and validate a cumulative handoff before creating its successor.
+            const sameWorktreeStream = builderStream && canonical(builderStream.worktreePath) === canonical(worktreePath) ? builderStream : undefined;
+            const continuedBuilderSession = resumeSession?.sessionId ?? sameWorktreeStream?.sessionId;
+            const continuedBuilderRef = resumeSession?.sessionRef ?? sameWorktreeStream?.sessionRef;
+            builder = await opts.createBuilder(worktreePath, continuedBuilderSession, continuedBuilderRef);
+            if (builderWorkSessions > 0 && continuedBuilderSession) {
+                const strategy = opts.builderSessionStrategy ?? "compact";
+                if (opts.builderSessionBoundary) {
+                    builder = await opts.builderSessionBoundary(builder, ticketInstruction, strategy, worktreePath);
+                }
+                else if (strategy === "compact") {
+                    const compacted = await compactWithRetry(builder);
+                    if (!compacted.ok) {
+                        await builder.close();
+                        builder = await opts.createBuilder(worktreePath);
+                    }
+                }
+                else {
                     await builder.close();
                     builder = await opts.createBuilder(worktreePath);
                 }
             }
             builderWorkSessions += 1;
             viewer = opts.observeBuilder?.(builder);
-            const foreman = new Foreman(builder, opts.log, opts.notificationsEnabled, opts.qaEnabled, 3, undefined);
-            const { result, status } = await foreman.runInstruction(resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths));
+            const foreman = new Foreman(builder, opts.log, opts.notificationsEnabled, opts.qaEnabled, 3, undefined, undefined, undefined, opts.qaSessionStrategy ?? "compact", undefined, opts.builderSessionStrategy ?? "compact", undefined, opts.beforeBuilderTurn ? (adapter, action) => opts.beforeBuilderTurn(adapter, action, worktreePath) : undefined);
+            const { result, status } = await foreman.runInstruction(ticketInstruction);
+            builder = foreman.builderAdapter();
             workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
             const sessionId = builder.sessionId();
-            builderStreamSession = opts.builderSessionStrategy === "compact" ? sessionId : undefined;
+            const sessionRef = builder.sessionRef?.();
+            if (sessionId)
+                builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
+            if (sessionId) {
+                opts.recordBuilderSession?.(sessionRef ?? sessionId, node.ticket.id, worktreePath);
+                workflowCheckpoint(opts.projectDir, opts.runId, "builder-session-scoped", node.ticket.id, { sessionId, sessionRef, worktree: worktreePath, branch: node.branch });
+            }
             if (sessionId) {
                 opts.log.write("branch-session", {
                     ticket: node.ticket.id,
@@ -167,6 +192,7 @@ export async function runBranchPlan(opts) {
                     base: node.baseBranch,
                     worktreePath,
                     sessionId,
+                    sessionRef: builder.sessionRef?.(),
                     agent: opts.agent,
                     model: opts.model,
                     effort: opts.effort,
@@ -183,7 +209,7 @@ export async function runBranchPlan(opts) {
                 if (node.deliveryUnitId) {
                     const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
                     mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
-                    writeFileSync(path, `${JSON.stringify({ unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, ticket: node.ticket.id }, null, 2)}\n`, "utf8");
+                    writeFileSync(path, `${JSON.stringify({ unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
                 }
             }
             opts.log.write("step", {
@@ -215,30 +241,47 @@ export async function runBranchPlan(opts) {
                 const qa = await runIsolatedQa({
                     ticket: node.ticket, builderWorktree: worktreePath, builderSummary: status.summary ?? result.text,
                     qaStrategy: opts.qaSessionStrategy ?? "compact", state: qaStream, createQa: opts.createQa, maxCycles: 3,
+                    sessionBoundary: opts.qaSessionBoundary,
                     evidence: (entry) => opts.log.write("qa-evidence", { ticket: node.ticket.id, ...entry }),
                     fix: async (issues) => {
                         if (!builder)
                             return { ok: false, detail: "Builder session unavailable" };
                         builderWorkSessions += 1;
-                        if (opts.builderSessionStrategy === "compact" && builder.sessionId()) {
+                        const digest = (await withActivityPhase("recording QA fix changes", () => changeManifestAsync(worktreePath, (state, detail) => currentActivity()?.update(state, detail), "recording QA fix changes"))).diffDigest;
+                        const fixInstruction = buildDurableQaFixHandoff(node.ticket, issues, worktreePath, result.text, digest);
+                        const strategy = opts.builderSessionStrategy ?? "compact";
+                        if (opts.builderSessionBoundary) {
+                            builder = await opts.builderSessionBoundary(builder, fixInstruction, strategy, worktreePath);
+                        }
+                        else if (strategy === "compact" && builder.sessionId()) {
                             const compacted = await compactWithRetry(builder);
                             if (!compacted.ok) {
                                 await builder.close();
                                 builder = await opts.createBuilder(worktreePath);
                             }
                         }
-                        else if (opts.builderSessionStrategy === "fresh") {
+                        else if (strategy === "fresh") {
                             await builder.close();
                             builder = await opts.createBuilder(worktreePath);
                         }
-                        const digest = (await withActivityPhase("recording QA fix changes", () => changeManifestAsync(worktreePath, (state, detail) => currentActivity()?.update(state, detail), "recording QA fix changes"))).diffDigest;
-                        const fixed = await builder.sendTurn(buildDurableQaFixHandoff(node.ticket, issues, worktreePath, result.text, digest));
+                        if (opts.beforeBuilderTurn)
+                            builder = await opts.beforeBuilderTurn(builder, fixInstruction, worktreePath);
+                        const fixed = await builder.sendTurn(fixInstruction);
                         const fixedStatus = parseStepStatus(fixed.text);
-                        builderStreamSession = opts.builderSessionStrategy === "compact" ? builder.sessionId() : undefined;
+                        const fixedSessionId = builder.sessionId();
+                        const fixedSessionRef = builder.sessionRef?.();
+                        if (fixedSessionId)
+                            builderStream = { sessionId: fixedSessionId, ...(fixedSessionRef ? { sessionRef: fixedSessionRef } : {}), worktreePath };
+                        if (fixedSessionId) {
+                            opts.recordBuilderSession?.(fixedSessionRef ?? fixedSessionId, node.ticket.id, worktreePath);
+                            workflowCheckpoint(opts.projectDir, opts.runId, "builder-session-scoped", node.ticket.id, { sessionId: fixedSessionId, sessionRef: fixedSessionRef, worktree: worktreePath, branch: node.branch });
+                        }
                         return { ok: !fixed.isError && fixedStatus.kind === "done", detail: fixedStatus.error ?? fixed.text.slice(0, 500) };
                     },
                     onNonconvergence: opts.qaNonconvergence,
                 });
+                if (qaStream.sessionId)
+                    opts.recordQaSession?.(qaStream.sessionRef ?? qaStream.sessionId, node.ticket.id, worktreePath);
                 workflowCheckpoint(opts.projectDir, opts.runId, "qa-after", node.ticket.id, { outcome: qa.outcome, detail: qa.detail });
                 if (qa.outcome !== "passed" && qa.outcome !== "waived") {
                     const detail = qa.detail ?? "QA did not pass";
@@ -444,6 +487,14 @@ export async function runBranchPlan(opts) {
                 removeTicketWorktree(opts.projectDir, worktreePath);
         }
         catch (err) {
+            if (err instanceof SessionUnavailableError || err instanceof SessionUnavailableContinuityError) {
+                const message = err.message;
+                opts.log.write("branch-issue", { ticket: node.ticket.id, code: "session_unavailable", message, blocking: true });
+                notifyIssue(opts.notificationsEnabled, `${node.ticket.id}: ${message}`);
+                summaries.push(summaryFor(node, "blocked", message));
+                opts.onSessionUnavailable?.(err);
+                return summaries;
+            }
             const message = err instanceof Error ? err.message : String(err);
             const code = message.includes("switched branch")
                 ? "branch_switch"
@@ -510,6 +561,7 @@ function workflowCheckpoint(projectDir, runId, checkpoint, ticket, payload) {
         if (!run)
             return;
         db.transition(runId, { checkpoint, state: { ...run.state, currentTicket: ticket, ...payload }, event: checkpoint, payload: { ticket, ...payload } });
+        db.appendContinuityEvent({ runId, role: "host", kind: checkpoint, payload: { ticket, ...payload }, authoritativeStateRevision: db.continuityHead(runId, "run")?.authoritativeStateRevision ?? 0 });
     }
     finally {
         db.close();
@@ -583,6 +635,14 @@ function autoMergePollMs() {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function canonical(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
 function notifyIssue(enabled, message) {
     if (enabled)
         fireNotification("Foreman branch issue", message);

package/dist/buildRuns.d.ts

@@ -1,42 +1,75 @@
-import type { BuildRunRecordV1, ResolvedAgentSettings } from "rafi-spec";
-export declare const BUILD_RUN_VERSION = 1;
+import type { BuildRunRecordV2, ProviderSessionRefV1, ResolvedAgentSettings, SessionAvailabilityV1 } from "rafi-spec";
+import { type ResolveSessionAvailabilityOptions } from "./sessionAvailability.js";
+export declare const BUILD_RUN_VERSION = 2;
 export declare const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export declare const BUILD_HEARTBEAT_MS = 10000;
 export declare const BUILD_LEASE_STALE_MS = 45000;
 export interface CreateBuildRunInput {
     tickets: string[];
     deliveryUnit?: string;
-    branchMode?: BuildRunRecordV1["branchMode"];
+    branchMode?: BuildRunRecordV2["branchMode"];
     repositoryRoot: string;
     worktree?: string;
     branch?: string;
     baseHead?: string;
+    baseRef?: string;
     startHead?: string;
     builder?: LegacyResolvedAgentSettings;
     qa?: LegacyResolvedAgentSettings;
+    runDecisions?: BuildRunRecordV2["runDecisions"];
     now?: Date;
 }
-export declare function createBuildRun(input: CreateBuildRunInput): BuildRunRecordV1;
+export declare function createBuildRun(input: CreateBuildRunInput): BuildRunRecordV2;
 export declare function resumeBuildRun(projectDir: string, runId: string, patch: {
     builder?: LegacyResolvedAgentSettings;
     qa?: LegacyResolvedAgentSettings;
     builderSessionId?: string | null;
-}, now?: Date): BuildRunRecordV1;
-type LegacyResolvedAgentSettings = Omit<ResolvedAgentSettings, "session_strategy" | "settings_revision"> & Partial<Pick<ResolvedAgentSettings, "session_strategy" | "settings_revision">>;
-export declare function saveBuildRun(projectDir: string, run: BuildRunRecordV1, now?: Date): BuildRunRecordV1;
-export declare function checkpointBuildRun(projectDir: string, run: BuildRunRecordV1, checkpoint: string, patch?: Partial<BuildRunRecordV1>): BuildRunRecordV1;
-export declare function persistBuildSession(projectDir: string, run: BuildRunRecordV1, role: "builder" | "qa", sessionId: string): BuildRunRecordV1;
-export declare function recordBuildReceipt(projectDir: string, run: BuildRunRecordV1, operationId: string, detail?: {
+    builderSessionRef?: ProviderSessionRefV1 | null;
+}, now?: Date): BuildRunRecordV2;
+type LegacyResolvedAgentSettings = Omit<ResolvedAgentSettings, "session_strategy" | "settings_revision" | "display_session_cost" | "auto_compact_threshold_percent" | "compact_maximum"> & Partial<Pick<ResolvedAgentSettings, "session_strategy" | "settings_revision" | "display_session_cost" | "auto_compact_threshold_percent" | "compact_maximum">>;
+export declare function saveBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
+export declare function checkpointBuildRun(projectDir: string, run: BuildRunRecordV2, checkpoint: string, patch?: Partial<BuildRunRecordV2>): BuildRunRecordV2;
+export declare function persistBuildSession(projectDir: string, run: BuildRunRecordV2, role: "builder" | "qa", session: string | ProviderSessionRefV1): BuildRunRecordV2;
+/** Latest scoped binding, with the narrow legacy Builder inference allowed by the recovery protocol. */
+export declare function buildRunSessionBinding(run: BuildRunRecordV2, role: "builder" | "qa", sessionId?: string): ProviderSessionRefV1 | undefined;
+export declare function recordBuildReceipt(projectDir: string, run: BuildRunRecordV2, operationId: string, detail?: {
     externalId?: string;
     detail?: string;
-}): BuildRunRecordV1;
-export declare function heartbeatBuildRun(projectDir: string, run: BuildRunRecordV1, now?: Date): BuildRunRecordV1;
-export declare function releaseBuildLease(projectDir: string, run: BuildRunRecordV1, status?: BuildRunRecordV1["status"]): BuildRunRecordV1;
-export declare function completeBuildRun(projectDir: string, run: BuildRunRecordV1, now?: Date): BuildRunRecordV1;
-export declare function readBuildRuns(projectDir: string): BuildRunRecordV1[];
-export declare function recoverableBuildRuns(projectDir: string, now?: Date): Array<BuildRunRecordV1 & {
+}): BuildRunRecordV2;
+export declare function heartbeatBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
+export declare function releaseBuildLease(projectDir: string, run: BuildRunRecordV2, status?: BuildRunRecordV2["status"]): BuildRunRecordV2;
+export declare function completeBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
+export declare function readBuildRuns(projectDir: string): BuildRunRecordV2[];
+export declare function recoverableBuildRuns(projectDir: string, now?: Date): Array<BuildRunRecordV2 & {
     active: boolean;
 }>;
-export declare function isLeaseActive(run: BuildRunRecordV1, now?: Date): boolean;
-export declare function buildRecoveryPreview(run: BuildRunRecordV1): string[];
+export declare function isLeaseActive(run: BuildRunRecordV2, now?: Date): boolean;
+export declare function buildRecoveryPreview(run: BuildRunRecordV2): string[];
+export interface BuildRecoveryProjection {
+    run: BuildRunRecordV2;
+    ticketId?: string;
+    ticketTitle?: string;
+    compactLabel: string;
+    compactHint: string;
+    completed: string[];
+    remaining: string[];
+    lastSuccess: string;
+    interruption: string;
+    validation: string;
+    expectedChanges: string[];
+    unexpectedChanges: Array<{
+        path: string;
+        risk: string;
+    }>;
+    nextAction: string;
+    worktree: string;
+    branch?: string;
+    exactSessionId?: string;
+    exactSessionRef?: ProviderSessionRefV1;
+    sessionCandidateRef?: ProviderSessionRefV1;
+    sessionAvailability?: SessionAvailabilityV1;
+}
+export declare function projectBuildRecovery(projectDir: string, run: BuildRunRecordV2, now?: Date, ticketOverride?: string, sessionAvailability?: SessionAvailabilityV1): BuildRecoveryProjection;
+export declare function resolveBuildRecoveryProjection(projectDir: string, run: BuildRunRecordV2, now?: Date, ticketOverride?: string, probe?: ResolveSessionAvailabilityOptions): Promise<BuildRecoveryProjection>;
+export declare function formatBuildRecoveryProjection(projection: BuildRecoveryProjection): string[];
 export {};