mixdog 0.9.147 → 0.9.149

package/src/standalone/agent-tool/tag-registry.mjs

@@ -204,34 +204,48 @@ export function createTagRegistry({
     if (id) removeWorkerRow({ sessionId: id });
   }
 
-  function tombstoneTerminalSession(tag, sessionId, session = null) {
+  function tombstoneTerminalSession(tag, sessionId, session = null, expectedReapAt = '') {
     const value = clean(tag);
     const id = clean(sessionId);
     if (!value || !id) {
-      forgetTerminalSession(value, id);
-      return;
+      if (!expectedReapAt) forgetTerminalSession(value, id);
+      return false;
     }
-    if (tags.get(value) === id) {
-      tags.delete(value);
-      tagAgents.delete(value);
-      tagCwds.delete(value);
-    }
-    const tombstone = {
-      tag: value,
-      agent: clean(session?.agent) || null,
-      cwd: clean(session?.cwd) || null,
-      clientHostPid: positiveInt(session?.clientHostPid),
-      reapedAt: new Date().toISOString(),
-    };
+    let applied = false;
     flushWorkerIndexMutations();
     writeWorkerRows((byKey, tombstonesByKey, priorityTombstoneKeys) => {
-      for (const [key, row] of [...byKey.entries()]) {
-        if (clean(row.sessionId) === id) byKey.delete(key);
+      const matches = [...byKey.entries()]
+        .filter(([, row]) => clean(row.sessionId) === id);
+      const expected = expectedReapAt
+        ? matches.find(([, row]) =>
+          clean(row.reapAt) === expectedReapAt
+          && isTerminalWorkerStatus(row.status || row.stage))
+        : null;
+      // A stale timer from an earlier turn must never reap newer work.
+      if (expectedReapAt && !expected) return;
+      const source = expected?.[1] || matches[0]?.[1] || {};
+      const tombstone = {
+        tag: value,
+        agent: clean(session?.agent || source.agent) || null,
+        cwd: clean(session?.cwd || source.cwd) || null,
+        clientHostPid: positiveInt(session?.clientHostPid || source.clientHostPid),
+        reapedAt: new Date().toISOString(),
+      };
+      for (const [key] of matches) {
+        byKey.delete(key);
       }
       const tombstoneKey = tagTombstoneKey(tombstone);
       tombstonesByKey.set(tombstoneKey, tombstone);
       priorityTombstoneKeys.add(tombstoneKey);
+      applied = true;
     });
+    if (!applied) return false;
+    if (tags.get(value) === id) {
+      tags.delete(value);
+      tagAgents.delete(value);
+      tagCwds.delete(value);
+    }
+    return true;
   }
 
   function tagTombstoneForTag(tag, context = {}) {
@@ -256,27 +270,93 @@ export function createTagRegistry({
     return true;
   }
 
-  function scheduleReap(sessionId, provider = null) {
-    if (!sessionId) return;
+  function reapTerminalRow(row) {
+    const sessionId = clean(row?.sessionId);
+    const reapAt = clean(row?.reapAt);
+    const tag = clean(row?.tag) || tagForSession(sessionId);
+    if (!sessionId || !reapAt || !tag) return false;
+    const session = getLiveSession(sessionId);
+    if (!tombstoneTerminalSession(tag, sessionId, session, reapAt)) return false;
+    try { mgr.hideSessionFromList?.(sessionId); } catch {}
+    clearAgentStatuslineRoute(sessionId);
+    // Reaping expires only the reusable tag/runtime lease. The transcript is
+    // user-visible from the parent task's agent tab, so terminal cleanup must
+    // never tombstone it ahead of that parent.
+    try { mgr.unloadSessionRuntime?.(sessionId, 'terminal-reap'); } catch {}
+    return true;
+  }
+
+  function schedulePersistedReap(row) {
+    const sessionId = clean(row?.sessionId);
+    const reapAt = clean(row?.reapAt);
+    const deadline = Date.parse(reapAt) || 0;
+    if (!sessionId || !deadline) return false;
     cancelReap(sessionId);
-    const reapProvider = provider || getLiveSession(sessionId)?.provider || null;
-    const reapMs = resolveAgentTerminalReapMs(cfgMod.loadConfig(), reapProvider);
-    if (reapMs == null) return;
     const handle = setTimeout(() => {
       reapTimers.delete(sessionId);
-      const session = getLiveSession(sessionId);
-      try { mgr.hideSessionFromList?.(sessionId); } catch {}
-      const tag = tagForSession(sessionId);
-      tombstoneTerminalSession(tag, sessionId, session);
-      clearAgentStatuslineRoute(sessionId);
-      // Reaping expires only the reusable tag/runtime lease. The transcript is
-      // user-visible from the parent task's agent tab, so terminal cleanup must
-      // never tombstone it ahead of that parent. The normal completion path
-      // unloads immediately; this delayed call is an idempotent race fallback.
-      try { mgr.unloadSessionRuntime?.(sessionId, 'terminal-reap'); } catch {}
-    }, reapMs);
+      reapTerminalRow(row);
+    }, Math.max(0, deadline - Date.now()));
     handle.unref?.();
     reapTimers.set(sessionId, handle);
+    return true;
+  }
+
+  function scheduleReap(sessionId, provider = null) {
+    const id = clean(sessionId);
+    if (!id) return false;
+    cancelReap(id);
+    // The terminal upsert is deferred to batch parallel fanout writes. Flush it
+    // before stamping the deadline so reapAt and the terminal state land in one
+    // durable lifecycle order.
+    flushWorkerIndexMutations();
+    const row = readWorkerRows().find((entry) => clean(entry.sessionId) === id);
+    if (!row || !isTerminalWorkerStatus(row.status || row.stage)) return false;
+    const reapProvider = clean(provider) || clean(row.provider)
+      || clean(getLiveSession(id)?.provider) || null;
+    const reapMs = resolveAgentTerminalReapMs(cfgMod.loadConfig(), reapProvider);
+    const reapAt = reapMs == null ? null : new Date(Date.now() + reapMs).toISOString();
+    let persisted = null;
+    writeWorkerRows((byKey) => {
+      for (const [key, current] of byKey.entries()) {
+        if (clean(current.sessionId) !== id) continue;
+        if (!isTerminalWorkerStatus(current.status || current.stage)) return;
+        persisted = { ...current, reapAt };
+        byKey.set(key, persisted);
+        return;
+      }
+    });
+    return persisted?.reapAt ? schedulePersistedReap(persisted) : false;
+  }
+
+  /** Rebuild child terminal timers after a process restart. Legacy rows have
+   * no reapAt, so derive the original absolute deadline from their frozen
+   * terminal stamp instead of granting a fresh full lease on every boot. */
+  function recoverTerminalReaps() {
+    flushWorkerIndexMutations();
+    const now = Date.now();
+    const recovered = [];
+    writeWorkerRows((byKey) => {
+      for (const [key, row] of byKey.entries()) {
+        if (!isTerminalWorkerStatus(row.status || row.stage)) continue;
+        let reapAt = clean(row.reapAt);
+        if (!(Date.parse(reapAt) > 0)) {
+          const reapMs = resolveAgentTerminalReapMs(cfgMod.loadConfig(), row.provider);
+          if (reapMs == null) continue;
+          const terminalAt = workerRowTime(row);
+          // A timestamp-free legacy row cannot prove that its grace already
+          // elapsed. Give it one normal window from recovery; timestamped rows
+          // keep their original completion-based deadline.
+          reapAt = new Date((terminalAt > 0 ? terminalAt : now) + reapMs).toISOString();
+        }
+        const next = { ...row, reapAt };
+        byKey.set(key, next);
+        recovered.push(next);
+      }
+    });
+    for (const row of recovered) {
+      if ((Date.parse(row.reapAt) || 0) <= now) reapTerminalRow(row);
+      else schedulePersistedReap(row);
+    }
   }
 
   function transitionStaleNonterminalRows(context = {}) {
@@ -321,6 +401,8 @@ export function createTagRegistry({
     return true;
   }
 
+  recoverTerminalReaps();
+
   return {
     readAllTagTombstones,
     readTagTombstones,
@@ -351,6 +433,7 @@ export function createTagRegistry({
     consumeTagTombstone,
     cancelReap,
     scheduleReap,
+    recoverTerminalReaps,
     transitionStaleNonterminalRows,
   };
 }

package/src/standalone/agent-tool/tool-def.mjs

@@ -22,14 +22,14 @@ export const AGENT_TOOL = {
     openWorldHint: true,
     agentHidden: true,
   },
-  description: 'Run scoped agent work as background tasks. spawn/send return task_id immediately; the same tag reuses its live session, while independent scopes need distinct tags. Wait for completion notifications; use status/read only for manual recovery.',
+  description: 'Run scoped agent work as background tasks. spawn/send return task_id immediately. Reuse one tag for one scope for its whole lifetime; give distinct tags only to independent scopes. Never mint a new tag because a session expired or was lost — same-tag spawn respawns it with the full brief. Wait for completion notifications; use status/read only for manual recovery.',
   inputSchema: {
     type: 'object',
     properties: {
       type: { type: 'string', enum: ['spawn', 'send', 'list', 'close', 'cancel', 'status', 'read', 'cleanup'], description: 'Required action. New spawn requires agent and one of prompt/message/file; send requires tag and one of prompt/message/file; read/status/close/cancel require task_id or tag; list/cleanup require no target.' },
       task_id: { type: 'string', description: 'Task ID returned by spawn/send; target for read/status/close/cancel.' },
       agent: { type: 'string', description: 'Workflow agent id. Required for a new spawn; same-tag reuse can inherit it.' },
-      tag: { type: 'string', description: 'Stable scope handle. Reuse for the same scope; send requires it, while spawn can generate one when omitted.' },
+      tag: { type: 'string', description: 'Stable scope handle. Reuse the same tag for the same scope; never derive a variant by appending a number or suffix. send requires it, while spawn can generate one when omitted.' },
       prompt: { type: 'string', description: 'Spawn task brief; also accepted for send.' },
       message: { type: 'string', description: 'Send follow-up; also accepted for spawn.' },
       file: { type: 'string', description: 'Path to task text; alternative to prompt/message for spawn/send.' },

package/src/standalone/agent-tool/worker-index.mjs

@@ -7,17 +7,14 @@ import { readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 import { updateJsonAtomicSync } from '../../runtime/shared/atomic-file.mjs';
-import { resolveAgentTerminalReapMs } from '../../session-runtime/config-helpers.mjs';
 import { WORKER_INDEX_FILE } from './tool-def.mjs';
 import { agentTagOf, clean, positiveInt, rowMatchesContext } from './helpers.mjs';
 import {
   applyWorkerRowUpsert,
-  isDeadWorkerStatus,
   isLeadPoolAgent,
   normalizeTagTombstones,
   tagTombstoneKey,
   workerRowKey,
-  workerRowTime,
 } from './worker-rows.mjs';
 
 export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCwds }) {
@@ -33,15 +30,11 @@ export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCw
     return dataDir ? resolve(dataDir, WORKER_INDEX_FILE) : null;
   }
 
-  // A terminal row ages out after the configured reap window so the index does
-  // not grow without bound; live rows are always kept.
+  // Reaping is an explicit lifecycle mutation owned by tag-registry. Silently
+  // filtering an expired row here would skip its tombstone and make persisted
+  // state disagree with the reusable-tag lease.
   function keepWorkerRow(row = {}) {
-    if (!clean(row.tag) || !clean(row.sessionId)) return false;
-    const t = workerRowTime(row);
-    if (!t) return true;
-    if (!isDeadWorkerStatus(row.status || row.stage)) return true;
-    const reapMs = resolveAgentTerminalReapMs(cfgMod.loadConfig(), row.provider);
-    return reapMs == null || Date.now() - t < reapMs;
+    return Boolean(clean(row.tag) && clean(row.sessionId));
   }
 
   function normalizeWorkerRows(value) {
@@ -69,6 +62,7 @@ export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCw
         lastUsedAt: clean(row.lastUsedAt) || null,
         finishedAt: clean(row.finishedAt) || null,
         turnStartedAt: clean(row.turnStartedAt) || null,
+        reapAt: clean(row.reapAt) || null,
         clientHostPid: positiveInt(row.clientHostPid),
         cwd: clean(row.cwd) || null,
         task_id: clean(row.task_id || row.taskId) || null,
@@ -221,6 +215,9 @@ export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCw
       // Turn dispatch stamps this; terminal upserts leave it null and the
       // merge in applyWorkerRowUpsert preserves the running turn's value.
       turnStartedAt: clean(extra.turnStartedAt) || null,
+      // Active/new work clears the previous lease. Terminal settlement writes
+      // the new absolute deadline immediately afterwards via scheduleReap().
+      reapAt: clean(extra.reapAt) || null,
       clientHostPid: positiveInt(extra.clientHostPid) || positiveInt(session?.clientHostPid),
       cwd: clean(session?.cwd) || clean(extra.cwd) || null,
       task_id: clean(extra.task_id || extra.taskId) || null,

package/src/standalone/agent-tool/worker-rows.mjs

@@ -21,7 +21,9 @@ export function workerRowTime(row = {}) {
 }
 
 export function isTerminalWorkerStatus(status) {
-  return /^(idle|closed|completed|failed|error|cancelled|canceled|killed|timeout)$/i.test(clean(status));
+  return /^(idle|closed|complete|completed|done|success|fail|failed|error|cancelled|canceled|killed|timeout)$/i.test(
+    clean(status),
+  );
 }
 
 /** Finished / gone. Idle is living and must stay in the process-global pool. */
@@ -100,6 +102,7 @@ export function workerRowToSession(row = {}) {
     createdAt: row.createdAt || null,
     updatedAt: row.updatedAt || null,
     lastUsedAt: row.lastUsedAt || null,
+    reapAt: row.reapAt || null,
     clientHostPid: row.clientHostPid || null,
     cwd: row.cwd || null,
     permission: row.permission || null,

package/src/standalone/agent-tool.mjs

@@ -5,7 +5,6 @@ import {
   cleanupBackgroundTasks,
   getBackgroundTask,
   listBackgroundTasks,
-  reconcileBackgroundTask,
   startBackgroundTask,
   sanitizeTaskMeta,
   taskIdFromArgs,
@@ -51,6 +50,12 @@ import { createProviderInit } from './agent-tool/provider-init.mjs';
 import { createNotify } from './agent-tool/notify.mjs';
 import { createTagRegistry } from './agent-tool/tag-registry.mjs';
 import { createJobViews } from './agent-tool/job-views.mjs';
+import {
+  reconcileJobFinally,
+  reconcileJobStreamStalled,
+  reconcileJobTerminalResult,
+  reconcileJobWatchdogPartial,
+} from './agent-tool/job-task-reconcile.mjs';
 import { createSpawnFlow } from './agent-tool/spawn-flow.mjs';
 import { resolveAgentSpawnPreset } from './agent-tool/spawn-preset.mjs';
 import {
@@ -203,6 +208,7 @@ export function createStandaloneAgent({
       progressWatchdogs,
       startProgressIdleWatchdog,
       turnStartStamper,
+      progressStamper,
       prepareSpawn,
       prepareSpawnInProcess,
       runSpawn,
@@ -259,6 +265,7 @@ export function createStandaloneAgent({
     // the watchdog sweep re-stamps turnStartedAt at each turn boundary.
     const watchdog = startProgressIdleWatchdog(sessionId, resolveAgentWatchdogPolicy(sendAgent), sendAgent, {
       onTurnStart: turnStartStamper(session, tag),
+      onProgress: progressStamper(session, tag),
     });
     const turnReview = createTurnReviewCollector(session, tag, sendAgent, notifyContext || {});
     let finalStatus = 'idle';
@@ -294,24 +301,7 @@ export function createStandaloneAgent({
             const value = completionValue(terminalResult);
             if (job) job._terminalResultValue = value;
             notifyOwnerAgentCompletionEarly(job, value, notifyContext || {});
-            // Mark terminal as soon as the worker's final result lands so a slow
-            // post-result save can't strand the task in `running`. Idempotent.
-            if (job?.taskId) {
-              try {
-                reconcileBackgroundTask(job.taskId, value.error
-                  ? {
-                      status: 'failed',
-                      result: value,
-                      error: value.error,
-                      terminalReason: 'agent-empty-final',
-                    }
-                  : {
-                      status: 'completed',
-                      result: value,
-                      terminalReason: 'agent-terminal-result',
-                    });
-              } catch {}
-            }
+            reconcileJobTerminalResult(job, value);
           },
         } : {}),
       });
@@ -338,30 +328,11 @@ export function createStandaloneAgent({
           stallAbort: true,
         };
         if (job) job._terminalResultValue = value;
-        if (job?.taskId) {
-          try {
-            reconcileBackgroundTask(job.taskId, {
-              status: 'completed',
-              result: value,
-              terminalReason: 'agent-watchdog-partial',
-            });
-          } catch {}
-        }
+        reconcileJobWatchdogPartial(job, value);
         return value;
       }
       finalStatus = 'error';
-      // Part C (send path mirror): a mid-stream stall throws with no terminal
-      // result — reconcile to `failed` so the owner is notified rather than the
-      // task hanging in `running`. Idempotent (see runSpawn note).
-      if (job?.taskId && job._terminalResultValue === undefined) {
-        try {
-          reconcileBackgroundTask(job.taskId, {
-            status: 'failed',
-            error,
-            terminalReason: 'agent-stream-stalled',
-          });
-        } catch {}
-      }
+      reconcileJobStreamStalled(job, error);
       throw error;
     } finally {
       turnReview.complete();
@@ -371,20 +342,7 @@ export function createStandaloneAgent({
         stage: finalStatus,
         finishedAt: new Date().toISOString(),
       });
-      // Safety net mirror of runSpawn: reconcile a stranded task if a post-result
-      // step hung/threw after a terminal result was already produced.
-      if (job && job._terminalResultValue !== undefined) {
-        try {
-          reconcileBackgroundTask(job.taskId, {
-            status: finalStatus === 'error' ? 'failed' : 'completed',
-            result: job._terminalResultValue,
-            ...(finalStatus === 'error' && job._terminalResultValue?.error
-              ? { error: job._terminalResultValue.error }
-              : {}),
-            terminalReason: 'agent-finally-reconcile',
-          });
-        } catch {}
-      }
+      reconcileJobFinally(job, finalStatus);
       scheduleReap(sessionId);
       // Same lifecycle as a fresh spawn: the transcript/tag stays resumable,
       // while heavy process-local runtime state is reclaimed immediately.
@@ -458,7 +416,6 @@ export function createStandaloneAgent({
     }
     cancelReap(sessionId);
     const tag = tagForSession(sessionId);
-    forgetTerminalSession(tag, sessionId);
     clearAgentStatuslineRoute(sessionId);
     // Cancel any running background task bound to this session BEFORE closing
     // the session. Otherwise closeSession rejects the in-flight runSpawn with
@@ -470,8 +427,16 @@ export function createStandaloneAgent({
       if (row.sessionId !== sessionId && row.tag !== target) continue;
       cancelBackgroundTask(row.task_id, 'cancelled by agent close');
     }
+    // Close (and stamp cancelStatus) BEFORE dropping the worker row. Removing
+    // the row first left the next pool read with only a leftover heartbeat,
+    // which republished the session as `running`.
     const ok = mgr.closeSession(sessionId, 'cli-agent-close');
     if (task?.taskId) cancelBackgroundTask(task.taskId, 'cancelled by agent close');
+    // Drop the row only once the cancellation is DURABLY recorded. A close that
+    // failed still forgot the row, leaving the next pool read with a fresh
+    // heartbeat and no cancelled state — which republished the session as
+    // `running`, the exact lingering row this whole path exists to prevent.
+    if (ok) forgetTerminalSession(tag, sessionId);
     return { closed: ok, tag, sessionId, task_id: task?.taskId || null };
   }
 

package/src/standalone/agent-watchdog-registry.mjs

@@ -41,13 +41,32 @@ export function createProgressWatchdogRegistry({ mgr }) {
       state.lastAskStartedAt = askStartedAt;
       try { state.onTurnStart?.(askStartedAt); } catch { /* bookkeeping only */ }
     }
-    const abortErr = snapshot ? evaluateAgentWatchdogAbort(snapshot, now, watchdogPolicy) : null;
     const sess = typeof mgr.getSession === 'function' ? mgr.getSession(sessionId) : null;
     const iteration = typeof sess?.lastIterationIndex === 'number' ? sess.lastIterationIndex : null;
+    // In-turn progress. The worker index is otherwise stamped only at spawn and
+    // at turn boundaries, so a FIRST turn that runs dozens of tool iterations
+    // leaves the Agents panel frozen on its start stamp for minutes (user
+    // report: 위임한 세션이 안 도는 것처럼 보인다). This sweep already holds the
+    // live session, so reporting the change costs no extra read.
+    if (state.onProgress) {
+      const messages = Array.isArray(sess?.messages) ? sess.messages.length : 0;
+      const signature = `${iteration ?? ''}:${messages}`;
+      if (signature !== state.lastProgressSignature) {
+        state.lastProgressSignature = signature;
+        try { state.onProgress({ iteration, messages }); } catch { /* bookkeeping only */ }
+      }
+    }
+    const abortErr = snapshot ? evaluateAgentWatchdogAbort(snapshot, now, watchdogPolicy) : null;
     // No progress snapshot: fall back to the coarse last-progress timestamp so a
     // session that never reports structured progress can still stall out.
     if (!abortErr && !snapshot) {
-      const reported = mgr.getSessionLastProgressAt(sessionId);
+      // start() admits a manager that provides EITHER progress source, so this
+      // fallback must not assume the coarse one exists: throwing here escaped
+      // the shared interval and disabled watchdog coverage for every session.
+      let reported = 0;
+      if (typeof mgr.getSessionLastProgressAt === 'function') {
+        try { reported = Number(mgr.getSessionLastProgressAt(sessionId)) || 0; } catch { reported = 0; }
+      }
       const last = reported || anchorTs;
       if (watchdogPolicy.idleStaleMs > 0 && now - last > watchdogPolicy.idleStaleMs) {
         abortAgentProgressWatchdog(controller, {
@@ -80,7 +99,10 @@ export function createProgressWatchdogRegistry({ mgr }) {
   function ensureTimer() {
     if (timer || watched.size === 0) return;
     timer = setInterval(() => {
-      for (const state of [...watched.values()]) check(state);
+      // One session's failure must never cancel the sweep for the others.
+      for (const state of [...watched.values()]) {
+        try { check(state); } catch { /* watchdog is best-effort */ }
+      }
     }, WATCHDOG_SWEEP_INTERVAL_MS);
     timer.unref?.();
   }
@@ -88,7 +110,7 @@ export function createProgressWatchdogRegistry({ mgr }) {
   return {
     /** Watch a session until the returned handle is stopped; null when the
      *  policy is off or the manager cannot link an abort signal. */
-    start(sessionId, watchdogPolicy, agent = null, { onTurnStart = null } = {}) {
+    start(sessionId, watchdogPolicy, agent = null, { onTurnStart = null, onProgress = null } = {}) {
       if (!sessionId || !agentWatchdogPolicyActive(watchdogPolicy)) return null;
       if (typeof mgr.getSessionProgressSnapshot !== 'function'
         && typeof mgr.getSessionLastProgressAt !== 'function') return null;
@@ -103,7 +125,9 @@ export function createProgressWatchdogRegistry({ mgr }) {
         controller,
         anchorTs,
         onTurnStart: typeof onTurnStart === 'function' ? onTurnStart : null,
+        onProgress: typeof onProgress === 'function' ? onProgress : null,
         lastAskStartedAt: 0,
+        lastProgressSignature: '',
       };
       watched.set(sessionId, state);
       ensureTimer();

package/src/standalone/channel-client.mjs

@@ -8,24 +8,13 @@
 import http from 'node:http';
 import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-
-function parsePid(value) {
-  const n = Number(value);
-  return Number.isInteger(n) && n > 0 ? n : null;
-}
+import { isPidAlive, parsePid } from '../runtime/shared/pid-liveness.mjs';
 
 function parsePort(value) {
   const n = Number(value);
   return Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
 }
 
-function isPidAlive(pid) {
-  const n = parsePid(pid);
-  if (!n) return false;
-  try { process.kill(n, 0); return true; }
-  catch (error) { return error?.code === 'EPERM'; }
-}
-
 // Read + validate the discovery file. Returns null when missing/corrupt or when
 // the recorded pid is dead (stale daemon) so the caller reclaims + respawns.
 export function readChannelDiscovery(discoveryPath) {
@@ -153,6 +142,11 @@ export async function attachChannel({
   if (!isExpectedDaemon(initialHealth)) throw staleDiscoveryError('daemon discovery pid does not match health');
 
   let reg;
+  // A stable registration id even on the FIRST attach: if this response is
+  // lost, the daemon reaps the never-acknowledged token through its replay TTL
+  // instead of holding an unreapable client against a live pid forever (which
+  // blocks daemon self-shutdown).
+  const initialRegistrationId = randomUUID();
   try {
     reg = await request({
       port,
@@ -161,7 +155,10 @@ export async function attachChannel({
       path: '/client/register',
       // Channel attachment observes the current owner and never claims the
       // manual routing seat merely by opening the transport.
-      body: { leadPid, cwd, passive: true, restoreSessionId },
+      body: {
+        leadPid, cwd, passive: true, restoreSessionId,
+        registrationId: initialRegistrationId,
+      },
       timeoutMs: 3000,
       agent: controlAgent,
     });
@@ -186,7 +183,12 @@ export async function attachChannel({
   let reconnectReplaceToken = null;
   let lifecycle = 0;
   let stableTimer = null;
+  let livenessTimer = null;
   let closePromise = null;
+  // The daemon writes a `: ka` comment every 15s. A half-open socket delivers
+  // no bytes and no FIN, so without this deadline the stream stays "connected"
+  // forever and the client never reconnects.
+  const STREAM_LIVENESS_MS = 45_000;
   // Bounded reconnect is only for a verified-live daemon's transient SSE loss.
   // A stale/dead endpoint signals onFatal immediately so the owner re-reads
   // discovery instead of spinning against the captured port.
@@ -220,6 +222,10 @@ export async function attachChannel({
     if (stableTimer) { try { clearTimeout(stableTimer); } catch {} stableTimer = null; }
   }
 
+  function clearLivenessTimer() {
+    if (livenessTimer) { try { clearTimeout(livenessTimer); } catch {} livenessTimer = null; }
+  }
+
   function signalFatal(reason) {
     if (closed || fatal) return;
     fatal = true;
@@ -227,6 +233,7 @@ export async function attachChannel({
     lifecycle++;
     if (reconnectTimer) { try { clearTimeout(reconnectTimer); } catch {} reconnectTimer = null; }
     clearStableTimer();
+    clearLivenessTimer();
     try { sseReq?.destroy?.(); } catch {}
     log(`sse stale endpoint (${reason}); signalling re-attach`);
     try { onFatal(reason); } catch {}
@@ -251,6 +258,9 @@ export async function attachChannel({
 
   function openStream() {
     if (closed) return;
+    // A liveness expiry is a transient stream loss (reconnect), not a dead
+    // endpoint: keep the destroy() it triggers off the fatal path.
+    let livenessLost = false;
     const req = http.request({
       hostname: '127.0.0.1',
       port,
@@ -278,9 +288,22 @@ export async function attachChannel({
         if (!closed && !fatal && req === sseReq) reconnectAttempts = 0;
       }, STABLE_STREAM_MS);
       stableTimer.unref?.();
+      const armLiveness = () => {
+        clearLivenessTimer();
+        livenessTimer = setTimeout(() => {
+          if (closed || fatal || req !== sseReq) return;
+          livenessLost = true;
+          handleStreamLoss(`sse liveness timeout after ${STREAM_LIVENESS_MS}ms`);
+          try { req.destroy(new Error('channel SSE liveness timeout')); } catch {}
+        }, STREAM_LIVENESS_MS);
+        livenessTimer.unref?.();
+      };
+      armLiveness();
       let buf = '';
       res.on('data', (chunk) => {
         if (req !== sseReq || closed) return;
+        // Any byte, including a `: ka` keepalive comment, proves liveness.
+        armLiveness();
         buf += chunk;
         let idx;
         while ((idx = buf.indexOf('\n\n')) >= 0) {
@@ -299,18 +322,21 @@ export async function attachChannel({
       res.on('end', () => {
         if (req === sseReq) {
           clearStableTimer();
+          clearLivenessTimer();
           handleStreamLoss('sse ended');
         }
       });
       res.on('error', () => {
         if (req === sseReq) {
           clearStableTimer();
+          clearLivenessTimer();
           handleStreamLoss('sse error');
         }
       });
     });
     req.on('error', () => {
-      if (req === sseReq) signalFatal('sse req error');
+      if (req !== sseReq || livenessLost) return;
+      signalFatal('sse req error');
     });
     sseReq = req;
     req.end();
@@ -384,7 +410,12 @@ export async function attachChannel({
       err.daemonTransportError = true;
       throw err;
     }
-    if (out && out.error) throw new Error(out.error);
+    if (out && out.error) {
+      // Preserve the daemon's machine-readable classification across the wire.
+      const err = new Error(out.error);
+      if (out.code) err.code = String(out.code);
+      throw err;
+    }
     return out?.result;
   }
 
@@ -394,6 +425,7 @@ export async function attachChannel({
     lifecycle++;
     if (reconnectTimer) { try { clearTimeout(reconnectTimer); } catch {} reconnectTimer = null; }
     clearStableTimer();
+    clearLivenessTimer();
     try { sseReq?.destroy?.(); } catch {}
     // A re-register already in flight can mint a fresh token after close().
     // Await it so its stale branch deregisters that token before close resolves.