ai-foreman 1.4.0 → 1.6.0

package/dist/interviews.d.ts

@@ -0,0 +1,90 @@
+export declare const INTERVIEW_STATE_VERSION = 2;
+export declare const INTERVIEW_DIRECTORY = ".rafi/interviews";
+export type InterviewWorkflow = "create" | "plan" | "tickets-plan" | "tickets-setup-init" | "tickets-setup-update";
+export type InterviewStatus = "in_progress" | "paused" | "needs_review" | "completed" | "incompatible";
+export type InterviewStageStatus = "not_offered" | "offered" | "accepted" | "running" | "completed" | "skipped" | "paused" | "failed" | "cancelled";
+export interface InterviewRuntimeState {
+    runtime?: "claude" | "codex";
+    model?: string;
+    sessionId?: string;
+    /** True when a session id could not be resumed and a fresh session is needed. */
+    continuityLost?: boolean;
+}
+export interface InterviewOutputFingerprint {
+    path: string;
+    sha256: string | null;
+}
+export interface InterviewFailure {
+    checkpoint: string;
+    summary: string;
+    at: string;
+}
+export interface InterviewRecord {
+    version: number;
+    id: string;
+    journeyId: string;
+    parentId?: string;
+    childIds: string[];
+    workflow: InterviewWorkflow;
+    status: InterviewStatus;
+    /** Arguments/context required to re-enter the runner. No environment secrets. */
+    invocation: Record<string, unknown>;
+    answers: Record<string, unknown>;
+    /** V2 name for compact persisted answers; `answers` remains as a compatibility alias. */
+    decisions: Record<string, unknown>;
+    checkpoint: string;
+    stages: Record<string, {
+        status: InterviewStageStatus;
+        updatedAt: string;
+    }>;
+    planningMode?: "standard" | "exhaustive";
+    runtime: InterviewRuntimeState;
+    runtimeAttempts: Array<{
+        runtime: "claude" | "codex";
+        at: string;
+        outcome: "ready" | "failed" | "cancelled";
+        category?: string;
+    }>;
+    sessionIds: Record<string, string>;
+    continuityLost: boolean;
+    outputs: InterviewOutputFingerprint[];
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    failure?: InterviewFailure;
+}
+export interface InterviewRecordProblem {
+    path: string;
+    reason: string;
+}
+export interface InterviewReadResult {
+    records: InterviewRecord[];
+    problems: InterviewRecordProblem[];
+}
+export declare function interviewDirectory(projectDir: string): string;
+export declare function createInterviewRecord(input: {
+    workflow: InterviewWorkflow;
+    invocation: Record<string, unknown>;
+    answers?: Record<string, unknown>;
+    checkpoint: string;
+    outputs?: string[];
+    now?: Date;
+    parentId?: string;
+    journeyId?: string;
+    planningMode?: "standard" | "exhaustive";
+}): InterviewRecord;
+/** Ensure ignored local state exists without modifying unrelated gitignore text. */
+export declare function ensureInterviewGitignore(projectDir: string): void;
+export declare function saveInterviewRecord(projectDir: string, record: InterviewRecord, now?: Date): InterviewRecord;
+export declare function checkpointInterview(projectDir: string, record: InterviewRecord, update: Partial<Pick<InterviewRecord, "answers" | "decisions" | "checkpoint" | "runtime" | "outputs" | "invocation" | "status" | "stages" | "planningMode" | "runtimeAttempts" | "sessionIds" | "continuityLost" | "childIds">>): InterviewRecord;
+export declare function failInterview(projectDir: string, record: InterviewRecord, checkpoint: string, error: unknown): InterviewRecord;
+export declare function completeInterview(projectDir: string, record: InterviewRecord, now?: Date): InterviewRecord;
+export declare function readInterviewRecords(projectDir: string): InterviewReadResult;
+export declare function unfinishedInterviews(projectDir: string): InterviewRecord[];
+export declare function findInterviewRecord(projectDir: string, id: string): InterviewRecord | undefined;
+export declare function discardInterview(projectDir: string, id: string): boolean;
+/** Remove only completed records past retention; malformed/incompatible files stay for explicit discard. */
+export declare function pruneCompletedInterviews(projectDir: string, now?: Date): string[];
+export declare function fingerprintOutputs(projectDir: string, paths: string[]): InterviewOutputFingerprint[];
+export declare function outputsChanged(projectDir: string, fingerprints: InterviewOutputFingerprint[]): string[];
+export declare function redactFailure(error: unknown): string;

package/dist/interviews.js

@@ -0,0 +1,251 @@
+/**
+ * Durable, local state for commands that ask a human questions.  This lives in
+ * ai-foreman (rather than a CLI package) because `rafi tickets` is implemented
+ * there too.  Records deliberately contain decisions and small diagnostics,
+ * never a transcript or command output.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join, relative, resolve } from "node:path";
+export const INTERVIEW_STATE_VERSION = 2;
+export const INTERVIEW_DIRECTORY = ".rafi/interviews";
+const MAX_FAILURE_LENGTH = 1_000;
+const COMPLETE_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
+export function interviewDirectory(projectDir) {
+    return join(resolve(projectDir), INTERVIEW_DIRECTORY);
+}
+export function createInterviewRecord(input) {
+    const stamp = (input.now ?? new Date()).toISOString();
+    return {
+        version: INTERVIEW_STATE_VERSION,
+        id: randomUUID(),
+        journeyId: input.journeyId ?? randomUUID(),
+        parentId: input.parentId,
+        childIds: [],
+        workflow: input.workflow,
+        status: "in_progress",
+        invocation: { ...input.invocation },
+        answers: { ...(input.answers ?? {}) },
+        decisions: { ...(input.answers ?? {}) },
+        checkpoint: input.checkpoint,
+        stages: { [input.checkpoint]: { status: "running", updatedAt: stamp } },
+        planningMode: input.planningMode,
+        runtime: {},
+        runtimeAttempts: [],
+        sessionIds: {},
+        continuityLost: false,
+        outputs: fingerprintOutputs(String(input.invocation.projectDir ?? ""), input.outputs ?? []),
+        createdAt: stamp,
+        updatedAt: stamp,
+    };
+}
+/** Ensure ignored local state exists without modifying unrelated gitignore text. */
+export function ensureInterviewGitignore(projectDir) {
+    const root = resolve(projectDir);
+    const path = join(root, ".gitignore");
+    const line = ".rafi/interviews/";
+    const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (current.split(/\r?\n/).some((entry) => entry.trim() === line))
+        return;
+    const prefix = current && !current.endsWith("\n") ? "\n" : "";
+    writeFileSync(path, `${current}${prefix}${line}\n`, "utf8");
+}
+export function saveInterviewRecord(projectDir, record, now = new Date()) {
+    validateRecord(record);
+    const directory = interviewDirectory(projectDir);
+    mkdirSync(directory, { recursive: true });
+    ensureInterviewGitignore(projectDir);
+    const next = { ...record, updatedAt: now.toISOString() };
+    const path = interviewRecordPath(projectDir, next.id);
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    renameSync(temp, path);
+    return next;
+}
+export function checkpointInterview(projectDir, record, update) {
+    const nextAnswers = update.answers ?? update.decisions ?? record.answers;
+    const stamp = new Date().toISOString();
+    const stages = update.stages ?? (update.checkpoint && update.checkpoint !== record.checkpoint
+        ? {
+            ...record.stages,
+            [record.checkpoint]: { status: stageCompletionStatus(record.status), updatedAt: stamp },
+            [update.checkpoint]: { status: "running", updatedAt: stamp },
+        }
+        : record.stages);
+    const next = {
+        ...record,
+        ...update,
+        answers: { ...nextAnswers },
+        decisions: { ...nextAnswers },
+        stages,
+        runtime: update.runtime ? { ...update.runtime } : record.runtime,
+        sessionIds: update.runtime?.sessionId
+            ? { ...record.sessionIds, [update.runtime.runtime ?? "agent"]: update.runtime.sessionId }
+            : update.sessionIds ? { ...update.sessionIds } : record.sessionIds,
+        continuityLost: update.runtime?.continuityLost ?? update.continuityLost ?? record.continuityLost,
+        invocation: update.invocation ? { ...update.invocation } : record.invocation,
+        outputs: update.outputs ? update.outputs.map((output) => ({ ...output })) : record.outputs,
+    };
+    return saveInterviewRecord(projectDir, next);
+}
+export function failInterview(projectDir, record, checkpoint, error) {
+    const at = new Date().toISOString();
+    return saveInterviewRecord(projectDir, {
+        ...record,
+        status: record.status === "needs_review" ? "needs_review" : "in_progress",
+        checkpoint,
+        failure: { checkpoint, at, summary: redactFailure(error) },
+    });
+}
+export function completeInterview(projectDir, record, now = new Date()) {
+    const stamp = now.toISOString();
+    return saveInterviewRecord(projectDir, {
+        ...record,
+        status: "completed",
+        completedAt: stamp,
+        stages: { ...record.stages, [record.checkpoint]: { status: "completed", updatedAt: stamp } },
+        failure: undefined,
+    }, now);
+}
+export function readInterviewRecords(projectDir) {
+    const directory = interviewDirectory(projectDir);
+    if (!existsSync(directory))
+        return { records: [], problems: [] };
+    const records = [];
+    const problems = [];
+    for (const name of readFileNames(directory)) {
+        const path = join(directory, name);
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            const record = parseInterviewRecord(parsed);
+            records.push(record);
+        }
+        catch (error) {
+            problems.push({ path, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    records.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    return { records, problems };
+}
+export function unfinishedInterviews(projectDir) {
+    return readInterviewRecords(projectDir).records.filter((record) => record.status === "in_progress" || record.status === "paused" || record.status === "needs_review" || record.status === "incompatible");
+}
+export function findInterviewRecord(projectDir, id) {
+    return readInterviewRecords(projectDir).records.find((record) => record.id === id || record.id.startsWith(id));
+}
+export function discardInterview(projectDir, id) {
+    const record = findInterviewRecord(projectDir, id);
+    if (!record)
+        return false;
+    rmSync(interviewRecordPath(projectDir, record.id));
+    return true;
+}
+/** Remove only completed records past retention; malformed/incompatible files stay for explicit discard. */
+export function pruneCompletedInterviews(projectDir, now = new Date()) {
+    const removed = [];
+    for (const record of readInterviewRecords(projectDir).records) {
+        if (record.status !== "completed" || !record.completedAt)
+            continue;
+        if (now.getTime() - new Date(record.completedAt).getTime() <= COMPLETE_RETENTION_MS)
+            continue;
+        rmSync(interviewRecordPath(projectDir, record.id));
+        removed.push(record.id);
+    }
+    return removed;
+}
+export function fingerprintOutputs(projectDir, paths) {
+    if (!projectDir)
+        return paths.map((path) => ({ path, sha256: null }));
+    return paths.map((path) => ({ path, sha256: fingerprintFile(projectDir, path) }));
+}
+export function outputsChanged(projectDir, fingerprints) {
+    return fingerprints
+        .filter((fingerprint) => fingerprintFile(projectDir, fingerprint.path) !== fingerprint.sha256)
+        .map((fingerprint) => fingerprint.path);
+}
+export function redactFailure(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw
+        .replace(/((?:api[_-]?key|token|password|secret)\s*[=:])\s*[^\s,;]+/gi, "$1<redacted>")
+        .replace(/\b(?:sk|rk|ghp|github_pat)_[A-Za-z0-9_-]+\b/g, "<redacted>")
+        .replace(/\s+/g, " ")
+        .slice(0, MAX_FAILURE_LENGTH);
+}
+function interviewRecordPath(projectDir, id) {
+    return join(interviewDirectory(projectDir), `${id}.json`);
+}
+function readFileNames(directory) {
+    return readdirSync(directory).filter((name) => name.endsWith(".json"));
+}
+function fingerprintFile(projectDir, path) {
+    const root = resolve(projectDir);
+    const absolute = resolve(root, path);
+    if (relative(root, absolute).startsWith(".."))
+        return null;
+    if (!existsSync(absolute))
+        return null;
+    return createHash("sha256").update(readFileSync(absolute)).digest("hex");
+}
+function parseInterviewRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid interview record");
+    const record = value;
+    if (record.version === 1)
+        return migrateV1Record(value);
+    if (record.version !== INTERVIEW_STATE_VERSION) {
+        // Preserve it on disk. The caller can show it and require an explicit discard.
+        if (typeof record.id === "string" && typeof record.workflow === "string") {
+            return { ...record, status: "incompatible" };
+        }
+        throw new Error(`unsupported interview record version: ${String(record.version)}`);
+    }
+    validateRecord(record);
+    return record;
+}
+function migrateV1Record(value) {
+    const legacy = value;
+    if (!legacy.id || !legacy.workflow || !legacy.checkpoint || !legacy.createdAt || !legacy.updatedAt) {
+        throw new Error("invalid V1 interview record");
+    }
+    const outputs = Array.isArray(legacy.outputs) ? legacy.outputs : [];
+    const evidenceIsComplete = outputs.length > 0 && outputs.every((item) => item && typeof item.path === "string" && typeof item.sha256 === "string");
+    const answers = legacy.answers && typeof legacy.answers === "object" ? legacy.answers : {};
+    const runtime = legacy.runtime && typeof legacy.runtime === "object" ? legacy.runtime : {};
+    const stamp = legacy.updatedAt;
+    return {
+        version: 2,
+        id: legacy.id,
+        journeyId: legacy.id,
+        childIds: [],
+        workflow: legacy.workflow,
+        status: legacy.status === "completed" ? "completed" : evidenceIsComplete ? "paused" : "needs_review",
+        invocation: legacy.invocation && typeof legacy.invocation === "object" ? legacy.invocation : {},
+        answers,
+        decisions: { ...answers },
+        checkpoint: legacy.checkpoint,
+        stages: { [legacy.checkpoint]: { status: evidenceIsComplete ? "paused" : "failed", updatedAt: stamp } },
+        runtime,
+        runtimeAttempts: [],
+        sessionIds: runtime.sessionId ? { [runtime.runtime ?? "agent"]: runtime.sessionId } : {},
+        continuityLost: Boolean(runtime.continuityLost || !runtime.sessionId),
+        outputs,
+        createdAt: legacy.createdAt,
+        updatedAt: legacy.updatedAt,
+        completedAt: legacy.completedAt,
+        failure: legacy.failure,
+    };
+}
+function stageCompletionStatus(status) {
+    if (status === "paused" || status === "needs_review")
+        return "paused";
+    if (status === "completed")
+        return "completed";
+    return "completed";
+}
+function validateRecord(record) {
+    if (record.version !== INTERVIEW_STATE_VERSION)
+        throw new Error("unsupported interview record version");
+    if (!record.id || !record.journeyId || !record.workflow || !record.checkpoint || !record.createdAt || !record.updatedAt) {
+        throw new Error("invalid interview record");
+    }
+}

package/dist/log.d.ts

@@ -1,7 +1,7 @@
 /** A single structured log record. */
 export interface LogRecord {
     ts: string;
-    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "qa" | "qa-fix" | "error";
+    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "uninstall-proposal" | "qa" | "qa-fix" | "qa-protected-files-changed" | "error";
     [key: string]: unknown;
 }
 /** Append-only JSONL logger. One line per record, plus an echo to the console. */

package/dist/roles.d.ts

@@ -1,3 +1,14 @@
+import type { ConfigurableAgentRole } from "rafi-spec";
+export interface AgentRoleRegistration {
+    id: ConfigurableAgentRole;
+    label: string;
+    consumers: string[];
+    configurable: boolean;
+    manifest: string;
+    commands: string[];
+}
+/** One registry drives compilation, settings UI, and independently launched roles. */
+export declare const AGENT_ROLE_REGISTRY: readonly AgentRoleRegistration[];
 export interface RoleBundle {
     system: string;
     skills: string[];

package/dist/roles.js

@@ -11,6 +11,14 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgent } from "special-agents";
+/** One registry drives compilation, settings UI, and independently launched roles. */
+export const AGENT_ROLE_REGISTRY = [
+    { id: "planner", label: "Planner", consumers: ["initial planning", "ticket planning"], configurable: true, manifest: "planner", commands: ["rafi create", "rafi plan", "rafi tickets plan"] },
+    { id: "builder", label: "Builder", consumers: ["implementation"], configurable: true, manifest: "builder", commands: ["rafi start", "rafi build:resume"] },
+    { id: "qa", label: "QA (separate review session)", consumers: ["run-wide independent review"], configurable: true, manifest: "qa", commands: ["rafi start", "rafi build:resume"] },
+    { id: "ticket-maker", label: "Ticket maker", consumers: ["ticket population"], configurable: true, manifest: "ticket-maker", commands: ["rafi tickets populate"] },
+    { id: "uninstaller", label: "Uninstaller", consumers: ["non-empty uninstall instructions only"], configurable: true, manifest: "uninstaller", commands: ["rafi uninstall"] },
+];
 function libraryGetter(role) {
     const a = getAgent(role);
     return { system: a.system, skills: a.skills, model: a.model, effort: a.effort };

package/dist/runtimeAuth.d.ts

@@ -15,7 +15,7 @@ export declare class RuntimeAuthError extends Error {
     readonly authLikely: boolean;
     constructor(opts: RuntimeAuthErrorOptions);
 }
-export declare function checkRuntimeReady(projectDir: string, runtime: AgentRuntime): void;
+export declare function checkRuntimeReady(projectDir: string, runtime: AgentRuntime): Promise<void>;
 export declare function normalizeRuntimeErrorText(runtime: AgentRuntime, text: string, exitCode?: number | null, context?: string): string;
 export declare function isRuntimeAuthFailure(output: string): boolean;
 export declare function runtimeCommandLabel(runtime: AgentRuntime): string;

package/dist/runtimeAuth.js

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { formatRuntimeProbeFailure, probeRuntime } from "./runtimeReadiness.js";
 export class RuntimeAuthError extends Error {
     runtime;
     exitCode;
@@ -15,34 +15,15 @@ export class RuntimeAuthError extends Error {
         this.authLikely = isRuntimeAuthFailure(`${this.stderr}\n${this.stdout}`);
     }
 }
-export function checkRuntimeReady(projectDir, runtime) {
-    try {
-        if (runtime === "claude") {
-            execFileSync("claude", ["-p", "Return exactly OK"], {
-                cwd: projectDir,
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-        }
-        else {
-            execFileSync("codex", ["exec", "-C", projectDir, "Return exactly OK"], {
-                cwd: projectDir,
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-        }
-    }
-    catch (err) {
-        const failure = err;
+export async function checkRuntimeReady(projectDir, runtime) {
+    const result = await probeRuntime(projectDir, runtime);
+    if (!result.ok)
         throw new RuntimeAuthError({
             runtime,
             context: "readiness check",
-            exitCode: failure.status,
-            stdout: outputToString(failure.stdout),
-            stderr: outputToString(failure.stderr),
-            cause: err,
+            exitCode: result.exitCode,
+            stderr: formatRuntimeProbeFailure(result),
         });
-    }
 }
 export function normalizeRuntimeErrorText(runtime, text, exitCode, context = "builder turn") {
     if (!isRuntimeAuthFailure(text))

package/dist/runtimeReadiness.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeProbeCategory, RuntimeProbePhase, RuntimeProbeResult } from "rafi-spec";
+import type { AgentRuntime } from "./runtimeAuth.js";
+export declare const RUNTIME_PROBE_TIMEOUT_MS = 30000;
+export declare const RUNTIME_DIAGNOSTIC_LIMIT: number;
+export interface ProbeRuntimeOptions {
+    phase?: RuntimeProbePhase;
+    timeoutMs?: number;
+    maxDiagnosticsBytes?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function probeRuntime(cwd: string, runtime: AgentRuntime, opts?: ProbeRuntimeOptions): Promise<RuntimeProbeResult>;
+export declare function classifyRuntimeFailure(text: string, phase?: RuntimeProbePhase): RuntimeProbeCategory;
+export declare function sanitizeDiagnostics(text: string, maxBytes?: number): string;
+export declare function formatRuntimeProbeFailure(result: RuntimeProbeResult): string;

package/dist/runtimeReadiness.js

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+export const RUNTIME_PROBE_TIMEOUT_MS = 30_000;
+export const RUNTIME_DIAGNOSTIC_LIMIT = 8 * 1024;
+const RELEVANT_ENV = /^(ANTHROPIC|CLAUDE|CODEX|OPENAI|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|SSL_CERT_FILE|NODE_EXTRA_CA_CERTS)(_|$)/i;
+export async function probeRuntime(cwd, runtime, opts = {}) {
+    const executable = runtime === "claude" ? "claude" : "codex";
+    const args = runtime === "claude"
+        ? ["-p", "Return exactly OK"]
+        : ["exec", "--skip-git-repo-check", "-C", cwd, "Return exactly OK"];
+    const phase = opts.phase ?? "readiness";
+    const env = opts.env ?? process.env;
+    const limit = opts.maxDiagnosticsBytes ?? RUNTIME_DIAGNOSTIC_LIMIT;
+    const timeoutMs = opts.timeoutMs ?? RUNTIME_PROBE_TIMEOUT_MS;
+    return new Promise((resolveResult) => {
+        let output = Buffer.alloc(0);
+        let timedOut = false;
+        let settled = false;
+        const spawnOpts = { cwd, env, stdio: ["ignore", "pipe", "pipe"] };
+        const child = spawn(executable, args, spawnOpts);
+        const append = (chunk) => {
+            if (output.length >= limit)
+                return;
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            output = Buffer.concat([output, bytes.subarray(0, Math.max(0, limit - output.length))]);
+        };
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), 1_000).unref();
+        }, timeoutMs);
+        timer.unref();
+        const finish = (exitCode, signal, spawnError) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const diagnostics = sanitizeDiagnostics(spawnError?.message
+                ? `${spawnError.message}\n${output.toString("utf8")}`
+                : output.toString("utf8"), limit);
+            const category = timedOut
+                ? "timeout"
+                : spawnError?.code === "ENOENT"
+                    ? "missing-executable"
+                    : exitCode === 0
+                        ? "ready"
+                        : classifyRuntimeFailure(diagnostics, phase);
+            resolveResult({
+                ok: category === "ready",
+                runtime,
+                phase,
+                category,
+                executable,
+                cwd,
+                timedOut,
+                exitCode,
+                signal,
+                diagnostics,
+                environmentNames: Object.keys(env).filter((name) => RELEVANT_ENV.test(name)).sort(),
+                recoveryChoices: category === "ready" ? [] : ["retry", "switch", "cancel"],
+            });
+        };
+        child.once("error", (error) => finish(null, null, error));
+        child.once("close", (code, signal) => finish(code, signal));
+    });
+}
+export function classifyRuntimeFailure(text, phase = "readiness") {
+    const value = text.toLowerCase();
+    if (/not logged in|login required|unauthenticated|invalid authentication|expired.{0,20}token|token.{0,20}expired|\b401\b/.test(value))
+        return "authentication";
+    if (/forbidden|not authorized|unauthorized|entitlement|permission denied|\b403\b/.test(value))
+        return "authorization";
+    if (/rate.?limit|too many requests|\b429\b|quota exceeded/.test(value))
+        return "rate-limit";
+    if (/enotfound|econnreset|econnrefused|network|dns|socket hang up|timed? out|tls|certificate/.test(value))
+        return "network";
+    if (/cannot find module|module not found|sdk/.test(value))
+        return "sdk-load";
+    if (/malformed|invalid json|protocol|unexpected token/.test(value))
+        return "malformed-protocol";
+    if (/stream|agent turn|agent error/.test(value))
+        return "agent-stream";
+    if (/config|configuration|invalid model|unsupported model/.test(value))
+        return "configuration";
+    if (phase === "compiler-update")
+        return "compiler-update";
+    if (phase === "capability-discovery")
+        return "capability-discovery";
+    return "unknown";
+}
+export function sanitizeDiagnostics(text, maxBytes = RUNTIME_DIAGNOSTIC_LIMIT) {
+    const clean = text
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/((?:api[_-]?key|access[_-]?token|auth(?:orization)?|password|secret)\s*[=:]\s*)(?:bearer\s+)?[^\s,;]+/gi, "$1<redacted>")
+        .replace(/\b(?:sk|rk|ghp|github_pat)_[A-Za-z0-9_-]+\b/g, "<redacted>")
+        .replace(/Bearer\s+[A-Za-z0-9._~+\/-]+=*/gi, "Bearer <redacted>")
+        .replace(/\s+$/g, "")
+        .trim();
+    const bytes = Buffer.from(clean);
+    if (bytes.length <= maxBytes)
+        return clean;
+    return `${bytes.subarray(0, Math.max(0, maxBytes - 18)).toString("utf8")}\n... truncated ...`;
+}
+export function formatRuntimeProbeFailure(result) {
+    if (result.ok)
+        return `${result.executable} is ready.`;
+    const lines = [
+        `${result.executable} failed during ${result.phase} (${result.category}${result.timedOut ? ", timed out" : result.exitCode === null ? "" : `, exit ${result.exitCode}`}).`,
+    ];
+    if (result.category === "authentication") {
+        lines.push(result.runtime === "claude"
+            ? "Authenticate with `claude auth login --claudeai`, then retry."
+            : "Authenticate with `codex login`, then retry.");
+    }
+    else {
+        lines.push("Review the diagnostic below, then retry, switch to a verified provider, or cancel.");
+    }
+    if (result.diagnostics)
+        lines.push("", result.diagnostics);
+    return lines.join("\n");
+}

package/dist/ticketPlanning.d.ts

@@ -0,0 +1,83 @@
+import type { TicketDef } from "./tickets/ticketSchema.js";
+import { type TicketStatus } from "./tickets/stateDb.js";
+import { type DeliveryConfig } from "./tickets/delivery.js";
+import { type TicketBuildSetupConfig } from "./tickets/setupConfig.js";
+export declare const PROPOSAL_START = "RAFI_PROPOSAL_START";
+export declare const PROPOSAL_END = "RAFI_PROPOSAL_END";
+export interface TicketEdit {
+    id: string;
+    patch: Partial<Omit<TicketDef, "id">>;
+}
+export interface TicketSupersession {
+    replaced: string[];
+    replacements: string[];
+    reason: string;
+}
+export interface TicketStateChange {
+    id: string;
+    status: TicketStatus;
+    reason: string;
+}
+export interface SourceReconciliation {
+    source: string;
+    item: string;
+    disposition: "mapped" | "split" | "combined" | "deferred" | "excluded";
+    ticket_ids: string[];
+    reason?: string;
+}
+export interface FutureWorkDisposition {
+    id: number;
+    disposition: "accepted" | "rejected" | "merged" | "queued";
+}
+export interface TicketPlanProposal {
+    version: 1;
+    title: string;
+    markdown: string;
+    additions: TicketDef[];
+    edits: TicketEdit[];
+    supersessions: TicketSupersession[];
+    state_changes: TicketStateChange[];
+    source_reconciliation: SourceReconciliation[];
+    delivery?: DeliveryConfig | null;
+    build_defaults?: Partial<TicketBuildSetupConfig> | null;
+    future_work: FutureWorkDisposition[];
+    next: {
+        ticket_ids: string[];
+        replace_existing: boolean;
+    };
+}
+export interface PlanningFingerprint {
+    path: string;
+    sha256: string | null;
+}
+export interface TicketPlanningContext {
+    tickets: TicketDef[];
+    states: Array<{
+        ticket_id: string;
+        status: TicketStatus;
+    }>;
+    futureWork: Array<{
+        id?: number;
+        summary: string;
+        disposition: string;
+        rationale: string | null;
+    }>;
+    existingNext: string[];
+}
+export declare function readTicketPlanningContext(projectDir: string): TicketPlanningContext;
+export declare function ticketPlanningFingerprint(projectDir: string): PlanningFingerprint[];
+export declare function planningFingerprintChanges(projectDir: string, expected: PlanningFingerprint[]): string[];
+export declare function extractTicketPlanProposal(output: string, existingTickets?: TicketDef[]): TicketPlanProposal;
+export declare function validateTicketPlanProposal(value: unknown, existingTickets?: TicketDef[]): string[];
+export interface ApplyTicketPlanOptions {
+    expectedFingerprint: PlanningFingerprint[];
+    docsRoot: string;
+    now?: Date;
+}
+export interface AppliedTicketPlan {
+    added: string[];
+    edited: string[];
+    artifacts: string[];
+    backupDir: string;
+}
+export declare function applyApprovedTicketPlan(projectDir: string, proposal: TicketPlanProposal, opts: ApplyTicketPlanOptions): AppliedTicketPlan;