@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/tmux/session.d.ts

@@ -77,13 +77,66 @@ export declare function hasSession(name: string, socket?: string): Promise<boole
  * `replace` or `attachExisting` is set.
  */
 export declare function createSession(opts: CreateSessionOptions): Promise<SessionMeta>;
-/** Kill one named session. Idempotent — killing a non-existent session is a no-op. */
-export declare function killSession(name: string, socket?: string): Promise<boolean>;
+/**
+ * Kill one named session. Idempotent — killing a non-existent session is a no-op.
+ *
+ * Destroying the tmux session only SIGHUPs each pane's FOREGROUND process group,
+ * so a helper the agent put in its own process group (an MCP server, a harness
+ * background daemon) survives and reparents to init. `reapOrphans` therefore
+ * defaults ON: the session's leftover helpers are terminated with it rather than
+ * waiting for the daemon's next sweep (RUSH-2521). {@link reapDeadTmuxPanes}
+ * passes `false` because it sweeps every session's leftovers in one pass instead
+ * of re-snapshotting the process table per session.
+ */
+export declare function killSession(name: string, socket?: string, opts?: {
+    reapOrphans?: boolean;
+}): Promise<boolean>;
 /**
  * Kill every session on the shared server AND the server itself, then prune
  * meta files. Wipes the socket so the next `new` starts from a clean slate.
  */
 export declare function killAll(socket?: string): Promise<number>;
+/** Result returned by {@link reapDeadTmuxPanes}. */
+export interface ReapDeadPanesResult {
+    /** Number of tmux sessions killed. */
+    reaped: number;
+    /** Names of reaped sessions. */
+    sessions: string[];
+    /** Human-readable lines describing each reap, for log output. */
+    details: string[];
+    /** Orphaned helper processes terminated (MCP servers, harness background daemons). */
+    processes: number;
+    /** One human-readable line per terminated helper process. */
+    processDetails: string[];
+    /** Non-fatal observations worth logging — e.g. a tier-1 sweep skipped this tick because a tmux query failed. */
+    warnings: string[];
+}
+/**
+ * Kill every tmux session whose panes are ALL dead (`pane_dead=1`), and
+ * terminate the helper processes whose owning agent has exited.
+ *
+ * Dead panes accumulate because `remain-on-exit on` is intentionally set
+ * per-pane so the harness can inspect exit status. Without a periodic sweep
+ * they pile up indefinitely — e.g. 48 of 127 sessions dead on yosemite-s0
+ * (RUSH-2501).
+ *
+ * Killing the pane is not enough on its own: it SIGHUPs only the pane's
+ * FOREGROUND process group, so an MCP server or harness background daemon that
+ * moved itself out of that group survives the session that spawned it and keeps
+ * its memory forever (RUSH-2521). The process sweep runs FIRST, while the dead
+ * sessions still exist, so every leftover is attributed to a named session
+ * rather than to a session tmux has already forgotten.
+ *
+ * Safety invariant: a session with ANY live pane (`pane_dead=0`) is never
+ * touched, and neither are the processes belonging to a session whose agent is
+ * still running or that has a client attached.
+ *
+ * `dryRun` reports both halves without killing anything.
+ */
+export declare function reapDeadTmuxPanes(socket?: string, opts?: {
+    dryRun?: boolean;
+    pids?: number[];
+}): Promise<ReapDeadPanesResult>;
 /**
  * Map every pane id (`%N`) on a socket to its `session:window.pane` attach
  * target, in one batched `tmux list-panes -a` call. `%116 -> main:2.0` is a
@@ -179,6 +232,18 @@ export declare const AGENT_HOOK_SCHEMA = 5;
 export declare function agentPaneDiedHook(sessionName: string, agentPane: string): string;
 /** Stamp a session's hook-schema marker to the current version. */
 export declare function markSessionHookSchema(name: string, socket?: string): Promise<void>;
+/**
+ * The outcome of {@link prepareSessionForResume}. `attach` carries the pane it
+ * positively resolved so the caller can read that pane's exit status back after
+ * its attach client returns — without that, a resume-attach has no handle to ask
+ * tmux what happened and can only assume success (EXEC-23b).
+ */
+export type ResumePreparation = {
+    decision: 'attach';
+    pane: string;
+} | {
+    decision: 'create';
+};
 /**
  * Decide whether a native resume may attach an existing managed tmux session.
  * Only a positively resolved, living agent pane is reusable. Metadata-less
@@ -186,7 +251,7 @@ export declare function markSessionHookSchema(name: string, socket?: string): Pr
  * tmux before the decision; a dead or unreadable session is reaped so the
  * caller can create a fresh wrapper for the resumed harness.
  */
-export declare function prepareSessionForResume(name: string, socket?: string): Promise<'attach' | 'create'>;
+export declare function prepareSessionForResume(name: string, socket?: string): Promise<ResumePreparation>;
 /**
  * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
  * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:

package/dist/lib/tmux/session.js

@@ -117,8 +117,18 @@ export async function createSession(opts) {
     writeSessionMeta(meta);
     return meta;
 }
-/** Kill one named session. Idempotent — killing a non-existent session is a no-op. */
-export async function killSession(name, socket) {
+/**
+ * Kill one named session. Idempotent — killing a non-existent session is a no-op.
+ *
+ * Destroying the tmux session only SIGHUPs each pane's FOREGROUND process group,
+ * so a helper the agent put in its own process group (an MCP server, a harness
+ * background daemon) survives and reparents to init. `reapOrphans` therefore
+ * defaults ON: the session's leftover helpers are terminated with it rather than
+ * waiting for the daemon's next sweep (RUSH-2521). {@link reapDeadTmuxPanes}
+ * passes `false` because it sweeps every session's leftovers in one pass instead
+ * of re-snapshotting the process table per session.
+ */
+export async function killSession(name, socket, opts = {}) {
     assertValidSessionName(name);
     const sock = socket ?? getDefaultSocketPath();
     const existed = await hasSession(name, sock);
@@ -137,6 +147,10 @@ export async function killSession(name, socket) {
             throw err;
         }
     }
+    if (opts.reapOrphans !== false) {
+        const { reapProcessesForTmuxSession } = await import('./orphan-reap.js');
+        await reapProcessesForTmuxSession(name, sock).catch(() => ({ killed: 0, details: [], candidates: [], warnings: [] }));
+    }
     removeSessionMeta(name);
     return true;
 }
@@ -172,6 +186,83 @@ export async function killAll(socket) {
     catch { /* may not exist */ }
     return count;
 }
+/**
+ * Kill every tmux session whose panes are ALL dead (`pane_dead=1`), and
+ * terminate the helper processes whose owning agent has exited.
+ *
+ * Dead panes accumulate because `remain-on-exit on` is intentionally set
+ * per-pane so the harness can inspect exit status. Without a periodic sweep
+ * they pile up indefinitely — e.g. 48 of 127 sessions dead on yosemite-s0
+ * (RUSH-2501).
+ *
+ * Killing the pane is not enough on its own: it SIGHUPs only the pane's
+ * FOREGROUND process group, so an MCP server or harness background daemon that
+ * moved itself out of that group survives the session that spawned it and keeps
+ * its memory forever (RUSH-2521). The process sweep runs FIRST, while the dead
+ * sessions still exist, so every leftover is attributed to a named session
+ * rather than to a session tmux has already forgotten.
+ *
+ * Safety invariant: a session with ANY live pane (`pane_dead=0`) is never
+ * touched, and neither are the processes belonging to a session whose agent is
+ * still running or that has a client attached.
+ *
+ * `dryRun` reports both halves without killing anything.
+ */
+export async function reapDeadTmuxPanes(socket, opts = {}) {
+    const sock = socket ?? getDefaultSocketPath();
+    const result = { reaped: 0, sessions: [], details: [], processes: 0, processDetails: [], warnings: [] };
+    // The process sweep may run with no server, but an absent session is not
+    // evidence that a still-live marked process is orphaned. Tier 1 only acts on
+    // a present pane owner confirmed dead; tier 2 independently verifies its
+    // declared spawner pid (RUSH-2603).
+    // `opts.pids` is a test-only process-table scope (see `readAgentProcesses`)
+    // — production callers never set it.
+    const { reapOrphanAgentProcesses } = await import('./orphan-reap.js');
+    const orphans = await reapOrphanAgentProcesses({ socket: sock, dryRun: opts.dryRun, pids: opts.pids });
+    result.warnings = orphans.warnings;
+    result.processes = opts.dryRun ? orphans.candidates.length : orphans.killed;
+    result.processDetails = orphans.details;
+    if (!fs.existsSync(sock))
+        return result;
+    const res = await runTmux({
+        socket: sock,
+        args: ['list-panes', '-a', '-F', '#{pane_id}\t#{session_name}\t#{pane_dead}'],
+        throwOnError: false,
+    });
+    // Nonzero exit means no server or no sessions — nothing to reap.
+    if (res.code !== 0)
+        return result;
+    // Group dead-flags by session name.
+    const sessionFlags = new Map();
+    for (const raw of res.stdout.split('\n')) {
+        const parts = raw.trim().split('\t');
+        const name = parts[1];
+        if (!name)
+            continue;
+        const dead = parts[2]?.trim() === '1';
+        if (!sessionFlags.has(name))
+            sessionFlags.set(name, []);
+        sessionFlags.get(name).push(dead);
+    }
+    // Kill only sessions where every pane is dead.
+    for (const [name, flags] of sessionFlags) {
+        if (flags.length === 0 || !flags.every(d => d))
+            continue;
+        try {
+            // The one process-table sweep above already collected this session's
+            // leftovers; a per-session reap here would re-snapshot `ps` N times.
+            if (!opts.dryRun)
+                await killSession(name, sock, { reapOrphans: false });
+            result.reaped++;
+            result.sessions.push(name);
+            result.details.push(`${name} (${flags.length} dead pane${flags.length === 1 ? '' : 's'})`);
+        }
+        catch {
+            // Best-effort: session may already be gone by the time we hit it.
+        }
+    }
+    return result;
+}
 /**
  * Map every pane id (`%N`) on a socket to its `session:window.pane` attach
  * target, in one batched `tmux list-panes -a` call. `%116 -> main:2.0` is a
@@ -369,7 +460,7 @@ async function lowestPaneId(name, socket) {
 export async function prepareSessionForResume(name, socket) {
     const sock = socket ?? getDefaultSocketPath();
     if (!(await hasSession(name, sock)))
-        return 'create';
+        return { decision: 'create' };
     const recordedPane = readSessionMeta(name)?.pane;
     const recordedState = recordedPane ? await paneExitStatus(recordedPane, sock) : undefined;
     const pane = recordedPane && recordedState?.found
@@ -377,9 +468,9 @@ export async function prepareSessionForResume(name, socket) {
         : await lowestPaneId(name, sock);
     const state = pane ? await paneExitStatus(pane, sock) : undefined;
     if (pane && state?.found && !state.dead)
-        return 'attach';
+        return { decision: 'attach', pane };
     await killSession(name, sock);
-    return 'create';
+    return { decision: 'create' };
 }
 /**
  * Retrofit the current guarded `pane-died` hook onto every managed `agents run`

package/dist/lib/triggers/handlers.d.ts

@@ -28,6 +28,26 @@ export interface WebhookHandler {
      * to one platform. Omitted runs locally.
      */
     host?: string;
+    /**
+     * Named project (`agents projects`) whose base directory the dispatched
+     * agent/workflow run lands in — the execution anchor, mirroring a routine's
+     * `project`. Without it an agent handler runs at the target's `$HOME` with no
+     * repo checkout to edit. Applies to `run.agent`/`run.workflow` and the
+     * `routine:` delegate; ignored by `run.command` (put a `cd` in the command).
+     */
+    project?: string;
+    /**
+     * Portable execution directory for the dispatched run. A relative value
+     * resolves under `project` when set, otherwise the target's `$HOME`. Mirrors
+     * a routine's `cwd`.
+     */
+    cwd?: string;
+    /**
+     * Permission mode for a dispatched agent/workflow run. Defaults to `auto`
+     * (write with the classifier). Set `skip`/`full` for fully unattended edits,
+     * or `plan` for a read-only run.
+     */
+    mode?: JobConfig['mode'];
     run?: {
         agent?: AgentId;
         workflow?: string;

package/dist/lib/triggers/handlers.js

@@ -226,6 +226,16 @@ export function handlerMatchesWebhook(handler, webhook) {
             const current = data?.state?.name;
             if (current !== handler.stateTo)
                 return false;
+            // RUSH-2539: `stateTo` is a TRANSITION predicate, not a current-state one.
+            // Linear carries the prior value of each changed field in `updatedFrom`, so a
+            // real state change has `updatedFrom.state` (this codebase's shape) or
+            // `updatedFrom.stateId` (Linear's scalar). With neither, this Issue/update
+            // touched something else (label, assignee, description) while the issue merely
+            // still sits in `stateTo` — matching there re-fires on every later edit
+            // (RUSH-1459 accumulated 11 duplicate plan comments).
+            const updatedTo = webhook.payload.updatedFrom;
+            if (!updatedTo || (updatedTo.state === undefined && updatedTo.stateId === undefined))
+                return false;
         }
         if (handler.stateFrom) {
             const updatedFrom = webhook.payload.updatedFrom;
@@ -341,7 +351,7 @@ async function executeHandlerAction(handler, webhook, context, opts) {
     if (handler.run?.agent || handler.run?.workflow) {
         const config = {
             name: handler.name,
-            mode: 'auto',
+            mode: handler.mode ?? 'auto',
             effort: 'auto',
             timeout: '10m',
             enabled: true,
@@ -349,6 +359,8 @@ async function executeHandlerAction(handler, webhook, context, opts) {
             ...(handler.run.agent ? { agent: handler.run.agent } : { workflow: handler.run.workflow }),
             ...(handler.devices ? { devices: handler.devices } : {}),
             ...(handler.run.env ? { env: handler.run.env } : {}),
+            ...(handler.project ? { project: handler.project } : {}),
+            ...(handler.cwd ? { cwd: handler.cwd } : {}),
             ...(hostFields.host ? { host: hostFields.host } : {}),
             ...(hostFields.hostStrategy ? { hostStrategy: hostFields.hostStrategy } : {}),
         };
@@ -373,6 +385,9 @@ async function executeHandlerAction(handler, webhook, context, opts) {
             ...routine,
             prompt: substituteWebhookPrompt(routine.prompt, context),
             ...(handler.devices ? { devices: handler.devices } : {}),
+            ...(handler.project ? { project: handler.project } : {}),
+            ...(handler.cwd ? { cwd: handler.cwd } : {}),
+            ...(handler.mode ? { mode: handler.mode } : {}),
             ...(hostFields.host ? { host: hostFields.host } : {}),
             ...(hostFields.hostStrategy ? { hostStrategy: hostFields.hostStrategy } : {}),
         };

package/dist/lib/triggers/webhook.js

@@ -155,6 +155,16 @@ function linearTriggerMatches(trigger, webhook) {
         const current = data?.state?.name;
         if (current !== trigger.stateTo)
             return false;
+        // RUSH-2539: `stateTo` is a TRANSITION predicate, not a current-state one.
+        // Linear carries the prior value of each changed field in `updatedFrom`, so a
+        // real state change has `updatedFrom.state` (this codebase's shape) or
+        // `updatedFrom.stateId` (Linear's scalar). With neither, this Issue/update
+        // touched something else while the issue merely still sits in `stateTo` —
+        // matching there re-fires on every later edit (RUSH-1459 got 11 duplicate
+        // plan comments).
+        const updatedTo = webhook.payload.updatedFrom;
+        if (!updatedTo || (updatedTo.state === undefined && updatedTo.stateId === undefined))
+            return false;
     }
     if (trigger.stateFrom) {
         const updatedFrom = webhook.payload.updatedFrom;

package/dist/lib/types.d.ts

@@ -381,6 +381,8 @@ export interface SkillMetadata {
     version?: string;
     license?: string;
     keywords?: string[];
+    /** Alternate names this skill also resolves under (frontmatter `aliases:`). */
+    aliases?: string[];
 }
 /** Record of how a skill was installed into an agent version. */
 export interface SkillInstallation {
@@ -487,9 +489,9 @@ export interface SkillEntry {
     /** Registry-specific trust signal (e.g. 'builtin', 'trusted', 'community'). */
     trustLevel?: string;
     /**
-     * Lowercase hex sha256 of the skill's SKILL.md, as recorded by
-     * `agents publish`. When present, install verifies the cloned SKILL.md
-     * against it and aborts on mismatch.
+     * Lowercase hex sha256 of the skill's SKILL.md, as recorded by the registry
+     * index. When present, install verifies the cloned SKILL.md against it and
+     * aborts on mismatch.
      */
     sha256?: string;
 }
@@ -785,6 +787,10 @@ export interface ActorConfig {
 }
 /** Top-level structure of ~/.agents/.system/agents.yaml -- the CLI's persistent state. */
 export interface Meta {
+    /** Preferred provider account per harness. Explicit --account wins. */
+    accounts?: {
+        defaults?: Partial<Record<AgentId, string>>;
+    };
     agents?: Partial<Record<AgentId, string>>;
     /**
      * Per-agent preferred ISOLATED version — which copy a bare `agents run <agent>`
@@ -863,7 +869,7 @@ export interface Meta {
      * operator's config rather than an integration compiled into this CLI. When
      * this is unset/empty, an important-level post falls back to `notify.owner`
      * implicitly (RUSH-2123) — see lib/feed-broadcast.ts and
-     * docs/06-observability.md.
+     * docs/observability.md.
      */
     feed?: {
         broadcast?: FeedBroadcastConfig;
@@ -931,31 +937,28 @@ export interface Meta {
      */
     browser?: Record<string, BrowserProfileConfig>;
     /**
-     * Device-local pointer: the browser profile `agents browser start` resolves to
-     * when no `--profile` is passed (and what an explicit `--profile default`
-     * re-points to). Stored per-machine in `~/.agents/devices/<machine>/agents.yaml`,
-     * NOT central — the target profile may carry machine-local logins, so the choice
-     * must not ride `agents repo push/pull` to other machines. Unset = auto-detect an
-     * installed Chromium-family browser (legacy behavior). Set via
-     * `agents browser profiles set-default <name>`.
+     * Machine-local browser profiles — written to `config:`-adjacent
+     * `browser:` in `~/.agents/devices/<machine>/agents.yaml`, never the synced
+     * file.
+     *
+     * The auto-detected `default` profile lives here because it is inherently
+     * machine-specific: it carries an absolute `binary:` path and a port chosen by
+     * scanning THIS machine. Sharing it fleet-wide meant a macOS box wrote
+     * `/Applications/...`, a Linux box found it unlaunchable and rewrote
+     * `/usr/bin/chromium-browser`, and the two flipped the tracked agents.yaml back
+     * and forth on every `agents browser start` — the single largest source of
+     * churn on that file. User-created named profiles stay central and still sync.
      */
-    defaultBrowserProfile?: string;
+    deviceBrowser?: Record<string, BrowserProfileConfig>;
     /**
      * User-scope config block (`config:` in central agents.yaml). Holds the
      * user-scope keys from the device-config registry (`lib/device-config.ts`) —
-     * today just `interactiveHost`. Syncs fleet-wide via `agents repo push/pull`.
-     * Device-scope keys live in {@link Meta.deviceConfig} instead.
+     * currently `interactiveHost` and `usagePrimaryHost`. Syncs fleet-wide via
+     * `agents repo push/pull`.
+     * Device-scope keys live under `fleet.devices.<name>.config` instead (see
+     * {@link Meta.fleet}).
      */
     config?: Record<string, unknown>;
-    /**
-     * Device-scope config block, carried in memory under a distinct field so it
-     * can never leak into the central (synced) agents.yaml: `writeMetaUnlocked`
-     * routes it to `~/.agents/devices/<machine>/agents.yaml` under the `config:`
-     * key (mirroring how `defaultBrowserProfile` is routed), and
-     * `overlayMachineLocal` reads it back. Holds the device-scope keys from the
-     * device-config registry (`maxAgents`, `schedulerEnabled`, `notes`). Per-machine by design — unset = today's behavior.
-     */
-    deviceConfig?: Record<string, unknown>;
     /**
      * Routine names enabled on this machine. In memory this stays distinct from
      * portable user config; state.ts writes it as top-level `routines:` in
@@ -964,7 +967,19 @@ export interface Meta {
      */
     deviceRoutines?: string[];
     /**
-     * Agent-host registry keyed by host name (`agents hosts`). Portable user
+     * Machine-local operator config — the device-scope keys whose `visibility` is
+     * `machine` (see lib/device-config.ts). state.ts writes it as `config:` inside
+     * `~/.agents/devices/<machine>/agents.yaml`, which is gitignored, so it never
+     * reaches the fleet-shared agents.yaml.
+     *
+     * These are the keys nothing off-box reads. Keeping them out of the shared file
+     * is both a churn fix (13 machines were writing one tracked path) and a
+     * security one: `browser.remote-control` gates whether OTHER machines may drive
+     * this box's browser, so syncing one box's opt-in to the rest was wrong.
+     */
+    deviceConfig?: Record<string, unknown>;
+    /**
+     * Agent-host registry keyed by host name (the `--host`/`--device` dispatch overlay). Portable user
      * config synced with `agents repo push/pull`. For `ssh-config` hosts this is
      * just an overlay (caps/os) — the connection details stay in ~/.ssh/config and
      * are never copied. `inline` hosts carry their own address/user.
@@ -974,10 +989,13 @@ export interface Meta {
      * Declarative fleet profile (`agents apply` / `ag apply`). Additive to the
      * schema — project `agents:` version-pins are untouched. Declares which agents
      * every device should have, which config to sync, and how login propagates.
+     * `fleet.devices.<name>.config` is also the central store for per-device
+     * operator config (`agents devices config <name>`) — the device-scope keys of
+     * the `lib/device-config.ts` registry.
      * Full shape in `lib/fleet/types.ts` (FleetManifest).
      */
     fleet?: import('./fleet/types.js').FleetManifest;
-    /** `agents share` endpoint (Cloudflare R2 + Worker). Set by `agents share
+    /** Artifact share endpoint (Cloudflare R2 + Worker). Set by `agents artifacts
      * setup`/`join`; syncs fleet-wide via `agents repo push/pull`. The write token
      * lives in the `share` secrets bundle, not here. */
     share?: {
@@ -988,6 +1006,10 @@ export interface Meta {
         domain?: string;
         /** Cloudflare Web Analytics token injected into published HTML pages. */
         analyticsToken?: string;
+        /** sha256 of the Worker script deployed at the last provision/update, so
+         * `agents artifacts share status` can tell current vs outdated vs unknown (a config
+         * from before this field existed has no hash — always "unknown"). */
+        templateHash?: string;
     };
     /**
      * Owner/channel notification config for `agents send` / `agents notify`.
@@ -1004,16 +1026,6 @@ export interface Meta {
         };
         transports?: Record<string, string>;
     };
-    /**
-     * Routines daemon settings. `projects` is the allowlist of project roots
-     * whose `.agents/routines/*.yml` may be synced into `~/.agents/routines/`
-     * and fired by the daemon — never auto-discovered from a cloned public
-     * repo without an explicit opt-in (`agents routines enable-project`).
-     * Paths are stored absolute (or home-relative `~/…`).
-     */
-    routines?: {
-        projects?: string[];
-    };
 }
 /** A single delivery channel entry in humans.yaml. */
 export interface HumanChannel {

package/dist/lib/usage-fleet.d.ts

@@ -0,0 +1,32 @@
+import { type HeadroomEntry } from './usage-refresh.js';
+import { type UsageWindow } from './usage.js';
+export declare const USAGE_FLEET_VERSION = 1;
+export declare const USAGE_FLEET_FILE = ".usage-fleet.json";
+export interface UsageFleetWindow {
+    key: UsageWindow['key'];
+    label: string;
+    shortLabel: string;
+    usedPercent: number;
+    resetsAt: string | null;
+    windowMinutes: number | null;
+}
+export interface UsageFleetSnapshot {
+    capturedAt: string | null;
+    plan: string | null;
+    windows: UsageFleetWindow[];
+}
+export interface UsageFleetExport {
+    version: 1;
+    publishedAt: number;
+    usage: Record<string, UsageFleetSnapshot>;
+    headroom: Record<string, HeadroomEntry>;
+}
+/** Publisher/subscriber role selection, kept pure for the daemon gate test. */
+export declare function usageRefreshRole(primaryHost: string | undefined, self: string): 'publisher' | 'subscriber';
+export declare function setUsageFleetExportPathForTest(value: string | null): string | null;
+/** Build and persist the primary's safe cache envelope. */
+export declare function exportUsageFleet(now?: number): UsageFleetExport;
+/** Merge a primary-host envelope into the subscriber's existing caches. */
+export declare function importUsageFleet(value: unknown): UsageFleetExport;
+/** Fetch the primary's published envelope over the registered device SSH path. */
+export declare function importUsageFleetFromHost(host: string): Promise<UsageFleetExport>;

package/dist/lib/usage-fleet.js

@@ -0,0 +1,125 @@
+/**
+ * Token-free usage replication from the configured primary host.
+ *
+ * The publisher writes only the already-derived usage windows and routing
+ * headroom. Credentials, OAuth material, and provider responses never enter
+ * this envelope. Subscribers fetch that file over the existing SSH trust path
+ * and merge it into their local caches.
+ */
+import { spawn } from 'node:child_process';
+import * as path from 'node:path';
+import { buildSshInvocation, writeAskpassShim } from './devices/connect.js';
+import { loadDevices } from './devices/registry.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
+import { getCacheDir } from './state.js';
+import { readHeadroomCache, writeHeadroomEntries, } from './usage-refresh.js';
+import { readClaudeUsageCache, writeClaudeUsageCache, } from './usage.js';
+export const USAGE_FLEET_VERSION = 1;
+export const USAGE_FLEET_FILE = '.usage-fleet.json';
+/** Publisher/subscriber role selection, kept pure for the daemon gate test. */
+export function usageRefreshRole(primaryHost, self) {
+    return primaryHost && primaryHost !== self ? 'subscriber' : 'publisher';
+}
+let exportPathOverride = null;
+export function setUsageFleetExportPathForTest(value) {
+    const previous = exportPathOverride;
+    exportPathOverride = value;
+    return previous;
+}
+function exportPath() {
+    return exportPathOverride ?? path.join(getCacheDir(), USAGE_FLEET_FILE);
+}
+function safeSnapshot(snapshot) {
+    return {
+        capturedAt: snapshot.capturedAt?.toISOString() ?? null,
+        plan: snapshot.plan ?? null,
+        windows: snapshot.windows.map((window) => ({
+            key: window.key,
+            label: window.label,
+            shortLabel: window.shortLabel,
+            usedPercent: window.usedPercent,
+            resetsAt: window.resetsAt?.toISOString() ?? null,
+            windowMinutes: window.windowMinutes,
+        })),
+    };
+}
+function liveSnapshot(snapshot) {
+    return {
+        source: 'last_seen',
+        sourceLabel: 'primary host cache',
+        capturedAt: snapshot.capturedAt ? new Date(snapshot.capturedAt) : null,
+        plan: snapshot.plan,
+        windows: snapshot.windows.map((window) => ({
+            ...window,
+            resetsAt: window.resetsAt ? new Date(window.resetsAt) : null,
+        })),
+    };
+}
+/** Build and persist the primary's safe cache envelope. */
+export function exportUsageFleet(now = Date.now()) {
+    const headroom = readHeadroomCache();
+    const usage = {};
+    for (const usageKey of Object.keys(headroom)) {
+        const snapshot = readClaudeUsageCache(usageKey);
+        if (snapshot)
+            usage[usageKey] = safeSnapshot(snapshot);
+    }
+    const payload = {
+        version: USAGE_FLEET_VERSION,
+        publishedAt: now,
+        usage,
+        headroom,
+    };
+    atomicWriteFileSync(exportPath(), JSON.stringify(payload, null, 2), 'utf-8');
+    return payload;
+}
+function isUsageFleetExport(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const payload = value;
+    return payload.version === USAGE_FLEET_VERSION
+        && typeof payload.publishedAt === 'number'
+        && !!payload.usage && typeof payload.usage === 'object'
+        && !!payload.headroom && typeof payload.headroom === 'object';
+}
+/** Merge a primary-host envelope into the subscriber's existing caches. */
+export function importUsageFleet(value) {
+    if (!isUsageFleetExport(value))
+        throw new Error('usage fleet export has an unsupported shape');
+    for (const [usageKey, snapshot] of Object.entries(value.usage)) {
+        writeClaudeUsageCache(usageKey, liveSnapshot(snapshot));
+    }
+    writeHeadroomEntries(value.headroom);
+    return value;
+}
+/** Fetch the primary's published envelope over the registered device SSH path. */
+export async function importUsageFleetFromHost(host) {
+    const device = (await loadDevices())[host];
+    if (!device)
+        throw new Error(`usage primary host '${host}' is not a registered device`);
+    const remoteRead = device.shell === 'powershell'
+        ? ['Get-Content', '-Raw', '(Join-Path $HOME \'.agents/.cache/.usage-fleet.json\')']
+        : ['cat', '"$HOME/.agents/.cache/.usage-fleet.json"'];
+    const { args, env } = buildSshInvocation(device, remoteRead, writeAskpassShim(), {}, { agentOnly: true });
+    const raw = await new Promise((resolve, reject) => {
+        const child = spawn('ssh', args, {
+            env: { ...process.env, ...env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf-8');
+        child.stderr.setEncoding('utf-8');
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve(stdout);
+            else
+                reject(new Error(`usage primary host '${host}' export failed: ${stderr.trim() || `ssh exited ${code}`}`));
+        });
+    });
+    return importUsageFleet(JSON.parse(raw));
+}

package/dist/lib/usage-refresh.d.ts

@@ -72,7 +72,7 @@ export declare function shouldRefreshAccount(entry: HeadroomEntry | null | undef
  * projection, and record this call for the hourly cap.
  */
 export declare function nextHeadroomEntry(prev: HeadroomEntry | null | undefined, snapshot: UsageSnapshot | null, now: number): HeadroomEntry;
-/** An account whose credentials live on THIS host — the only ones we refresh. */
+/** An account whose credentials live on the publisher host. */
 export interface LocalUsageAccount {
     usageKey: string;
     agentId: AgentId;
@@ -80,12 +80,12 @@ export interface LocalUsageAccount {
     fetch: () => Promise<UsageInfo>;
 }
 /**
- * Enumerate the network-usage accounts whose credentials live on THIS host — one
+ * Enumerate the usage accounts whose credentials live on THIS host — one
  * per unique usage key, deduped to the most-recently-active version (the same
  * canonicalization `getUsageInfoByIdentity` uses). Each carries a closure that
  * live-fetches its usage. This is the daemon's `listAccounts`; because it only
  * ever lists local, signed-in accounts, each host is the sole writer for its own
- * accounts' caches — no cross-host coordination.
+ * accounts' caches. `runUsageRefreshTick` calls this only on the fleet publisher.
  */
 export declare function buildLocalUsageAccounts(): Promise<LocalUsageAccount[]>;
 /** Injectable side effects, so `runUsageRefresh` is drivable without the daemon. */