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

package/dist/providers/cli-provider-instance.d.ts

@@ -192,7 +192,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private meshStallEmittedForAnchor;
     private meshStallTurnActiveLast;
     private meshStallLastFiredAt;
-    private meshStallNativeTranscriptSample;
+    private meshStallTranscriptSignalSampled;
     private busyEpoch;
     private fastCollapseSynthesizedTaskId;
     private startupGraceCollapseAt;
@@ -413,6 +413,17 @@ export declare class CliProviderInstance implements ProviderInstance {
     private completedDebounceTimer;
     private completedDebouncePending;
     private lastExternalCompletionProbe;
+    /** 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). */
+    private transcriptSignalSource;
+    /** 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. */
+    private lastTranscriptSignalSnapshot;
     /**
      * The final assistant summary of the last completed turn, cached at
      * completion-emit time. For a native-source provider (antigravity) whose
@@ -448,6 +459,22 @@ export declare class CliProviderInstance implements ProviderInstance {
      */
     private spawnedEnvOverrides;
     private readExternalCompletionMessages;
+    /**
+     * 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.
+     */
+    private publishTranscriptSignalObservation;
     /**
      * 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
@@ -576,23 +603,35 @@ export declare class CliProviderInstance implements ProviderInstance {
      * starts with a clean slate (a restart is not throttled by a prior stall).
      */
     private resetMeshStallEpisode;
-    /**
-     * 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.
+    /** 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). */
+    /**
+     * 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.
      */
-    private sampleNativeTranscriptProgress;
+    private probeNativeTranscriptSignals;
     /**
      * KIMI-MESH-COMPLETION-EMIT (axis 2). Last-chance completion emit for a mesh
      * DELEGATED worker whose PTY has already exited (e.g. killed by a false stall)
@@ -645,6 +684,20 @@ export declare class CliProviderInstance implements ProviderInstance {
      * 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.
      */
     private tryReconcileTranscriptCompletionForStall;
     /**

package/dist/providers/spec/cli-adapter.d.ts

@@ -223,6 +223,13 @@ export declare class SpecCliAdapter implements CliAdapter {
     getRuntimeMetadata(): unknown;
     updateRuntimeMeta(meta?: Record<string, unknown>): void;
     refreshProviderDefinition(): void;
+    /**
+     * 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: import('./signal-envelope.js').SignalSnapshot | null): void;
     private handleEvent;
     private detectInteractivePromptFromPtyChunk;
     private readCurrentScreenSections;

package/dist/providers/spec/fsm-driver.d.ts

@@ -2,6 +2,7 @@ import { type SpecPtyEvent } from './adapter.js';
 import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
 import { type TraceEntry } from './evaluator.js';
 import { type TransitionEval } from './fsm-evaluator.js';
+import type { SignalSnapshot } from './signal-envelope.js';
 import { chunkPreservingSurrogates as chunkPreservingSurrogatesShared } from '../../cli-adapters/pty-write-chunking.js';
 export type DashboardEvent = {
     kind: 'pty_data';
@@ -159,6 +160,14 @@ export interface ISpecDriver {
     getFsmDebug?(): unknown;
     getFsmSnapshotHistory?(): ReadonlyArray<FsmSnapshotEntry>;
     getEventTimeline?(limit?: number): ReadonlyArray<SpecPtyEvent>;
+    /**
+     * TX-FSM Stage 0 (shadow): inject the daemon-normalized signal observation.
+     * Observation ONLY — the driver receives the envelope, never a reader; all
+     * file discovery / session pinning / parsing stays daemon-side so the FSM
+     * engine remains a generic PTY engine. The snapshot feeds the shadow
+     * verdict of `signal` conditions exclusively; it cannot gate a transition.
+     */
+    setSignalObservation?(snapshot: SignalSnapshot | null): void;
 }
 export interface SpecDriverOpts {
     specPath: string;
@@ -244,6 +253,15 @@ export declare class FsmDriver implements ISpecDriver {
      *  transition — the rich pre-transition table that lastFsmEval only keeps
      *  for the single most recent evaluation. Separate from stateHistory. */
     private 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. */
+    private signalObservation;
+    /** 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. */
+    private shadowDivergenceLast;
     constructor(opts: SpecDriverOpts);
     subscribe(listener: (ev: DashboardEvent) => void): () => void;
     start(): void;
@@ -259,6 +277,14 @@ export declare class FsmDriver implements ISpecDriver {
      *  the session registry. Not a DashboardCommand — this is a control-plane
      *  update, not user input. */
     updateMeta(meta: Record<string, unknown>, replace?: boolean): void;
+    /**
+     * 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: SignalSnapshot | null): void;
     snapshot(): string;
     getCursorPosition(): {
         row: number;
@@ -319,6 +345,15 @@ export declare class FsmDriver implements ISpecDriver {
     private emitInitialState;
     private buildClock;
     private evalFsmNow;
+    /**
+     * 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.
+     */
+    private logShadowDivergence;
     private reevaluate;
     private commitTransition;
     /** Snapshot the full FSM evaluation that produced a transition into the

package/dist/providers/spec/fsm-evaluator.d.ts

@@ -1,6 +1,7 @@
 import type { SectionDef } from './types.js';
 import { type ResolvedSection, type TraceEntry } from './evaluator.js';
 import { type CliSpecV4, type FsmCondition } from './fsm-types.js';
+import { type SignalSnapshot } from './signal-envelope.js';
 export interface FsmClock {
     /** Wall-clock now (ms). Passed in so the evaluator stays pure. */
     now: number;
@@ -14,7 +15,7 @@ export interface FsmClock {
 }
 /** Per-condition evaluation detail — the debugging payload. */
 export interface CondResult {
-    kind: 'regex' | 'changed' | 'elapsed' | 'stable' | 'all' | 'any' | 'not';
+    kind: 'regex' | 'changed' | 'elapsed' | 'stable' | 'signal' | 'all' | 'any' | 'not';
     result: boolean;
     detail: string;
     /** Remaining ms until a time-based condition would flip to true. 0 if
@@ -24,6 +25,17 @@ export interface CondResult {
      *  snapshot shows WHAT text the rule fired on — not just which regex. Never
      *  read by the FSM; purely for the Spec Debug Snapshot. */
     matchedText?: string;
+    /** TX-FSM Stage 0 (shadow): present only on `signal` leaves. `result` above
+     *  is ALWAYS true for a signal leaf (Stage-0 pass-through — the leaf never
+     *  gates a transition); this payload records what the leaf WOULD have
+     *  decided against the injected snapshot. shadowResult null = the signal
+     *  was unavailable/unknown (fail-open). */
+    signal?: {
+        name: string;
+        available: boolean;
+        value: boolean | null;
+        shadowResult: boolean | null;
+    };
     children?: CondResult[];
 }
 /** One evaluated transition with its full reasoning. */
@@ -42,6 +54,20 @@ export interface TransitionEval {
     /** Overall: would this transition fire? */
     fires: boolean;
     priority: number;
+    /**
+     * TX-FSM Stage 0 (shadow): present only when the guard contains at least
+     * one `signal` leaf. Records the verdict the transition WOULD have
+     * produced if signal leaves gated (condResult/fires), so the shadow log
+     * can compare it against the real PTY-only outcome. `unknown` = at least
+     * one signal leaf had no observation (fail-open); the shadow verdict is
+     * then informational, not a counterfactual proof. NEVER consumed by the
+     * driver for any transition decision — log/debug surface only.
+     */
+    shadow?: {
+        condResult: boolean;
+        fires: boolean;
+        unknown: boolean;
+    };
 }
 export interface FsmEvaluation {
     /** Sections resolved from the screen (shared with v3 shape). */
@@ -79,7 +105,7 @@ export declare function stableRegionKey(cond: {
 export declare function evaluateFsm(spec: CliSpecV4, currentStateId: string, screenText: string, cursor: {
     row: number;
     col: number;
-} | undefined, prevLines: string[] | undefined, clock: FsmClock): FsmEvaluation;
+} | undefined, prevLines: string[] | undefined, clock: FsmClock, signalSnapshot?: SignalSnapshot | null): FsmEvaluation;
 /**
  * Evaluate a single condition against a screen + section map — for the spec
  * editor's live preview ("does this regex match the current screen right

package/dist/providers/spec/fsm-types.d.ts

@@ -49,7 +49,25 @@ export interface FsmAnyCondition {
 export interface FsmNotCondition {
     not: FsmCondition;
 }
-export type FsmCondition = RegexCondition | ChangedCondition | ElapsedCondition | StableCondition | FsmAllCondition | FsmAnyCondition | FsmNotCondition;
+/**
+ * TX-FSM Stage 0 (shadow) — a daemon-signal leaf. References a NORMALIZED
+ * signal name from the SignalSnapshot envelope (never a provider name), so a
+ * spec can combine transcript evidence with PTY conditions via all/any/not:
+ *
+ *   { all: [ { matches: "…" }, { signal: "final_assistant_present" } ] }
+ *
+ * STAGE-0 SEMANTICS: evaluated for the shadow log only. The leaf NEVER gates
+ * a transition — the evaluator treats it as pass-through for the real verdict
+ * and records what it WOULD have decided (TransitionEval.shadow). A missing
+ * or unavailable signal fails open. Promotion to a real gate is Stage 1+.
+ */
+export interface FsmSignalCondition {
+    /** Normalized signal name (see SIGNAL_NAMES in signal-envelope.ts). */
+    signal: string;
+    /** Expected value; default true. */
+    equals?: boolean;
+}
+export type FsmCondition = RegexCondition | ChangedCondition | ElapsedCondition | StableCondition | FsmSignalCondition | FsmAllCondition | FsmAnyCondition | FsmNotCondition;
 export interface FsmState {
     id: string;
     label: string;

package/dist/providers/spec/signal-envelope.d.ts

@@ -0,0 +1,59 @@
+import type { TranscriptClass, CompletionTiming } from '../transcript-evidence.js';
+export declare const SIGNAL_SNAPSHOT_KIND: "adhdev:fsm/signal-snapshot@0";
+/** The normalized signal vocabulary. Stage 0 keeps this deliberately small —
+ *  every name must be derivable from the FLATTENED native-transcript pipeline
+ *  (which drops tool_use/tool_result correlation ids — that raw-JSONL read is
+ *  Stage 4 territory and must NOT be added here). */
+export type SignalName = 'final_assistant_present' | 'in_turn_progress' | 'transcript_growing';
+export declare const SIGNAL_NAMES: readonly SignalName[];
+export type SignalUnavailableReason = 'no_native_source' | 'unresolved' | 'error';
+/** The normalized, provider-agnostic observation the daemon hands the FSM. */
+export interface SignalSnapshot {
+    kind: typeof SIGNAL_SNAPSHOT_KIND;
+    /** Wall-clock time the underlying transcript read happened (ms). */
+    sampledAt: number;
+    /** False ⇒ every signal is null and conditions fail open. */
+    available: boolean;
+    unavailableReason?: SignalUnavailableReason;
+    /** The authority profile class/timing this snapshot was produced under
+     *  (via resolveTranscriptAuthorityProfile — never raw predicates). */
+    profile?: {
+        class: TranscriptClass;
+        timing: CompletionTiming;
+    };
+    /** Normalized signals; null = unknown (fail-open). */
+    signals: Record<SignalName, boolean | null>;
+    /** Raw sampling context for the shadow log / Stage 1-3 analysis. */
+    detail: {
+        msgCount: number;
+        sourceMtimeMs: number;
+        /** now - sourceMtimeMs; null when the mtime is unknown (0). */
+        ageMs: number | null;
+    };
+}
+/** The fail-open snapshot: no usable observation, every signal null. */
+export declare function unavailableSignalSnapshot(now: number, reason: SignalUnavailableReason, profile?: {
+    class: TranscriptClass;
+    timing: CompletionTiming;
+}): SignalSnapshot;
+/** The spec's `signal` leaf: `{ signal: 'transcript_growing', equals?: boolean }`. */
+export interface SignalLeaf {
+    signal: string;
+    equals?: boolean;
+}
+export interface SignalLeafEval {
+    /** The normalized signal value read from the snapshot; null = unknown. */
+    value: boolean | null;
+    /** What the leaf WOULD evaluate to if signals gated transitions; null =
+     *  unknown (no snapshot / signal missing → fail-open). */
+    shadowResult: boolean | null;
+    /** Human-readable shadow-log fragment. */
+    detail: string;
+}
+/**
+ * Evaluate one `signal` leaf against the injected snapshot. This computes the
+ * SHADOW verdict only — the caller (fsm-evaluator) owns the Stage-0
+ * pass-through rule that keeps the real result true regardless of what this
+ * returns.
+ */
+export declare function evaluateSignalLeaf(cond: SignalLeaf, snapshot: SignalSnapshot | null | undefined): SignalLeafEval;

package/dist/providers/transcript-signal-source.d.ts

@@ -0,0 +1,59 @@
+import type { TranscriptAuthorityProfile } from './transcript-evidence.js';
+import { type SignalSnapshot } from './spec/signal-envelope.js';
+/** One daemon transcript read, normalized for the source. */
+export interface TranscriptSignalSample {
+    /** Parsed native-transcript messages, or null when the read failed to
+     *  resolve a source this time. */
+    messages: unknown[] | null;
+    /** The probe metadata the read refreshed (sourcePath/mtime/msgCount), or
+     *  null when no source is bound. A null sourceMtimeMs is treated as "no
+     *  freshness evidence" (same contract as the growth-hold path). */
+    probe: {
+        msgCount: number;
+        sourceMtimeMs: number | null;
+        sourcePath?: string | null;
+    } | null;
+    /** True when the read threw — logged distinctly from a clean miss. */
+    error?: boolean;
+}
+export interface TranscriptSignalSourceOpts {
+    /** Log tag (provider type / session label) — never used for branching. */
+    label: string;
+    /** The P0 choke-point profile for this provider. */
+    profile: TranscriptAuthorityProfile;
+    /** Turn-boundary clock (adapter.currentTurnStartedAt) for turn-scoped
+     *  final-assistant detection; may yield undefined pre-turn. */
+    turnStartedAt?: () => number | undefined;
+    /** In-turn final-assistant predicate over the flattened messages — the
+     *  instance passes its existing completionHasFinalAssistantMessage so the
+     *  signal reuses the exact completion machinery instead of duplicating it. */
+    finalAssistantPresent: (messages: unknown[], turnStartedAt?: number) => boolean;
+    /** Freshness window (ms) for transcript_growing. The caller passes the
+     *  completion pipeline's MISSING_ASSISTANT_TRANSCRIPT_GROWTH_QUIET_MS so
+     *  the shadow signal is comparable to the existing growth-hold judgment. */
+    growthQuietMs: number;
+}
+export declare class TranscriptSignalSource {
+    private readonly opts;
+    /** msgCount seen at the previous update — drives in_turn_progress. */
+    private prevMsgCount;
+    /** Fingerprint of the last LOGGED snapshot, so the shadow log fires on
+     *  change only (a quiet session must not spam one line per read). */
+    private lastLoggedFingerprint;
+    constructor(opts: TranscriptSignalSourceOpts);
+    /**
+     * 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: TranscriptSignalSample, now?: number): SignalSnapshot;
+    /** Pure normalization — separated from update() so tests can assert the
+     *  envelope without touching the log path. */
+    buildSnapshot(sample: TranscriptSignalSample, now: number): SignalSnapshot;
+    /** 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. */
+    private logOnChange;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "1.0.28-rc.10",
+  "version": "1.0.28-rc.12",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,8 +49,8 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "1.0.28-rc.10",
-    "@adhdev/session-host-core": "1.0.28-rc.10",
+    "@adhdev/mesh-shared": "1.0.28-rc.12",
+    "@adhdev/session-host-core": "1.0.28-rc.12",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

package/src/cli-adapter-types.ts

@@ -173,6 +173,13 @@ export interface CliAdapter {
     // back to resolveModal + the resolution-cooldown check).
     resolveModalMatched?(buttonIndex: number): boolean;
     isApprovalRecentlyResolved?(): boolean;
+    /**
+     * TX-FSM Stage 0 (shadow): receive the daemon-normalized transcript signal
+     * observation (SignalSnapshot envelope, providers/spec/signal-envelope.ts).
+     * Optional — only the spec-driven FSM adapter implements it; callers must
+     * typeof-guard. Shadow-only: the observation can never gate a transition.
+     */
+    setSignalObservation?(snapshot: unknown): void;
  // Raw PTY I/O (for terminal view)
     setOnPtyData?(callback: (data: string) => void): void;
     writeRaw?(data: string): void;

package/src/commands/low-family/daemon-lifecycle.ts

@@ -112,6 +112,47 @@ export const daemonLifecycleHandlers: Record<string, LowFamilyHandler> = {
         }
     },
 
+    // 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: LowFamilyContext, args: any) => {
+        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 — 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');
+
+            // Exit after the command response has been sent so the helper can re-spawn cleanly.
+            setTimeout(() => {
+                LOG.info('Restart', 'Exiting daemon so detached helper can re-spawn it...');
+                process.exit(0);
+            }, 3000);
+
+            return { success: true, restarted: true, restarting: true, mode: 'restart', killSessionHost };
+        } catch (e: any) {
+            LOG.error('Restart', `Failed: ${e.message}`);
+            return { success: false, error: e.message };
+        }
+    },
+
     set_machine_nickname: async (_ctx: LowFamilyContext, args: any) => {
         const nickname = args?.nickname;
         updateConfig({ machineNickname: nickname || null });