@phnx-labs/agents-cli 1.22.66 → 1.22.69

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, SHARE_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';
@@ -37,7 +39,11 @@ export function formatSharePublishResult(result, json = false) {
         lines.push(chalk.dim('  expires never'));
     const visibility = result.visibility ?? (result.unlisted ? 'unlisted' : 'public');
     if (visibility === 'unlisted') {
-        lines.push(chalk.dim('  visibility: unlisted (noindex, hidden from gallery)'));
+        lines.push(chalk.dim('  visibility: unlisted (noindex, hidden from gallery — NOT authenticated)'));
+    }
+    else if (visibility === 'private') {
+        lines.push(chalk.dim('  visibility: private (token-gated — 404 without the key; hidden from gallery)'));
+        lines.push(chalk.yellow('  the key is in the URL above (?k=…) — treat the whole link as a secret'));
     }
     else if (visibility === 'me' || visibility === 'org') {
         lines.push(chalk.dim(`  visibility: ${visibility} (login required, hidden from gallery)`));
@@ -57,6 +63,14 @@ export function shareTemplateStatus(cfg) {
     return cfg.templateHash === hashWorkerScript(renderWorkerBundle().script) ? 'current' : 'outdated';
 }
 export async function runShareEdit(target, opts) {
+    // Token-gated `private` can't be set in place: the metadata-edit route carries
+    // no viewer token, so re-stamping visibility=private alone would leave the page
+    // gated by a hash that doesn't exist — inaccessible to everyone (PHNX-3654).
+    // Fail loud pointing at the publish path, which mints the key.
+    if (opts.visibility === 'private') {
+        throw new Error("Can't change a page to 'private' in place — a token-gated link needs a fresh viewer key. " +
+            "Re-publish it with 'agents artifacts share <file> --protected' instead.");
+    }
     // Same public-listing gate as publish: label + every metadata value are
     // world-readable in the gallery and `share list --list-json`.
     if (opts.force !== true) {
@@ -158,7 +172,10 @@ export function parseShareListing(user, body) {
             host: item.host == null ? null : String(item.host),
             repo: item.repo == null ? null : String(item.repo),
             revisionCount: typeof item.revisionCount === 'number' ? item.revisionCount : 0,
-            visibility: item.visibility === 'unlisted' || item.visibility === 'me' || item.visibility === 'org'
+            visibility: item.visibility === 'unlisted' ||
+                item.visibility === 'private' ||
+                item.visibility === 'me' ||
+                item.visibility === 'org'
                 ? item.visibility
                 : 'public',
             meta: parseMetaField(item.meta),
@@ -230,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
@@ -374,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') {
@@ -609,11 +628,11 @@ 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 | me | org (default public). unlisted is a capability URL; me/org require a Phoenix session and are hidden from the gallery')
-        .choices(['public', 'unlisted', 'me', 'org'])
-        .default('public'))
-        .addOption(new Option('--unlisted', 'hidden alias of --visibility unlisted').hideHelp())
-        .addOption(new Option('--private', 'hidden alias of --visibility unlisted').hideHelp())
+        .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())
         .option('--force', 'publish even when the file contains emails or credential-shaped strings')
         .option('--no-cover', 'skip the OG preview image (HTML pages get one by default)')
         .option('--no-analytics', 'skip injecting the Cloudflare Web Analytics beacon')
@@ -634,16 +653,29 @@ 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.
+            if (visibility === 'unlisted' && !opts.json) {
+                console.error(chalk.yellow(`⚠ ${unlistedNotPrivateWarning()}`));
+            }
             const result = await publishFile(file, {
                 slug: opts.slug,
                 githubUser: opts.githubUser,
                 expire: opts.expire,
                 visibility,
                 unlisted: visibility === 'unlisted',
+                protected: visibility === 'private',
                 force: opts.force,
                 cover: opts.cover,
                 analytics: opts.analytics,
@@ -660,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
@@ -696,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.
@@ -929,10 +981,10 @@ Prefer to change visibility without a browser? Use 'agents artifacts share visib
         // so the listing filter is named `--scope` here; `--all` is the convenience
         // alias for `--scope all`.
         .option('--for-user <user>', 'GitHub username whose namespace to list (default: resolved from gh/git config)')
-        .addOption(new Option('--scope <level>', 'visibility filter: public (default), unlisted, me, org, or all')
-        .choices(['public', 'unlisted', 'me', 'org', 'all'])
+        .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
@@ -964,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/account-pool-collect.d.ts

@@ -25,10 +25,12 @@ export declare function foldRegistryCandidates(agent: AgentId, inputs: RunCandid
  * provider can authenticate `agent` and whose credential is present locally
  * (RUSH-3182). This is what makes a setup-token / API-key account balance-eligible.
  *
- * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path
- * ONLY — the other consumers of {@link collectRunCandidates} (watchdog, session
- * recovery, teams placement) keep calling it directly and are unaffected. The
- * existing {@link pickBalancedCandidate} selects over the combined list, so the
+ * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path,
+ * and used by session recovery (`resolveSessionRecovery`, PHNX-3626) so an
+ * origin-account limit can rotate to a healthy provider account and stay NATIVE.
+ * The other consumers of {@link collectRunCandidates} (watchdog, teams
+ * placement) keep calling it directly and are unaffected. The existing
+ * {@link pickBalancedCandidate} selects over the combined list, so the
  * revoked / rate-limit / exhausted logic is unchanged.
  */
 export declare function collectRunCandidatesForRun(agent: AgentId): Promise<RotateCandidate[]>;

package/dist/lib/accounting/account-pool-collect.js

@@ -63,10 +63,12 @@ export function foldRegistryCandidates(agent, inputs) {
  * provider can authenticate `agent` and whose credential is present locally
  * (RUSH-3182). This is what makes a setup-token / API-key account balance-eligible.
  *
- * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path
- * ONLY — the other consumers of {@link collectRunCandidates} (watchdog, session
- * recovery, teams placement) keep calling it directly and are unaffected. The
- * existing {@link pickBalancedCandidate} selects over the combined list, so the
+ * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path,
+ * and used by session recovery (`resolveSessionRecovery`, PHNX-3626) so an
+ * origin-account limit can rotate to a healthy provider account and stay NATIVE.
+ * The other consumers of {@link collectRunCandidates} (watchdog, teams
+ * placement) keep calling it directly and are unaffected. The existing
+ * {@link pickBalancedCandidate} selects over the combined list, so the
  * revoked / rate-limit / exhausted logic is unchanged.
  */
 export async function collectRunCandidatesForRun(agent) {

package/dist/lib/accounting/usage-ingest.js

@@ -1,7 +1,7 @@
 /**
  * The `agents __usage-ingest` receiver (PHNX-3392 usage-sync).
  *
- * A headed peer's daemon pipes a {@link UsageSyncPayload} JSON envelope to our
+ * A legacy headed peer may pipe a {@link UsageSyncPayload} JSON envelope to our
  * stdin; we merge its identity-keyed rows into the local usage cache newest-wins
  * ({@link ingestPeerClaudeUsageRows}). Hidden internal verb — intercepted in
  * index.ts before bootstrap, so it never triggers an update check or a detached
@@ -12,7 +12,9 @@
  * accepting a wrong shape, but a busy cache lock degrades to best-effort inside
  * `ingestPeerClaudeUsageRows` like every other cache writer.
  *
- * The payload arrives on stdin, EXCEPT on a Windows receiver: the `agents.ps1`
+ * New daemon ticks use the fleet-shared store instead. This compatibility
+ * receiver remains for older installed versions. The payload arrives on stdin,
+ * EXCEPT on a Windows receiver: the `agents.ps1`
  * shim does not forward ssh-piped stdin to the node process, so the pusher writes
  * the payload to a temp file and passes `agents __usage-ingest --from <path>`
  * (the same workaround the secrets push uses — `buildWindowsStdinImportCommand`).