@phnx-labs/agents-cli 1.22.68 → 1.22.69

package/dist/commands/sessions-inject.js

@@ -13,14 +13,121 @@
  * `--pane`/`--pty` target a backend directly when the handle is already known.
  */
 import chalk from 'chalk';
-import { getActiveSessions } from '../lib/session/active.js';
+import { getActiveSessions, shortIdFromName } from '../lib/session/active.js';
 import { injectIntoTerminal, resolveInjectTargetForSession } from '../lib/terminal/index.js';
+import { sshExec, shellQuote } from '../lib/ssh-exec.js';
+import { resolveHost } from '../lib/hosts/registry.js';
+import { sshTargetFor } from '../lib/hosts/types.js';
 import { setHelpSections } from '../lib/help.js';
+/**
+ * Whether an active session is the one `sessions inject <token>` means. Matches
+ * a resolvable session id (exact or unique prefix) AND — for a tmux-hosted row
+ * whose full id never resolved (`sessionId` absent) — the `ag-<agent>-<shortid>`
+ * tmux name's `shortid` suffix (exact or prefix), the full tmux name, and the
+ * pane id. Those are the only selectors an id-less remote tmux row exposes, so
+ * without this an operator has no tool-native way to nudge it (PHNX-3688).
+ */
+export function matchInjectSelector(session, token) {
+    if (!token)
+        return false;
+    const sid = session.sessionId;
+    if (sid && (sid === token || sid.startsWith(token)))
+        return true;
+    const short = session.tmuxName ? shortIdFromName(session.tmuxName) : undefined;
+    if (short && (short === token || short.startsWith(token)))
+        return true;
+    if (session.tmuxName && session.tmuxName === token)
+        return true;
+    if (session.paneId && session.paneId === token)
+        return true;
+    return false;
+}
+/**
+ * The `--device` selector, normalized to a single host string. `optsWithGlobals()`
+ * merges the parent `sessions` command's variadic `-D, --device <target...>` over
+ * this subcommand's scalar `--device`, so a single `--device box` arrives as
+ * `['box']` — which flowed straight into `sshExec` and crashed on
+ * `host.startsWith` (PHNX-3688). Coerce the array to its one element; fail loud on
+ * several, since inject delivers to exactly one terminal (a fan-out spelling is a
+ * user error, not a first-of-list guess).
+ */
+export function normalizeInjectDevice(value) {
+    const list = value == null ? [] : Array.isArray(value) ? value : [value];
+    const hosts = list.map((v) => String(v).trim()).filter((v) => v.length > 0);
+    if (hosts.length === 0)
+        return undefined;
+    if (hosts.length > 1) {
+        throw new Error(`sessions inject targets a single device, but --device named ${hosts.length}: ${hosts.join(', ')}.`);
+    }
+    return hosts[0];
+}
+/**
+ * The `agents sessions inject` argv to re-run ON a device (its tmux panes live
+ * there, so resolution must happen there). Every flag rides along EXCEPT
+ * `--device`: the command runs on the device, resolving locally. Pure so the
+ * forwarded invocation is asserted without an SSH hop (PHNX-3688).
+ */
+export function buildRemoteInjectArgv(sessionId, text, options) {
+    const argv = ['agents', 'sessions', 'inject', sessionId, text];
+    if (options.enter === false)
+        argv.push('--no-enter');
+    if (options.combined)
+        argv.push('--combined');
+    if (options.socket)
+        argv.push('--socket', options.socket);
+    if (options.pty)
+        argv.push('--pty', options.pty);
+    if (options.pane)
+        argv.push('--pane', options.pane);
+    if (options.json)
+        argv.push('--json');
+    return argv;
+}
+/**
+ * Resolve `device` (registry alias or `user@host`) to an ssh target and re-run
+ * `agents sessions inject` there, so a bare session id + `--device` resolves on
+ * the box that actually holds the session's tmux panes. The tool-native form of
+ * the `agents ssh <device> "agents sessions inject <id> …"` workaround (PHNX-3688).
+ */
+/**
+ * Resolve `--device` to an ssh target. A registered device becomes its
+ * `user@dnsName`; a bare unknown name (an ad-hoc `user@host` or ssh_config alias)
+ * is handed to ssh verbatim (`resolveHost` returns null for it). A registered
+ * device we CANNOT dial — password-auth, addressless — throws its typed error and
+ * is NOT degraded to the raw name, which could ssh a coincidentally-matching but
+ * unrelated `~/.ssh/config` Host (PHNX-3688 review).
+ */
+export async function resolveInjectSshTarget(device) {
+    const host = await resolveHost(device);
+    return host ? sshTargetFor(host) : device;
+}
+async function injectOnDevice(sessionId, text, options, device) {
+    let target;
+    try {
+        target = await resolveInjectSshTarget(device);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (options.json)
+            console.log(JSON.stringify({ ok: false, error: message }));
+        else
+            console.error(chalk.red(message));
+        process.exit(1);
+    }
+    const remoteCmd = buildRemoteInjectArgv(sessionId, text, options).map(shellQuote).join(' ');
+    const res = sshExec(target, remoteCmd, { multiplex: true });
+    if (res.stdout)
+        process.stdout.write(res.stdout);
+    if (res.stderr)
+        process.stderr.write(res.stderr);
+    if (res.code !== 0)
+        process.exit(res.code ?? 1);
+}
 /** Resolve a session id (short or full) to an addressable terminal target, via the
  * same resolver the watchdog uses so both agree on what is reachable. */
 async function resolveTarget(sessionId) {
     const sessions = await getActiveSessions();
-    const match = sessions.find((s) => s.sessionId === sessionId || (s.sessionId != null && s.sessionId.startsWith(sessionId)));
+    const match = sessions.find((s) => matchInjectSelector(s, sessionId));
     if (!match)
         return { target: null, reason: `No active session matches "${sessionId}".` };
     const resolution = resolveInjectTargetForSession(match);
@@ -35,8 +142,21 @@ async function resolveTarget(sessionId) {
     return { target: resolution.target };
 }
 async function runInject(sessionId, text, options) {
+    let device;
+    try {
+        device = normalizeInjectDevice(options.device);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (options.json)
+            console.log(JSON.stringify({ ok: false, error: message }));
+        else
+            console.error(chalk.red(message));
+        process.exit(1);
+    }
     // Direct-target shortcuts skip the session lookup — the watchdog often already
-    // holds the pane id or pty session it wants to type into.
+    // holds the pane id or pty session it wants to type into. The pane's exact
+    // address is known, so it composes with --device (tmux send-keys over SSH).
     let target = null;
     if (options.pty) {
         target = { backend: 'pty', id: options.pty };
@@ -44,6 +164,12 @@ async function runInject(sessionId, text, options) {
     else if (options.pane) {
         target = { backend: 'tmux', pane: options.pane, socket: options.socket };
     }
+    else if (device) {
+        // A bare session id + a device: the session's tmux panes live ON that device,
+        // so getActiveSessions here can't see them. Resolve + deliver THERE by re-running
+        // inject over SSH (the same command, minus --device) — PHNX-3688.
+        return injectOnDevice(sessionId, text, options, device);
+    }
     else {
         const resolved = await resolveTarget(sessionId);
         if (!resolved.target) {
@@ -60,7 +186,7 @@ async function runInject(sessionId, text, options) {
         enter: options.enter !== false,
         combined: options.combined,
         socket: options.socket,
-        host: options.device,
+        host: device,
     });
     if (options.json) {
         console.log(JSON.stringify(res));
@@ -82,7 +208,7 @@ export function registerSessionsInjectCommand(sessionsCmd) {
         .option('--pane <id>', 'Target a tmux pane id directly (e.g. %3), skipping session lookup')
         .option('--pty <id>', 'Target an agents-pty session id directly, skipping session lookup')
         .option('--socket <path>', 'tmux socket path (defaults to the session/shared socket)')
-        .option('--device <target>', 'Deliver on a remote device over SSH (tmux/AppleScript backends)')
+        .option('--device <target>', 'Deliver on a remote device over SSH. With a bare session id, the session is resolved ON that device; with --pane, the pane is addressed there directly.')
         .option('--no-enter', 'Send only the text, without a trailing Enter')
         .option('--combined', 'Fuse text + Enter into ONE write (default: two writes, Ink-TUI safe)')
         .option('--json', 'Output the InjectResult as JSON');
@@ -96,6 +222,12 @@ export function registerSessionsInjectCommand(sessionsCmd) {
 
       # Type into an agents-pty session without submitting
       agents sessions inject _ "ls" --pty $SID --no-enter
+
+      # Nudge a live session on another box (resolved on the device)
+      agents sessions inject 214edaae "continue" --device yosemite-s0
+
+      # Address a known remote pane directly (skips lookup, sends over SSH)
+      agents sessions inject _ "continue" --pane %122 --socket $SOCK --device yosemite-s0
     `,
         notes: `
       - Ink-TUI Enter semantics: by default the text and Enter are two separate
@@ -103,8 +235,12 @@ export function registerSessionsInjectCommand(sessionsCmd) {
       - A session is addressable by id when it resolves to a precise split —
         tmux, iTerm, a VSCodium/Cursor/VS Code integrated terminal, or a pty
         (resolveInjectTargetForSession). Use --pane/--pty for direct targeting.
-      - Built on the Terminal Engine (src/lib/terminal): --device runs the tmux /
-        AppleScript spec over the same SSH transport the launch engine uses.
+      - The id may be the session id (short or full) OR the '<shortid>' suffix of
+        a tmux target (ag-<agent>-<shortid>) — the only selector a live tmux
+        session whose id column shows '-' exposes.
+      - Built on the Terminal Engine (src/lib/terminal): with --pane, --device
+        runs the tmux send-keys spec over SSH; with a bare id, --device re-runs
+        the lookup on that box (its tmux panes live there, not here).
     `,
     });
     // The parent `sessions` command also defines --json, so it binds there;

package/dist/commands/sessions-picker.js

@@ -104,6 +104,7 @@ function sanitizeMeta(s) {
         version: clean(s.version),
         account: clean(s.account),
         topic: clean(s.topic),
+        firstUserMessage: clean(s.firstUserMessage),
         label: clean(s.label),
         ticketId: clean(s.ticketId),
         prUrl: clean(s.prUrl),

package/dist/commands/share.js

@@ -11,11 +11,13 @@ import { Argument, Option } from 'commander';
 import chalk from 'chalk';
 import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, readWriteToken, readWriteTokenEnv, readWriteTokenFromBundle, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
 import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, putWorkerSecret, updateWorker, WORKER_PHOENIX_ID_BASE_SECRET, setWorkerSecret, } from '../lib/share/provision.js';
-import { publishFile, resolveShareUsername, parseMetaEntries, sanitizeLabel, resolveShareVisibility, scanShareContent, formatSensitiveContentError, unlistedNotPrivateWarning, SHARE_VISIBILITY_LEVELS, PUBLISH_VISIBILITY_LEVELS, } from '../lib/share/publish.js';
+import { publishFile, resolveShareUsername, parseMetaEntries, sanitizeLabel, scanShareContent, formatSensitiveContentError, unlistedNotPrivateWarning, SHARE_VISIBILITY_LEVELS, PUBLISH_VISIBILITY_LEVELS, } from '../lib/share/publish.js';
 import { deleteShare, resolveDeleteTarget } from '../lib/share/delete.js';
 import { renderWorkerBundle } from '../lib/share/worker-template.js';
 import { analyticsEnabled } from '../lib/share/analytics.js';
-import { phoenixIdBaseForDeploy, resolveShareBackend, } from '../lib/share/backend.js';
+import { extractShareHttpError, formatShareHttpErrorDetail } from '../lib/share/http-error.js';
+import { phoenixIdBaseForDeploy, resolveShareBackend, shouldUseManaged, } from '../lib/share/backend.js';
+import { publishVisibility } from '../lib/storage/visibility.js';
 import { resolveGitHubUsername } from '../lib/git.js';
 import { setHelpSections } from '../lib/help.js';
 import { showUrl } from '../lib/open-url.js';
@@ -245,7 +247,8 @@ export async function runShareList(opts = {}) {
         throw new Error(OUTDATED_TEMPLATE_HINT);
     }
     if (res.status !== 200) {
-        throw new Error(`Listing failed (${res.status}) for ${listUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
+        const detail = formatShareHttpErrorDetail(extractShareHttpError({ status: res.status, body: res.body }));
+        throw new Error(`Listing failed (${res.status}) for ${listUrl}${detail}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
     }
     if (!/application\/json/i.test(res.contentType)) {
         // A 200 that isn't JSON means the old Worker ignored ?format=json and served
@@ -389,7 +392,8 @@ export async function runShareRevisions(target, opts = {}) {
     const fetchListing = opts.fetchListing ?? defaultListingFetch;
     const res = await fetchListing(revUrl);
     if (res.status !== 200) {
-        throw new Error(`Revisions lookup failed (${res.status}) for ${revUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
+        const detail = formatShareHttpErrorDetail(extractShareHttpError({ status: res.status, body: res.body }));
+        throw new Error(`Revisions lookup failed (${res.status}) for ${revUrl}${detail}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
     }
     if (!/application\/json/i.test(res.contentType)) {
         if (backend.kind === 'managed') {
@@ -624,9 +628,8 @@ export function registerShareCommands(artifactsCmd) {
         .option('--slug <slug>', 'URL slug override (default: stable slug of the artifact title, then filename)')
         .option('--github-user <user>', 'GitHub username for the share namespace (default: resolved from gh/git config; ignored on the managed endpoint)')
         .option('--expire <spec>', "auto-expire (default 30d). e.g. 12h, 30d, 2026-08-01, or 'never'")
-        .addOption(new Option('--visibility <level>', 'public | unlisted | private | me | org (default public). unlisted is an UNAUTHENTICATED capability URL; private is token-gated (404 without the key); me/org require a Phoenix session. All but public are hidden from the gallery')
-        .choices([...PUBLISH_VISIBILITY_LEVELS])
-        .default('public'))
+        .addOption(new Option('--visibility <level>', 'public | unlisted | private | me | org. Default when signed in: me (owner-only, Phoenix-gated); use org for your whole email domain, public to opt into the gallery. unlisted is an UNAUTHENTICATED capability URL; private is token-gated (404 without the key). All but public are hidden from the gallery')
+        .choices([...PUBLISH_VISIBILITY_LEVELS]))
         .addOption(new Option('--protected', 'token-gated link (= --visibility private): the URL carries a secret key and returns 404 without it — the authenticated alternative to --unlisted'))
         .addOption(new Option('--unlisted', 'hidden alias of --visibility unlisted (obscurity, NOT authentication)').hideHelp())
         .addOption(new Option('--private', 'hidden alias of --visibility unlisted (obscurity, NOT authentication — for real read-auth use --protected)').hideHelp())
@@ -650,11 +653,16 @@ export function registerShareCommands(artifactsCmd) {
         }
         try {
             const meta = parseMetaEntries(opts.meta);
-            const visibility = resolveShareVisibility({
+            // Private by default: an explicit flag wins; otherwise the backend-aware
+            // product default — `me` (owner-only) when signed in to Phoenix, `public`
+            // for a BYO bucket (the Worker refuses `me`/`org` without a Phoenix owner).
+            // `shouldUseManaged` reads the same session/BYO signals `publishFile` will
+            // resolve, so the default matches the backend the publish actually uses.
+            const visibility = publishVisibility({
                 visibility: opts.visibility,
                 unlisted: opts.unlisted === true || opts.private === true,
                 protected: opts.protected === true,
-            });
+            }, shouldUseManaged({}) ? 'managed' : 'byo');
             // unlisted (incl. its --private alias) is obscurity, not read-auth — warn
             // loudly before the publish so a "private" link is never mistaken for a
             // gated one (PHNX-3654). Skipped for --json so machine output stays clean.
@@ -684,15 +692,25 @@ export function registerShareCommands(artifactsCmd) {
     });
     setHelpSections(shareCmd, {
         examples: `
-      # Signed in? Just publish — no Cloudflare setup (managed endpoint)
+      # Signed in? Just publish — no Cloudflare setup (managed endpoint).
+      # Default is private: an owner-only 'me' link, Phoenix-gated.
       agents auth login
       agents artifacts share ./out/plan.html
 
+      # Share with everyone at your email domain (no org setup — the domain is it)
+      agents artifacts share ./out/plan.html --visibility org
+
+      # Opt into the public gallery with an OG preview card
+      agents artifacts share ./out/landing.html --visibility public
+
       # Hide from the public gallery (direct URL still works, noindex) and expire sooner
       agents artifacts share ./out/report.html --visibility unlisted --expire 12h
 
+      # Token-gated link — GET returns 404 without the secret ?k= key
+      agents artifacts share ./out/secret.html --protected
+
       # Permanent public page (the slug is derived from its title)
-      agents artifacts share ./out/landing.html --expire never
+      agents artifacts share ./out/landing.html --visibility public --expire never
 
       # Optional slug override
       agents artifacts share ./out/report.html --slug q3-report --expire 7d
@@ -720,11 +738,21 @@ ${SHARE_DELETE_EXAMPLES}
   applies (setup / join). HTML is stored as one object: local images are inlined
   and Chrome-saved file:// TOC links become in-page hashes.
 
+  Private by default: signed in, a publish with no --visibility is 'me' —
+  owner-only, Phoenix-gated, not in the gallery. Pass --visibility org to share
+  with everyone at your email domain (no org to create — the domain is the whole
+  mechanism), or --visibility public to opt into the gallery with an OG card. A
+  BYO publish (no Phoenix session) still defaults to public, since me/org need a
+  Phoenix owner to gate on.
+
   Default expiry is 30d so an accidental publish decays. Pass --expire never for
   a permanent link. --visibility unlisted (hidden aliases: --unlisted / --private)
   hides the page from the public gallery and agents artifacts share list; the
   direct URL is still world-readable (unlisted, not secret) and GET sends
-  X-Robots-Tag: noindex. --visibility me requires a Phoenix session and is only
+  X-Robots-Tag: noindex. --protected (= --visibility private) is token-gated
+  read-auth: the published URL carries a secret ?k= key (Authorization: Bearer
+  is accepted too) and GET returns 404 without it — treat the whole link as a
+  secret. --visibility me requires a Phoenix session and is only
   visible to the signed-in owner; --visibility org requires the same and is
   visible to members of the same Phoenix organization. A pre-publish scan
   refuses emails and credential-shaped strings unless --force is passed.
@@ -956,7 +984,7 @@ Prefer to change visibility without a browser? Use 'agents artifacts share visib
         .addOption(new Option('--scope <level>', 'visibility filter: public (default), unlisted, private, me, org, or all')
         .choices(['public', 'unlisted', 'private', 'me', 'org', 'all'])
         .default('public'))
-        .option('--all', "list every page including hidden unlisted/me/org shares (alias for --scope all)")
+        .option('--all', "list every page including hidden unlisted/private/me/org shares (alias for --scope all)")
         .option('--agent <name>', 'filter to shares published by this agent/harness (case-insensitive)')
         .option('--session <id>', 'filter to shares published from this session id')
         // Named --label-contains, not --label: `share <file>` (the parent) already owns
@@ -988,10 +1016,11 @@ Prefer to change visibility without a browser? Use 'agents artifacts share visib
       # Everything you've published, newest first
       agents artifacts share list
 
-      # Include your hidden pages (unlisted / me / org) so you can see everything
+      # Include your hidden pages (unlisted / private / me / org) so you can see everything
       agents artifacts share list --all
       agents artifacts share list --scope me
       agents artifacts share list --scope unlisted
+      agents artifacts share list --scope private
 
       # Machine-readable — e.g. pull every still-public URL with jq
       agents artifacts share list --list-json | jq -r '.objects[].url'

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/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;