@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/lib/tmux/session.js

@@ -367,13 +367,14 @@ export async function paneExitStatus(pane, socket) {
  * Best-effort — returns false when tmux rejects the hook so callers do not
  * stamp a schema marker and daemon reconciliation can retry later.
  */
-export async function setSessionHook(name, hook, command, socket) {
+export async function setSessionHook(name, hook, command, socket, timeoutMs) {
     assertValidSessionName(name);
     const sock = socket ?? getDefaultSocketPath();
     const result = await runTmux({
         socket: sock,
         args: ['set-hook', '-t', name, hook, command],
         throwOnError: false,
+        timeoutMs,
     }).catch(() => null);
     return result?.code === 0;
 }
@@ -405,6 +406,15 @@ export async function setSessionHook(name, hook, command, socket) {
 export const AGENT_HOOK_SCHEMA = 5;
 /** Per-session tmux user-option that records which AGENT_HOOK_SCHEMA a session's hook is at. */
 const HOOK_SCHEMA_OPTION = '@ag_hook_schema';
+/**
+ * Bound on every tmux call made by the hook-repair path (daemon startup,
+ * upgrade migration, and single-session repair-before-attach). A wedged tmux
+ * server would otherwise hang the caller indefinitely — exactly the class of
+ * bug RUSH-2507 fixed for `listTmuxAgentSessions`'s `list-panes` call, applied
+ * here to `reconcileSessionHooks`/`repairSessionHookIfStale`'s calls so a
+ * wedged shared socket can no longer wedge daemon startup (RUSH-2435 review).
+ */
+const TMUX_HOOK_REPAIR_TIMEOUT_MS = 5_000;
 /**
  * The guarded `pane-died` hook. Detach the client ONLY when the agent pane dies
  * (so the blocking attach in runInTmux returns and the exit status can be read);
@@ -423,13 +433,13 @@ export function agentPaneDiedHook(sessionName, agentPane) {
     return `if -F '#{==:#{hook_pane},${agentPane}}' 'detach-client -s =${sessionName}' 'run-shell -b -C "kill-pane -t #{hook_pane}"'`;
 }
 /** Stamp a session's hook-schema marker to the current version. */
-export async function markSessionHookSchema(name, socket) {
+export async function markSessionHookSchema(name, socket, timeoutMs) {
     const sock = socket ?? getDefaultSocketPath();
-    await runTmux({ socket: sock, args: ['set-option', '-t', name, HOOK_SCHEMA_OPTION, String(AGENT_HOOK_SCHEMA)], throwOnError: false }).catch(() => { });
+    await runTmux({ socket: sock, args: ['set-option', '-t', name, HOOK_SCHEMA_OPTION, String(AGENT_HOOK_SCHEMA)], throwOnError: false, timeoutMs }).catch(() => { });
 }
 /** Read a session's hook-schema marker; undefined when unset (pre-marker sessions). */
-async function readHookSchema(name, socket) {
-    const res = await runTmux({ socket, args: ['show-options', '-v', '-t', name, HOOK_SCHEMA_OPTION], throwOnError: false }).catch(() => null);
+async function readHookSchema(name, socket, timeoutMs) {
+    const res = await runTmux({ socket, args: ['show-options', '-v', '-t', name, HOOK_SCHEMA_OPTION], throwOnError: false, timeoutMs }).catch(() => null);
     if (!res || res.code !== 0)
         return undefined;
     const v = res.stdout.trim();
@@ -441,8 +451,8 @@ async function readHookSchema(name, socket) {
  * for sessions whose SessionMeta (which records the agent pane) predates meta
  * persistence. Undefined when the session has no panes (already torn down).
  */
-async function lowestPaneId(name, socket) {
-    const res = await runTmux({ socket, args: ['list-panes', '-t', name, '-F', '#{pane_id}'], throwOnError: false }).catch(() => null);
+async function lowestPaneId(name, socket, timeoutMs) {
+    const res = await runTmux({ socket, args: ['list-panes', '-t', name, '-F', '#{pane_id}'], throwOnError: false, timeoutMs }).catch(() => null);
     if (!res || res.code !== 0)
         return undefined;
     const ids = res.stdout.split('\n').map(l => l.trim()).filter(id => /^%\d+$/.test(id));
@@ -467,11 +477,35 @@ export async function prepareSessionForResume(name, socket) {
         ? recordedPane
         : await lowestPaneId(name, sock);
     const state = pane ? await paneExitStatus(pane, sock) : undefined;
-    if (pane && state?.found && !state.dead)
+    if (pane && state?.found && !state.dead) {
+        // Self-heal a legacy/stale hook right before handing the session back to
+        // an attach client — the steady-state repair point between the daemon's
+        // startup and upgrade one-shots (RUSH-2435).
+        await ensureSessionHookRepaired(name, sock);
         return { decision: 'attach', pane };
+    }
     await killSession(name, sock);
     return { decision: 'create' };
 }
+/**
+ * Repair ONE session's `pane-died` hook if it predates AGENT_HOOK_SCHEMA.
+ * Idempotent and NON-DESTRUCTIVE — only `set-hook`s, never kills a pane or
+ * detaches a client. Shared by {@link reconcileSessionHooks} (full sweep) and
+ * {@link ensureSessionHookRepaired} (single session, called before attach) so
+ * the two can never drift on what counts as "repaired" (RUSH-2435).
+ */
+async function repairSessionHookIfStale(name, sock, meta, timeoutMs = TMUX_HOOK_REPAIR_TIMEOUT_MS) {
+    if (await readHookSchema(name, sock, timeoutMs) === String(AGENT_HOOK_SCHEMA))
+        return false;
+    const agentPane = meta?.pane ?? await lowestPaneId(name, sock, timeoutMs);
+    if (!agentPane)
+        return false;
+    const installed = await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, agentPane), sock, timeoutMs);
+    if (!installed)
+        return false;
+    await markSessionHookSchema(name, sock, timeoutMs);
+    return true;
+}
 /**
  * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
  * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:
@@ -481,9 +515,15 @@ export async function prepareSessionForResume(name, socket) {
  * exited a split — self-heals in place, without waiting for those agents to exit
  * or for the server to be recycled.
  *
- * The daemon calls this on a light interval. The per-session `@ag_hook_schema`
- * marker makes steady-state a cheap no-op: a session already at the current
- * schema is skipped. Only run-wrapped sessions (`ag-` prefix) are touched — an
+ * NOT a daemon poll — the 5-minute `tmux-reconcile` routine that used to call this
+ * was deleted (RUSH-2495). It survives as the version-skew ONE-SHOT: the daemon
+ * calls it once at startup (`runDaemon` in `../daemon.js`) and once from the
+ * upgrade-time migration (`runMigration` in `../migrate.js`), so a session a
+ * pre-fix binary left with a stale hook still self-heals without a live poller.
+ * `ensureSessionHookRepaired` covers the steady-state gap between those two
+ * points by repairing a single session right before it's attached to. The
+ * per-session `@ag_hook_schema` marker makes both paths a cheap no-op once a
+ * session is current. Only run-wrapped sessions (`ag-` prefix) are touched — an
  * externally-created session on the socket keeps whatever hook it set.
  */
 export async function reconcileSessionHooks(socket) {
@@ -492,7 +532,7 @@ export async function reconcileSessionHooks(socket) {
         return { scanned: 0, reconciled: 0 };
     let sessions;
     try {
-        sessions = await listSessions({ socket: sock });
+        sessions = await listSessions({ socket: sock, timeoutMs: TMUX_HOOK_REPAIR_TIMEOUT_MS });
     }
     catch {
         return { scanned: 0, reconciled: 0 };
@@ -501,19 +541,32 @@ export async function reconcileSessionHooks(socket) {
     for (const s of sessions) {
         if (!s.name.startsWith('ag-'))
             continue; // only run-wrapped sessions
-        if (await readHookSchema(s.name, sock) === String(AGENT_HOOK_SCHEMA))
-            continue;
-        const agentPane = s.meta?.pane ?? await lowestPaneId(s.name, sock);
-        if (!agentPane)
-            continue;
-        const installed = await setSessionHook(s.name, 'pane-died', agentPaneDiedHook(s.name, agentPane), sock);
-        if (!installed)
-            continue;
-        await markSessionHookSchema(s.name, sock);
-        reconciled++;
+        if (await repairSessionHookIfStale(s.name, sock, s.meta))
+            reconciled++;
     }
     return { scanned: sessions.length, reconciled };
 }
+/**
+ * Repair a single managed session's `pane-died` hook right before it is
+ * attached to, so a legacy session left by a pre-fix binary self-heals on the
+ * next touch instead of waiting for the next daemon-startup/upgrade one-shot
+ * (RUSH-2435). Only `ag-`-prefixed (run-wrapped) sessions are touched; a no-op
+ * for anything else. Best-effort — never throws, so a repair failure can never
+ * block the attach it is protecting.
+ */
+export async function ensureSessionHookRepaired(name, socket) {
+    if (!name.startsWith('ag-'))
+        return;
+    const sock = socket ?? getDefaultSocketPath();
+    if (!fs.existsSync(sock))
+        return;
+    try {
+        await repairSessionHookIfStale(name, sock, readSessionMeta(name) ?? undefined);
+    }
+    catch {
+        // best-effort — an attach must never fail because a repair attempt did
+    }
+}
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)
@@ -532,6 +585,7 @@ export async function listSessions(opts = {}) {
         socket,
         args: ['list-sessions', '-F', fmt],
         throwOnError: false,
+        timeoutMs: opts.timeoutMs,
     });
     // tmux returns nonzero with "no server running" or "no sessions" — both mean empty.
     if (res.code !== 0) {

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

@@ -5,7 +5,7 @@
  * project/system layers). They complement routine triggers: a matching webhook
  * can run an agent, workflow, shell command, or delegate to a routine.
  */
-import type { JobConfig, RunMeta, WebhookContext } from '../routines.js';
+import type { JobConfig, RunMeta, WebhookContext } from '../scheduling/routines.js';
 import type { AgentId } from '../types.js';
 import type { IncomingWebhook, WebhookSource } from './webhook.js';
 export interface WebhookHandler {

package/dist/lib/triggers/handlers.js

@@ -9,11 +9,11 @@ import { exec } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { emit } from '../events.js';
+import { emit } from '../feed/events.js';
 import { machineId, normalizeHost } from '../machine-id.js';
 import { safeJoin } from '../paths.js';
 import { pickFleetDevice } from '../routines-placement.js';
-import { assertShellSubstitutionSupported, readJob, substituteWebhookCommand, substituteWebhookPrompt, } from '../routines.js';
+import { assertShellSubstitutionSupported, readJob, substituteWebhookCommand, substituteWebhookPrompt, } from '../scheduling/routines.js';
 import { ensureAgentsDir, getProjectWebhooksDir, getSystemWebhooksDir, getWebhooksDir } from '../state.js';
 const HANDLER_DEFAULTS = {
     enabled: true,

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

@@ -13,7 +13,7 @@
  */
 import * as http from 'http';
 import type { IncomingHttpHeaders } from 'http';
-import type { JobConfig, RunMeta, WebhookContext } from '../routines.js';
+import type { JobConfig, RunMeta, WebhookContext } from '../scheduling/routines.js';
 import { type FiredHandler } from './handlers.js';
 export type WebhookSource = 'github' | 'linear';
 export interface IncomingWebhook {
@@ -123,6 +123,15 @@ export interface RateLimiter {
     take(key: string): boolean;
 }
 export declare function createMemoryRateLimiter(limit: number, windowMs: number): RateLimiter;
+/**
+ * Resolve once a receiver is actually accepting connections, REJECT if the bind
+ * failed. `server.listen()` reports a bind failure (EADDRINUSE, EACCES) as an
+ * asynchronous `'error'` event, never a throw — so a `try/catch` around
+ * `startWebhookServer` cannot see it, and without this the event reaches Node's
+ * default handler and takes the whole process down. Every caller that hosts a
+ * receiver MUST await this rather than assuming the return means "bound".
+ */
+export declare function waitForListening(server: http.Server): Promise<void>;
 /** Options for the local webhook http listener. */
 export interface WebhookServerOptions {
     port?: number;
@@ -131,8 +140,19 @@ export interface WebhookServerOptions {
     secrets: WebhookSecrets;
     /** Override the fire options (mainly for tests). */
     fire?: FireWebhookOptions;
-    /** Called after each delivery is handled (mainly for tests/observability). */
+    /**
+     * Called after a delivery has fully settled — every matched routine and
+     * handler dispatched. Because the receiver acks the HTTP response BEFORE
+     * dispatch (see `startWebhookServer`), this fires strictly after the response
+     * has been written, and is the only way a caller observes the outcome.
+     */
     onDelivery?: (webhook: IncomingWebhook, fired: FiredJob[], handlers: FiredHandler[]) => void;
+    /**
+     * Called when settling an already-acked delivery threw. The HTTP status can
+     * no longer carry the failure, so this is the loud path — the daemon host and
+     * `agents webhooks serve` both log it. Never swallowed silently.
+     */
+    onDeliveryError?: (webhook: IncomingWebhook, error: Error) => void;
     deliveryStore?: DeliveryStore;
     rateLimiter?: RateLimiter;
     rateLimitPerMinute?: number;
@@ -149,6 +169,20 @@ export interface WebhookServerOptions {
  *   POST /hooks/github  with X-Hub-Signature-256
  *   POST /hooks/linear  with Linear-Signature + fresh webhookTimestamp
  *
+ * **The ack is asynchronous (RUSH-2548).** Once a delivery has passed signature
+ * verification, freshness, dedup, and rate limiting, the receiver writes
+ * `202 {ok:true, accepted:true}` IMMEDIATELY and dispatches the matched routines
+ * and handlers afterwards. Dispatch starts an agent run and takes 15-20s, which
+ * exceeds Linear's delivery timeout — holding the socket open across it made
+ * every real delivery log a timeout + retry on Linear's side. Nothing about the
+ * dedup ledger changes: the `<source>:<delivery-id>` key is still what makes a
+ * retry a no-op, per-job `markJob` still lets a retry finish only the matches
+ * that failed, and the delivery is marked complete only after it settles.
+ *
+ * A retry that lands WHILE the first is still settling is answered as a
+ * duplicate from an in-flight set, since `deliveryStore.seen` only reports
+ * completed deliveries and would otherwise let a mid-flight retry double-fire.
+ *
  * Returns the underlying server so callers can `close()` it.
  */
 export declare function startWebhookServer(options: WebhookServerOptions): http.Server;

package/dist/lib/triggers/webhook.js

@@ -15,9 +15,9 @@ import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as http from 'http';
 import * as path from 'path';
-import { jobRunsOnThisDevice, listJobs, substituteWebhookPrompt } from '../routines.js';
+import { jobRunsOnThisDevice, listJobs, substituteWebhookPrompt } from '../scheduling/routines.js';
 import { executeJobDetached } from '../runner.js';
-import { emit } from '../events.js';
+import { emit } from '../feed/events.js';
 import { listHandlers, handlerMatchesWebhook, executeHandler, buildWebhookContext, } from './handlers.js';
 /** Read `repository.full_name` (`owner/name`) from a webhook payload, if present. */
 export function webhookRepo(payload) {
@@ -420,18 +420,106 @@ async function readRawBody(req, maxBytes) {
     }
     return Buffer.concat(chunks);
 }
+/**
+ * Resolve once a receiver is actually accepting connections, REJECT if the bind
+ * failed. `server.listen()` reports a bind failure (EADDRINUSE, EACCES) as an
+ * asynchronous `'error'` event, never a throw — so a `try/catch` around
+ * `startWebhookServer` cannot see it, and without this the event reaches Node's
+ * default handler and takes the whole process down. Every caller that hosts a
+ * receiver MUST await this rather than assuming the return means "bound".
+ */
+export function waitForListening(server) {
+    if (server.listening)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            server.off('listening', onListening);
+            server.off('error', onError);
+        };
+        const onListening = () => { cleanup(); resolve(); };
+        const onError = (err) => { cleanup(); reject(err); };
+        server.once('listening', onListening);
+        server.once('error', onError);
+    });
+}
 /**
  * Start a localhost-bound receiver. It accepts only:
  *   POST /hooks/github  with X-Hub-Signature-256
  *   POST /hooks/linear  with Linear-Signature + fresh webhookTimestamp
  *
+ * **The ack is asynchronous (RUSH-2548).** Once a delivery has passed signature
+ * verification, freshness, dedup, and rate limiting, the receiver writes
+ * `202 {ok:true, accepted:true}` IMMEDIATELY and dispatches the matched routines
+ * and handlers afterwards. Dispatch starts an agent run and takes 15-20s, which
+ * exceeds Linear's delivery timeout — holding the socket open across it made
+ * every real delivery log a timeout + retry on Linear's side. Nothing about the
+ * dedup ledger changes: the `<source>:<delivery-id>` key is still what makes a
+ * retry a no-op, per-job `markJob` still lets a retry finish only the matches
+ * that failed, and the delivery is marked complete only after it settles.
+ *
+ * A retry that lands WHILE the first is still settling is answered as a
+ * duplicate from an in-flight set, since `deliveryStore.seen` only reports
+ * completed deliveries and would otherwise let a mid-flight retry double-fire.
+ *
  * Returns the underlying server so callers can `close()` it.
  */
 export function startWebhookServer(options) {
     const deliveryStore = options.deliveryStore ?? createMemoryDeliveryStore();
+    /** Delivery ids acked but not yet settled — dedup across the async window. */
+    const inFlight = new Set();
     const rateLimiter = options.rateLimiter ?? createMemoryRateLimiter(options.rateLimitPerMinute ?? 60, 60_000);
     const ipRateLimiter = options.ipRateLimiter ?? createMemoryRateLimiter(options.ipRateLimitPerMinute ?? 120, 60_000);
     const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+    /**
+     * Dispatch an already-acked delivery: matched routines first, then matched
+     * handlers, then mark the delivery complete. A failure leaves the delivery
+     * UNMARKED (its per-job `markJob` entries survive), so a later retry of the
+     * same delivery id re-runs only what did not complete — the same partial-retry
+     * ledger the synchronous receiver had, minus the 4xx that used to request it.
+     */
+    async function settleDelivery(webhook, id) {
+        const { source, event: webhookEvent } = webhook;
+        try {
+            const context = buildWebhookContext(webhook);
+            const fireOptions = options.fire ?? {};
+            const firedJobs = await fireWebhookJobs(webhook, {
+                ...fireOptions,
+                context,
+                skipJobNames: deliveryStore.completedJobs(id),
+                onJobFired: (job, firedJob) => {
+                    emit('webhook.fired', { source, event: webhookEvent, deliveryId: id, jobName: job.name, runId: firedJob.runId });
+                    deliveryStore.markJob(id, job.name);
+                    fireOptions.onJobFired?.(job, firedJob);
+                },
+            });
+            const matchedHandlers = listHandlers().filter((handler) => handlerMatchesWebhook(handler, webhook));
+            const firedHandlers = [];
+            const handlerErrors = [];
+            await Promise.allSettled(matchedHandlers.map(async (handler) => {
+                if (deliveryStore.completedJobs(id).has(handler.name))
+                    return;
+                emit('webhook.matched', { source, event: webhookEvent, deliveryId: id, handlerName: handler.name });
+                try {
+                    const result = await executeHandler(handler, webhook);
+                    deliveryStore.markJob(id, handler.name);
+                    firedHandlers.push(result);
+                }
+                catch (err) {
+                    handlerErrors.push({ handlerName: handler.name, error: err.message });
+                }
+            }));
+            deliveryStore.mark(id);
+            for (const failure of handlerErrors) {
+                emit('webhook.failed', { source, event: webhookEvent, deliveryId: id, handlerName: failure.handlerName, error: failure.error });
+            }
+            options.onDelivery?.(webhook, firedJobs, firedHandlers);
+        }
+        catch (err) {
+            const error = err;
+            emit('webhook.failed', { source, event: webhookEvent, deliveryId: id, error: error.message });
+            options.onDeliveryError?.(webhook, error);
+        }
+    }
     const server = http.createServer((req, res) => {
         void (async () => {
             if (req.method !== 'POST') {
@@ -485,7 +573,7 @@ export function startWebhookServer(options) {
                 const id = deliveryId(source, req.headers, rawBody);
                 const event = source === 'github' ? (header(req.headers, 'x-github-event') ?? '') : '';
                 emit('webhook.received', { source, event, deliveryId: id });
-                if (deliveryStore.seen(id)) {
+                if (deliveryStore.seen(id) || inFlight.has(id)) {
                     res.writeHead(200, { 'content-type': 'application/json' });
                     res.end(JSON.stringify({ ok: true, duplicate: true, fired: [] }));
                     return;
@@ -510,45 +598,12 @@ export function startWebhookServer(options) {
                     payload,
                 };
                 emit('webhook.authorized', { source, event: webhookEvent, deliveryId: id });
-                const context = buildWebhookContext(webhook);
-                const fireOptions = options.fire ?? {};
-                const firedJobs = await fireWebhookJobs(webhook, {
-                    ...fireOptions,
-                    context,
-                    skipJobNames: deliveryStore.completedJobs(id),
-                    onJobFired: (job, firedJob) => {
-                        emit('webhook.fired', { source, event: webhookEvent, deliveryId: id, jobName: job.name, runId: firedJob.runId });
-                        deliveryStore.markJob(id, job.name);
-                        fireOptions.onJobFired?.(job, firedJob);
-                    },
-                });
-                const handlers = listHandlers();
-                const matchedHandlers = handlers.filter((handler) => handlerMatchesWebhook(handler, webhook));
-                const firedHandlers = [];
-                const handlerErrors = [];
-                await Promise.allSettled(matchedHandlers.map(async (handler) => {
-                    if (deliveryStore.completedJobs(id).has(handler.name))
-                        return;
-                    emit('webhook.matched', { source, event: webhookEvent, deliveryId: id, handlerName: handler.name });
-                    try {
-                        const result = await executeHandler(handler, webhook);
-                        deliveryStore.markJob(id, handler.name);
-                        firedHandlers.push(result);
-                    }
-                    catch (err) {
-                        handlerErrors.push({ handlerName: handler.name, error: err.message });
-                    }
-                }));
-                deliveryStore.mark(id);
-                options.onDelivery?.(webhook, firedJobs, firedHandlers);
-                res.writeHead(200, { 'content-type': 'application/json' });
-                res.end(JSON.stringify({
-                    ok: true,
-                    fired: firedJobs.map((f) => f.jobName),
-                    runs: firedJobs,
-                    handlers: firedHandlers,
-                    ...(handlerErrors.length > 0 ? { handlerErrors } : {}),
-                }));
+                // ACK FIRST (RUSH-2548). Everything that could reject this delivery has
+                // run; what remains starts agent runs and outlives any sender timeout.
+                inFlight.add(id);
+                res.writeHead(202, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, accepted: true, deliveryId: id }));
+                void settleDelivery(webhook, id).finally(() => inFlight.delete(id));
             }
             catch (err) {
                 res.writeHead(400, { 'content-type': 'application/json' });

package/dist/lib/types.d.ts

@@ -790,6 +790,17 @@ export interface Meta {
     /** Preferred provider account per harness. Explicit --account wins. */
     accounts?: {
         defaults?: Partial<Record<AgentId, string>>;
+        /** Named harness-owned identities. Metadata only; OAuth credentials stay in the harness home. */
+        native?: Record<string, {
+            id: string;
+            name: string;
+            agent: AgentId;
+            identityKey: string;
+            identityLabel?: string;
+            scope: 'version' | 'device';
+        }>;
+        /** Exact installation/custom-harness target -> stable account id. */
+        bindings?: Record<string, string>;
     };
     agents?: Partial<Record<AgentId, string>>;
     /**
@@ -955,8 +966,9 @@ export interface Meta {
      * user-scope keys from the device-config registry (`lib/device-config.ts`) —
      * 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}).
+     * Device-scope keys live in the per-device doc
+     * `devices/<name>/agents.yaml` `config:` block, layered over the fleet-wide
+     * defaults in {@link Meta.fleet} (`fleet.defaults.config`).
      */
     config?: Record<string, unknown>;
     /**
@@ -979,7 +991,7 @@ export interface Meta {
      */
     deviceConfig?: Record<string, unknown>;
     /**
-     * Agent-host registry keyed by host name (the `--host`/`--device` dispatch overlay). Portable user
+     * Agent-host registry keyed by host name (the `--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.
@@ -989,9 +1001,9 @@ 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.
+     * `fleet.defaults.config` is also the fleet-wide DEFAULTS layer of the
+     * device-config store (`agents devices config --fleet <key> <value>`) — read
+     * between the built-in default and the per-device doc's `config:` block.
      * Full shape in `lib/fleet/types.ts` (FleetManifest).
      */
     fleet?: import('./fleet/types.js').FleetManifest;

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

@@ -1,5 +1,5 @@
 import { type HeadroomEntry } from './usage-refresh.js';
-import { type UsageWindow } from './usage.js';
+import { type UsageWindow } from './accounting/usage.js';
 export declare const USAGE_FLEET_VERSION = 1;
 export declare const USAGE_FLEET_FILE = ".usage-fleet.json";
 export interface UsageFleetWindow {

package/dist/lib/usage-fleet.js

@@ -13,7 +13,7 @@ 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';
+import { readClaudeUsageCache, writeClaudeUsageCache, } from './accounting/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. */

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

@@ -1,4 +1,4 @@
-import { type UsageHeadroom, type UsageSnapshot, type UsageInfo } from './usage.js';
+import { type UsageHeadroom, type UsageSnapshot, type UsageInfo } from './accounting/usage.js';
 import type { AgentId } from './types.js';
 /**
  * Default schedule between successful (or attempted) live usage fetches for one

package/dist/lib/usage-refresh.js

@@ -50,9 +50,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
-import { deriveUsageHeadroom, buildCanonicalUsageContext, USAGE_SOURCE_AGENT_IDS, } from './usage.js';
+import { deriveUsageHeadroom, buildCanonicalUsageContext, USAGE_SOURCE_AGENT_IDS, } from './accounting/usage.js';
 import { getAccountInfo } from './agents.js';
-import { listInstalledVersions, getVersionHomePath } from './versions.js';
+import { listInstalledVersions, getVersionHomePath } from './installations/versions.js';
 /**
  * Default schedule between successful (or attempted) live usage fetches for one
  * account. Floor and ceiling of the delay helper are pinned to this so the
@@ -202,7 +202,7 @@ export async function buildLocalUsageAccounts() {
                 // only, never the interactive login (see loadClaudeOauth); no setup-token
                 // reads as "usage pending".
                 fetch: async () => {
-                    const { getUsageInfoForIdentity } = await import('./usage.js');
+                    const { getUsageInfoForIdentity } = await import('./accounting/usage.js');
                     return getUsageInfoForIdentity({
                         agentId,
                         home: fetchInput.home,

package/dist/lib/version-duplicates.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import { getAccountInfo, agentLabel } from './agents.js';
-import { compareVersions, getVersionHomePath, listInstalledVersions, } from './versions.js';
-import { buildCanonicalUsageContext, getUsageLookupKey, } from './usage.js';
+import { compareVersions, getVersionHomePath, listInstalledVersions, } from './installations/versions.js';
+import { buildCanonicalUsageContext, getUsageLookupKey, } from './accounting/usage.js';
 function duplicateIdentity(info) {
     if (!info)
         return null;

package/dist/lib/view-types.d.ts

@@ -0,0 +1,56 @@
+import type { ConfiguredModelSource } from './models.js';
+import type { ProfileSummary } from './profiles.js';
+import type { AgentId } from './types.js';
+export type SyncState = 'synced' | 'new' | 'modified' | 'deleted';
+export interface ViewJsonVersion {
+    version: string;
+    isDefault: boolean;
+    isolated: boolean;
+    isIsolatedDefault: boolean;
+    signedIn: boolean;
+    email: string | null;
+    accountId?: string | null;
+    organizationType?: string | null;
+    organizationName?: string | null;
+    plan: string | null;
+    usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null;
+    overageCredits?: {
+        amount: number;
+        currency: string;
+    } | null;
+    windows: Array<{
+        key: 'session' | 'week' | 'sonnet_week' | 'month';
+        label?: string;
+        usedPercent: number;
+        resetsAt: string | null;
+    }>;
+    lastActive: string | null;
+    path: string;
+    configuredModel?: {
+        model: string;
+        source: ConfiguredModelSource;
+    } | null;
+    resources?: VersionResourcesJson;
+}
+export interface ViewJsonAgent {
+    agent: AgentId;
+    versions: ViewJsonVersion[];
+    harnesses: ProfileSummary[];
+}
+export type ResourceSection = 'commands' | 'skills' | 'mcp' | 'memory' | 'hooks' | 'workflows' | 'plugins';
+export interface ResourceItemJson {
+    name: string;
+    scope?: 'user' | 'project';
+    syncState?: SyncState;
+    description?: string;
+    ruleCount?: number;
+}
+export interface VersionResourcesJson {
+    commands?: ResourceItemJson[];
+    skills?: ResourceItemJson[];
+    mcp?: ResourceItemJson[];
+    memory?: ResourceItemJson[];
+    hooks?: ResourceItemJson[];
+    workflows?: ResourceItemJson[];
+    plugins?: ResourceItemJson[];
+}

package/dist/lib/view-types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/watchdog/rotate.d.ts

@@ -27,7 +27,7 @@
  *
  * Config: `watchdog.rotate: on|off` in agents.yaml (default on), read per tick.
  */
-import type { InjectTarget } from '../terminal/inject.js';
+import type { InjectTarget } from '../terminal/index.js';
 import type { ActiveSession } from '../session/active.js';
 /**
  * Agent-reported hard-limit texts, matched against a session transcript tail.
@@ -78,7 +78,7 @@ export declare function exitSequenceFor(agent: string): string[];
  * host (affinity) → harness (cross-harness headroom) → account (balanced) and
  * exits nonzero when every layer is exhausted. Ported from apps/ext
  * autoRotate.ts buildAutoRotateLaunchCommand. A terminal on a REMOTE device
- * rotates ON that device (`--host`); a local terminal omits it. `--session-id`
+ * rotates ON that device (`--device`); a local terminal omits it. `--session-id`
  * is honored only when the CLI picks claude (existing claude-only semantics)
  * and ignored otherwise — passing it unconditionally keeps the terminal's
  * AGENT_SESSION_ID aligned with the session Claude actually creates.