@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/lib/daemon/device-probe-service.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Device-probe tick as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * Refreshes registered devices' reachability and detects newly appeared
+ * tailnet nodes, dropping a sentinel per pending device so the menu-bar helper
+ * can surface "NEW DEVICES -> Register / Ignore". Refresh mode never
+ * auto-registers a newcomer; a machine without tailscale is a clean no-op.
+ * `reconcilePendingSentinels` re-subtracts the ignore-list AND the registered
+ * roster, so a dismissed or already-known device is never re-surfaced. On
+ * soft-fail (no tailscale) sentinels are still pruned so a hermetic test leak
+ * cannot leave fleet boxes in NEW DEVICES forever.
+ *
+ * The supervisor fires an immediate tick on start (see `service.ts`), which
+ * replaces the previous inline `void runDeviceProbeTick()` kick-off that
+ * cleared any leftover pollution set without waiting for the first interval.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class DeviceProbeService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs = 90000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/device-probe-service.js

@@ -0,0 +1,47 @@
+/**
+ * Device-probe tick as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * Refreshes registered devices' reachability and detects newly appeared
+ * tailnet nodes, dropping a sentinel per pending device so the menu-bar helper
+ * can surface "NEW DEVICES -> Register / Ignore". Refresh mode never
+ * auto-registers a newcomer; a machine without tailscale is a clean no-op.
+ * `reconcilePendingSentinels` re-subtracts the ignore-list AND the registered
+ * roster, so a dismissed or already-known device is never re-surfaced. On
+ * soft-fail (no tailscale) sentinels are still pruned so a hermetic test leak
+ * cannot leave fleet boxes in NEW DEVICES forever.
+ *
+ * The supervisor fires an immediate tick on start (see `service.ts`), which
+ * replaces the previous inline `void runDeviceProbeTick()` kick-off that
+ * cleared any leftover pollution set without waiting for the first interval.
+ */
+import { BasePeriodicService } from './service.js';
+/** Matches the historical inline interval (daemon.ts DEVICE_PROBE_TICK_MS). */
+const DEVICE_PROBE_TICK_MS = 3 * 60_000;
+/** Hard cap per tick — a tailnet + reachability sweep, short enough that a hang never freezes the service for long. */
+const DEVICE_PROBE_DEADLINE_MS = 90_000;
+export class DeviceProbeService extends BasePeriodicService {
+    id = 'device-probe';
+    intervalMs = DEVICE_PROBE_TICK_MS;
+    deadlineMs = DEVICE_PROBE_DEADLINE_MS;
+    async onStart(_ctx) {
+        // No connections/handles to open — each tick performs a fresh soft sync.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
+    }
+    async onTick(ctx) {
+        const { runDeviceSync } = await import('../devices/sync.js');
+        const { reconcilePendingSentinels, pruneDismissedPendingSentinels } = await import('../devices/pending.js');
+        const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
+        if (!dev.ok) {
+            await pruneDismissedPendingSentinels();
+            if (dev.reason)
+                ctx.log('WARN', `device probe soft-fail: ${dev.reason}`);
+            return;
+        }
+        await reconcilePendingSentinels(dev.pending);
+        if (dev.pending.length) {
+            ctx.log('INFO', `devices: ${dev.pending.length} new pending (${dev.pending.map((p) => p.name).join(', ')})`);
+        }
+    }
+}

package/dist/lib/daemon/keychain-reap-service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Keychain orphan reaper tick as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * Kills stuck keychain helper and `agents` processes whose keychain call
+ * never returned (RUSH-2232). Single-executor: only the daemon runs this, so
+ * no cross-device race.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class KeychainReapService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs = 30000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/keychain-reap-service.js

@@ -0,0 +1,32 @@
+/**
+ * Keychain orphan reaper tick as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * Kills stuck keychain helper and `agents` processes whose keychain call
+ * never returned (RUSH-2232). Single-executor: only the daemon runs this, so
+ * no cross-device race.
+ */
+import { BasePeriodicService } from './service.js';
+/** Matches the historical inline interval (daemon.ts KEYCHAIN_REAP_TICK_MS). */
+const KEYCHAIN_REAP_TICK_MS = 5 * 60_000;
+/** Hard cap per tick — a process-table scan + targeted kills, short enough a hang never freezes the service for long. */
+const KEYCHAIN_REAP_DEADLINE_MS = 30_000;
+export class KeychainReapService extends BasePeriodicService {
+    id = 'keychain-reap';
+    intervalMs = KEYCHAIN_REAP_TICK_MS;
+    deadlineMs = KEYCHAIN_REAP_DEADLINE_MS;
+    async onStart(_ctx) {
+        // No connections/handles to open — each tick performs a fresh process scan.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
+    }
+    async onTick(ctx) {
+        const { reapOrphanedKeychainProcesses } = await import('../secrets/reaper.js');
+        const result = reapOrphanedKeychainProcesses();
+        if (result.reaped > 0) {
+            ctx.log('WARN', `Reaped ${result.reaped} keychain orphan/stuck process(es)`);
+            for (const d of result.details)
+                ctx.log('WARN', `  ${d}`);
+        }
+    }
+}

package/dist/lib/daemon/monitor-engine-service.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MonitorEngine lifecycle as a `DaemonService` (RUSH-3193 P2).
+ *
+ * Wraps the `MonitorEngine` (event-triggered watchers) under the
+ * `ServiceSupervisor` contract. This is a lifecycle-only service — the engine
+ * runs its own internal event loop; the supervisor just calls `start()` at
+ * boot and `stop()` at shutdown.
+ *
+ * `getEngine()` exposes the underlying `MonitorEngine` so `daemon.ts`'s
+ * SIGHUP handler can call `engine.reload()` when needed.
+ */
+import { BaseDaemonService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+import { MonitorEngine } from '../monitors/engine.js';
+export declare class MonitorEngineService extends BaseDaemonService {
+    readonly id: DaemonServiceId;
+    private engine;
+    /** Returns the live engine after `start()`, or `null` before/after. */
+    getEngine(): MonitorEngine | null;
+    protected onStart(ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+}

package/dist/lib/daemon/monitor-engine-service.js

@@ -0,0 +1,29 @@
+/**
+ * MonitorEngine lifecycle as a `DaemonService` (RUSH-3193 P2).
+ *
+ * Wraps the `MonitorEngine` (event-triggered watchers) under the
+ * `ServiceSupervisor` contract. This is a lifecycle-only service — the engine
+ * runs its own internal event loop; the supervisor just calls `start()` at
+ * boot and `stop()` at shutdown.
+ *
+ * `getEngine()` exposes the underlying `MonitorEngine` so `daemon.ts`'s
+ * SIGHUP handler can call `engine.reload()` when needed.
+ */
+import { BaseDaemonService } from './service.js';
+import { MonitorEngine } from '../monitors/engine.js';
+export class MonitorEngineService extends BaseDaemonService {
+    id = 'monitors';
+    engine = null;
+    /** Returns the live engine after `start()`, or `null` before/after. */
+    getEngine() {
+        return this.engine;
+    }
+    async onStart(ctx) {
+        this.engine = new MonitorEngine((level, message) => ctx.log(level, message));
+        this.engine.start();
+    }
+    async onStop() {
+        this.engine?.stop();
+        this.engine = null;
+    }
+}

package/dist/lib/daemon/secrets-broker-service.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Secrets-broker lifecycle as a `DaemonService` (RUSH-3193 P2).
+ *
+ * Wraps the daemon's secrets-broker hosting under the `ServiceSupervisor`
+ * contract so the supervisor owns start/stop and reports health through the
+ * uniform `daemon-health.ts` path. The broker self-heal (RUSH-1817) is
+ * encapsulated here: a background interval re-probes the socket and takes
+ * over hosting whenever the daemon is NOT already hosting AND no healthy
+ * standalone broker answers a ping.
+ */
+import { BaseDaemonService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class SecretsBrokerService extends BaseDaemonService {
+    readonly id: DaemonServiceId;
+    private hostedBroker;
+    private selfHealTimer;
+    private selfHealInFlight;
+    protected onStart(ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+}

package/dist/lib/daemon/secrets-broker-service.js

@@ -0,0 +1,66 @@
+/**
+ * Secrets-broker lifecycle as a `DaemonService` (RUSH-3193 P2).
+ *
+ * Wraps the daemon's secrets-broker hosting under the `ServiceSupervisor`
+ * contract so the supervisor owns start/stop and reports health through the
+ * uniform `daemon-health.ts` path. The broker self-heal (RUSH-1817) is
+ * encapsulated here: a background interval re-probes the socket and takes
+ * over hosting whenever the daemon is NOT already hosting AND no healthy
+ * standalone broker answers a ping.
+ */
+import { BaseDaemonService } from './service.js';
+/** Matches the constant previously in daemon.ts. */
+const BROKER_SELF_HEAL_TICK_MS = 60_000;
+/** Take over only when we are not already hosting AND no broker is reachable. */
+function shouldTakeOver(isHosting, brokerReachable) {
+    return !isHosting && !brokerReachable;
+}
+export class SecretsBrokerService extends BaseDaemonService {
+    id = 'secrets-broker';
+    hostedBroker = null;
+    selfHealTimer;
+    selfHealInFlight = false;
+    async onStart(ctx) {
+        const { agentPing, startHostedBroker } = await import('../secrets/agent.js');
+        if ((await agentPing()).reachable) {
+            ctx.log('INFO', 'Secrets broker already running (standalone); daemon not hosting it');
+        }
+        else {
+            this.hostedBroker = await startHostedBroker();
+            if (this.hostedBroker)
+                ctx.log('INFO', 'Secrets broker hosted in daemon (socket-first)');
+        }
+        // RUSH-1817: if the standalone the daemon deferred to at start later dies,
+        // take over hosting on the next self-heal probe.
+        const runSelfHeal = async () => {
+            if (this.selfHealInFlight)
+                return;
+            this.selfHealInFlight = true;
+            try {
+                const { agentPing: ping, startHostedBroker: startBroker } = await import('../secrets/agent.js');
+                const reachable = (await ping()).reachable;
+                if (!shouldTakeOver(this.hostedBroker != null, reachable))
+                    return;
+                this.hostedBroker = await startBroker();
+                if (this.hostedBroker) {
+                    ctx.log('WARN', 'Secrets broker was unreachable; daemon took over hosting (self-heal)');
+                }
+            }
+            catch (err) {
+                ctx.log('WARN', `Secrets broker self-heal skipped: ${err.message}`);
+            }
+            finally {
+                this.selfHealInFlight = false;
+            }
+        };
+        this.selfHealTimer = setInterval(() => { void runSelfHeal(); }, BROKER_SELF_HEAL_TICK_MS);
+    }
+    async onStop() {
+        if (this.selfHealTimer !== undefined) {
+            clearInterval(this.selfHealTimer);
+            this.selfHealTimer = undefined;
+        }
+        this.hostedBroker?.close();
+        this.hostedBroker = null;
+    }
+}

package/dist/lib/daemon/self-heal-service.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resource self-heal tick as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * Fills missing resources, repairs invalid manifests, and fast-forwards
+ * pristine stale plugins. Conservative 'safe' mode: never overwrites
+ * hand-edited content. Does not run when the daemon's state directory no
+ * longer exists — that is the state-dir self-check's signal to shut down;
+ * background maintenance must not recreate the tree while it is mid-exit.
+ *
+ * The pre-migration inline timer also delayed its first fire by
+ * `SELF_HEAL_KICKOFF_MS` (30s) so shims/PATH could settle shortly after daemon
+ * start, without making launch itself busy. `startupDelayMs` below reproduces
+ * that stagger through the supervisor's generic per-service contract
+ * (`service.ts`) — every other tick still fires on the normal `intervalMs`
+ * cadence; only self-heal's boot-time tick is deliberately staggered.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class SelfHealService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs: number;
+    readonly startupDelayMs = 30000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/self-heal-service.js

@@ -0,0 +1,48 @@
+/**
+ * Resource self-heal tick as a `PeriodicService` (RUSH-3193 P3).
+ *
+ * Fills missing resources, repairs invalid manifests, and fast-forwards
+ * pristine stale plugins. Conservative 'safe' mode: never overwrites
+ * hand-edited content. Does not run when the daemon's state directory no
+ * longer exists — that is the state-dir self-check's signal to shut down;
+ * background maintenance must not recreate the tree while it is mid-exit.
+ *
+ * The pre-migration inline timer also delayed its first fire by
+ * `SELF_HEAL_KICKOFF_MS` (30s) so shims/PATH could settle shortly after daemon
+ * start, without making launch itself busy. `startupDelayMs` below reproduces
+ * that stagger through the supervisor's generic per-service contract
+ * (`service.ts`) — every other tick still fires on the normal `intervalMs`
+ * cadence; only self-heal's boot-time tick is deliberately staggered.
+ */
+import { BasePeriodicService } from './service.js';
+import { getDaemonDir } from '../state.js';
+import * as fs from 'fs';
+/** Matches the historical inline interval (daemon.ts SELF_HEAL_TICK_MS). Runs ~every 6h. */
+const SELF_HEAL_TICK_MS = 6 * 60 * 60_000;
+/** Hard cap per tick — a full resource repair sweep across every version home, short enough a hang never freezes the service for long relative to its 6h cadence. */
+const SELF_HEAL_DEADLINE_MS = 10 * 60_000;
+/** Matches the historical inline kickoff delay (daemon.ts SELF_HEAL_KICKOFF_MS). Staggers self-heal's first tick after shims/PATH settle, so launch itself isn't made busy. */
+const SELF_HEAL_KICKOFF_MS = 30_000;
+export class SelfHealService extends BasePeriodicService {
+    id = 'self-heal';
+    intervalMs = SELF_HEAL_TICK_MS;
+    deadlineMs = SELF_HEAL_DEADLINE_MS;
+    startupDelayMs = SELF_HEAL_KICKOFF_MS;
+    async onStart(_ctx) {
+        // No connections/handles to open — each tick re-checks the state dir itself.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
+    }
+    async onTick(ctx) {
+        if (!fs.existsSync(getDaemonDir()))
+            return;
+        const { runSelfHeal, selfHealChangedAnything, selfHealNeedsAttention, summarizeSelfHeal } = await import('../self-heal/registry.js');
+        if (!fs.existsSync(getDaemonDir()))
+            return;
+        const report = await runSelfHeal({ mode: 'safe' });
+        if (selfHealChangedAnything(report) || selfHealNeedsAttention(report)) {
+            ctx.log('INFO', `self-heal: ${summarizeSelfHeal(report)}`);
+        }
+    }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * DaemonService contract (RUSH-3193 P1).
+ *
+ * Today the daemon's ~13 background services are bare `setInterval` closures
+ * inside one long `runDaemon()` (daemon.ts), sharing one event loop with no
+ * per-service error boundary or deadline. A throw escaping a tick's local
+ * try/catch hits the process-wide handler and kills every service; a tick that
+ * hangs on an unbounded await latches its in-flight guard `true` forever and
+ * silently freezes that service for the daemon's life.
+ *
+ * This module defines the service shape a `ServiceSupervisor` (supervisor.ts)
+ * drives instead: one contract per service, owned timer, per-tick deadline,
+ * and a health record the supervisor can report without the service having to
+ * know it is being supervised.
+ */
+import type { DaemonServiceId } from '../daemon-services.js';
+/** Lifecycle state a supervised service can be in. */
+export type ServiceState = 'idle' | 'running' | 'parked' | 'stopped';
+/** A service's most recently observed health, as reported by the supervisor. */
+export interface ServiceHealth {
+    state: ServiceState;
+    /** `Date.now()` of the last tick that completed without throwing or timing out. */
+    lastRunMs: number;
+    lastError?: string;
+    /** Consecutive failed/timed-out ticks since the last success. */
+    consecutiveFailures: number;
+}
+/** Shared context every service receives at start/tick time. */
+export interface DaemonContext {
+    log: (level: string, message: string) => void;
+}
+/** Base contract every supervised daemon service implements. */
+export interface DaemonService {
+    readonly id: DaemonServiceId;
+    start(ctx: DaemonContext): Promise<void>;
+    stop(): Promise<void>;
+    /** `stop()` then `start()` — used by the supervisor's circuit-breaker (and, in future, an on-demand `daemon services restart <id>` command — not wired up yet). */
+    restart(): Promise<void>;
+    health(): ServiceHealth;
+}
+/** A service the supervisor ticks on a fixed interval, under a hard per-tick deadline. */
+export interface PeriodicService extends DaemonService {
+    readonly intervalMs: number;
+    /** Hard cap per tick. An over-budget tick is abandoned (never awaited past this) so its in-flight guard always releases. */
+    readonly deadlineMs: number;
+    /**
+     * Delay before the FIRST tick after `start()`, in ms. Every later tick
+     * still fires on the normal `intervalMs` cadence — this only staggers the
+     * boot-time tick. Default (omitted) is 0, the supervisor's baseline
+     * immediate-first-tick behavior. Set this when a service's first-boot work
+     * needs something else (shims, PATH) to settle before it runs, rather than
+     * firing at daemon startup.
+     */
+    readonly startupDelayMs?: number;
+    tick(ctx: DaemonContext): Promise<void>;
+}
+export declare function isPeriodicService(service: DaemonService): service is PeriodicService;
+/**
+ * Convenience base for a lifecycle-only (non-periodic) daemon service.
+ *
+ * Concrete subclasses implement `onStart` and `onStop`; the base owns the
+ * `ServiceHealth` record and the `restart()` default (`stop` + `start`).
+ * Unlike `BasePeriodicService` there is no tick — the supervisor just calls
+ * `start()` once at boot, keeps the service marked `running`, and calls
+ * `stop()` at shutdown.
+ *
+ * `lastRunMs` is set to the time `start()` completed, so `supervisor.health()`
+ * carries a meaningful "last known healthy" timestamp even with no periodic ticks.
+ */
+export declare abstract class BaseDaemonService implements DaemonService {
+    abstract readonly id: DaemonServiceId;
+    protected ctx: DaemonContext | null;
+    private healthRecord;
+    protected abstract onStart(ctx: DaemonContext): Promise<void>;
+    protected abstract onStop(): Promise<void>;
+    start(ctx: DaemonContext): Promise<void>;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+    health(): ServiceHealth;
+}
+/**
+ * Convenience base for a periodic service: owns the `ServiceHealth` record so
+ * concrete services only implement the three lifecycle hooks. `restart()`
+ * defaults to `stop()` then `start()` against the last context passed to
+ * `start()`, which is what every current-generation service needs — a
+ * concrete service overrides it only if it must reuse state across a restart.
+ */
+export declare abstract class BasePeriodicService implements PeriodicService {
+    abstract readonly id: DaemonServiceId;
+    abstract readonly intervalMs: number;
+    abstract readonly deadlineMs: number;
+    protected ctx: DaemonContext | null;
+    private healthRecord;
+    protected abstract onStart(ctx: DaemonContext): Promise<void>;
+    protected abstract onStop(): Promise<void>;
+    protected abstract onTick(ctx: DaemonContext): Promise<void>;
+    start(ctx: DaemonContext): Promise<void>;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+    tick(ctx: DaemonContext): Promise<void>;
+    health(): ServiceHealth;
+}

package/dist/lib/daemon/service.js

@@ -0,0 +1,98 @@
+/**
+ * DaemonService contract (RUSH-3193 P1).
+ *
+ * Today the daemon's ~13 background services are bare `setInterval` closures
+ * inside one long `runDaemon()` (daemon.ts), sharing one event loop with no
+ * per-service error boundary or deadline. A throw escaping a tick's local
+ * try/catch hits the process-wide handler and kills every service; a tick that
+ * hangs on an unbounded await latches its in-flight guard `true` forever and
+ * silently freezes that service for the daemon's life.
+ *
+ * This module defines the service shape a `ServiceSupervisor` (supervisor.ts)
+ * drives instead: one contract per service, owned timer, per-tick deadline,
+ * and a health record the supervisor can report without the service having to
+ * know it is being supervised.
+ */
+export function isPeriodicService(service) {
+    const candidate = service;
+    return typeof candidate.tick === 'function' && typeof candidate.intervalMs === 'number' && typeof candidate.deadlineMs === 'number';
+}
+function blankHealth() {
+    return { state: 'idle', lastRunMs: 0, consecutiveFailures: 0 };
+}
+/**
+ * Convenience base for a lifecycle-only (non-periodic) daemon service.
+ *
+ * Concrete subclasses implement `onStart` and `onStop`; the base owns the
+ * `ServiceHealth` record and the `restart()` default (`stop` + `start`).
+ * Unlike `BasePeriodicService` there is no tick — the supervisor just calls
+ * `start()` once at boot, keeps the service marked `running`, and calls
+ * `stop()` at shutdown.
+ *
+ * `lastRunMs` is set to the time `start()` completed, so `supervisor.health()`
+ * carries a meaningful "last known healthy" timestamp even with no periodic ticks.
+ */
+export class BaseDaemonService {
+    ctx = null;
+    healthRecord = blankHealth();
+    async start(ctx) {
+        this.ctx = ctx;
+        await this.onStart(ctx);
+        this.healthRecord = { ...this.healthRecord, state: 'running', lastRunMs: Date.now() };
+    }
+    async stop() {
+        await this.onStop();
+        this.healthRecord = { ...this.healthRecord, state: 'stopped' };
+    }
+    async restart() {
+        const ctx = this.ctx;
+        if (!ctx)
+            throw new Error(`service '${this.id}' cannot restart before it has started once`);
+        await this.stop();
+        await this.start(ctx);
+    }
+    health() {
+        return { ...this.healthRecord };
+    }
+}
+/**
+ * Convenience base for a periodic service: owns the `ServiceHealth` record so
+ * concrete services only implement the three lifecycle hooks. `restart()`
+ * defaults to `stop()` then `start()` against the last context passed to
+ * `start()`, which is what every current-generation service needs — a
+ * concrete service overrides it only if it must reuse state across a restart.
+ */
+export class BasePeriodicService {
+    ctx = null;
+    healthRecord = blankHealth();
+    async start(ctx) {
+        this.ctx = ctx;
+        await this.onStart(ctx);
+        this.healthRecord = { ...this.healthRecord, state: 'running' };
+    }
+    async stop() {
+        await this.onStop();
+        this.healthRecord = { ...this.healthRecord, state: 'stopped' };
+    }
+    async restart() {
+        const ctx = this.ctx;
+        if (!ctx)
+            throw new Error(`service '${this.id}' cannot restart before it has started once`);
+        await this.stop();
+        await this.start(ctx);
+    }
+    async tick(ctx) {
+        try {
+            await this.onTick(ctx);
+            this.healthRecord = { ...this.healthRecord, lastRunMs: Date.now(), consecutiveFailures: 0, lastError: undefined };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.healthRecord = { ...this.healthRecord, lastError: message, consecutiveFailures: this.healthRecord.consecutiveFailures + 1 };
+            throw err;
+        }
+    }
+    health() {
+        return { ...this.healthRecord };
+    }
+}

package/dist/lib/daemon/session-index-service.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Session-index warm service (RUSH-2682), migrated onto `ServiceSupervisor`
+ * (RUSH-3193 P1) as the proof-of-concept periodic service.
+ *
+ * Incrementally scans this host's transcript dirs into the local index so a
+ * locally-started session is discoverable within seconds, not on the next
+ * unrelated `agents sessions*` call. Single-flight via the DB scan claim in
+ * `scanSessionsIncremental` — a concurrent foreground scan is a skip, not a
+ * failure. Previously a bare `setInterval` in `runDaemon()`
+ * (daemon.ts:1118-1137); the supervisor now owns its timer, error boundary,
+ * and deadline instead.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class SessionIndexService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs = 20000;
+    readonly deadlineMs = 60000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/session-index-service.js

@@ -0,0 +1,40 @@
+/**
+ * Session-index warm service (RUSH-2682), migrated onto `ServiceSupervisor`
+ * (RUSH-3193 P1) as the proof-of-concept periodic service.
+ *
+ * Incrementally scans this host's transcript dirs into the local index so a
+ * locally-started session is discoverable within seconds, not on the next
+ * unrelated `agents sessions*` call. Single-flight via the DB scan claim in
+ * `scanSessionsIncremental` — a concurrent foreground scan is a skip, not a
+ * failure. Previously a bare `setInterval` in `runDaemon()`
+ * (daemon.ts:1118-1137); the supervisor now owns its timer, error boundary,
+ * and deadline instead.
+ */
+import { BasePeriodicService } from './service.js';
+import { runSessionIndexWarmTick } from '../daemon-ticks.js';
+/** Matches the historical inline interval (daemon.ts SESSION_INDEX_WARM_TICK_MS). */
+const SESSION_INDEX_WARM_TICK_MS = 20_000;
+/** Hard cap per tick — well above a healthy incremental scan, short enough that a hang never freezes the service for long. */
+const SESSION_INDEX_WARM_DEADLINE_MS = 60_000;
+export class SessionIndexService extends BasePeriodicService {
+    id = 'session-index';
+    intervalMs = SESSION_INDEX_WARM_TICK_MS;
+    deadlineMs = SESSION_INDEX_WARM_DEADLINE_MS;
+    async onStart(_ctx) {
+        // No connections/handles to open — the scan claim itself is per-tick state.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
+    }
+    async onTick(ctx) {
+        const { indexed, claimed } = await runSessionIndexWarmTick();
+        // Log only when the tick did something. A silent tick is what let it
+        // report 0 forever unnoticed (RUSH-2691); a line on every idle 20s tick
+        // would drown the log, so the steady state (claimed, nothing changed)
+        // stays quiet and both interesting outcomes are visible.
+        if (!claimed)
+            ctx.log('INFO', 'session-index warm: skipped, another process holds the scan claim');
+        else if (indexed > 0)
+            ctx.log('INFO', `session-index warm: indexed ${indexed} transcript(s)`);
+    }
+}

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>;
+}