@caupulican/pi-adaptative 0.81.38 → 0.81.39

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

@@ -0,0 +1,72 @@
+/**
+ * Process-matrix SSOT for tagged result codes and shared record types.
+ *
+ * Every process-matrix lifecycle transition is expressed as one of the string-literal codes/status
+ * values below -- callers (the runtime, the master orphan scan, the worker watcher) branch on
+ * `code`/`status`, NEVER on a message/substring (the same doctrine as `worktree-sync/codes.ts`).
+ *
+ * The matrix tracks two roles:
+ * - `master`: the top-level interactive/direct session (or the root of a launch chain).
+ * - `worker`: a session launched with a known parent (`PI_PARENT_PID`/`--parent-pid`), e.g. a
+ *   tmux-dispatched agent. A worker knows its parent's pid and winds down gracefully -- never
+ *   silently -- when that parent disappears.
+ */
+export type ProcessRole = "master" | "worker";
+/**
+ * - `running` -- normal operation.
+ * - `winding_down` -- a lifecycle transition is in progress (parent lost, parent shutdown, or a
+ *   cooperative user-requested cleanup); the process is finishing up before exit.
+ * - `resumable` -- wound down leaving a payload describing how to pick the task back up.
+ * - `adopted` -- claimed by a new parent after the original parent was lost (retained by
+ *   `reconcileMatrix` alongside `resumable`, TTL-gated).
+ * - `closed` -- terminal; safe to prune.
+ */
+export type ProcessStatus = "running" | "winding_down" | "resumable" | "adopted" | "closed";
+export type WindDownReason = "parent_lost" | "parent_shutdown" | "user_cleanup";
+/** What a wound-down worker leaves behind so its task can be picked back up. */
+export interface ResumablePayload {
+    laneKey?: string;
+    taskSummary?: string;
+    lastCode: ProcessStatus;
+}
+/** One process-matrix entry: one file under `state/process-matrix/<entryId>.json` (see `store.ts`). */
+export interface ProcessMatrixEntry {
+    entryId: string;
+    role: ProcessRole;
+    pid: number;
+    sessionId: string;
+    hostname: string;
+    startedAt: string;
+    heartbeatAt: string;
+    status: ProcessStatus;
+    /** Worker-only: the pid of the process that launched this one. */
+    parentPid?: number;
+    parentSessionId?: string;
+    laneKey?: string;
+    tmuxSession?: string;
+    tmuxPanePid?: number;
+    taskRef?: string;
+    windDownReason?: WindDownReason;
+    resumable?: ResumablePayload;
+}
+/** What a master decides to do about one orphaned worker during the startup scan. */
+export type CleanupAction = "adopt" | "cleanup" | "leave";
+/**
+ * What a worker learns by re-reading its OWN fresh matrix entry (a master may have written an
+ * adoption or a cooperative-cleanup request into it -- see `docs/process-matrix.md`).
+ */
+export type WorkerDirective = {
+    code: "adopt";
+    parentPid: number;
+} | {
+    code: "user_cleanup";
+} | {
+    code: "none";
+};
+/** Outcome of a `reconcileMatrix` pass: which entries survive and which were pruned, and why. */
+export interface ReconcileMatrixResult {
+    code: "reconciled";
+    kept: ProcessMatrixEntry[];
+    prunedEntryIds: string[];
+}
+//# sourceMappingURL=codes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../../src/core/process-matrix/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5F,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAEhF,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,aAAa,CAAC;CACxB;AAED,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjH,iGAAiG;AACjG,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;CACzB","sourcesContent":["/**\n * Process-matrix SSOT for tagged result codes and shared record types.\n *\n * Every process-matrix lifecycle transition is expressed as one of the string-literal codes/status\n * values below -- callers (the runtime, the master orphan scan, the worker watcher) branch on\n * `code`/`status`, NEVER on a message/substring (the same doctrine as `worktree-sync/codes.ts`).\n *\n * The matrix tracks two roles:\n * - `master`: the top-level interactive/direct session (or the root of a launch chain).\n * - `worker`: a session launched with a known parent (`PI_PARENT_PID`/`--parent-pid`), e.g. a\n *   tmux-dispatched agent. A worker knows its parent's pid and winds down gracefully -- never\n *   silently -- when that parent disappears.\n */\n\nexport type ProcessRole = \"master\" | \"worker\";\n\n/**\n * - `running` -- normal operation.\n * - `winding_down` -- a lifecycle transition is in progress (parent lost, parent shutdown, or a\n *   cooperative user-requested cleanup); the process is finishing up before exit.\n * - `resumable` -- wound down leaving a payload describing how to pick the task back up.\n * - `adopted` -- claimed by a new parent after the original parent was lost (retained by\n *   `reconcileMatrix` alongside `resumable`, TTL-gated).\n * - `closed` -- terminal; safe to prune.\n */\nexport type ProcessStatus = \"running\" | \"winding_down\" | \"resumable\" | \"adopted\" | \"closed\";\n\nexport type WindDownReason = \"parent_lost\" | \"parent_shutdown\" | \"user_cleanup\";\n\n/** What a wound-down worker leaves behind so its task can be picked back up. */\nexport interface ResumablePayload {\n\tlaneKey?: string;\n\ttaskSummary?: string;\n\tlastCode: ProcessStatus;\n}\n\n/** One process-matrix entry: one file under `state/process-matrix/<entryId>.json` (see `store.ts`). */\nexport interface ProcessMatrixEntry {\n\tentryId: string;\n\trole: ProcessRole;\n\tpid: number;\n\tsessionId: string;\n\thostname: string;\n\tstartedAt: string;\n\theartbeatAt: string;\n\tstatus: ProcessStatus;\n\t/** Worker-only: the pid of the process that launched this one. */\n\tparentPid?: number;\n\tparentSessionId?: string;\n\tlaneKey?: string;\n\ttmuxSession?: string;\n\ttmuxPanePid?: number;\n\ttaskRef?: string;\n\twindDownReason?: WindDownReason;\n\tresumable?: ResumablePayload;\n}\n\n/** What a master decides to do about one orphaned worker during the startup scan. */\nexport type CleanupAction = \"adopt\" | \"cleanup\" | \"leave\";\n\n/**\n * What a worker learns by re-reading its OWN fresh matrix entry (a master may have written an\n * adoption or a cooperative-cleanup request into it -- see `docs/process-matrix.md`).\n */\nexport type WorkerDirective = { code: \"adopt\"; parentPid: number } | { code: \"user_cleanup\" } | { code: \"none\" };\n\n/** Outcome of a `reconcileMatrix` pass: which entries survive and which were pruned, and why. */\nexport interface ReconcileMatrixResult {\n\tcode: \"reconciled\";\n\tkept: ProcessMatrixEntry[];\n\tprunedEntryIds: string[];\n}\n"]}

package/dist/core/process-matrix/codes.js

@@ -0,0 +1,15 @@
+/**
+ * Process-matrix SSOT for tagged result codes and shared record types.
+ *
+ * Every process-matrix lifecycle transition is expressed as one of the string-literal codes/status
+ * values below -- callers (the runtime, the master orphan scan, the worker watcher) branch on
+ * `code`/`status`, NEVER on a message/substring (the same doctrine as `worktree-sync/codes.ts`).
+ *
+ * The matrix tracks two roles:
+ * - `master`: the top-level interactive/direct session (or the root of a launch chain).
+ * - `worker`: a session launched with a known parent (`PI_PARENT_PID`/`--parent-pid`), e.g. a
+ *   tmux-dispatched agent. A worker knows its parent's pid and winds down gracefully -- never
+ *   silently -- when that parent disappears.
+ */
+export {};
+//# sourceMappingURL=codes.js.map

package/dist/core/process-matrix/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../../src/core/process-matrix/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG","sourcesContent":["/**\n * Process-matrix SSOT for tagged result codes and shared record types.\n *\n * Every process-matrix lifecycle transition is expressed as one of the string-literal codes/status\n * values below -- callers (the runtime, the master orphan scan, the worker watcher) branch on\n * `code`/`status`, NEVER on a message/substring (the same doctrine as `worktree-sync/codes.ts`).\n *\n * The matrix tracks two roles:\n * - `master`: the top-level interactive/direct session (or the root of a launch chain).\n * - `worker`: a session launched with a known parent (`PI_PARENT_PID`/`--parent-pid`), e.g. a\n *   tmux-dispatched agent. A worker knows its parent's pid and winds down gracefully -- never\n *   silently -- when that parent disappears.\n */\n\nexport type ProcessRole = \"master\" | \"worker\";\n\n/**\n * - `running` -- normal operation.\n * - `winding_down` -- a lifecycle transition is in progress (parent lost, parent shutdown, or a\n *   cooperative user-requested cleanup); the process is finishing up before exit.\n * - `resumable` -- wound down leaving a payload describing how to pick the task back up.\n * - `adopted` -- claimed by a new parent after the original parent was lost (retained by\n *   `reconcileMatrix` alongside `resumable`, TTL-gated).\n * - `closed` -- terminal; safe to prune.\n */\nexport type ProcessStatus = \"running\" | \"winding_down\" | \"resumable\" | \"adopted\" | \"closed\";\n\nexport type WindDownReason = \"parent_lost\" | \"parent_shutdown\" | \"user_cleanup\";\n\n/** What a wound-down worker leaves behind so its task can be picked back up. */\nexport interface ResumablePayload {\n\tlaneKey?: string;\n\ttaskSummary?: string;\n\tlastCode: ProcessStatus;\n}\n\n/** One process-matrix entry: one file under `state/process-matrix/<entryId>.json` (see `store.ts`). */\nexport interface ProcessMatrixEntry {\n\tentryId: string;\n\trole: ProcessRole;\n\tpid: number;\n\tsessionId: string;\n\thostname: string;\n\tstartedAt: string;\n\theartbeatAt: string;\n\tstatus: ProcessStatus;\n\t/** Worker-only: the pid of the process that launched this one. */\n\tparentPid?: number;\n\tparentSessionId?: string;\n\tlaneKey?: string;\n\ttmuxSession?: string;\n\ttmuxPanePid?: number;\n\ttaskRef?: string;\n\twindDownReason?: WindDownReason;\n\tresumable?: ResumablePayload;\n}\n\n/** What a master decides to do about one orphaned worker during the startup scan. */\nexport type CleanupAction = \"adopt\" | \"cleanup\" | \"leave\";\n\n/**\n * What a worker learns by re-reading its OWN fresh matrix entry (a master may have written an\n * adoption or a cooperative-cleanup request into it -- see `docs/process-matrix.md`).\n */\nexport type WorkerDirective = { code: \"adopt\"; parentPid: number } | { code: \"user_cleanup\" } | { code: \"none\" };\n\n/** Outcome of a `reconcileMatrix` pass: which entries survive and which were pruned, and why. */\nexport interface ReconcileMatrixResult {\n\tcode: \"reconciled\";\n\tkept: ProcessMatrixEntry[];\n\tprunedEntryIds: string[];\n}\n"]}

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

@@ -0,0 +1,63 @@
+/**
+ * Process-matrix runtime composition: the pieces main.ts wires together for durable,
+ * restart-surviving master/worker process supervision.
+ *
+ * Contract:
+ * - A WORKER is any process launched with a known parent (`PI_PARENT_PID` -- set by the
+ *   `--parent-pid` CLI flag, or directly by a launcher such as tmux dispatch). It self-registers
+ *   its OWN entry (the single writer of that entry during normal operation) and watches its
+ *   parent's liveness. On parent death it winds down GRACEFULLY -- never silently -- leaving a
+ *   `resumable` payload, then exits on its own after a bounded grace window (during which it may
+ *   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.
+ *
+ * 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.
+ */
+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;
+export interface ProcessMatrixRuntimeConfig {
+    agentDir: string;
+    sessionId: string;
+    /** 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;
+    /** 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. */
+    promptConfirm: (message: string) => Promise<boolean>;
+    /** 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;
+}
+export interface ProcessMatrixRuntimeHandle {
+    stop(): void;
+}
+/**
+ * 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
+ * crash.
+ */
+export declare function startProcessMatrixRuntime(config: ProcessMatrixRuntimeConfig): Promise<ProcessMatrixRuntimeHandle>;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +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"]}

package/dist/core/process-matrix/runtime.js

@@ -0,0 +1,310 @@
+/**
+ * Process-matrix runtime composition: the pieces main.ts wires together for durable,
+ * restart-surviving master/worker process supervision.
+ *
+ * Contract:
+ * - A WORKER is any process launched with a known parent (`PI_PARENT_PID` -- set by the
+ *   `--parent-pid` CLI flag, or directly by a launcher such as tmux dispatch). It self-registers
+ *   its OWN entry (the single writer of that entry during normal operation) and watches its
+ *   parent's liveness. On parent death it winds down GRACEFULLY -- never silently -- leaving a
+ *   `resumable` payload, then exits on its own after a bounded grace window (during which it may
+ *   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.
+ *
+ * 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.
+ */
+import { hostname as osHostname } from "node:os";
+import { getBoundWorktreeLaneKey } from "../worktree-sync/runtime.js";
+import { buildEntryId, listEntries, readEntry, writeEntry, writeEntrySync } from "./store.js";
+import { applyAdoption, applyHeartbeat, beginWindDown, buildMasterEntry, buildWorkerEntry, detectOrphanedWorkers, markClosed, markResumable, pollWorkerDirective, } from "./supervisor.js";
+export const PI_PARENT_PID_ENV = "PI_PARENT_PID";
+export 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 function getParentPid(env = process.env) {
+    const raw = env[PI_PARENT_PID_ENV];
+    if (raw === undefined)
+        return undefined;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/** This process's declared parent sessionId, from the cross-process env contract. */
+export function getParentSessionId(env = process.env) {
+    const value = env[PI_PARENT_SESSION_ENV]?.trim();
+    return value && value.length > 0 ? value : undefined;
+}
+const NOOP_HANDLE = { stop: () => { } };
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function nowIso(now) {
+    return new Date(now()).toISOString();
+}
+/**
+ * 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
+ * crash.
+ */
+export async function startProcessMatrixRuntime(config) {
+    if (!config.settings.enabled)
+        return NOOP_HANDLE;
+    const now = config.now ?? Date.now;
+    const parentPid = getParentPid();
+    try {
+        if (parentPid !== undefined) {
+            return await startWorkerBranch(config, parentPid, now);
+        }
+        return await startMasterBranch(config, now);
+    }
+    catch (error) {
+        config.onDiagnostic?.(`process-matrix: runtime failed to start: ${describeError(error)}`);
+        return NOOP_HANDLE;
+    }
+}
+// ---------------------------------------------------------------------------
+// Master branch
+// ---------------------------------------------------------------------------
+async function startMasterBranch(config, now) {
+    let entry = buildMasterEntry({
+        sessionId: config.sessionId,
+        pid: process.pid,
+        hostname: osHostname(),
+        now: nowIso(now),
+    });
+    try {
+        await writeEntry(config.agentDir, entry);
+    }
+    catch (error) {
+        config.onDiagnostic?.(`process-matrix: failed to register master entry: ${describeError(error)}`);
+    }
+    let stopped = false;
+    const heartbeatTimer = setInterval(() => {
+        if (stopped)
+            return;
+        entry = applyHeartbeat(entry, nowIso(now));
+        void writeEntry(config.agentDir, entry).catch((error) => {
+            config.onDiagnostic?.(`process-matrix: failed to write master heartbeat: ${describeError(error)}`);
+        });
+    }, config.settings.heartbeatMs);
+    heartbeatTimer.unref?.();
+    // Best-effort close on process exit. A SIGKILLed master leaving "running" is fine -- reconcile's
+    // own dead-pid detection covers it; this only makes the common clean-exit case tidy.
+    process.on("exit", () => {
+        try {
+            writeEntrySync(config.agentDir, markClosed(entry, nowIso(now)));
+        }
+        catch {
+            // Best-effort only -- see module doc.
+        }
+    });
+    void runOrphanScan(config, now);
+    return {
+        stop() {
+            stopped = true;
+            clearInterval(heartbeatTimer);
+        },
+    };
+}
+async function runOrphanScan(config, now) {
+    let entries;
+    try {
+        entries = await listEntries(config.agentDir);
+    }
+    catch (error) {
+        config.onDiagnostic?.(`process-matrix: orphan scan failed to list entries: ${describeError(error)}`);
+        return;
+    }
+    const orphans = detectOrphanedWorkers(entries, {
+        isPidAlive: config.isProcessAlive,
+        ownSessionId: config.sessionId,
+    });
+    if (orphans.length === 0)
+        return;
+    if (!config.hasUI) {
+        config.onDiagnostic?.(`process-matrix: found ${orphans.length} orphaned worker(s) with no reachable parent (report-only, non-interactive; nothing written, nothing killed): ${orphans
+            .map((orphan) => orphan.entryId)
+            .join(", ")}`);
+        return;
+    }
+    for (const orphan of orphans) {
+        const adopt = await config.promptConfirm(`adopt worker ${orphan.entryId} (lane ${orphan.laneKey ?? "none"})?`);
+        if (adopt) {
+            const adopted = applyAdoption(orphan, { parentPid: process.pid, parentSessionId: config.sessionId });
+            try {
+                await writeEntry(config.agentDir, adopted);
+            }
+            catch (error) {
+                config.onDiagnostic?.(`process-matrix: failed to write adoption for ${orphan.entryId}: ${describeError(error)}`);
+            }
+            continue;
+        }
+        const cleanup = await config.promptConfirm(`clean up worker ${orphan.entryId} gracefully?`);
+        if (!cleanup)
+            continue;
+        const windingDown = beginWindDown(orphan, "user_cleanup", nowIso(now));
+        try {
+            await writeEntry(config.agentDir, windingDown);
+        }
+        catch (error) {
+            config.onDiagnostic?.(`process-matrix: failed to write cleanup for ${orphan.entryId}: ${describeError(error)}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Worker branch
+// ---------------------------------------------------------------------------
+async function startWorkerBranch(config, initialParentPid, now) {
+    const parentSessionId = getParentSessionId();
+    const laneKey = getBoundWorktreeLaneKey();
+    let entry = buildWorkerEntry({
+        sessionId: config.sessionId,
+        pid: process.pid,
+        hostname: osHostname(),
+        now: nowIso(now),
+        parentPid: initialParentPid,
+        ...(parentSessionId !== undefined ? { parentSessionId } : {}),
+        ...(laneKey !== undefined ? { laneKey } : {}),
+    });
+    try {
+        await writeEntry(config.agentDir, entry);
+    }
+    catch (error) {
+        config.onDiagnostic?.(`process-matrix: failed to register worker entry: ${describeError(error)}`);
+    }
+    let currentParentPid = initialParentPid;
+    let currentParentSessionId = parentSessionId;
+    let stopped = false;
+    let timer;
+    let ticking = false;
+    const stop = () => {
+        stopped = true;
+        if (timer)
+            clearInterval(timer);
+        timer = undefined;
+    };
+    const persist = async (next, failureContext) => {
+        entry = next;
+        try {
+            await writeEntry(config.agentDir, entry);
+        }
+        catch (error) {
+            config.onDiagnostic?.(`process-matrix: ${failureContext}: ${describeError(error)}`);
+        }
+    };
+    const startHealthyWatch = () => {
+        timer = setInterval(() => {
+            if (ticking)
+                return;
+            ticking = true;
+            void healthyTick().finally(() => {
+                ticking = false;
+            });
+        }, config.settings.watcherPollMs);
+        timer.unref?.();
+    };
+    const declaredParentIsAlive = async () => {
+        // PID liveness alone is not process identity: a reused PID could otherwise keep a worker
+        // attached to an unrelated process forever. The parent session's own fresh master entry binds
+        // PID to a durable identity and proves that that exact session is still heartbeating.
+        if (!currentParentSessionId || !config.isProcessAlive(currentParentPid))
+            return false;
+        const parent = await readEntry(config.agentDir, buildEntryId("master", currentParentSessionId));
+        if (!parent || parent.role !== "master" || parent.sessionId !== currentParentSessionId)
+            return false;
+        if (parent.pid !== currentParentPid || parent.status !== "running")
+            return false;
+        const heartbeatAt = Date.parse(parent.heartbeatAt);
+        const maxAge = config.settings.heartbeatMs * 2 + config.settings.watcherPollMs;
+        return Number.isFinite(heartbeatAt) && now() - heartbeatAt <= maxAge;
+    };
+    const healthyTick = async () => {
+        if (stopped)
+            return;
+        if (!(await declaredParentIsAlive())) {
+            await enterWindDown();
+            return;
+        }
+        // Still healthy: also poll for a master-initiated cooperative-cleanup directive.
+        const fresh = await readEntry(config.agentDir, entry.entryId);
+        if (!fresh)
+            return;
+        const directive = pollWorkerDirective(fresh, currentParentPid, { isPidAlive: config.isProcessAlive });
+        if (directive.code !== "user_cleanup")
+            return;
+        await persist(beginWindDown(fresh, "user_cleanup", nowIso(now)), "failed to write a master-requested worker wind-down");
+        config.notify("process-matrix: the parent session requested a cooperative cleanup. Winding down.");
+        stop();
+        config.requestExit();
+    };
+    const enterWindDown = async () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+        const windDownAt = nowIso(now);
+        const resumable = { lastCode: "resumable" };
+        if (laneKey !== undefined)
+            resumable.laneKey = laneKey;
+        await persist(markResumable(beginWindDown(entry, "parent_lost", windDownAt), resumable, windDownAt), "failed to write worker wind-down");
+        config.notify(`process-matrix: parent process (pid ${currentParentPid}) is gone. Winding down gracefully; this task is resumable.`);
+        startGraceWatch();
+    };
+    const startGraceWatch = () => {
+        const graceDeadline = now() + config.settings.adoptionGraceMs;
+        timer = setInterval(() => {
+            if (ticking)
+                return;
+            ticking = true;
+            void graceTick(graceDeadline).finally(() => {
+                ticking = false;
+            });
+        }, config.settings.watcherPollMs);
+        timer.unref?.();
+    };
+    const graceTick = async (graceDeadline) => {
+        if (stopped)
+            return;
+        const fresh = await readEntry(config.agentDir, entry.entryId);
+        if (fresh) {
+            const directive = pollWorkerDirective(fresh, currentParentPid, { isPidAlive: config.isProcessAlive });
+            if (directive.code === "adopt" && fresh.parentSessionId) {
+                // The adopting master persists its session id with the pid. Require both on the next
+                // healthy tick; accepting a pid-only adoption would reintroduce the PID-reuse bug.
+                await persist(applyAdoption(fresh, { parentPid: directive.parentPid, parentSessionId: fresh.parentSessionId }), "failed to write worker adoption");
+                config.notify(`process-matrix: adopted by a new parent (pid ${directive.parentPid}). Resuming.`);
+                currentParentPid = directive.parentPid;
+                currentParentSessionId = fresh.parentSessionId;
+                if (timer) {
+                    clearInterval(timer);
+                    timer = undefined;
+                }
+                startHealthyWatch();
+                return;
+            }
+            if (directive.code === "user_cleanup") {
+                stop();
+                config.requestExit();
+                return;
+            }
+        }
+        if (now() >= graceDeadline) {
+            stop();
+            config.requestExit();
+        }
+    };
+    startHealthyWatch();
+    return { stop };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/core/process-matrix/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/core/process-matrix/runtime.ts"],"names":[],"mappings":"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","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"]}

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

@@ -0,0 +1,22 @@
+/**
+ * Process-matrix on-disk store: one file per process (`state/process-matrix/<entryId>.json`),
+ * durable across restarts and crashes (see `agent-paths.ts` -- this is machine state, not
+ * transient `work/`).
+ *
+ * Each entry is owned by the process it describes: a master writes and heartbeats its OWN entry,
+ * a worker self-registers and heartbeats its OWN entry (see `runtime.ts`'s module doc for the one
+ * sanctioned, ask-gated exception during orphan adoption/cleanup). A missing or corrupt entry file
+ * reads as absent -- never an error -- matching `worktree-sync/store.ts`'s store doctrine.
+ */
+import type { ProcessMatrixEntry, ProcessRole } from "./codes.ts";
+export declare function processMatrixDir(agentDir: string): string;
+export declare function entryPath(agentDir: string, entryId: string): string;
+/** Stable entry identity: one entry per (role, sessionId) pair. */
+export declare function buildEntryId(role: ProcessRole, sessionId: string): string;
+export declare function readEntry(agentDir: string, entryId: string): Promise<ProcessMatrixEntry | undefined>;
+export declare function listEntries(agentDir: string): Promise<ProcessMatrixEntry[]>;
+export declare function writeEntry(agentDir: string, entry: ProcessMatrixEntry): Promise<void>;
+/** Sync counterpart for the `process.on("exit")` best-effort master close -- see `runtime.ts`. */
+export declare function writeEntrySync(agentDir: string, entry: ProcessMatrixEntry): void;
+export declare function removeEntry(agentDir: string, entryId: string): Promise<void>;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/core/process-matrix/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAElE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzE;AAiBD,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAE1G;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAcjF;AAMD,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3F;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAEhF;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMlF","sourcesContent":["/**\n * Process-matrix on-disk store: one file per process (`state/process-matrix/<entryId>.json`),\n * durable across restarts and crashes (see `agent-paths.ts` -- this is machine state, not\n * transient `work/`).\n *\n * Each entry is owned by the process it describes: a master writes and heartbeats its OWN entry,\n * a worker self-registers and heartbeats its OWN entry (see `runtime.ts`'s module doc for the one\n * sanctioned, ask-gated exception during orphan adoption/cleanup). A missing or corrupt entry file\n * reads as absent -- never an error -- matching `worktree-sync/store.ts`'s store doctrine.\n */\n\nimport { promises as fsPromises } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { stateFile } from \"../agent-paths.ts\";\nimport { writeFileAtomic, writeFileAtomicSync } from \"../util/atomic-file.ts\";\nimport type { ProcessMatrixEntry, ProcessRole } from \"./codes.ts\";\n\nexport function processMatrixDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"process-matrix\");\n}\n\nexport function entryPath(agentDir: string, entryId: string): string {\n\treturn join(processMatrixDir(agentDir), `${entryId}.json`);\n}\n\n/** Stable entry identity: one entry per (role, sessionId) pair. */\nexport function buildEntryId(role: ProcessRole, sessionId: string): string {\n\treturn `${role}-${sessionId}`;\n}\n\nasync function readJsonFile<T>(filePath: string): Promise<T | undefined> {\n\tlet raw: string;\n\ttry {\n\t\traw = await fsPromises.readFile(filePath, \"utf-8\");\n\t} catch {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\treturn JSON.parse(raw) as T;\n\t} catch {\n\t\t// Corrupt entry files are treated as absent -- reconcile/re-registration rebuilds them.\n\t\treturn undefined;\n\t}\n}\n\nexport async function readEntry(agentDir: string, entryId: string): Promise<ProcessMatrixEntry | undefined> {\n\treturn readJsonFile<ProcessMatrixEntry>(entryPath(agentDir, entryId));\n}\n\nexport async function listEntries(agentDir: string): Promise<ProcessMatrixEntry[]> {\n\tlet names: string[];\n\ttry {\n\t\tnames = await fsPromises.readdir(processMatrixDir(agentDir));\n\t} catch {\n\t\treturn [];\n\t}\n\tconst entries: ProcessMatrixEntry[] = [];\n\tfor (const name of names.sort()) {\n\t\tif (!name.endsWith(\".json\")) continue;\n\t\tconst entry = await readJsonFile<ProcessMatrixEntry>(join(processMatrixDir(agentDir), name));\n\t\tif (entry?.entryId) entries.push(entry);\n\t}\n\treturn entries;\n}\n\nfunction serialize(entry: ProcessMatrixEntry): string {\n\treturn `${JSON.stringify(entry, null, \"\\t\")}\\n`;\n}\n\nexport async function writeEntry(agentDir: string, entry: ProcessMatrixEntry): Promise<void> {\n\tawait writeFileAtomic(entryPath(agentDir, entry.entryId), serialize(entry));\n}\n\n/** Sync counterpart for the `process.on(\"exit\")` best-effort master close -- see `runtime.ts`. */\nexport function writeEntrySync(agentDir: string, entry: ProcessMatrixEntry): void {\n\twriteFileAtomicSync(entryPath(agentDir, entry.entryId), serialize(entry));\n}\n\nexport async function removeEntry(agentDir: string, entryId: string): Promise<void> {\n\ttry {\n\t\tawait fsPromises.rm(entryPath(agentDir, entryId), { force: true });\n\t} catch {\n\t\t// Best-effort; a missing file is already the desired end state.\n\t}\n}\n"]}