@cydm/happy-elves 0.1.0-beta.74 → 0.1.0-beta.76

package/apps/cli/dist/commands/app.js

@@ -2,6 +2,7 @@ import { handleAccount } from "./account.js";
 import { handleCollect } from "./collect.js";
 import { handleConfig } from "./config.js";
 import { handleDaemon } from "./daemon.js";
+import { handleDiagnostics } from "./diagnostics.js";
 import { handleGateway } from "./gateway.js";
 import { handleLoop } from "./loop.js";
 import { handleMachine } from "./machine.js";
@@ -22,6 +23,7 @@ const domainHandlers = [
     handleToken,
     handleLoop,
     handleDaemon,
+    handleDiagnostics,
     handleRelay,
     handleMachine,
     handleMemory,

package/apps/cli/dist/commands/diagnostics.d.ts

@@ -0,0 +1,2 @@
+import type { CommandInput } from "./command.js";
+export declare function handleDiagnostics({ domain, action, flags }: CommandInput): Promise<boolean>;

package/apps/cli/dist/commands/diagnostics.js

@@ -0,0 +1,71 @@
+import { UiProbeClient } from "../../../../packages/client/dist/index.js";
+import { CliError, ok, parseDurationMs, readConfig, requireString, wantsJson } from "./lib/index.js";
+const DEFAULT_CAPTURE_TIMEOUT_MS = 30_000;
+const DEFAULT_WATCH_DURATION_MS = 10 * 60_000;
+const MAX_WATCH_DURATION_MS = 10 * 60_000;
+function durationFlag(flags, key, fallbackMs, maximumMs) {
+    const durationMs = parseDurationMs(flags[key], fallbackMs);
+    if (!Number.isFinite(durationMs) || durationMs <= 0 || durationMs > maximumMs) {
+        throw new CliError(`Invalid --${key}: expected a positive duration no greater than 10m`, "INVALID_ARGUMENT");
+    }
+    return durationMs;
+}
+function printTelemetry(telemetry) {
+    console.log(JSON.stringify(telemetry));
+}
+export async function handleDiagnostics({ domain, action, flags }) {
+    if (domain !== "diagnostics")
+        return false;
+    const config = await readConfig(flags);
+    const client = new UiProbeClient(config);
+    try {
+        if (action === "surfaces") {
+            const surfaces = await client.listSurfaces();
+            if (wantsJson(flags))
+                ok("diagnostics.surfaces", { surfaces });
+            else if (surfaces.length === 0)
+                console.log("No Device is sharing live diagnostics.");
+            else {
+                for (const surface of surfaces) {
+                    console.log(`${surface.deviceId}  ${surface.surfaceId}  ${surface.kind}  expires ${new Date(surface.expiresAt).toISOString()}`);
+                }
+            }
+            return true;
+        }
+        if (action === "capture") {
+            const deviceId = requireString(flags, "device");
+            const surfaceId = requireString(flags, "surface");
+            const timeoutMs = durationFlag(flags, "timeout", DEFAULT_CAPTURE_TIMEOUT_MS, MAX_WATCH_DURATION_MS);
+            const telemetry = await client.capture({ deviceId, surfaceId, timeoutMs });
+            if (wantsJson(flags))
+                ok("diagnostics.capture", telemetry);
+            else
+                console.log(JSON.stringify(telemetry, null, 2));
+            return true;
+        }
+        if (action === "watch") {
+            if (flags.jsonl !== true) {
+                throw new CliError("diagnostics watch requires --jsonl", "MISSING_ARGUMENT");
+            }
+            const deviceId = requireString(flags, "device");
+            const surfaceId = requireString(flags, "surface");
+            const durationMs = durationFlag(flags, "duration", DEFAULT_WATCH_DURATION_MS, MAX_WATCH_DURATION_MS);
+            const abortController = new AbortController();
+            const onSigint = () => abortController.abort();
+            process.once("SIGINT", onSigint);
+            try {
+                const watch = await client.watch({ deviceId, surfaceId, durationMs, signal: abortController.signal });
+                for await (const telemetry of watch)
+                    printTelemetry(telemetry);
+            }
+            finally {
+                process.removeListener("SIGINT", onSigint);
+            }
+            return true;
+        }
+        throw new CliError(`Unknown diagnostics action: ${action ?? "(missing)"}`, "INVALID_ARGUMENT");
+    }
+    finally {
+        await client.close();
+    }
+}

package/apps/cli/dist/commands/lib/args.js

@@ -25,7 +25,9 @@ const valueFlags = new Set([
     "device-id",
     "device-name",
     "display-name",
+    "device",
     "domain",
+    "duration",
     "from",
     "host",
     "host-machine",
@@ -69,6 +71,7 @@ const valueFlags = new Set([
     "runtime-limit",
     "runtime-session",
     "shell",
+    "surface",
     "actions",
     "expires-in",
     "format",
@@ -122,6 +125,7 @@ const booleanFlags = new Set([
     "include-archived",
     "isolated",
     "json",
+    "jsonl",
     "keep-source",
     "local",
     "longterm",

package/apps/cli/dist/commands/lib/bootstrap-daemon.d.ts

@@ -1,6 +1,6 @@
 import { type ControllerClient, type ControllerSnapshot } from "../../../../../packages/client/dist/index.js";
 import type { MachineSnapshot } from "../../../../../packages/shared/dist/index.js";
-import { localDaemonStatus, readLocalDaemonPidIdentity, type SpawnedDaemonHandle } from "./local-daemon.js";
+import { inspectLocalDaemonRuntime, localDaemonStatus, readLocalDaemonPidIdentity, stopLocalDaemon, stopSpawnedDaemon, type SpawnedDaemonHandle } from "./local-daemon.js";
 import type { DaemonConfig } from "./types.js";
 export declare function startFailureMayUseCommittedConfig(error: unknown): boolean;
 export declare function ensureDaemonRunning(expectedConfig: DaemonConfig, cwd?: string): Promise<{
@@ -12,6 +12,27 @@ export declare function ensureDaemonRunning(expectedConfig: DaemonConfig, cwd?:
     committedConfigMayBeInUse?: boolean;
     autostartNeedsAttention?: string;
 }>;
+type BootstrapDaemonRestartOptions = {
+    readStatus?: typeof localDaemonStatus;
+    inspectRuntime?: typeof inspectLocalDaemonRuntime;
+    readIdentity?: typeof readLocalDaemonPidIdentity;
+    stopLocal?: typeof stopLocalDaemon;
+    stopStarted?: typeof stopSpawnedDaemon;
+    ensureRunning?: typeof ensureDaemonRunning;
+    assertConfigFence?: (expectedConfig: DaemonConfig) => Promise<void>;
+};
+/**
+ * `happy-elves start` is an explicit foreground recovery/entry command. When
+ * it finds a verified local Daemon, restart that exact owner so the process
+ * always loads the currently installed package before the browser opens.
+ *
+ * The lower-level `ensureDaemonRunning()` deliberately remains idempotent for
+ * `happy-elves daemon start`, enrollment rollback, and service recovery.
+ */
+export declare function restartDaemonForBootstrap(expectedConfig: DaemonConfig, cwd?: string, options?: BootstrapDaemonRestartOptions): Promise<Awaited<ReturnType<typeof ensureDaemonRunning>> & {
+    restarted: boolean;
+    previousInstanceGeneration?: string;
+}>;
 export type DaemonReadinessResult = {
     phase: "relay-authenticated" | "process-exited" | "owner-changed" | "relay-pending";
     local: Awaited<ReturnType<typeof localDaemonStatus>>;

package/apps/cli/dist/commands/lib/bootstrap-daemon.js

@@ -3,7 +3,7 @@ import { daemonRuntimeConfigFingerprint } from "../../../../../packages/shared/d
 import { CliError } from "../../errors.js";
 import { startDaemonTimeoutMs } from "./paths.js";
 import { readDaemonConfig } from "./config.js";
-import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, inspectLocalDaemonRuntime, ensureRunningDaemonAutostart, localDaemonStatus, readLocalDaemonPidIdentity, spawnDaemonStartTracked, stopSpawnedDaemon, } from "./local-daemon.js";
+import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, inspectLocalDaemonRuntime, ensureRunningDaemonAutostart, localDaemonStatus, readLocalDaemonPidIdentity, spawnDaemonStartTracked, stopLocalDaemon, stopSpawnedDaemon, } from "./local-daemon.js";
 const committedConfigMayBeInUseErrors = new WeakSet();
 export function startFailureMayUseCommittedConfig(error) {
     return Boolean(error && typeof error === "object" && committedConfigMayBeInUseErrors.has(error));
@@ -183,6 +183,78 @@ export async function ensureDaemonRunning(expectedConfig, cwd = process.cwd()) {
         throw error;
     }
 }
+/**
+ * `happy-elves start` is an explicit foreground recovery/entry command. When
+ * it finds a verified local Daemon, restart that exact owner so the process
+ * always loads the currently installed package before the browser opens.
+ *
+ * The lower-level `ensureDaemonRunning()` deliberately remains idempotent for
+ * `happy-elves daemon start`, enrollment rollback, and service recovery.
+ */
+export async function restartDaemonForBootstrap(expectedConfig, cwd = process.cwd(), options = {}) {
+    const readStatus = options.readStatus ?? localDaemonStatus;
+    const inspectRuntime = options.inspectRuntime ?? inspectLocalDaemonRuntime;
+    const readIdentity = options.readIdentity ?? readLocalDaemonPidIdentity;
+    const stopLocal = options.stopLocal ?? stopLocalDaemon;
+    const stopStarted = options.stopStarted ?? stopSpawnedDaemon;
+    const ensureRunning = options.ensureRunning ?? ensureDaemonRunning;
+    const assertConfigFence = options.assertConfigFence ?? assertDaemonConfigFence;
+    await assertConfigFence(expectedConfig);
+    const current = await readStatus();
+    assertLocalDaemonVerified(current);
+    if (!current.running) {
+        return {
+            ...await ensureRunning(expectedConfig, cwd),
+            restarted: false,
+        };
+    }
+    const owner = await readIdentity();
+    if (!owner.record || owner.record.pid !== current.pid) {
+        throw new CliError("The verified Daemon owner identity changed before restart; no process was signalled.", "DAEMON_PID_INVALID");
+    }
+    const runtime = await inspectRuntime(expectedConfig);
+    if (runtime.state !== "match" && runtime.state !== "missing") {
+        const code = runtime.state === "invalid"
+            ? "DAEMON_RUNTIME_IDENTITY_INVALID"
+            : runtime.state === "owner-mismatch"
+                ? "DAEMON_RUNTIME_IDENTITY_MISMATCH"
+                : "DAEMON_RUNTIME_CONFIG_MISMATCH";
+        throw new CliError("The running Daemon identity could not be matched to daemon.json, so happy-elves start did not restart or signal it.", code);
+    }
+    if (runtime.state === "match" &&
+        (runtime.identity.pid !== owner.record.pid ||
+            runtime.identity.instanceNonce !== owner.record.instanceNonce ||
+            runtime.identity.startedAt !== owner.record.startedAt)) {
+        throw new CliError("The Daemon runtime owner changed while restart was being verified; no process was signalled.", "DAEMON_RUNTIME_IDENTITY_MISMATCH");
+    }
+    const previousInstanceGeneration = owner.record.instanceNonce;
+    await assertConfigFence(expectedConfig);
+    const stopped = await stopLocal(startDaemonTimeoutMs, {
+        pid: owner.record.pid,
+        instanceNonce: owner.record.instanceNonce,
+        startedAt: owner.record.startedAt,
+    });
+    if (stopped.running || stopped.alive) {
+        throw new CliError("Daemon did not stop before the restart deadline; no replacement process was started.", "DAEMON_STOP_FAILED");
+    }
+    const started = await ensureRunning(expectedConfig, cwd);
+    if (started.instanceGeneration === previousInstanceGeneration) {
+        if (started.startedHandle) {
+            try {
+                await stopStarted(started.startedHandle);
+            }
+            catch (error) {
+                throw new CliError(`Daemon restart returned a stale generation and its replacement cleanup failed: ${error instanceof Error ? error.message : String(error)}`, "DAEMON_START_CLEANUP_FAILED");
+            }
+        }
+        throw new CliError("Daemon restart did not publish a fresh process generation.", "DAEMON_RESTART_GENERATION_MISMATCH");
+    }
+    return {
+        ...started,
+        restarted: true,
+        previousInstanceGeneration,
+    };
+}
 function committedConfigInUseError(message) {
     return markCommittedConfigMayBeInUse(new CliError(message, "DAEMON_START_CONFLICT"));
 }

package/apps/cli/dist/commands/lib/bootstrap-device-recovery.d.ts

@@ -2,7 +2,7 @@ import { ControllerClient } from "../../../../../packages/client/dist/index.js";
 import { type DeviceRecoveryIntentV1 } from "../../../../../packages/shared/dist/index.js";
 import { stopSpawnedDaemon } from "./local-daemon.js";
 import { type StartConfigPreflight } from "./bootstrap-config.js";
-import { ensureDaemonRunning } from "./bootstrap-daemon.js";
+import { type ensureDaemonRunning } from "./bootstrap-daemon.js";
 export declare function startDeviceRecoveryBootstrap(params: {
     flags: Record<string, string | boolean>;
     preflight: StartConfigPreflight;
@@ -12,12 +12,15 @@ export declare function startDeviceRecoveryBootstrap(params: {
 }): Promise<void>;
 export declare function deviceRecoveryIntentNeedsReplacement(intent: Pick<DeviceRecoveryIntentV1, "status">): boolean;
 export declare function isTerminalRecoveryIntentCreationFailure(error: unknown): boolean;
-export declare function projectRecoveredDaemonReadinessFailure(started: Awaited<ReturnType<typeof ensureDaemonRunning>>, machineName: string, readinessError: unknown, options?: {
+export declare function projectRecoveredDaemonReadinessFailure(started: Awaited<ReturnType<typeof ensureDaemonRunning>> & {
+    restarted?: boolean;
+}, machineName: string, readinessError: unknown, options?: {
     stopStarted?: typeof stopSpawnedDaemon;
 }): Promise<{
     online: false;
     pid?: number;
     started: boolean;
+    restarted: boolean;
     name: string;
     needsAttention: string;
 }>;

package/apps/cli/dist/commands/lib/bootstrap-device-recovery.js

@@ -7,10 +7,10 @@ import { accountFingerprintV1, deviceRecoveryTtlMsV1, randomId, } from "../../..
 import { daemonRuntimeConfigFingerprint } from "../../../../../packages/shared/dist/node/daemon-process.js";
 import { CliError } from "../../errors.js";
 import { ok } from "./json.js";
-import { assertLocalDaemonVerified, ensureRunningDaemonAutostart, inspectLocalDaemonRuntime, localDaemonStatus, stopSpawnedDaemon, } from "./local-daemon.js";
+import { assertLocalDaemonVerified, localDaemonStatus, stopSpawnedDaemon, } from "./local-daemon.js";
 import { withAccountConfigTransaction } from "./config.js";
 import { controllerBaseUrl } from "./bootstrap-config.js";
-import { ensureDaemonRunning, readDaemonProjectionBaseline, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
+import { readDaemonProjectionBaseline, restartDaemonForBootstrap, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
 import { openUrl } from "./bootstrap-output.js";
 import { assertNoPendingDaemonEnrollmentForDeviceRecovery } from "./daemon-enrollment-intent.js";
 import { configDir, configPath, deviceRecoveryPendingPath, startDaemonTimeoutMs } from "./paths.js";
@@ -318,34 +318,10 @@ async function ensureRecoveredDaemonReady(params) {
             ...projection,
             ...(current.pid ? { pid: current.pid } : {}),
             started: false,
+            restarted: false,
             needsAttention: error instanceof Error ? error.message : "The local Daemon owner needs verification.",
         };
     }
-    if (current.running) {
-        const runtime = await inspectLocalDaemonRuntime(params.daemonConfig);
-        if (runtime.state !== "match") {
-            const projection = await readProjection();
-            const needsAttention = runtime.state === "missing"
-                ? "Automatic startup metadata will be repaired on the next controlled Daemon restart."
-                : "The running Daemon identity needs repair before Happy Elves can manage its process.";
-            return {
-                ...projection,
-                ...(current.pid ? { pid: current.pid } : {}),
-                started: false,
-                needsAttention,
-            };
-        }
-        const autostart = await ensureRunningDaemonAutostart();
-        const projection = await readProjection();
-        return {
-            ...projection,
-            ...(current.pid ? { pid: current.pid } : {}),
-            started: false,
-            ...(autostart.state === "needs-attention"
-                ? { needsAttention: autostart.message }
-                : {}),
-        };
-    }
     let baseline;
     try {
         baseline = await readDaemonProjectionBaseline(client, params.daemonConfig.machineId, {
@@ -357,37 +333,51 @@ async function ensureRecoveredDaemonReady(params) {
     }
     let started;
     try {
-        started = await ensureDaemonRunning(params.daemonConfig, params.cwd);
-    }
-    catch (error) {
-        const projection = await readProjection();
-        return {
-            ...projection,
-            ...(current.pid ? { pid: current.pid } : {}),
-            started: false,
-            needsAttention: error instanceof Error ? error.message : "The Daemon could not be started automatically.",
-        };
-    }
-    try {
-        const readiness = await waitForDaemonReadiness(client, params.daemonConfig.machineId, {
-            baseline,
-            expectedInstanceGeneration: started.instanceGeneration,
-            requireFreshProjection: started.started,
-            timeoutMs: startDaemonTimeoutMs,
+        const ready = await withAccountConfigTransaction(async (transaction) => {
+            const currentDaemonConfig = await transaction.readDaemon();
+            if (!currentDaemonConfig ||
+                daemonRuntimeConfigFingerprint(currentDaemonConfig) !== daemonRuntimeConfigFingerprint(params.daemonConfig)) {
+                throw new CliError("The local Daemon identity changed before restart. No process was signalled.", "CONFIG_CHANGED_DURING_START");
+            }
+            started = await restartDaemonForBootstrap(params.daemonConfig, params.cwd);
+            const readiness = await waitForDaemonReadiness(client, params.daemonConfig.machineId, {
+                baseline,
+                expectedInstanceGeneration: started.instanceGeneration,
+                requireFreshProjection: started.started || started.restarted,
+                timeoutMs: startDaemonTimeoutMs,
+            });
+            if (readiness.phase !== "relay-authenticated" || !readiness.machine?.online) {
+                throw new CliError("The Daemon did not authenticate before the startup deadline.", "DAEMON_ONLINE_TIMEOUT");
+            }
+            const confirmedDaemonConfig = await transaction.readDaemon();
+            if (!confirmedDaemonConfig ||
+                daemonRuntimeConfigFingerprint(confirmedDaemonConfig) !== daemonRuntimeConfigFingerprint(params.daemonConfig)) {
+                throw new CliError("The local Daemon identity changed during restart.", "CONFIG_CHANGED_DURING_START");
+            }
+            return { started, readiness };
         });
-        if (readiness.phase !== "relay-authenticated" || !readiness.machine?.online) {
-            throw new CliError("The Daemon did not authenticate before the startup deadline.", "DAEMON_ONLINE_TIMEOUT");
-        }
-        const pid = started.local.pid ?? started.startedPid;
+        const pid = ready.started.local.pid ?? ready.started.startedPid;
         return {
             online: true,
             ...(pid ? { pid } : {}),
-            started: started.started,
-            name: readiness.machine.name ?? params.daemonConfig.machineName,
+            started: ready.started.started,
+            restarted: ready.started.restarted,
+            name: ready.readiness.machine?.name ?? params.daemonConfig.machineName,
         };
     }
     catch (error) {
-        return await projectRecoveredDaemonReadinessFailure(started, params.daemonConfig.machineName, error);
+        if (started) {
+            return await projectRecoveredDaemonReadinessFailure(started, params.daemonConfig.machineName, error);
+        }
+        const settled = await localDaemonStatus().catch(() => current);
+        return {
+            online: false,
+            name: params.daemonConfig.machineName,
+            ...(settled.pid ? { pid: settled.pid } : {}),
+            started: false,
+            restarted: current.running && !settled.running,
+            needsAttention: error instanceof Error ? error.message : "The Daemon could not be restarted automatically.",
+        };
     }
 }
 export async function projectRecoveredDaemonReadinessFailure(started, machineName, readinessError, options = {}) {
@@ -408,6 +398,7 @@ export async function projectRecoveredDaemonReadinessFailure(started, machineNam
         online: false,
         ...(started.local.pid ?? started.startedPid ? { pid: started.local.pid ?? started.startedPid } : {}),
         started: daemonCleanupError ? started.started : false,
+        restarted: started.restarted === true,
         name: machineName,
         needsAttention,
     };

package/apps/cli/dist/commands/lib/bootstrap.js

@@ -10,7 +10,7 @@ import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, inspe
 import { redactedRelayUrl, withAccountConfigTransaction, } from "./config.js";
 import { cliErrorFromFetch } from "./relay-http.js";
 import { controllerBaseUrl, ensureControllerConfig, ensureDaemonPaired, readStartConfigPreflight } from "./bootstrap-config.js";
-import { ensureDaemonRunning, readDaemonProjectionBaseline, startFailureMayUseCommittedConfig, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
+import { readDaemonProjectionBaseline, restartDaemonForBootstrap, startFailureMayUseCommittedConfig, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
 import { openUrl, writeHumanStartOutput } from "./bootstrap-output.js";
 import { startJoinBootstrap } from "./bootstrap-join.js";
 import { reconcileSatisfiedDeviceRecoveryPending, startDeviceRecoveryBootstrap } from "./bootstrap-device-recovery.js";
@@ -85,16 +85,15 @@ export async function startBootstrap(flags) {
         if (daemonBefore.running && preflight.kind !== "ready") {
             throw new CliError("A verified daemon is running, but the matching controller/daemon config pair is incomplete. No configuration or daemon process was changed. Run happy-elves doctor before recovering this workspace.", "CONFIG_SPLIT_BRAIN");
         }
-        // A running owner is accepted only when its signed runtime marker proves
-        // that it loaded the same daemon identity we just read under this lease.
-        // Ordinary `start` never restarts a healthy daemon because package files
-        // happen to have a newer mtime.
+        // Top-level `happy-elves start` deliberately restarts a verified owner so
+        // it always loads the currently installed package. A missing marker is the
+        // supported legacy-upgrade case: exact PID v2 ownership still fences the
+        // stop, and the replacement publishes a fresh marker. Invalid, mismatched,
+        // or unverified identities remain fail-closed and are never signalled.
         if (!daemonProcessNeedsAttention && daemonBefore.running && preflight.daemon) {
             const runtime = await inspectLocalDaemonRuntime(preflight.daemon);
-            if (runtime.state !== "match") {
-                daemonProcessNeedsAttention = runtime.state === "missing"
-                    ? "Automatic startup metadata will be repaired on the next controlled Daemon restart."
-                    : "The running Daemon identity needs repair before Happy Elves can manage its process.";
+            if (runtime.state !== "match" && runtime.state !== "missing") {
+                daemonProcessNeedsAttention = "The running Daemon identity needs repair before Happy Elves can manage its process.";
             }
         }
         const networkDeadline = Date.now() + startDaemonTimeoutMs;
@@ -187,19 +186,20 @@ export async function startBootstrap(flags) {
                         started: false,
                         startedPid: undefined,
                         committedConfigMayBeInUse: daemonBefore.running,
+                        restarted: false,
                     },
                     machine: baseline,
                     invite,
                     daemonProcessNeedsAttention,
                 };
             }
-            const daemon = await ensureDaemonRunning(daemonState.config, cwd);
+            const daemon = await restartDaemonForBootstrap(daemonState.config, cwd);
             startedHandle = daemon.startedHandle;
             committedConfigMayBeInUse = daemon.committedConfigMayBeInUse === true;
             const readiness = await waitForDaemonReadiness(client, daemonState.config.machineId, {
                 baseline,
                 expectedInstanceGeneration: daemon.instanceGeneration,
-                requireFreshProjection: daemon.started,
+                requireFreshProjection: daemon.started || daemon.restarted,
                 // Lifetime-lock acquisition/reclaim and relay-authenticated readiness
                 // are separate bounded phases.
                 timeoutMs: startDaemonTimeoutMs,
@@ -317,8 +317,9 @@ export async function startBootstrap(flags) {
             pid: daemon.local.pid ?? daemon.startedPid,
             pidPath: daemon.local.pidPath,
             started: daemon.started,
-            alreadyRunning: daemonBefore.running || daemon.committedConfigMayBeInUse === true,
-            restarted: false,
+            alreadyRunning: daemon.restarted !== true &&
+                (daemonBefore.running || daemon.committedConfigMayBeInUse === true),
+            restarted: daemon.restarted,
             ...(daemonNeedsAttention ? { needsAttention: daemonNeedsAttention } : {}),
         },
         ...(invite ? {

package/apps/cli/dist/commands/lib/usage.js

@@ -12,6 +12,15 @@ Show the current Account, Daemon, and latest Session state.
     doctor: `Usage: happy-elves doctor [--relay <url>] [--json]
 
 Check local Device access, Account consistency, service reachability, and Daemon state.
+`,
+    diagnostics: `Usage:
+  happy-elves diagnostics surfaces --json
+  happy-elves diagnostics capture --device <deviceId> --surface <surfaceId> [--timeout 30s] --json
+  happy-elves diagnostics watch --device <deviceId> --surface <surfaceId> [--duration 10m] --jsonl
+
+Observe privacy-filtered layout, focus, viewport, pointer, and scroll telemetry
+from a Device that explicitly enabled Settings > Diagnostics > Share live diagnostics.
+Probe traffic is end-to-end encrypted and expires after ten minutes.
 `,
     account: `Usage:
   happy-elves account create --relay <url> [--device-id <id>] [--device-name <name>] [--reveal-secrets] --json
@@ -300,6 +309,11 @@ Advanced and compatibility commands:
   relay status [--relay <url>] [--json]
   relay doctor [--relay <url>] [--json]
 
+  # Privacy-filtered diagnostics shared by another trusted Device.
+  diagnostics surfaces --json
+  diagnostics capture --device <deviceId> --surface <surfaceId> --json
+  diagnostics watch --device <deviceId> --surface <surfaceId> --jsonl
+
 Usage:
   happy-elves <domain> <action> [args] [flags]
   happy-elves <domain> --help
@@ -316,7 +330,7 @@ More:
   happy-elves --version
   happy-elves version --json
   happy-elves <domain> --help
-  start, status, doctor, collect, config, account, daemon, relay, token, gateway, loop.
+  start, status, doctor, collect, config, account, daemon, relay, diagnostics, token, gateway, loop.
   orchestrator, skill.
 `;
 }