@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/daemon/state-dir-check-service.d.ts

@@ -0,0 +1,43 @@
+/**
+ * State-dir self-terminate guard as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * RUSH-2367: self-terminate if this daemon's own state directory has been
+ * removed out from under it — the shape of a leaked test-fixture daemon whose
+ * /tmp HOME was deleted by its test's own cleanup while the process itself
+ * somehow survived. Nothing else can reach a daemon in that state: a
+ * different HOME resolves a different `ensureDaemonDir()` and therefore a
+ * different instance registry — without this it runs forever. Reads the
+ * lifetime marker directly, never the local `ensureDaemonDir()` wrapper,
+ * which recreates the directory as a side effect and would defeat the check.
+ * Heartbeat/status paths may recreate the directory and pid file after a
+ * deletion; they never recreate this per-lifetime token.
+ *
+ * `lifetimePath`/`lifetimeToken` are per-boot constants computed once at
+ * `runDaemon()` start and passed in via the constructor, along with the
+ * shutdown callback. Registering (and starting) this service happens AFTER
+ * `runDaemon()` defines its `handleShutdown` — unlike the other four migrated
+ * services, which register before `supervisor.startAll()` — because the
+ * supervisor fires an immediate first tick on start, and calling an
+ * as-yet-undefined `handleShutdown` const at that point would throw. See the
+ * registration site in daemon.ts for the deferred `supervisor.register()` +
+ * `supervisor.start()` pairing this requires.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export interface StateDirCheckServiceOptions {
+    lifetimePath: string;
+    lifetimeToken: string;
+    onMissing: () => void;
+}
+export declare class StateDirCheckService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs = 5000;
+    private readonly lifetimePath;
+    private readonly lifetimeToken;
+    private readonly onMissing;
+    constructor(opts: StateDirCheckServiceOptions);
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/state-dir-check-service.js

@@ -0,0 +1,63 @@
+/**
+ * State-dir self-terminate guard as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * RUSH-2367: self-terminate if this daemon's own state directory has been
+ * removed out from under it — the shape of a leaked test-fixture daemon whose
+ * /tmp HOME was deleted by its test's own cleanup while the process itself
+ * somehow survived. Nothing else can reach a daemon in that state: a
+ * different HOME resolves a different `ensureDaemonDir()` and therefore a
+ * different instance registry — without this it runs forever. Reads the
+ * lifetime marker directly, never the local `ensureDaemonDir()` wrapper,
+ * which recreates the directory as a side effect and would defeat the check.
+ * Heartbeat/status paths may recreate the directory and pid file after a
+ * deletion; they never recreate this per-lifetime token.
+ *
+ * `lifetimePath`/`lifetimeToken` are per-boot constants computed once at
+ * `runDaemon()` start and passed in via the constructor, along with the
+ * shutdown callback. Registering (and starting) this service happens AFTER
+ * `runDaemon()` defines its `handleShutdown` — unlike the other four migrated
+ * services, which register before `supervisor.startAll()` — because the
+ * supervisor fires an immediate first tick on start, and calling an
+ * as-yet-undefined `handleShutdown` const at that point would throw. See the
+ * registration site in daemon.ts for the deferred `supervisor.register()` +
+ * `supervisor.start()` pairing this requires.
+ */
+import { BasePeriodicService } from './service.js';
+import * as fs from 'fs';
+/** Matches the historical inline interval (daemon.ts STATE_DIR_CHECK_TICK_MS), overridable for tests. */
+const STATE_DIR_CHECK_TICK_MS = 60_000;
+/** Hard cap per tick — a single synchronous file read, far above what it could ever need. */
+const STATE_DIR_CHECK_DEADLINE_MS = 5_000;
+export class StateDirCheckService extends BasePeriodicService {
+    id = 'state-dir-check';
+    intervalMs = Number(process.env.AGENTS_DAEMON_STATE_DIR_CHECK_MS) || STATE_DIR_CHECK_TICK_MS;
+    deadlineMs = STATE_DIR_CHECK_DEADLINE_MS;
+    lifetimePath;
+    lifetimeToken;
+    onMissing;
+    constructor(opts) {
+        super();
+        this.lifetimePath = opts.lifetimePath;
+        this.lifetimeToken = opts.lifetimeToken;
+        this.onMissing = opts.onMissing;
+    }
+    async onStart(_ctx) {
+        // No connections/handles to open — each tick re-reads the lifetime marker.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
+    }
+    async onTick(ctx) {
+        let markerMatches = false;
+        try {
+            markerMatches = fs.readFileSync(this.lifetimePath, 'utf-8') === this.lifetimeToken;
+        }
+        catch {
+            // A missing state dir or marker is the condition this guard detects.
+        }
+        if (!markerMatches) {
+            ctx.log('WARN', `Daemon state dir no longer exists; exiting (self-terminate guard)`);
+            this.onMissing();
+        }
+    }
+}

package/dist/lib/daemon/supervisor.d.ts

@@ -0,0 +1,87 @@
+/**
+ * ServiceSupervisor (RUSH-3193 P1).
+ *
+ * Owns the timer for every registered `PeriodicService`, replacing the bare
+ * `setInterval` closures in `runDaemon()`. Two failure modes motivated it,
+ * both observed in production:
+ *
+ *  - A throw escaping a tick's local try/catch used to hit the process-wide
+ *    `uncaughtException` handler and `process.exit(1)` the whole daemon,
+ *    taking every OTHER service down with it. Here, a tick failure is caught
+ *    per-service and never propagates past `runTick`.
+ *  - A tick that hangs on an unbounded await (SSH, keychain) used to latch its
+ *    local in-flight guard `true` forever, silently freezing that one service
+ *    for the daemon's life (observed ~51h). Here, every tick races a
+ *    `deadlineMs` timeout; when the deadline wins, the guard is released in
+ *    `finally` regardless of whether the real tick promise ever settles, so
+ *    the NEXT scheduled tick can still run.
+ *
+ * Repeated failures (thrown or timed-out) open a circuit breaker: the service
+ * is parked (its timer stopped) and retried on exponential backoff via its own
+ * `restart()`, while every sibling service keeps ticking on its own timer,
+ * unaffected.
+ */
+import type { DaemonServiceId } from '../daemon-services.js';
+import type { DaemonContext, DaemonService, ServiceHealth } from './service.js';
+export interface ServiceSupervisorOptions {
+    /** Consecutive tick failures (throw or deadline breach) before a service is parked. Default 3. */
+    parkAfterFailures?: number;
+    /** First restart backoff delay, doubled on each further failed restart attempt. Default 5s. */
+    backoffBaseMs?: number;
+    /** Backoff ceiling. Default 5 minutes. */
+    backoffMaxMs?: number;
+}
+export declare class ServiceSupervisor {
+    private readonly registry;
+    private ctx;
+    private readonly parkAfterFailures;
+    private readonly backoffBaseMs;
+    private readonly backoffMaxMs;
+    constructor(opts?: ServiceSupervisorOptions);
+    /**
+     * Register a service. Must be called before `startAll()`.
+     *
+     * Accepts both `PeriodicService` (ticked on a fixed interval) and
+     * lifecycle-only `DaemonService` (started once, stopped at shutdown). The
+     * supervisor uses `isPeriodicService()` to decide whether to schedule a timer
+     * for each registered entry.
+     */
+    register(service: DaemonService): void;
+    /** Start every registered service and begin ticking each on its own timer. */
+    startAll(ctx: DaemonContext): Promise<void>;
+    /** Stop every registered service and clear all timers. */
+    stopAll(): Promise<void>;
+    /** Force one service to restart right now, outside its normal backoff schedule. Drives `agents daemon services restart <id>` (RUSH-3193 P4). */
+    restartOne(id: DaemonServiceId): Promise<void>;
+    /** Whether `id` is registered on this supervisor. A service disabled at daemon boot is never registered — see {@link start}. */
+    isRegistered(id: DaemonServiceId): boolean;
+    /** Every currently registered service id. */
+    registeredIds(): DaemonServiceId[];
+    /**
+     * Start one registered service live — drives `agents daemon services enable
+     * <id>` (RUSH-3193 P4). Only affects a service already registered on this
+     * supervisor: one disabled at daemon boot was never constructed or
+     * registered, so enabling it live is not possible without a daemon restart
+     * (the CLI falls back to that advice — see `commands/daemon.ts`).
+     */
+    start(id: DaemonServiceId): Promise<void>;
+    /** Stop one registered service live — drives `agents daemon services disable <id>` (RUSH-3193 P4). */
+    stop(id: DaemonServiceId): Promise<void>;
+    /** Health for every registered service, keyed by service id. */
+    health(): Record<string, ServiceHealth>;
+    private startOne;
+    private stopOne;
+    private scheduleTimer;
+    /**
+     * Run one tick under a hard deadline. The deadline is enforced with
+     * `Promise.race`, not true cancellation — JS cannot abort an arbitrary
+     * in-flight await. What matters for the freeze this replaces is that
+     * `inFlight` is released in `finally` as soon as the race settles, so an
+     * abandoned tick can never block the next scheduled one again.
+     */
+    private runTick;
+    private park;
+    private scheduleRestart;
+    private attemptRestart;
+    private recordFailure;
+}

package/dist/lib/daemon/supervisor.js

@@ -0,0 +1,298 @@
+/**
+ * ServiceSupervisor (RUSH-3193 P1).
+ *
+ * Owns the timer for every registered `PeriodicService`, replacing the bare
+ * `setInterval` closures in `runDaemon()`. Two failure modes motivated it,
+ * both observed in production:
+ *
+ *  - A throw escaping a tick's local try/catch used to hit the process-wide
+ *    `uncaughtException` handler and `process.exit(1)` the whole daemon,
+ *    taking every OTHER service down with it. Here, a tick failure is caught
+ *    per-service and never propagates past `runTick`.
+ *  - A tick that hangs on an unbounded await (SSH, keychain) used to latch its
+ *    local in-flight guard `true` forever, silently freezing that one service
+ *    for the daemon's life (observed ~51h). Here, every tick races a
+ *    `deadlineMs` timeout; when the deadline wins, the guard is released in
+ *    `finally` regardless of whether the real tick promise ever settles, so
+ *    the NEXT scheduled tick can still run.
+ *
+ * Repeated failures (thrown or timed-out) open a circuit breaker: the service
+ * is parked (its timer stopped) and retried on exponential backoff via its own
+ * `restart()`, while every sibling service keeps ticking on its own timer,
+ * unaffected.
+ */
+import { recordSubsystemOk, recordSubsystemError, recordSubsystemState } from '../daemon-health.js';
+import { isPeriodicService } from './service.js';
+const DEFAULT_PARK_AFTER_FAILURES = 3;
+const DEFAULT_BACKOFF_BASE_MS = 5_000;
+const DEFAULT_BACKOFF_MAX_MS = 5 * 60_000;
+export class ServiceSupervisor {
+    registry = new Map();
+    ctx = null;
+    parkAfterFailures;
+    backoffBaseMs;
+    backoffMaxMs;
+    constructor(opts = {}) {
+        this.parkAfterFailures = opts.parkAfterFailures ?? DEFAULT_PARK_AFTER_FAILURES;
+        this.backoffBaseMs = opts.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS;
+        this.backoffMaxMs = opts.backoffMaxMs ?? DEFAULT_BACKOFF_MAX_MS;
+    }
+    /**
+     * Register a service. Must be called before `startAll()`.
+     *
+     * Accepts both `PeriodicService` (ticked on a fixed interval) and
+     * lifecycle-only `DaemonService` (started once, stopped at shutdown). The
+     * supervisor uses `isPeriodicService()` to decide whether to schedule a timer
+     * for each registered entry.
+     */
+    register(service) {
+        if (this.registry.has(service.id))
+            throw new Error(`service '${service.id}' is already registered`);
+        this.registry.set(service.id, {
+            service,
+            state: 'idle',
+            lastRunMs: 0,
+            consecutiveFailures: 0,
+            restartAttempts: 0,
+            inFlight: false,
+            everStarted: false,
+        });
+    }
+    /** Start every registered service and begin ticking each on its own timer. */
+    async startAll(ctx) {
+        this.ctx = ctx;
+        for (const id of this.registry.keys())
+            await this.startOne(id);
+    }
+    /** Stop every registered service and clear all timers. */
+    async stopAll() {
+        for (const id of this.registry.keys())
+            await this.stopOne(id);
+    }
+    /** Force one service to restart right now, outside its normal backoff schedule. Drives `agents daemon services restart <id>` (RUSH-3193 P4). */
+    async restartOne(id) {
+        const entry = this.registry.get(id);
+        if (!entry)
+            throw new Error(`service '${id}' is not registered`);
+        if (entry.restartTimer) {
+            clearTimeout(entry.restartTimer);
+            entry.restartTimer = undefined;
+        }
+        await this.attemptRestart(id);
+    }
+    /** Whether `id` is registered on this supervisor. A service disabled at daemon boot is never registered — see {@link start}. */
+    isRegistered(id) {
+        return this.registry.has(id);
+    }
+    /** Every currently registered service id. */
+    registeredIds() {
+        return Array.from(this.registry.keys());
+    }
+    /**
+     * Start one registered service live — drives `agents daemon services enable
+     * <id>` (RUSH-3193 P4). Only affects a service already registered on this
+     * supervisor: one disabled at daemon boot was never constructed or
+     * registered, so enabling it live is not possible without a daemon restart
+     * (the CLI falls back to that advice — see `commands/daemon.ts`).
+     */
+    async start(id) {
+        const entry = this.registry.get(id);
+        if (!entry)
+            throw new Error(`service '${id}' is not registered`);
+        if (entry.state === 'running')
+            return;
+        await this.startOne(id);
+    }
+    /** Stop one registered service live — drives `agents daemon services disable <id>` (RUSH-3193 P4). */
+    async stop(id) {
+        const entry = this.registry.get(id);
+        if (!entry)
+            throw new Error(`service '${id}' is not registered`);
+        if (entry.state === 'stopped')
+            return;
+        await this.stopOne(id);
+    }
+    /** Health for every registered service, keyed by service id. */
+    health() {
+        const out = {};
+        for (const [id, entry] of this.registry) {
+            out[id] = {
+                state: entry.state,
+                lastRunMs: entry.lastRunMs,
+                lastError: entry.lastError,
+                consecutiveFailures: entry.consecutiveFailures,
+            };
+        }
+        return out;
+    }
+    async startOne(id) {
+        const entry = this.registry.get(id);
+        const ctx = this.ctx;
+        if (!entry || !ctx)
+            return;
+        try {
+            await entry.service.start(ctx);
+        }
+        catch (err) {
+            this.recordFailure(entry, id, err);
+            this.park(id);
+            return;
+        }
+        entry.everStarted = true;
+        entry.state = 'running';
+        recordSubsystemState(id, 'running');
+        if (isPeriodicService(entry.service)) {
+            const startupDelayMs = entry.service.startupDelayMs ?? 0;
+            if (startupDelayMs > 0) {
+                // Defer BOTH the first tick and the recurring interval's start until the
+                // delay elapses — starting the interval at t=0 would fire its own ticks
+                // on top of the staggered one instead of after it.
+                entry.startupTimer = setTimeout(() => {
+                    entry.startupTimer = undefined;
+                    this.scheduleTimer(id);
+                    void this.runTick(id);
+                }, startupDelayMs);
+            }
+            else {
+                this.scheduleTimer(id);
+                void this.runTick(id);
+            }
+        }
+        else {
+            // Lifecycle-only service: record health once on successful start (no ticks).
+            entry.lastRunMs = Date.now();
+            recordSubsystemOk(id);
+        }
+    }
+    async stopOne(id) {
+        const entry = this.registry.get(id);
+        if (!entry)
+            return;
+        if (entry.timer) {
+            clearInterval(entry.timer);
+            entry.timer = undefined;
+        }
+        if (entry.restartTimer) {
+            clearTimeout(entry.restartTimer);
+            entry.restartTimer = undefined;
+        }
+        if (entry.startupTimer) {
+            clearTimeout(entry.startupTimer);
+            entry.startupTimer = undefined;
+        }
+        entry.state = 'stopped';
+        recordSubsystemState(id, 'stopped');
+        if (!entry.everStarted)
+            return; // start() never succeeded — nothing to stop.
+        try {
+            await entry.service.stop();
+        }
+        catch (err) {
+            this.ctx?.log('WARN', `service '${id}' stop failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    scheduleTimer(id) {
+        const entry = this.registry.get(id);
+        if (!entry || !isPeriodicService(entry.service))
+            return;
+        entry.timer = setInterval(() => { void this.runTick(id); }, entry.service.intervalMs);
+    }
+    /**
+     * Run one tick under a hard deadline. The deadline is enforced with
+     * `Promise.race`, not true cancellation — JS cannot abort an arbitrary
+     * in-flight await. What matters for the freeze this replaces is that
+     * `inFlight` is released in `finally` as soon as the race settles, so an
+     * abandoned tick can never block the next scheduled one again.
+     */
+    async runTick(id) {
+        const entry = this.registry.get(id);
+        const ctx = this.ctx;
+        if (!entry || !ctx || entry.state !== 'running' || entry.inFlight)
+            return;
+        // runTick is only called for periodic services (from scheduleTimer and startOne).
+        // The isPeriodicService guard here keeps TypeScript narrowing correct.
+        if (!isPeriodicService(entry.service))
+            return;
+        const periodicService = entry.service;
+        entry.inFlight = true;
+        let deadlineTimer;
+        try {
+            const deadline = new Promise((_, reject) => {
+                deadlineTimer = setTimeout(() => reject(new Error(`tick exceeded deadline of ${periodicService.deadlineMs}ms`)), periodicService.deadlineMs);
+            });
+            await Promise.race([periodicService.tick(ctx), deadline]);
+            entry.consecutiveFailures = 0;
+            entry.lastError = undefined;
+            entry.lastRunMs = Date.now();
+            recordSubsystemOk(id);
+        }
+        catch (err) {
+            this.recordFailure(entry, id, err);
+            if (entry.consecutiveFailures >= this.parkAfterFailures)
+                this.park(id);
+        }
+        finally {
+            if (deadlineTimer)
+                clearTimeout(deadlineTimer);
+            entry.inFlight = false;
+        }
+    }
+    park(id) {
+        const entry = this.registry.get(id);
+        if (!entry || entry.state === 'parked' || entry.state === 'stopped')
+            return;
+        entry.state = 'parked';
+        recordSubsystemState(id, 'parked');
+        if (entry.timer) {
+            clearInterval(entry.timer);
+            entry.timer = undefined;
+        }
+        this.ctx?.log('WARN', `service '${id}' parked after ${entry.consecutiveFailures} consecutive failure(s)`);
+        this.scheduleRestart(id);
+    }
+    scheduleRestart(id) {
+        const entry = this.registry.get(id);
+        if (!entry)
+            return;
+        const delay = Math.min(this.backoffMaxMs, this.backoffBaseMs * 2 ** entry.restartAttempts);
+        entry.restartAttempts += 1;
+        entry.restartTimer = setTimeout(() => { void this.attemptRestart(id); }, delay);
+    }
+    async attemptRestart(id) {
+        const entry = this.registry.get(id);
+        const ctx = this.ctx;
+        if (!entry || !ctx || entry.state === 'stopped')
+            return;
+        try {
+            await entry.service.restart();
+            entry.everStarted = true; // restart() is stop()+start() on the service — a successful one means it is running again and owes a stop() at shutdown.
+            entry.state = 'running';
+            recordSubsystemState(id, 'running');
+            entry.consecutiveFailures = 0;
+            entry.restartAttempts = 0;
+            entry.lastError = undefined;
+            if (isPeriodicService(entry.service)) {
+                this.scheduleTimer(id);
+                void this.runTick(id);
+            }
+            else {
+                entry.lastRunMs = Date.now();
+            }
+            recordSubsystemOk(id);
+            ctx.log('INFO', `service '${id}' restarted`);
+        }
+        catch (err) {
+            this.recordFailure(entry, id, err);
+            entry.state = 'parked';
+            recordSubsystemState(id, 'parked');
+            this.scheduleRestart(id);
+        }
+    }
+    recordFailure(entry, id, err) {
+        const message = err instanceof Error ? err.message : String(err);
+        entry.consecutiveFailures += 1;
+        entry.lastError = message;
+        recordSubsystemError(id, message);
+        this.ctx?.log('WARN', `service '${id}' failed: ${message}`);
+    }
+}

package/dist/lib/daemon/watchdog-service.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Watchdog tick as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * Nudges this host's own stalled agent sessions. Gated on the `watchdog.enabled`
+ * device-config flag (`agents watchdog enable`), so the timer always fires but
+ * only does work when the user opted in — the check happens inside the tick
+ * itself, not the enable/disable registration gate, matching the pre-migration
+ * inline behavior (daemon.ts previously `WATCHDOG_TICK_MS`-interval closure).
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class WatchdogService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs = 120000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/watchdog-service.js

@@ -0,0 +1,40 @@
+/**
+ * Watchdog tick as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * Nudges this host's own stalled agent sessions. Gated on the `watchdog.enabled`
+ * device-config flag (`agents watchdog enable`), so the timer always fires but
+ * only does work when the user opted in — the check happens inside the tick
+ * itself, not the enable/disable registration gate, matching the pre-migration
+ * inline behavior (daemon.ts previously `WATCHDOG_TICK_MS`-interval closure).
+ */
+import { BasePeriodicService } from './service.js';
+import { getConfigValue } from '../device-config.js';
+import { emit } from '../feed/events.js';
+/** Matches the historical inline interval (daemon.ts WATCHDOG_TICK_MS). */
+const WATCHDOG_TICK_MS = 3 * 60_000;
+/** Hard cap per tick — `runWatchdogPass` is host-local (adds no SSH fan-out of its own, `watchdog/runner.ts:580`); short enough that a hang never freezes the service for long. */
+const WATCHDOG_DEADLINE_MS = 120_000;
+export class WatchdogService extends BasePeriodicService {
+    id = 'watchdog';
+    intervalMs = WATCHDOG_TICK_MS;
+    deadlineMs = WATCHDOG_DEADLINE_MS;
+    async onStart(_ctx) {
+        // No connections/handles to open — each tick re-reads the enable flag.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
+    }
+    async onTick(ctx) {
+        if (getConfigValue('watchdog.enabled').value !== true)
+            return;
+        const { runWatchdogPass } = await import('../watchdog/service.js');
+        const result = await runWatchdogPass({ nudge: true });
+        ctx.log('INFO', `watchdog: ${result.counts.total} live, ${result.counts.stalled} stalled, ${result.counts.nudged} nudged`);
+        emit('watchdog.action', {
+            module: 'watchdog',
+            total: result.counts.total,
+            stalled: result.counts.stalled,
+            nudged: result.counts.nudged,
+        });
+    }
+}

package/dist/lib/daemon-health.d.ts

@@ -22,6 +22,14 @@ export interface SubsystemHealth {
     consecutiveFailures: number;
     /** ISO timestamp of the most recent success, or null if it has never succeeded. */
     lastOkAt: string | null;
+    /**
+     * `ServiceSupervisor`'s lifecycle state (`idle`/`running`/`parked`/`stopped`),
+     * written by `recordSubsystemState` on every transition. Only present for
+     * supervisor-managed subsystems (RUSH-3193 P4) — a subsystem that predates the
+     * supervisor (e.g. `daemon-start`) never has this field, which is how `agents
+     * daemon services` tells a measured state from an inferred one.
+     */
+    state?: string;
 }
 /** Record a successful subsystem check-in — clears the failure streak. */
 export declare function recordSubsystemOk(subsystem: string, at?: string): void;
@@ -40,6 +48,13 @@ export declare function recordSubsystemError(subsystem: string, error: string, a
  * subsystem is left alone rather than given a blank record to decorate.
  */
 export declare function recordSubsystemErrorReason(subsystem: string, error: string, at?: string): void;
+/**
+ * Record a `ServiceSupervisor` lifecycle-state transition, without touching
+ * the ok/error streak. Cross-process readers (`agents daemon services`) have
+ * no other way to see `parked`/`stopped` vs `running` — `agents daemon
+ * status` runs as a separate process from the daemon (see module docblock).
+ */
+export declare function recordSubsystemState(subsystem: string, state: string): void;
 /** Read one subsystem's health record, or null if it has never reported in. */
 export declare function readSubsystemHealth(subsystem: string): SubsystemHealth | null;
 /** Read every subsystem's health record, sorted by subsystem name. */

package/dist/lib/daemon-health.js

@@ -52,14 +52,26 @@ function readAll() {
         return {};
     }
 }
+/**
+ * Never throws. `recordSubsystemOk`/`recordSubsystemError` are called from
+ * inside a service's error boundary (`ServiceSupervisor.runTick`'s catch, and
+ * its own catch-of-a-catch in `recordFailure`) — a write failure here (disk
+ * full, permission, or the state dir removed mid-run, which this daemon
+ * explicitly anticipates via the state-dir self-check) must degrade to a
+ * dropped health update, never escape as an unhandled rejection that would
+ * hit the process-wide handler and take down every OTHER service too.
+ */
 function writeAll(records) {
-    const healthPath = getHealthPath();
-    fs.mkdirSync(path.dirname(healthPath), { recursive: true });
-    fs.writeFileSync(healthPath, JSON.stringify(records), 'utf-8');
     try {
-        fs.chmodSync(healthPath, 0o600);
+        const healthPath = getHealthPath();
+        fs.mkdirSync(path.dirname(healthPath), { recursive: true });
+        fs.writeFileSync(healthPath, JSON.stringify(records), 'utf-8');
+        try {
+            fs.chmodSync(healthPath, 0o600);
+        }
+        catch { /* best effort */ }
     }
-    catch { /* best effort */ }
+    catch { /* see docblock above — health recording must never crash a caller */ }
 }
 function blankRecord(subsystem) {
     return { subsystem, lastError: null, lastErrorAt: null, consecutiveFailures: 0, lastOkAt: null };
@@ -104,6 +116,18 @@ export function recordSubsystemErrorReason(subsystem, error, at = new Date().toI
     all[subsystem] = { ...existing, lastError: error, lastErrorAt: at };
     writeAll(all);
 }
+/**
+ * Record a `ServiceSupervisor` lifecycle-state transition, without touching
+ * the ok/error streak. Cross-process readers (`agents daemon services`) have
+ * no other way to see `parked`/`stopped` vs `running` — `agents daemon
+ * status` runs as a separate process from the daemon (see module docblock).
+ */
+export function recordSubsystemState(subsystem, state) {
+    const all = readAll();
+    const existing = all[subsystem] ?? blankRecord(subsystem);
+    all[subsystem] = { ...existing, subsystem, state };
+    writeAll(all);
+}
 /** Read one subsystem's health record, or null if it has never reported in. */
 export function readSubsystemHealth(subsystem) {
     return readAll()[subsystem] ?? null;

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check';
+export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;
@@ -48,3 +48,10 @@ export declare function setDaemonServiceEnabled(id: DaemonServiceId, enabled: bo
 export declare function listDaemonServiceStates(): Array<DaemonServiceDef & {
     enabled: boolean;
 }>;
+/** Queue a live restart for `id`, to be picked up on the next SIGHUP reload. */
+export declare function queueDaemonServiceRestart(id: DaemonServiceId): void;
+/**
+ * Drain every queued restart request. Called once per SIGHUP reload by the
+ * daemon; never throws. Clears the file so a request is applied at most once.
+ */
+export declare function drainDaemonServiceRestartQueue(): DaemonServiceId[];