@adhdev/daemon-core 1.0.28-rc.10 → 1.0.28-rc.12

package/dist/index.mjs

@@ -786,10 +786,10 @@ function readInjected(value) {
 }
 function getDaemonBuildInfo() {
   if (cached) return cached;
-  const commit = readInjected(true ? "e4b8cfd97ab9fbe458b61198b091a9051da87a6e" : void 0) ?? "unknown";
-  const commitShort = readInjected(true ? "e4b8cfd9" : void 0) ?? (commit !== "unknown" ? commit.slice(0, 7) : "unknown");
-  const version = readInjected(true ? "1.0.28-rc.10" : void 0) ?? readInjected(typeof process !== "undefined" ? process.env?.ADHDEV_PKG_VERSION : void 0) ?? "unknown";
-  const builtAt = readInjected(true ? "2026-07-26T03:08:22.566Z" : void 0);
+  const commit = readInjected(true ? "6f38d1460a02018ef53a3ecdf306004005b44310" : void 0) ?? "unknown";
+  const commitShort = readInjected(true ? "6f38d146" : void 0) ?? (commit !== "unknown" ? commit.slice(0, 7) : "unknown");
+  const version = readInjected(true ? "1.0.28-rc.12" : void 0) ?? readInjected(typeof process !== "undefined" ? process.env?.ADHDEV_PKG_VERSION : void 0) ?? "unknown";
+  const builtAt = readInjected(true ? "2026-07-26T08:24:03.072Z" : void 0);
   cached = builtAt ? { commit, commitShort, version, builtAt } : { commit, commitShort, version };
   return cached;
 }
@@ -27269,6 +27269,11 @@ function validateCondition(c, sectionIds, path46) {
     return errs;
   }
   if ("cursor_above" in w && "changed" in w) return errs;
+  if ("signal" in w) {
+    if (typeof w.signal !== "string" || !w.signal.trim()) errs.push(`${path46}.signal must be a non-empty string`);
+    if (w.equals !== void 0 && typeof w.equals !== "boolean") errs.push(`${path46}.equals must be a boolean`);
+    return errs;
+  }
   if ("elapsed_ms" in w) {
     if (typeof w.elapsed_ms !== "number") errs.push(`${path46}.elapsed_ms must be a number`);
     return errs;
@@ -27583,6 +27588,51 @@ var init_evaluator = __esm({
   }
 });
 
+// src/providers/spec/signal-envelope.ts
+function unavailableSignalSnapshot(now, reason, profile) {
+  return {
+    kind: SIGNAL_SNAPSHOT_KIND,
+    sampledAt: now,
+    available: false,
+    unavailableReason: reason,
+    ...profile ? { profile } : {},
+    signals: { final_assistant_present: null, in_turn_progress: null, transcript_growing: null },
+    detail: { msgCount: 0, sourceMtimeMs: 0, ageMs: null }
+  };
+}
+function evaluateSignalLeaf(cond, snapshot) {
+  const expected = cond.equals ?? true;
+  if (!snapshot || !snapshot.available) {
+    const why = !snapshot ? "no snapshot" : `unavailable(${snapshot.unavailableReason ?? "unknown"})`;
+    return {
+      value: null,
+      shadowResult: null,
+      detail: `signal ${cond.signal} ${why} \u2192 fail-open`
+    };
+  }
+  const raw = Object.prototype.hasOwnProperty.call(snapshot.signals, cond.signal) ? snapshot.signals[cond.signal] : null;
+  if (raw === null || raw === void 0) {
+    return {
+      value: null,
+      shadowResult: null,
+      detail: `signal ${cond.signal} unknown \u2192 fail-open`
+    };
+  }
+  const shadowResult = raw === expected;
+  return {
+    value: raw,
+    shadowResult,
+    detail: `signal ${cond.signal}=${raw} expected=${expected} \u2192 ${shadowResult}`
+  };
+}
+var SIGNAL_SNAPSHOT_KIND;
+var init_signal_envelope = __esm({
+  "src/providers/spec/signal-envelope.ts"() {
+    "use strict";
+    SIGNAL_SNAPSHOT_KIND = "adhdev:fsm/signal-snapshot@0";
+  }
+});
+
 // src/providers/spec/fsm-evaluator.ts
 var fsm_evaluator_exports = {};
 __export(fsm_evaluator_exports, {
@@ -27616,24 +27666,74 @@ function isAny(c) {
 function isNot(c) {
   return "not" in c;
 }
-function evalCond(cond, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId) {
+function isSignal(c) {
+  return "signal" in c;
+}
+function containsSignal(c) {
+  if (isSignal(c)) return true;
+  if (isAll(c)) return c.all.some(containsSignal);
+  if (isAny(c)) return c.any.some(containsSignal);
+  if (isNot(c)) return containsSignal(c.not);
+  return false;
+}
+function foldShadow(cond) {
+  if (cond.kind === "signal") {
+    const s2 = cond.signal;
+    if (s2 && s2.shadowResult !== null && s2.shadowResult !== void 0) {
+      return { value: s2.shadowResult, unknown: false };
+    }
+    return { value: true, unknown: true };
+  }
+  if (cond.kind === "not" && cond.children?.length) {
+    const c = foldShadow(cond.children[0]);
+    return { value: !c.value, unknown: c.unknown };
+  }
+  if (cond.kind === "all" && cond.children) {
+    const kids = cond.children.map(foldShadow);
+    if (kids.some((k) => !k.unknown && !k.value)) return { value: false, unknown: false };
+    if (kids.some((k) => k.unknown)) return { value: true, unknown: true };
+    return { value: true, unknown: false };
+  }
+  if (cond.kind === "any" && cond.children) {
+    const kids = cond.children.map(foldShadow);
+    if (kids.some((k) => !k.unknown && k.value)) return { value: true, unknown: false };
+    if (kids.some((k) => k.unknown)) return { value: false, unknown: true };
+    return { value: false, unknown: false };
+  }
+  return { value: cond.result, unknown: false };
+}
+function evalCond(cond, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId, signalSnapshot) {
   if (isAll(cond)) {
-    const children = cond.all.map((c) => evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId));
+    const children = cond.all.map((c) => evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId, signalSnapshot));
     const result = children.every((c) => c.result);
     const remainingMs = result ? 0 : Math.max(0, ...children.filter((c) => !c.result).map((c) => c.remainingMs ?? 0));
     return { kind: "all", result, detail: `all(${children.length})`, remainingMs, children };
   }
   if (isAny(cond)) {
-    const children = cond.any.map((c) => evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId));
+    const children = cond.any.map((c) => evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId, signalSnapshot));
     const result = children.some((c) => c.result);
     const pending = children.filter((c) => !c.result).map((c) => c.remainingMs ?? Infinity);
     const remainingMs = result ? 0 : pending.length ? Math.min(...pending) : 0;
     return { kind: "any", result, detail: `any(${children.length})`, remainingMs: Number.isFinite(remainingMs) ? remainingMs : 0, children };
   }
   if (isNot(cond)) {
-    const child = evalCond(cond.not, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId);
+    const child = evalCond(cond.not, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId, signalSnapshot);
     return { kind: "not", result: !child.result, detail: `not`, remainingMs: 0, children: [child] };
   }
+  if (isSignal(cond)) {
+    const leaf = evaluateSignalLeaf(cond, signalSnapshot);
+    return {
+      kind: "signal",
+      result: true,
+      detail: `${leaf.detail} (stage0 shadow \u2014 pass-through)`,
+      signal: {
+        name: cond.signal,
+        available: !!signalSnapshot?.available,
+        value: leaf.value,
+        shadowResult: leaf.shadowResult
+      }
+    };
+  }
   if (isElapsed(cond)) {
     const age = clock.now - clock.stateEnteredAt;
     const result = age >= cond.elapsed_ms;
@@ -27672,7 +27772,7 @@ function fromLabel(t) {
   const from = Array.isArray(t.from) ? t.from.join("|") : t.from;
   return t.label ?? `${from}\u2192${t.to}`;
 }
-function evaluateFsm(spec, currentStateId, screenText, cursor, prevLines, clock) {
+function evaluateFsm(spec, currentStateId, screenText, cursor, prevLines, clock, signalSnapshot) {
   const legacyTrace = [];
   const lines = screenText.split("\n").map((l) => l.endsWith("\r") ? l.slice(0, -1) : l);
   const cleanScreen = lines.join("\n");
@@ -27688,7 +27788,7 @@ function evaluateFsm(spec, currentStateId, screenText, cursor, prevLines, clock)
     let cond;
     let condResult = true;
     if (t.when) {
-      cond = evalCond(t.when, sections, cleanScreen, cursor, prevLines, clock, legacyTrace, `${currentStateId}\u2192${t.to}`);
+      cond = evalCond(t.when, sections, cleanScreen, cursor, prevLines, clock, legacyTrace, `${currentStateId}\u2192${t.to}`, signalSnapshot);
       condResult = cond.result;
     }
     const fires = holdSatisfied && condResult;
@@ -27703,6 +27803,14 @@ function evaluateFsm(spec, currentStateId, screenText, cursor, prevLines, clock)
       fires,
       priority: t.priority ?? 0
     };
+    if (t.when && containsSignal(t.when) && cond) {
+      const folded = foldShadow(cond);
+      te.shadow = {
+        condResult: folded.value,
+        fires: holdSatisfied && folded.value,
+        unknown: folded.unknown
+      };
+    }
     transitions.push(te);
     if (fires && !fired) fired = te;
   }
@@ -27725,6 +27833,7 @@ var init_fsm_evaluator = __esm({
     "use strict";
     init_evaluator();
     init_fsm_types();
+    init_signal_envelope();
     WHOLE_SCREEN = -1;
   }
 });
@@ -45073,12 +45182,21 @@ async function runDaemonUpgradeHelper(payload) {
     appendUpgradeLog(`Waiting for parent pid ${payload.parentPid} to exit`);
     await waitForPidExit(payload.parentPid, 15e3);
   }
-  if (process.platform === "win32") {
+  if (process.platform === "win32" || payload.killSessionHost === true) {
     await stopSessionHostProcesses(sessionHostAppName);
   } else {
     appendUpgradeLog("POSIX \u2014 session-host left running (survives upgrade; sessions rebind on next boot)");
   }
   removeDaemonPidFile();
+  if (payload.skipInstall) {
+    appendUpgradeLog("Restart-only mode \u2014 package install skipped, re-spawning daemon");
+    spawnDetachedDaemonRestart(restartArgv, payload.cwd);
+    try {
+      fs15.unlinkSync(getUpgradeFailureNoticePath());
+    } catch {
+    }
+    return;
+  }
   const instanceDir = resolveInstanceDir();
   const windowsInstallerLayout = resolveWindowsInstallerLayout({
     homeDir: os14.homedir(),
@@ -45197,6 +45315,13 @@ async function runDaemonUpgradeHelper(payload) {
     cleanupStaleGlobalInstallDirs(payload.packageName, installCommand.surface);
     appendUpgradeLog("Post-install staging cleanup complete");
   }
+  spawnDetachedDaemonRestart(restartArgv, payload.cwd);
+  try {
+    fs15.unlinkSync(getUpgradeFailureNoticePath());
+  } catch {
+  }
+}
+function spawnDetachedDaemonRestart(restartArgv, cwd) {
   if (restartArgv.length > 0) {
     const env = { ...process.env };
     delete env[UPGRADE_HELPER_ENV];
@@ -45205,17 +45330,13 @@ async function runDaemonUpgradeHelper(payload) {
       detached: true,
       stdio: "ignore",
       windowsHide: true,
-      cwd: payload.cwd || process.cwd(),
+      cwd: cwd || process.cwd(),
       env
     });
     child.unref();
   } else {
     appendUpgradeLog("No restart argv provided; upgrade completed without restart");
   }
-  try {
-    fs15.unlinkSync(getUpgradeFailureNoticePath());
-  } catch {
-  }
 }
 async function maybeRunDaemonUpgradeHelperFromEnv() {
   const raw = process.env[UPGRADE_HELPER_ENV];
@@ -45308,6 +45429,41 @@ var daemonLifecycleHandlers = {
       return { success: false, error: e.message };
     }
   },
+  // Restart-only path (mesh restart_daemon_node mode="restart"): re-spawn the
+  // daemon WITHOUT the npm reinstall daemon_upgrade performs. Used to reset
+  // daemon state (memory leaks, zombie sessions, wedged internals) when the
+  // version is already correct — downtime drops to the detached re-spawn.
+  // killSessionHost is an explicit opt-in hard refresh (see upgrade-helper).
+  daemon_restart: async (ctx, args) => {
+    LOG.info("Restart", "Restart-only requested (no package reinstall)");
+    try {
+      const isStandalone = ctx.deps.packageName === "@adhdev/daemon-standalone" || process.argv[1]?.includes("daemon-standalone");
+      const pkgName = isStandalone ? "@adhdev/daemon-standalone" : "adhdev";
+      const killSessionHost = args?.killSessionHost === true;
+      if (killSessionHost) {
+        LOG.warn("Restart", "killSessionHost requested \u2014 session-host will be stopped and ALL hosted sessions destroyed");
+      }
+      spawnDetachedDaemonUpgradeHelper({
+        packageName: pkgName,
+        targetVersion: "",
+        parentPid: process.pid,
+        restartArgv: process.argv.slice(1),
+        cwd: process.cwd(),
+        sessionHostAppName: process.env.ADHDEV_SESSION_HOST_NAME || "adhdev",
+        skipInstall: true,
+        killSessionHost
+      });
+      LOG.info("Restart", "Scheduled detached restart-only helper");
+      setTimeout(() => {
+        LOG.info("Restart", "Exiting daemon so detached helper can re-spawn it...");
+        process.exit(0);
+      }, 3e3);
+      return { success: true, restarted: true, restarting: true, mode: "restart", killSessionHost };
+    } catch (e) {
+      LOG.error("Restart", `Failed: ${e.message}`);
+      return { success: false, error: e.message };
+    }
+  },
   set_machine_nickname: async (_ctx, args) => {
     const nickname = args?.nickname;
     updateConfig({ machineNickname: nickname || null });
@@ -45804,6 +45960,93 @@ import * as fs24 from "fs";
 init_hash();
 init_transcript_evidence();
 
+// src/providers/transcript-signal-source.ts
+init_logger();
+init_signal_envelope();
+var TranscriptSignalSource = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /** msgCount seen at the previous update — drives in_turn_progress. */
+  prevMsgCount = -1;
+  /** Fingerprint of the last LOGGED snapshot, so the shadow log fires on
+   *  change only (a quiet session must not spam one line per read). */
+  lastLoggedFingerprint = "";
+  /**
+   * Normalize one daemon read into a SignalSnapshot and emit the Stage-0
+   * shadow log when the observation changed. Pure w.r.t. the outside world:
+   * the only side effect is the (change-gated) log line. Returns the
+   * snapshot the caller should inject into the FSM driver.
+   */
+  update(sample, now = Date.now()) {
+    const snapshot = this.buildSnapshot(sample, now);
+    this.logOnChange(snapshot);
+    return snapshot;
+  }
+  /** Pure normalization — separated from update() so tests can assert the
+   *  envelope without touching the log path. */
+  buildSnapshot(sample, now) {
+    const profileRef = { class: this.opts.profile.class, timing: this.opts.profile.timing };
+    if (this.opts.profile.class !== "native-source") {
+      return unavailableSignalSnapshot(now, "no_native_source", profileRef);
+    }
+    if (sample.error) {
+      return unavailableSignalSnapshot(now, "error", profileRef);
+    }
+    const probe = sample.probe;
+    if (!probe || !Array.isArray(sample.messages)) {
+      return unavailableSignalSnapshot(now, "unresolved", profileRef);
+    }
+    const msgCount = typeof probe.msgCount === "number" && Number.isFinite(probe.msgCount) ? probe.msgCount : sample.messages.length;
+    const sourceMtimeMs = typeof probe.sourceMtimeMs === "number" && Number.isFinite(probe.sourceMtimeMs) ? probe.sourceMtimeMs : 0;
+    const ageMs = sourceMtimeMs > 0 ? Math.max(0, now - sourceMtimeMs) : null;
+    let turnStartedAt;
+    try {
+      turnStartedAt = this.opts.turnStartedAt?.();
+    } catch {
+      turnStartedAt = void 0;
+    }
+    let finalAssistant = null;
+    try {
+      finalAssistant = this.opts.finalAssistantPresent(sample.messages, turnStartedAt);
+    } catch {
+      finalAssistant = null;
+    }
+    const countAdvanced = this.prevMsgCount >= 0 && msgCount > this.prevMsgCount;
+    const fresh = ageMs !== null && ageMs < this.opts.growthQuietMs;
+    const inTurnProgress = countAdvanced || fresh;
+    const transcriptGrowing = ageMs === null ? null : fresh;
+    this.prevMsgCount = msgCount;
+    return {
+      kind: SIGNAL_SNAPSHOT_KIND,
+      sampledAt: now,
+      available: true,
+      profile: profileRef,
+      signals: {
+        final_assistant_present: finalAssistant,
+        in_turn_progress: inTurnProgress,
+        transcript_growing: transcriptGrowing
+      },
+      detail: { msgCount, sourceMtimeMs, ageMs }
+    };
+  }
+  /** Stage-0 shadow log: emit one line when the normalized observation
+   *  CHANGES. This log is the Stage 1-3 judgment input ("which signals were
+   *  actually observable, and when"), so it carries the full signal set —
+   *  but only on change, so a steady-state session stays quiet. */
+  logOnChange(snapshot) {
+    const s2 = snapshot.signals;
+    const fingerprint = snapshot.available ? `1|fa=${s2.final_assistant_present}|tp=${s2.in_turn_progress}|tg=${s2.transcript_growing}|n=${snapshot.detail.msgCount}` : `0|${snapshot.unavailableReason ?? "unknown"}`;
+    if (fingerprint === this.lastLoggedFingerprint) return;
+    this.lastLoggedFingerprint = fingerprint;
+    const age = snapshot.detail.ageMs === null ? "n/a" : `${snapshot.detail.ageMs}ms`;
+    LOG.info(
+      "TranscriptSignalSource",
+      `[${this.opts.label}] [shadow] signals available=${snapshot.available}` + (snapshot.available ? ` final_assistant_present=${s2.final_assistant_present} in_turn_progress=${s2.in_turn_progress} transcript_growing=${s2.transcript_growing} msgCount=${snapshot.detail.msgCount} age=${age}` : ` reason=${snapshot.unavailableReason ?? "unknown"}`)
+    );
+  }
+};
+
 // src/providers/spec/route.ts
 init_provider_cli_adapter();
 import * as fs22 from "fs";
@@ -46168,6 +46411,15 @@ var FsmDriver = class {
    *  transition — the rich pre-transition table that lastFsmEval only keeps
    *  for the single most recent evaluation. Separate from stateHistory. */
   fsmSnapshotHistory = [];
+  /** TX-FSM Stage 0 (shadow): the latest daemon-injected signal observation.
+   *  Read by evalFsmNow for the shadow verdict of `signal` conditions ONLY —
+   *  the Stage-0 pass-through in the evaluator means it can never alter
+   *  which transition fires. */
+  signalObservation = null;
+  /** Per-transition last-logged shadow divergence (`${from}→${to}` → whether
+   *  the shadow verdict currently disagrees with the real one), so the
+   *  shadow log emits on FLIP only, not every frame. */
+  shadowDivergenceLast = /* @__PURE__ */ new Map();
   subscribe(listener) {
     this.listeners.add(listener);
     return () => {
@@ -46240,6 +46492,16 @@ var FsmDriver = class {
   updateMeta(meta, replace = false) {
     this.adapter.updateMeta(meta, replace);
   }
+  /**
+   * TX-FSM Stage 0 (shadow): receive the daemon-normalized signal
+   * observation. The driver stores it verbatim — it does NOT poll, parse,
+   * or read anything itself (generic-PTY-engine boundary). The observation
+   * only feeds the shadow verdict of `signal` conditions; the evaluator's
+   * Stage-0 pass-through guarantees it cannot change a transition.
+   */
+  setSignalObservation(snapshot) {
+    this.signalObservation = snapshot ?? null;
+  }
   snapshot() {
     return this.adapter.snapshot();
   }
@@ -46430,7 +46692,35 @@ var FsmDriver = class {
   }
   evalFsmNow(screen, cursor, now) {
     const prev = this.prevScreenLines.length > 0 ? this.prevScreenLines : void 0;
-    return evaluateFsm(this.spec, this.currentStateId, screen, cursor, prev, this.buildClock(now));
+    return evaluateFsm(this.spec, this.currentStateId, screen, cursor, prev, this.buildClock(now), this.signalObservation);
+  }
+  /**
+   * TX-FSM Stage 0 (shadow): compare each signal-guarded transition's
+   * counterfactual verdict against the real (PTY-only) one and log on FLIP.
+   * This is the "만약 적용했다면" half of the shadow log — the Stage 1-3
+   * evidence for whether signal gating would have changed any verdict, and
+   * in which direction. Read-only: runs after the evaluation is complete
+   * and never feeds back into it.
+   */
+  logShadowDivergence(ev) {
+    for (const t of ev.transitions) {
+      if (!t.shadow) continue;
+      const key2 = `${this.currentStateId}\u2192${t.to}`;
+      const diverges = t.shadow.fires !== t.fires;
+      if ((this.shadowDivergenceLast.get(key2) ?? false) === diverges) continue;
+      this.shadowDivergenceLast.set(key2, diverges);
+      if (diverges) {
+        LOG.info(
+          "FsmDriver",
+          `[${this.specTag()}] [shadow] ${key2} (${t.label}): real fires=${t.fires} but signal-gated verdict would be fires=${t.shadow.fires} (shadowCond=${t.shadow.condResult}${t.shadow.unknown ? ", signal unknown/fail-open" : ""})`
+        );
+      } else {
+        LOG.info(
+          "FsmDriver",
+          `[${this.specTag()}] [shadow] ${key2} (${t.label}): shadow verdict realigned with real fires=${t.fires}`
+        );
+      }
+    }
   }
   reevaluate(forceEmit = false) {
     const now = Date.now();
@@ -46441,6 +46731,7 @@ var FsmDriver = class {
     const ev = this.evalFsmNow(screen, cursor, now);
     this.lastFsmEval = ev;
     this.prevScreenLines = currentLines;
+    this.logShadowDivergence(ev);
     if (ev.fired) {
       this.commitTransition(ev.fired, now, ev);
       this.emitStateChanged(forceEmit);
@@ -49089,6 +49380,18 @@ var SpecCliAdapter = class _SpecCliAdapter {
   }
   refreshProviderDefinition() {
   }
+  /**
+   * TX-FSM Stage 0 (shadow): forward the daemon's normalized signal
+   * observation into the FSM driver. Observation-only — failures here must
+   * never break the adapter, and the driver treats the envelope as a pure
+   * injected value (no reads cross the engine boundary).
+   */
+  setSignalObservation(snapshot) {
+    try {
+      this.driver.setSignalObservation?.(snapshot);
+    } catch {
+    }
+  }
   handleEvent(ev) {
     this.lastEvent = ev;
     switch (ev.kind) {
@@ -50134,18 +50437,20 @@ var CliProviderInstance = class _CliProviderInstance {
   // MESH_WORKER_STALL_REFIRE_COOLDOWN_MS between successive emissions across
   // anchor re-arms (the per-anchor guard only covers a single continuous stall).
   meshStallLastFiredAt = -1;
-  // KIMI-MESH-COMPLETION-EMIT (axis 1): the native-source transcript progress
-  // fingerprint (record count + source mtime) observed the LAST time the stall
-  // watchdog checked a native-source provider (transcriptAuthority=provider — e.g.
-  // kimi wire.jsonl). A pure-PTY native-source worker running a long, screen-quiet
-  // tool (no viewport bytes for minutes) looks stalled by the lastOutputAt clock
-  // even though its transcript file is still growing. Before firing the stall, we
-  // compare the current transcript fingerprint against this snapshot; if the
-  // transcript advanced, the "stall" is a false positive of PTY-render stasis, so
-  // we re-arm the anchor instead of paging the coordinator (whose no_progress
-  // handling can lead to the worker being stopped mid-work → completion never
-  // emitted). null = not yet sampled for this session/anchor.
-  meshStallNativeTranscriptSample = null;
+  // KIMI-MESH-COMPLETION-EMIT (axis 1) — TX-FSM Stage 1: whether the stall
+  // watchdog has consumed a usable native-transcript SIGNAL SNAPSHOT for the
+  // current stall episode. A pure-PTY native-source worker running a long,
+  // screen-quiet tool (no viewport bytes for minutes) looks stalled by the
+  // lastOutputAt clock even though its transcript file is still growing.
+  // Before firing the stall, the watchdog consults the shared
+  // TranscriptSignalSource's in_turn_progress signal; if the transcript is
+  // advancing, the "stall" is a false positive of PTY-render stasis, so we
+  // re-arm the anchor instead of paging the coordinator (whose no_progress
+  // handling can lead to the worker being stopped mid-work → completion
+  // never emitted). The FIRST usable sample of an episode still re-arms
+  // unconditionally (no episode-scoped baseline exists yet to prove stasis
+  // against) — the historical `!prev → advanced` semantics, preserved.
+  meshStallTranscriptSignalSampled = false;
   // FALSE-IDLE continuity epoch: monotonically bumped on EVERY entry into a busy
   // phase (→generating or →waiting_approval). The completedDebouncePending snapshots
   // this value at arm time (busyEpochAtArm); the flush guard requires it UNCHANGED
@@ -50943,6 +51248,17 @@ var CliProviderInstance = class _CliProviderInstance {
   completedDebounceTimer = null;
   completedDebouncePending = null;
   lastExternalCompletionProbe = null;
+  /** TX-FSM: lazily-created transcript signal normalizer. Fed ONLY by
+   *  transcript reads this instance already performs — it adds zero I/O.
+   *  Stage 0: its output was a pure shadow observation for the FSM driver.
+   *  Stage 1: the instance's own stall/growth-hold judgments consume the
+   *  normalized snapshot too (single source of truth). */
+  transcriptSignalSource = null;
+  /** TX-FSM Stage 1: the latest snapshot the source produced (set inside
+   *  publishTranscriptSignalObservation). Consumed the same tick by the
+   *  stall-path / growth-hold judgments via probeNativeTranscriptSignals —
+   *  never treated as fresh across ticks. */
+  lastTranscriptSignalSnapshot = null;
   /**
    * The final assistant summary of the last completed turn, cached at
    * completion-emit time. For a native-source provider (antigravity) whose
@@ -51108,6 +51424,7 @@ var CliProviderInstance = class _CliProviderInstance {
     });
     if (restoredHistory.source !== "provider-native") {
       this.lastExternalCompletionProbe = null;
+      this.publishTranscriptSignalObservation(null);
       return null;
     }
     this.lastExternalCompletionProbe = buildExternalTranscriptProbe(
@@ -51115,8 +51432,55 @@ var CliProviderInstance = class _CliProviderInstance {
       restoredHistory.sourcePath,
       restoredHistory.sourceMtimeMs
     );
+    this.publishTranscriptSignalObservation(restoredHistory.messages);
     return restoredHistory.messages;
   }
+  /**
+   * TX-FSM: normalize the transcript read that JUST happened into a
+   * SignalSnapshot. Stage 0 injected it into the FSM driver as a pure
+   * shadow observation (daemon → SpecCliAdapter → FsmDriver); Stage 1
+   * additionally caches it (lastTranscriptSignalSnapshot) so the instance's
+   * OWN stall/growth-hold judgments consume the SAME normalized snapshot
+   * instead of re-running private transcript scans. Fed ONLY by reads this
+   * method's caller already performs — it adds zero I/O, so the getState()
+   * zero-native-read invariant and the stall-path read cadence are
+   * untouched. The source update runs regardless of the adapter hook so a
+   * non-spec provider still produces the instance-side snapshot (the FSM
+   * injection is simply skipped there). Fail-open end to end — an
+   * unresolved transcript or any throw degrades to "no observation", never
+   * to a wedge.
+   */
+  publishTranscriptSignalObservation(messages, error = false) {
+    try {
+      if (!this.transcriptSignalSource) {
+        this.transcriptSignalSource = new TranscriptSignalSource({
+          label: this.type,
+          // Choke point: class/timing come from the P0 profile
+          // resolver, never from raw predicates or provider names.
+          profile: resolveTranscriptAuthorityProfile(this.provider),
+          turnStartedAt: () => {
+            const t = this.adapter?.currentTurnStartedAt;
+            if (typeof t === "number" && Number.isFinite(t)) return t;
+            return this.meshTaskInjectedAt > 0 ? this.meshTaskInjectedAt : void 0;
+          },
+          // Reuse the exact completion machinery (I1) for the
+          // final_assistant_present signal rather than duplicating
+          // the message scan.
+          finalAssistantPresent: (msgs, ts2) => this.completionHasFinalAssistantMessage(msgs, ts2),
+          growthQuietMs: MISSING_ASSISTANT_TRANSCRIPT_GROWTH_QUIET_MS
+        });
+      }
+      const snapshot = this.transcriptSignalSource.update(
+        { messages, probe: this.lastExternalCompletionProbe, error }
+      );
+      this.lastTranscriptSignalSnapshot = snapshot;
+      const adapter = this.adapter;
+      if (typeof adapter?.setSignalObservation === "function") {
+        adapter.setSignalObservation(snapshot);
+      }
+    } catch {
+    }
+  }
   /**
    * The content of the LAST visible assistant bubble in a message list, or ''
    * when the tail is not an assistant reply. Skips trailing system/tool/activity
@@ -51606,17 +51970,17 @@ var CliProviderInstance = class _CliProviderInstance {
     const threshold = turnActive ? _CliProviderInstance.MESH_WORKER_STALL_TURN_THRESHOLD_MS : _CliProviderInstance.MESH_WORKER_STALL_IDLE_THRESHOLD_MS;
     const stalledMs = now - this.meshStallAnchorAt;
     if (stalledMs < threshold) return;
-    const nativeSample = this.sampleNativeTranscriptProgress();
-    if (nativeSample) {
-      const prev = this.meshStallNativeTranscriptSample;
-      const advanced = !prev || nativeSample.msgCount > prev.msgCount || nativeSample.sourceMtimeMs > prev.sourceMtimeMs;
-      this.meshStallNativeTranscriptSample = nativeSample;
-      if (advanced) {
+    const transcriptSignals = this.probeNativeTranscriptSignals();
+    if (transcriptSignals?.snapshot?.available === true) {
+      const firstSampleThisEpisode = !this.meshStallTranscriptSignalSampled;
+      this.meshStallTranscriptSignalSampled = true;
+      const signalDetail = transcriptSignals.snapshot.detail;
+      if (firstSampleThisEpisode || transcriptSignals.snapshot.signals.in_turn_progress === true) {
         if (this.isMeshWorkerSession()) {
           traceMeshEventDrop(
             "mesh_worker_stall_transcript_advancing",
             this.meshTraceCtx("monitor:no_progress"),
-            `msgCount=${nativeSample.msgCount} sourceMtime=${nativeSample.sourceMtimeMs} (PTY quiet ${Math.round(stalledMs / 1e3)}s but transcript advancing)`
+            `msgCount=${signalDetail.msgCount} sourceMtime=${signalDetail.sourceMtimeMs} (PTY quiet ${Math.round(stalledMs / 1e3)}s but transcript advancing)`
           );
         }
         this.meshStallAnchorAt = now;
@@ -51624,7 +51988,7 @@ var CliProviderInstance = class _CliProviderInstance {
         return;
       }
     }
-    if (this.tryReconcileTranscriptCompletionForStall(observedStatus)) {
+    if (this.tryReconcileTranscriptCompletionForStall(observedStatus, transcriptSignals)) {
       this.meshStallEmittedForAnchor = true;
       return;
     }
@@ -51664,38 +52028,45 @@ var CliProviderInstance = class _CliProviderInstance {
     this.meshStallEmittedForAnchor = false;
     this.meshStallTurnActiveLast = void 0;
     this.meshStallLastFiredAt = -1;
-    this.meshStallNativeTranscriptSample = null;
+    this.meshStallTranscriptSignalSampled = false;
   }
+  /** The result of one native-transcript signal probe: the normalized
+   *  snapshot the shared TranscriptSignalSource produced from the read, and
+   *  the very messages it was normalized from (so a judgment site can pull
+   *  a payload — e.g. the final summary — from the SAME read with zero
+   *  added I/O). */
   /**
-   * KIMI-MESH-COMPLETION-EMIT (axis 1). For a native-source provider
-   * (transcriptAuthority=provider — its authoritative history is an on-disk
-   * transcript file, e.g. kimi's wire.jsonl), sample the transcript's current
-   * progress fingerprint (record count + source-file mtime) WITHOUT parsing the
-   * PTY. Used by the stall watchdog to distinguish "PTY render is quiet but the
-   * worker is still doing long tool work (transcript growing)" from a genuine
-   * wedge. Returns null for a pure-PTY provider (no native source) or when the
-   * source cannot be resolved this tick — the caller then falls back to the
-   * unchanged lastOutputAt-only judgment.
+   * TX-FSM Stage 1 — the single native-transcript signal probe (replaces
+   * the Stage-0 sampleNativeTranscriptProgress fingerprint sampler). For a
+   * native-source provider (its authoritative history is an on-disk
+   * transcript file, e.g. kimi's wire.jsonl), perform the read this
+   * judgment point already owns — SAME cadence as before, one
+   * readExternalCompletionMessages() per call, never more — and return the
+   * NORMALIZED SignalSnapshot the shared TranscriptSignalSource produced
+   * from it (publishTranscriptSignalObservation runs inside the read), plus
+   * the messages that read returned. Judgment sites (the stall watchdog's
+   * transcript-advancing axis, the completion growth-hold, the stall-path
+   * completion rescue) consume the snapshot's SIGNALS instead of running
+   * their own fingerprint/freshness/final-assistant scans — one source of
+   * truth for "what does the transcript say right now".
    *
-   * Generalized on the provider's native-source flag, NOT a hardcoded provider
-   * type, so every current and future pure-PTY long-tool native-source provider
-   * benefits. Cheap enough for the stall path: it runs only at the stall threshold
-   * (≥180s of PTY stasis), never on the routine 5s tick.
+   * Class gating goes through resolveTranscriptAuthorityProfile ONLY.
+   * Returns null for a non-native-source class (nothing to signal from) and
+   * a null snapshot when the read threw — callers keep their fail-open
+   * fallbacks ("couldn't tell" never blocks an idle verdict and never
+   * fabricates a completion). Cheap enough for the stall path: it runs
+   * only at the stall threshold (≥180s of PTY stasis) or during an armed
+   * completion-debounce retry, never on the routine 5s tick.
    */
-  sampleNativeTranscriptProgress() {
-    if (!isNativeSourceCanonicalHistory(this.provider?.nativeHistory)) return null;
+  probeNativeTranscriptSignals() {
+    if (resolveTranscriptAuthorityProfile(this.provider).class !== "native-source") return null;
     let messages = null;
     try {
       messages = this.readExternalCompletionMessages();
     } catch {
-      return null;
+      return { snapshot: null, messages: null };
     }
-    const probe = this.lastExternalCompletionProbe;
-    if (!probe) return null;
-    return {
-      msgCount: typeof probe.msgCount === "number" ? probe.msgCount : Array.isArray(messages) ? messages.length : 0,
-      sourceMtimeMs: typeof probe.sourceMtimeMs === "number" ? probe.sourceMtimeMs : 0
-    };
+    return { snapshot: this.lastTranscriptSignalSnapshot, messages };
   }
   /**
    * KIMI-MESH-COMPLETION-EMIT (axis 2). Last-chance completion emit for a mesh
@@ -51784,8 +52155,22 @@ var CliProviderInstance = class _CliProviderInstance {
    * false for a daemon-owned provider and for a genuinely mid-turn / wedged
    * worker with no in-turn final assistant, so a real stall still fires
    * unchanged. Evidence bar is identical to flushMeshCompletionBeforeCleanup.
+   *
+   * TX-FSM Stage 1 (FIX 3 probe delegation): for a native-source class the
+   * completion VERDICT is the shared TranscriptSignalSource's
+   * final_assistant_present signal, normalized from the ONE transcript read
+   * the stall watchdog already performed this tick (passed in as
+   * `transcriptSignals`) — not a second private read + scan. The emit
+   * payload (finalSummary) is extracted from the SAME messages the signal
+   * was normalized from, with the SAME turn boundary the legacy path used,
+   * so the extraction re-proves the turn scope the signal checked. Fail-open
+   * both ways: no usable snapshot (read failed / unresolved / a pure-PTY
+   * class, which has no native signal by construction) → the legacy
+   * class-appropriate evidence path (completionFinalSummary), unchanged; and
+   * a present-but-unextractable signal yields false rather than a
+   * payload-less emit.
    */
-  tryReconcileTranscriptCompletionForStall(observedStatus) {
+  tryReconcileTranscriptCompletionForStall(observedStatus, transcriptSignals) {
     const profile = resolveTranscriptAuthorityProfile(this.provider);
     if (profile.class === "daemon-owned") return false;
     if (observedStatus !== "idle") return false;
@@ -51803,10 +52188,19 @@ var CliProviderInstance = class _CliProviderInstance {
       parsedMessages = void 0;
     }
     let finalSummary;
-    try {
-      finalSummary = this.completionFinalSummary(parsedMessages, turnStartedAt);
-    } catch {
-      finalSummary = void 0;
+    const signalSnapshot = transcriptSignals?.snapshot;
+    if (profile.class === "native-source" && signalSnapshot?.available === true) {
+      if (signalSnapshot.signals.final_assistant_present !== true) return false;
+      finalSummary = extractFinalSummaryFromMessagesAfter(
+        Array.isArray(transcriptSignals?.messages) ? transcriptSignals.messages : [],
+        turnStartedAt
+      ) || void 0;
+    } else {
+      try {
+        finalSummary = this.completionFinalSummary(parsedMessages, turnStartedAt);
+      } catch {
+        finalSummary = void 0;
+      }
     }
     if (!finalSummary) return false;
     const diagnosticSource = profile.class === "pure-pty" ? "stall_pure_pty_transcript_completion" : "stall_native_source_transcript_completion";
@@ -52073,24 +52467,25 @@ var CliProviderInstance = class _CliProviderInstance {
       const isTranscriptEvidenceGate = block2.allowTimeout === true;
       LOG.debug("CLI", `[${this.type}] finalization block: reason=${blockReason} terminal=${block2.terminal} allowTimeout=${isTranscriptEvidenceGate} waitedMs=${waitedMs} maxWait=${COMPLETED_FINALIZATION_MAX_WAIT_MS}`);
       if (blockReason === "missing_final_assistant" && block2.noExternalTranscriptSource === true) {
-        let nativeSample = null;
+        let growthSnapshot = null;
         try {
-          nativeSample = this.sampleNativeTranscriptProgress();
+          growthSnapshot = this.probeNativeTranscriptSignals()?.snapshot ?? null;
         } catch {
-          nativeSample = null;
+          growthSnapshot = null;
         }
-        const sourceMtimeMs = nativeSample?.sourceMtimeMs ?? 0;
-        if (nativeSample && sourceMtimeMs > 0 && Date.now() - sourceMtimeMs < MISSING_ASSISTANT_TRANSCRIPT_GROWTH_QUIET_MS) {
+        if (growthSnapshot?.available === true && growthSnapshot.signals.transcript_growing === true) {
+          const growthDetail = growthSnapshot.detail;
+          const mtimeAgeMs = growthDetail.ageMs ?? 0;
           if (pending.loggedBlockReason !== "native_transcript_advancing") {
-            LOG.info("CLI", `[${this.type}] holding pending completed (native_transcript_advancing: msgCount=${nativeSample.msgCount} mtimeAge=${Date.now() - sourceMtimeMs}ms < ${MISSING_ASSISTANT_TRANSCRIPT_GROWTH_QUIET_MS}ms) \u2014 transcript still growing, screen-idle verdict not trusted`);
+            LOG.info("CLI", `[${this.type}] holding pending completed (native_transcript_advancing: msgCount=${growthDetail.msgCount} mtimeAge=${mtimeAgeMs}ms < ${MISSING_ASSISTANT_TRANSCRIPT_GROWTH_QUIET_MS}ms) \u2014 transcript still growing, screen-idle verdict not trusted`);
             if (this.isMeshWorkerSession()) {
-              traceMeshEventDrop("completion_gate_hold", this.meshTraceCtx(), `native_transcript_advancing msgCount=${nativeSample.msgCount} mtimeAge=${Date.now() - sourceMtimeMs}ms`);
+              traceMeshEventDrop("completion_gate_hold", this.meshTraceCtx(), `native_transcript_advancing msgCount=${growthDetail.msgCount} mtimeAge=${mtimeAgeMs}ms`);
             }
             if (this.completionTraceOn()) this.recordCompletionGateTrace("hold", {
               blockReason: "native_transcript_advancing",
               latestVisibleStatus,
-              msgCount: nativeSample.msgCount,
-              sourceMtimeAgeMs: Date.now() - sourceMtimeMs,
+              msgCount: growthDetail.msgCount,
+              sourceMtimeAgeMs: mtimeAgeMs,
               growthQuietMs: MISSING_ASSISTANT_TRANSCRIPT_GROWTH_QUIET_MS,
               waitedMs
             });
@@ -62591,17 +62986,134 @@ var fastForwardHandlers = {
 
 // src/commands/med-family/mesh-restart.ts
 init_dist();
+init_logger();
 var RESTART_BLOCKING_STATES = /* @__PURE__ */ new Set(["generating", "waiting_approval", "starting"]);
-function hasBlockingSessions(ctx) {
+var DEFERRED_RESTART_DEFAULT_TIMEOUT_MS = 30 * 60 * 1e3;
+var DEFERRED_RESTART_MAX_TIMEOUT_MS = 6 * 60 * 60 * 1e3;
+var DEFERRED_RESTART_POLL_MS = 1e4;
+function collectBlockingSessions(ctx, meshId) {
+  const blocking = [];
   const states = ctx.deps.instanceManager.collectAllStates();
+  const consider = (state) => {
+    const status = String(state?.status || "");
+    if (!RESTART_BLOCKING_STATES.has(status)) return;
+    blocking.push({
+      instanceId: typeof state?.instanceId === "string" ? state.instanceId : null,
+      status,
+      // The coordinator marker is stamped by mesh_coordinator_launch and
+      // re-stamped on restore (cli-manager.restoreHostedSessions). Ad-hoc
+      // coordinator sessions have no marker and are NOT waived by selfOnly.
+      selfCoordinator: !!meshId && state?.settings?.meshCoordinatorFor === meshId
+    });
+  };
   for (const state of states) {
-    if (RESTART_BLOCKING_STATES.has(String(state.status || ""))) return true;
+    consider(state);
     const childStates = "extensions" in state && Array.isArray(state.extensions) ? state.extensions : [];
-    for (const child of childStates) {
-      if (RESTART_BLOCKING_STATES.has(String(child?.status || ""))) return true;
-    }
+    for (const child of childStates) consider(child);
+  }
+  return blocking;
+}
+var pendingDeferredRestart = null;
+function deferredRestartInfo() {
+  if (!pendingDeferredRestart) return null;
+  return {
+    meshId: pendingDeferredRestart.meshId,
+    nodeId: pendingDeferredRestart.nodeId,
+    mode: pendingDeferredRestart.mode,
+    killSessionHost: pendingDeferredRestart.killSessionHost,
+    scheduledAt: new Date(pendingDeferredRestart.scheduledAt).toISOString(),
+    expiresAt: new Date(pendingDeferredRestart.expiresAt).toISOString(),
+    runCondition: "executes automatically once no session is generating / waiting_approval / starting"
+  };
+}
+function clearPendingDeferredRestart() {
+  if (pendingDeferredRestart) clearInterval(pendingDeferredRestart.timer);
+  pendingDeferredRestart = null;
+}
+function normalizeRestartMode(value) {
+  return value === "restart" ? "restart" : "upgrade";
+}
+function restartWarnings(args) {
+  const warnings = [];
+  if (args.forced) {
+    warnings.push("forced restart over active sessions \u2014 in-flight turns were interrupted and the in-memory pendingOutboundQueue is permanently lost (no persistence/restore path).");
+  }
+  if (args.killSessionHost) {
+    warnings.push("killSessionHost: the session-host process was stopped \u2014 ALL hosted CLI sessions on this machine are destroyed (hard refresh).");
+  }
+  if (process.platform === "win32") {
+    warnings.push("Windows: the daemon restart/upgrade path stops the session-host regardless of options \u2014 all hosted sessions terminate.");
+  } else {
+    warnings.push("POSIX: hosted PTY sessions survive a plain daemon restart and rebind on next boot (unless killSessionHost was set).");
+  }
+  return warnings;
+}
+async function executeRestart(ctx, args, opts) {
+  const mode = normalizeRestartMode(args?.mode);
+  const killSessionHost = args?.killSessionHost === true;
+  const result = mode === "restart" ? await daemonLifecycleHandlers.daemon_restart({ deps: ctx.deps }, { killSessionHost }) : await daemonLifecycleHandlers.daemon_upgrade({ deps: ctx.deps }, args);
+  const restarting = result?.restarting === true;
+  return {
+    ...result,
+    mode,
+    restarted: restarting,
+    ...restarting ? {
+      warnings: restartWarnings({ killSessionHost, forced: opts.forced }),
+      // MCP IPC has no automatic reconnect/retry — tell the caller when to
+      // talk to this daemon again.
+      clientHint: "daemon restarting \u2014 retry your next call in ~10s"
+    } : {}
+  };
+}
+function scheduleDeferredRestart(ctx, args, meshId, nodeId) {
+  clearPendingDeferredRestart();
+  const requestedTimeout = typeof args?.timeoutMs === "number" && Number.isFinite(args.timeoutMs) ? args.timeoutMs : DEFERRED_RESTART_DEFAULT_TIMEOUT_MS;
+  const timeoutMs = Math.min(Math.max(requestedTimeout, DEFERRED_RESTART_POLL_MS), DEFERRED_RESTART_MAX_TIMEOUT_MS);
+  const record = {
+    meshId,
+    nodeId,
+    mode: normalizeRestartMode(args?.mode),
+    killSessionHost: args?.killSessionHost === true,
+    scheduledAt: Date.now(),
+    expiresAt: Date.now() + timeoutMs,
+    timer: setInterval(() => {
+      void deferredRestartTick(ctx);
+    }, DEFERRED_RESTART_POLL_MS)
+  };
+  record.timer.unref?.();
+  pendingDeferredRestart = record;
+  LOG.info("MeshRestart", `Deferred restart scheduled for node ${nodeId} (mode=${record.mode}, expires in ${Math.round(timeoutMs / 6e4)}min)`);
+  return {
+    success: true,
+    restarted: false,
+    scheduled: true,
+    code: "restart_scheduled_when_idle",
+    reason: "Restart scheduled \u2014 it will execute automatically as soon as no session on this daemon is generating / waiting_approval / starting. Running at an idle point also avoids pendingOutboundQueue loss, making this the safest restart path.",
+    deferredRestart: deferredRestartInfo()
+  };
+}
+async function deferredRestartTick(ctx) {
+  const record = pendingDeferredRestart;
+  if (!record) return;
+  if (Date.now() >= record.expiresAt) {
+    LOG.warn("MeshRestart", `Deferred restart for node ${record.nodeId} expired without reaching an idle point; dropping the schedule`);
+    clearPendingDeferredRestart();
+    return;
+  }
+  const blocking = collectBlockingSessions(ctx, record.meshId);
+  if (blocking.length > 0) return;
+  LOG.info("MeshRestart", `Deferred restart for node ${record.nodeId} executing \u2014 daemon is idle`);
+  clearPendingDeferredRestart();
+  try {
+    await executeRestart(ctx, {
+      meshId: record.meshId,
+      nodeId: record.nodeId,
+      mode: record.mode,
+      killSessionHost: record.killSessionHost
+    }, { forced: false });
+  } catch (e) {
+    LOG.error("MeshRestart", `Deferred restart execution failed: ${e?.message || String(e)}`);
   }
-  return false;
 }
 var meshRestartHandlers = {
   restart_daemon_node: async (ctx, args) => {
@@ -62622,16 +63134,43 @@ var meshRestartHandlers = {
       });
       return forwarded ?? { success: false, error: "no response from remote node" };
     }
-    if (hasBlockingSessions(ctx)) {
+    if (args?.cancelWhenIdle === true) {
+      const had = pendingDeferredRestart !== null;
+      clearPendingDeferredRestart();
+      return { success: true, restarted: false, cancelled: had, deferredRestart: null };
+    }
+    if (args?.whenIdleStatus === true) {
+      return { success: true, restarted: false, deferredRestart: deferredRestartInfo() };
+    }
+    const blocking = collectBlockingSessions(ctx, meshId);
+    if (blocking.length > 0) {
+      if (args?.force === true) {
+        LOG.warn("MeshRestart", `force restart over ${blocking.length} blocking session(s): ${blocking.map((b) => `${b.instanceId || "?"}(${b.status})`).join(", ")} \u2014 pendingOutboundQueue will be lost`);
+        return executeRestart(ctx, args, { forced: true });
+      }
+      const foreignBlocking = blocking.filter((b) => !b.selfCoordinator);
+      if (args?.selfOnly === true && foreignBlocking.length === 0) {
+        LOG.info("MeshRestart", `selfOnly restart: waiving ${blocking.length} self-coordinator session(s) for mesh ${meshId}`);
+        return executeRestart(ctx, args, { forced: false });
+      }
+      if (args?.whenIdle === true) {
+        return scheduleDeferredRestart(ctx, args, meshId, nodeId);
+      }
       return {
         success: false,
         restarted: false,
         code: "blocking_sessions",
-        reason: "Daemon has an active session (generating / waiting_approval / starting); restart refused to avoid interrupting in-flight work. Retry when the node is idle."
+        reason: "Daemon has an active session (generating / waiting_approval / starting); restart refused to avoid interrupting in-flight work. Retry when the node is idle.",
+        blockingSessions: blocking,
+        options: {
+          selfOnly: "waive only this mesh's own coordinator session (settings.meshCoordinatorFor === meshId)",
+          force: "bypass the idle-gate entirely \u2014 kills in-flight turns and loses the unpersisted pendingOutboundQueue",
+          whenIdle: "schedule the restart to run automatically once the daemon goes idle (safest)"
+        },
+        deferredRestart: deferredRestartInfo()
       };
     }
-    const result = await daemonLifecycleHandlers.daemon_upgrade({ deps: ctx.deps }, args);
-    return { ...result, restarted: result?.restarting === true };
+    return executeRestart(ctx, args, { forced: false });
   }
 };