@tea-agent/loop-agent 0.42.0-next.9 → 0.42.1

package/dist/workflows/dag/rerun-task.js

@@ -1,6 +1,10 @@
 import { access, readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { generateTaskDagUseCase } from "../../application/dag/generate-task-dag.js";
+import { buildDefaultFrontendRecoveryDeps, } from "../../application/dag/run-dag.js";
+import { runDagContinuation, } from "./runner.js";
+import { stageRecoveryChild } from "./frontend-recovery-run.js";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { DAG_RUNS_DIR, isTerminalDagRunStatus, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
 import { deriveDagRerunFeedback } from "./rerun-feedback.js";
@@ -9,7 +13,7 @@ import { parseDagSpec, } from "./types.js";
 export const RERUN_TASK_LINEAGE_REL_PATH = ".runtime/rerun-task-lineage.json";
 export function parseDagRerunTaskArgs(args) {
     if (args.length === 0) {
-        throw new Error("usage: dag rerun-task --run-id <id> --reason <text> --request-id <key> [--profile auto|minimal|standard|reviewed|supervised] [--task-id <id>] [--json]");
+        throw new Error("usage: dag rerun-task --run-id <id> --reason <text> --request-id <key> [--profile auto|minimal|standard|reviewed|supervised] [--task-id <id>] [--frontend-recovery --recovery-operation-id <id>] [--json]");
     }
     let parentRunId;
     let reason;
@@ -18,6 +22,8 @@ export function parseDagRerunTaskArgs(args) {
     let profileExplicit = false;
     let taskIdOverride;
     let execute = true;
+    let frontendRecovery = false;
+    let recoveryOperationId;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === "--run-id")
@@ -48,6 +54,12 @@ export function parseDagRerunTaskArgs(args) {
             continue;
         else if (arg === "--no-execute")
             execute = false;
+        else if (arg === "--frontend-recovery")
+            frontendRecovery = true;
+        else if (arg === "--recovery-operation-id")
+            recoveryOperationId = args[++index];
+        else if (arg.startsWith("--recovery-operation-id="))
+            recoveryOperationId = arg.slice("--recovery-operation-id=".length);
         else if (arg.startsWith("-"))
             throw new Error(`unknown dag rerun-task flag: ${arg}`);
         else
@@ -70,6 +82,48 @@ export function parseDagRerunTaskArgs(args) {
         profileExplicit,
         ...(taskIdOverride?.trim() ? { taskIdOverride: taskIdOverride.trim() } : {}),
         execute,
+        frontendRecovery,
+        ...(recoveryOperationId ? { recoveryOperationId } : {}),
+    };
+}
+const frontendRecoveryDescriptorPath = (runDir, requestId) => path.join(runDir, ".runtime", "frontend-recovery", `${requestId}.json`);
+async function readFrontendRecoveryDescriptor(runDir, parentRunId, requestId) {
+    const raw = JSON.parse(await readFile(frontendRecoveryDescriptorPath(runDir, requestId), "utf8"));
+    const plan = raw.plan;
+    if (raw.schemaVersion !== 1 ||
+        raw.parentRunId !== parentRunId ||
+        raw.requestId !== requestId ||
+        typeof raw.failureSource !== "string" ||
+        typeof raw.recoveryMode !== "string" ||
+        typeof raw.planHash !== "string" ||
+        !plan ||
+        plan.schemaVersion !== 1 ||
+        plan.parentRunId !== parentRunId ||
+        plan.requestId !== requestId ||
+        !Array.isArray(plan.resetNodeIds) ||
+        !Array.isArray(plan.importedNodeIds)) {
+        throw new Error("frontend recovery descriptor is invalid or unbound");
+    }
+    const expectedHash = createHash("sha256")
+        .update(JSON.stringify(plan))
+        .digest("hex");
+    if (raw.planHash !== expectedHash) {
+        throw new Error("frontend recovery descriptor plan hash mismatch");
+    }
+    return raw;
+}
+function buildFrontendRecoveryIntent(input) {
+    return {
+        schemaVersion: 1,
+        phase: "child-staging",
+        requestId: input.requestId,
+        recoveryRootRunId: input.parentRecovery?.recoveryRootRunId ?? input.parentRunId,
+        parentRunId: input.parentRunId,
+        attemptId: input.requestId,
+        attemptIndex: input.parentRecovery?.attemptIndex ?? 0,
+        continuationCount: input.parentRecovery?.continuationCount ?? 0,
+        failureSource: input.failureSource,
+        revision: 0,
     };
 }
 function parseDagRerunTaskProfile(value) {
@@ -136,6 +190,21 @@ function resolveTaskIdForRerun(spec, taskIdOverride) {
 function operatorRequestPath(cwd, requestId) {
     return path.join(cwd, DAG_RUNS_DIR, ".operator-requests", `${requestId}.json`);
 }
+function computeRerunTaskRequestHash(input) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        parentRunId: input.parentRunId,
+        reason: input.reason,
+        requestId: input.requestId,
+        profile: input.profile ?? "auto",
+        profileExplicit: input.profileExplicit ?? false,
+        taskIdOverride: input.taskIdOverride ?? null,
+        execute: input.execute ?? true,
+        frontendRecovery: input.frontendRecovery ?? false,
+        recoveryOperationId: input.recoveryOperationId ?? null,
+    }))
+        .digest("hex");
+}
 async function fileExists(filePath) {
     try {
         await access(filePath);
@@ -185,23 +254,45 @@ export async function assessGeneratedOutputConflict(spec, cwd) {
     }
     return conflictPaths;
 }
-async function readExistingOperatorRequest(cwd, requestId) {
+async function readExistingOperatorRequest(cwd, requestId, expected) {
+    let raw;
     try {
-        const raw = JSON.parse(await readFile(operatorRequestPath(cwd, requestId), "utf-8"));
-        if (raw.result && typeof raw.result === "object") {
-            return { ...raw.result, idempotentReplay: true };
-        }
-    }
-    catch {
-        // not found or unreadable
+        raw = JSON.parse(await readFile(operatorRequestPath(cwd, requestId), "utf-8"));
     }
-    return undefined;
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return undefined;
+        }
+        throw new Error(`invalid persisted rerun-task operator request: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (raw.schemaVersion !== 1 ||
+        raw.kind !== "standalone-task-rerun-request" ||
+        raw.requestId !== requestId) {
+        throw new Error("REQUEST_ID_REUSE_CONFLICT: operator request id belongs to a different request kind");
+    }
+    if (raw.parentRunId !== expected.parentRunId ||
+        raw.requestHash !== expected.requestHash) {
+        throw new Error("REQUEST_ID_REUSE_CONFLICT: rerun-task operator request payload drifted");
+    }
+    const result = raw.result;
+    if (!result ||
+        typeof result !== "object" ||
+        Array.isArray(result) ||
+        result.parentRunId !== expected.parentRunId ||
+        result.requestId !== requestId) {
+        throw new Error("invalid persisted rerun-task operator request result");
+    }
+    return { ...result, idempotentReplay: true };
 }
-async function persistOperatorRequest(cwd, result) {
+async function persistOperatorRequest(cwd, result, requestHash) {
     await writeJsonAtomic(operatorRequestPath(cwd, result.requestId), {
         schemaVersion: 1,
         kind: "standalone-task-rerun-request",
         parentRunId: result.parentRunId,
+        requestHash,
         newRunId: result.newRunId,
         taskId: result.taskId,
         reason: result.reason,
@@ -264,8 +355,106 @@ function extractNewRunId(generateResult) {
     const runSummary = extractRunSummary(generateResult);
     return runSummary?.runId;
 }
+async function executeFrontendRecoveryContinuation(input) {
+    const located = await locateDagRun(input.cwd, input.parentRunId);
+    if (!located || located.lifecycle !== "active") {
+        throw new Error(`frontend recovery parent run must remain active: ${input.parentRunId}`);
+    }
+    const lease = await acquireDagRecoveryLease({
+        cwd: input.cwd,
+        parentRunId: input.parentRunId,
+        requestId: input.requestId,
+        kind: "standalone-task-rerun",
+    });
+    if (lease.kind !== "held" ||
+        lease.lease.kind !== "auto-frontend-recovery" ||
+        lease.lease.requestId !== input.requestId ||
+        !input.recoveryOperationId ||
+        lease.lease.executionRef !== input.recoveryOperationId) {
+        return blockedResult({
+            parentRunId: input.parentRunId,
+            reason: input.reason,
+            requestId: input.requestId,
+            blockedReason: "recovery-lease-held",
+            note: "frontend recovery operation is not the owner of the parent recovery lease",
+        });
+    }
+    const descriptor = await readFrontendRecoveryDescriptor(located.runDir, input.parentRunId, input.requestId);
+    const parentState = await readDagRunState(located.runDir);
+    const staged = await stageRecoveryChild({
+        cwd: input.cwd,
+        parentRunId: input.parentRunId,
+        recoveryIntent: buildFrontendRecoveryIntent({
+            parentRunId: input.parentRunId,
+            requestId: input.requestId,
+            failureSource: descriptor.failureSource,
+            parentRecovery: parentState.frontendRecoveryState,
+        }),
+        recoveryPlan: descriptor.plan,
+    });
+    const locatedChild = await locateDagRun(input.cwd, staged.childRunId);
+    if (!locatedChild || locatedChild.runDir !== staged.childRunDir) {
+        throw new Error(`frontend recovery child lifecycle drift: ${staged.childRunId}`);
+    }
+    const childSpec = await readDagRunSpec(locatedChild.runDir);
+    const childState = await readDagRunState(locatedChild.runDir);
+    let runSummary;
+    if (locatedChild.lifecycle === "completed" ||
+        locatedChild.lifecycle === "paused") {
+        runSummary = {
+            title: childState.title,
+            runId: childState.runId,
+            status: childState.status,
+            ranks: childState.ranks,
+            nodes: childState.nodes,
+            runDir: locatedChild.runDir,
+        };
+    }
+    else {
+        const childRecovery = childSpec.tasks.some((task) => task.id === "frontend-implement-pi")
+            ? input.recovery ?? await buildDefaultFrontendRecoveryDeps(input.cwd)
+            : undefined;
+        runSummary = await runDagContinuation({
+            cwd: input.cwd,
+            spec: childSpec,
+            state: childState,
+            runDir: locatedChild.runDir,
+            ...(childRecovery ? { recovery: childRecovery } : {}),
+        });
+    }
+    const settledChild = await locateDagRun(input.cwd, staged.childRunId);
+    const settledChildState = settledChild
+        ? await readDagRunState(settledChild.runDir)
+        : childState;
+    const feedback = summarizeFeedback(childSpec.rerunFeedback, "no-unresolved-verify-review-feedback");
+    const result = {
+        ok: runSummary.status === "finished" ||
+            settledChildState.frontendRecoveryResult?.outcome === "recovered",
+        parentRunId: input.parentRunId,
+        newRunId: staged.childRunId,
+        taskId: childSpec.taskContractBinding?.taskId ??
+            childSpec.sourceBinding?.taskId,
+        reason: input.reason,
+        requestId: input.requestId,
+        mode: "generate+validate+execute",
+        feedback,
+        runSummary,
+    };
+    await writeRerunTaskLineage(input.cwd, staged.childRunId, {
+        parentRunId: input.parentRunId,
+        reason: input.reason,
+        requestId: input.requestId,
+        feedback,
+    });
+    await persistOperatorRequest(input.cwd, result, input.requestHash);
+    return result;
+}
 export async function rerunStandaloneTask(input) {
-    const existing = await readExistingOperatorRequest(input.cwd, input.requestId);
+    const requestHash = computeRerunTaskRequestHash(input);
+    const existing = await readExistingOperatorRequest(input.cwd, input.requestId, {
+        parentRunId: input.parentRunId,
+        requestHash,
+    });
     if (existing) {
         return existing;
     }
@@ -298,6 +487,17 @@ export async function rerunStandaloneTask(input) {
             note: eligibility.note,
         });
     }
+    if (input.frontendRecovery) {
+        return executeFrontendRecoveryContinuation({
+            cwd: input.cwd,
+            parentRunId: input.parentRunId,
+            reason: input.reason,
+            requestId: input.requestId,
+            requestHash,
+            recoveryOperationId: input.recoveryOperationId,
+            recovery: input.recovery,
+        });
+    }
     let parentFeedback;
     let missingFeedbackReason = "no-unresolved-verify-review-feedback";
     try {
@@ -318,6 +518,9 @@ export async function rerunStandaloneTask(input) {
         // eligible full rerun.
         missingFeedbackReason = "feedback-unavailable";
     }
+    if (state.terminalReason === "design-request-changes" && !parentFeedback) {
+        throw new Error("frontend design recovery feedback unavailable: no typed findings were found");
+    }
     const execute = input.execute ?? true;
     let effectiveFeedback;
     let expectedRerunFeedbackDigest;
@@ -381,10 +584,7 @@ export async function rerunStandaloneTask(input) {
             kind: "standalone-task-rerun",
         })
         : undefined;
-    const nestedAutoRecoveryLease = recoveryLease?.kind === "held" &&
-        recoveryLease.lease.kind === "auto-frontend-recovery" &&
-        recoveryLease.lease.requestId === input.requestId;
-    if (recoveryLease?.kind === "held" && !nestedAutoRecoveryLease) {
+    if (recoveryLease?.kind === "held") {
         return blockedResult({
             parentRunId: input.parentRunId,
             reason: input.reason,
@@ -455,10 +655,13 @@ export async function rerunStandaloneTask(input) {
         ...(runSummary ? { runSummary } : {}),
     };
     if (await fileExists(operatorRequestPath(input.cwd, input.requestId))) {
-        const replay = await readExistingOperatorRequest(input.cwd, input.requestId);
+        const replay = await readExistingOperatorRequest(input.cwd, input.requestId, {
+            parentRunId: input.parentRunId,
+            requestHash,
+        });
         if (replay)
             return replay;
     }
-    await persistOperatorRequest(input.cwd, result);
+    await persistOperatorRequest(input.cwd, result, requestHash);
     return result;
 }

package/dist/workflows/dag/retry-policy.js

@@ -7,8 +7,8 @@ import { TYPED_EVENT_FACT_KINDS } from "./frontend-typed-event-store.js";
  * is re-exported here unchanged so retry-policy stays the single import
  * surface for retry policies and helpers.
  */
-export { ALL_DAG_RETRY_CATEGORIES, CONTEXT_OVERFLOW_RETRY_CATEGORY, DEFAULT_DAG_RETRY_CATEGORIES, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, PROTOCOL_AWARE_DAG_RETRY_CATEGORIES, PROTOCOL_INVALID_RETRY_CATEGORY, READ_BURST_RETRY_CATEGORY, REVIEW_TERMINAL_MISSING_RETRY_CATEGORY, STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY, STRUCTURED_OUTPUT_RETRY_CATEGORY, STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY, STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES, TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, dagRetryBackoffSchema, dagRetryCategorySchema, dagRetryPolicySchema, } from "./dag-retry-schema.js";
-import { CONTEXT_OVERFLOW_RETRY_CATEGORY, DEFAULT_DAG_RETRY_CATEGORIES, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, PROTOCOL_AWARE_DAG_RETRY_CATEGORIES, READ_BURST_RETRY_CATEGORY, REVIEW_TERMINAL_MISSING_RETRY_CATEGORY, STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY, STRUCTURED_OUTPUT_RETRY_CATEGORY, STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES, TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "./dag-retry-schema.js";
+export { ALL_DAG_RETRY_CATEGORIES, CONTEXT_OVERFLOW_RETRY_CATEGORY, DEFAULT_DAG_RETRY_CATEGORIES, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, OUTPUT_LIMIT_RETRY_CATEGORY, PROTOCOL_AWARE_DAG_RETRY_CATEGORIES, PROTOCOL_INVALID_RETRY_CATEGORY, READ_BURST_RETRY_CATEGORY, REVIEW_TERMINAL_MISSING_RETRY_CATEGORY, STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY, STRUCTURED_OUTPUT_RETRY_CATEGORY, STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY, STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES, TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, dagRetryBackoffSchema, dagRetryCategorySchema, dagRetryPolicySchema, } from "./dag-retry-schema.js";
+import { CONTEXT_OVERFLOW_RETRY_CATEGORY, DEFAULT_DAG_RETRY_CATEGORIES, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, OUTPUT_LIMIT_RETRY_CATEGORY, PROTOCOL_AWARE_DAG_RETRY_CATEGORIES, READ_BURST_RETRY_CATEGORY, REVIEW_TERMINAL_MISSING_RETRY_CATEGORY, STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY, STRUCTURED_OUTPUT_RETRY_CATEGORY, STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES, TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "./dag-retry-schema.js";
 const RETRY_SAFE_PI_ROLES = new Set([
     "planner",
     "scout",
@@ -19,7 +19,7 @@ const RETRY_SAFE_PI_ROLES = new Set([
 ]);
 /**
  * The default retry policy applied to safe generated read-only Pi nodes.
- * Total attempts: 3, exponential backoff with cap.
+ * Total attempts: 5, exponential backoff with cap.
  *
  * Includes `context-overflow`: a read-only node that blew the context window
  * (400 request too large, e.g. a review node accumulating too many reads) is a
@@ -29,7 +29,7 @@ const RETRY_SAFE_PI_ROLES = new Set([
  * design-review/review fell straight to ERROR without a retry attempt.
  */
 export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
-    maxAttempts: 3,
+    maxAttempts: 5,
     backoff: "exponential",
     initialDelayMs: 2000,
     maxDelayMs: 30000,
@@ -80,6 +80,17 @@ export const PLANNER_OUTPUT_LIMIT_RETRY_POLICY = {
         CONTEXT_OVERFLOW_RETRY_CATEGORY,
     ],
 };
+/** Backend-test N2 emits a mandatory run-owned Markdown protocol, so both
+ * provider length truncation and deterministic protocol validation failures
+ * are safe producer-local retries. */
+export const BACKEND_TEST_MD_PLAN_RETRY_POLICY = {
+    ...STRUCTURED_REQUIRED_PI_RETRY_POLICY,
+    retryCategories: [
+        ...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
+};
 /**
  * Default retry for reviewer / recovery nodes that declare outputProtocol.
  * Includes protocol-invalid so missing VERDICT lines are corrected in-node.
@@ -114,7 +125,10 @@ export const WRITER_EMPTY_DIFF_RETRY_POLICY = {
     backoff: "exponential",
     initialDelayMs: 2000,
     maxDelayMs: 30000,
-    retryCategories: [WRITER_EMPTY_DIFF_RETRY_CATEGORY],
+    retryCategories: [
+        WRITER_EMPTY_DIFF_RETRY_CATEGORY,
+        OUTPUT_LIMIT_RETRY_CATEGORY,
+    ],
 };
 /**
  * Bounded transport retry for standard exclusive implementers when a provider
@@ -129,6 +143,7 @@ export const WRITER_TRANSPORT_RETRY_POLICY = {
     retryCategories: [
         WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
         CONTEXT_OVERFLOW_RETRY_CATEGORY,
+        OUTPUT_LIMIT_RETRY_CATEGORY,
     ],
 };
 /**
@@ -164,6 +179,7 @@ export const TARGET_TEMPLATE_WRITER_TRANSPORT_RETRY_POLICY = {
     retryCategories: [
         WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
         CONTEXT_OVERFLOW_RETRY_CATEGORY,
+        OUTPUT_LIMIT_RETRY_CATEGORY,
     ],
 };
 /**
@@ -171,13 +187,14 @@ export const TARGET_TEMPLATE_WRITER_TRANSPORT_RETRY_POLICY = {
  * recovery attempts driven by Completeness Gate (missing/broken target files).
  */
 export const BACKEND_TEST_WRITER_COMPLETENESS_RETRY_POLICY = {
-    maxAttempts: 3,
+    maxAttempts: 5,
     backoff: "exponential",
     initialDelayMs: 2000,
     maxDelayMs: 30000,
     retryCategories: [
         WRITER_EMPTY_DIFF_RETRY_CATEGORY,
         INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
+        OUTPUT_LIMIT_RETRY_CATEGORY,
     ],
 };
 /** Markdown shard writers use one full attempt plus at most one bounded binding repair. */
@@ -461,9 +478,9 @@ function reasonMandatedFrontendPlanRetryStep(reason) {
     }
 }
 /**
- * Opt-in retry policy mounted on the frontend-plan-pi node. maxAttempts=3
- * bounds plan retry cost: the four-rung ladder is only partially traversable
- * before the run fails non-converging (rungs: normal → bounded-tool-only →
+ * Opt-in retry policy mounted on the frontend-plan-pi node. maxAttempts=5
+ * lets the producer validate and repair each generated increment while still
+ * bounding the four-rung ladder (normal → bounded-tool-only →
  * compact-terminal-first → backup-model). `invalid-output` (typed-fact schema
  * violations, e.g. verification targets referencing undeclared UI states)
  * retries at the `normal` rung with the contractCheck reason injected via
@@ -474,7 +491,7 @@ export const FRONTEND_PLAN_LADDER_RETRY_POLICY = {
     // incremental record_* calls; dense call bursts hit provider rate limits
     // whose windows exceed the old 30s cap. Longer backoff gives the limit
     // window time to expire before the next attempt.
-    maxAttempts: 3,
+    maxAttempts: 5,
     backoff: "exponential",
     initialDelayMs: 5000,
     maxDelayMs: 60000,

package/dist/workflows/dag/runner-exit-diagnostics.js

@@ -0,0 +1,125 @@
+import { appendFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { hostname } from "node:os";
+import path from "node:path";
+/**
+ * Runner exit-time diagnostics (silent-death forensics).
+ *
+ * A DAG runner can disappear without a crash report and without stderr (five
+ * reproductions during frontend recovery/long-plan runs, 2026-09-06): when a
+ * supervisor hard-kills the process or the event loop is wedged, no JS runs,
+ * so nothing is persisted and the run is only discoverable later as an
+ * orphaned RUNNING state with a frozen heartbeat. That leaves no evidence of
+ * WHERE the runner was when it died or whether the exit was even observable
+ * by Node.
+ *
+ * This module gives every abnormal death a durable trace next to state.json:
+ *   - an `armed` line is written when the checkpoint starts executing;
+ *   - a `process-exit` line is appended from the process `exit` hook with the
+ *     exit code and a live state snapshot (status, terminalReason, RUNNING
+ *     nodes, heartbeat staleness);
+ *   - `uncaught-exception` / `unhandled-rejection` lines record the error
+ *     before the process is allowed to crash exactly as it would have
+ *     via uncaughtExceptionMonitor without changing the host's crash policy.
+ *
+ * On a clean terminal return the runner calls stop(), which removes every
+ * listener and deletes the journal, so completed runs carry no noise. A file
+ * left behind therefore means: diagnostics were armed, then the process went
+ * away through a path Node could not observe (`armed` line only → external
+ * SIGKILL/OOM/event-loop wedge) or through an observed abnormal exit (`armed`
+ * + one or more event lines → the reason is recorded in the file).
+ *
+ * Journal writes are strictly synchronous and best-effort: an append failure
+ * must never alter the runner's own crash/exit behavior.
+ */
+export const RUNNER_EXIT_DIAGNOSTICS_FILE = "runner-exit-diagnostics.jsonl";
+function describeError(error) {
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message };
+    }
+    try {
+        return { message: String(error) };
+    }
+    catch {
+        return { message: "<unstringifiable error>" };
+    }
+}
+function appendJournalLineSync(journalPath, record) {
+    try {
+        mkdirSync(path.dirname(journalPath), { recursive: true });
+        appendFileSync(journalPath, `${JSON.stringify(record)}\n`, "utf8");
+    }
+    catch {
+        // Best-effort: journaling must never crash or alter exit behavior.
+    }
+}
+function removeJournalSync(journalPath) {
+    try {
+        unlinkSync(journalPath);
+    }
+    catch {
+        // Tolerate a missing journal (e.g. nothing was ever written).
+    }
+}
+export function installRunnerExitDiagnostics(options) {
+    const journalPath = path.join(options.runDir, RUNNER_EXIT_DIAGNOSTICS_FILE);
+    const target = options.target ?? process;
+    const armedAt = Date.now();
+    let stopped = false;
+    const base = {
+        runId: options.runId,
+        title: options.title,
+        pid: process.pid,
+        hostname: hostname(),
+    };
+    const safeSnapshot = () => {
+        try {
+            return options.snapshot();
+        }
+        catch {
+            return { status: "<snapshot-error>", running: [] };
+        }
+    };
+    const record = (kind, extra) => ({
+        ts: new Date().toISOString(),
+        kind,
+        ...base,
+        ...(extra ?? {}),
+        state: safeSnapshot(),
+    });
+    appendJournalLineSync(journalPath, {
+        ...record("armed"),
+        armedAt: new Date(armedAt).toISOString(),
+    });
+    const onProcessExit = (code) => {
+        if (stopped)
+            return;
+        appendJournalLineSync(journalPath, record("process-exit", {
+            code: typeof code === "number" ? code : process.exitCode ?? 0,
+            elapsedMs: Date.now() - armedAt,
+        }));
+    };
+    const onUncaughtException = (error, origin) => {
+        if (stopped)
+            return;
+        appendJournalLineSync(journalPath, record(origin === "unhandledRejection" ? "unhandled-rejection" : "uncaught-exception", {
+            error: describeError(error),
+            elapsedMs: Date.now() - armedAt,
+        }));
+        // Monitor listeners neither suppress fatal errors nor force a crash
+        // when the host has its own handlers or a nonfatal rejection policy.
+    };
+    target.on("exit", onProcessExit);
+    target.on("uncaughtExceptionMonitor", onUncaughtException);
+    return {
+        journalPath,
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            target.removeListener("exit", onProcessExit);
+            target.removeListener("uncaughtExceptionMonitor", onUncaughtException);
+            // Clean completion: leave completed runs free of diagnostics noise.
+            removeJournalSync(journalPath);
+        },
+    };
+}