ai-foreman 1.7.11 → 1.7.13

package/dist/adapters/types.d.ts

@@ -2,6 +2,7 @@
  * Agent-agnostic interface over a coding agent ("builder").
  */
 import type { ConfigurableAgentRole, ProviderSessionRefV1, RuntimeProbeCategory, RuntimeProbePhase, SessionAvailabilityV1 } from "rafi-spec";
+import type { RunObserver } from "../observability.js";
 /** A permission request surfaced by a builder before it runs a tool. */
 export interface PermissionRequest {
     toolName: string;
@@ -58,16 +59,53 @@ export interface TurnResult {
     costAuthoritative?: boolean;
     inputTokens?: number;
     outputTokens?: number;
+    /** Explicit counter semantics. Compatibility counters above must not be summed without this scope. */
+    usage?: {
+        scope: "turn-delta" | "session-cumulative";
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        costUsd?: number;
+    };
     failure?: RuntimeFailure;
+    /** Stable host/provider correlation ID for this turn. */
+    turnId?: string;
+    /** Exact instruction requested by the immediate host caller. */
+    hostInstruction?: string;
+    /** Exact instruction dispatched to the provider after all wrappers. */
+    providerInstruction?: string;
+    /** Exact provider response before continuity or contract cleanup. */
+    rawResponse?: string;
+    /** Effective response consumed by the host contract parser. */
+    cleanedResponse?: string;
+    providerMetadata?: {
+        provider: "claude" | "codex";
+        sessionId?: string;
+        sessionRef?: ProviderSessionRefV1;
+    };
 }
 /** Observability events emitted while a builder works. */
-export type BuilderEvent = {
+export type BuilderEvent = ({
     kind: "text";
     text: string;
+    byteCount?: number;
+    digest?: string;
 } | {
     kind: "tool";
     name: string;
     input: unknown;
+    inputCompleteness?: "complete" | "truncated" | "unavailable";
+    lifecycle?: "started" | "progress" | "completed";
+    callId?: string;
+    status?: string;
+    durationMs?: number;
+    exitCode?: number;
+    outputSummary?: string;
+    outputDigest?: string;
+    outputCompleteness?: "complete" | "truncated" | "unavailable";
+    rawOutputBytes?: number;
+    completionKnown?: boolean;
+    providerTurnId?: string;
 } | {
     kind: "activity";
     state: string;
@@ -83,9 +121,12 @@ export type BuilderEvent = {
     maximum?: number;
     delayMs?: number;
     managedBy: "provider" | "rafi";
+    retryId?: string;
+    providerTurnId?: string;
 } | {
     kind: "turn-complete";
     result: TurnResult;
+    turnId?: string;
 } | {
     kind: "session-transition";
     transition: "started" | "resumed" | "compacting" | "compacted" | "fresh-fallback";
@@ -100,6 +141,9 @@ export type BuilderEvent = {
 } | {
     kind: "error";
     message: string;
+}) & {
+    eventId?: string;
+    observedAt?: string;
 };
 export interface ContextUsage {
     used: number;
@@ -185,6 +229,8 @@ export interface BuilderAdapterOptions {
     skills?: string[];
     /** Provider-native context ceiling, as a percentage of that provider's model window. */
     autoCompactThresholdPercent?: number;
+    /** Raw-adapter observability; wrapper adapters must not persist re-emitted events. */
+    observer?: RunObserver;
 }
 export interface BuilderAdapter {
     readonly agent: "claude" | "codex";

package/dist/agentRun.d.ts

@@ -22,6 +22,8 @@ export interface RoleBuilderOptions {
     permissionConfig?: PermissionConfig;
     extraSkills?: string[];
     sandboxMode?: BuilderAdapterOptions["sandboxMode"];
+    /** Disable recovery-session persistence for isolated, non-recoverable roles such as Manager. */
+    persistSessionBindings?: boolean;
     resumeSessionId?: string;
     /** Location-scoped exact session. Raw IDs are resolved through durable project bindings or treated as legacy candidates. */
     resumeSessionRef?: ProviderSessionRefV1;

package/dist/agentRun.js

@@ -199,6 +199,8 @@ export async function createRoleBuilder(opts) {
     };
     const initial = await makeAdapter(runtime, opts.resumeSessionId, requestedResumeRef);
     const persistSessionRef = (ref) => {
+        if (opts.persistSessionBindings === false)
+            return;
         const bindingDb = new WorkflowDb(opts.projectDir);
         try {
             bindingDb.recordProviderSessionBinding(ref);
@@ -240,6 +242,8 @@ function phaseForRole(role) {
         return "qa";
     if (role === "uninstaller")
         return "uninstaller";
+    if (role === "manager")
+        return "manager";
     return "builder";
 }
 export function readRoleDefaultsForExecution(projectDir, role) {
@@ -253,6 +257,8 @@ export function readRoleDefaultsForExecution(projectDir, role) {
             : undefined;
         if (!saved)
             return undefined;
+        if (role === "manager")
+            return saved;
         if (isFullyInitializedTracker(projectDir))
             return saved;
         const { make: _pendingMake, ...active } = saved;
@@ -293,7 +299,7 @@ export async function runRoleInstruction(opts) {
     const { builder, effort, roleBundle, skills } = roleBuilder;
     const viewer = printEvents(builder.events());
     const config = loadConfig(join(opts.projectDir, "foreman.yaml"));
-    const foreman = new Foreman(builder, log, config.notifications.enabled, false, 3, opts.projectDir);
+    const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, false, 3, opts.projectDir);
     try {
         const turn = await foreman.runInstruction(opts.instruction);
         await builder.close();
@@ -333,7 +339,7 @@ export async function runRoleInstruction(opts) {
     }
 }
 function configurableRole(role) {
-    return ["builder", "qa", "planner", "ticket-maker", "uninstaller"].includes(role)
+    return ["builder", "qa", "planner", "ticket-maker", "uninstaller", "manager"].includes(role)
         ? role
         : "builder";
 }

package/dist/branch/resume.js

@@ -1,8 +1,18 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { WorkflowReader } from "../workflowReader.js";
 export function findResumableBranchSessions(foremanDir) {
     if (!existsSync(foremanDir))
         return [];
+    const reader = new WorkflowReader(dirname(foremanDir));
+    try {
+        const structured = reader.branchResumeSessions().filter(session => existsSync(session.worktreePath));
+        if (structured.length)
+            return structured.sort((a, b) => a.ticket.localeCompare(b.ticket, undefined, { numeric: true }));
+    }
+    finally {
+        reader.close();
+    }
     const byTicket = new Map();
     const logs = readdirSync(foremanDir)
         .filter((file) => file.endsWith(".jsonl"))

package/dist/branch/runner.d.ts

@@ -1,10 +1,12 @@
 import type { BuilderAdapter, EffortLevel } from "../adapters/types.js";
+import type { RunObserver } from "../observability.js";
 import type { ProviderSessionRefV1, SessionStrategy } from "rafi-spec";
-import { type QaNonconvergenceContext, type QaNonconvergenceDecision } from "../qaReview.js";
+import { type QaNonconvergenceContext, type QaNonconvergenceDecision, type QaReportRecoveryHandler, type QaSessionBoundaryRecovery, type QaSessionHandle } from "../qaReview.js";
 import type { Log } from "../log.js";
 import type { BranchPlan, BranchPlanNode, BranchRunSummary, CompletionMode, MergeMethod, ReviewProvider } from "./types.js";
 import { SessionUnavailableError } from "../adapters/sessionFailure.js";
 import { SessionUnavailableContinuityError } from "../continuity.js";
+import type { QaRecoveryPacket } from "../qaRecovery.js";
 export interface DeliveryUnitSession {
     unitId: string;
     branch: string;
@@ -25,7 +27,9 @@ export interface BranchRunnerOptions {
     effort?: EffortLevel;
     fast?: boolean;
     notificationsEnabled: boolean;
+    terminalBellEnabled?: boolean;
     qaEnabled: boolean;
+    qaMaxFixAttempts?: number;
     createPr: boolean;
     completionMode?: CompletionMode;
     reviewProvider?: ReviewProvider;
@@ -52,7 +56,7 @@ export interface BranchRunnerOptions {
     recordQaSession?: (session: string | ProviderSessionRefV1, ticketId: string, worktreePath: string) => void;
     /** Notify the host and stop the branch plan without discarding its worktree. */
     onSessionUnavailable?: (error: SessionUnavailableError | SessionUnavailableContinuityError) => void;
-    createQa?: (cwd: string, sessionId?: string) => Promise<BuilderAdapter>;
+    createQa?: (cwd: string, sessionId?: string) => Promise<BuilderAdapter | QaSessionHandle>;
     builderSessionStrategy?: SessionStrategy;
     qaSessionStrategy?: SessionStrategy;
     observeBuilder?: (builder: BuilderAdapter) => Promise<void>;
@@ -61,7 +65,12 @@ export interface BranchRunnerOptions {
     qaNonconvergence?: (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
     beforeBuilderTurn?: (adapter: BuilderAdapter, frozenAction: string, cwd: string) => Promise<BuilderAdapter>;
     builderSessionBoundary?: (adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string) => Promise<BuilderAdapter>;
-    qaSessionBoundary?: (adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string) => Promise<BuilderAdapter>;
+    qaSessionBoundary?: (adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string, recovery?: QaSessionBoundaryRecovery) => Promise<BuilderAdapter>;
+    observer?: RunObserver;
+    qaRuntimeContext?: unknown;
+    qaContinuityManaged?: boolean;
+    qaReportRecovery?: QaReportRecoveryHandler;
+    qaResumedRecovery?: QaRecoveryPacket;
 }
 export declare function runBranchPlan(opts: BranchRunnerOptions): Promise<BranchRunSummary[]>;
 export declare function buildBranchTicketInstruction(node: BranchPlanNode, trackerPaths?: {

package/dist/branch/runner.js

@@ -1,8 +1,8 @@
 import { buildDurableQaFixHandoff, compactWithRetry, runIsolatedQa } from "../qaReview.js";
-import { changeManifestAsync } from "../qaSnapshot.js";
+import { changeManifestAsync, deterministicChangeSummaryAsync } from "../qaSnapshot.js";
 import { Foreman, MARKER_SPEC, parseStepStatus } from "../foreman.js";
 import { fireNotification } from "../notify.js";
-import { cmdBlock, cmdComplete, cmdUpdate } from "../tickets/commands.js";
+import { cmdBlock, cmdComplete, cmdUnblock, 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";
@@ -27,6 +27,7 @@ function deliverySessionPath(projectDir, unitId) {
     return join(projectDir, ".foreman", "delivery-sessions", `${unitId}.json`);
 }
 export async function runBranchPlan(opts) {
+    let qaResumedRecovery = opts.qaResumedRecovery;
     const baseWorktreePolicy = opts.baseWorktreePolicy ?? "enforce";
     if (baseWorktreePolicy !== "skip") {
         try {
@@ -128,7 +129,7 @@ export async function runBranchPlan(opts) {
         const resumeSession = opts.resumeSessions?.get(node.ticket.id);
         const worktreePath = resumeSession?.worktreePath
             ?? (sharedUnit ? findWorktreeForBranch(opts.projectDir, node.branch) : undefined)
-            ?? createTicketWorktree(opts.projectDir, opts.runId, node.branch, node.baseBranch);
+            ?? await observeNode(opts, node, "git", "creating ticket worktree", () => createTicketWorktree(opts.projectDir, opts.runId, node.branch, node.baseBranch));
         node.worktreePath = worktreePath;
         let builder;
         let viewer;
@@ -143,10 +144,14 @@ export async function runBranchPlan(opts) {
                     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}`,
-            }));
+            journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:in-progress`, { ticket: node.ticket.id, status: "in_progress" }, () => {
+                if (resumeSession)
+                    cmdUnblock(opts.projectDir, node.ticket.id, { actor: "foreman", summary: `Reopened by explicit branch recovery for ${node.branch}` });
+                cmdUpdate(opts.projectDir, node.ticket.id, {
+                    status: "in_progress", actor: "foreman",
+                    summary: resumeSession ? `Resuming branch ${node.branch}` : `Starting branch ${node.branch}`,
+                });
+            });
             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.
@@ -173,8 +178,11 @@ export async function runBranchPlan(opts) {
             }
             builderWorkSessions += 1;
             viewer = opts.observeBuilder?.(builder);
-            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, undefined, undefined, async (adapter) => opts.observeBuilderNativeCompactions?.(adapter, worktreePath));
-            const { result, status } = await foreman.runInstruction(ticketInstruction);
+            const foreman = new Foreman(builder, opts.log, { desktop: opts.notificationsEnabled, terminalBell: opts.terminalBellEnabled ?? true }, opts.qaEnabled, 3, undefined, undefined, undefined, opts.qaSessionStrategy ?? "compact", undefined, opts.builderSessionStrategy ?? "compact", undefined, opts.beforeBuilderTurn ? (adapter, action) => opts.beforeBuilderTurn(adapter, action, worktreePath) : undefined, undefined, undefined, undefined, async (adapter) => opts.observeBuilderNativeCompactions?.(adapter, worktreePath));
+            const turn = () => foreman.runInstruction(ticketInstruction);
+            const { result, status } = opts.observer
+                ? await opts.observer.withContext({ role: "builder", stream: "builder", ticketId: node.ticket.id, deliveryUnitId: node.deliveryUnitId }, turn)
+                : await turn();
             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();
@@ -186,7 +194,7 @@ export async function runBranchPlan(opts) {
                 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", {
+                const resumeSession = {
                     ticket: node.ticket.id,
                     branch: node.branch,
                     base: node.baseBranch,
@@ -205,7 +213,17 @@ export async function runBranchPlan(opts) {
                     keepWorktrees: opts.keepWorktrees,
                     deliveryUnitId: node.deliveryUnitId,
                     deliveryUnitFinal: node.deliveryUnitFinal,
-                });
+                    logPath: "structured-recovery",
+                    ts: new Date().toISOString(),
+                };
+                opts.log.write("branch-session", resumeSession);
+                const resumeDb = new WorkflowDb(opts.projectDir);
+                try {
+                    resumeDb.recordBranchResumeSession(opts.runId, resumeSession);
+                }
+                finally {
+                    resumeDb.close();
+                }
                 if (node.deliveryUnitId) {
                     const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
                     mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
@@ -239,17 +257,25 @@ export async function runBranchPlan(opts) {
                     throw new Error("independent disposable QA factory is required when QA is enabled");
                 workflowCheckpoint(opts.projectDir, opts.runId, "qa-before", node.ticket.id, { worktree: worktreePath });
                 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,
+                    ticket: node.ticket, builderWorktree: worktreePath, builderSummary: result.text,
+                    qaStrategy: opts.qaSessionStrategy ?? "compact", state: qaStream, createQa: opts.createQa, maxCycles: opts.qaMaxFixAttempts ?? 3,
+                    recovery: { projectDir: opts.projectDir, runId: opts.runId },
+                    observer: opts.observer,
+                    qaRuntimeContext: opts.qaRuntimeContext,
+                    continuityManaged: opts.qaContinuityManaged,
+                    onReportRecovery: opts.qaReportRecovery,
+                    resumedRecovery: qaResumedRecovery,
                     sessionBoundary: opts.qaSessionBoundary,
                     observeNativeCompactions: opts.observeQaNativeCompactions,
+                    resolveBlocked: (adapter, reason) => foreman.resolveBlocker(adapter, reason, "qa"),
                     evidence: (entry) => opts.log.write("qa-evidence", { ticket: node.ticket.id, ...entry }),
-                    fix: async (issues) => {
+                    fix: async (request) => {
                         if (!builder)
                             return { ok: false, detail: "Builder session unavailable" };
                         builderWorkSessions += 1;
                         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 changeSummary = await deterministicChangeSummaryAsync(worktreePath);
+                        const fixInstruction = buildDurableQaFixHandoff(node.ticket, request, worktreePath, request.latestBuilderResult, digest, changeSummary);
                         const strategy = opts.builderSessionStrategy ?? "compact";
                         if (opts.builderSessionBoundary) {
                             builder = await opts.builderSessionBoundary(builder, fixInstruction, strategy, worktreePath);
@@ -267,8 +293,13 @@ export async function runBranchPlan(opts) {
                         }
                         if (opts.beforeBuilderTurn)
                             builder = await opts.beforeBuilderTurn(builder, fixInstruction, worktreePath);
-                        const fixed = await builder.sendTurn(fixInstruction);
-                        const fixedStatus = parseStepStatus(fixed.text);
+                        let fixed = await builder.sendTurn(fixInstruction);
+                        let fixedStatus = parseStepStatus(fixed.text);
+                        if (!fixed.isError && fixedStatus.kind === "blocked") {
+                            const resolved = await foreman.resolveBlocker(builder, fixedStatus.reason ?? "Builder QA fix reported an unspecified blocker");
+                            fixed = resolved.result;
+                            fixedStatus = resolved.status;
+                        }
                         const fixedSessionId = builder.sessionId();
                         const fixedSessionRef = builder.sessionRef?.();
                         if (fixedSessionId)
@@ -277,10 +308,11 @@ export async function runBranchPlan(opts) {
                             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) };
+                        return { ok: !fixed.isError && fixedStatus.kind === "done", detail: fixedStatus.error, response: fixed.text, summary: fixedStatus.summary ?? fixed.text };
                     },
                     onNonconvergence: opts.qaNonconvergence,
                 });
+                qaResumedRecovery = undefined;
                 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 });
@@ -316,7 +348,7 @@ export async function runBranchPlan(opts) {
                 const operation = `${opts.runId}:commit:${node.ticket.id}`;
                 planJournal(opts.projectDir, opts.runId, operation, "commit", { ticket: node.ticket.id, branch: node.branch, worktreePath });
                 try {
-                    commit = commitAll(worktreePath, `${node.ticket.id}: ${node.ticket.title}`);
+                    commit = await observeNode(opts, node, "git", "committing ticket changes", () => commitAll(worktreePath, `${node.ticket.id}: ${node.ticket.title}`));
                     confirmJournal(opts.projectDir, operation, commit, { sha: commit });
                     workflowCheckpoint(opts.projectDir, opts.runId, "commit-after", node.ticket.id, { sha: commit });
                 }
@@ -334,12 +366,12 @@ export async function runBranchPlan(opts) {
                 workflowCheckpoint(opts.projectDir, opts.runId, "push-before", node.ticket.id, { branch: node.branch, sha: commit });
                 const pushOperation = `${opts.runId}:push:${node.branch}`;
                 planJournal(opts.projectDir, opts.runId, pushOperation, "push", { branch: node.branch, sha: commit, remote: "origin" });
-                const push = await withActivityPhase(`pushing ${node.branch}`, async () => {
+                const push = await observeNode(opts, node, "git", `pushing ${node.branch}`, () => withActivityPhase(`pushing ${node.branch}`, async () => {
                     currentActivity()?.update(`pushing ${node.branch}`, `publishing ${node.ticket.id}`);
                     return reviewProvider === "gitlab"
                         ? pushBranchForMr(worktreePath, node.branch)
                         : pushBranchForPr(worktreePath, node.branch);
-                });
+                }));
                 if (push.ok) {
                     confirmJournal(opts.projectDir, pushOperation, node.branch, { sha: commit });
                     opts.log.write("branch-push", { ticket: node.ticket.id, branch: node.branch, status: "pushed" });
@@ -376,7 +408,7 @@ export async function runBranchPlan(opts) {
                 workflowCheckpoint(opts.projectDir, opts.runId, "review-creation-before", node.ticket.id, { provider: reviewProvider, head: node.branch, base: node.baseBranch });
                 const reviewOperation = `${opts.runId}:${reviewProvider === "gitlab" ? "mr" : "pr"}:${node.branch}:${node.baseBranch}`;
                 planJournal(opts.projectDir, opts.runId, reviewOperation, reviewProvider === "gitlab" ? "mr-create" : "pr-create", { head: node.branch, base: node.baseBranch, sha: commit });
-                const pr = await withActivityPhase(`creating ${reviewProvider === "gitlab" ? "merge request" : "pull request"}`, async () => {
+                const pr = await observeNode(opts, node, "external_check", `creating ${reviewProvider === "gitlab" ? "merge request" : "pull request"}`, () => withActivityPhase(`creating ${reviewProvider === "gitlab" ? "merge request" : "pull request"}`, async () => {
                     currentActivity()?.update(`creating ${reviewProvider === "gitlab" ? "merge request" : "pull request"}`, node.ticket.id);
                     return reviewProvider === "gitlab"
                         ? createOrReuseMr(opts.projectDir, {
@@ -396,7 +428,7 @@ export async function runBranchPlan(opts) {
                             qaEvidence: qaSummary,
                             commit,
                         });
-                });
+                }));
                 summary.pr = pr;
                 if (pr.status === "created" || pr.status === "existing") {
                     confirmJournal(opts.projectDir, reviewOperation, pr.url, { head: node.branch, base: node.baseBranch, url: pr.url });
@@ -415,10 +447,10 @@ export async function runBranchPlan(opts) {
                     continue;
                 }
                 if (completionMode === "auto-merge" && reviewProvider === "github") {
-                    const autoMerge = await withActivityPhase("enabling GitHub auto-merge", async () => {
+                    const autoMerge = await observeNode(opts, node, "external_check", "enabling GitHub auto-merge", () => withActivityPhase("enabling GitHub auto-merge", async () => {
                         currentActivity()?.update("enabling GitHub auto-merge", node.branch);
                         return enableGitHubAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
-                    });
+                    }));
                     summary.pr = autoMerge.status === "failed" ? autoMerge : { ...pr, status: "auto_merge_enabled", url: autoMerge.url ?? pr.url };
                     if (autoMerge.status === "failed") {
                         opts.log.write("pr-auto-merge-failed", failureLogFields(node, autoMerge));
@@ -429,10 +461,10 @@ export async function runBranchPlan(opts) {
                     opts.log.write("pr-auto-merge-enabled", { ticket: node.ticket.id, branch: node.branch, url: summary.pr.url });
                 }
                 else if (completionMode === "auto-merge" && reviewProvider === "gitlab") {
-                    const autoMerge = await withActivityPhase("enabling GitLab auto-merge", async () => {
+                    const autoMerge = await observeNode(opts, node, "external_check", "enabling GitLab auto-merge", () => withActivityPhase("enabling GitLab auto-merge", async () => {
                         currentActivity()?.update("enabling GitLab auto-merge", node.branch);
                         return enableGitLabAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
-                    });
+                    }));
                     summary.pr = autoMerge.status === "failed" ? autoMerge : { ...pr, status: "auto_merge_enabled", url: autoMerge.url ?? pr.url };
                     if (autoMerge.status === "failed") {
                         opts.log.write("mr-auto-merge-failed", failureLogFields(node, autoMerge));
@@ -450,7 +482,7 @@ export async function runBranchPlan(opts) {
             else if (commit && completionMode === "direct-merge" && completesSharedUnit) {
                 if (!opts.keepWorktrees)
                     removeTicketWorktree(opts.projectDir, worktreePath);
-                const mergeCommit = mergeBranchToLocalBase(opts.projectDir, node.branch, node.baseBranch, `${node.ticket.id}: ${node.ticket.title}`, opts.mergeMethod ?? "squash");
+                const mergeCommit = await observeNode(opts, node, "git", "merging ticket branch to local base", () => mergeBranchToLocalBase(opts.projectDir, node.branch, node.baseBranch, `${node.ticket.id}: ${node.ticket.title}`, opts.mergeMethod ?? "squash"));
                 summary.pr = { status: "merged", url: mergeCommit };
                 opts.log.write("branch-direct-merge", {
                     ticket: node.ticket.id,
@@ -482,10 +514,17 @@ export async function runBranchPlan(opts) {
                 status: "done",
                 detail: summary.detail,
             });
+            const resumeDb = new WorkflowDb(opts.projectDir);
+            try {
+                resumeDb.completeBranchResumeSession(opts.runId, node.ticket.id);
+            }
+            finally {
+                resumeDb.close();
+            }
             if (node.deliveryUnitId && node.deliveryUnitFinal)
                 rmSync(deliverySessionPath(opts.projectDir, node.deliveryUnitId), { force: true });
             if (!opts.keepWorktrees && completionMode !== "direct-merge" && completesSharedUnit)
-                removeTicketWorktree(opts.projectDir, worktreePath);
+                await observeNode(opts, node, "cleanup", "removing ticket worktree", () => removeTicketWorktree(opts.projectDir, worktreePath));
         }
         catch (err) {
             if (err instanceof SessionUnavailableError || err instanceof SessionUnavailableContinuityError) {
@@ -581,49 +620,69 @@ async function waitForAutoMergeDependenciesInternal(opts, node, provider) {
         ? null
         : opts.autoMergeTimeoutMinutes * 60_000;
     const deadline = opts.autoMergeWait && timeoutMs !== null ? Date.now() + timeoutMs : null;
-    while (true) {
-        const pending = [];
-        for (const dep of dependencyNodes) {
-            const status = provider === "gitlab"
-                ? checkGitLabMrMerged(opts.projectDir, dep.branch)
-                : checkGitHubPrMerged(opts.projectDir, dep.branch);
-            if (!status.ok) {
+    let waitSpanId;
+    let waitOutcome = "completed";
+    let waitLogged = false;
+    try {
+        while (true) {
+            const pending = [];
+            for (const dep of dependencyNodes) {
+                const status = provider === "gitlab"
+                    ? checkGitLabMrMerged(opts.projectDir, dep.branch)
+                    : checkGitHubPrMerged(opts.projectDir, dep.branch);
+                if (!status.ok) {
+                    waitOutcome = "failed";
+                    return {
+                        ok: false,
+                        code: status.code,
+                        message: `dependency ${dep.ticket.id} merge check failed: ${status.message}`,
+                        repairCommands: status.repairCommands,
+                        command: status.command,
+                        output: status.output,
+                    };
+                }
+                if (!status.merged)
+                    pending.push(`${dep.ticket.id}${status.state ? ` (${status.state})` : ""}`);
+            }
+            if (pending.length === 0)
+                return { ok: true };
+            const message = `auto-merge dependency ${pending.join(", ")} has not merged into the root base yet`;
+            currentActivity()?.update("waiting for dependency merge", pending.join(", "));
+            if (!opts.autoMergeWait) {
                 return {
                     ok: false,
-                    code: status.code,
-                    message: `dependency ${dep.ticket.id} merge check failed: ${status.message}`,
-                    repairCommands: status.repairCommands,
-                    command: status.command,
-                    output: status.output,
+                    code: "dependency_unavailable",
+                    message: `${message}; rerun after it merges or enable auto-merge wait in ticket setup`,
                 };
             }
-            if (!status.merged)
-                pending.push(`${dep.ticket.id}${status.state ? ` (${status.state})` : ""}`);
-        }
-        if (pending.length === 0)
-            return { ok: true };
-        const message = `auto-merge dependency ${pending.join(", ")} has not merged into the root base yet`;
-        currentActivity()?.update("waiting for dependency merge", pending.join(", "));
-        if (!opts.autoMergeWait) {
-            return {
-                ok: false,
-                code: "dependency_unavailable",
-                message: `${message}; rerun after it merges or enable auto-merge wait in ticket setup`,
-            };
-        }
-        if (deadline !== null && Date.now() >= deadline) {
-            return {
-                ok: false,
-                code: "dependency_unavailable",
-                message: `${message}; timed out waiting for dependency merge`,
-            };
+            if (!waitSpanId && opts.observer) {
+                waitSpanId = opts.observer.store.startSpan({ runId: opts.runId, executionId: opts.observer.executionId, role: "host", stream: "dependency", ticketId: node.ticket.id }, { kind: "dependency_wait", name: "waiting for dependency merge", attributes: { dependencies: pending } });
+                opts.observer.store.updateCurrentState({ runId: opts.runId, role: "host", stream: "dependency", executionId: opts.observer.executionId, ticketId: node.ticket.id, phase: "waiting for dependency merge", activeSpanId: waitSpanId, activeSpanKind: "dependency_wait", lastSemanticProgressAt: new Date().toISOString() });
+            }
+            if (!waitLogged) {
+                opts.log.write("branch-auto-merge-wait", {
+                    ticket: node.ticket.id,
+                    pending,
+                    timeoutMinutes: opts.autoMergeTimeoutMinutes ?? null,
+                });
+                waitLogged = true;
+            }
+            if (deadline !== null && Date.now() >= deadline) {
+                waitOutcome = "timed_out";
+                return {
+                    ok: false,
+                    code: "dependency_unavailable",
+                    message: `${message}; timed out waiting for dependency merge`,
+                };
+            }
+            await sleep(autoMergePollMs());
         }
-        opts.log.write("branch-auto-merge-wait", {
-            ticket: node.ticket.id,
-            pending,
-            timeoutMinutes: opts.autoMergeTimeoutMinutes ?? null,
-        });
-        await sleep(autoMergePollMs());
+    }
+    finally {
+        if (waitSpanId && opts.observer)
+            opts.observer.store.finishSpan(waitSpanId, { outcome: waitOutcome });
+        if (waitLogged)
+            opts.log.write("branch-auto-merge-wait", { ticket: node.ticket.id, outcome: waitOutcome, terminal: true });
     }
 }
 function autoMergePollMs() {
@@ -636,6 +695,11 @@ function autoMergePollMs() {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function observeNode(opts, node, kind, name, operation) {
+    if (!opts.observer)
+        return Promise.resolve().then(operation);
+    return opts.observer.withContext({ role: "host", stream: kind, ticketId: node.ticket.id, deliveryUnitId: node.deliveryUnitId }, () => opts.observer.span(kind, name, operation));
+}
 function canonical(path) {
     try {
         return realpathSync.native(path);

package/dist/buildRuns.d.ts

@@ -1,10 +1,11 @@
-import type { BuildRunRecordV2, ProviderSessionRefV1, ResolvedAgentSettings, SessionAvailabilityV1 } from "rafi-spec";
+import type { AutonomyProfile, BuildRunRecordV2, ProviderSessionRefV1, ResolvedAgentSettings, ResolvedAutonomyPolicy, SessionAvailabilityV1 } from "rafi-spec";
 import { type ResolveSessionAvailabilityOptions } from "./sessionAvailability.js";
-export declare const BUILD_RUN_VERSION = 2;
+export declare const BUILD_RUN_VERSION = 3;
 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 {
+    runId?: string;
     tickets: string[];
     deliveryUnit?: string;
     branchMode?: BuildRunRecordV2["branchMode"];
@@ -17,6 +18,9 @@ export interface CreateBuildRunInput {
     builder?: LegacyResolvedAgentSettings;
     qa?: LegacyResolvedAgentSettings;
     runDecisions?: BuildRunRecordV2["runDecisions"];
+    autonomyProfile?: AutonomyProfile;
+    frozenPolicy?: ResolvedAutonomyPolicy;
+    qaEnabled?: boolean;
     now?: Date;
 }
 export declare function createBuildRun(input: CreateBuildRunInput): BuildRunRecordV2;