@phnx-labs/agents-cli 1.22.53 → 1.22.55

package/dist/lib/startup/root-command.js

@@ -19,7 +19,8 @@
 export function configureRootCommand(program, name, version) {
     return program
         .name(name)
-        .description('Environment manager for AI agents')
+        .description('Install, configure, run, and dispatch AI coding agents from one place.\n' +
+        'Works with Claude, Codex, Antigravity, Cursor, OpenCode, OpenClaw, and Droid.')
         .version(version)
         .option('--verbose', 'Show startup self-heal details on stderr')
         .helpOption('-h, --help', 'Show help')

package/dist/lib/state.d.ts

@@ -391,6 +391,22 @@ export declare function getDeviceMetaPath(): string;
  */
 export declare function getVersionResourcesPath(): string;
 export declare function withMetaLock<T>(fn: () => T): T;
+/**
+ * True when the top-level `~/.agents/agents.yaml` carries a metadata header that
+ * is NOT the canonical {@link META_HEADER} — the P1 frozen-header case a box only
+ * heals on its next central write (serializeCentral). An absent or headerless
+ * file is NOT stale (a headerless central file is deliberately left alone).
+ * Surfaced as config drift by `agents sync status` (PHNX-3315).
+ */
+export declare function hasStaleMetaHeader(): boolean;
+/**
+ * Parse the top-level user `agents.yaml` (this box's synced central file) WITHOUT
+ * the system-repo merge, machine-local overlay, or cache — the raw on-disk central
+ * map, or null when the file is absent/unparseable. Used by config-drift detection
+ * to see the central blocks that should have folded into the device doc, without
+ * mis-attributing a system-repo default as this box's own leak (PHNX-3315).
+ */
+export declare function readTopLevelUserMeta(): Record<string, unknown> | null;
 /**
  * Write `meta` to disk (central + device docs + pins) WITHOUT taking the meta
  * lock — the caller must already hold it via {@link withMetaLock}. Exported so a

package/dist/lib/state.js

@@ -858,52 +858,99 @@ function writeIfChanged(filePath, content) {
  * `agents:` / `versions:` are not written (no empty committed files).
  */
 /**
- * Every `Meta` key, classified as `central` (synced via agents.yaml) or `device`
- * (routed to the per-machine device file by {@link writeMetaUnlocked}). The
- * `Record<keyof Meta, …>` type makes this EXHAUSTIVE: adding a field to `Meta`
- * without classifying it here is a compile error. That guarantee is what lets
- * `serializeCentral` delete only keys THIS version models — a key a newer CLI
- * version added (absent from this map) is preserved verbatim instead of being
- * dropped and synced fleet-wide as data loss. This is the fix for the recurring
- * agents.yaml key-loss (beta flags, `notify.owner`, and `feed:` all vanished
- * this way when an older-versioned CLI on the fleet rewrote the file).
+ * Fleet-shared (`central`) Meta keys — the OPT-IN allowlist. A key listed here is
+ * written to the synced `~/.agents/agents.yaml`. Device-scope is the DEFAULT:
+ * {@link metaKeyScope} returns `'device'` for every Meta key NOT listed here, so a
+ * newly-added key can never SILENTLY churn the shared file the way a
+ * central-by-default would — the very trap behind the recurring agents.yaml churn.
+ * Making a key fleet-shared is now a deliberate edit HERE, not the path of least
+ * resistance (PHNX-3315).
  */
-const META_KEY_SCOPE = {
-    // Device-local — writeMetaUnlocked destructures these out; never in central.
-    agents: 'device',
-    isolatedAgents: 'device',
-    versions: 'device',
-    deviceRoutines: 'device',
-    deviceConfig: 'device',
-    deviceBrowser: 'device',
-    deviceFleet: 'device',
-    deviceHosts: 'device',
-    deviceAccounts: 'device',
-    // Central — synced via agents.yaml.
-    accounts: 'central',
-    run: 'central',
-    model: 'central',
-    watchdog: 'central',
-    lease: 'central',
-    secrets: 'central',
-    budget: 'central',
-    feed: 'central',
-    beta: 'central',
-    registries: 'central',
-    profiles: 'central',
-    source: 'central',
-    projectRoot: 'device',
-    extraRepos: 'central',
-    brands: 'central',
-    actors: 'central',
-    seededPresets: 'central',
-    hooks: 'central',
-    config: 'central',
-    hosts: 'central',
-    fleet: 'central',
-    share: 'central',
-    notify: 'central',
-};
+const CENTRAL_META_KEYS = [
+    'accounts',
+    'run',
+    'model',
+    'watchdog',
+    'lease',
+    'secrets',
+    'budget',
+    'feed',
+    'beta',
+    'registries',
+    'profiles',
+    'source',
+    'extraRepos',
+    'brands',
+    'actors',
+    'seededPresets',
+    'hooks',
+    'config',
+    'hosts',
+    'fleet',
+    'share',
+    'notify',
+];
+/**
+ * Device-scoped Meta keys with BESPOKE routing — each lands in a special file
+ * (pins JSON / version-resources JSON) or a REMAPPED device-doc sub-block
+ * (`deviceHosts`->`hosts:`, `deviceFleet`->`fleet:`, ...), so their handling is
+ * hand-written in {@link writeMetaUnlocked} / {@link overlayMachineLocal} and kept
+ * behavior-identical. A device-scoped key NOT listed here is a GENERIC device key:
+ * it round-trips through `devices/<host>/agents.yaml` under its OWN name with no
+ * bespoke wiring (see the generic loops in those two functions). The `browser`
+ * tombstone is bespoke too — drained by lib/browser/registry.ts.
+ */
+const BESPOKE_DEVICE_KEYS = [
+    'agents',
+    'isolatedAgents',
+    'versions',
+    'deviceRoutines',
+    'deviceConfig',
+    'deviceBrowser',
+    'deviceFleet',
+    'deviceHosts',
+    'deviceAccounts',
+    'projectRoot',
+];
+const CENTRAL_KEY_SET = new Set(CENTRAL_META_KEYS);
+const _metaKeysAreExhaustive = true;
+void _metaKeysAreExhaustive;
+/**
+ * Sync-domain of a Meta key. `'central'` ONLY for the opt-in allowlist; `'device'`
+ * by DEFAULT for everything else — so the classification is authoritative (it
+ * DRIVES the generic device-doc router below) rather than a decorative string map,
+ * and forgetting to classify a new key routes it to the SAFE per-box file.
+ */
+function metaKeyScope(key) {
+    return CENTRAL_KEY_SET.has(key) ? 'central' : 'device';
+}
+/** Bespoke device keys as a runtime Set (the generic router skips these). */
+const BESPOKE_DEVICE_KEY_SET = new Set([
+    ...BESPOKE_DEVICE_KEYS,
+    // The `browser` tombstone is device-scoped but bespoke: lib/browser/registry.ts
+    // drains it (collision-checked) into deviceBrowser, so the generic router must
+    // never blindly relocate it.
+    'browser',
+]);
+/**
+ * Device-doc sub-block names the read/write paths handle BESPOKE-ly (each maps to
+ * a different `device*` Meta key, or lives in a separate file). The generic
+ * device-doc overlay skips these so it only surfaces genuine generic keys.
+ */
+const BESPOKE_DEVICE_DOC_KEYS = new Set([
+    'agents',
+    'isolatedAgents',
+    'routines',
+    'config',
+    'browser',
+    'fleet',
+    'hosts',
+    'accounts',
+    'projectRoot',
+    // Legacy top-level doc key the config migration folds into `config:`; never
+    // surfaced onto Meta before, so keep the generic overlay from doing so.
+    'defaultBrowserProfile',
+]);
 /**
  * Every key this version models (central + device). serializeCentral deletes an
  * on-disk key only when it is KNOWN and absent from the write's in-memory object:
@@ -913,7 +960,8 @@ const META_KEY_SCOPE = {
  * a newer CLI version added — is preserved verbatim, never dropped + synced away.
  */
 const KNOWN_META_KEYS = new Set([
-    ...Object.keys(META_KEY_SCOPE),
+    ...CENTRAL_META_KEYS,
+    ...BESPOKE_DEVICE_KEYS,
     // Removed browser-profile store. Kept only as a serializer tombstone so the
     // first registry read can migrate it into this device's file and delete it.
     'browser',
@@ -947,6 +995,56 @@ function healMetaHeader(serialized) {
     // real central change). A current header round-trips to the identical bytes.
     return stripped === serialized ? serialized : META_HEADER + stripped;
 }
+/**
+ * True when the top-level `~/.agents/agents.yaml` carries a metadata header that
+ * is NOT the canonical {@link META_HEADER} — the P1 frozen-header case a box only
+ * heals on its next central write (serializeCentral). An absent or headerless
+ * file is NOT stale (a headerless central file is deliberately left alone).
+ * Surfaced as config drift by `agents sync status` (PHNX-3315).
+ */
+export function hasStaleMetaHeader() {
+    let content;
+    try {
+        content = fs.readFileSync(META_FILE, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    return healMetaHeader(content) !== content;
+}
+/**
+ * Parse the top-level user `agents.yaml` (this box's synced central file) WITHOUT
+ * the system-repo merge, machine-local overlay, or cache — the raw on-disk central
+ * map, or null when the file is absent/unparseable. Used by config-drift detection
+ * to see the central blocks that should have folded into the device doc, without
+ * mis-attributing a system-repo default as this box's own leak (PHNX-3315).
+ */
+export function readTopLevelUserMeta() {
+    let content;
+    try {
+        content = fs.readFileSync(META_FILE, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = yaml.parse(content);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch { /* malformed — nothing to report */ }
+    return null;
+}
+/**
+ * Top-level keys currently on disk in the central `agents.yaml` ({} when the file
+ * is absent or unparseable). The generic device-doc router uses this to leave a
+ * FOREIGN key — one this version does not model, already written to central by a
+ * newer CLI — in place instead of relocating it to this box's device doc.
+ */
+function readCentralKeys() {
+    return new Set(Object.keys(readTopLevelUserMeta() ?? {}));
+}
 /**
  * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
  * hand-written comments in the committed file.
@@ -1035,6 +1133,10 @@ function serializeCentral(central) {
  * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
  */
 export function writeMetaUnlocked(meta) {
+    // INVARIANT: every key destructured here must also be in BESPOKE_DEVICE_KEYS (and
+    // vice versa) — a bespoke device key that is classified but NOT pulled out here
+    // would fall into `central`, and the generic router skips it (BESPOKE_DEVICE_KEY_SET),
+    // so it would silently sync to the shared file. Keep the two lists in lockstep.
     const { agents, isolatedAgents, versions, deviceRoutines, deviceConfig, deviceBrowser, deviceFleet, deviceHosts, deviceAccounts, projectRoot, ...central } = meta;
     // Write the machine-local files FIRST, then strip central — so a crash mid-write
     // never removes pins/versions from central before they're persisted elsewhere.
@@ -1140,6 +1242,27 @@ export function writeMetaUnlocked(meta) {
         doc.projectRoot = projectRoot;
     else
         delete doc.projectRoot;
+    // Generic device-scoped keys (PHNX-3315): any key left in `central` that this
+    // version classifies as device but does NOT bespoke-route round-trips through
+    // this box's device doc under its OWN name — so a NEWLY DECLARED device-scoped
+    // key lands per-box BY DEFAULT, with no bespoke wiring, and never reaches the
+    // synced central file. Today the bespoke set covers every device key, so this
+    // loop moves nothing (behavior-identical). A key that is UNKNOWN to this version
+    // AND already present in the on-disk central file is a FOREIGN key a newer CLI
+    // wrote as central — left in `central` and preserved verbatim by serializeCentral
+    // (the fleet-wide config-loss guard), never relocated to this box's doc.
+    const centralRecord = central;
+    const onDiskCentralKeys = readCentralKeys();
+    for (const k of Object.keys(centralRecord)) {
+        if (metaKeyScope(k) !== 'device')
+            continue; // fleet-shared: stays central
+        if (BESPOKE_DEVICE_KEY_SET.has(k))
+            continue; // bespoke (incl. browser tombstone)
+        if (!KNOWN_META_KEYS.has(k) && onDiskCentralKeys.has(k))
+            continue; // foreign — preserve
+        doc[k] = centralRecord[k];
+        delete centralRecord[k];
+    }
     if (Object.keys(doc).length > 0) {
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
         writeIfChanged(devicePath, META_HEADER + yaml.stringify(doc));
@@ -1259,6 +1382,15 @@ function overlayMachineLocal(meta) {
                 }
                 meta.deviceRoutines = dm.routines;
             }
+            // Generic device-scoped keys (PHNX-3315): device-doc keys this overlay does
+            // NOT bespoke-handle map straight back onto Meta under their own name —
+            // symmetry with the generic write in writeMetaUnlocked. The bespoke sub-blocks
+            // are handled above and skipped, so a stock device doc surfaces nothing extra.
+            for (const [k, v] of Object.entries(dm)) {
+                if (BESPOKE_DEVICE_DOC_KEYS.has(k))
+                    continue;
+                meta[k] = v;
+            }
         }
     }
     const vrPath = getVersionResourcesPath();

package/dist/lib/sync-status.d.ts

@@ -20,6 +20,7 @@
  */
 import { AgentId } from './types.js';
 import { type DoctorKind } from './doctor-diff.js';
+import { type ConfigDrift } from './config-drift.js';
 /**
  * One stable status per resource, unified across every surface.
  *  - `synced`  — installed copy matches the resolved source (DiffStatus 'ok').
@@ -76,6 +77,9 @@ export interface UserRepoStatus {
 export interface UnifiedSyncStatus {
     system: SystemRepoStatus;
     user: UserRepoStatus;
+    /** Config drift: has this box drained its device-scoped state, or is it still
+     *  carrying per-box state in the shared top-level agents.yaml? (PHNX-3315) */
+    config: ConfigDrift;
     agents: AgentVersionStatus[];
     totals: {
         drifted: number;

package/dist/lib/sync-status.js

@@ -26,6 +26,7 @@ import { loadManifest } from './staleness/index.js';
 import { getSystemAgentsDir, getUserAgentsDir } from './state.js';
 import * as fs from 'fs';
 import { isGitRepo, readOriginUrl } from './git.js';
+import { detectConfigDrift } from './config-drift.js';
 const STATUS_MAP = {
     ok: 'synced',
     diff: 'drifted',
@@ -125,6 +126,7 @@ export async function computeSyncStatus(options = {}) {
     }
     const system = await getSystemRepoStatus();
     const user = await getUserRepoStatus();
+    const config = detectConfigDrift();
     const agentsNeedingSync = new Set();
     let drifted = 0, missing = 0, orphan = 0, versionsNeedingSync = 0, versionsNeverSynced = 0;
     for (const v of agents) {
@@ -141,6 +143,7 @@ export async function computeSyncStatus(options = {}) {
     return {
         system,
         user,
+        config,
         agents,
         totals: {
             drifted,

package/dist/lib/traces/classify.js

@@ -4,29 +4,34 @@ function normalizedEvidence(input) {
         .join(' ')
         .toLowerCase();
 }
+const TOPIC_RULES = [
+    { group: 'review', key: 'code-review', label: 'Code review',
+        text: /\b(review|audit|pr[-_/ ]?review|code[-_/ ]?review)\b/, tool: /review|comment/ },
+    { group: 'ops', key: 'release', label: 'Release',
+        text: /\b(release|deploy|publish|rollout|changelog)\b/ },
+    { group: 'research', key: 'debugging', label: 'Debugging',
+        text: /\b(debug|investigat|repro|root[-_ ]?cause|traceback|stack ?trace)\b/ },
+    { group: 'content', key: 'content', label: 'Blog & docs',
+        text: /\b(blog|docs?|documentation|readme|post|article|content|caption)\b/ },
+    { group: 'research', key: 'research', label: 'Research',
+        text: /\b(research|analysis|benchmark|paper|explore|spike)\b/, tool: /web_search|search_query|webfetch|browser/ },
+    { group: 'code', key: 'bugfix', label: 'Bug fixes',
+        text: /\b(fix|bug|hotfix|patch)\b/ },
+    { group: 'code', key: 'refactor', label: 'Refactor',
+        text: /\b(refactor|cleanup|clean[-_ ]?up|restructure|rename|tidy)\b/ },
+    { group: 'ops', key: 'operations', label: 'Fleet / ops',
+        text: /\b(fleet|ci|infra|daemon|provision|ops|pipeline)\b/, tool: /ssh|deploy|computer/ },
+    { group: 'code', key: 'feature', label: 'Feature work',
+        text: /\b(feat|feature|implement|add|build|code|test)\b/, tool: /edit|write|apply_patch|exec|bash|shell/ },
+];
 /** Classify a session from metadata and aggregate tool names; never reads transcript text. */
 export function classifyTopic(input) {
     const text = normalizedEvidence(input);
     const tools = Object.keys(input.toolMix ?? {}).map((tool) => tool.toLowerCase());
-    const hasTool = (pattern) => tools.some((tool) => pattern.test(tool));
-    if (/\b(review|audit|pr[-_/ ]?review|code[-_/ ]?review)\b/.test(text)
-        || hasTool(/review|comment/)) {
-        return { group: 'review', key: 'code-review', label: 'Code review' };
-    }
-    if (/\b(research|investigat|analysis|benchmark|paper|docs?)\b/.test(text)
-        || hasTool(/web_search|search_query|webfetch|browser/)) {
-        return { group: 'research', key: 'research', label: 'Research' };
-    }
-    if (/\b(blog|copy|content|post|article|script|caption)\b/.test(text)) {
-        return { group: 'content', key: 'content', label: 'Content' };
-    }
-    if (/\b(deploy|release|infra|ci|ops|fleet|daemon|provision)\b/.test(text)
-        || hasTool(/ssh|deploy|computer/)) {
-        return { group: 'ops', key: 'operations', label: 'Operations' };
-    }
-    if (/\b(test|fix|bug|feat|refactor|implement|code)\b/.test(text)
-        || hasTool(/edit|write|apply_patch|exec|bash|shell/)) {
-        return { group: 'code', key: 'engineering', label: 'Engineering' };
+    for (const rule of TOPIC_RULES) {
+        if ((rule.text && rule.text.test(text)) || (rule.tool && tools.some((tool) => rule.tool.test(tool)))) {
+            return { group: rule.group, key: rule.key, label: rule.label };
+        }
     }
     return { group: 'research', key: 'general', label: 'General' };
 }

package/dist/lib/usage-refresh.js

@@ -245,7 +245,8 @@ export async function buildLocalUsageAccounts() {
                 // fileOnly: never open the ACL-bound keychain item from the daemon —
                 // that path is the Touch ID storm. Usage reads the file-based setup-token
                 // only, never the interactive login (see loadClaudeOauth); no setup-token
-                // reads as "usage pending".
+                // reads as "usage unavailable (no usage credential)" — "usage pending"
+                // is now the cold-cache state only (#2987).
                 fetch: async () => {
                     const { getUsageInfoForIdentity } = await import('./accounting/usage.js');
                     return getUsageInfoForIdentity({

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

@@ -21,6 +21,13 @@ export interface ViewJsonVersion {
         amount: number;
         currency: string;
     } | null;
+    /**
+     * Human-readable reason a usage snapshot is absent: a live-refresh failure, or
+     * (without `--refresh`, on a never-cached account) a plain "not collected yet"
+     * pending state. Always a full sentence — never the internal `'stale'` cache
+     * sentinel, which `usageErrorForDisplay` normalizes away (PHNX-3348).
+     */
+    usageError?: string | null;
     windows: Array<{
         key: 'session' | 'week' | 'sonnet_week' | 'month';
         label?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.53",
+  "version": "1.22.55",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -86,8 +86,11 @@
     "@homebridge/node-pty-prebuilt-multiarch"
   ],
   "dependencies": {
+    "@fontsource/inter": "^5.3.0",
+    "@fontsource/jetbrains-mono": "^5.3.0",
     "@homebridge/node-pty-prebuilt-multiarch": "0.13.1",
     "@inquirer/prompts": "8.5.2",
+    "@resvg/resvg-wasm": "^2.6.2",
     "@types/proper-lockfile": "4.1.4",
     "@xterm/headless": "6.0.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
@@ -98,17 +101,20 @@
     "commander": "15.0.0",
     "croner": "10.0.1",
     "diff": "9.0.0",
+    "esbuild": "^0.28.2",
     "lru-cache": "11.5.2",
     "marked": "15.0.12",
     "marked-terminal": "7.3.0",
     "ora": "9.4.1",
     "proper-lockfile": "4.1.2",
+    "satori": "0.12.2",
     "shlex": "3.0.0",
     "simple-git": "3.36.0",
     "smol-toml": "1.7.0",
     "unbash": "4.0.5",
     "ws": "^8.21.0",
-    "yaml": "2.9.0"
+    "yaml": "2.9.0",
+    "yoga-wasm-web": "^0.3.3"
   },
   "devDependencies": {
     "@types/diff": "8.0.0",
@@ -116,6 +122,7 @@
     "@types/node": "26.1.0",
     "@types/ssh2": "1.15.5",
     "@types/ws": "^8.18.1",
+    "miniflare": "4.20260730.0",
     "ssh2": "1.17.0",
     "tsx": "4.23.0",
     "typescript": "6.0.3",