@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/commands/setup-mine.d.ts

@@ -2,10 +2,11 @@
  * `agents setup mine` — interactive wizard to white-label the CLI under your own
  * name. Pick a name, choose which features to turn off, and get a personally-
  * named binary (e.g. `jack`) that runs every agents verb as yours. Delegates the
- * actual minting to `initBrand` (see mine.ts); the `agents mine` group manages
- * brands afterward.
+ * actual minting to `initBrand` (see mine.ts). Manage verbs (init/list/toggle/
+ * remove) live under the same `setup mine` command.
  *
  * Idempotent: re-running for an existing brand offers to re-mint it.
+ * Bare `agents setup mine` (no subcommand) runs the wizard.
  */
 import type { Command } from 'commander';
 /**
@@ -14,5 +15,8 @@ import type { Command } from 'commander';
  * relies on that.
  */
 export declare function runMineWizard(): Promise<boolean>;
-/** Register `agents setup mine` under the parent `setup` command. */
+/**
+ * Register `agents setup mine` under the parent `setup` command.
+ * Bare invocation runs the wizard; init/list/toggle/remove manage brands.
+ */
 export declare function registerSetupMineCommand(setupCmd: Command): void;

package/dist/commands/setup-mine.js

@@ -2,20 +2,21 @@
  * `agents setup mine` — interactive wizard to white-label the CLI under your own
  * name. Pick a name, choose which features to turn off, and get a personally-
  * named binary (e.g. `jack`) that runs every agents verb as yours. Delegates the
- * actual minting to `initBrand` (see mine.ts); the `agents mine` group manages
- * brands afterward.
+ * actual minting to `initBrand` (see mine.ts). Manage verbs (init/list/toggle/
+ * remove) live under the same `setup mine` command.
  *
  * Idempotent: re-running for an existing brand offers to re-mint it.
+ * Bare `agents setup mine` (no subcommand) runs the wizard.
  */
 import chalk from 'chalk';
-import { initBrand } from './mine.js';
+import { initBrand, registerMineManageCommands } from './mine.js';
 import { validateBrandName, getBrandConfig } from '../lib/brand.js';
 import { isShimsInPath } from '../lib/shims.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 /**
  * Optional/heavier top-level commands a brand commonly turns off. Kept short so
  * the checkbox is scannable — anything can still be toggled later with
- * `agents mine toggle <name> --disable <cmd>`.
+ * `agents setup mine toggle <name> --disable <cmd>`.
  */
 const DISABLEABLE_FEATURES = [
     { name: 'teams', hint: 'coordinate multiple agents on shared work' },
@@ -34,7 +35,7 @@ const DISABLEABLE_FEATURES = [
 export async function runMineWizard() {
     if (!isInteractiveTerminal()) {
         console.log(chalk.dim('Non-interactive shell. Create a brand directly, e.g.:\n') +
-            chalk.cyan('  agents mine init jack --disable teams cloud'));
+            chalk.cyan('  agents setup mine init jack --disable teams cloud'));
         return false;
     }
     const { input, checkbox, confirm } = await import('@inquirer/prompts');
@@ -79,14 +80,17 @@ function printNextSteps(name, pathWarning) {
     console.log(chalk.bold('\nTry it:'));
     console.log('  ' + chalk.cyan(`${name} --help`) + chalk.dim(`         # your CLI, your name`));
     console.log('  ' + chalk.cyan(`${name} run claude "hello"`));
-    console.log(chalk.dim(`  Manage it later:  agents mine toggle ${name} --disable <cmd>   ·   agents mine list`));
+    console.log(chalk.dim(`  Manage it later:  agents setup mine toggle ${name} --disable <cmd>   ·   agents setup mine list`));
     if (pathWarning) {
         console.log(chalk.yellow(`\n  note: the shims dir isn't on your PATH yet — run 'agents setup' or open a new shell.`));
     }
 }
-/** Register `agents setup mine` under the parent `setup` command. */
+/**
+ * Register `agents setup mine` under the parent `setup` command.
+ * Bare invocation runs the wizard; init/list/toggle/remove manage brands.
+ */
 export function registerSetupMineCommand(setupCmd) {
-    setupCmd
+    const mineCmd = setupCmd
         .command('mine')
         .description('White-label the CLI — mint your own personally-named binary (e.g. `jack`).')
         .action(async () => {
@@ -102,4 +106,5 @@ export function registerSetupMineCommand(setupCmd) {
             process.exitCode = 1;
         }
     });
+    registerMineManageCommands(mineCmd);
 }

package/dist/commands/setup-secrets.js

@@ -69,7 +69,7 @@ function printBackendNotes(backend) {
         console.log(chalk.gray('backend: file — encrypted at rest; headless reads need no passphrase by default, via a machine-local key at ~/.agents/.secrets-key/passphrase.'));
     }
     else {
-        console.log(chalk.gray('backend: vault — synced ~/.agents/vault.age storage; unlock it with agents login.'));
+        console.log(chalk.gray('backend: vault — synced ~/.agents/vault.age storage; unlock it with `agents secrets vault unlock`.'));
     }
 }
 function runAgentsSubcommand(args) {
@@ -138,7 +138,7 @@ async function resolveInteractiveChoices(opts) {
         choices: [
             { name: 'keychain — local OS keychain; reads may ask for Touch ID/device password', value: 'keychain' },
             { name: 'file — passphrase-encrypted file store for headless machines', value: 'file' },
-            { name: 'vault — synced ~/.agents/vault.age file; requires agents login', value: 'vault' },
+            { name: 'vault — synced ~/.agents/vault.age file; requires `agents secrets vault unlock`', value: 'vault' },
         ],
     });
     const policy = opts.policy ? parsePolicy(opts.policy) : await select({

package/dist/commands/setup-watchdog.js

@@ -10,7 +10,7 @@ export async function runWatchdogSetupWizard() {
     const devices = [...new Set([...Object.keys(registry), machineId()].map(normalizeHost))].sort();
     const enabled = new Set(devices.filter((device) => getConfigValue('watchdog.enabled', { device }).value === true));
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        requireInteractiveSelection('watchdog devices', ['agents watchdog on', 'agents watchdog on --host <device>']);
+        requireInteractiveSelection('watchdog devices', ['agents watchdog on', 'agents watchdog on --device <device>']);
     }
     try {
         const { checkbox } = await import('@inquirer/prompts');
@@ -25,7 +25,7 @@ export async function runWatchdogSetupWizard() {
                 setConfigValue('watchdog.enabled', on);
                 continue;
             }
-            const launch = getCliLaunch(['watchdog', on ? 'on' : 'off', '--host', device]);
+            const launch = getCliLaunch(['watchdog', on ? 'on' : 'off', '--device', device]);
             const result = spawnSync(launch.command, launch.args, { stdio: 'inherit', env: process.env });
             if ((result.status ?? 1) !== 0)
                 throw new Error(`Could not configure watchdog on ${device}`);

package/dist/commands/setup.js

@@ -15,7 +15,7 @@ import { getAgentsDir, getVersionsDir, ensureAgentsDir } from '../lib/state.js';
 import { isGitRepo, cloneIntoExisting, pullRepo } from '../lib/git.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
 import { AGENTS, agentConfigDirName, getUnmanagedAgentInstalls, countSessionFiles, agentLabel } from '../lib/agents.js';
-import { setGlobalDefault } from '../lib/versions.js';
+import { setGlobalDefault } from '../lib/installations/versions.js';
 import { ensureShimCurrent, switchHomeFileSymlinks, isShimsInPath, addShimsToPath, getPathSetupInstructions, assertIsolationBoundary } from '../lib/shims.js';
 import { setHelpSections } from '../lib/help.js';
 import { registerSetupBrowserCommand, runBrowserWizard } from './setup-browser.js';
@@ -137,7 +137,7 @@ export async function runSetup(program, options = {}) {
             : (await import('../lib/device-config.js')).isDaemonEnabled();
         if (enabled) {
             const start = options.startDaemonFn
-                ?? (await import('../lib/daemon.js')).startDaemon;
+                ?? (await import('../lib/daemon/daemon.js')).startDaemon;
             const started = start();
             if (started.method !== 'already-running' && started.pid) {
                 console.log(chalk.gray(`Started the always-on agents daemon (pid ${started.pid}).`));
@@ -150,6 +150,11 @@ export async function runSetup(program, options = {}) {
     // resolve to ok:false), so this can never block setup.
     const { runDeviceSync } = await import('../lib/devices/sync.js');
     const dev = await runDeviceSync({ soft: true });
+    if (dev.ok) {
+        const { setDeviceDiscoveryStatus } = await import('../lib/devices/discovery-policy.js');
+        for (const name of dev.syncedNames)
+            setDeviceDiscoveryStatus(name, 'approved');
+    }
     if (dev.ok && dev.synced > 0) {
         console.log(chalk.gray(`Discovered ${dev.synced} device${dev.synced === 1 ? '' : 's'} on your tailnet (agents devices list).`));
     }

package/dist/commands/share.d.ts

@@ -21,6 +21,24 @@ export interface ShareListItem {
     publishedAt: string;
     /** ISO auto-expire timestamp, or null for a permanent share. */
     expiresAt: string | null;
+    /** Human display title (explicit `--label` or auto-derived), or null for a
+     * share published before this field existed. */
+    label: string | null;
+    /** Harness/agent name that published this (`AGENTS_AGENT_NAME`), or null. */
+    agent: string | null;
+    /** Session id that published this, or null. */
+    session: string | null;
+    /** Hostname the publish ran from, or null. */
+    host: string | null;
+    /** git repo name at publish time, or null (published outside a git repo, or
+     * before this field existed). */
+    repo: string | null;
+    /** Count of retained prior versions under this slug (see `share revisions`). */
+    revisionCount: number;
+    /** Arbitrary `--meta key=value` entries attached at publish time (RUSH-2683)
+     * — everything that isn't a reserved provenance/label key. `{}` when none
+     * were set, or when the deployed Worker predates this field. */
+    meta: Record<string, string>;
 }
 export interface ShareListResult {
     /** The namespace listed. */
@@ -48,11 +66,58 @@ export declare function runShareList(opts?: {
     githubUser?: string;
     config?: ShareConfig;
     fetchListing?: ListingFetchFn;
+    /** Only shares published by this agent/harness (case-insensitive, exact). */
+    agent?: string;
+    /** Only shares published from this session id (exact). */
+    session?: string;
+    /** Only shares whose label contains this text (case-insensitive substring). */
+    label?: string;
 }): Promise<ShareListResult>;
 export declare function formatShareList(result: ShareListResult, json?: boolean): string;
+/** One retained prior version of a slug, as reported by the Worker's
+ * `?revisions=json` route. */
+export interface ShareRevisionItem {
+    /** R2 object key, `<user>/<slug>/rev-<ts>-<rand>`. */
+    key: string;
+    url: string;
+    size: number;
+    contentType: string | null;
+    /** ISO timestamp this version was replaced (when the copy was made). */
+    uploadedAt: string;
+    expiresAt: string | null;
+    label: string | null;
+    agent: string | null;
+    session: string | null;
+    host: string | null;
+    repo: string | null;
+    /** Arbitrary `--meta key=value` entries attached at publish time (RUSH-2683)
+     * — everything that isn't a reserved provenance/label key. `{}` when none
+     * were set, or when the deployed Worker predates this field. */
+    meta: Record<string, string>;
+}
+export interface ShareRevisionsResult {
+    /** The canonical `<user>/<slug>` key these are revisions of. */
+    key: string;
+    count: number;
+    revisions: ShareRevisionItem[];
+}
+/** Parse the Worker's `?revisions=json` payload, failing loud (with the same
+ * outdated-template hint as {@link parseShareListing}) on an unexpected shape. */
+export declare function parseShareRevisions(key: string, body: string): ShareRevisionsResult;
+/** 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 declare function runShareRevisions(target: string, opts?: {
+    githubUser?: string;
+    config?: ShareConfig;
+    fetchListing?: ListingFetchFn;
+}): Promise<ShareRevisionsResult>;
+export declare function formatShareRevisions(result: ShareRevisionsResult, json?: boolean): string;
 export declare function formatShareDeleteResult(result: DeleteShareResult, json?: boolean): string;
 interface ShareDeleteCliOpts {
     keepCover?: boolean;
+    keepRevisions?: boolean;
     ifExists?: boolean;
     githubUser?: string;
     json?: boolean;

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');