@caupulican/pi-adaptative 0.81.39 → 0.81.40

package/dist/core/process-matrix/resume-launcher.js

@@ -0,0 +1,62 @@
+import { spawn } from "node:child_process";
+import { buildPiResumeLaunchSpec } from "../orchestration/agent-resume.js";
+export function buildResumablePiAgentWakePrompt(payload) {
+    const context = payload.agent.resumeContext;
+    const taskSummary = payload.taskSummary?.trim().slice(0, 2_000);
+    const contextPointers = context.contextPointers
+        .slice(0, 20)
+        .map((pointer) => `- ${JSON.stringify({ id: pointer.id, kind: pointer.kind, uri: pointer.uri, readOnly: pointer.readOnly }).slice(0, 1_000)}`);
+    return [
+        "Resume this interrupted delegated task using the persisted session context and the same logical agent identity.",
+        ...(taskSummary ? [`Task: ${taskSummary}`] : []),
+        ...(context.latestCheckpointId ? [`Latest checkpoint: ${context.latestCheckpointId}`] : []),
+        ...(contextPointers.length > 0 ? ["Persisted context pointers:", ...contextPointers] : []),
+        "Continue from the persisted transcript and referenced checkpoints or artifacts, then finish with a persisted terminal result.",
+    ].join("\n");
+}
+/** Launches one exact persisted Pi session; completion is observed only through process events. */
+export async function launchResumablePiAgent(options) {
+    const context = options.payload.agent.resumeContext;
+    if (!context || context.provider !== "pi") {
+        return { started: false, reason: "Pi resume context is unavailable." };
+    }
+    const spec = buildPiResumeLaunchSpec(options.payload.agent, {
+        executable: options.target.executable,
+        argsPrefix: options.target.argsPrefix,
+        parentPid: options.parentPid,
+        parentSessionId: options.parentSessionId,
+        taskRef: options.payload.taskRef,
+        wakePrompt: buildResumablePiAgentWakePrompt(options.payload),
+    });
+    if ([spec.executable, spec.cwd, ...spec.args].some((value) => value.includes("\0"))) {
+        return { started: false, reason: "Resume launch data contains a null byte." };
+    }
+    try {
+        const child = spawn(spec.executable, spec.args, {
+            cwd: spec.cwd,
+            detached: true,
+            stdio: "ignore",
+            env: { ...options.environment, ...spec.env },
+        });
+        return await new Promise((resolve) => {
+            child.once("error", (error) => resolve({ started: false, reason: error.message }));
+            child.once("spawn", () => {
+                const childPid = child.pid;
+                if (childPid === undefined || !Number.isSafeInteger(childPid) || childPid <= 0) {
+                    resolve({ started: false, reason: "Resume process started without a valid pid." });
+                    return;
+                }
+                const completion = new Promise((resolveCompletion, rejectCompletion) => {
+                    child.once("exit", (code, signal) => resolveCompletion({ code, signal }));
+                    child.once("error", rejectCompletion);
+                });
+                child.unref();
+                resolve({ started: true, pid: childPid, completion });
+            });
+        });
+    }
+    catch (error) {
+        return { started: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+//# sourceMappingURL=resume-launcher.js.map

package/dist/core/process-matrix/resume-launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-launcher.js","sourceRoot":"","sources":["../../../src/core/process-matrix/resume-launcher.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from \"node:child_process\";\nimport { buildPiResumeLaunchSpec } from \"../orchestration/agent-resume.ts\";\nimport type { ResumablePayload } from \"./codes.ts\";\n\nexport interface PiSelfLaunchTarget {\n\texecutable: string;\n\targsPrefix: readonly string[];\n}\n\nexport type ResumablePiAgentLaunchOutcome =\n\t| {\n\t\t\tstarted: true;\n\t\t\tpid: number;\n\t\t\tcompletion: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;\n\t  }\n\t| { started: false; reason: string };\n\nexport function buildResumablePiAgentWakePrompt(payload: ResumablePayload): string {\n\tconst context = payload.agent.resumeContext;\n\tconst taskSummary = payload.taskSummary?.trim().slice(0, 2_000);\n\tconst contextPointers = context.contextPointers\n\t\t.slice(0, 20)\n\t\t.map(\n\t\t\t(pointer) =>\n\t\t\t\t`- ${JSON.stringify({ id: pointer.id, kind: pointer.kind, uri: pointer.uri, readOnly: pointer.readOnly }).slice(0, 1_000)}`,\n\t\t);\n\treturn [\n\t\t\"Resume this interrupted delegated task using the persisted session context and the same logical agent identity.\",\n\t\t...(taskSummary ? [`Task: ${taskSummary}`] : []),\n\t\t...(context.latestCheckpointId ? [`Latest checkpoint: ${context.latestCheckpointId}`] : []),\n\t\t...(contextPointers.length > 0 ? [\"Persisted context pointers:\", ...contextPointers] : []),\n\t\t\"Continue from the persisted transcript and referenced checkpoints or artifacts, then finish with a persisted terminal result.\",\n\t].join(\"\\n\");\n}\n\n/** Launches one exact persisted Pi session; completion is observed only through process events. */\nexport async function launchResumablePiAgent(options: {\n\tpayload: ResumablePayload;\n\ttarget: PiSelfLaunchTarget;\n\tparentPid: number;\n\tparentSessionId: string;\n\tenvironment: NodeJS.ProcessEnv;\n}): Promise<ResumablePiAgentLaunchOutcome> {\n\tconst context = options.payload.agent.resumeContext;\n\tif (!context || context.provider !== \"pi\") {\n\t\treturn { started: false, reason: \"Pi resume context is unavailable.\" };\n\t}\n\tconst spec = buildPiResumeLaunchSpec(options.payload.agent, {\n\t\texecutable: options.target.executable,\n\t\targsPrefix: options.target.argsPrefix,\n\t\tparentPid: options.parentPid,\n\t\tparentSessionId: options.parentSessionId,\n\t\ttaskRef: options.payload.taskRef,\n\t\twakePrompt: buildResumablePiAgentWakePrompt(options.payload),\n\t});\n\tif ([spec.executable, spec.cwd, ...spec.args].some((value) => value.includes(\"\\0\"))) {\n\t\treturn { started: false, reason: \"Resume launch data contains a null byte.\" };\n\t}\n\ttry {\n\t\tconst child = spawn(spec.executable, spec.args, {\n\t\t\tcwd: spec.cwd,\n\t\t\tdetached: true,\n\t\t\tstdio: \"ignore\",\n\t\t\tenv: { ...options.environment, ...spec.env },\n\t\t});\n\t\treturn await new Promise<ResumablePiAgentLaunchOutcome>((resolve) => {\n\t\t\tchild.once(\"error\", (error) => resolve({ started: false, reason: error.message }));\n\t\t\tchild.once(\"spawn\", () => {\n\t\t\t\tconst childPid = child.pid;\n\t\t\t\tif (childPid === undefined || !Number.isSafeInteger(childPid) || childPid <= 0) {\n\t\t\t\t\tresolve({ started: false, reason: \"Resume process started without a valid pid.\" });\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tconst completion = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(\n\t\t\t\t\t(resolveCompletion, rejectCompletion) => {\n\t\t\t\t\t\tchild.once(\"exit\", (code, signal) => resolveCompletion({ code, signal }));\n\t\t\t\t\t\tchild.once(\"error\", rejectCompletion);\n\t\t\t\t\t},\n\t\t\t\t);\n\t\t\t\tchild.unref();\n\t\t\t\tresolve({ started: true, pid: childPid, completion });\n\t\t\t});\n\t\t});\n\t} catch (error) {\n\t\treturn { started: false, reason: error instanceof Error ? error.message : String(error) };\n\t}\n}\n"]}

package/dist/core/process-matrix/runtime.d.ts

@@ -11,38 +11,32 @@
  *   instead be adopted by a new parent). "No new turns" after that point is automatic: a dead
  *   parent injects no further follow-ups, so the worker simply runs out of work to do.
  * - A MASTER is everything else (no known parent). On startup it scans the matrix for orphaned
- *   workers (workers whose recorded parent is dead) and, when interactive, ASKS the owner before
- *   touching anything -- adopt, cooperative cleanup, or leave untouched. Non-interactive: report
- *   only, zero writes, zero kills.
+ *   workers (workers whose recorded parent is dead). Workers owned by this exact resumed session
+ *   are restored automatically; foreign workers remain owner-gated interactively and report-only
+ *   headlessly.
  *
- * One sanctioned exception to "a worker's entry is written only by that worker": the master
- * orphan-scan writes an adoption or a cooperative-cleanup request directly into an ORPHANED
- * worker's own entry, but ONLY after explicit owner confirmation (`promptConfirm`) -- mirroring
- * the worktree-sync integration lock's dead-owner takeover (a new owner may claim a PROVABLY DEAD
- * owner's resource). The worker itself later confirms/applies that grant locally via
- * `pollWorkerDirective` and re-writes its own entry -- see `docs/process-matrix.md`. Outside this
- * one ask-gated handshake, a master NEVER writes another session's entry, and nothing here ever
- * kills a process directly: every termination is either owner-confirmed or the worker's own
- * cooperative self-exit.
+ * Sanctioned exceptions to "a worker's entry is written only by that worker": an exact resumed
+ * parent may restore its recorded ownership, and an owner may explicitly approve adoption or
+ * cooperative cleanup of a foreign orphan. The worker later confirms/applies the directive via
+ * `pollWorkerDirective` and re-writes its own entry -- see `docs/process-matrix.md`. Outside these
+ * identity/approval-fenced handshakes, a master NEVER writes another session's entry, and nothing
+ * here ever kills a process directly.
  */
+import type { AgentIdentityContract } from "../orchestration/contracts.ts";
 import type { ResolvedProcessMatrixSettings } from "../settings-manager.ts";
-export declare const PI_PARENT_PID_ENV = "PI_PARENT_PID";
-export declare const PI_PARENT_SESSION_ENV = "PI_PARENT_SESSION";
-/** This process's declared parent pid, from the cross-process env contract. A malformed or
- * non-positive value is ignored (never a crash on bad env). */
-export declare function getParentPid(env?: NodeJS.ProcessEnv): number | undefined;
-/** This process's declared parent sessionId, from the cross-process env contract. */
-export declare function getParentSessionId(env?: NodeJS.ProcessEnv): string | undefined;
+import type { ResumablePayload } from "./codes.ts";
+export { getOrchestrationAgentId, getParentPid, getParentSessionId, getProcessTaskRef, PI_ORCHESTRATION_AGENT_ID_ENV, PI_PARENT_PID_ENV, PI_PARENT_SESSION_ENV, PI_TASK_REF_ENV, } from "../process-identity.ts";
 export interface ProcessMatrixRuntimeConfig {
     agentDir: string;
-    sessionId: string;
+    /** Canonical logical identity for this process and any exact-session resume. */
+    agent: AgentIdentityContract;
     /** Whether an interactive UI is available to ask the owner (see `promptConfirm`). */
     hasUI: boolean;
     settings: ResolvedProcessMatrixSettings;
     isProcessAlive: (pid: number) => boolean;
     now?: () => number;
     /** Structural notice injection into the running session (host `sendCustomMessage` seam). */
-    notify: (text: string) => void;
+    notify: (text: string) => void | Promise<void>;
     /** Diagnostics sink (never throws into the session). */
     onDiagnostic?: (message: string) => void;
     /** The ask seam: resolves false on decline AND on any non-interactive/non-TTY caller. */
@@ -50,10 +44,31 @@ export interface ProcessMatrixRuntimeConfig {
     /** Cooperative self-exit -- called by a worker once wound down (grace expiry or a
      * master-granted cleanup directive). Never called for the master's own lifecycle. */
     requestExit: () => void;
+    /** Stable goal/task identity. Automatic recovery requires an exact match. */
+    taskRef?: string;
+    taskSummary?: string;
+    /** False for terminal/blocked owner state; recovery then remains explicit-owner gated. */
+    allowAutomaticRecovery?: boolean;
+    /** Starts a replacement OS process for a dead resumable worker. Completion is an event-driven
+     * terminal signal; worker product remains in its persisted session/artifacts. */
+    resumeWorker?: (payload: ResumablePayload) => Promise<ResumeWorkerLaunchOutcome>;
 }
+export type ResumeWorkerLaunchOutcome = {
+    started: true;
+    /** OS identity of this specific replacement process, used to fence its terminal handoff. */
+    pid: number;
+    completion: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+} | {
+    started: false;
+    reason: string;
+};
 export interface ProcessMatrixRuntimeHandle {
-    stop(): void;
+    stop(): Promise<void> | void;
 }
+export declare const PROCESS_MATRIX_RESUMABLE_RETENTION_MS: number;
 /**
  * Start the per-session process-matrix runtime. No-op when disabled (byte-identical to not
  * calling this at all). Never throws: a broken store must surface as a diagnostic, not a startup

package/dist/core/process-matrix/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/core/process-matrix/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAgB5E,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AACjD,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD;+DAC+D;AAC/D,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAKrF;AAED,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,6BAA6B,CAAC;IACxC,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,4FAA4F;IAC5F,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,wDAAwD;IACxD,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,yFAAyF;IACzF,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD;yFACqF;IACrF,WAAW,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IAC1C,IAAI,IAAI,IAAI,CAAC;CACb;AAYD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC9C,MAAM,EAAE,0BAA0B,GAChC,OAAO,CAAC,0BAA0B,CAAC,CAcrC","sourcesContent":["/**\n * Process-matrix runtime composition: the pieces main.ts wires together for durable,\n * restart-surviving master/worker process supervision.\n *\n * Contract:\n * - A WORKER is any process launched with a known parent (`PI_PARENT_PID` -- set by the\n *   `--parent-pid` CLI flag, or directly by a launcher such as tmux dispatch). It self-registers\n *   its OWN entry (the single writer of that entry during normal operation) and watches its\n *   parent's liveness. On parent death it winds down GRACEFULLY -- never silently -- leaving a\n *   `resumable` payload, then exits on its own after a bounded grace window (during which it may\n *   instead be adopted by a new parent). \"No new turns\" after that point is automatic: a dead\n *   parent injects no further follow-ups, so the worker simply runs out of work to do.\n * - A MASTER is everything else (no known parent). On startup it scans the matrix for orphaned\n *   workers (workers whose recorded parent is dead) and, when interactive, ASKS the owner before\n *   touching anything -- adopt, cooperative cleanup, or leave untouched. Non-interactive: report\n *   only, zero writes, zero kills.\n *\n * One sanctioned exception to \"a worker's entry is written only by that worker\": the master\n * orphan-scan writes an adoption or a cooperative-cleanup request directly into an ORPHANED\n * worker's own entry, but ONLY after explicit owner confirmation (`promptConfirm`) -- mirroring\n * the worktree-sync integration lock's dead-owner takeover (a new owner may claim a PROVABLY DEAD\n * owner's resource). The worker itself later confirms/applies that grant locally via\n * `pollWorkerDirective` and re-writes its own entry -- see `docs/process-matrix.md`. Outside this\n * one ask-gated handshake, a master NEVER writes another session's entry, and nothing here ever\n * kills a process directly: every termination is either owner-confirmed or the worker's own\n * cooperative self-exit.\n */\n\nimport { hostname as osHostname } from \"node:os\";\nimport type { ResolvedProcessMatrixSettings } from \"../settings-manager.ts\";\nimport { getBoundWorktreeLaneKey } from \"../worktree-sync/runtime.ts\";\nimport type { ProcessMatrixEntry, ResumablePayload } from \"./codes.ts\";\nimport { buildEntryId, listEntries, readEntry, writeEntry, writeEntrySync } from \"./store.ts\";\nimport {\n\tapplyAdoption,\n\tapplyHeartbeat,\n\tbeginWindDown,\n\tbuildMasterEntry,\n\tbuildWorkerEntry,\n\tdetectOrphanedWorkers,\n\tmarkClosed,\n\tmarkResumable,\n\tpollWorkerDirective,\n} from \"./supervisor.ts\";\n\nexport const PI_PARENT_PID_ENV = \"PI_PARENT_PID\";\nexport const PI_PARENT_SESSION_ENV = \"PI_PARENT_SESSION\";\n\n/** This process's declared parent pid, from the cross-process env contract. A malformed or\n * non-positive value is ignored (never a crash on bad env). */\nexport function getParentPid(env: NodeJS.ProcessEnv = process.env): number | undefined {\n\tconst raw = env[PI_PARENT_PID_ENV];\n\tif (raw === undefined) return undefined;\n\tconst value = Number.parseInt(raw, 10);\n\treturn Number.isFinite(value) && value > 0 ? value : undefined;\n}\n\n/** This process's declared parent sessionId, from the cross-process env contract. */\nexport function getParentSessionId(env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst value = env[PI_PARENT_SESSION_ENV]?.trim();\n\treturn value && value.length > 0 ? value : undefined;\n}\n\nexport interface ProcessMatrixRuntimeConfig {\n\tagentDir: string;\n\tsessionId: string;\n\t/** Whether an interactive UI is available to ask the owner (see `promptConfirm`). */\n\thasUI: boolean;\n\tsettings: ResolvedProcessMatrixSettings;\n\tisProcessAlive: (pid: number) => boolean;\n\tnow?: () => number;\n\t/** Structural notice injection into the running session (host `sendCustomMessage` seam). */\n\tnotify: (text: string) => void;\n\t/** Diagnostics sink (never throws into the session). */\n\tonDiagnostic?: (message: string) => void;\n\t/** The ask seam: resolves false on decline AND on any non-interactive/non-TTY caller. */\n\tpromptConfirm: (message: string) => Promise<boolean>;\n\t/** Cooperative self-exit -- called by a worker once wound down (grace expiry or a\n\t * master-granted cleanup directive). Never called for the master's own lifecycle. */\n\trequestExit: () => void;\n}\n\nexport interface ProcessMatrixRuntimeHandle {\n\tstop(): void;\n}\n\nconst NOOP_HANDLE: ProcessMatrixRuntimeHandle = { stop: () => {} };\n\nfunction describeError(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nfunction nowIso(now: () => number): string {\n\treturn new Date(now()).toISOString();\n}\n\n/**\n * Start the per-session process-matrix runtime. No-op when disabled (byte-identical to not\n * calling this at all). Never throws: a broken store must surface as a diagnostic, not a startup\n * crash.\n */\nexport async function startProcessMatrixRuntime(\n\tconfig: ProcessMatrixRuntimeConfig,\n): Promise<ProcessMatrixRuntimeHandle> {\n\tif (!config.settings.enabled) return NOOP_HANDLE;\n\tconst now = config.now ?? Date.now;\n\tconst parentPid = getParentPid();\n\n\ttry {\n\t\tif (parentPid !== undefined) {\n\t\t\treturn await startWorkerBranch(config, parentPid, now);\n\t\t}\n\t\treturn await startMasterBranch(config, now);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: runtime failed to start: ${describeError(error)}`);\n\t\treturn NOOP_HANDLE;\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Master branch\n// ---------------------------------------------------------------------------\n\nasync function startMasterBranch(\n\tconfig: ProcessMatrixRuntimeConfig,\n\tnow: () => number,\n): Promise<ProcessMatrixRuntimeHandle> {\n\tlet entry = buildMasterEntry({\n\t\tsessionId: config.sessionId,\n\t\tpid: process.pid,\n\t\thostname: osHostname(),\n\t\tnow: nowIso(now),\n\t});\n\ttry {\n\t\tawait writeEntry(config.agentDir, entry);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: failed to register master entry: ${describeError(error)}`);\n\t}\n\n\tlet stopped = false;\n\tconst heartbeatTimer = setInterval(() => {\n\t\tif (stopped) return;\n\t\tentry = applyHeartbeat(entry, nowIso(now));\n\t\tvoid writeEntry(config.agentDir, entry).catch((error) => {\n\t\t\tconfig.onDiagnostic?.(`process-matrix: failed to write master heartbeat: ${describeError(error)}`);\n\t\t});\n\t}, config.settings.heartbeatMs);\n\theartbeatTimer.unref?.();\n\n\t// Best-effort close on process exit. A SIGKILLed master leaving \"running\" is fine -- reconcile's\n\t// own dead-pid detection covers it; this only makes the common clean-exit case tidy.\n\tprocess.on(\"exit\", () => {\n\t\ttry {\n\t\t\twriteEntrySync(config.agentDir, markClosed(entry, nowIso(now)));\n\t\t} catch {\n\t\t\t// Best-effort only -- see module doc.\n\t\t}\n\t});\n\n\tvoid runOrphanScan(config, now);\n\n\treturn {\n\t\tstop() {\n\t\t\tstopped = true;\n\t\t\tclearInterval(heartbeatTimer);\n\t\t},\n\t};\n}\n\nasync function runOrphanScan(config: ProcessMatrixRuntimeConfig, now: () => number): Promise<void> {\n\tlet entries: ProcessMatrixEntry[];\n\ttry {\n\t\tentries = await listEntries(config.agentDir);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: orphan scan failed to list entries: ${describeError(error)}`);\n\t\treturn;\n\t}\n\tconst orphans = detectOrphanedWorkers(entries, {\n\t\tisPidAlive: config.isProcessAlive,\n\t\townSessionId: config.sessionId,\n\t});\n\tif (orphans.length === 0) return;\n\n\tif (!config.hasUI) {\n\t\tconfig.onDiagnostic?.(\n\t\t\t`process-matrix: found ${orphans.length} orphaned worker(s) with no reachable parent (report-only, non-interactive; nothing written, nothing killed): ${orphans\n\t\t\t\t.map((orphan) => orphan.entryId)\n\t\t\t\t.join(\", \")}`,\n\t\t);\n\t\treturn;\n\t}\n\n\tfor (const orphan of orphans) {\n\t\tconst adopt = await config.promptConfirm(`adopt worker ${orphan.entryId} (lane ${orphan.laneKey ?? \"none\"})?`);\n\t\tif (adopt) {\n\t\t\tconst adopted = applyAdoption(orphan, { parentPid: process.pid, parentSessionId: config.sessionId });\n\t\t\ttry {\n\t\t\t\tawait writeEntry(config.agentDir, adopted);\n\t\t\t} catch (error) {\n\t\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t\t`process-matrix: failed to write adoption for ${orphan.entryId}: ${describeError(error)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tconst cleanup = await config.promptConfirm(`clean up worker ${orphan.entryId} gracefully?`);\n\t\tif (!cleanup) continue;\n\t\tconst windingDown = beginWindDown(orphan, \"user_cleanup\", nowIso(now));\n\t\ttry {\n\t\t\tawait writeEntry(config.agentDir, windingDown);\n\t\t} catch (error) {\n\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t`process-matrix: failed to write cleanup for ${orphan.entryId}: ${describeError(error)}`,\n\t\t\t);\n\t\t}\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Worker branch\n// ---------------------------------------------------------------------------\n\nasync function startWorkerBranch(\n\tconfig: ProcessMatrixRuntimeConfig,\n\tinitialParentPid: number,\n\tnow: () => number,\n): Promise<ProcessMatrixRuntimeHandle> {\n\tconst parentSessionId = getParentSessionId();\n\tconst laneKey = getBoundWorktreeLaneKey();\n\n\tlet entry = buildWorkerEntry({\n\t\tsessionId: config.sessionId,\n\t\tpid: process.pid,\n\t\thostname: osHostname(),\n\t\tnow: nowIso(now),\n\t\tparentPid: initialParentPid,\n\t\t...(parentSessionId !== undefined ? { parentSessionId } : {}),\n\t\t...(laneKey !== undefined ? { laneKey } : {}),\n\t});\n\ttry {\n\t\tawait writeEntry(config.agentDir, entry);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: failed to register worker entry: ${describeError(error)}`);\n\t}\n\n\tlet currentParentPid = initialParentPid;\n\tlet currentParentSessionId = parentSessionId;\n\tlet stopped = false;\n\tlet timer: NodeJS.Timeout | undefined;\n\tlet ticking = false;\n\n\tconst stop = (): void => {\n\t\tstopped = true;\n\t\tif (timer) clearInterval(timer);\n\t\ttimer = undefined;\n\t};\n\n\tconst persist = async (next: ProcessMatrixEntry, failureContext: string): Promise<void> => {\n\t\tentry = next;\n\t\ttry {\n\t\t\tawait writeEntry(config.agentDir, entry);\n\t\t} catch (error) {\n\t\t\tconfig.onDiagnostic?.(`process-matrix: ${failureContext}: ${describeError(error)}`);\n\t\t}\n\t};\n\n\tconst startHealthyWatch = (): void => {\n\t\ttimer = setInterval(() => {\n\t\t\tif (ticking) return;\n\t\t\tticking = true;\n\t\t\tvoid healthyTick().finally(() => {\n\t\t\t\tticking = false;\n\t\t\t});\n\t\t}, config.settings.watcherPollMs);\n\t\ttimer.unref?.();\n\t};\n\n\tconst declaredParentIsAlive = async (): Promise<boolean> => {\n\t\t// PID liveness alone is not process identity: a reused PID could otherwise keep a worker\n\t\t// attached to an unrelated process forever. The parent session's own fresh master entry binds\n\t\t// PID to a durable identity and proves that that exact session is still heartbeating.\n\t\tif (!currentParentSessionId || !config.isProcessAlive(currentParentPid)) return false;\n\t\tconst parent = await readEntry(config.agentDir, buildEntryId(\"master\", currentParentSessionId));\n\t\tif (!parent || parent.role !== \"master\" || parent.sessionId !== currentParentSessionId) return false;\n\t\tif (parent.pid !== currentParentPid || parent.status !== \"running\") return false;\n\t\tconst heartbeatAt = Date.parse(parent.heartbeatAt);\n\t\tconst maxAge = config.settings.heartbeatMs * 2 + config.settings.watcherPollMs;\n\t\treturn Number.isFinite(heartbeatAt) && now() - heartbeatAt <= maxAge;\n\t};\n\n\tconst healthyTick = async (): Promise<void> => {\n\t\tif (stopped) return;\n\t\tif (!(await declaredParentIsAlive())) {\n\t\t\tawait enterWindDown();\n\t\t\treturn;\n\t\t}\n\t\t// Still healthy: also poll for a master-initiated cooperative-cleanup directive.\n\t\tconst fresh = await readEntry(config.agentDir, entry.entryId);\n\t\tif (!fresh) return;\n\t\tconst directive = pollWorkerDirective(fresh, currentParentPid, { isPidAlive: config.isProcessAlive });\n\t\tif (directive.code !== \"user_cleanup\") return;\n\t\tawait persist(\n\t\t\tbeginWindDown(fresh, \"user_cleanup\", nowIso(now)),\n\t\t\t\"failed to write a master-requested worker wind-down\",\n\t\t);\n\t\tconfig.notify(\"process-matrix: the parent session requested a cooperative cleanup. Winding down.\");\n\t\tstop();\n\t\tconfig.requestExit();\n\t};\n\n\tconst enterWindDown = async (): Promise<void> => {\n\t\tif (timer) {\n\t\t\tclearInterval(timer);\n\t\t\ttimer = undefined;\n\t\t}\n\t\tconst windDownAt = nowIso(now);\n\t\tconst resumable: ResumablePayload = { lastCode: \"resumable\" };\n\t\tif (laneKey !== undefined) resumable.laneKey = laneKey;\n\t\tawait persist(\n\t\t\tmarkResumable(beginWindDown(entry, \"parent_lost\", windDownAt), resumable, windDownAt),\n\t\t\t\"failed to write worker wind-down\",\n\t\t);\n\t\tconfig.notify(\n\t\t\t`process-matrix: parent process (pid ${currentParentPid}) is gone. Winding down gracefully; this task is resumable.`,\n\t\t);\n\t\tstartGraceWatch();\n\t};\n\n\tconst startGraceWatch = (): void => {\n\t\tconst graceDeadline = now() + config.settings.adoptionGraceMs;\n\t\ttimer = setInterval(() => {\n\t\t\tif (ticking) return;\n\t\t\tticking = true;\n\t\t\tvoid graceTick(graceDeadline).finally(() => {\n\t\t\t\tticking = false;\n\t\t\t});\n\t\t}, config.settings.watcherPollMs);\n\t\ttimer.unref?.();\n\t};\n\n\tconst graceTick = async (graceDeadline: number): Promise<void> => {\n\t\tif (stopped) return;\n\t\tconst fresh = await readEntry(config.agentDir, entry.entryId);\n\t\tif (fresh) {\n\t\t\tconst directive = pollWorkerDirective(fresh, currentParentPid, { isPidAlive: config.isProcessAlive });\n\t\t\tif (directive.code === \"adopt\" && fresh.parentSessionId) {\n\t\t\t\t// The adopting master persists its session id with the pid. Require both on the next\n\t\t\t\t// healthy tick; accepting a pid-only adoption would reintroduce the PID-reuse bug.\n\t\t\t\tawait persist(\n\t\t\t\t\tapplyAdoption(fresh, { parentPid: directive.parentPid, parentSessionId: fresh.parentSessionId }),\n\t\t\t\t\t\"failed to write worker adoption\",\n\t\t\t\t);\n\t\t\t\tconfig.notify(`process-matrix: adopted by a new parent (pid ${directive.parentPid}). Resuming.`);\n\t\t\t\tcurrentParentPid = directive.parentPid;\n\t\t\t\tcurrentParentSessionId = fresh.parentSessionId;\n\t\t\t\tif (timer) {\n\t\t\t\t\tclearInterval(timer);\n\t\t\t\t\ttimer = undefined;\n\t\t\t\t}\n\t\t\t\tstartHealthyWatch();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (directive.code === \"user_cleanup\") {\n\t\t\t\tstop();\n\t\t\t\tconfig.requestExit();\n\t\t\t\treturn;\n\t\t\t}\n\t\t}\n\t\tif (now() >= graceDeadline) {\n\t\t\tstop();\n\t\t\tconfig.requestExit();\n\t\t}\n\t};\n\n\tstartHealthyWatch();\n\n\treturn { stop };\n}\n"]}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/core/process-matrix/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAE3E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAE5E,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAyBvE,OAAO,EACN,uBAAuB,EACvB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,EAC7B,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,GACf,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,KAAK,EAAE,qBAAqB,CAAC;IAC7B,qFAAqF;IACrF,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,6BAA6B,CAAC;IACxC,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,4FAA4F;IAC5F,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,wDAAwD;IACxD,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,yFAAyF;IACzF,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD;yFACqF;IACrF,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;qFACiF;IACjF,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACjF;AAED,MAAM,MAAM,yBAAyB,GAClC;IACA,OAAO,EAAE,IAAI,CAAC;IACd,4FAA4F;IAC5F,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC3E,GACD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,0BAA0B;IAC1C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7B;AAGD,eAAO,MAAM,qCAAqC,QAAwB,CAAC;AAoB3E;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC9C,MAAM,EAAE,0BAA0B,GAChC,OAAO,CAAC,0BAA0B,CAAC,CAerC","sourcesContent":["/**\n * Process-matrix runtime composition: the pieces main.ts wires together for durable,\n * restart-surviving master/worker process supervision.\n *\n * Contract:\n * - A WORKER is any process launched with a known parent (`PI_PARENT_PID` -- set by the\n *   `--parent-pid` CLI flag, or directly by a launcher such as tmux dispatch). It self-registers\n *   its OWN entry (the single writer of that entry during normal operation) and watches its\n *   parent's liveness. On parent death it winds down GRACEFULLY -- never silently -- leaving a\n *   `resumable` payload, then exits on its own after a bounded grace window (during which it may\n *   instead be adopted by a new parent). \"No new turns\" after that point is automatic: a dead\n *   parent injects no further follow-ups, so the worker simply runs out of work to do.\n * - A MASTER is everything else (no known parent). On startup it scans the matrix for orphaned\n *   workers (workers whose recorded parent is dead). Workers owned by this exact resumed session\n *   are restored automatically; foreign workers remain owner-gated interactively and report-only\n *   headlessly.\n *\n * Sanctioned exceptions to \"a worker's entry is written only by that worker\": an exact resumed\n * parent may restore its recorded ownership, and an owner may explicitly approve adoption or\n * cooperative cleanup of a foreign orphan. The worker later confirms/applies the directive via\n * `pollWorkerDirective` and re-writes its own entry -- see `docs/process-matrix.md`. Outside these\n * identity/approval-fenced handshakes, a master NEVER writes another session's entry, and nothing\n * here ever kills a process directly.\n */\n\nimport { hostname as osHostname } from \"node:os\";\nimport { isAgentIdentity } from \"../orchestration/agent-resume.ts\";\nimport type { AgentIdentityContract } from \"../orchestration/contracts.ts\";\nimport { getParentPid, getParentSessionId, getProcessTaskRef } from \"../process-identity.ts\";\nimport type { ResolvedProcessMatrixSettings } from \"../settings-manager.ts\";\nimport { getBoundWorktreeLaneKey } from \"../worktree-sync/runtime.ts\";\nimport type { ProcessMatrixEntry, ResumablePayload } from \"./codes.ts\";\nimport {\n\tbuildEntryId,\n\tlistEntries,\n\treadEntry,\n\tremoveEntryIfUnchanged,\n\twriteEntry,\n\twriteEntryIfUnchanged,\n\twriteEntryIfUnchangedSync,\n} from \"./store.ts\";\nimport {\n\tapplyAdoption,\n\tapplyHeartbeat,\n\tbeginWindDown,\n\tbuildMasterEntry,\n\tbuildWorkerEntry,\n\tdetectOrphanedWorkers,\n\tmarkClosed,\n\tmarkResumable,\n\tmarkTerminal,\n\tmarkTerminalNotificationDelivered,\n\tpollWorkerDirective,\n\treconcileMatrix,\n} from \"./supervisor.ts\";\n\nexport {\n\tgetOrchestrationAgentId,\n\tgetParentPid,\n\tgetParentSessionId,\n\tgetProcessTaskRef,\n\tPI_ORCHESTRATION_AGENT_ID_ENV,\n\tPI_PARENT_PID_ENV,\n\tPI_PARENT_SESSION_ENV,\n\tPI_TASK_REF_ENV,\n} from \"../process-identity.ts\";\n\nexport interface ProcessMatrixRuntimeConfig {\n\tagentDir: string;\n\t/** Canonical logical identity for this process and any exact-session resume. */\n\tagent: AgentIdentityContract;\n\t/** Whether an interactive UI is available to ask the owner (see `promptConfirm`). */\n\thasUI: boolean;\n\tsettings: ResolvedProcessMatrixSettings;\n\tisProcessAlive: (pid: number) => boolean;\n\tnow?: () => number;\n\t/** Structural notice injection into the running session (host `sendCustomMessage` seam). */\n\tnotify: (text: string) => void | Promise<void>;\n\t/** Diagnostics sink (never throws into the session). */\n\tonDiagnostic?: (message: string) => void;\n\t/** The ask seam: resolves false on decline AND on any non-interactive/non-TTY caller. */\n\tpromptConfirm: (message: string) => Promise<boolean>;\n\t/** Cooperative self-exit -- called by a worker once wound down (grace expiry or a\n\t * master-granted cleanup directive). Never called for the master's own lifecycle. */\n\trequestExit: () => void;\n\t/** Stable goal/task identity. Automatic recovery requires an exact match. */\n\ttaskRef?: string;\n\ttaskSummary?: string;\n\t/** False for terminal/blocked owner state; recovery then remains explicit-owner gated. */\n\tallowAutomaticRecovery?: boolean;\n\t/** Starts a replacement OS process for a dead resumable worker. Completion is an event-driven\n\t * terminal signal; worker product remains in its persisted session/artifacts. */\n\tresumeWorker?: (payload: ResumablePayload) => Promise<ResumeWorkerLaunchOutcome>;\n}\n\nexport type ResumeWorkerLaunchOutcome =\n\t| {\n\t\t\tstarted: true;\n\t\t\t/** OS identity of this specific replacement process, used to fence its terminal handoff. */\n\t\t\tpid: number;\n\t\t\tcompletion: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;\n\t  }\n\t| { started: false; reason: string };\n\nexport interface ProcessMatrixRuntimeHandle {\n\tstop(): Promise<void> | void;\n}\n\nconst NOOP_HANDLE: ProcessMatrixRuntimeHandle = { stop: () => {} };\nexport const PROCESS_MATRIX_RESUMABLE_RETENTION_MS = 30 * 24 * 60 * 60_000;\n\nfunction describeError(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nfunction nowIso(now: () => number): string {\n\treturn new Date(now()).toISOString();\n}\n\nfunction emitRuntimeNotice(config: ProcessMatrixRuntimeConfig, text: string): void {\n\ttry {\n\t\tvoid Promise.resolve(config.notify(text)).catch((error: unknown) => {\n\t\t\tconfig.onDiagnostic?.(`process-matrix: failed to notify session: ${describeError(error)}`);\n\t\t});\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: failed to notify session: ${describeError(error)}`);\n\t}\n}\n\n/**\n * Start the per-session process-matrix runtime. No-op when disabled (byte-identical to not\n * calling this at all). Never throws: a broken store must surface as a diagnostic, not a startup\n * crash.\n */\nexport async function startProcessMatrixRuntime(\n\tconfig: ProcessMatrixRuntimeConfig,\n): Promise<ProcessMatrixRuntimeHandle> {\n\tif (!config.settings.enabled) return NOOP_HANDLE;\n\tconst now = config.now ?? Date.now;\n\tconst parentPid = getParentPid();\n\n\ttry {\n\t\tif (!isAgentIdentity(config.agent)) throw new TypeError(\"Process-matrix agent identity is invalid.\");\n\t\tif (parentPid !== undefined) {\n\t\t\treturn await startWorkerBranch(config, parentPid, now);\n\t\t}\n\t\treturn await startMasterBranch(config, now);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: runtime failed to start: ${describeError(error)}`);\n\t\treturn NOOP_HANDLE;\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Master branch\n// ---------------------------------------------------------------------------\n\nasync function startMasterBranch(\n\tconfig: ProcessMatrixRuntimeConfig,\n\tnow: () => number,\n): Promise<ProcessMatrixRuntimeHandle> {\n\tlet entry = buildMasterEntry({\n\t\tagent: config.agent,\n\t\tpid: process.pid,\n\t\thostname: osHostname(),\n\t\tnow: nowIso(now),\n\t});\n\ttry {\n\t\tawait writeEntry(config.agentDir, entry);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: failed to register master entry: ${describeError(error)}`);\n\t}\n\n\tlet stopped = false;\n\tlet ownsEntry = true;\n\tlet heartbeatTask: Promise<void> | undefined;\n\tconst lifetime = new AbortController();\n\tconst heartbeatTimer = setInterval(() => {\n\t\tif (stopped || !ownsEntry || heartbeatTask) return;\n\t\tconst expected = entry;\n\t\tconst next = applyHeartbeat(expected, nowIso(now));\n\t\theartbeatTask = writeEntryIfUnchanged(config.agentDir, expected.entryId, expected, next)\n\t\t\t.then((written) => {\n\t\t\t\tif (written) {\n\t\t\t\t\tentry = next;\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\townsEntry = false;\n\t\t\t\tlifetime.abort();\n\t\t\t\tclearInterval(heartbeatTimer);\n\t\t\t\tprocess.off(\"exit\", closeOnExit);\n\t\t\t\tconfig.onDiagnostic?.(\"process-matrix: master entry ownership moved to a newer process generation\");\n\t\t\t})\n\t\t\t.catch((error: unknown) => {\n\t\t\t\tconfig.onDiagnostic?.(`process-matrix: failed to write master heartbeat: ${describeError(error)}`);\n\t\t\t})\n\t\t\t.finally(() => {\n\t\t\t\theartbeatTask = undefined;\n\t\t\t});\n\t}, config.settings.heartbeatMs);\n\theartbeatTimer.unref?.();\n\n\t// Best-effort close on process exit. A SIGKILLed master leaving \"running\" is fine -- reconcile's\n\t// own dead-pid detection covers it; this only makes the common clean-exit case tidy.\n\tconst closeOnExit = (): void => {\n\t\tif (!ownsEntry) return;\n\t\ttry {\n\t\t\tconst closed = markClosed(entry, nowIso(now));\n\t\t\tif (writeEntryIfUnchangedSync(config.agentDir, entry, closed)) entry = closed;\n\t\t} catch {\n\t\t\t// Best-effort only -- see module doc.\n\t\t}\n\t};\n\tprocess.once(\"exit\", closeOnExit);\n\n\tconst maintenance = reconcileAndRunOrphanScan(config, now, lifetime.signal).catch((error: unknown) => {\n\t\tconfig.onDiagnostic?.(`process-matrix: maintenance failed: ${describeError(error)}`);\n\t});\n\n\treturn {\n\t\tasync stop() {\n\t\t\tif (stopped) return;\n\t\t\tstopped = true;\n\t\t\tlifetime.abort();\n\t\t\tclearInterval(heartbeatTimer);\n\t\t\tprocess.off(\"exit\", closeOnExit);\n\t\t\tawait heartbeatTask;\n\t\t\tif (ownsEntry) {\n\t\t\t\tconst closed = markClosed(entry, nowIso(now));\n\t\t\t\tif (await writeEntryIfUnchanged(config.agentDir, entry.entryId, entry, closed)) entry = closed;\n\t\t\t}\n\t\t\tawait maintenance;\n\t\t},\n\t};\n}\n\nasync function reconcileAndRunOrphanScan(\n\tconfig: ProcessMatrixRuntimeConfig,\n\tnow: () => number,\n\tsignal: AbortSignal,\n): Promise<void> {\n\tlet entries: ProcessMatrixEntry[];\n\ttry {\n\t\tentries = await listEntries(config.agentDir);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: reconciliation failed to list entries: ${describeError(error)}`);\n\t\treturn;\n\t}\n\tif (signal.aborted) return;\n\tconst reconciled = reconcileMatrix(entries, {\n\t\tisPidAlive: (pid) => pid === process.pid || config.isProcessAlive(pid),\n\t\tnow: now(),\n\t\tresumableTtlMs: PROCESS_MATRIX_RESUMABLE_RETENTION_MS,\n\t});\n\tconst originalByEntryId = new Map(entries.map((entry) => [entry.entryId, entry]));\n\tconst recoveredEntryIdSet = new Set(reconciled.recoveredEntryIds);\n\tconst [prunedOutcomes, recoveredOutcomes] = await Promise.all([\n\t\tPromise.all(\n\t\t\treconciled.prunedEntryIds.map((entryId) => {\n\t\t\t\tconst original = originalByEntryId.get(entryId);\n\t\t\t\treturn original ? removeEntryIfUnchanged(config.agentDir, original) : false;\n\t\t\t}),\n\t\t),\n\t\tPromise.all(\n\t\t\treconciled.kept\n\t\t\t\t.filter((entry) => recoveredEntryIdSet.has(entry.entryId))\n\t\t\t\t.map((entry) => {\n\t\t\t\t\tconst original = originalByEntryId.get(entry.entryId);\n\t\t\t\t\treturn original ? writeEntryIfUnchanged(config.agentDir, entry.entryId, original, entry) : false;\n\t\t\t\t}),\n\t\t),\n\t]);\n\tif (signal.aborted) return;\n\tconst recoveredCount = recoveredOutcomes.filter(Boolean).length;\n\tconst prunedCount = prunedOutcomes.filter(Boolean).length;\n\tif (recoveredCount > 0) {\n\t\tconfig.onDiagnostic?.(\n\t\t\t`process-matrix: recovered ${recoveredCount} interrupted Pi worker entr${recoveredCount === 1 ? \"y\" : \"ies\"}`,\n\t\t);\n\t}\n\tif (prunedCount > 0) {\n\t\tconfig.onDiagnostic?.(\n\t\t\t`process-matrix: pruned ${prunedCount} terminal or expired entr${prunedCount === 1 ? \"y\" : \"ies\"}`,\n\t\t);\n\t}\n\tconst currentEntries = await listEntries(config.agentDir);\n\tawait deliverTerminalNotifications(config, currentEntries, now, signal);\n\tif (signal.aborted) return;\n\tawait runOrphanScan(config, currentEntries, now, signal);\n}\n\nasync function deliverTerminalNotifications(\n\tconfig: ProcessMatrixRuntimeConfig,\n\tentries: ProcessMatrixEntry[],\n\tnow: () => number,\n\tsignal: AbortSignal,\n): Promise<void> {\n\tfor (const entry of entries) {\n\t\tif (\n\t\t\tsignal.aborted ||\n\t\t\tentry.status !== \"closed\" ||\n\t\t\t!entry.terminal ||\n\t\t\tentry.terminal.notificationDeliveredAt ||\n\t\t\tentry.parentSessionId !== config.agent.resumeContext.sessionId\n\t\t)\n\t\t\tcontinue;\n\t\ttry {\n\t\t\tawait config.notify(formatTerminalNotification(entry));\n\t\t\tif (signal.aborted) return;\n\t\t} catch (error) {\n\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t`process-matrix: failed to deliver terminal handoff for ${entry.entryId}: ${describeError(error)}`,\n\t\t\t);\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tconst delivered = markTerminalNotificationDelivered(entry, nowIso(now));\n\t\t\tif (!(await writeEntryIfUnchanged(config.agentDir, entry.entryId, entry, delivered))) {\n\t\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t\t`process-matrix: terminal handoff changed before acknowledgement for ${entry.entryId}`,\n\t\t\t\t);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t`process-matrix: failed to acknowledge terminal handoff for ${entry.entryId}: ${describeError(error)}`,\n\t\t\t);\n\t\t}\n\t}\n}\n\nfunction formatTerminalNotification(entry: ProcessMatrixEntry): string {\n\tconst terminal = entry.terminal;\n\treturn `process-matrix: resumed agent ${entry.agent.agentId} reached a terminal process state (code ${terminal?.code ?? \"none\"}, signal ${terminal?.signal ?? \"none\"}). Inspect its persisted result before continuing.`;\n}\n\nasync function runOrphanScan(\n\tconfig: ProcessMatrixRuntimeConfig,\n\tentries: ProcessMatrixEntry[],\n\tnow: () => number,\n\tsignal: AbortSignal,\n): Promise<void> {\n\tconst orphans = detectOrphanedWorkers(entries, {\n\t\tisPidAlive: config.isProcessAlive,\n\t\townSessionId: config.agent.resumeContext.sessionId,\n\t});\n\tif (orphans.length === 0) return;\n\n\tfor (const orphan of orphans) {\n\t\tif (signal.aborted) return;\n\t\tconst recoveryBoundary = getAutomaticRecoveryBoundary(config, orphan);\n\t\tconst exactResumedParent = recoveryBoundary === undefined;\n\t\tif (!config.isProcessAlive(orphan.pid)) {\n\t\t\tif (!exactResumedParent) {\n\t\t\t\tif (!config.hasUI) {\n\t\t\t\t\treportOwnerGatedOrphan(config, orphan, recoveryBoundary);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst payload = orphan.resumable;\n\t\t\t\tif (!payload) {\n\t\t\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t\t\t`process-matrix: dead worker ${orphan.entryId} is not resumable because its launch context is unavailable`,\n\t\t\t\t\t);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst resume = await config.promptConfirm(\n\t\t\t\t\t`resume agent ${payload.agent.agentId} from its persisted session?`,\n\t\t\t\t);\n\t\t\t\tif (!resume || signal.aborted) continue;\n\t\t\t}\n\t\t\tawait resumeDeadOrphan(config, orphan, signal);\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (exactResumedParent) {\n\t\t\tawait adoptLiveOrphan(config, orphan, signal);\n\t\t\tcontinue;\n\t\t}\n\t\tif (!config.hasUI) {\n\t\t\treportOwnerGatedOrphan(config, orphan, recoveryBoundary);\n\t\t\tcontinue;\n\t\t}\n\t\tconst adopt = await config.promptConfirm(\n\t\t\t`adopt worker ${orphan.entryId} (lane ${orphan.agent.resumeContext.worktreeLaneKey ?? \"none\"})?`,\n\t\t);\n\t\tif (signal.aborted) return;\n\t\tif (adopt) {\n\t\t\tawait adoptLiveOrphan(config, orphan, signal);\n\t\t\tcontinue;\n\t\t}\n\t\tconst cleanup = await config.promptConfirm(`clean up worker ${orphan.entryId} gracefully?`);\n\t\tif (!cleanup || signal.aborted) continue;\n\t\tconst windingDown = beginWindDown(orphan, \"user_cleanup\", nowIso(now));\n\t\ttry {\n\t\t\tif (!(await writeEntryIfUnchanged(config.agentDir, orphan.entryId, orphan, windingDown))) {\n\t\t\t\tconfig.onDiagnostic?.(`process-matrix: cleanup skipped because ${orphan.entryId} changed`);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t`process-matrix: failed to write cleanup for ${orphan.entryId}: ${describeError(error)}`,\n\t\t\t);\n\t\t}\n\t}\n}\n\nfunction getAutomaticRecoveryBoundary(\n\tconfig: ProcessMatrixRuntimeConfig,\n\torphan: ProcessMatrixEntry,\n): string | undefined {\n\tif (orphan.parentSessionId !== config.agent.resumeContext.sessionId) return \"foreign parent session\";\n\tconst entryTaskRef = orphan.taskRef;\n\tconst payloadTaskRef = orphan.resumable?.taskRef;\n\tif (entryTaskRef !== undefined && payloadTaskRef !== undefined && entryTaskRef !== payloadTaskRef) {\n\t\treturn \"inconsistent persisted task identity\";\n\t}\n\tif ((payloadTaskRef ?? entryTaskRef) !== config.taskRef) return \"task identity does not match the current goal\";\n\tif (config.allowAutomaticRecovery === false) return \"current goal state does not permit automatic recovery\";\n\treturn undefined;\n}\n\nfunction reportOwnerGatedOrphan(config: ProcessMatrixRuntimeConfig, orphan: ProcessMatrixEntry, reason: string): void {\n\tconfig.onDiagnostic?.(\n\t\t`process-matrix: found owner-gated orphan ${orphan.entryId} (${reason}; report-only, non-interactive; nothing written, nothing killed)`,\n\t);\n}\n\nasync function adoptLiveOrphan(\n\tconfig: ProcessMatrixRuntimeConfig,\n\torphan: ProcessMatrixEntry,\n\tsignal: AbortSignal,\n): Promise<void> {\n\tif (signal.aborted) return;\n\tconst adopted = applyAdoption(orphan, {\n\t\tparentPid: process.pid,\n\t\tparentSessionId: config.agent.resumeContext.sessionId,\n\t});\n\ttry {\n\t\tif (!(await writeEntryIfUnchanged(config.agentDir, orphan.entryId, orphan, adopted))) return;\n\t\tif (signal.aborted) await writeEntryIfUnchanged(config.agentDir, orphan.entryId, adopted, orphan);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: failed to write adoption for ${orphan.entryId}: ${describeError(error)}`);\n\t}\n}\n\nasync function resumeDeadOrphan(\n\tconfig: ProcessMatrixRuntimeConfig,\n\torphan: ProcessMatrixEntry,\n\tsignal: AbortSignal,\n): Promise<void> {\n\tif (signal.aborted) return;\n\tconst payload = orphan.resumable;\n\tif (!payload || !config.resumeWorker) {\n\t\tconfig.onDiagnostic?.(\n\t\t\t`process-matrix: dead worker ${orphan.entryId} is not resumable because its launch context or resume launcher is unavailable`,\n\t\t);\n\t\treturn;\n\t}\n\tconst claimed = applyAdoption(orphan, {\n\t\tparentPid: process.pid,\n\t\tparentSessionId: config.agent.resumeContext.sessionId,\n\t});\n\tlet launched: Extract<ResumeWorkerLaunchOutcome, { started: true }>;\n\ttry {\n\t\tif (!(await writeEntryIfUnchanged(config.agentDir, orphan.entryId, orphan, claimed))) return;\n\t\tif (signal.aborted) {\n\t\t\tawait writeEntryIfUnchanged(config.agentDir, orphan.entryId, claimed, orphan);\n\t\t\treturn;\n\t\t}\n\t\tconst launchOutcome = await config.resumeWorker(payload);\n\t\tif (!launchOutcome.started) {\n\t\t\tawait writeEntryIfUnchanged(config.agentDir, orphan.entryId, claimed, orphan);\n\t\t\tconfig.onDiagnostic?.(`process-matrix: failed to resume ${orphan.entryId}: ${launchOutcome.reason}`);\n\t\t\treturn;\n\t\t}\n\t\tlaunched = launchOutcome;\n\t} catch (error) {\n\t\ttry {\n\t\t\tawait writeEntryIfUnchanged(config.agentDir, orphan.entryId, claimed, orphan);\n\t\t} catch {\n\t\t\t// The original resumable record remains the intended recovery state.\n\t\t}\n\t\tconfig.onDiagnostic?.(`process-matrix: failed to resume ${orphan.entryId}: ${describeError(error)}`);\n\t\treturn;\n\t}\n\tconst launchedEntry = { ...claimed, pid: launched.pid };\n\tif (!signal.aborted) {\n\t\ttry {\n\t\t\t// Bridge the interval before the replacement can self-register. Without its real PID here, a\n\t\t\t// restarted master can mistake this live replacement for the original dead process and spawn\n\t\t\t// a duplicate.\n\t\t\tawait writeEntryIfUnchanged(config.agentDir, claimed.entryId, claimed, launchedEntry);\n\t\t} catch (error) {\n\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t`process-matrix: failed to record resumed worker pid for ${orphan.entryId}: ${describeError(error)}`,\n\t\t\t);\n\t\t}\n\t} else {\n\t\tconfig.onDiagnostic?.(\n\t\t\t`process-matrix: resumed worker ${orphan.entryId} launched after owner shutdown; preserving its terminal handoff only`,\n\t\t);\n\t}\n\tvoid launched.completion.then(\n\t\t(result) => persistResumedWorkerTerminal(config, launchedEntry, claimed, result, signal),\n\t\t(error: unknown) => {\n\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t`process-matrix: resumed agent ${payload.agent.agentId} terminal signal failed: ${describeError(error)}`,\n\t\t\t);\n\t\t},\n\t);\n}\n\nasync function persistResumedWorkerTerminal(\n\tconfig: ProcessMatrixRuntimeConfig,\n\tclaimed: ProcessMatrixEntry,\n\tpreLaunchClaim: ProcessMatrixEntry,\n\tresult: { code: number | null; signal: NodeJS.Signals | null },\n\tlifetime: AbortSignal,\n): Promise<void> {\n\ttry {\n\t\tconst observedAt = new Date().toISOString();\n\t\tconst terminal = markTerminal(claimed, result, observedAt);\n\t\tif (await writeEntryIfUnchanged(config.agentDir, claimed.entryId, claimed, terminal)) {\n\t\t\tif (lifetime.aborted) return;\n\t\t\tawait notifyResumedWorkerTerminal(config, terminal, lifetime);\n\t\t\treturn;\n\t\t}\n\t\tconst selfRegistered = await readEntry(config.agentDir, claimed.entryId);\n\t\tif (selfRegistered?.pid === claimed.pid) {\n\t\t\tconst registeredTerminal = markTerminal(selfRegistered, result, observedAt);\n\t\t\tif (await writeEntryIfUnchanged(config.agentDir, claimed.entryId, selfRegistered, registeredTerminal)) {\n\t\t\t\tif (lifetime.aborted) return;\n\t\t\t\tawait notifyResumedWorkerTerminal(config, registeredTerminal, lifetime);\n\t\t\t\treturn;\n\t\t\t}\n\t\t}\n\t\t// If recording the spawned PID failed (or shutdown won the race immediately after spawn), the\n\t\t// untouched pre-launch claim proves no newer process has taken this logical entry. Upgrade it\n\t\t// to the actual exited process before persisting its terminal handoff.\n\t\tconst fallbackTerminal = markTerminal({ ...preLaunchClaim, pid: claimed.pid }, result, observedAt);\n\t\tif (await writeEntryIfUnchanged(config.agentDir, claimed.entryId, preLaunchClaim, fallbackTerminal)) {\n\t\t\tif (lifetime.aborted) return;\n\t\t\tawait notifyResumedWorkerTerminal(config, fallbackTerminal, lifetime);\n\t\t\treturn;\n\t\t}\n\t\tif (await writeEntryIfUnchanged(config.agentDir, claimed.entryId, undefined, terminal)) {\n\t\t\tif (lifetime.aborted) return;\n\t\t\tawait notifyResumedWorkerTerminal(config, terminal, lifetime);\n\t\t\treturn;\n\t\t}\n\t\tconfig.onDiagnostic?.(`process-matrix: ignored stale terminal handoff for ${claimed.entryId}`);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(\n\t\t\t`process-matrix: failed to persist terminal handoff for ${claimed.entryId}: ${describeError(error)}`,\n\t\t);\n\t}\n}\n\nasync function notifyResumedWorkerTerminal(\n\tconfig: ProcessMatrixRuntimeConfig,\n\tterminal: ProcessMatrixEntry,\n\tlifetime: AbortSignal,\n): Promise<void> {\n\tif (lifetime.aborted) return;\n\ttry {\n\t\tawait config.notify(formatTerminalNotification(terminal));\n\t\tif (lifetime.aborted) return;\n\t\tconst delivered = markTerminalNotificationDelivered(terminal, new Date().toISOString());\n\t\tif (!(await writeEntryIfUnchanged(config.agentDir, terminal.entryId, terminal, delivered))) {\n\t\t\tconfig.onDiagnostic?.(\n\t\t\t\t`process-matrix: terminal handoff changed before acknowledgement for ${terminal.entryId}`,\n\t\t\t);\n\t\t}\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(\n\t\t\t`process-matrix: failed to deliver terminal handoff for ${terminal.entryId}: ${describeError(error)}`,\n\t\t);\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Worker branch\n// ---------------------------------------------------------------------------\n\nasync function startWorkerBranch(\n\tconfig: ProcessMatrixRuntimeConfig,\n\tinitialParentPid: number,\n\tnow: () => number,\n): Promise<ProcessMatrixRuntimeHandle> {\n\tconst parentSessionId = getParentSessionId();\n\tconst taskRef = (getProcessTaskRef() ?? config.taskRef)?.trim().slice(0, 512) || undefined;\n\tconst taskSummary = config.taskSummary?.trim().slice(0, 2_000) || undefined;\n\tconst laneKey = getBoundWorktreeLaneKey();\n\tconst contextLaneKey = config.agent.resumeContext.worktreeLaneKey;\n\tif (laneKey !== contextLaneKey) {\n\t\tthrow new TypeError(\n\t\t\t`Process-matrix agent lane '${contextLaneKey ?? \"none\"}' does not match active lane '${laneKey ?? \"none\"}'.`,\n\t\t);\n\t}\n\n\tlet entry = buildWorkerEntry({\n\t\tagent: config.agent,\n\t\tpid: process.pid,\n\t\thostname: osHostname(),\n\t\tnow: nowIso(now),\n\t\tparentPid: initialParentPid,\n\t\t...(parentSessionId !== undefined ? { parentSessionId } : {}),\n\t\t...(taskRef !== undefined ? { taskRef } : {}),\n\t\t...(taskSummary !== undefined ? { taskSummary } : {}),\n\t});\n\ttry {\n\t\tawait writeEntry(config.agentDir, entry);\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`process-matrix: failed to register worker entry: ${describeError(error)}`);\n\t}\n\n\tlet currentParentPid = initialParentPid;\n\tlet currentParentSessionId = parentSessionId;\n\tlet stopped = false;\n\tlet timer: NodeJS.Timeout | undefined;\n\tlet ticking = false;\n\tlet preserveResumableOnExit = false;\n\tconst closeOnExit = (code: number | null = null): void => {\n\t\tif (preserveResumableOnExit) return;\n\t\ttry {\n\t\t\tconst terminal = markTerminal(entry, { code, signal: null }, nowIso(now));\n\t\t\tif (writeEntryIfUnchangedSync(config.agentDir, entry, terminal)) entry = terminal;\n\t\t} catch {\n\t\t\t// Best-effort. Dead-pid reconciliation remains authoritative.\n\t\t}\n\t};\n\tprocess.once(\"exit\", closeOnExit);\n\n\tconst stop = (): void => {\n\t\tif (stopped) return;\n\t\tstopped = true;\n\t\tif (timer) clearInterval(timer);\n\t\ttimer = undefined;\n\t\tif (!preserveResumableOnExit) closeOnExit();\n\t\tprocess.off(\"exit\", closeOnExit);\n\t};\n\n\tconst persist = async (\n\t\texpected: ProcessMatrixEntry,\n\t\tnext: ProcessMatrixEntry,\n\t\tfailureContext: string,\n\t): Promise<boolean> => {\n\t\ttry {\n\t\t\tif (await writeEntryIfUnchanged(config.agentDir, expected.entryId, expected, next)) {\n\t\t\t\tentry = next;\n\t\t\t\treturn true;\n\t\t\t}\n\t\t\tconst current = await readEntry(config.agentDir, expected.entryId);\n\t\t\tif (current?.pid === process.pid) entry = current;\n\t\t\telse {\n\t\t\t\tstopped = true;\n\t\t\t\tif (timer) clearInterval(timer);\n\t\t\t\ttimer = undefined;\n\t\t\t\tprocess.off(\"exit\", closeOnExit);\n\t\t\t\tconfig.onDiagnostic?.(\"process-matrix: worker entry ownership moved to a newer process generation\");\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tconfig.onDiagnostic?.(`process-matrix: ${failureContext}: ${describeError(error)}`);\n\t\t}\n\t\treturn false;\n\t};\n\n\tconst startHealthyWatch = (): void => {\n\t\ttimer = setInterval(() => {\n\t\t\tif (ticking) return;\n\t\t\tticking = true;\n\t\t\tvoid healthyTick().finally(() => {\n\t\t\t\tticking = false;\n\t\t\t});\n\t\t}, config.settings.watcherPollMs);\n\t\ttimer.unref?.();\n\t};\n\n\tconst declaredParentIsAlive = async (): Promise<boolean> => {\n\t\t// PID liveness alone is not process identity: a reused PID could otherwise keep a worker\n\t\t// attached to an unrelated process forever. The parent session's own fresh master entry binds\n\t\t// PID to a durable identity and proves that that exact session is still heartbeating.\n\t\tif (!currentParentSessionId || !config.isProcessAlive(currentParentPid)) return false;\n\t\tconst parent = await readEntry(config.agentDir, buildEntryId(\"master\", currentParentSessionId));\n\t\tif (!parent || parent.role !== \"master\" || parent.agent.resumeContext.sessionId !== currentParentSessionId)\n\t\t\treturn false;\n\t\tif (parent.pid !== currentParentPid || parent.status !== \"running\") return false;\n\t\tconst heartbeatAt = Date.parse(parent.heartbeatAt);\n\t\tconst maxAge = config.settings.heartbeatMs * 2 + config.settings.watcherPollMs;\n\t\treturn Number.isFinite(heartbeatAt) && now() - heartbeatAt <= maxAge;\n\t};\n\n\tconst healthyTick = async (): Promise<void> => {\n\t\tif (stopped) return;\n\t\tif (!(await declaredParentIsAlive())) {\n\t\t\tawait enterWindDown();\n\t\t\treturn;\n\t\t}\n\t\t// Still healthy: also poll for a master-initiated cooperative-cleanup directive.\n\t\tconst fresh = await readEntry(config.agentDir, entry.entryId);\n\t\tif (!fresh) return;\n\t\tconst directive = pollWorkerDirective(fresh, currentParentPid, { isPidAlive: config.isProcessAlive });\n\t\tif (directive.code !== \"user_cleanup\") return;\n\t\tif (\n\t\t\t!(await persist(\n\t\t\t\tfresh,\n\t\t\t\tbeginWindDown(fresh, \"user_cleanup\", nowIso(now)),\n\t\t\t\t\"failed to write a master-requested worker wind-down\",\n\t\t\t))\n\t\t)\n\t\t\treturn;\n\t\temitRuntimeNotice(config, \"process-matrix: the parent session requested a cooperative cleanup. Winding down.\");\n\t\tstop();\n\t\tconfig.requestExit();\n\t};\n\n\tconst enterWindDown = async (): Promise<void> => {\n\t\tconst windDownAt = nowIso(now);\n\t\tconst expected = entry;\n\t\tconst resumable: ResumablePayload = { lastCode: \"resumable\", agent: structuredClone(config.agent) };\n\t\tif (expected.taskRef !== undefined) resumable.taskRef = expected.taskRef;\n\t\tif (expected.taskSummary !== undefined) resumable.taskSummary = expected.taskSummary;\n\t\tconst woundDown = markResumable(beginWindDown(expected, \"parent_lost\", windDownAt), resumable, windDownAt);\n\t\tif (!(await persist(expected, woundDown, \"failed to write worker wind-down\"))) return;\n\t\tif (timer) clearInterval(timer);\n\t\ttimer = undefined;\n\t\tpreserveResumableOnExit = true;\n\t\temitRuntimeNotice(\n\t\t\tconfig,\n\t\t\t`process-matrix: parent process (pid ${currentParentPid}) is gone. Winding down gracefully; this task is resumable.`,\n\t\t);\n\t\tstartGraceWatch();\n\t};\n\n\tconst startGraceWatch = (): void => {\n\t\tconst graceDeadline = now() + config.settings.adoptionGraceMs;\n\t\ttimer = setInterval(() => {\n\t\t\tif (ticking) return;\n\t\t\tticking = true;\n\t\t\tvoid graceTick(graceDeadline).finally(() => {\n\t\t\t\tticking = false;\n\t\t\t});\n\t\t}, config.settings.watcherPollMs);\n\t\ttimer.unref?.();\n\t};\n\n\tconst graceTick = async (graceDeadline: number): Promise<void> => {\n\t\tif (stopped) return;\n\t\tconst fresh = await readEntry(config.agentDir, entry.entryId);\n\t\tif (fresh) {\n\t\t\tconst directive = pollWorkerDirective(fresh, currentParentPid, { isPidAlive: config.isProcessAlive });\n\t\t\tif (directive.code === \"adopt\" && fresh.parentSessionId) {\n\t\t\t\t// The adopting master persists its session id with the pid. Require both on the next\n\t\t\t\t// healthy tick; accepting a pid-only adoption would reintroduce the PID-reuse bug.\n\t\t\t\tif (\n\t\t\t\t\t!(await persist(\n\t\t\t\t\t\tfresh,\n\t\t\t\t\t\tapplyAdoption(fresh, { parentPid: directive.parentPid, parentSessionId: fresh.parentSessionId }),\n\t\t\t\t\t\t\"failed to write worker adoption\",\n\t\t\t\t\t))\n\t\t\t\t)\n\t\t\t\t\treturn;\n\t\t\t\temitRuntimeNotice(\n\t\t\t\t\tconfig,\n\t\t\t\t\t`process-matrix: adopted by a new parent (pid ${directive.parentPid}). Resuming.`,\n\t\t\t\t);\n\t\t\t\tcurrentParentPid = directive.parentPid;\n\t\t\t\tcurrentParentSessionId = fresh.parentSessionId;\n\t\t\t\tpreserveResumableOnExit = false;\n\t\t\t\tif (timer) {\n\t\t\t\t\tclearInterval(timer);\n\t\t\t\t\ttimer = undefined;\n\t\t\t\t}\n\t\t\t\tstartHealthyWatch();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (directive.code === \"user_cleanup\") {\n\t\t\t\tstop();\n\t\t\t\tconfig.requestExit();\n\t\t\t\treturn;\n\t\t\t}\n\t\t}\n\t\tif (now() >= graceDeadline) {\n\t\t\tstop();\n\t\t\tconfig.requestExit();\n\t\t}\n\t};\n\n\tstartHealthyWatch();\n\n\treturn { stop };\n}\n"]}