ai-foreman 1.7.19 → 1.7.21

package/dist/statusReporter.js

@@ -189,6 +189,7 @@ export class RoleStatusAdapter {
     restoreNativeCompactions(compactions) { this.adapter.restoreNativeCompactions?.(compactions); }
     contextUsageAfterNativeCompaction(compaction) { return this.adapter.contextUsageAfterNativeCompaction?.(compaction) ?? Promise.resolve(undefined); }
     contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
+    graphRuntimeSettings() { return this.adapter.graphRuntimeSettings?.(); }
     sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
     switchSettings(settings) { return this.adapter.switchSettings?.(settings) ?? Promise.resolve({ ok: false, error: "settings switch unavailable" }); }
     events() { return this.adapter.events(); }

package/dist/supervisedStart.d.ts

@@ -7,6 +7,12 @@ export declare function superviseStart(projectDir: string, runId: string, policy
     steps?: string;
     stacks?: string;
     detach?: boolean;
+    launchToken?: string;
+    startArgs?: string[];
 }): Promise<boolean>;
 /** Deliberately narrow: established work requires the normal recovery flow. */
 export declare function canRestartPreparation(db: WorkflowDb, runId: string): boolean;
+/** Cleanup cannot hide the original failure or erase an uncertain launch. */
+export declare function finishStartAdmission(projectDir: string, runId: string): void;
+/** Re-exec inherits run selection, but transfers only the newly reserved capability. */
+export declare function normalizeNestedLaunchArguments(args: readonly string[], token: string): string[];

package/dist/supervisedStart.js

@@ -1,9 +1,10 @@
+import { maintainBuildAdmission, stopBuildAdmissionHeartbeat, launchDigest, localBuildAuthority } from "./buildAdmission.js";
+import { fileURLToPath } from "node:url";
 import { execFileSync, spawn } from "node:child_process";
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { DurableSupervisor } from "./supervisor.js";
 import { WorkflowDb } from "./workflowDb.js";
-import { processStartIdentity } from "./processIdentity.js";
 import { cancelOwnedRuntimeProbes } from "./runtimeReadiness.js";
 /** Worker IPC is created by the parent; an environment flag alone cannot bypass supervision. */
 export function supervisedRunId() {
@@ -11,6 +12,28 @@ export function supervisedRunId() {
 }
 /** Both ordinary and branch starts enter through this process boundary. */
 export async function superviseStart(projectDir, runId, policy, selection) {
+    const preparation = new WorkflowDb(projectDir);
+    const invocationDigest = launchDigest(selection?.startArgs ?? ["start", projectDir]);
+    try {
+        const environmentToken = process.env.RAFI_BUILD_LAUNCH_TOKEN;
+        if (environmentToken && selection?.launchToken && environmentToken !== selection.launchToken)
+            throw new Error("Conflicting build launch contexts");
+        const launchToken = environmentToken ?? selection?.launchToken;
+        if (launchToken) {
+            preparation.claimBuildLaunch(runId, launchToken, supervisedRunId() ? "worker" : "coordinator", invocationDigest);
+            delete process.env.RAFI_BUILD_LAUNCH_TOKEN;
+        }
+        else
+            preparation.acquireBuildAdmission(runId, policy.supervisorEnabled && process.argv.includes("start") ? "coordinator" : "worker");
+        const run = preparation.ensureRun(runId, "build");
+        policy = preparation.freezeAutonomyPolicy(runId, policy);
+        if (selection?.startArgs && !run.state.runId && !run.state.startArgs)
+            preparation.transition(runId, { checkpoint: run.checkpoint, state: { ...run.state, startArgs: selection.startArgs }, event: "build_preparation_saved" });
+    }
+    finally {
+        preparation.close();
+    }
+    maintainBuildAdmission(localBuildAuthority(projectDir));
     if (supervisedRunId()) {
         const heartbeat = setInterval(() => { if (process.connected)
             process.send?.({ kind: "rafi-worker-heartbeat", runId }); }, 5_000);
@@ -60,7 +83,7 @@ export async function superviseStart(projectDir, runId, policy, selection) {
     if (!policy.supervisorEnabled) {
         const db = new WorkflowDb(projectDir);
         try {
-            db.putSupervisorState(runId, { status: "disabled", generation: 0, workerGeneration: 0, checkpointRestarts: 0, runRestarts: 0 });
+            db.putSupervisorState(runId, { generation: 0, workerGeneration: 0, checkpointRestarts: 0, runRestarts: 0, ...db.supervisorState(runId), status: "disabled" });
         }
         finally {
             db.close();
@@ -74,19 +97,55 @@ export async function superviseStart(projectDir, runId, policy, selection) {
         args.push("--steps", selection.steps);
     if (!args.some(arg => arg === "--stacks" || arg.startsWith("--stacks=")) && selection?.stacks)
         args.push("--stacks", selection.stacks);
+    const gate = fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./buildLaunchGate.ts" : "./buildLaunchGate.js", import.meta.url));
+    const gatedArgs = (token) => [...process.execArgv, gate, process.argv[1], projectDir, token, ...normalizeNestedLaunchArguments(args.slice(process.execArgv.length + 1), token)];
     if (selection?.detach && !process.env.RAFI_DETACHED_SUPERVISOR_RUN) {
         const directory = join(projectDir, ".rafi", "logs");
         mkdirSync(directory, { recursive: true });
         const path = join(directory, `supervisor-${runId}.log`);
         const fd = openSync(path, "a", 0o600);
+        const launchDb = new WorkflowDb(projectDir);
+        const authority = localBuildAuthority(projectDir);
+        const launch = launchDb.reserveBuildLaunch(authority, "coordinator", invocationDigest, "registered-v2");
+        launchDb.dispatchBuildLaunch(authority, launch.token);
         try {
-            const parent = spawn(process.execPath, args, { cwd: process.cwd(), detached: true,
-                env: { ...process.env, RAFI_DETACHED_SUPERVISOR_RUN: runId }, stdio: ["ignore", fd, fd] });
-            await new Promise((resolve, reject) => { parent.once("spawn", resolve); parent.once("error", reject); });
-            parent.unref();
+            const parent = spawn(process.execPath, gatedArgs(launch.token), { cwd: process.cwd(), detached: true,
+                env: { ...process.env, RAFI_DETACHED_SUPERVISOR_RUN: runId, RAFI_BUILD_LAUNCH_TOKEN: launch.token }, stdio: ["ignore", fd, fd, "ipc"] });
+            try {
+                await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { parent.kill("SIGTERM"); reject(new Error("Detached supervisor startup timed out; use rafi resume to reconcile")); }, 15_000);
+                    parent.once("message", () => {
+                        try {
+                            launchDb.acknowledgeBuildLaunchChild(authority, launch.token, parent.pid);
+                            parent.send("rafi-launch-ack", error => { clearTimeout(timer); if (error)
+                                reject(error);
+                            else
+                                resolve(); });
+                        }
+                        catch (error) {
+                            clearTimeout(timer);
+                            parent.kill("SIGTERM");
+                            reject(error);
+                        }
+                    });
+                    parent.once("error", error => { clearTimeout(timer); if (!parent.pid)
+                        launchDb.failBuildLaunch(authority, launch.token); reject(error); });
+                    parent.once("exit", () => { clearTimeout(timer); launchDb.reconcileBuildLaunches(runId, authority); reject(new Error("Detached supervisor exited during startup; use rafi resume")); });
+                });
+            }
+            finally {
+                // Startup rejection can be followed by a late exit/error. Remove DB
+                // callbacks before the outer finally closes the connection in either case.
+                parent.removeAllListeners("exit");
+                parent.removeAllListeners("message");
+                parent.removeAllListeners("error");
+                parent.on("error", () => { });
+                parent.unref();
+            }
             console.log(`rafi: launched supervisor for ${runId}; output: ${path}`);
         }
         finally {
+            launchDb.close();
             closeSync(fd);
         }
         return true;
@@ -95,16 +154,39 @@ export async function superviseStart(projectDir, runId, policy, selection) {
     db.ensureRun(runId, "build");
     db.freezeAutonomyPolicy(runId, policy);
     let exitCode = 2;
-    const supervisor = new DurableSupervisor({ projectDir, runId, policy,
+    let stopRequestSource;
+    const supervisor = new DurableSupervisor({ projectDir, runId, policy, admission: localBuildAuthority(projectDir),
         checkpoint: () => db.getRun(runId)?.checkpoint ?? "preparing",
         spawnWorker: generation => {
-            const child = spawn(process.execPath, args, {
-                cwd: process.cwd(), env: { ...process.env, RAFI_BUILD_WORKER_RUN: runId, RAFI_BUILD_WORKER_GENERATION: String(generation) },
+            let authority = localBuildAuthority(projectDir);
+            if (db.buildAdmission()?.token !== authority.token) {
+                authority = db.reacquireBuildCoordinator(runId);
+            }
+            const launch = db.reserveBuildLaunch(authority, "worker", invocationDigest, "registered-v2");
+            db.dispatchBuildLaunch(authority, launch.token);
+            const child = spawn(process.execPath, gatedArgs(launch.token), {
+                cwd: process.cwd(), env: { ...process.env, RAFI_BUILD_WORKER_RUN: runId, RAFI_BUILD_WORKER_GENERATION: String(generation), RAFI_BUILD_LAUNCH_TOKEN: launch.token },
                 stdio: ["inherit", "inherit", "inherit", "ipc"], detached: process.platform !== "win32",
             });
+            const startup = setTimeout(() => child.kill("SIGTERM"), 15_000);
+            child.on("message", message => {
+                if (!message || typeof message !== "object" || !("kind" in message) || message.kind !== "rafi-launch-registered")
+                    return;
+                try {
+                    db.acknowledgeBuildLaunchChild(authority, launch.token, child.pid);
+                    child.send("rafi-launch-ack", () => { });
+                    clearTimeout(startup);
+                }
+                catch {
+                    child.kill("SIGTERM");
+                }
+            });
+            child.once("exit", () => clearTimeout(startup));
+            child.once("error", () => clearTimeout(startup));
             let lastHeartbeat = Date.now();
             let stopping = false;
             const readinessChildren = new Map();
+            const readinessTags = new Map();
             let killTimer;
             const stop = () => {
                 if (stopping)
@@ -120,8 +202,10 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                 }
                 catch { /* exited */ }
             };
-            const watchdog = setInterval(() => { if (Date.now() - lastHeartbeat > 120_000)
-                stop(); }, 5_000);
+            const watchdog = setInterval(() => { if (Date.now() - lastHeartbeat > 120_000) {
+                stopRequestSource = "heartbeat-timeout";
+                stop();
+            } }, 5_000);
             watchdog.unref();
             child.on("message", message => { if (message && typeof message === "object" && "kind" in message && message.kind === "rafi-worker-heartbeat")
                 lastHeartbeat = Date.now(); });
@@ -131,50 +215,78 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                 const value = message;
                 if (!Number.isSafeInteger(value.pid) || Number(value.pid) <= 1)
                     return;
-                if (value.active === false)
+                if (typeof value.tag === "string")
+                    readinessTags.set(Number(value.pid), value.tag);
+                if (value.active === false) {
                     readinessChildren.delete(Number(value.pid));
+                    readinessTags.delete(Number(value.pid));
+                }
                 else if (typeof value.processStart === "string")
                     readinessChildren.set(Number(value.pid), value.processStart);
             });
             const result = new Promise(resolve => {
-                child.once("error", error => { clearInterval(watchdog); resolve({ kind: "failed", detail: error.message }); });
+                child.once("error", error => {
+                    clearInterval(watchdog);
+                    if (child.pid) {
+                        stop();
+                        return;
+                    } // exit handler owns cleanup and settlement
+                    db.failBuildLaunch(authority, launch.token);
+                    resolve({ kind: "failed", detail: error.message });
+                });
                 child.once("exit", async (code, signal) => {
                     clearInterval(watchdog);
                     if (killTimer)
                         clearTimeout(killTimer);
                     exitCode = code ?? 2;
                     try {
+                        const exitState = db.getRun(runId);
+                        if (exitState)
+                            db.transitionSupervisor(runId, generation, { checkpoint: exitState.checkpoint, event: "worker_exit", payload: { code, signal, stopRequested: stopping, source: stopRequestSource ?? "unknown", at: new Date().toISOString(), generation } });
+                        // Durable records are authoritative even when the worker never sent IPC.
+                        const deadline = Date.now() + 5000;
+                        const owned = db.readinessProcesses(runId).filter(row => {
+                            const launchChild = db.buildLaunch(launch.token)?.claimant;
+                            return launchChild && row.owner === launchChild.token;
+                        });
+                        const readinessWasActive = owned.length > 0;
+                        const readinessCleanup = owned.length ? await db.reconcileReadiness(runId, undefined, deadline) : [];
+                        const readinessQuiescent = readinessCleanup.length === 0;
+                        if (!readinessQuiescent) {
+                            exitCode = 2;
+                            resolve({ kind: "waiting_for_human" });
+                            console.error(`rafi: readiness cleanup remains unresolved; use rafi resume (${readinessCleanup.join(", ")})`);
+                            return;
+                        }
+                        const launchOutcome = db.reconcileBuildLaunches(runId, authority);
+                        if (launchOutcome === "retired" && db.buildLaunch(launch.token)?.state === "failed") {
+                            resolve({ kind: "crashed", detail: "Worker exited before claiming its launch; authorization retired safely" });
+                            return;
+                        }
                         if (signal || stopping) {
                             try {
                                 process.kill(process.platform === "win32" ? child.pid : -child.pid, "SIGKILL");
                             }
                             catch { /* owned group exited */ }
-                            const readinessWasActive = readinessChildren.size > 0;
-                            let readinessQuiescent = readinessWasActive;
-                            const readinessCleanup = [];
-                            for (const [pid, identity] of readinessChildren) {
-                                const cleanup = await stopOwnedReadinessGroup(pid, identity);
-                                if (cleanup !== "quiescent") {
-                                    readinessQuiescent = false;
-                                    readinessCleanup.push(cleanup);
-                                }
-                            }
                             const workerQuiescent = await ownedGroupIsQuiescent(child.pid);
                             const preparationReconciled = canRestartPreparation(db, runId);
                             if (!stopping && readinessQuiescent && workerQuiescent && preparationReconciled) {
-                                db.transition(runId, { status: "paused", checkpoint: "preparation-reconciled", event: "worker_preparation_reconciled", payload: { generation, signal, noImplementationAuthority: true } });
+                                db.transitionSupervisor(runId, generation, { status: "paused", checkpoint: "preparation-reconciled", event: "worker_preparation_reconciled", payload: { generation, signal, noImplementationAuthority: true } });
                                 resolve({ kind: "crashed", detail: "Preparation worker exited before acquiring implementation authority; owned process group is quiescent" });
                                 return;
                             }
                             // Process death does not establish that remote side effects stopped.
                             // Never replay an unacknowledged provider action automatically.
                             const uncertain = [...db.unresolvedRoleDispatches(runId, "builder"), ...db.unresolvedRoleDispatches(runId, "qa")];
-                            db.transition(runId, { status: "paused", checkpoint: uncertain.length ? "uncertain-worker-dispatch" : "worker-interrupted", event: "worker_reconciliation_required", payload: { generation, signal, uncertainDispatches: uncertain.map(item => item.idempotencyKey), readinessWasActive, readinessQuiescent, workerQuiescent, preparationReconciled, readinessCleanup, readinessOwnershipVerified: [...readinessChildren.values()].every(value => value !== "unavailable") } });
+                            db.transitionSupervisor(runId, generation, { status: "paused", checkpoint: uncertain.length ? "uncertain-worker-dispatch" : "worker-interrupted", event: "worker_reconciliation_required", payload: { generation, signal, uncertainDispatches: uncertain.map(item => item.idempotencyKey), readinessWasActive, readinessQuiescent, workerQuiescent, preparationReconciled, readinessCleanup, readinessOwnershipVerified: [...readinessChildren.values()].every(value => value !== "unavailable") } });
                             resolve({ kind: "waiting_for_human" });
                         }
                         else {
                             const state = db.getRun(runId);
-                            if (code === 0 && state?.status !== "completed") {
+                            if (code === 0 && state?.status === "cancelled") {
+                                resolve({ kind: "completed" });
+                            }
+                            else if (code === 0 && state?.status !== "completed") {
                                 exitCode = 2;
                                 resolve({ kind: "waiting_for_human" });
                             }
@@ -191,15 +303,16 @@ export async function superviseStart(projectDir, runId, policy, selection) {
             return { pid: child.pid, result, stop };
         },
     });
-    const stop = () => supervisor.requestStop();
-    process.once("SIGINT", stop);
-    process.once("SIGTERM", stop);
+    const stopInt = () => { stopRequestSource = "parent-SIGINT"; supervisor.requestStop(); };
+    const stopTerm = () => { stopRequestSource = "parent-SIGTERM"; supervisor.requestStop(); };
+    process.once("SIGINT", stopInt);
+    process.once("SIGTERM", stopTerm);
     try {
         await supervisor.run();
     }
     finally {
-        process.off("SIGINT", stop);
-        process.off("SIGTERM", stop);
+        process.off("SIGINT", stopInt);
+        process.off("SIGTERM", stopTerm);
         db.close();
     }
     process.exitCode = exitCode;
@@ -208,13 +321,7 @@ export async function superviseStart(projectDir, runId, policy, selection) {
 /** Deliberately narrow: established work requires the normal recovery flow. */
 export function canRestartPreparation(db, runId) {
     const run = db.getRun(runId);
-    if (!run || !["durable-baseline", "preparing", "preparation-reconciled"].includes(run.checkpoint))
-        return false;
-    if (run.state.version !== undefined || db.pendingHumanDecisions(runId).length || db.operations(runId).length || db.handoffs(runId).length)
-        return false;
-    if (db.roleMutationLease(runId, "builder") || db.roleMutationLease(runId, "qa"))
-        return false;
-    return db.branchResumeSessions(false).length === 0;
+    return Boolean(run && ["durable-baseline", "preparing", "preparation-reconciled"].includes(run.checkpoint) && db.preparationEligibility(runId).eligible);
 }
 async function ownedGroupIsQuiescent(pid) {
     if (process.platform === "win32")
@@ -245,32 +352,41 @@ async function ownedGroupIsQuiescent(pid) {
     } while (Date.now() < until);
     return false;
 }
-async function stopOwnedReadinessGroup(pid, expectedStart) {
-    if (process.platform === "win32" || expectedStart === "unavailable")
-        return "unverified readiness ownership";
-    try {
-        process.kill(pid, 0);
-        const actual = processStartIdentity(pid);
-        if (actual !== expectedStart)
-            return `readiness process identity changed: ${expectedStart} -> ${actual}`;
-    }
-    catch (error) {
-        if (error.code !== "ESRCH")
-            return `readiness liveness unavailable: ${String(error)}`;
-    }
+/** Cleanup cannot hide the original failure or erase an uncertain launch. */
+export function finishStartAdmission(projectDir, runId) {
+    const authority = localBuildAuthority(projectDir);
+    if (!authority || authority.runId !== runId)
+        return;
+    stopBuildAdmissionHeartbeat(authority);
+    const db = new WorkflowDb(projectDir);
     try {
-        process.kill(-pid, "SIGKILL");
+        if (db.buildAdmission()?.token === authority.token) {
+            try {
+                db.releaseBuildAdmission(authority);
+            }
+            catch (error) {
+                console.error(`rafi: retaining build ownership for reconciliation: ${String(error)}`);
+            }
+        }
     }
-    catch (error) {
-        if (error.code !== "ESRCH")
-            return `readiness group cleanup unavailable: ${String(error)}`;
+    finally {
+        db.close();
     }
-    if (await ownedGroupIsQuiescent(pid))
-        return "quiescent";
-    let state = "unavailable";
-    try {
-        state = execFileSync("ps", ["-o", "pid=,ppid=,pgid=,stat=", "-p", String(pid)], { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+/** Re-exec inherits run selection, but transfers only the newly reserved capability. */
+export function normalizeNestedLaunchArguments(args, token) {
+    const result = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--launch-token") {
+            i++;
+            continue;
+        }
+        if (args[i].startsWith("--launch-token="))
+            continue;
+        result.push(args[i]);
     }
-    catch { /* keep unknown */ }
-    return `readiness group ${pid} remains active or unverified (${state})`;
+    // Ordinary supervised start gets its run from the acknowledged IPC gate.
+    if (result.some(arg => arg === "--preparation-run" || arg === "--recover-run" || arg.startsWith("--preparation-run=") || arg.startsWith("--recover-run=")))
+        result.push("--launch-token", token);
+    return result;
 }

package/dist/supervisor.d.ts

@@ -1,3 +1,4 @@
+import type { BuildAdmission } from "./buildAdmission.js";
 import type { ResolvedAutonomyPolicy, SupervisorState } from "rafi-spec";
 export type WorkerOutcome = {
     kind: "completed";
@@ -21,6 +22,7 @@ export interface DurableSupervisorOptions {
     projectDir: string;
     runId: string;
     policy: ResolvedAutonomyPolicy;
+    admission?: BuildAdmission;
     spawnWorker: (generation: number) => Promise<SupervisorWorkerHandle> | SupervisorWorkerHandle;
     checkpoint: () => string;
     sleep?: (milliseconds: number) => Promise<void>;

package/dist/supervisor.js

@@ -25,7 +25,12 @@ export class DurableSupervisor {
             db.close();
             return { kind: "stopped" };
         }
+        let ownedAdmission;
         try {
+            if (this.options.admission)
+                db.assertBuildAdmission(this.options.admission);
+            else
+                ownedAdmission = db.acquireBuildAdmission(this.options.runId, "coordinator");
             state = db.atomic(() => {
                 for (const other of db.runningSupervisors()) {
                     if (other.runId !== this.options.runId && other.state.pid && processLooksLive(other.state.pid, other.state.processStart))
@@ -43,7 +48,13 @@ export class DurableSupervisor {
             });
         }
         catch (error) {
-            db.close();
+            try {
+                if (ownedAdmission)
+                    db.releaseBuildAdmission(ownedAdmission);
+            }
+            finally {
+                db.close();
+            }
             throw error;
         }
         const saveState = () => db.atomic(() => {
@@ -88,6 +99,13 @@ export class DurableSupervisor {
                     saveState();
                     return outcome;
                 }
+                const eligibility = db.preparationEligibility(this.options.runId);
+                if (!eligibility.eligible) {
+                    state = { ...state, status: "waiting_for_human" };
+                    saveState();
+                    db.transitionSupervisor(this.options.runId, state.workerGeneration, { status: "paused", checkpoint: "worker-reconciliation-required", event: "worker_restart_withheld", payload: { reasons: eligibility.reasons } });
+                    return { kind: "waiting_for_human" };
+                }
                 const checkpointLimit = this.options.policy.limits.workerRestartsPerCheckpoint;
                 const runLimit = this.options.policy.limits.workerRestartsPerRun;
                 if (state.checkpointRestarts >= checkpointLimit || state.runRestarts >= runLimit) {
@@ -105,7 +123,13 @@ export class DurableSupervisor {
         }
         finally {
             clearInterval(heartbeat);
-            db.close();
+            try {
+                if (ownedAdmission && db.buildAdmission()?.token === ownedAdmission.token)
+                    db.releaseBuildAdmission(ownedAdmission);
+            }
+            finally {
+                db.close();
+            }
         }
     }
 }

package/dist/terminalStyle.d.ts

@@ -0,0 +1,21 @@
+/** Small, dependency-free terminal styling and display sanitization helpers. */
+export type TerminalColorRole = "accent" | "success" | "warning" | "error" | "info";
+export interface TerminalStyleStream {
+    readonly isTTY?: boolean;
+}
+export interface TerminalStyleContext {
+    readonly stream?: TerminalStyleStream;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    /** Declared data output is always plain, including FORCE_COLOR sessions. */
+    readonly machineReadable?: boolean;
+}
+export declare function terminalColorEnabled(context?: TerminalStyleContext): boolean;
+export declare function styleTerminalText(role: TerminalColorRole, text: string, context?: TerminalStyleContext): string;
+export declare function accent(text: string, context?: TerminalStyleContext): string;
+export declare function success(text: string, context?: TerminalStyleContext): string;
+export declare function warning(text: string, context?: TerminalStyleContext): string;
+export declare function error(text: string, context?: TerminalStyleContext): string;
+export declare function info(text: string, context?: TerminalStyleContext): string;
+/** Remove terminal control sequences while retaining intended line breaks. */
+export declare function sanitizeTerminalText(value: string): string;

package/dist/terminalStyle.js

@@ -0,0 +1,50 @@
+/** Small, dependency-free terminal styling and display sanitization helpers. */
+const ANSI = {
+    accent: "\x1b[36m",
+    success: "\x1b[32m",
+    warning: "\x1b[33m",
+    error: "\x1b[31m",
+    info: "\x1b[34m",
+};
+const RESET = "\x1b[39m";
+export function terminalColorEnabled(context = {}) {
+    if (context.machineReadable)
+        return false;
+    const env = context.env ?? process.env;
+    const stream = context.stream ?? process.stdout;
+    if (Object.hasOwn(env, "NO_COLOR"))
+        return false;
+    if (env.TERM?.toLowerCase() === "dumb")
+        return false;
+    if (env.FORCE_COLOR === "0")
+        return false;
+    if (["1", "2", "3"].includes(env.FORCE_COLOR ?? ""))
+        return true;
+    if (!stream.isTTY)
+        return false;
+    // Modern Windows terminals advertise ANSI support. A bare legacy console TTY
+    // is not enough evidence, so leave it readable and unstyled.
+    if ((context.platform ?? process.platform) === "win32") {
+        return Boolean(env.WT_SESSION || env.ANSICON || env.ConEmuANSI === "ON" || env.TERM);
+    }
+    return true;
+}
+export function styleTerminalText(role, text, context = {}) {
+    const safeText = sanitizeTerminalText(text);
+    return terminalColorEnabled(context) ? `${ANSI[role]}${safeText}${RESET}` : safeText;
+}
+export function accent(text, context) { return styleTerminalText("accent", text, context); }
+export function success(text, context) { return styleTerminalText("success", text, context); }
+export function warning(text, context) { return styleTerminalText("warning", text, context); }
+export function error(text, context) { return styleTerminalText("error", text, context); }
+export function info(text, context) { return styleTerminalText("info", text, context); }
+/** Remove terminal control sequences while retaining intended line breaks. */
+export function sanitizeTerminalText(value) {
+    return value
+        // CSI, OSC, DCS/SOS/PM/APC, and two-byte ESC controls.
+        .replace(/\x1b\](?:[^\x07\x1b]|\x1b(?!\\))*(?:\x07|\x1b\\)?/gs, "")
+        .replace(/\x1b(?:[PX^_](?:.|\n)*?\x1b\\|\[[0-?]*[ -/]*[@-~]|[@-_])/g, "")
+        .replace(/\x9d[^\x07]*(?:\x07)?/g, "")
+        .replace(/\x9b[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+}

package/dist/ticketPopulation.d.ts

@@ -2,6 +2,7 @@ import type { StructuredPlanV1 } from "rafi-spec";
 import type { TicketDef } from "./tickets/ticketSchema.js";
 import { type DeliveryConfig } from "./tickets/delivery.js";
 export interface TicketSliceProposal {
+    qa_preparation?: TicketDef["qa_preparation"];
     slice_ref: string;
     title: string;
     area: string;

package/dist/ticketPopulation.js

@@ -1,3 +1,4 @@
+import { canonicalContractJson } from "./qaVerificationContract.js";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -30,6 +31,9 @@ export function validateTicketPopulationProposal(proposal, plan, existing) {
     const planned = new Set(plan.slices.map((slice) => slice.slice_ref));
     const mapped = new Set();
     for (const ticket of proposal.tickets) {
+        const depth = plan.slices.find(slice => slice.slice_ref === ticket.slice_ref)?.qa_preparation;
+        if (ticket.qa_preparation && (!depth || canonicalContractJson(ticket.qa_preparation) !== canonicalContractJson(depth)))
+            issues.push(`ticket-maker cannot override planner QA depth for ${ticket.slice_ref}`);
         if (!planned.has(ticket.slice_ref))
             issues.push(`unknown slice mapping ${ticket.slice_ref}`);
         if (mapped.has(ticket.slice_ref))
@@ -64,7 +68,7 @@ export function materializeTicketPopulation(proposal, plan, existing) {
     const materialized = proposal.tickets.map((slice, index) => {
         const retained = byPlanSlice.get(`${plan.plan_id}:${slice.slice_ref}`);
         return {
-            ...(retained ?? {}), id: sliceToTicket.get(slice.slice_ref), order: retained?.order ?? nextOrder(existing, index),
+            ...(retained ?? {}), qa_preparation: structuredClone(plan.slices.find(item => item.slice_ref === slice.slice_ref)?.qa_preparation), id: sliceToTicket.get(slice.slice_ref), order: retained?.order ?? nextOrder(existing, index),
             title: slice.title, area: slice.area, priority: slice.priority, size: slice.size, risk: slice.risk,
             depends_on: slice.depends_on.map((ref) => sliceToTicket.get(ref)), summary: slice.summary,
             acceptance: [...slice.acceptance], required_tests: [...slice.required_tests], likely_files: [...slice.likely_files],

package/dist/tickets/commands.js

@@ -259,8 +259,8 @@ export function cmdBlock(projectDir, ticketId, opts) {
             ctx.db.upsertState(ticketId, {
                 status: "blocked",
                 blocked_by_json: JSON.stringify(merged),
-                blocker_type: opts.blockerType ?? "dependency",
-                blocker_notes: opts.unblockCriteria ?? null,
+                blocker_type: opts.blockerType ?? (merged.length ? "dependency" : "external"),
+                blocker_notes: opts.unblockCriteria ?? opts.summary ?? "Resolve the external prerequisite before continuing",
                 first_blocked_at: state?.first_blocked_at ?? now,
                 last_checked_at: now,
                 last_worked_at: now,

package/dist/tickets/queue.js

@@ -31,7 +31,7 @@ export function buildNextQueue(ticketDefs, states, queueLimit) {
             blockedBy: blockedBy.length ? blockedBy.join(", ") : "None",
             size: ticket.size,
             risk: ticket.risk,
-            nextAction: state?.next_action ?? defaultNextAction(ticket, displayStatus, blockedBy),
+            nextAction: state?.next_action ?? (displayStatus === "blocked" && !blockedBy.length ? `Resolve blocker: ${state?.blocker_notes ?? "external prerequisite requires recovery"}` : defaultNextAction(ticket, displayStatus, blockedBy)),
             requiredTests: ticket.required_tests.join("; "),
             evidence: state?.evidence ?? "N/A until implemented.",
             likelyFiles: ticket.likely_files.length ? ticket.likely_files.join(", ") : "unknown",