@caupulican/pi-adaptative 0.81.39 → 0.81.41

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

@@ -11,47 +11,42 @@
  *   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 { hostname as osHostname } from "node:os";
+import { isAgentIdentity } from "../orchestration/agent-resume.js";
+import { getParentPid, getParentSessionId, getProcessTaskRef } from "../process-identity.js";
 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;
-}
+import { buildEntryId, listEntries, readEntry, removeEntryIfUnchanged, writeEntry, writeEntryIfUnchanged, writeEntryIfUnchangedSync, } from "./store.js";
+import { applyAdoption, applyHeartbeat, beginWindDown, buildMasterEntry, buildWorkerEntry, detectOrphanedWorkers, markClosed, markResumable, markTerminal, markTerminalNotificationDelivered, pollWorkerDirective, reconcileMatrix, } from "./supervisor.js";
+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.js";
 const NOOP_HANDLE = { stop: () => { } };
+export const PROCESS_MATRIX_RESUMABLE_RETENTION_MS = 30 * 24 * 60 * 60_000;
 function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function nowIso(now) {
     return new Date(now()).toISOString();
 }
+function emitRuntimeNotice(config, text) {
+    try {
+        void Promise.resolve(config.notify(text)).catch((error) => {
+            config.onDiagnostic?.(`process-matrix: failed to notify session: ${describeError(error)}`);
+        });
+    }
+    catch (error) {
+        config.onDiagnostic?.(`process-matrix: failed to notify session: ${describeError(error)}`);
+    }
+}
 /**
  * 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
@@ -63,6 +58,8 @@ export async function startProcessMatrixRuntime(config) {
     const now = config.now ?? Date.now;
     const parentPid = getParentPid();
     try {
+        if (!isAgentIdentity(config.agent))
+            throw new TypeError("Process-matrix agent identity is invalid.");
         if (parentPid !== undefined) {
             return await startWorkerBranch(config, parentPid, now);
         }
@@ -78,7 +75,7 @@ export async function startProcessMatrixRuntime(config) {
 // ---------------------------------------------------------------------------
 async function startMasterBranch(config, now) {
     let entry = buildMasterEntry({
-        sessionId: config.sessionId,
+        agent: config.agent,
         pid: process.pid,
         hostname: osHostname(),
         now: nowIso(now),
@@ -90,92 +87,377 @@ async function startMasterBranch(config, now) {
         config.onDiagnostic?.(`process-matrix: failed to register master entry: ${describeError(error)}`);
     }
     let stopped = false;
+    let ownsEntry = true;
+    let heartbeatTask;
+    const lifetime = new AbortController();
     const heartbeatTimer = setInterval(() => {
-        if (stopped)
+        if (stopped || !ownsEntry || heartbeatTask)
             return;
-        entry = applyHeartbeat(entry, nowIso(now));
-        void writeEntry(config.agentDir, entry).catch((error) => {
+        const expected = entry;
+        const next = applyHeartbeat(expected, nowIso(now));
+        heartbeatTask = writeEntryIfUnchanged(config.agentDir, expected.entryId, expected, next)
+            .then((written) => {
+            if (written) {
+                entry = next;
+                return;
+            }
+            ownsEntry = false;
+            lifetime.abort();
+            clearInterval(heartbeatTimer);
+            process.off("exit", closeOnExit);
+            config.onDiagnostic?.("process-matrix: master entry ownership moved to a newer process generation");
+        })
+            .catch((error) => {
             config.onDiagnostic?.(`process-matrix: failed to write master heartbeat: ${describeError(error)}`);
+        })
+            .finally(() => {
+            heartbeatTask = undefined;
         });
     }, 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", () => {
+    const closeOnExit = () => {
+        if (!ownsEntry)
+            return;
         try {
-            writeEntrySync(config.agentDir, markClosed(entry, nowIso(now)));
+            const closed = markClosed(entry, nowIso(now));
+            if (writeEntryIfUnchangedSync(config.agentDir, entry, closed))
+                entry = closed;
         }
         catch {
             // Best-effort only -- see module doc.
         }
+    };
+    process.once("exit", closeOnExit);
+    const maintenance = reconcileAndRunOrphanScan(config, now, lifetime.signal).catch((error) => {
+        config.onDiagnostic?.(`process-matrix: maintenance failed: ${describeError(error)}`);
     });
-    void runOrphanScan(config, now);
     return {
-        stop() {
+        async stop() {
+            if (stopped)
+                return;
             stopped = true;
+            lifetime.abort();
             clearInterval(heartbeatTimer);
+            process.off("exit", closeOnExit);
+            await heartbeatTask;
+            if (ownsEntry) {
+                const closed = markClosed(entry, nowIso(now));
+                if (await writeEntryIfUnchanged(config.agentDir, entry.entryId, entry, closed))
+                    entry = closed;
+            }
+            await maintenance;
         },
     };
 }
-async function runOrphanScan(config, now) {
+async function reconcileAndRunOrphanScan(config, now, signal) {
     let entries;
     try {
         entries = await listEntries(config.agentDir);
     }
     catch (error) {
-        config.onDiagnostic?.(`process-matrix: orphan scan failed to list entries: ${describeError(error)}`);
+        config.onDiagnostic?.(`process-matrix: reconciliation failed to list entries: ${describeError(error)}`);
+        return;
+    }
+    if (signal.aborted)
+        return;
+    const reconciled = reconcileMatrix(entries, {
+        isPidAlive: (pid) => pid === process.pid || config.isProcessAlive(pid),
+        now: now(),
+        resumableTtlMs: PROCESS_MATRIX_RESUMABLE_RETENTION_MS,
+    });
+    const originalByEntryId = new Map(entries.map((entry) => [entry.entryId, entry]));
+    const recoveredEntryIdSet = new Set(reconciled.recoveredEntryIds);
+    const [prunedOutcomes, recoveredOutcomes] = await Promise.all([
+        Promise.all(reconciled.prunedEntryIds.map((entryId) => {
+            const original = originalByEntryId.get(entryId);
+            return original ? removeEntryIfUnchanged(config.agentDir, original) : false;
+        })),
+        Promise.all(reconciled.kept
+            .filter((entry) => recoveredEntryIdSet.has(entry.entryId))
+            .map((entry) => {
+            const original = originalByEntryId.get(entry.entryId);
+            return original ? writeEntryIfUnchanged(config.agentDir, entry.entryId, original, entry) : false;
+        })),
+    ]);
+    if (signal.aborted)
         return;
+    const recoveredCount = recoveredOutcomes.filter(Boolean).length;
+    const prunedCount = prunedOutcomes.filter(Boolean).length;
+    if (recoveredCount > 0) {
+        config.onDiagnostic?.(`process-matrix: recovered ${recoveredCount} interrupted Pi worker entr${recoveredCount === 1 ? "y" : "ies"}`);
+    }
+    if (prunedCount > 0) {
+        config.onDiagnostic?.(`process-matrix: pruned ${prunedCount} terminal or expired entr${prunedCount === 1 ? "y" : "ies"}`);
+    }
+    const currentEntries = await listEntries(config.agentDir);
+    await deliverTerminalNotifications(config, currentEntries, now, signal);
+    if (signal.aborted)
+        return;
+    await runOrphanScan(config, currentEntries, now, signal);
+}
+async function deliverTerminalNotifications(config, entries, now, signal) {
+    for (const entry of entries) {
+        if (signal.aborted ||
+            entry.status !== "closed" ||
+            !entry.terminal ||
+            entry.terminal.notificationDeliveredAt ||
+            entry.parentSessionId !== config.agent.resumeContext.sessionId)
+            continue;
+        try {
+            await config.notify(formatTerminalNotification(entry));
+            if (signal.aborted)
+                return;
+        }
+        catch (error) {
+            config.onDiagnostic?.(`process-matrix: failed to deliver terminal handoff for ${entry.entryId}: ${describeError(error)}`);
+            continue;
+        }
+        try {
+            const delivered = markTerminalNotificationDelivered(entry, nowIso(now));
+            if (!(await writeEntryIfUnchanged(config.agentDir, entry.entryId, entry, delivered))) {
+                config.onDiagnostic?.(`process-matrix: terminal handoff changed before acknowledgement for ${entry.entryId}`);
+            }
+        }
+        catch (error) {
+            config.onDiagnostic?.(`process-matrix: failed to acknowledge terminal handoff for ${entry.entryId}: ${describeError(error)}`);
+        }
     }
+}
+function formatTerminalNotification(entry) {
+    const terminal = entry.terminal;
+    return `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.`;
+}
+async function runOrphanScan(config, entries, now, signal) {
     const orphans = detectOrphanedWorkers(entries, {
         isPidAlive: config.isProcessAlive,
-        ownSessionId: config.sessionId,
+        ownSessionId: config.agent.resumeContext.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)}`);
+        if (signal.aborted)
+            return;
+        const recoveryBoundary = getAutomaticRecoveryBoundary(config, orphan);
+        const exactResumedParent = recoveryBoundary === undefined;
+        if (!config.isProcessAlive(orphan.pid)) {
+            if (!exactResumedParent) {
+                if (!config.hasUI) {
+                    reportOwnerGatedOrphan(config, orphan, recoveryBoundary);
+                    continue;
+                }
+                const payload = orphan.resumable;
+                if (!payload) {
+                    config.onDiagnostic?.(`process-matrix: dead worker ${orphan.entryId} is not resumable because its launch context is unavailable`);
+                    continue;
+                }
+                const resume = await config.promptConfirm(`resume agent ${payload.agent.agentId} from its persisted session?`);
+                if (!resume || signal.aborted)
+                    continue;
             }
+            await resumeDeadOrphan(config, orphan, signal);
+            continue;
+        }
+        if (exactResumedParent) {
+            await adoptLiveOrphan(config, orphan, signal);
+            continue;
+        }
+        if (!config.hasUI) {
+            reportOwnerGatedOrphan(config, orphan, recoveryBoundary);
+            continue;
+        }
+        const adopt = await config.promptConfirm(`adopt worker ${orphan.entryId} (lane ${orphan.agent.resumeContext.worktreeLaneKey ?? "none"})?`);
+        if (signal.aborted)
+            return;
+        if (adopt) {
+            await adoptLiveOrphan(config, orphan, signal);
             continue;
         }
         const cleanup = await config.promptConfirm(`clean up worker ${orphan.entryId} gracefully?`);
-        if (!cleanup)
+        if (!cleanup || signal.aborted)
             continue;
         const windingDown = beginWindDown(orphan, "user_cleanup", nowIso(now));
         try {
-            await writeEntry(config.agentDir, windingDown);
+            if (!(await writeEntryIfUnchanged(config.agentDir, orphan.entryId, orphan, windingDown))) {
+                config.onDiagnostic?.(`process-matrix: cleanup skipped because ${orphan.entryId} changed`);
+            }
         }
         catch (error) {
             config.onDiagnostic?.(`process-matrix: failed to write cleanup for ${orphan.entryId}: ${describeError(error)}`);
         }
     }
 }
+function getAutomaticRecoveryBoundary(config, orphan) {
+    if (orphan.parentSessionId !== config.agent.resumeContext.sessionId)
+        return "foreign parent session";
+    const entryTaskRef = orphan.taskRef;
+    const payloadTaskRef = orphan.resumable?.taskRef;
+    if (entryTaskRef !== undefined && payloadTaskRef !== undefined && entryTaskRef !== payloadTaskRef) {
+        return "inconsistent persisted task identity";
+    }
+    if ((payloadTaskRef ?? entryTaskRef) !== config.taskRef)
+        return "task identity does not match the current goal";
+    if (config.allowAutomaticRecovery === false)
+        return "current goal state does not permit automatic recovery";
+    return undefined;
+}
+function reportOwnerGatedOrphan(config, orphan, reason) {
+    config.onDiagnostic?.(`process-matrix: found owner-gated orphan ${orphan.entryId} (${reason}; report-only, non-interactive; nothing written, nothing killed)`);
+}
+async function adoptLiveOrphan(config, orphan, signal) {
+    if (signal.aborted)
+        return;
+    const adopted = applyAdoption(orphan, {
+        parentPid: process.pid,
+        parentSessionId: config.agent.resumeContext.sessionId,
+    });
+    try {
+        if (!(await writeEntryIfUnchanged(config.agentDir, orphan.entryId, orphan, adopted)))
+            return;
+        if (signal.aborted)
+            await writeEntryIfUnchanged(config.agentDir, orphan.entryId, adopted, orphan);
+    }
+    catch (error) {
+        config.onDiagnostic?.(`process-matrix: failed to write adoption for ${orphan.entryId}: ${describeError(error)}`);
+    }
+}
+async function resumeDeadOrphan(config, orphan, signal) {
+    if (signal.aborted)
+        return;
+    const payload = orphan.resumable;
+    if (!payload || !config.resumeWorker) {
+        config.onDiagnostic?.(`process-matrix: dead worker ${orphan.entryId} is not resumable because its launch context or resume launcher is unavailable`);
+        return;
+    }
+    const claimed = applyAdoption(orphan, {
+        parentPid: process.pid,
+        parentSessionId: config.agent.resumeContext.sessionId,
+    });
+    let launched;
+    try {
+        if (!(await writeEntryIfUnchanged(config.agentDir, orphan.entryId, orphan, claimed)))
+            return;
+        if (signal.aborted) {
+            await writeEntryIfUnchanged(config.agentDir, orphan.entryId, claimed, orphan);
+            return;
+        }
+        const launchOutcome = await config.resumeWorker(payload);
+        if (!launchOutcome.started) {
+            await writeEntryIfUnchanged(config.agentDir, orphan.entryId, claimed, orphan);
+            config.onDiagnostic?.(`process-matrix: failed to resume ${orphan.entryId}: ${launchOutcome.reason}`);
+            return;
+        }
+        launched = launchOutcome;
+    }
+    catch (error) {
+        try {
+            await writeEntryIfUnchanged(config.agentDir, orphan.entryId, claimed, orphan);
+        }
+        catch {
+            // The original resumable record remains the intended recovery state.
+        }
+        config.onDiagnostic?.(`process-matrix: failed to resume ${orphan.entryId}: ${describeError(error)}`);
+        return;
+    }
+    const launchedEntry = { ...claimed, pid: launched.pid };
+    if (!signal.aborted) {
+        try {
+            // Bridge the interval before the replacement can self-register. Without its real PID here, a
+            // restarted master can mistake this live replacement for the original dead process and spawn
+            // a duplicate.
+            await writeEntryIfUnchanged(config.agentDir, claimed.entryId, claimed, launchedEntry);
+        }
+        catch (error) {
+            config.onDiagnostic?.(`process-matrix: failed to record resumed worker pid for ${orphan.entryId}: ${describeError(error)}`);
+        }
+    }
+    else {
+        config.onDiagnostic?.(`process-matrix: resumed worker ${orphan.entryId} launched after owner shutdown; preserving its terminal handoff only`);
+    }
+    void launched.completion.then((result) => persistResumedWorkerTerminal(config, launchedEntry, claimed, result, signal), (error) => {
+        config.onDiagnostic?.(`process-matrix: resumed agent ${payload.agent.agentId} terminal signal failed: ${describeError(error)}`);
+    });
+}
+async function persistResumedWorkerTerminal(config, claimed, preLaunchClaim, result, lifetime) {
+    try {
+        const observedAt = new Date().toISOString();
+        const terminal = markTerminal(claimed, result, observedAt);
+        if (await writeEntryIfUnchanged(config.agentDir, claimed.entryId, claimed, terminal)) {
+            if (lifetime.aborted)
+                return;
+            await notifyResumedWorkerTerminal(config, terminal, lifetime);
+            return;
+        }
+        const selfRegistered = await readEntry(config.agentDir, claimed.entryId);
+        if (selfRegistered?.pid === claimed.pid) {
+            const registeredTerminal = markTerminal(selfRegistered, result, observedAt);
+            if (await writeEntryIfUnchanged(config.agentDir, claimed.entryId, selfRegistered, registeredTerminal)) {
+                if (lifetime.aborted)
+                    return;
+                await notifyResumedWorkerTerminal(config, registeredTerminal, lifetime);
+                return;
+            }
+        }
+        // If recording the spawned PID failed (or shutdown won the race immediately after spawn), the
+        // untouched pre-launch claim proves no newer process has taken this logical entry. Upgrade it
+        // to the actual exited process before persisting its terminal handoff.
+        const fallbackTerminal = markTerminal({ ...preLaunchClaim, pid: claimed.pid }, result, observedAt);
+        if (await writeEntryIfUnchanged(config.agentDir, claimed.entryId, preLaunchClaim, fallbackTerminal)) {
+            if (lifetime.aborted)
+                return;
+            await notifyResumedWorkerTerminal(config, fallbackTerminal, lifetime);
+            return;
+        }
+        if (await writeEntryIfUnchanged(config.agentDir, claimed.entryId, undefined, terminal)) {
+            if (lifetime.aborted)
+                return;
+            await notifyResumedWorkerTerminal(config, terminal, lifetime);
+            return;
+        }
+        config.onDiagnostic?.(`process-matrix: ignored stale terminal handoff for ${claimed.entryId}`);
+    }
+    catch (error) {
+        config.onDiagnostic?.(`process-matrix: failed to persist terminal handoff for ${claimed.entryId}: ${describeError(error)}`);
+    }
+}
+async function notifyResumedWorkerTerminal(config, terminal, lifetime) {
+    if (lifetime.aborted)
+        return;
+    try {
+        await config.notify(formatTerminalNotification(terminal));
+        if (lifetime.aborted)
+            return;
+        const delivered = markTerminalNotificationDelivered(terminal, new Date().toISOString());
+        if (!(await writeEntryIfUnchanged(config.agentDir, terminal.entryId, terminal, delivered))) {
+            config.onDiagnostic?.(`process-matrix: terminal handoff changed before acknowledgement for ${terminal.entryId}`);
+        }
+    }
+    catch (error) {
+        config.onDiagnostic?.(`process-matrix: failed to deliver terminal handoff for ${terminal.entryId}: ${describeError(error)}`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Worker branch
 // ---------------------------------------------------------------------------
 async function startWorkerBranch(config, initialParentPid, now) {
     const parentSessionId = getParentSessionId();
+    const taskRef = (getProcessTaskRef() ?? config.taskRef)?.trim().slice(0, 512) || undefined;
+    const taskSummary = config.taskSummary?.trim().slice(0, 2_000) || undefined;
     const laneKey = getBoundWorktreeLaneKey();
+    const contextLaneKey = config.agent.resumeContext.worktreeLaneKey;
+    if (laneKey !== contextLaneKey) {
+        throw new TypeError(`Process-matrix agent lane '${contextLaneKey ?? "none"}' does not match active lane '${laneKey ?? "none"}'.`);
+    }
     let entry = buildWorkerEntry({
-        sessionId: config.sessionId,
+        agent: config.agent,
         pid: process.pid,
         hostname: osHostname(),
         now: nowIso(now),
         parentPid: initialParentPid,
         ...(parentSessionId !== undefined ? { parentSessionId } : {}),
-        ...(laneKey !== undefined ? { laneKey } : {}),
+        ...(taskRef !== undefined ? { taskRef } : {}),
+        ...(taskSummary !== undefined ? { taskSummary } : {}),
     });
     try {
         await writeEntry(config.agentDir, entry);
@@ -188,20 +470,53 @@ async function startWorkerBranch(config, initialParentPid, now) {
     let stopped = false;
     let timer;
     let ticking = false;
+    let preserveResumableOnExit = false;
+    const closeOnExit = (code = null) => {
+        if (preserveResumableOnExit)
+            return;
+        try {
+            const terminal = markTerminal(entry, { code, signal: null }, nowIso(now));
+            if (writeEntryIfUnchangedSync(config.agentDir, entry, terminal))
+                entry = terminal;
+        }
+        catch {
+            // Best-effort. Dead-pid reconciliation remains authoritative.
+        }
+    };
+    process.once("exit", closeOnExit);
     const stop = () => {
+        if (stopped)
+            return;
         stopped = true;
         if (timer)
             clearInterval(timer);
         timer = undefined;
+        if (!preserveResumableOnExit)
+            closeOnExit();
+        process.off("exit", closeOnExit);
     };
-    const persist = async (next, failureContext) => {
-        entry = next;
+    const persist = async (expected, next, failureContext) => {
         try {
-            await writeEntry(config.agentDir, entry);
+            if (await writeEntryIfUnchanged(config.agentDir, expected.entryId, expected, next)) {
+                entry = next;
+                return true;
+            }
+            const current = await readEntry(config.agentDir, expected.entryId);
+            if (current?.pid === process.pid)
+                entry = current;
+            else {
+                stopped = true;
+                if (timer)
+                    clearInterval(timer);
+                timer = undefined;
+                process.off("exit", closeOnExit);
+                config.onDiagnostic?.("process-matrix: worker entry ownership moved to a newer process generation");
+            }
         }
         catch (error) {
             config.onDiagnostic?.(`process-matrix: ${failureContext}: ${describeError(error)}`);
         }
+        return false;
     };
     const startHealthyWatch = () => {
         timer = setInterval(() => {
@@ -221,7 +536,7 @@ async function startWorkerBranch(config, initialParentPid, now) {
         if (!currentParentSessionId || !config.isProcessAlive(currentParentPid))
             return false;
         const parent = await readEntry(config.agentDir, buildEntryId("master", currentParentSessionId));
-        if (!parent || parent.role !== "master" || parent.sessionId !== currentParentSessionId)
+        if (!parent || parent.role !== "master" || parent.agent.resumeContext.sessionId !== currentParentSessionId)
             return false;
         if (parent.pid !== currentParentPid || parent.status !== "running")
             return false;
@@ -243,22 +558,28 @@ async function startWorkerBranch(config, initialParentPid, now) {
         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.");
+        if (!(await persist(fresh, beginWindDown(fresh, "user_cleanup", nowIso(now)), "failed to write a master-requested worker wind-down")))
+            return;
+        emitRuntimeNotice(config, "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.`);
+        const expected = entry;
+        const resumable = { lastCode: "resumable", agent: structuredClone(config.agent) };
+        if (expected.taskRef !== undefined)
+            resumable.taskRef = expected.taskRef;
+        if (expected.taskSummary !== undefined)
+            resumable.taskSummary = expected.taskSummary;
+        const woundDown = markResumable(beginWindDown(expected, "parent_lost", windDownAt), resumable, windDownAt);
+        if (!(await persist(expected, woundDown, "failed to write worker wind-down")))
+            return;
+        if (timer)
+            clearInterval(timer);
+        timer = undefined;
+        preserveResumableOnExit = true;
+        emitRuntimeNotice(config, `process-matrix: parent process (pid ${currentParentPid}) is gone. Winding down gracefully; this task is resumable.`);
         startGraceWatch();
     };
     const startGraceWatch = () => {
@@ -282,10 +603,12 @@ async function startWorkerBranch(config, initialParentPid, now) {
             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.`);
+                if (!(await persist(fresh, applyAdoption(fresh, { parentPid: directive.parentPid, parentSessionId: fresh.parentSessionId }), "failed to write worker adoption")))
+                    return;
+                emitRuntimeNotice(config, `process-matrix: adopted by a new parent (pid ${directive.parentPid}). Resuming.`);
                 currentParentPid = directive.parentPid;
                 currentParentSessionId = fresh.parentSessionId;
+                preserveResumableOnExit = false;
                 if (timer) {
                     clearInterval(timer);
                     timer = undefined;