mixdog 1.1.2 → 1.2.1

package/src/standalone/daemon.mjs

@@ -20,6 +20,8 @@ process.env.MIXDOG_DAEMON_HOST = '1';
 // Size the libuv threadpool before any async fs work spins it up (see
 // uv-threadpool-boot.mjs) — imports below already touch fs.
 await import('../runtime/shared/uv-threadpool-boot.mjs');
+// Before anything can import sharp: Electron on Linux must use its wasm build.
+await import('../runtime/shared/sharp-electron-linux.mjs');
 
 // No V8 compile cache here, on purpose. Measured on this runtime: a cache hit
 // saves nothing (spawn→ready 316-347ms with the cache vs 318-323ms without,
@@ -37,8 +39,17 @@ import { writeJsonAtomicSync } from '../runtime/shared/atomic-file.mjs';
 import { ensurePrivateRuntimeRoot, resolveRuntimeRoot } from '../runtime/shared/runtime-root.mjs';
 import { ensureProcessListenerHeadroom } from '../runtime/shared/process-listener-headroom.mjs';
 import { listenerLeakWarningLine } from '../runtime/shared/listener-leak-warning.mjs';
-import { claimSingletonOwner, releaseSingletonOwner } from '../runtime/shared/singleton-owner.mjs';
+import { claimSingletonOwner, readSingletonOwner, releaseSingletonOwner } from '../runtime/shared/singleton-owner.mjs';
+import {
+  createOwnerHeartbeat,
+  daemonOwnerIsStale,
+  daemonOwnerTimings,
+  discoveryPid,
+  proveDaemonOwnerRecord,
+  startOwnerLivenessListener,
+} from './daemon-owner.mjs';
 import { remoteIntentPath } from '../runtime/shared/remote-intent.mjs';
+import { modelProxyClientMode } from '../runtime/shared/model-proxy-mode.mjs';
 import { setChannelNotifySink } from '../runtime/channels/lib/parent-bridge.mjs';
 import { setOwnerContext } from '../runtime/channels/lib/runtime-paths.mjs';
 import { safeIpcSend } from '../runtime/shared/safe-ipc-send.mjs';
@@ -61,6 +72,7 @@ import { createSessionService } from './session-service.mjs';
 import { createLocalSessionBridge } from './daemon-local-session-bridge.mjs';
 import { createStoredSessionViews } from './daemon-stored-session-views.mjs';
 import * as quotaResumeStore from '../runtime/shared/quota-resume-store.mjs';
+import { registerWorktreeCacheCleanups } from '../runtime/shared/worktrees/cache-cleanups.mjs';
 import { createInlineSessionRuntimeHost } from './session-runtime-inline-host.mjs';
 import { getStandaloneMemoryRuntime } from '../session-runtime/services/memory-runtime-proxy.mjs';
 import { createBootPhaseProfiler } from './boot-phase-profiler.mjs';
@@ -126,6 +138,18 @@ let remoteSessionState = { enabled: false, sessionId: null };
 let shuttingDown = false;
 let shutdownRecheckTimer = null;
 let replacementRequested = null;
+let ownerHeartbeat = null;
+// Answers /health with this pid on the port the owner record names, from
+// before the claim until exit (daemon-owner.mjs).
+let ownerLiveness = null;
+// The endpoints daemon.json carries once published; a heartbeat re-publishes
+// them when the file goes missing (TEMP cleanup).
+let publishedEndpoints = null;
+// Remote mode only: the loopback relay that lets headless runs started from
+// model shells (skill scripts) reach the PC behind this daemon's model proxy
+// channel (providers/model-proxy-bridge.mjs), and its running-call count.
+let modelProxyBridge = null;
+let modelProxyBridgeActive = 0;
 const eventLoopDelay = monitorEventLoopDelay({ resolution: 20 });
 eventLoopDelay.enable();
 let idleGc = null;
@@ -181,6 +205,7 @@ const SHUTDOWN_BUDGET_MS = 15_000;
 async function shutdown(reason, code = 0) {
   if (shuttingDown) return;
   shuttingDown = true;
+  ownerHeartbeat?.stop();
   exitRecorder.setReason(`shutdown: ${reason}`, code);
   if (shutdownRecheckTimer) {
     clearTimeout(shutdownRecheckTimer);
@@ -199,6 +224,13 @@ async function shutdown(reason, code = 0) {
   try {
     setChannelNotifySink(null);
   } catch {}
+  // Abort every relayed model call, close the bridge sockets and wait for the
+  // calls to settle before anything they depend on goes away.
+  try {
+    await modelProxyBridge?.close(`daemon shutdown: ${reason}`);
+  } catch (e) {
+    log(`model proxy bridge stop failed: ${e?.message || e}`);
+  }
   try {
     await sessionService?.stop?.(reason);
   } catch (e) {
@@ -258,7 +290,9 @@ async function shutdown(reason, code = 0) {
   daemonTelemetry?.stop();
   eventLoopDelay.disable();
   try {
-    rmSync(DAEMON_DISCOVERY_PATH, { force: true });
+    // Only our own: a successor that reclaimed a stale owner record may
+    // already have published its endpoint here.
+    if (discoveryPid(DAEMON_DISCOVERY_PATH) === process.pid) rmSync(DAEMON_DISCOVERY_PATH, { force: true });
   } catch {}
   try {
     releaseSingletonOwner(OWNER_PATH, process.pid);
@@ -271,7 +305,7 @@ async function shutdown(reason, code = 0) {
  *  asks whether this process may exit; idle GC asks whether a pause is safe. */
 function inFlightWork() {
   return {
-    activeCalls: (transport?.activeCount ?? 0) + (sessionTransport?.activeCount ?? 0),
+    activeCalls: (transport?.activeCount ?? 0) + (sessionTransport?.activeCount ?? 0) + modelProxyBridgeActive,
     queuedCalls: (transport?.queuedCount ?? 0) + (sessionTransport?.queuedCount ?? 0),
     busySessions: sessionService?.busyCount ?? 0,
     busyMemoryAgents: agentDispatchBroker?.snapshot?.().inFlight ?? 0,
@@ -421,7 +455,18 @@ function requestDaemonReplacement({ protocol, revision, version, force } = {}) {
 /** Pid-verified singleton claim (claimSingletonOwner reclaims a dead-pid owner
  *  file and refuses only a LIVE peer). Loser exits so the spawner attaches to
  *  the winner instead of running a second daemon. */
-function claimDaemonOwnership(bootPhases) {
+async function claimDaemonOwnership(bootPhases) {
+  const timings = daemonOwnerTimings();
+  // A live-pid record is reclaimable only when its holder's endpoint does not
+  // answer with its pid (daemon-owner.mjs); probed before the sync claim.
+  const proof = await proveDaemonOwnerRecord(OWNER_PATH, {
+    discoveryPath: DAEMON_DISCOVERY_PATH,
+    staleMs: timings.staleMs,
+  });
+  // Up BEFORE the claim, so even the first record names a port that answers
+  // with this pid: a contender never reclaims a booting daemon on a stale-
+  // looking stamp (a clock jump) alone.
+  ownerLiveness = await startOwnerLivenessListener({ log });
   const claim = claimSingletonOwner(OWNER_PATH, {
     kind: 'mixdog-daemon',
     pid: process.pid,
@@ -430,14 +475,47 @@ function claimDaemonOwnership(bootPhases) {
       protocol: SESSION_PROTOCOL,
       revision: SESSION_REVISION,
       version: runtimeVersion(),
+      heartbeatAt: new Date().toISOString(),
+      ...(ownerLiveness ? { livenessPort: ownerLiveness.port } : {}),
+    },
+    // A live pid that neither beats nor answers is a reused pid, not a peer.
+    isStale: (owner) => {
+      const stale = daemonOwnerIsStale(owner, { proof, staleMs: timings.staleMs });
+      if (stale) {
+        log(
+          `reclaiming stale owner record pid=${owner.pid} claimedAt=${owner.claimedAt}` +
+            ` heartbeatAt=${owner.heartbeatAt ?? '-'} probe=${proof?.verdict ?? '-'}`
+        );
+      }
+      return stale;
     },
   });
   if (!claim.owned) {
     log(`live peer holds owner lock (pid=${claim.owner?.pid}) — exiting for attach`);
+    void ownerLiveness?.close();
+    ownerLiveness = null;
     exitRecorder.setReason(`lost singleton claim to live peer pid=${claim.owner?.pid}`, 0);
     process.exit(0);
   }
   bootPhases.mark('owner-claimed');
+  // Beats from here on, through boot: a slow boot is never mistaken for a
+  // reused pid. Losing the record to another pid, or the lease running out
+  // unrefreshed, means another daemon owns (or may now claim) this data dir —
+  // at most one may keep serving.
+  ownerHeartbeat = createOwnerHeartbeat({
+    ownerPath: OWNER_PATH,
+    owner: claim.owner,
+    heartbeatMs: timings.heartbeatMs,
+    fenceMs: timings.fenceMs,
+    tickMs: timings.tickMs,
+    stallMs: timings.stallMs,
+    log,
+    onBeat: republishMissingDiscovery,
+    onSuperseded: (record) => fenceDaemon(`owner claim superseded by pid=${record?.pid}`),
+    onFenced: ({ lastRefreshAt, sinceMs }) =>
+      fenceDaemon(`owner lease expired (no refresh for ${sinceMs}ms, last ${lastRefreshAt})`),
+  });
+  ownerHeartbeat.start();
   process.on('exit', () => {
     try {
       releaseSingletonOwner(OWNER_PATH, process.pid);
@@ -497,7 +575,9 @@ function daemonStatusSnapshot() {
 
 /** The file every attacher reads to find this daemon: wire identity plus both
  *  loopback endpoints and their privileged tokens. */
-function publishDaemonDiscovery({ channel, session }) {
+function publishDaemonDiscovery({ channel, session, modelProxy = null }) {
+  // A re-publish keeps the first publication's startedAt.
+  publishedEndpoints = { channel, session, modelProxy, startedAt: publishedEndpoints?.startedAt ?? Date.now() };
   writeJsonAtomicSync(
     DAEMON_DISCOVERY_PATH,
     {
@@ -506,16 +586,75 @@ function publishDaemonDiscovery({ channel, session }) {
       version: runtimeVersion(),
       capabilityFingerprint: SESSION_CAPABILITY_FINGERPRINT,
       pid: process.pid,
-      startedAt: Date.now(),
+      startedAt: publishedEndpoints.startedAt,
       endpoints: {
         channel: { port: channel.port, token: channel.token },
         session: { port: session.port, token: session.token },
+        ...(modelProxy ? { modelProxy: { port: modelProxy.port, token: modelProxy.token } } : {}),
       },
     },
     { compact: true, secret: true }
   );
 }
 
+/** Remote mode only: the model proxy bridge endpoint to publish, or null. */
+async function startModelProxyBridge(bootPhases) {
+  if (!modelProxyClientMode()) return null;
+  const [{ createModelProxyBridgeServer }, { getModelProxyChannel }] = await Promise.all([
+    import('../runtime/agent/orchestrator/providers/model-proxy-bridge.mjs'),
+    import('../runtime/agent/orchestrator/providers/model-proxy-channel.mjs'),
+  ]);
+  modelProxyBridge = createModelProxyBridgeServer({
+    channel: getModelProxyChannel(),
+    // Fenced or shutting down: no new relayed call.
+    admit: () => !shuttingDown && admitOwnerWork(),
+    trackWork: (active) => {
+      modelProxyBridgeActive = active;
+    },
+    log,
+  });
+  const endpoint = await bootPhases.measure('model-proxy-bridge-start', () => modelProxyBridge.start());
+  log(`model proxy bridge on 127.0.0.1:${endpoint.port}`);
+  return endpoint;
+}
+
+/** Asked by both front doors before every register/call: an expired lease
+ *  fences here (answered 503), and after an event-loop stall nothing is
+ *  served until the record is re-verified as ours. */
+function admitOwnerWork() {
+  return ownerHeartbeat ? ownerHeartbeat.admit() : true;
+}
+
+/** This process no longer holds (or is about to lose) the owner lease: refuse
+ *  new work at once, unpublish its endpoint so launchers stop finding it, then
+ *  shut down within the shutdown budget — before a contender may reclaim. */
+function fenceDaemon(reason) {
+  if (shuttingDown) return;
+  log(`${reason} — refusing new work and stopping so only one daemon serves`);
+  sessionTransport?.commitDrain?.(reason);
+  transport?.commitDrain?.(reason);
+  modelProxyBridge?.abortAll(reason);
+  try {
+    if (discoveryPid(DAEMON_DISCOVERY_PATH) === process.pid) rmSync(DAEMON_DISCOVERY_PATH, { force: true });
+  } catch (e) {
+    log(`daemon.json unpublish failed: ${e?.message || e}`);
+  }
+  void shutdown(reason);
+}
+
+/** Heartbeat follow-up while this process still owns the lock: a daemon.json
+ *  deleted (TEMP cleanup) or overwritten while it runs is written again, so
+ *  new clients keep finding the one daemon that serves this data dir. */
+function republishMissingDiscovery() {
+  if (!publishedEndpoints || shuttingDown || discoveryPid(DAEMON_DISCOVERY_PATH) === process.pid) return;
+  try {
+    publishDaemonDiscovery(publishedEndpoints);
+    log('daemon.json was missing or named another pid — re-published');
+  } catch (error) {
+    log(`daemon.json re-publish failed: ${error?.message || error}`);
+  }
+}
+
 /** Ready handshake for the spawner, plus the log-sink handoff pinned to the
  *  same boundary. Transport is already listening; signal ready before the heavy
  *  channel-worker connect so the spawner's ready wait never blocks on service
@@ -569,6 +708,7 @@ async function startChannelFrontDoor({ channelsRuntime, bootPhases }) {
   transport = createChannelTransport({
     handleCall: channelsRuntime.handleCall,
     agentBroker: agentDispatchBroker,
+    admitWork: admitOwnerWork,
     log,
     // The durable channel link lives in this file. Without it a restart loses
     // the pinned session (nothing to restore) and every catalog reports Remote
@@ -617,8 +757,27 @@ async function main() {
   // are per-user and fail closed if another account owns the configured path.
   ensurePrivateRuntimeRoot(RUNTIME_ROOT);
 
-  claimDaemonOwnership(bootPhases);
+  await claimDaemonOwnership(bootPhases);
   registerMemoryRuntimeLazy();
+  // Every in-process session runtime removes managed worktrees through the
+  // shared manager; its root cleanups drop the path-keyed caches (turn
+  // snapshots, code graph) of a removed worktree. Modules load on first use.
+  registerWorktreeCacheCleanups();
+  // Managed worktrees, off the boot path: finish interrupted deletions and
+  // creations, release stale leases and, with autoCleanup on, remove clean,
+  // merged worktrees no stored session retains (never one a session keeps).
+  void import('../runtime/shared/worktrees/maintenance.mjs')
+    .then((maintenance) => maintenance.reconcileWorktreesAtStartup())
+    .then((report) => {
+      const changed = report.removed.length + report.recovered.length + report.pruned.length;
+      if (changed || report.errors.length) {
+        log(
+          `worktree reconcile: removed ${report.removed.length}, recovered ${report.recovered.length}, ` +
+            `pruned ${report.pruned.length}, errors ${report.errors.length}`
+        );
+      }
+    })
+    .catch((error) => log(`worktree reconcile failed: ${error?.message || error}`));
   // The daemon owns prompt attachments; its census runs off the boot path
   // (first attempt after the store's start delay, then per its interval).
   void import('../runtime/attachments/store.mjs').then((store) => store.startAttachmentGc()).catch(() => {});
@@ -764,9 +923,21 @@ async function main() {
       } catch {}
     },
     onUpgradeRequested: requestDaemonReplacement,
+    admitWork: admitOwnerWork,
   });
   const sessionEndpoint = await bootPhases.measure('session-transport-start', () => sessionTransport.start());
-  publishDaemonDiscovery({ channel: { port, token }, session: sessionEndpoint });
+  const modelProxyEndpoint = await startModelProxyBridge(bootPhases);
+  // A boot whose holder stopped answering may have been superseded by a
+  // contender between beats; never publish over the winner's endpoint. An
+  // unreadable record (an antivirus lock) is not a takeover.
+  const ownerPid = Number(readSingletonOwner(OWNER_PATH).owner?.pid) || 0;
+  if (shuttingDown) return;
+  if (ownerPid && ownerPid !== process.pid) {
+    log(`owner record now names pid=${ownerPid} — exiting for attach before publishing`);
+    exitRecorder.setReason(`owner claim superseded by pid=${ownerPid} before publish`, 0);
+    process.exit(0);
+  }
+  publishDaemonDiscovery({ channel: { port, token }, session: sessionEndpoint, modelProxy: modelProxyEndpoint });
   bootPhases.mark('discovery-published');
   log(`session front door on 127.0.0.1:${sessionEndpoint.port}`);
 

package/src/standalone/desktop-service-registry.mjs

@@ -1,6 +1,8 @@
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { sanitizeForWire } from './session-wire-values.mjs';
+import { modelProxyClientMode } from '../runtime/shared/model-proxy-mode.mjs';
+import { getModelProxyChannel } from '../runtime/agent/orchestrator/providers/model-proxy-channel.mjs';
 
 const requireDesktopModule = createRequire(import.meta.url);
 
@@ -185,9 +187,24 @@ export class DesktopServiceRegistry {
     if (this.#closed) throw new Error('session service is closed');
     const token = subscriberToken(ctx);
     if (token) service.subscribers.add(token);
+    this.#syncModelProxyPresence();
     return { desktopId: service.desktopId };
   }
 
+  // Proxied model calls need a live desktop subscriber; tell the channel the
+  // moment the last one leaves instead of waiting for its claim timeout.
+  #syncModelProxyPresence() {
+    if (!modelProxyClientMode()) return;
+    let present = false;
+    for (const service of this.#servicesById.values()) {
+      if (service.subscribers.size) {
+        present = true;
+        break;
+      }
+    }
+    getModelProxyChannel().setClientPresent(present);
+  }
+
   // Every addressed call also (re)subscribes its caller to the service lane.
   #requireSubscribed(desktopId, ctx) {
     const service = this.#require(desktopId);
@@ -211,6 +228,7 @@ export class DesktopServiceRegistry {
 
   ready({ desktopId } = {}, ctx = null) {
     const { service, token } = this.#requireSubscribed(desktopId, ctx);
+    this.#syncModelProxyPresence();
     this.#onReady({ desktopId: service.desktopId, clientToken: token || null });
     return { ok: true };
   }
@@ -219,6 +237,7 @@ export class DesktopServiceRegistry {
     const service = this.#require(desktopId);
     const token = subscriberToken(ctx);
     if (token) service.subscribers.delete(token);
+    this.#syncModelProxyPresence();
     return { ok: true, unsubscribed: true };
   }
 
@@ -228,6 +247,7 @@ export class DesktopServiceRegistry {
     for (const service of this.#servicesById.values()) {
       service.subscribers.delete(token);
     }
+    this.#syncModelProxyPresence();
   }
 
   notifySessionRuntimeReleased(sessionId, reason) {

package/src/standalone/local-session-runtime.mjs

@@ -122,14 +122,17 @@ export async function createLocalSessionRuntime({
   model,
   effort,
   fast,
+  autoEffort,
   modelParameters,
   contextPercent,
+  contextTokens,
   selectedContextWindow,
   toolMode = 'full',
   remote = false,
   cwd,
   desktopSession,
   sessionProfile,
+  worktree,
   executeAgentControl,
 } = {}) {
   const startedAt = performance.now();
@@ -150,14 +153,18 @@ export async function createLocalSessionRuntime({
     model,
     effort,
     fast,
+    autoEffort,
     modelParameters,
     contextPercent,
+    contextTokens,
     selectedContextWindow,
     toolMode,
     remote,
     ...(cwd ? { cwd } : {}),
     ...(desktopSession ? { desktopSession } : {}),
     ...(sessionProfile && typeof sessionProfile === 'object' ? { sessionProfile } : {}),
+    // Session creation worktree intent; consumed by the workspace transition scope.
+    ...(worktree && typeof worktree === 'object' ? { worktree } : {}),
     ...(typeof executeAgentControl === 'function' ? { executeAgentControl } : {}),
   });
   bootProfile('session:create:runtime-ready', { ms: (performance.now() - startedAt).toFixed(1) });
@@ -396,6 +403,10 @@ export async function createLocalSessionRuntime({
     subscribeRuntimeNotifications,
   });
   Object.assign(bag, createSessionFlow(bag));
+  // Runtime-driven completion wakes (no attached surface acked the completion)
+  // get the same idle auto-clear as a user submit.
+  lifecycle.unsubscribeCompletionWakeGate =
+    runtime.setCompletionWakeGate?.(() => bag.autoClearBeforeWake()) || null;
   Object.assign(
     bag,
     createGoalContinuation({

package/src/standalone/session-client/attachment-calls.mjs

@@ -13,7 +13,7 @@ const URGENT_CALLS = new Set([
   'desktop.unsubscribe',
 ]);
 
-export function createAttachmentCalls({ request, port, serverToken, clientToken, stopStream, log }) {
+export function createAttachmentCalls({ request, port, serverToken, clientToken, stopStream, stopHeartbeat, log }) {
   let closed = false;
 
   async function call(name, args = {}, { timeoutMs = 300_000, callId = null } = {}) {
@@ -38,6 +38,7 @@ export function createAttachmentCalls({ request, port, serverToken, clientToken,
       // Preserve the daemon's machine-readable classification across the wire.
       const err = new Error(out.error);
       if (out.code) err.code = String(out.code);
+      if (out.details && typeof out.details === 'object') err.details = out.details;
       throw err;
     }
     return out?.result;
@@ -47,6 +48,7 @@ export function createAttachmentCalls({ request, port, serverToken, clientToken,
     if (closed) return;
     closed = true;
     stopStream();
+    stopHeartbeat?.();
     try {
       await request({
         port,

package/src/standalone/session-client/daemon-unavailable.mjs

@@ -0,0 +1,62 @@
+// The error ensureDaemon throws when no session endpoint appeared before its
+// deadline. The first line is the stable message callers and tests match; the
+// lines below carry what the last pass observed — an unanswered discovery, an
+// owner that never published, the newest candidate's exit and first stderr
+// error — so the desktop error card's details name the cause, not only the
+// symptom.
+export const DAEMON_UNAVAILABLE_MESSAGE = 'daemon session endpoint is unavailable';
+
+function exitCodeText(code) {
+  // Windows reports NTSTATUS crash codes as large unsigned values.
+  return Number.isSafeInteger(code) && code > 0x7fffffff ? `0x${code.toString(16).toUpperCase()}` : String(code);
+}
+
+function candidateLines(candidate, { attempt, maxAttempts, now }) {
+  const head = `last daemon candidate (attempt ${attempt} of ${maxAttempts})`;
+  if (!candidate.pid) return [`${head} failed to spawn: ${candidate.error || 'unknown error'}`];
+  let state;
+  if (candidate.exitedAt) {
+    state =
+      `exited code=${candidate.exitCode === null ? '-' : exitCodeText(candidate.exitCode)}` +
+      ` signal=${candidate.exitSignal || '-'} after ${candidate.uptimeMs ?? '?'}ms` +
+      (candidate.exitReason ? ` (${candidate.exitReason})` : '');
+  } else if (candidate.ready) {
+    state = 'reported ready but its endpoint never answered';
+  } else {
+    const spawnedAt = Date.parse(candidate.spawnedAt || '');
+    state = `still running, not ready ${Number.isFinite(spawnedAt) ? now - spawnedAt : '?'}ms after spawn`;
+  }
+  const lines = [`${head}: pid=${candidate.pid} ${state}`];
+  if (candidate.stderrErrorLine) lines.push(`first stderr error: ${candidate.stderrErrorLine}`);
+  else if (candidate.stderrLastLine) lines.push(`last stderr line: ${candidate.stderrLastLine}`);
+  if (candidate.stderrPath) lines.push(`stderr capture: ${candidate.stderrPath}`);
+  return lines;
+}
+
+export function daemonUnavailableError({
+  discovery = null,
+  owner = null,
+  candidate = null,
+  spawnAttempts = 0,
+  maxSpawnAttempts = 0,
+  captureDir,
+  now = Date.now(),
+}) {
+  const lines = [DAEMON_UNAVAILABLE_MESSAGE];
+  if (discovery) lines.push(`discovery: pid=${discovery.pid} port=${discovery.port} did not answer its health check`);
+  if (owner) {
+    lines.push(
+      `daemon owner: pid=${owner.pid} (claimed ${owner.claimedAt || 'at an unknown time'}) held the lock` +
+        ' but never published an endpoint'
+    );
+  }
+  if (candidate) {
+    lines.push(...candidateLines(candidate, { attempt: spawnAttempts, maxAttempts: maxSpawnAttempts, now }));
+  } else {
+    lines.push(`no daemon candidate was spawned (spawn attempts allowed: ${maxSpawnAttempts})`);
+  }
+  lines.push(`daemon crash captures: ${captureDir}`);
+  const error = new Error(lines.join('\n'));
+  error.daemonUnavailable = { discovery, owner, candidate, spawnAttempts, captureDir };
+  return error;
+}

package/src/standalone/session-client/lease-heartbeat.mjs

@@ -0,0 +1,47 @@
+// session-client/lease-heartbeat.mjs
+// A remote attachment has no local pid the daemon can probe, so its liveness
+// is a lease the client renews: POST /client/heartbeat every `heartbeatMs`,
+// one request in flight at a time, each bounded by heartbeatMs / 2. A failed
+// beat is only logged — the next tick retries, and the stream's own recovery
+// decides when the attachment is truly lost.
+import { clampLeaseMs } from '../session-transport/client-registry/client-grace.mjs';
+
+export function createLeaseHeartbeat({ request, port, serverToken, clientToken, heartbeatMs = 10_000, leaseMs, log }) {
+  // Always beat at least three times per (server-clamped) lease.
+  heartbeatMs = Math.min(heartbeatMs, Math.floor(clampLeaseMs(leaseMs) / 3));
+  let timer = null;
+  let inFlight = false;
+
+  async function beat() {
+    if (inFlight) return;
+    inFlight = true;
+    try {
+      await request({
+        port,
+        token: serverToken,
+        method: 'POST',
+        path: '/client/heartbeat',
+        body: { token: clientToken },
+        timeoutMs: heartbeatMs / 2,
+        control: true,
+      });
+    } catch (error) {
+      log(`heartbeat failed: ${error?.message || error}`);
+    } finally {
+      inFlight = false;
+    }
+  }
+
+  function start() {
+    if (timer) return;
+    timer = setInterval(beat, heartbeatMs);
+    timer.unref?.();
+  }
+
+  function stop() {
+    if (timer) clearInterval(timer);
+    timer = null;
+  }
+
+  return { start, stop };
+}