@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/commands/share.js

@@ -5,11 +5,12 @@
 // provisioning door lives beside it at `agents artifacts setup`
 // (commands/artifacts-setup.ts), which calls `runShareProvision` below.
 import { existsSync } from 'node:fs';
+import { formatBytes } from '../lib/format.js';
 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, updateWorker, setWorkerSecret, } from '../lib/share/provision.js';
-import { publishFile, resolveShareUsername } from '../lib/share/publish.js';
-import { deleteShare } from '../lib/share/delete.js';
+import { publishFile, resolveShareUsername, parseMetaEntries } from '../lib/share/publish.js';
+import { deleteShare, resolveDeleteTarget } from '../lib/share/delete.js';
 import { renderWorkerScript } from '../lib/share/worker-template.js';
 import { analyticsEnabled } from '../lib/share/analytics.js';
 import { resolveGitHubUsername } from '../lib/git.js';
@@ -18,6 +19,10 @@ export function formatSharePublishResult(result, json = false) {
     if (json)
         return JSON.stringify(result, null, 2);
     const lines = [chalk.green(result.url)];
+    if (result.label) {
+        const hint = result.labelSource === 'derived' ? chalk.dim(' (derived — pass --label to set one)') : '';
+        lines.push(chalk.dim(`  "${result.label}"`) + hint);
+    }
     if (result.coverUrl)
         lines.push(chalk.dim(`  cover ${result.coverUrl}`));
     if (result.expiresAt)
@@ -47,6 +52,18 @@ async function defaultListingFetch(url) {
     const res = await fetch(url, { headers: { accept: 'application/json' } });
     return { status: res.status, contentType: res.headers.get('content-type') ?? '', body: await res.text() };
 }
+/** Normalize the Worker's `meta` field (arbitrary `--meta key=value` entries,
+ * RUSH-2683) into a plain string record — `{}` for a missing/malformed field
+ * (a deployed Worker that predates it, or a non-object value), never throws. */
+function parseMetaField(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        out[k] = String(v);
+    }
+    return out;
+}
 /** Parse the Worker's listing JSON into a validated result, failing loud (with the
  * outdated-template hint) on any body that isn't the expected shape — an old Worker
  * serves the HTML gallery for a non-empty namespace, which must not be silently
@@ -72,6 +89,13 @@ export function parseShareListing(user, body) {
             contentType: item.contentType == null ? null : String(item.contentType),
             publishedAt: String(item.publishedAt ?? ''),
             expiresAt: item.expiresAt == null ? null : String(item.expiresAt),
+            label: item.label == null ? null : String(item.label),
+            agent: item.agent == null ? null : String(item.agent),
+            session: item.session == null ? null : String(item.session),
+            host: item.host == null ? null : String(item.host),
+            repo: item.repo == null ? null : String(item.repo),
+            revisionCount: typeof item.revisionCount === 'number' ? item.revisionCount : 0,
+            meta: parseMetaField(item.meta),
         };
     });
     return { user, count: objects.length, objects };
@@ -118,20 +142,38 @@ export async function runShareList(opts = {}) {
         // the HTML gallery — the deployed template is outdated.
         throw new Error(OUTDATED_TEMPLATE_HINT);
     }
-    return parseShareListing(user, res.body);
+    const parsed = parseShareListing(user, res.body);
+    return applyShareListFilters(parsed, opts);
+}
+/** Client-side filtering over an already-fetched listing (RUSH-2683) — the
+ * Worker has no query surface for this, so it narrows the fetched set instead
+ * of a second round trip. `count` reflects the FILTERED set, matching what the
+ * caller actually sees. */
+function applyShareListFilters(result, filters) {
+    let objects = result.objects;
+    if (filters.agent) {
+        const needle = filters.agent.toLowerCase();
+        objects = objects.filter((o) => (o.agent ?? '').toLowerCase() === needle);
+    }
+    if (filters.session) {
+        objects = objects.filter((o) => o.session === filters.session);
+    }
+    if (filters.label) {
+        const needle = filters.label.toLowerCase();
+        objects = objects.filter((o) => (o.label ?? '').toLowerCase().includes(needle));
+    }
+    return { user: result.user, count: objects.length, objects };
 }
 /** Human-readable bytes, e.g. `1.2 KB`, `640 B`. */
-function formatBytes(n) {
-    if (n < 1024)
-        return `${n} B`;
-    const units = ['KB', 'MB', 'GB'];
-    let value = n / 1024;
-    let unit = 0;
-    while (value >= 1024 && unit < units.length - 1) {
-        value /= 1024;
-        unit++;
-    }
-    return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+/** Render an arbitrary `--meta` map as `k=v k2=v2` for a human table row, or
+ * undefined when there's nothing to show (RUSH-2683). */
+function formatMetaPairs(meta) {
+    if (!meta)
+        return undefined;
+    const entries = Object.entries(meta);
+    if (entries.length === 0)
+        return undefined;
+    return entries.map(([k, v]) => `${k}=${v}`).join(' ');
 }
 export function formatShareList(result, json = false) {
     if (json)
@@ -143,8 +185,97 @@ export function formatShareList(result, json = false) {
         chalk.dim(`  ${result.count} published ${result.count === 1 ? 'page' : 'pages'}`);
     const rows = result.objects.map((o) => {
         const when = o.publishedAt ? o.publishedAt.slice(0, 10) : 'unknown';
-        const meta = `${when} · ${formatBytes(o.size)}${o.expiresAt ? ` · expires ${o.expiresAt.slice(0, 10)}` : ''}`;
-        return `${chalk.cyan(o.slug)}  ${chalk.dim(meta)}\n  ${chalk.green(o.url)}`;
+        const bits = [when, formatBytes(o.size)];
+        if (o.agent)
+            bits.push(o.agent);
+        if (o.revisionCount > 0)
+            bits.push(`${o.revisionCount} ${o.revisionCount === 1 ? 'revision' : 'revisions'}`);
+        if (o.expiresAt)
+            bits.push(`expires ${o.expiresAt.slice(0, 10)}`);
+        const metaPairs = formatMetaPairs(o.meta);
+        if (metaPairs)
+            bits.push(metaPairs);
+        const line = bits.join(' · ');
+        const title = o.label ? `${chalk.bold(o.label)}\n  ` : '';
+        return `${title}${chalk.cyan(o.slug)}  ${chalk.dim(line)}\n  ${chalk.green(o.url)}`;
+    });
+    return [header, ...rows].join('\n');
+}
+/** Parse the Worker's `?revisions=json` payload, failing loud (with the same
+ * outdated-template hint as {@link parseShareListing}) on an unexpected shape. */
+export function parseShareRevisions(key, body) {
+    let data;
+    try {
+        data = JSON.parse(body);
+    }
+    catch {
+        throw new Error(OUTDATED_TEMPLATE_HINT);
+    }
+    const revisionsRaw = data?.revisions;
+    if (!data || typeof data !== 'object' || !Array.isArray(revisionsRaw)) {
+        throw new Error(OUTDATED_TEMPLATE_HINT);
+    }
+    const revisions = revisionsRaw.map((o) => {
+        const item = o;
+        return {
+            key: String(item.key ?? ''),
+            url: String(item.url ?? ''),
+            size: typeof item.size === 'number' ? item.size : 0,
+            contentType: item.contentType == null ? null : String(item.contentType),
+            uploadedAt: String(item.uploadedAt ?? ''),
+            expiresAt: item.expiresAt == null ? null : String(item.expiresAt),
+            label: item.label == null ? null : String(item.label),
+            agent: item.agent == null ? null : String(item.agent),
+            session: item.session == null ? null : String(item.session),
+            host: item.host == null ? null : String(item.host),
+            repo: item.repo == null ? null : String(item.repo),
+            meta: parseMetaField(item.meta),
+        };
+    });
+    return { key, count: revisions.length, revisions };
+}
+/** Fetch and parse the retained prior versions of one published slug. `target`
+ * accepts the same three forms as `agents unshare` (a full URL, `<user>/<slug>`,
+ * or a bare slug resolved against the caller's own namespace) — reuses
+ * {@link resolveDeleteTarget} rather than re-deriving the key. */
+export async function runShareRevisions(target, opts = {}) {
+    const cfg = opts.config ?? readShareConfig();
+    if (!cfg) {
+        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
+    }
+    const templateStatus = shareTemplateStatus(cfg);
+    if (templateStatus === 'outdated') {
+        throw new Error(OUTDATED_TEMPLATE_HINT);
+    }
+    const { key } = await resolveDeleteTarget(target, { githubUser: opts.githubUser });
+    const revUrl = `${cfg.baseUrl.replace(/\/+$/, '')}/${key}?revisions=json`;
+    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' completed.`);
+    }
+    if (!/application\/json/i.test(res.contentType)) {
+        throw new Error(OUTDATED_TEMPLATE_HINT);
+    }
+    return parseShareRevisions(key, res.body);
+}
+export function formatShareRevisions(result, json = false) {
+    if (json)
+        return JSON.stringify(result, null, 2);
+    if (result.count === 0) {
+        return chalk.dim(`No retained revisions for ${result.key} (only the current version exists).`);
+    }
+    const header = chalk.bold(result.key) + chalk.dim(`  ${result.count} retained ${result.count === 1 ? 'revision' : 'revisions'}`);
+    const rows = result.revisions.map((r) => {
+        const bits = [r.uploadedAt ? r.uploadedAt.slice(0, 10) : 'unknown', formatBytes(r.size)];
+        if (r.agent)
+            bits.push(r.agent);
+        if (r.label)
+            bits.push(r.label);
+        const metaPairs = formatMetaPairs(r.meta);
+        if (metaPairs)
+            bits.push(metaPairs);
+        return `${chalk.cyan(r.uploadedAt || r.key)}  ${chalk.dim(bits.join(' · '))}\n  ${chalk.green(r.url)}`;
     });
     return [header, ...rows].join('\n');
 }
@@ -159,6 +290,9 @@ export function formatShareDeleteResult(result, json = false) {
             ? chalk.dim(`  cover deleted ${result.cover.url}`)
             : chalk.dim(`  cover (none) ${result.cover.url}`));
     }
+    if (result.revisions?.length) {
+        lines.push(chalk.dim(`  ${result.revisions.length} retained ${result.revisions.length === 1 ? 'revision' : 'revisions'} deleted`));
+    }
     return lines.join('\n');
 }
 /** Shared handler for `agents artifacts share delete <targets...>` and the
@@ -175,6 +309,7 @@ export async function runShareDelete(targets, opts, deleteFn = deleteShare) {
         try {
             const result = await deleteFn(target, {
                 keepCover: opts.keepCover === true,
+                keepRevisions: opts.keepRevisions === true,
                 ifExists: opts.ifExists === true,
                 githubUser: opts.githubUser,
             });
@@ -198,12 +333,13 @@ export async function runShareDelete(targets, opts, deleteFn = deleteShare) {
 function registerShareDeleteOptions(cmd) {
     return cmd
         .option('--keep-cover', 'leave the sibling <slug>.png OG cover in place (default: delete it too)')
+        .option('--keep-revisions', 'leave retained revisions (<slug>/rev-*) in place (default: delete them too)')
         .option('--if-exists', 'treat an already-missing target as a no-op success instead of an error')
         .option('--github-user <user>', 'GitHub username for resolving a bare-slug target (default: resolved from gh/git config)')
         .option('--json', 'emit machine-readable results');
 }
 const SHARE_DELETE_EXAMPLES = `
-      # Delete by full URL — also takes down the sibling OG cover
+      # Delete by full URL — also takes down the sibling OG cover and any retained revisions
       agents artifacts share delete https://share.agents-cli.sh/octocat/my-plan-a1b2
 
       # Delete by <user>/<slug>, or a bare slug in your own namespace
@@ -216,6 +352,9 @@ const SHARE_DELETE_EXAMPLES = `
       # Keep the cover image up (rare — you usually want both gone)
       agents unshare my-plan-a1b2 --keep-cover
 
+      # Keep retained revisions up too (rare — they're world-readable by URL like the page itself)
+      agents unshare my-plan-a1b2 --keep-revisions
+
       # Don't error if it's already gone
       agents unshare my-plan-a1b2 --if-exists
 `;
@@ -224,6 +363,12 @@ const SHARE_DELETE_NOTES = `
   Worker's DELETE is idempotent and returns {"ok":true} even for a key that was
   never there, so that response alone is never proof of a takedown.
 
+  Also deletes any retained revisions of the target (RUSH-2683) — a share that was
+  republished at least once leaves its prior version(s) live at their own URL until
+  they're purged too, so leaving them up would defeat the point of taking the page
+  down. Pass --keep-revisions to leave them (they still expire via the bucket's
+  lifecycle rule on their own schedule either way).
+
   agents artifacts share delete === agents unshare (same command, different name).
 `;
 /**
@@ -245,6 +390,10 @@ export function registerShareCommands(artifactsCmd) {
         .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')
+        .option('--label <text>', 'human display title, shown in the gallery and `share list` (default: derived from the HTML <title>, frontmatter title, or filename)')
+        .option('--title <text>', 'alias of --label')
+        .option('--meta <key=value>', 'structured metadata (repeatable), e.g. --meta kind=plan --meta ticket=RUSH-2683. Recommended keys: kind (plan|report|visual|screenshot|recording|deck|doc), project, ticket, status (draft|final). Reserved (set automatically, not settable): agent, session, host, repo, date, label', (val, prev) => [...prev, val], [])
+        .option('--no-revision', "overwrite an existing slug in place — skip keeping the prior version as a <slug>/rev-<ts> backup (default: keep it, see 'agents artifacts share revisions')")
         .option('--json', 'emit machine-readable publish result for plan-render hooks and scripts')
         .action(async (file, opts) => {
         if (!file) {
@@ -257,6 +406,7 @@ export function registerShareCommands(artifactsCmd) {
             return;
         }
         try {
+            const meta = parseMetaEntries(opts.meta);
             const result = await publishFile(file, {
                 slug: opts.slug,
                 githubUser: opts.githubUser,
@@ -265,6 +415,9 @@ export function registerShareCommands(artifactsCmd) {
                 force: opts.force,
                 cover: opts.cover,
                 analytics: opts.analytics,
+                label: opts.label ?? opts.title,
+                meta,
+                noRevision: opts.revision === false,
             });
             console.log(formatSharePublishResult(result, Boolean(opts.json)));
         }
@@ -286,6 +439,12 @@ export function registerShareCommands(artifactsCmd) {
 
       # Custom slug, expiring in 7 days
       agents artifacts share ./out/report.html --slug q3-report --expire 7d
+
+      # Human title + structured metadata, shown in the gallery and share list
+      agents artifacts share ./out/plan.html --label "Q3 fleet plan" --meta kind=plan --meta ticket=RUSH-2683
+
+      # Republish without keeping the previous version as a revision
+      agents artifacts share ./out/plan.html --slug q3-report --no-revision
 ${SHARE_DELETE_EXAMPLES}
       # One-time setup (or join an existing endpoint)
       agents artifacts setup
@@ -300,6 +459,13 @@ ${SHARE_DELETE_EXAMPLES}
   and agents artifacts share list; the direct URL is still world-readable
   (unlisted, not secret). A pre-publish scan refuses emails and credential-shaped
   strings unless --force is passed.
+
+  Every publish carries provenance auto-captured from the exec env/git/clock
+  (agent, session, host, repo, date) — never invented, only sent when present —
+  plus a label (explicit --label/--title, else derived from the HTML <title>,
+  frontmatter title, or filename; never blocks on a prompt) and any --meta
+  key=value pairs. Republishing an existing slug keeps the prior version as a
+  retained revision by default; see 'agents artifacts share revisions'.
 ${SHARE_DELETE_NOTES}
     `,
     });
@@ -391,10 +557,25 @@ ${SHARE_DELETE_NOTES}
         .command('list')
         .description("List the pages you've published to your share namespace (human table; --json for scripts).")
         .option('--github-user <user>', 'GitHub username whose namespace to list (default: resolved from gh/git config)')
-        .option('--json', 'emit the machine-readable listing (slug, url, size, contentType, publishedAt, expiresAt)')
+        .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
+        // `--label`/`--title`, and commander's argv scanner resolves an option name
+        // against the WHOLE ancestor chain, not per-command — a same-named child option
+        // is silently dropped (verified; see RUSH-2683 PR notes). Fixing that properly
+        // needs `enablePositionalOptions()` on the root program, a CLI-wide change out
+        // of scope here (a pre-existing instance of it already affects --json/
+        // --github-user on list/update/delete — tracked as a follow-up).
+        .option('--label-contains <substr>', 'filter to shares whose label contains this text (case-insensitive)')
+        .option('--json', 'emit the machine-readable listing (slug, url, size, contentType, publishedAt, expiresAt, label, agent, session, host, repo, revisionCount, meta)')
         .action(async (opts) => {
         try {
-            const result = await runShareList({ githubUser: opts.githubUser });
+            const result = await runShareList({
+                githubUser: opts.githubUser,
+                agent: opts.agent,
+                session: opts.session,
+                label: opts.labelContains,
+            });
             console.log(formatShareList(result, Boolean(opts.json)));
         }
         catch (e) {
@@ -412,6 +593,10 @@ ${SHARE_DELETE_NOTES}
 
       # List another namespace
       agents artifacts share list --github-user octocat
+
+      # Narrow by who/what published it
+      agents artifacts share list --agent claude
+      agents artifacts share list --label-contains "fleet plan"
     `,
         notes: `
   Lists the ACTIVE pages in your namespace — expired links and the sibling .png OG
@@ -420,6 +605,54 @@ ${SHARE_DELETE_NOTES}
   Worker predates this feature the command says so and points you at 'agents
   artifacts share update' (RUSH-2449) rather than returning a wrong or empty result
   — see 'agents artifacts share status' for whether an update is due.
+
+  --agent/--session/--label-contains filter the fetched listing client-side; --json's
+  count reflects the filtered set.
+    `,
+    });
+    const shareRevisionsCmd = shareCmd
+        .command('revisions <target>')
+        .description('Show the retained prior versions of a published slug, newest first (human table; --revisions-json for scripts).')
+        // Named --for-user / --revisions-json, not --github-user / --json: `share
+        // <file>` (the parent) already owns both those long names, and commander's
+        // argv scanner resolves an option name against the WHOLE ancestor chain —
+        // a same-named child option is silently dropped even when it parses alone
+        // (verified with a real program.parseAsync(), see share.test.ts). Unlike
+        // `list`'s pre-existing --json/--github-user collision (RUSH-2687, left
+        // as a tracked follow-up because it predates this diff), `revisions` is
+        // brand-new here, so it gets non-colliding names from the start instead
+        // of shipping a silently-broken flag.
+        .option('--for-user <user>', 'GitHub username for resolving a bare-slug target (default: resolved from gh/git config)')
+        .option('--revisions-json', 'emit the machine-readable revision list')
+        .action(async (target, opts) => {
+        try {
+            const result = await runShareRevisions(target, { githubUser: opts.forUser });
+            console.log(formatShareRevisions(result, Boolean(opts.revisionsJson)));
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exitCode = 1;
+        }
+    });
+    setHelpSections(shareRevisionsCmd, {
+        examples: `
+      # Prior versions kept under this slug (bare slug — your own namespace)
+      agents artifacts share revisions q3-report
+
+      # By <user>/<slug> or full URL, same target forms as 'agents unshare'
+      agents artifacts share revisions octocat/q3-report
+      agents artifacts share revisions https://share.agents-cli.sh/octocat/q3-report
+
+      # Machine-readable, and a bare slug resolved against another namespace
+      agents artifacts share revisions q3-report --revisions-json
+      agents artifacts share revisions q3-report --for-user octocat
+    `,
+        notes: `
+  A revision is created automatically on every republish of an existing slug
+  (pass --no-revision at publish time to skip it) — this is history, never
+  shown on the public gallery or in 'agents artifacts share list' beyond its
+  count. Each revision's own URL is still directly reachable and honors its own
+  recorded expiry.
     `,
     });
     shareCmd
@@ -521,7 +754,7 @@ export async function runShareProvision(opts) {
         storeWriteToken(token);
         console.log(chalk.green(`\nShare endpoint ready → ${chalk.bold(baseUrl)}`));
         console.log(chalk.dim('Publish with:  ') + chalk.cyan('agents artifacts share <file>'));
-        console.log(chalk.dim(`Fleet: push the token with 'agents secrets export share --host <box>' and pull config with 'agents repo pull'.`));
+        console.log(chalk.dim(`Fleet: push the token with 'agents secrets export share --device <box>' and pull config with 'agents repo pull'.`));
     }
     catch (e) {
         spin.fail('Provisioning failed');

package/dist/commands/skills.js

@@ -7,8 +7,8 @@ import { select, checkbox } from '@inquirer/prompts';
 import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
-import { discoverSkillsFromRepo, installSkillCentrally, listInstalledSkills, listInstalledSkillsWithScope, getSkillInfo, getSkillRules, getSkillsDir, countSkillFiles, tryParseSkillMetadata, diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/skills.js';
-import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
+import { discoverSkillsFromRepo, installSkillCentrally, listInstalledSkills, listInstalledSkillsWithScope, getSkillInfo, getSkillRules, getSkillsDir, countSkillFiles, tryParseSkillMetadata, diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/plugins/skills.js';
+import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/installations/versions.js';
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, promptRemovalTargets, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
@@ -180,7 +180,7 @@ Examples:
                     const skillMdPath = path.join(localPath, 'SKILL.md');
                     if (fs.existsSync(skillMdPath)) {
                         const skillName = path.basename(localPath);
-                        const { validateSkillMetadata, countSkillRules } = await import('../lib/skills.js');
+                        const { validateSkillMetadata, countSkillRules } = await import('../lib/plugins/skills.js');
                         const parseResult = tryParseSkillMetadata(localPath);
                         const validation = validateSkillMetadata(parseResult.metadata, skillName);
                         // Warn if YAML is invalid

package/dist/commands/snapshot.d.ts

@@ -1,5 +1,5 @@
 /**
- * `agents snapshot` — one-process consumer snapshot for pollers.
+ * `agents devices snapshot` — one-process consumer snapshot for pollers.
  *
  * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
  * fork storm with a single command. Does NOT replace `agents status`, which
@@ -8,4 +8,4 @@
  * JSON shape: {@link FleetSnapshot} in `lib/snapshot.ts` (version: 1).
  */
 import type { Command } from 'commander';
-export declare function registerSnapshotCommand(program: Command): void;
+export declare function registerSnapshotCommand(devicesCmd: Command): void;

package/dist/commands/snapshot.js

@@ -1,5 +1,5 @@
 /**
- * `agents snapshot` — one-process consumer snapshot for pollers.
+ * `agents devices snapshot` — one-process consumer snapshot for pollers.
  *
  * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
  * fork storm with a single command. Does NOT replace `agents status`, which
@@ -59,11 +59,11 @@ function renderHuman(snap) {
                 : 'system ok';
         console.log(`  ${'Sync'.padEnd(12)} ${sys} · ${need} version${need === 1 ? '' : 's'} need sync`);
     }
-    console.log(chalk.gray('\n  Machine-readable: agents snapshot --json\n' +
+    console.log(chalk.gray('\n  Machine-readable: agents devices snapshot --json\n' +
         '  Sync-only (unchanged): agents status --json'));
 }
-export function registerSnapshotCommand(program) {
-    const cmd = addHostOption(program
+export function registerSnapshotCommand(devicesCmd) {
+    const cmd = addHostOption(devicesCmd
         .command('snapshot')
         .description('One-process poll snapshot: install inventory + active sessions (optional feed/sync). Not the sync-status command — use `agents status` for drift.'))
         .option('--json', 'Emit the machine-readable FleetSnapshot contract (version 1)')
@@ -74,19 +74,19 @@ export function registerSnapshotCommand(program) {
     setHelpSections(cmd, {
         examples: `
       # One-shot inventory + local active sessions (JSON)
-      agents snapshot --json
+      agents devices snapshot --json
 
       # Same, plus open feed blocks for needs-you polls
-      agents snapshot --json --with-feed
+      agents devices snapshot --json --with-feed
 
       # Fleet-wide active sessions (matches sessions --active scope)
-      agents snapshot --json --all-hosts
+      agents devices snapshot --json --all-hosts
 
       # Inventory for one harness only (an AGI EXT-style usage poll)
-      agents snapshot --json --agent claude
+      agents devices snapshot --json --agent claude
 
       # Run the whole snapshot on another device
-      agents snapshot --json --host yosemite-s0
+      agents devices snapshot --json --device yosemite-s0
     `,
     });
     cmd.action(async (opts, command) => {

package/dist/commands/ssh.d.ts

@@ -7,7 +7,7 @@
  * (offline → fail fast instead of a 2-minute hang), platform-aware exec
  * (PowerShell on Windows), and password-from-bundle auth via an askpass shim.
  * Rendering the registry to an ssh_config include also lets plain ssh / scp /
- * rsync / `agents sessions --host` resolve the same logical names.
+ * rsync / `agents sessions --device` resolve the same logical names.
  */
 import type { Command } from 'commander';
 import { type FanOutDeviceTarget } from '../lib/devices/fleet.js';