@phnx-labs/agents-cli 1.22.53 → 1.22.54

package/dist/commands/share.d.ts

@@ -1,7 +1,7 @@
 import { type Command } from 'commander';
 import { type ShareConfig } from '../lib/share/config.js';
 import { type CloudflareRequester } from '../lib/share/provision.js';
-import { type PublishResult } from '../lib/share/publish.js';
+import { type PublishResult, type ShareVisibility } from '../lib/share/publish.js';
 import { deleteShare, type DeleteShareResult } from '../lib/share/delete.js';
 import type { PhoenixSession } from '../lib/identity/client.js';
 export declare function formatSharePublishResult(result: PublishResult, json?: boolean): string;
@@ -36,6 +36,9 @@ export interface ShareListItem {
     repo: string | null;
     /** Count of retained prior versions under this slug (see `share revisions`). */
     revisionCount: number;
+    /** The visibility stamped at publish time: public | unlisted | me | org.
+     * Missing on Workers that predate this field → treated as public. */
+    visibility: ShareVisibility;
     /** 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. */
@@ -47,12 +50,41 @@ export interface ShareListResult {
     count: number;
     objects: ShareListItem[];
 }
-/** DI seam for tests — override the real HTTP GET of the JSON listing route. */
-export type ListingFetchFn = (url: string) => Promise<{
+/** DI seam for tests — override the real HTTP GET of the JSON listing route.
+ * The optional `headers` carry the owner bearer for hidden-visibility listings. */
+export type ListingFetchFn = (url: string, headers?: Record<string, string>) => Promise<{
     status: number;
     contentType: string;
     body: string;
 }>;
+export interface ShareEditResult {
+    ok: true;
+    url: string;
+    label: string | null;
+    meta: Record<string, string>;
+    /** The visibility the page now carries (present on Workers that support the
+     * visibility edit; absent from an older deployed template). */
+    visibility?: ShareVisibility;
+    /** The visibility the page had before this edit, when the Worker reports it. */
+    previousVisibility?: ShareVisibility;
+}
+export declare function runShareEdit(target: string, opts: {
+    githubUser?: string;
+    config?: ShareConfig;
+    writeToken?: string;
+    byo?: boolean;
+    session?: PhoenixSession | null;
+    label?: string | null;
+    meta?: Record<string, string>;
+    metaMode?: 'merge' | 'replace';
+    removeMeta?: string[];
+    /** Change the page's visibility in place (public | unlisted | me | org).
+     * A metadata-only rewrite like label/meta — the body is untouched, so no
+     * revision is created. me/org require a Phoenix session. */
+    visibility?: ShareVisibility;
+    force?: boolean;
+    fetchEdit?: typeof fetch;
+}): Promise<ShareEditResult>;
 /** 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
@@ -79,7 +111,24 @@ export declare function runShareList(opts?: {
     session?: string;
     /** Only shares whose label contains this text (case-insensitive substring). */
     label?: string;
+    /** Only shares matching every provided `--meta key=value` entry. */
+    meta?: Record<string, string>;
+    /** Visibility filter. `public` (default) lists only public gallery pages;
+     * `unlisted`/`me`/`org` include that owner's hidden pages; `all` includes
+     * every active page. Hidden scopes send the owner's bearer and `scope=mine`. */
+    scope?: 'public' | 'unlisted' | 'me' | 'org' | 'all';
 }): Promise<ShareListResult>;
+/** 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. */
+export declare function applyShareListFilters(result: ShareListResult, filters: {
+    agent?: string;
+    session?: string;
+    label?: string;
+    meta?: Record<string, string>;
+    scope?: 'public' | 'unlisted' | 'me' | 'org' | 'all';
+}): 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. */

package/dist/commands/share.js

@@ -7,11 +7,11 @@
 // (commands/artifacts-setup.ts), which calls `runShareProvision` below.
 import { existsSync } from 'node:fs';
 import { formatBytes } from '../lib/format.js';
-import { Option } from 'commander';
+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, resolveShareVisibility, } from '../lib/share/publish.js';
+import { publishFile, resolveShareUsername, parseMetaEntries, sanitizeLabel, resolveShareVisibility, scanShareContent, formatSensitiveContentError, SHARE_VISIBILITY_LEVELS, } 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';
@@ -55,14 +55,63 @@ export function shareTemplateStatus(cfg) {
         return 'unknown';
     return cfg.templateHash === hashWorkerScript(renderWorkerScript()) ? 'current' : 'outdated';
 }
+export async function runShareEdit(target, opts) {
+    // 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) {
+        const hits = [
+            ...(typeof opts.label === 'string' ? scanShareContent(opts.label) : []),
+            ...Object.values(opts.meta ?? {}).flatMap((value) => scanShareContent(value)),
+        ];
+        if (hits.length > 0)
+            throw new Error(formatSensitiveContentError(hits));
+    }
+    const backend = resolveShareBackend({ githubUser: opts.githubUser, config: opts.config, writeToken: opts.writeToken, byo: opts.byo, session: opts.session });
+    // me/org are Phoenix-only — surface a crisp login hint here rather than the
+    // Worker's generic 400 for a signed-out caller (BYO WRITE_TOKEN can only set
+    // public/unlisted).
+    if ((opts.visibility === 'me' || opts.visibility === 'org') && backend.kind !== 'managed') {
+        throw new Error(`Changing visibility to '${opts.visibility}' requires a Phoenix session. Run 'agents auth login'.`);
+    }
+    const { key } = await resolveDeleteTarget(target, { githubUser: backend.kind === 'managed' ? backend.namespace : opts.githubUser || backend.namespace });
+    const res = await (opts.fetchEdit ?? fetch)(`${backend.baseUrl.replace(/\/+$/, '')}/${key}`, {
+        method: 'PATCH',
+        headers: { authorization: `Bearer ${backend.token}`, 'content-type': 'application/json' },
+        body: JSON.stringify({
+            ...(opts.label !== undefined ? { label: opts.label } : {}),
+            ...(opts.visibility !== undefined ? { visibility: opts.visibility } : {}),
+            meta: opts.meta ?? {}, metaMode: opts.metaMode ?? 'merge', removeMeta: opts.removeMeta ?? [],
+        }),
+    });
+    const body = await res.text();
+    if (!res.ok) {
+        let detail = body;
+        try {
+            detail = String(JSON.parse(body).error ?? body);
+        }
+        catch { /* keep body */ }
+        throw new Error(`Share metadata edit failed (${res.status}): ${detail || 'unknown error'}`);
+    }
+    const result = JSON.parse(body);
+    // A Worker template that predates the visibility edit ignores the `visibility`
+    // field and 200s without echoing it back — which would otherwise report a
+    // silent success while the page's visibility never changed. Fail loud with the
+    // update path instead (visibility rode in on RUSH-3135's metadata-edit route).
+    if (opts.visibility !== undefined && result.visibility === undefined) {
+        throw new Error("This share endpoint's Worker doesn't support in-place visibility changes yet — it predates them. " +
+            "Run 'agents artifacts share update' to deploy the current Worker template, then retry " +
+            "('agents artifacts share status' shows whether an update is due).");
+    }
+    return result;
+}
 /** Shown whenever the deployed Worker has no `?format=json` listing route — an
  * endpoint provisioned before this feature. Points at the RUSH-2449 update path
  * (`agents artifacts share update`) instead of letting the caller hit a 404 or an
  * HTML body and get a confusing parse error. */
 const OUTDATED_TEMPLATE_HINT = 'Your deployed share Worker has no machine-readable listing route — it predates `agents artifacts share list`. ' +
     'Run `agents artifacts share update` to deploy the current Worker template, then retry (`agents artifacts share status` shows whether an update is due).';
-async function defaultListingFetch(url) {
-    const res = await fetch(url, { headers: { accept: 'application/json' } });
+async function defaultListingFetch(url, headers) {
+    const res = await fetch(url, { headers: { accept: 'application/json', ...(headers || {}) } });
     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,
@@ -108,6 +157,9 @@ 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'
+                ? item.visibility
+                : 'public',
             meta: parseMetaField(item.meta),
         };
     });
@@ -148,9 +200,21 @@ export async function runShareList(opts = {}) {
         }
     }
     const user = await namespaceForBackend(backend, opts.githubUser);
-    const listUrl = `${backend.baseUrl.replace(/\/+$/, '')}/${encodeURIComponent(user)}?format=json`;
+    const scope = opts.scope ?? 'public';
+    const includeHidden = scope !== 'public';
+    const query = new URLSearchParams({ format: 'json' });
+    if (includeHidden)
+        query.set('scope', 'mine');
+    const listUrl = `${backend.baseUrl.replace(/\/+$/, '')}/${encodeURIComponent(user)}?${query.toString()}`;
+    const listingHeaders = {};
+    if (includeHidden) {
+        if (!backend.token) {
+            throw new Error(`Listing ${scope} shares requires owner authentication. Run 'agents auth login' for the managed endpoint, or ensure SHARE_WRITE_TOKEN / 'agents artifacts share join' is configured for BYO.`);
+        }
+        listingHeaders.authorization = `Bearer ${backend.token}`;
+    }
     const fetchListing = opts.fetchListing ?? defaultListingFetch;
-    const res = await fetchListing(listUrl);
+    const res = await fetchListing(listUrl, listingHeaders);
     if (res.status === 404) {
         // A single-segment path 404s either because the namespace is genuinely empty
         // (current template — the listing route gates on the namespace holding objects,
@@ -177,14 +241,23 @@ export async function runShareList(opts = {}) {
         throw new Error(OUTDATED_TEMPLATE_HINT);
     }
     const parsed = parseShareListing(user, res.body);
-    return applyShareListFilters(parsed, opts);
+    return applyShareListFilters(parsed, {
+        agent: opts.agent,
+        session: opts.session,
+        label: opts.label,
+        meta: opts.meta,
+        scope,
+    });
 }
 /** 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) {
+export function applyShareListFilters(result, filters) {
     let objects = result.objects;
+    if (filters.scope && filters.scope !== 'all') {
+        objects = objects.filter((o) => o.visibility === filters.scope);
+    }
     if (filters.agent) {
         const needle = filters.agent.toLowerCase();
         objects = objects.filter((o) => (o.agent ?? '').toLowerCase() === needle);
@@ -196,6 +269,9 @@ function applyShareListFilters(result, filters) {
         const needle = filters.label.toLowerCase();
         objects = objects.filter((o) => (o.label ?? '').toLowerCase().includes(needle));
     }
+    if (filters.meta) {
+        objects = objects.filter((o) => Object.entries(filters.meta).every(([key, value]) => o.meta[key] === value));
+    }
     return { user: result.user, count: objects.length, objects };
 }
 /** Human-readable bytes, e.g. `1.2 KB`, `640 B`. */
@@ -219,7 +295,9 @@ 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 bits = [when, formatBytes(o.size)];
+        const visibility = o.visibility ?? 'public';
+        const visibilityBit = visibility === 'public' ? chalk.green('public') : chalk.yellow(visibility);
+        const bits = [visibilityBit, when, formatBytes(o.size)];
         if (o.agent)
             bits.push(o.agent);
         if (o.revisionCount > 0)
@@ -341,6 +419,18 @@ export function formatShareDeleteResult(result, json = false) {
     }
     return lines.join('\n');
 }
+/** Human summary of an in-place visibility change. */
+function formatShareVisibilityResult(result, requested) {
+    const now = result.visibility ?? requested;
+    const from = result.previousVisibility && result.previousVisibility !== now
+        ? `${chalk.dim(result.previousVisibility)} → `
+        : '';
+    return [
+        `${chalk.green('✓')} visibility ${from}${chalk.bold(now)}`,
+        chalk.dim(`  ${result.url}`),
+        chalk.dim('  body unchanged — no revision created'),
+    ].join('\n');
+}
 /** Shared handler for `agents artifacts share delete <targets...>` and the
  * nested `agents artifacts unshare <targets...>` alias. Deletes each target independently and
  * continues past a failed one (rm-style), reporting all results and exiting
@@ -426,6 +516,36 @@ const SHARE_DELETE_NOTES = `
 
   agents artifacts share delete === agents artifacts unshare (same command, different name).
 `;
+const SHARE_VISIBILITY_EXAMPLES = `
+      # Take a public page private to just you (Phoenix session required for me/org)
+      agents artifacts share visibility https://share.agents-cli.sh/octocat/q3-plan me
+
+      # Make it public again — by <user>/<slug> or a bare slug in your namespace
+      agents artifacts share visibility octocat/q3-plan public
+      agents artifacts share visibility q3-plan unlisted
+
+      # Share with your Phoenix org (rejected on a public-inbox email domain)
+      agents artifacts share visibility q3-plan org
+
+      # Machine-readable result
+      agents artifacts share visibility q3-plan me --visibility-json
+`;
+const SHARE_VISIBILITY_NOTES = `
+  Changes an ALREADY-published page's visibility in place: the slug — and so the
+  URL — is preserved. It re-stamps only the visibility on the stored object; the
+  body, provenance, label, and --meta are untouched, so — like 'agents artifacts
+  share edit' — this is a metadata-only rewrite and creates no revision.
+
+  public is listed in the gallery; unlisted is a capability URL (GET still 200,
+  X-Robots-Tag: noindex, hidden from gallery/list); me is visible only to the
+  signed-in owner; org is visible to members of the same Phoenix organization.
+  me and org require a Phoenix session — run 'agents auth login' first — and org
+  is refused on a public-inbox email domain (gmail.com, outlook.com, …).
+
+  This hits the live endpoint via the owner's Phoenix session (or the BYO
+  WRITE_TOKEN for public/unlisted). It does not re-run the pre-publish
+  sensitive-content scan — the body is unchanged.
+`;
 /**
  * Register the `share` subtree under its parent group — `agents artifacts share`
  * (see commands/artifacts.ts). `agents artifacts unshare` is the nested alias
@@ -436,6 +556,10 @@ const SHARE_DELETE_NOTES = `
 export function registerShareCommands(artifactsCmd) {
     const shareCmd = artifactsCmd
         .command('share')
+        // Child task commands intentionally reuse publish vocabulary (`edit --label`,
+        // `list --meta`). Keep option ownership positional within this subtree so
+        // Commander does not silently resolve those flags to the parent publisher.
+        .enablePositionalOptions()
         .description('Publish an HTML file to a shareable link — managed if signed in, otherwise your Cloudflare R2.')
         .argument('[file]', 'file to publish (HTML or any static asset)')
         .option('--slug <slug>', 'URL slug override (default: stable slug of the artifact title, then filename)')
@@ -553,6 +677,43 @@ ${SHARE_DELETE_NOTES}
     shareDeleteCmd.action(async (targets, opts) => {
         await runShareDelete(targets, opts);
     });
+    // `agents artifacts share visibility <target> <level>` — change an
+    // already-published page's visibility in place. Kept in its own block; it
+    // reuses the delete target parser and the same PATCH metadata-edit route as
+    // `share edit` (visibility is metadata), so it re-stamps the stored object
+    // rather than re-publishing — a re-publish over the PUT path can't express an
+    // in-place change (GET injects the attribution bar at serve time and never
+    // strips it, and the served body carries no provenance/label/--meta back to
+    // re-send). --for-user / --visibility-json (not --github-user / --json): the
+    // parent `share <file>` already owns both long names, and commander resolves a
+    // child option's long name against the whole ancestor chain, silently dropping
+    // a same-named child (RUSH-2687) — the same rename the delete/list blocks make.
+    const shareVisibilityCmd = shareCmd
+        .command('visibility')
+        .description("Change an already-published page's visibility in place (public | unlisted | me | org). The slug/URL is preserved; the body is untouched, so no revision is created.")
+        .addArgument(new Argument('<target>', 'the published page: a full URL, <user>/<slug>, or a bare slug in your namespace'))
+        .addArgument(new Argument('<level>', 'new visibility').choices([...SHARE_VISIBILITY_LEVELS]))
+        .option('--for-user <user>', 'GitHub username for resolving a bare-slug target (default: resolved from gh/git config)')
+        .option('--visibility-json', 'emit a machine-readable result')
+        .action(async (target, level, opts) => {
+        try {
+            const visibility = level;
+            const result = await runShareEdit(target, { visibility, githubUser: opts.forUser });
+            if (opts.visibilityJson) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(formatShareVisibilityResult(result, visibility));
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exitCode = 1;
+        }
+    });
+    setHelpSections(shareVisibilityCmd, {
+        examples: SHARE_VISIBILITY_EXAMPLES,
+        notes: SHARE_VISIBILITY_NOTES,
+    });
     shareCmd
         .command('join')
         .description('Use an existing synced share endpoint and write token (no provisioning).')
@@ -664,20 +825,33 @@ ${SHARE_DELETE_NOTES}
         // share.test.ts). Matches the `revisions` precedent (--for-user/
         // --revisions-json) and the `delete`/`unshare` precedent (--for-user/
         // --delete-json) below.
+        //
+        // `--visibility` is also owned by the parent `share <file>` command (publish),
+        // 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'])
+        .default('public'))
+        .option('--all', "list every page including hidden unlisted/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
         // `--label`/`--title`, same collision class as --for-user/--list-json above.
         .option('--label-contains <substr>', 'filter to shares whose label contains this text (case-insensitive)')
-        .option('--list-json', 'emit the machine-readable listing (slug, url, size, contentType, publishedAt, expiresAt, label, agent, session, host, repo, revisionCount, meta)')
+        .option('--meta <key=value>', 'filter by an exact arbitrary metadata entry (repeatable)', (v, p) => [...p, v], [])
+        .option('--list-json', 'emit the machine-readable listing (slug, url, size, contentType, publishedAt, expiresAt, label, visibility, agent, session, host, repo, revisionCount, meta)')
         .action(async (opts) => {
         try {
+            const scope = opts.all ? 'all' : (opts.scope ?? 'public');
+            const parentMeta = shareCmd.opts().meta ?? [];
             const result = await runShareList({
                 githubUser: opts.forUser,
+                scope,
                 agent: opts.agent,
                 session: opts.session,
                 label: opts.labelContains,
+                meta: parseMetaEntries(opts.meta.length ? opts.meta : parentMeta),
             });
             console.log(formatShareList(result, Boolean(opts.listJson)));
         }
@@ -691,6 +865,11 @@ ${SHARE_DELETE_NOTES}
       # Everything you've published, newest first
       agents artifacts share list
 
+      # Include your hidden pages (unlisted / me / org) so you can see everything
+      agents artifacts share list --all
+      agents artifacts share list --scope me
+      agents artifacts share list --scope unlisted
+
       # Machine-readable — e.g. pull every still-public URL with jq
       agents artifacts share list --list-json | jq -r '.objects[].url'
 
@@ -700,18 +879,83 @@ ${SHARE_DELETE_NOTES}
       # Narrow by who/what published it
       agents artifacts share list --agent claude
       agents artifacts share list --label-contains "fleet plan"
+      agents artifacts share list --meta kind=plan --meta status=final
     `,
         notes: `
   Lists the ACTIVE pages in your namespace — expired links and the sibling .png OG
-  covers are omitted (it mirrors the public gallery). Signed-in users list the
-  managed endpoint (share.agents-cli.sh/<handle>); otherwise BYO. It reads the
-  endpoint's JSON listing route, which ships with the current Worker template. If
-  a BYO 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.
+  covers are omitted. By default this mirrors the public gallery (public pages only).
+  Use --scope unlisted|me|org or --all to include your hidden pages; those scopes
+  send the owner's bearer and a 'scope=mine' hint to the Worker's JSON listing route,
+  which returns hidden pages ONLY after verifying the caller owns the namespace.
+  Signed-in users list the managed endpoint (share.agents-cli.sh/<handle>); otherwise
+  BYO. It reads the endpoint's JSON listing route, which ships with the current
+  Worker template. If a BYO 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/--meta filter the fetched listing client-side;
+  --list-json's count reflects the filtered set. Each human row shows the page's
+  visibility so public vs hidden is obvious at a glance.
+    `,
+    });
+    const shareEditCmd = shareCmd
+        .command('edit <target>')
+        .description('Edit a published share\'s label or arbitrary metadata without republishing its body.')
+        .option('--for-user <user>', 'namespace for resolving a bare slug (default: your namespace)')
+        .option('--label <text>', 'set or replace the display label')
+        .option('--remove-label', 'remove the display label')
+        .option('--meta <key=value>', 'merge a metadata entry (repeatable)', (v, p) => [...p, v], [])
+        .option('--replace-meta <key=value>', 'replace all arbitrary metadata with these entries (repeatable)', (v, p) => [...p, v], [])
+        .option('--remove-meta <key>', 'remove an arbitrary metadata key (repeatable)', (v, p) => [...p, v], [])
+        .option('--edit-json', 'emit the machine-readable edit result')
+        .action(async (target, opts) => {
+        try {
+            const parent = shareCmd.opts();
+            const label = opts.label ?? parent.label;
+            const mergeMeta = opts.meta.length ? opts.meta : (parent.meta ?? []);
+            if (label !== undefined && opts.removeLabel)
+                throw new Error('--label and --remove-label are mutually exclusive.');
+            if (mergeMeta.length && opts.replaceMeta.length)
+                throw new Error('--meta and --replace-meta are mutually exclusive.');
+            if (opts.replaceMeta.length && opts.removeMeta.length)
+                throw new Error('--replace-meta and --remove-meta are mutually exclusive.');
+            if (label === undefined && !opts.removeLabel && !mergeMeta.length && !opts.replaceMeta.length && !opts.removeMeta.length)
+                throw new Error('Nothing to edit. Pass --label, --remove-label, --meta, --replace-meta, or --remove-meta.');
+            const removeMeta = opts.removeMeta.map((key) => Object.keys(parseMetaEntries([`${key}=x`]))[0]);
+            const result = await runShareEdit(target, {
+                githubUser: opts.forUser,
+                label: opts.removeLabel ? null : label === undefined ? undefined : sanitizeLabel(label),
+                meta: parseMetaEntries(opts.replaceMeta.length ? opts.replaceMeta : mergeMeta),
+                metaMode: opts.replaceMeta.length ? 'replace' : 'merge',
+                removeMeta,
+                // Parent `share --force` (RUSH-2687: a child --force is silently dropped).
+                force: parent.force,
+            });
+            console.log(opts.editJson ? JSON.stringify(result, null, 2) : chalk.green(`updated ${result.url}`));
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exitCode = 1;
+        }
+    });
+    setHelpSections(shareEditCmd, {
+        examples: `
+      # Change only the gallery/list title
+      agents artifacts share edit q3-plan --label "Q3 fleet plan"
 
-  --agent/--session/--label-contains filter the fetched listing client-side;
-  --list-json's count reflects the filtered set.
+      # Merge metadata, or deliberately replace/remove it
+      agents artifacts share edit q3-plan --meta status=final --meta ticket=PHNX-3278
+      agents artifacts share edit q3-plan --replace-meta kind=plan --replace-meta status=final
+      agents artifacts share edit q3-plan --remove-meta status
+    `,
+        notes: `
+  Metadata edits preserve the exact published body, content type/HTTP metadata,
+  publication time, visibility, expiry, provenance, cover, and retained revisions. --meta merges;
+  --replace-meta replaces all arbitrary metadata; --remove-meta deletes named keys.
+  Reserved Worker/provenance keys cannot be changed through metadata flags.
+  Edited labels and metadata values are scanned for emails and credential-shaped
+  strings the same way publish is — pass --force to write them anyway.
     `,
     });
     const shareRevisionsCmd = shareCmd

package/dist/commands/ssh.d.ts

@@ -48,6 +48,13 @@ export declare function showLeasedBoxesSection(opts: {
     all?: boolean;
     stats?: boolean;
 }): boolean;
+/**
+ * Remote argv for `agents ssh <slug>` into a leased crabbox. Crabbox ssh does
+ * not go through {@link buildSshInvocation}, so this stamps the same
+ * AGENTS_FLEET_REMOTE consent marker a registered-device ssh would (PHNX-3065).
+ * Exported so the branch is unit-testable without a live crabbox.
+ */
+export declare function leasedBoxRemoteCmd(cmd: string[]): string[];
 /**
  * Race `fanOut` against an overall wall-clock deadline (RUSH-2041).
  *

package/dist/commands/ssh.js

@@ -34,7 +34,7 @@ import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { getDeviceDiscoveryStatus, setDeviceDiscoveryStatus } from '../lib/devices/discovery-policy.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
-import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, deviceIdentityArgs, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.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';
@@ -351,9 +351,21 @@ function trySshLeasedBox(name, cmd) {
         console.error(chalk.red(`Leased box '${name}' is not reachable yet (status: ${boxStatus(box)}).`));
         process.exit(1);
     }
-    const res = spawnSync(sshArgv[0], [...sshArgv.slice(1), ...cmd], { stdio: 'inherit' });
+    // Crabbox ssh does not go through buildSshInvocation; stamp the same
+    // consent marker so a browser drive on a leased box is gated too.
+    const remoteCmd = leasedBoxRemoteCmd(cmd);
+    const res = spawnSync(sshArgv[0], [...sshArgv.slice(1), ...remoteCmd], { stdio: 'inherit' });
     process.exit(res.status ?? 1);
 }
+/**
+ * Remote argv for `agents ssh <slug>` into a leased crabbox. Crabbox ssh does
+ * not go through {@link buildSshInvocation}, so this stamps the same
+ * AGENTS_FLEET_REMOTE consent marker a registered-device ssh would (PHNX-3065).
+ * Exported so the branch is unit-testable without a live crabbox.
+ */
+export function leasedBoxRemoteCmd(cmd) {
+    return isAgentsBrowserDrive(cmd) ? markFleetRemote(cmd, { shell: 'posix' }) : cmd;
+}
 /** Resolve a device or exit with a clear error. */
 async function mustGetDevice(name) {
     const d = await getDevice(name);
@@ -2412,6 +2424,10 @@ An interactive login with no command mirrors the home-relative directory you
 launched from — 'agents ssh yosemite-s0' from ~/src/app lands in ~/src/app on
 the target when it exists, else the remote home. Same portable-cwd rule as
 'agents run --device'. Passing a command keeps the remote home.
+
+An 'agents browser …', 'ag browser …', or standalone 'browser …' command is
+stamped AGENTS_FLEET_REMOTE so the target's browser.remote-control consent
+gate applies, same as 'agents browser <verb> --device <name>'.
 `)
         .action(async (name, cmd) => {
         // Hidden askpass bridge: ssh execs the shim, which re-invokes us here.

package/dist/commands/status.js

@@ -97,6 +97,20 @@ export function registerStatusCommand(syncCmd) {
         if (status.totals.orphan > 0) {
             console.log(chalk.gray(`  (${status.totals.orphan} orphan${status.totals.orphan === 1 ? '' : 's'} — run \`agents prune cleanup\`)`));
         }
+        // Config drift is its OWN class, not a per-agent "N missing": a box that has
+        // not folded its device-scoped state still carries a stale top-level header or
+        // a lingering central fleet/hosts/accounts/browser block. Surface it distinctly
+        // so an un-drained box is SEEN here instead of via a mystery pull conflict
+        // (PHNX-3315).
+        if (status.config.staleHeader || status.config.centralLeaks.length > 0) {
+            console.log(`  ${'config (device-scoped)'.padEnd(28)} ${chalk.yellow('not drained — folds automatically on normal `agents` use here (idempotent)')}`);
+            if (status.config.staleHeader) {
+                console.log(chalk.gray('    · top-level agents.yaml header is stale (pre-rename)'));
+            }
+            for (const leak of status.config.centralLeaks) {
+                console.log(chalk.gray(`    · central ${leak} should be device-scoped`));
+            }
+        }
         // Hand off to the shared interactive/apply flow (summary already printed above).
         await promptDriftSync({ cwd, yes: opts.yes, status, quiet: true });
     });

package/dist/commands/view.d.ts

@@ -81,7 +81,9 @@ export declare function parseResourceSections(options: {
  * agents-cli extension's "resume current session in best available version"
  * command).
  */
-export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSections?: Set<ResourceSection>): Promise<ViewJsonAgent[]>;
+export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSections?: Set<ResourceSection>, opts?: {
+    forceRefresh?: boolean;
+}): Promise<ViewJsonAgent[]>;
 /**
  * Identity key for duplicate-install detection. Prefers accountKey — which
  * encodes account AND org — over the bare email: two installs can share an

package/dist/commands/view.js

@@ -1209,7 +1209,7 @@ export function parseResourceSections(options, jsonMode) {
  * agents-cli extension's "resume current session in best available version"
  * command).
  */
-export async function collectAgentsJson(filterAgentId, resourceSections) {
+export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
     const authCache = readAuthHealthCache();
     const host = machineId();
@@ -1230,7 +1230,7 @@ export async function collectAgentsJson(filterAgentId, resourceSections) {
         home,
         cliVersion: version,
         info,
-    })));
+    })), { forceRefresh: opts?.forceRefresh === true });
     const mergeCanonical = (info) => {
         const key = getUsageLookupKey(info);
         if (!key)
@@ -1273,6 +1273,7 @@ export async function collectAgentsJson(filterAgentId, resourceSections) {
             plan: info.plan,
             usageStatus: info.usageStatus,
             overageCredits: info.overageCredits,
+            usageError: usageInfo?.error ?? null,
             windows: snapshot
                 ? snapshot.windows.map((w) => ({
                     key: w.key,
@@ -1562,7 +1563,7 @@ export async function viewAction(agentArg, options) {
             return;
         }
         if (json) {
-            const data = await collectAgentsJson(undefined, resourceSections);
+            const data = await collectAgentsJson(undefined, resourceSections, { forceRefresh });
             console.log(JSON.stringify(data, null, 2));
             return;
         }
@@ -1624,7 +1625,7 @@ export async function viewAction(agentArg, options) {
     if (json) {
         // --json ignores the @version suffix, but --resources/--detailed (or a
         // section flag) now attach each version's resource inventory + sync-state.
-        const data = await collectAgentsJson(agentId, resourceSections);
+        const data = await collectAgentsJson(agentId, resourceSections, { forceRefresh });
         console.log(JSON.stringify(data[0] ?? { agent: agentId, versions: [], harnesses: [] }, null, 2));
         return;
     }