@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/daemon-ticks.js

@@ -1,123 +1,81 @@
 /**
- * Daemon housekeeping ticks — one-shot bodies invoked by system routines.
+ * Daemon account-state tick bodies.
  *
- * RUSH-2353: these were ~15 hardcoded `setInterval` timers inside
- * `runDaemon()` (daemon.ts) — a parallel, inferior reimplementation of the
- * routines system (no declaration, no run history, no pause/disable, no
- * device pin). Each function here is one migrated tick's *body*, unchanged in
- * behavior, now invoked as a detached one-shot process by a system routine's
- * `command:` (via the `agents __daemon-tick <name>` entrypoint in index.ts)
- * instead of an in-process interval closure.
+ * These two bodies are the `refreshUsage` / `refreshAuth` implementations the
+ * daemon's `account-state-service.ts` timers call directly, in-process, on a
+ * plain `setInterval` (usage every 60s, auth every ~3 min). They are NOT
+ * routines and are never fired through the scheduler — the daemon owns usage and
+ * authentication health as first-party device state (RUSH-2451).
  *
- * Overlap protection that used to live in daemon.ts as a per-tick boolean
- * flag (`watchdogInFlight`, `probingDevices`, ...) is now provided by the
- * routine runner's launch claim (`withRoutineLaunchClaim` in runner.ts) — two
- * fires of the same routine name never run concurrently.
- *
- * Output goes to `console.log`/`console.error`: each tick runs as a spawned
- * child of `executeCommandJobDetached`, which redirects the child's stdout to
- * the run's `stdout.log` — so this doubles as the run's log, readable via
- * `agents routines runs <name>`.
+ * `refreshLocalFleetAuthState` is also called by `agents fleet`/`ssh` surfaces
+ * that need a fresh local auth snapshot on demand; provider-level work is guarded
+ * by the cross-process refresh lease so an explicit CLI refresh and the daemon
+ * timer converge on the same published result.
  */
-import { getConfigValue } from './device-config.js';
-/** ~every 3 min. Mirrors the old WATCHDOG_TICK_MS. */
-export async function runWatchdogTick() {
-    if (getConfigValue('watchdog.enabled').value !== true) {
-        console.log('watchdog: disabled (watchdog.enabled != true) — skipping');
-        return;
-    }
-    const { runWatchdogPass } = await import('./watchdog/service.js');
-    const result = await runWatchdogPass({ nudge: true });
-    console.log(`watchdog: ${result.counts.total} live, ${result.counts.stalled} stalled, ${result.counts.nudged} nudged`);
-}
-/**
- * Device probe: refresh registered devices' reachability and detect 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. ~every 3 min.
- */
-export async function runDeviceProbeTick() {
-    const { runDeviceSync } = await import('./devices/sync.js');
-    const { reconcilePendingSentinels } = await import('./devices/pending.js');
-    const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
-    if (!dev.ok) {
-        console.log('device probe: sync not ok — skipping sentinel reconcile');
-        return;
-    }
-    reconcilePendingSentinels(dev.pending);
-    if (dev.pending.length) {
-        console.log(`devices: ${dev.pending.length} new pending (${dev.pending.map((p) => p.name).join(', ')})`);
-    }
-    else {
-        console.log('device probe: no new pending devices');
-    }
-}
-/**
- * tmux hook reconcile: retrofit the guarded `pane-died` hook onto managed
- * `agents run` sessions a pre-fix binary left with the old unconditional
- * hook. Non-destructive: set-hook only, never a kill or detach. ~every 5 min.
- */
-export async function runTmuxReconcileTick() {
-    const { isTmuxInstalled } = await import('./tmux/binary.js');
-    if (!isTmuxInstalled()) {
-        console.log('tmux reconcile: tmux not installed — skipping');
-        return;
-    }
-    const { reconcileSessionHooks } = await import('./tmux/session.js');
-    const r = await reconcileSessionHooks();
-    console.log(`tmux: retrofitted pane-died hook on ${r.reconciled} session(s)`);
-}
-/**
- * Launch-health self-heal: probe that each agent's DEFAULT version actually
- * LAUNCHES, and repair a gutted install. Never repoints the global default
- * (allowDefaultSwitch: false) — a background default switch would be a
- * silent logout. ~every 6h.
- */
-export async function runLaunchHealthTick() {
-    const { healBrokenDefaultLaunches } = await import('./versions.js');
-    const { repaired, unhealed } = await healBrokenDefaultLaunches((m) => console.log(`launch-health: ${m}`), { allowDefaultSwitch: false });
-    if (repaired.length)
-        console.log(`launch-health: repaired ${repaired.join(', ')}`);
-    if (unhealed.length) {
-        console.log(`launch-health: ${unhealed.join(', ')} won't launch and will not be auto-switched — choose a version with \`agents use <agent> <version>\` or \`agents add <agent>@latest\``);
-    }
-    if (!repaired.length && !unhealed.length)
-        console.log('launch-health: all default launches healthy');
+export function isFreshFleetAuthSnapshot(value, minimumCapturedAt) {
+    return value.row.capturedAt >= minimumCapturedAt
+        && value.authRows.length > 0
+        && value.authRows.every(authRow => authRow.health.checkedAt >= minimumCapturedAt);
 }
 /**
  * Fleet cache warm: publish THIS host's row for the caches `agents fleet
  * status` / `agents devices list` read (PUBLISH-OWN / READ-UNION, RUSH-2061).
- * ~every 3 min.
  */
-export async function runFleetCacheWarmTick() {
+export async function refreshLocalFleetAuthState() {
     const { machineId } = await import('./machine-id.js');
-    const self = machineId();
-    const { probeLocalFleetAuth, writeFleetAuthRows } = await import('./auth-health.js');
+    const { probeLocalFleetAuth, readFleetAuthRows, writeFleetAuthRows } = await import('./auth-health.js');
     const { getCliVersion } = await import('./version.js');
-    const authRows = await probeLocalFleetAuth({ cliVersion: getCliVersion() });
-    writeFleetAuthRows(self, authRows);
-    const { publishLocalFleetStatus } = await import('./fleet-status.js');
-    const row = await publishLocalFleetStatus(self);
-    console.log(`fleet cache warm: ${authRows.length} auth row(s), ${row.agents.running} running agent(s) on ${self}`);
+    const self = machineId();
+    const requestedAt = Date.now();
+    const minimumCapturedAt = requestedAt - 2 * 60_000;
+    const { withRefreshLease } = await import('./refresh-coordinator.js');
+    const { readFleetStatus, publishLocalFleetStatus } = await import('./fleet-status.js');
+    return withRefreshLease({
+        scope: 'auth',
+        key: self,
+        readCompleted: () => {
+            const row = readFleetStatus()[self];
+            if (!row)
+                return null;
+            return { row, authRows: readFleetAuthRows(self) };
+        },
+        // A recent daemon publication is the completed result, not a reason to probe
+        // every provider a second time.
+        isCompleted: (value) => isFreshFleetAuthSnapshot(value, minimumCapturedAt),
+        refresh: async () => {
+            const authRows = await probeLocalFleetAuth({ cliVersion: getCliVersion() });
+            writeFleetAuthRows(self, authRows);
+            const row = await publishLocalFleetStatus(self);
+            return { row, authRows };
+        },
+    });
 }
-/**
- * Session-status cache warm (RUSH-2062): publish THIS host's local active
- * sessions so menubar / Factory / watchdog / CLI share one warm snapshot.
- * Publish-own only (no cross-host SSH). ~every 3 min.
- */
-export async function runSessionCacheWarmTick() {
-    const { publishLocalActiveSessions } = await import('./session/session-cache.js');
-    const r = await publishLocalActiveSessions();
-    console.log(`session cache warm: ${r.sessions.length} local session(s)`);
+export async function runFleetCacheWarmTick() {
+    const result = await refreshLocalFleetAuthState();
+    // A waiter receives the already-published fleet row. The auth-row count is
+    // available only to the process that performed the provider probes.
+    const row = result.row;
+    const authCount = result.authRows.length;
+    console.log(`fleet cache warm: ${authCount} auth row(s) refreshed, ${row.agents.running} running agent(s) on ${row.host}`);
 }
 /**
  * Usage refresh: keep the usage cache the `agents run` router reads
  * (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
- * This host is the sole writer for its own local accounts. ~every 60s
- * (USAGE_REFRESH_TICK_MS in usage-refresh.ts — keep in sync).
+ * The configured primary host is the fleet's sole provider-facing writer;
+ * subscribers import its token-free derived cache.
  */
 export async function runUsageRefreshTick() {
+    const { resolveUsagePrimaryHost } = await import('./device-config.js');
+    const { machineId } = await import('./machine-id.js');
+    // usage.primary-host, else interactive.host, else null (standalone local refresh)
+    const primaryHost = resolveUsagePrimaryHost() ?? undefined;
+    const self = machineId();
+    const { importUsageFleetFromHost, usageRefreshRole } = await import('./usage-fleet.js');
+    if (usageRefreshRole(primaryHost, self) === 'subscriber') {
+        const imported = await importUsageFleetFromHost(primaryHost);
+        console.log(`usage refresh: imported ${Object.keys(imported.usage).length} account(s) from primary host ${primaryHost}`);
+        return;
+    }
     const { runUsageRefresh, buildLocalUsageAccounts } = await import('./usage-refresh.js');
     const { writeClaudeUsageCache } = await import('./usage.js');
     const { usageRateLimitedUntil } = await import('./usage-backoff.js');
@@ -126,65 +84,25 @@ export async function runUsageRefreshTick() {
         writeUsageCache: writeClaudeUsageCache,
         backoffUntil: usageRateLimitedUntil,
     });
-    console.log(`usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped`);
+    const { listProfiles } = await import('./profiles.js');
+    const { refreshDueByokUsage } = await import('./byok-usage.js');
+    const byok = await refreshDueByokUsage(listProfiles());
+    const { exportUsageFleet } = await import('./usage-fleet.js');
+    const published = exportUsageFleet();
+    console.log(`usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped; BYOK ${byok.refreshed} refreshed, ${byok.skipped} not-due; published ${Object.keys(published.usage).length} account(s)`);
 }
 /**
- * Auto-dispatch: for any managed project that has opted in (autoDispatch:true
- * + maxAgents>0 in ~/.agents/factory/projects.json), pick up Linear tickets
- * delegated to an agent and still in Todo, and dispatch each through
- * agents-cli's own cloud-provider layer. OFF unless a project opts in; no
- * opted-in project or no LINEAR_API_KEY is a clean no-op. ~every 3 min.
+ * Active-sessions warm (RUSH-2062 / RUSH-2484): publish THIS host's live session
+ * rows so `agents sessions watch` (and the extension that tails it) receive
+ * journal deltas. Publish-own only — no cross-host SSH.
  *
- * Migrated to a routine (RUSH-2353) so it inherits the `devices:` allowlist —
- * pin with `agents routines devices auto-dispatch --set <one>` to fix the
- * shared-input double-fire problem this job had hardcoded (every daemon on
- * the fleet polled the same Linear queue with no coordination).
+ * Cadence matches {@link DEFAULT_ACTIVE_CACHE_MAX_AGE_MS} so one-shot readers and
+ * long-lived watchers share one writer. Without this tick the journal has no
+ * continuous producer and Factory freezes after the initial cache snapshot.
  */
-export async function runAutoDispatchTick() {
-    const { readAutoDispatchProjects, isEligible, autoDispatchTick } = await import('./auto-dispatch.js');
-    const projects = readAutoDispatchProjects();
-    if (!projects.some(isEligible)) {
-        console.log('auto-dispatch: no opted-in project — skipping');
-        return;
-    }
-    const { createLinearGateway } = await import('./auto-dispatch-linear.js');
-    const linear = createLinearGateway();
-    if (!linear) {
-        console.log('auto-dispatch: no LINEAR_API_KEY configured — skipping');
-        return;
-    }
-    const { createProviderDispatcher } = await import('./auto-dispatch-provider.js');
-    const dispatcher = createProviderDispatcher();
-    const dispatched = await autoDispatchTick({
-        projects,
-        linear,
-        dispatcher,
-        log: (lvl, m) => (lvl === 'ERROR' ? console.error(m) : console.log(m)),
-    });
-    if (dispatched.length) {
-        console.log(`auto-dispatch: started ${dispatched.length} delegated ticket(s): ${dispatched.map((d) => d.identifier).join(', ')}`);
-    }
-    else {
-        console.log('auto-dispatch: no delegated tickets to dispatch');
-    }
-}
-/** Registry: routine-facing name -> tick body. Keys match the shipped routine YAML names. */
-export const DAEMON_TICKS = {
-    watchdog: runWatchdogTick,
-    'device-probe': runDeviceProbeTick,
-    'tmux-reconcile': runTmuxReconcileTick,
-    'launch-health': runLaunchHealthTick,
-    'fleet-cache-warm': runFleetCacheWarmTick,
-    'session-cache-warm': runSessionCacheWarmTick,
-    'usage-refresh': runUsageRefreshTick,
-    'auto-dispatch': runAutoDispatchTick,
-};
-export const DAEMON_TICK_ROUTINE_NAMES = Object.freeze(Object.keys(DAEMON_TICKS));
-/** Run one named tick, or throw for an unknown name (fails the routine run loud). */
-export async function runDaemonTick(name) {
-    const fn = DAEMON_TICKS[name];
-    if (!fn) {
-        throw new Error(`Unknown daemon tick '${name}'. Known: ${Object.keys(DAEMON_TICKS).join(', ')}`);
-    }
-    await fn();
+export async function runActiveSessionsWarmTick(opts = {}) {
+    const { publishLocalActiveSessions } = await import('./session/session-cache.js');
+    const r = await publishLocalActiveSessions({ gather: opts.gather });
+    console.log(`active-sessions warm: ${r.sessions.length} session(s) published`);
+    return { sessions: r.sessions.length };
 }

package/dist/lib/daemon.d.ts

@@ -7,6 +7,13 @@
  * log output, reload (SIGHUP), and graceful shutdown are handled here.
  */
 import { getAgentsBinPath } from './cli-entry.js';
+/**
+ * How many consecutive failed daemon starts disable the *implicit* auto-start
+ * (`ensureDaemonStarted`). Matches `DAEMON_START_LIMIT_BURST` so the two layers
+ * give up together rather than one silently masking the other. `agents daemon
+ * start` is the deliberate override and is never gated by this.
+ */
+export declare const DAEMON_AUTOSTART_FAILURE_LIMIT = 5;
 /**
  * RUSH-1817: decide whether the daemon should (re)take over hosting the secrets
  * broker. The startup host decision is one-shot; this drives the periodic
@@ -29,6 +36,35 @@ export declare function shouldTakeOverBroker(isHosting: boolean, brokerReachable
  */
 export type SchedulerGateTransition = 'reload' | 'stop' | 'boot' | 'none';
 export declare function schedulerGateTransition(running: boolean, enabled: boolean): SchedulerGateTransition;
+/**
+ * Wrap an async routine so it runs AT MOST ONCE, however many callers fire it.
+ *
+ * Extracted rather than left as a `let shuttingDown = false` inside runDaemon so
+ * the property can actually be tested (RUSH-2423). The daemon's shutdown is
+ * reachable from SIGTERM, SIGINT, and the state-dir self-check, but a real
+ * shutdown completes in ~26ms, so the re-entrant window is not reachable from
+ * outside the process — an end-to-end "send three signals" test passes with the
+ * guard removed and proves nothing. The mechanism is what is testable, so the
+ * mechanism is what is separated out.
+ *
+ * The flag is set synchronously before the first `await`, which is what makes
+ * this safe: two callers in the same tick cannot both get past it.
+ *
+ * A rejected `fn` leaves the guard SET — one attempt is all there is, and the
+ * rejection propagates to the caller that made it. That is right for shutdown
+ * (a failed shutdown must not be silently retried by the next signal) but is
+ * the thing to re-examine before giving this a second consumer.
+ */
+export declare function singleShot(fn: () => Promise<void>): () => Promise<void>;
+/**
+ * Absolute path to the daemon's structured log.
+ *
+ * Exported because two commands rebuilt the same path from a hardcoded
+ * `'logs.jsonl'` literal (`commands/daemon.ts`, `commands/routines.ts`), so
+ * renaming the file would have silently pointed them at nothing (RUSH-2423).
+ * One definition, three callers.
+ */
+export declare function getDaemonLogPath(): string;
 /** Read the stored daemon PID from disk. Returns null if not present or invalid. */
 export declare function readDaemonPid(): number | null;
 /** Write the daemon PID to the pid file. */
@@ -74,15 +110,15 @@ export declare function claimDaemonInstance(): boolean;
  * Record this daemon in the device's instance registry — a marker file named by
  * pid under `<daemonDir>/instances/`. The registry, not a process scan, is how
  * the reaper enumerates the device singleton: because the dir lives INSIDE the
- * daemon dir (`AGENTS_DAEMON_DIR` ?? `<HOME>/.agents/.cache/helpers/daemon`), every
+ * state dir (`AGENTS_DAEMON_DIR` ?? `<HOME>/.agents/.cache/helpers/daemon`), every
  * daemon of one device — however it was launched — registers in the same place,
  * while a genuinely separate install/home or a test fixture registers under its
- * own daemon dir and is invisible here. This is what fixes the two-entry pile-up:
+ * own state dir and is invisible here. This is what fixes the two-entry pile-up:
  * the compiled `dist/bin/agents` binary and the `node <shim>` JS entry have
  * different `process.argv[1]`, so the old launch-entry-scoped `ps` match never
  * reaped across them and duplicates accumulated (78 observed on one box), every
  * routine double-firing. Best-effort — the reaper self-heals a missing/stale
- * marker, and reading another process's ENV to key on the daemon dir directly is
+ * marker, and reading another process's ENV to key on the state dir directly is
  * not portable (hardened macOS hides it from `ps`), so identity rides the shared
  * on-disk registry instead. No-op on Windows (POSIX-only reaper).
  */
@@ -175,6 +211,14 @@ export declare function startDaemon(agentsBin?: string): {
     pid: number | null;
     method: string;
 };
+/**
+ * Is the auto-start circuit breaker open (RUSH-2418)? True once
+ * {@link DAEMON_AUTOSTART_FAILURE_LIMIT} consecutive starts have failed to
+ * produce a daemon that reported healthy. Pure read of the persisted health
+ * record, and `agents daemon doctor` reports the same record — the message the
+ * breaker prints has to lead somewhere that can explain it.
+ */
+export declare function isDaemonAutostartCircuitOpen(): boolean;
 /**
  * Bring the always-on daemon up as a side effect of a background-adjacent
  * command (secrets unlock, browser start, ...), not only from `routines add`.
@@ -256,6 +300,30 @@ export declare function startDetached(opts?: StartDetachedOptions): {
     pid: number | null;
     method: string;
 };
+/**
+ * One piece of daemon state that a graceful `handleShutdown` removes and an
+ * escalated kill leaves behind (RUSH-2421).
+ */
+export interface StopResidueArtifact {
+    label: string;
+    present: boolean;
+    /** The file names a pid that is alive and is NOT the daemon we stopped. */
+    ownedByLiveOther: boolean;
+    reclaim: () => void;
+    stillPresent: () => boolean;
+}
+/**
+ * The lifetime marker, heartbeat, and instance-registry entry, described so
+ * {@link stopDaemon} can assert them the same way it asserts the two sockets.
+ *
+ * Ownership, not mere presence, decides: a file naming a pid that is alive and
+ * is not the daemon we just stopped belongs to a DIFFERENT daemon (a successor
+ * that started during the stop, or a peer serving this state dir), and deleting
+ * it would break that live daemon — the same reasoning the broker-socket branch
+ * above uses for a standalone owner. Everything else is residue from a provably
+ * dead owner and is reclaimed.
+ */
+export declare function stopResidueArtifacts(stoppedPid: number | null, survivors?: number[]): StopResidueArtifact[];
 /**
  * Structured outcome of {@link stopDaemon} (SING-12, RUSH-2355). `stopDaemon`
  * asserts its postcondition instead of assuming it: `ok` is true only when every
@@ -276,7 +344,7 @@ export interface DaemonStopResult {
 /**
  * Live `__daemon-run` processes still registered in THIS state dir's instance
  * registry, excluding `exclude`. State-dir-scoped by construction: the registry
- * lives inside this daemon dir, so a daemon serving a DIFFERENT state dir (a test
+ * lives inside this state dir, so a daemon serving a DIFFERENT state dir (a test
  * fixture with its own HOME, a separate install/home) registers elsewhere and is
  * invisible here — it is never a stop/takeover target. POSIX-only (the registry
  * and its `ps` liveness probe are); `[]` on Windows.