@phnx-labs/agents-cli 1.22.68 → 1.22.70

package/dist/commands/ssh.js

@@ -37,7 +37,7 @@ import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
 import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, deviceIdentityArgs, fleetDialTarget, isAgentsBrowserDrive, markFleetRemote, writeAskpassShim, } from '../lib/devices/connect.js';
 import { ensureManagedKnownHostsDir, isHostPinned } from '../lib/devices/known-hosts.js';
 import { shouldSyncTerminfo, syncTerminfoToDevice, terminfoHostKey } from '../lib/devices/terminfo.js';
-import { fanOutDevices, fleetHealthSkip, planFleetTargets, remoteFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
+import { fanOutDevices, fleetHealthSkip, planFleetTargets, remoteFleetTargets, runFleet, runOnDevice, runLocalCommand, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
 import { isRolloutSuccess, verifyFleetRollout, } from '../lib/devices/rollout-verify.js';
 import { fleetCapacity, fmtBytes, headroom, } from '../lib/devices/health.js';
 import { buildFleetHealthReport, renderFleetMatrix, renderFleetSummary, renderFleetWarnings, } from '../lib/devices/health-report.js';
@@ -61,6 +61,8 @@ import { runFleetLogin } from '../lib/fleet/remote-login.js';
 import { getConfigValue, listConfig, setConfigValue, unsetConfigValue, configKeySpec, autoPoolMode, configuredDeviceRole, listConfiguredDeviceRoles, setConfiguredDeviceRole, } from '../lib/device-config.js';
 import { filterAutoPool, listWorkerDevices } from '../lib/devices/pool.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
+import { isSelfHost } from '../lib/devices/self-host.js';
+import { collectHeldWorktrees, collectHeldWorktreesUnder, summarizeHeld, aggregateHeld, pushStrandedBranch, } from '../lib/worktree/held.js';
 /** One-line summary of a device for `list`. `isSelf` marks the machine this
  * command is running on so it stands out from the rest of the tailnet.
  * `isInteractive` marks the configured interactive host (`devices config <name> interactive.host`). */
@@ -1130,7 +1132,7 @@ function registerDevicesCommands(program) {
         { title: 'Inspect', names: ['list', 'show', 'status', 'ping', 'harnesses', 'accounts', 'snapshot'] },
         { title: 'Disposable devices', names: ['lease'] },
         { title: 'Configure a device', names: ['config', 'describe', 'render'] },
-        { title: 'Fleet operations', names: ['update', 'run', 'login', 'capture', 'apply'] },
+        { title: 'Fleet operations', names: ['update', 'run', 'login', 'capture', 'apply', 'worktrees'] },
     ]);
     devicesCmd
         .command('sync')
@@ -2363,6 +2365,207 @@ is reported \`failed\` (exit non-zero), never a stranded \`ok\`.
         .alias('kill')
         .description('Terminate a running dispatched task from this machine (SIGTERM the remote process group; marks it failed/143).')
         .action((id) => doDeviceTaskStop(id));
+    const worktreesCmd = devicesCmd
+        .command('worktrees')
+        .description("Surface the held set of agent worktrees the sweep only counts, broken into buckets: unmerged-commits (real stranded work), uncommitted-changes, undeterminable. Read-only; --push publishes stranded branches.")
+        .option('--json', 'emit the structured held set (device, repo, worktree, branch, reason, age, size) for machine callers / fleet aggregation')
+        .option('--home <dir>', 'search root to discover repos under (default: $HOME)')
+        .option('--repo <path>', 'scope to a single repo root instead of discovering')
+        .option('--bucket <name>', 'show only one bucket: unmerged-commits | uncommitted-changes | undeterminable')
+        .option('--fleet', 'fan out across every online device and aggregate the held set fleet-wide')
+        .option('--push', 'PUBLISH each unmerged-commits branch that is on no remote (the safe recovery action); never deletes')
+        .option('--yes', 'skip the confirmation prompt for --push')
+        .action((opts) => runWorktreesHeld(opts));
+    setHelpSections(worktreesCmd, {
+        examples: `
+      Inspect the residue:
+        agents fleet worktrees                       # this box, grouped by bucket
+        agents fleet worktrees --bucket unmerged-commits
+        agents fleet worktrees --json               # structured, for scripts
+
+      Fleet-wide:
+        agents fleet worktrees --fleet              # aggregate every online device
+        agents fleet run 'agents fleet worktrees --json'  # per-device composition
+
+      Recover stranded work (never deletes):
+        agents fleet worktrees --push               # publish on-no-remote branches
+    `,
+        notes: 'The nightly worktree-sweep (phnx-labs/.agents) reclaims merged worktrees and HOLDS the rest, reporting only a count. This surfaces that held set. unmerged-commits is the one that matters — a branch with commits on no remote is the PHNX-2951/PHNX-2732 stranded-work class; --push makes it visible. --push and --fleet are mutually exclusive (recovery is per-device on purpose).',
+    });
+}
+const BUCKET_ORDER = ['unmerged-commits', 'uncommitted-changes', 'undeterminable'];
+const BUCKET_LABEL = {
+    'unmerged-commits': 'unmerged-commits (stranded work — push or open a PR)',
+    'uncommitted-changes': 'uncommitted-changes (dirty tree — needs review)',
+    'undeterminable': 'undeterminable (broken/locked — re-examine)',
+};
+function isHeldBucket(v) {
+    return BUCKET_ORDER.includes(v);
+}
+function fmtWtSize(n) {
+    if (n < 0)
+        return '?';
+    if (n < 1024)
+        return `${n}B`;
+    const units = ['K', 'M', 'G', 'T'];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(v < 10 ? 1 : 0)}${units[i]}`;
+}
+/**
+ * `agents fleet worktrees` — surface the held set the sweep only counts. Never
+ * removes anything; `--push` publishes on-no-remote stranded branches. This is
+ * the CLI-native surfacing half of PHNX-3520 (the sweep itself lives in
+ * phnx-labs/.agents; it still emits a bare count until a sibling change teaches
+ * it to consume this).
+ */
+async function runWorktreesHeld(opts) {
+    if (opts.bucket && !isHeldBucket(opts.bucket)) {
+        console.error(chalk.red(`Unknown bucket '${opts.bucket}'. Use one of: ${BUCKET_ORDER.join(', ')}`));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.fleet && opts.push) {
+        console.error(chalk.red('--push and --fleet are mutually exclusive; run --push on the device that holds the work.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.fleet && opts.repo) {
+        console.error(chalk.red('--repo scopes a single local repo and cannot combine with --fleet; drop one. To scope on each device, run `agents fleet run \'agents fleet worktrees --repo <path> --json\'`.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.fleet) {
+        await runWorktreesHeldFleet(opts);
+        return;
+    }
+    const searchHome = opts.home ?? os.homedir();
+    const held = opts.repo
+        ? await collectHeldWorktrees(path.resolve(opts.repo))
+        : await collectHeldWorktreesUnder(searchHome);
+    if (opts.push) {
+        await runWorktreesPush(held, opts);
+        return;
+    }
+    const shown = opts.bucket ? held.filter((w) => w.bucket === opts.bucket) : held;
+    if (opts.json) {
+        console.log(JSON.stringify(shown, null, 2));
+        return;
+    }
+    const summary = summarizeHeld(shown);
+    if (summary.total === 0) {
+        console.log(chalk.green('No held worktrees — nothing stranded, dirty, or undeterminable.'));
+        return;
+    }
+    for (const bucket of BUCKET_ORDER) {
+        const items = summary.buckets[bucket];
+        if (items.length === 0)
+            continue;
+        const color = bucket === 'unmerged-commits' ? chalk.yellow : chalk.gray;
+        console.log('\n' + color(chalk.bold(`${BUCKET_LABEL[bucket]} — ${items.length}`)));
+        for (const w of items.sort((a, b) => b.unmergedCommits - a.unmergedCommits)) {
+            const detail = bucket === 'unmerged-commits'
+                ? `${w.unmergedCommits} commit${w.unmergedCommits === 1 ? '' : 's'}, ${w.hasRemoteBranch ? 'on remote' : chalk.red('NO remote')}`
+                : bucket === 'uncommitted-changes'
+                    ? `${w.dirtyFiles} dirty file${w.dirtyFiles === 1 ? '' : 's'}`
+                    : w.reason;
+            console.log(`  ${chalk.cyan(w.repoName + '/' + w.name).padEnd(48)} ${chalk.gray((w.branch ?? 'detached').padEnd(28))} ${detail}  ${chalk.dim(`${w.ageDays}d · ${fmtWtSize(w.sizeBytes)}`)}`);
+        }
+    }
+    const stranded = summary.buckets['unmerged-commits'].filter((w) => !w.hasRemoteBranch).length;
+    if (stranded > 0) {
+        console.log('\n' + chalk.yellow(`${stranded} branch${stranded === 1 ? '' : 'es'} with unmerged commits on no remote. Recover: agents fleet worktrees --push`));
+    }
+}
+/** `--push`: publish every on-no-remote stranded branch. Never deletes. */
+async function runWorktreesPush(held, opts) {
+    const candidates = held.filter((w) => w.bucket === 'unmerged-commits' && !w.hasRemoteBranch && w.branch);
+    if (candidates.length === 0) {
+        console.log(chalk.green('No stranded branches to publish (nothing with unmerged commits on no remote).'));
+        return;
+    }
+    if (isInteractiveTerminal() && !opts.yes) {
+        console.log(chalk.yellow(`About to push ${candidates.length} stranded branch${candidates.length === 1 ? '' : 'es'} to origin:`));
+        for (const w of candidates)
+            console.log(`  ${chalk.cyan(w.repoName + '/' + w.name)} → ${w.branch}`);
+        const { confirm } = await import('@inquirer/prompts');
+        const go = await confirm({ message: 'Push these branches?', default: true }).catch(() => false);
+        if (!go) {
+            console.log(chalk.gray('Cancelled — nothing pushed.'));
+            return;
+        }
+    }
+    let pushed = 0;
+    for (const w of candidates) {
+        const res = await pushStrandedBranch(w.repo, w);
+        if (res.pushed) {
+            pushed++;
+            console.log(chalk.green(`  pushed ${w.repoName}/${w.name} (${res.branch})`));
+        }
+        else {
+            console.log(chalk.yellow(`  skipped ${w.repoName}/${w.name}: ${res.reason}`));
+        }
+    }
+    console.log('\n' + chalk.green(`Published ${pushed}/${candidates.length} stranded branch${candidates.length === 1 ? '' : 'es'}.`));
+}
+/** `--fleet`: run this same read-only surface on every online device, aggregate. */
+async function runWorktreesHeldFleet(opts) {
+    const reg = await loadDevices();
+    const targets = planFleetTargets(reg);
+    const online = targets.filter((t) => !t.skip);
+    if (online.length === 0) {
+        console.log(chalk.gray("No online devices. Run 'agents devices sync' first."));
+        return;
+    }
+    const self = machineId();
+    const remoteCmd = ['agents', 'fleet', 'worktrees', '--json'];
+    if (opts.home)
+        remoteCmd.push('--home', opts.home);
+    const perDevice = [];
+    for (const t of online) {
+        const name = t.device.name;
+        const isSelf = name === self || isSelfHost(name);
+        const res = isSelf ? runLocalCommand(remoteCmd) : runOnDevice(t.device, remoteCmd);
+        if (res.code !== 0) {
+            console.error(chalk.gray(`  ${name}: ${(res.stderr || 'failed').trim().slice(0, 120)}`));
+            continue;
+        }
+        try {
+            perDevice.push({ device: name, held: JSON.parse(res.stdout) });
+        }
+        catch {
+            console.error(chalk.gray(`  ${name}: unparseable output (older CLI?)`));
+        }
+    }
+    // Apply the bucket filter to the per-device inputs BEFORE aggregating, so
+    // `total`, per-`devices` totals, and `buckets` all describe the same filtered
+    // set — zeroing buckets after the sum leaves `total` counting rows the output
+    // no longer lists.
+    const scoped = opts.bucket
+        ? perDevice.map((d) => ({ device: d.device, held: d.held.filter((w) => w.bucket === opts.bucket) }))
+        : perDevice;
+    const agg = aggregateHeld(scoped);
+    if (opts.json) {
+        console.log(JSON.stringify(agg, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`Held worktrees across ${perDevice.length} device(s): ${agg.total}`));
+    for (const bucket of BUCKET_ORDER) {
+        const items = agg.buckets[bucket];
+        if (items.length === 0)
+            continue;
+        const color = bucket === 'unmerged-commits' ? chalk.yellow : chalk.gray;
+        console.log('\n' + color(chalk.bold(`${BUCKET_LABEL[bucket]} — ${items.length}`)));
+        for (const w of items) {
+            const dev = w.device ?? '?';
+            const detail = bucket === 'unmerged-commits' ? `${w.unmergedCommits} commits, ${w.hasRemoteBranch ? 'on remote' : chalk.red('NO remote')}` : w.reason;
+            console.log(`  ${chalk.magenta(dev.padEnd(14))} ${chalk.cyan((w.repoName + '/' + w.name).padEnd(40))} ${chalk.gray((w.branch ?? 'detached').padEnd(24))} ${detail}`);
+        }
+    }
 }
 /**
  * `agents devices ps` — list tasks dispatched to devices (`agents run --device

package/dist/commands/traces.js

@@ -182,7 +182,7 @@ export function registerTracesCommands(program) {
         .description("Sync this device's derived, redacted trajectories to your Phoenix account");
     const setupCmd = tracesCmd
         .command('setup')
-        .description('Provision the private Cloudflare Worker and R2 bucket for traces')
+        .description('(advanced) Provision a self-hosted Cloudflare Worker + R2 bucket for traces — NOT required; `agents auth login` syncs to the managed endpoint with zero setup')
         .option('--bundle <name>', 'secrets bundle holding the Cloudflare API token', DEFAULT_CF_BUNDLE)
         .option('--worker <name>', 'Worker name', DEFAULT_WORKER_NAME)
         .option('--bucket <name>', 'R2 bucket name', DEFAULT_BUCKET_NAME)

package/dist/lib/account-capabilities.js

@@ -35,10 +35,8 @@ export const NATIVE_ACCOUNT_CAPABILITIES = {
     copilot: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
     openclaw: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
     amp: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
-    kiro: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
     goose: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
     hermes: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
-    pi: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
     warp: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
 };
 export function nativeAccountCapability(agent) {

package/dist/lib/account-registry.d.ts

@@ -54,12 +54,12 @@ export declare function listNativeAccounts(meta: Pick<Meta, 'accounts' | 'device
  * running before the body, so callers that only need a native lookup must be
  * able to omit it.
  */
-export declare function findUnifiedAccount(nameOrId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, doc?: AccountRegistryDocument): UnifiedAccount | null;
+export declare function findUnifiedAccount(nameOrId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, doc?: AccountRegistryDocument, preferAgent?: AgentId): UnifiedAccount | null;
 export declare function addNativeAccount(name: string, agent: AgentId, identityKey: string, identityLabel: string | undefined, scope: 'version' | 'device'): NativeAccount;
 /** Create or replace the version-independent label for one native identity. */
 export declare function labelNativeAccount(agent: AgentId, identityKey: string, identityLabel: string | undefined, label: string | undefined, scope: 'version' | 'device'): NativeAccount;
-export declare function bindAccount(nameOrId: string, target: string): UnifiedAccount;
-export declare function unbindAccount(nameOrId: string, target: string): void;
+export declare function bindAccount(nameOrId: string, target: string, preferAgent?: AgentId): UnifiedAccount;
+export declare function unbindAccount(nameOrId: string, target: string, preferAgent?: AgentId): void;
 /** Every target bound to `accountId`: this box's device-doc bindings merged over
  * the fleet-shared central bindings (PHNX-3315). */
 export declare function accountBindings(accountId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): string[];

package/dist/lib/account-registry.js

@@ -159,9 +159,18 @@ export function listNativeAccounts(meta) {
  * running before the body, so callers that only need a native lookup must be
  * able to omit it.
  */
-export function findUnifiedAccount(nameOrId, meta, doc) {
+export function findUnifiedAccount(nameOrId, meta, doc, preferAgent) {
     const needle = nameOrId.toLowerCase();
-    const native = listNativeAccounts(meta).find(account => account.id === nameOrId || account.name.toLowerCase() === needle || account.identityLabel?.toLowerCase() === needle);
+    const matches = listNativeAccounts(meta).filter(account => account.id === nameOrId || account.name.toLowerCase() === needle || account.identityLabel?.toLowerCase() === needle);
+    // `identityLabel` defaults to the login's own identifier (the email), so ONE
+    // selector legitimately matches several harnesses: `muqsitnawaz@gmail.com` is a
+    // claude login AND a codex login. Un-scoped, `.find()` returned whichever row the
+    // merged store happened to order first, so `agents run claude#<email>` died with
+    // "Account 'personal' is a codex login and cannot authenticate the claude harness"
+    // while that identity's own claude login sat right there. Prefer the harness being
+    // launched; fall back to the first match so a management lookup with no harness in
+    // hand (rename/remove/view) behaves exactly as before.
+    const native = matches.find(account => account.agent === preferAgent) ?? matches[0];
     if (native)
         return native;
     const provider = findAccount(nameOrId, doc ?? readAccountRegistry());
@@ -253,9 +262,13 @@ export function labelNativeAccount(agent, identityKey, identityLabel, label, sco
     });
     return { ...matches[0], name: resolvedLabel, identityLabel, scope: rowScope };
 }
-export function bindAccount(nameOrId, target) {
+export function bindAccount(nameOrId, target, preferAgent) {
     const meta = readMeta();
-    const account = findUnifiedAccount(nameOrId, meta);
+    // Scope to the harness being bound to: a bare identity selector matches every
+    // harness it is signed into, so without this the binding could persist against
+    // a different harness's row than the caller validated (the attach command
+    // resolves `targetAgent` and passes it here).
+    const account = findUnifiedAccount(nameOrId, meta, undefined, preferAgent);
     if (!account)
         throw new Error(`Unknown account '${nameOrId}'.`);
     // A binding follows its account: one that targets a device-scoped native login
@@ -275,9 +288,11 @@ export function bindAccount(nameOrId, target) {
     }
     return account;
 }
-export function unbindAccount(nameOrId, target) {
+export function unbindAccount(nameOrId, target, preferAgent) {
     const meta = readMeta();
-    const account = findUnifiedAccount(nameOrId, meta);
+    // Same scoping as bindAccount: detach the row on the harness the caller means,
+    // not whichever the store happened to order first for a colliding identity.
+    const account = findUnifiedAccount(nameOrId, meta, undefined, preferAgent);
     if (!account)
         throw new Error(`Unknown account '${nameOrId}'.`);
     const inCentral = meta.accounts?.bindings?.[target] === account.id;
@@ -527,7 +542,10 @@ export function resolveSpawnAccount(explicit, agent, version, meta, opts = {}) {
     const selection = resolveAccountSelection(explicit, agent, meta, { useDefault: opts.useDefault, target });
     if (!selection)
         return null;
-    const unified = findUnifiedAccount(selection.id, meta);
+    // Scope the lookup to the harness being launched: a bare identity selector
+    // (`claude#muqsitnawaz@gmail.com`) matches every harness that identity is signed
+    // into, and only this one can authenticate the spawn.
+    const unified = findUnifiedAccount(selection.id, meta, undefined, agent);
     if (!unified) {
         // A stale per-harness default is a preference, not a hard requirement: the
         // machine stays runnable by falling back to balanced rotation. Bindings and

package/dist/lib/accounting/usage.d.ts

@@ -180,8 +180,13 @@ export interface UsageSnapshot {
      * MUST NEVER read this field — `isUsageVerified`/`hasStaleUsage`/
      * `hasUsageAvailable`/`deriveUsageStatusFromSnapshot` consult only `windows`,
      * so a stale number rendered here can never make a stale account read as
-     * verified or eligible (the RUSH-2858 property). Never serialized to the
-     * on-disk cache or `--json` (both project `windows` explicitly).
+     * verified or eligible (the RUSH-2858 property). Not a serialized key of its
+     * own, and dropped from `--json` (which projects `windows` explicitly) — but
+     * the READINGS it holds do round-trip through the on-disk cache:
+     * `serializeClaudeUsageSnapshot` persists the union of `windows` and
+     * `staleWindows`, and `deserializeClaudeUsageSnapshot` re-runs the freshness
+     * gate on read to re-partition them (so a collector like Grok that pre-splits
+     * an ended-period reading onto `staleWindows` still survives the round-trip).
      */
     staleWindows?: UsageWindow[];
     plan?: string | null;

package/dist/lib/accounting/usage.js

@@ -1900,6 +1900,17 @@ function writeClaudeUsageCacheFile(cache, cachePath) {
 }
 /** Convert a live UsageSnapshot to its JSON-serializable cached form. */
 function serializeClaudeUsageSnapshot(snapshot) {
+    // Persist the union of fresh `windows` and last-known `staleWindows`.
+    // `deserializeClaudeUsageSnapshot` re-runs the freshness gate on read and
+    // re-partitions the serialized windows into fresh vs. stale, so what matters
+    // is that every last-known reading reaches disk. Claude's collector returns
+    // raw windows (no `staleWindows`) and relies on that read-side partition. But
+    // Grok's collector pre-partitions in the fetch, moving an ended-period reading
+    // onto `staleWindows` — serializing only `windows` dropped it, so the very
+    // number a daemon `--refresh` just captured was gone from the next cached
+    // `agents view grok`, which rendered the plan alone (no bar). Include the
+    // stale windows here so the round-trip preserves them for any collector.
+    const persistedWindows = [...snapshot.windows, ...(snapshot.staleWindows ?? [])];
     return {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
         plan: snapshot.plan ?? null,
@@ -1910,7 +1921,7 @@ function serializeClaudeUsageSnapshot(snapshot) {
                 resetsAt: snapshot.unavailable.resetsAt?.toISOString(),
             }
             : undefined,
-        windows: snapshot.windows.map((window) => ({
+        windows: persistedWindows.map((window) => ({
             key: window.key,
             label: window.label,
             shortLabel: window.shortLabel,
@@ -2400,17 +2411,131 @@ function safeStatSync(filePath) {
         return null;
     }
 }
+/**
+ * Resolve the Grok billing log to read usage from.
+ *
+ * `agents view grok` reads usage per INSTALLED VERSION, passing each version's
+ * isolated home (`~/.agents/.history/versions/grok/<ver>`). Grok writes
+ * `unified.jsonl` only to the shared real home `~/.grok/logs/unified.jsonl`
+ * even though GROK_HOME isolates auth/config/models per version. A per-version
+ * log, if one ever appears, still wins; otherwise we return the shared path
+ * marked `shared: true` so the caller can attribute it to at most one identity.
+ * Grok accounts are version-scoped (`NATIVE_ACCOUNT_CAPABILITIES.grok.scope ===
+ * 'version'`) — the shared file has no owner, so it must not be stamped onto
+ * every version home.
+ */
+function resolveGrokBillingLogPath(home) {
+    const rel = ['.grok', 'logs', 'unified.jsonl'];
+    const perVersion = path.join(home || os.homedir(), ...rel);
+    try {
+        if (fs.existsSync(perVersion))
+            return { logPath: perVersion, shared: false };
+    }
+    catch { /* unreadable */ }
+    // `AGENTS_REAL_HOME` is the seam every version-home consumer honors: a
+    // daemon/service-manager child's HOME can be baked to something other than
+    // the account's real home, so os.homedir() alone is not a reliable stand-in.
+    const shared = path.join(process.env.AGENTS_REAL_HOME || os.homedir(), ...rel);
+    if (shared !== perVersion) {
+        try {
+            if (fs.existsSync(shared))
+                return { logPath: shared, shared: true };
+        }
+        catch { /* unreadable */ }
+    }
+    return null;
+}
+/** This home's own `.grok/auth.json` only — never the shared-home fallback. */
+function readGrokAuthIdentity(home) {
+    const authPath = path.join(home, '.grok', 'auth.json');
+    try {
+        if (!fs.existsSync(authPath))
+            return null;
+        const data = JSON.parse(fs.readFileSync(authPath, 'utf-8'));
+        const records = (data && typeof data === 'object' ? [data, ...Object.values(data)] : [])
+            .filter((r) => !!r && typeof r === 'object' && !Array.isArray(r));
+        const account = records
+            .filter((r) => typeof r.refresh_token === 'string' || typeof r.email === 'string' || typeof r.user_id === 'string')
+            .sort((a, b) => String(b.create_time || '').localeCompare(String(a.create_time || '')))[0];
+        if (!account)
+            return null;
+        const userRaw = account.user_id ?? account.principal_id;
+        const userId = typeof userRaw === 'string' && userRaw.trim() ? userRaw.trim() : null;
+        const email = typeof account.email === 'string' && account.email.trim()
+            ? account.email.trim().toLowerCase()
+            : null;
+        if (!userId && !email)
+            return null;
+        return { userId, email };
+    }
+    catch {
+        return null;
+    }
+}
+function grokIdentitiesMatch(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.userId && b.userId)
+        return a.userId === b.userId;
+    if (a.email && b.email)
+        return a.email === b.email;
+    return false;
+}
+function grokIdentityFromBillingPayload(parsed) {
+    const ctx = parsed.ctx && typeof parsed.ctx === 'object' && !Array.isArray(parsed.ctx)
+        ? parsed.ctx
+        : null;
+    const config = ctx?.config && typeof ctx.config === 'object' && !Array.isArray(ctx.config)
+        ? ctx.config
+        : null;
+    const pick = (...cands) => {
+        for (const c of cands) {
+            if (typeof c === 'string' && c.trim())
+                return c.trim();
+        }
+        return null;
+    };
+    const userId = pick(ctx?.user_id, ctx?.userId, ctx?.principal_id, config?.user_id, parsed.user_id);
+    const emailRaw = pick(ctx?.email, config?.email, parsed.email);
+    if (!userId && !emailRaw)
+        return null;
+    return { userId, email: emailRaw ? emailRaw.toLowerCase() : null };
+}
+function sameHomePath(a, b) {
+    return (safeRealpathSync(a) ?? path.resolve(a)) === (safeRealpathSync(b) ?? path.resolve(b));
+}
+/**
+ * Whether the shared `~/.grok` billing log may be attached to this home.
+ * Grok logins are per version home; the shared last line is one account's
+ * meter. Fail loud: never copy it onto every installed identity.
+ */
+function sharedGrokLogAppliesToHome(home, match) {
+    const realHome = process.env.AGENTS_REAL_HOME || os.homedir();
+    const requestedHome = home || os.homedir();
+    const thisId = readGrokAuthIdentity(requestedHome);
+    if (match.identity) {
+        return grokIdentitiesMatch(match.identity, thisId);
+    }
+    // No identity on the line (the live Grok shape). Attribute the reading to
+    // exactly one canonical identity: the real home itself, or the version home
+    // whose own auth.json matches the shared `~/.grok/auth.json`.
+    if (sameHomePath(requestedHome, realHome))
+        return true;
+    return grokIdentitiesMatch(thisId, readGrokAuthIdentity(realHome));
+}
 /** Parse the latest billing info from Grok's unified log. */
 async function getGrokUsageInfo(options) {
     try {
-        const base = options?.home || os.homedir();
-        const logPath = path.join(base, '.grok', 'logs', 'unified.jsonl');
+        const resolved = resolveGrokBillingLogPath(options?.home);
         // No log yet: a benign "nothing recorded here", not a failure (RUSH-3040).
-        if (!fs.existsSync(logPath))
+        if (!resolved)
             return usageNoRecentUsageInfo();
-        const match = await readLatestGrokBilling(logPath);
+        const match = await readLatestGrokBilling(resolved.logPath);
         if (!match)
             return usageNoRecentUsageInfo();
+        if (resolved.shared && !sharedGrokLogAppliesToHome(options?.home, match)) {
+            return usageNoRecentUsageInfo();
+        }
         // Grok has no live usage API (`network: false`) — bars are last-seen from
         // this machine's unified.jsonl only. Drop windows whose billing period has
         // already ended so a stale 100% does not paint "rate-limited" after reset,
@@ -2703,10 +2828,16 @@ async function readLatestGrokBilling(filePath) {
                 return;
             try {
                 const parsed = JSON.parse(line);
-                if (parsed.msg === 'billing: fetched credits config' && parsed.ctx?.config) {
-                    const config = parsed.ctx.config;
+                const ctx = parsed.ctx && typeof parsed.ctx === 'object' && !Array.isArray(parsed.ctx)
+                    ? parsed.ctx
+                    : null;
+                if (parsed.msg === 'billing: fetched credits config' && ctx?.config) {
+                    const config = ctx.config;
                     const windows = [];
-                    if (config.currentPeriod?.end && typeof config.creditUsagePercent === 'number') {
+                    const currentPeriod = config.currentPeriod && typeof config.currentPeriod === 'object'
+                        ? config.currentPeriod
+                        : null;
+                    if (currentPeriod?.end && typeof config.creditUsagePercent === 'number') {
                         // `creditUsagePercent` is Grok's weekly credit consumption (0-100);
                         // the billing period's `end` is when that window resets.
                         // Do NOT coerce a missing percent to 0 — a new period often lands a
@@ -2718,14 +2849,15 @@ async function readLatestGrokBilling(filePath) {
                             label: 'Current week',
                             shortLabel: 'W',
                             usedPercent: Math.max(0, Math.min(100, rawPercent)),
-                            resetsAt: parseDateValue(config.currentPeriod.end),
+                            resetsAt: parseDateValue(currentPeriod.end),
                             windowMinutes: inferWindowMinutes('week'),
                         });
                     }
                     latest = {
                         capturedAt: parseDateValue(parsed.ts),
-                        subscriptionTier: parsed.ctx.subscriptionTier || null,
+                        subscriptionTier: typeof ctx.subscriptionTier === 'string' ? ctx.subscriptionTier : null,
                         windows,
+                        identity: grokIdentityFromBillingPayload(parsed),
                     };
                 }
             }

package/dist/lib/acp/client.d.ts

@@ -11,7 +11,7 @@
  */
 import { type SessionNotification } from '@zed-industries/agent-client-protocol';
 import type { AgentId } from '../types.js';
-import type { ExecMode } from '../exec.js';
+import { type ExecMode } from '../exec.js';
 export interface AcpRunOptions {
     agent: AgentId;
     prompt: string;

package/dist/lib/acp/client.js

@@ -15,6 +15,7 @@ import { promises as fs } from 'fs';
 import * as path from 'path';
 import { ClientSideConnection, ndJsonStream, } from '@zed-industries/agent-client-protocol';
 import { getAcpSpec, supportsAcp } from './harnesses.js';
+import { buildExecEnv } from '../exec.js';
 const PROTOCOL_VERSION = 1;
 /**
  * Runs a single prompt turn against an ACP-capable agent and streams updates
@@ -25,10 +26,20 @@ export async function runAcp(opts) {
         throw new Error(`Agent '${opts.agent}' does not support ACP. Use direct exec instead.`);
     }
     const spec = getAcpSpec(opts.agent);
+    // Build the harness's exec env the SAME way `agents run` does, instead of
+    // handing it a raw process.env. buildExecEnv is what injects the per-account
+    // `CLAUDE_CODE_OAUTH_TOKEN` on a worker device (gated by device role: a
+    // headed/personal box still defers to its native login). Without this, an ACP
+    // launch inherited no setup-token and fell through to the version home's
+    // copied native `.credentials.json` — which expires in ~15h and 401s once its
+    // refresh chain dies, exactly the "logged out on a worker" report (PHNX-3681).
+    // A verified precedence test shows the env token wins over a present
+    // `.credentials.json`, so injecting here is sufficient — the stale file no
+    // longer decides the session.
     const child = spawn(spec.command, spec.args, {
         cwd: opts.cwd,
         stdio: ['pipe', 'pipe', 'inherit'],
-        env: process.env,
+        env: buildExecEnv({ agent: opts.agent, cwd: opts.cwd, mode: opts.mode, effort: 'auto', interactive: true }),
     });
     const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
     const client = buildClient(opts);

package/dist/lib/acp/harnesses.js

@@ -52,7 +52,7 @@ export const ACP_HARNESSES = {
     },
     // antigravity: no documented ACP support (May 2026).
     // goose: ACP over HTTP via `goosed`, not a clean stdio subcommand.
-    // copilot, kiro: excluded for now (not installed in the reference environment,
+    // copilot: excluded for now (not installed in the reference environment,
     //                no local verification possible).
     // amp: not on the ACP agents list.
 };

package/dist/lib/add-dir.js

@@ -33,11 +33,9 @@ export const ADD_DIR_STRATEGY = {
     // No multi-root CLI surface today (single --dir / project path).
     opencode: 'none',
     gemini: 'none',
-    pi: 'none',
     openclaw: 'none',
     copilot: 'none',
     amp: 'none',
-    kiro: 'none',
     goose: 'none',
     antigravity: 'none',
     droid: 'none',

package/dist/lib/agent-cli-commands.js

@@ -14,11 +14,9 @@ export const AGENT_CLI_COMMANDS = [
     'gemini',
     'cursor-agent',
     'opencode',
-    'omp',
     'openclaw',
     'copilot',
     'amp',
-    'kiro-cli',
     'goose',
     'agy',
     'grok',

package/dist/lib/agent-spec/agents.d.ts

@@ -104,7 +104,7 @@ export declare const MANAGED_AGENT_IDS: AgentId[];
  * `curl … | sh` / `brew install` script that carries NO version token — the
  * installer can only ever fetch the *current* release, and the binary then keeps
  * itself up to date in place (droid, grok, antigravity, cursor, hermes,
- * kiro, goose). There is no semver to pin, so agents-cli must not model these as
+ * goose). There is no semver to pin, so agents-cli must not model these as
  * having multiple installable version-homes the way it does for npm-packaged
  * agents (claude, codex, kimi, …).
  *