@phnx-labs/agents-cli 1.22.53 → 1.22.55

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. */
@@ -123,6 +172,33 @@ export declare function runShareRevisions(target: string, opts?: {
     session?: PhoenixSession | null;
     fetchListing?: ListingFetchFn;
 }): Promise<ShareRevisionsResult>;
+/** The resolved page URL plus a signed-in-owner URL that carries a one-time
+ * login ticket, so opening it activates the shared page's inline visibility
+ * control (PHNX-3370). */
+export interface ShareOpenResult {
+    /** `<user>/<slug>` key of the target page. */
+    key: string;
+    /** The plain page URL (no ticket). */
+    url: string;
+    /** The page URL with `?phoenix_ticket=<t>` — open THIS to be the owner. */
+    ownerUrl: string;
+}
+/** Mint a one-time login ticket for the signed-in owner and build the URL that
+ * opens their own published page **as the owner**, so the inline visibility
+ * control is live in the browser. Managed backend only — the control is gated on
+ * the Phoenix identity, and BYO (WRITE_TOKEN) endpoints have no per-viewer login.
+ * `target` accepts the same three forms as `visibility`/`unshare` (a full URL,
+ * `<user>/<slug>`, or a bare slug in the caller's namespace). */
+export declare function runShareOpen(target: string, opts?: {
+    githubUser?: string;
+    config?: ShareConfig;
+    session?: PhoenixSession | null;
+    /** DI seam — override the ticket-mint POST. */
+    fetchTicket?: (url: string, bearer: string) => Promise<{
+        status: number;
+        body: string;
+    }>;
+}): Promise<ShareOpenResult>;
 export declare function formatShareRevisions(result: ShareRevisionsResult, json?: boolean): string;
 export declare function formatShareDeleteResult(result: DeleteShareResult, json?: boolean): string;
 interface ShareDeleteCliOpts {

package/dist/commands/share.js

@@ -7,17 +7,18 @@
 // (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';
 import { phoenixIdBaseForDeploy, resolveShareBackend, } from '../lib/share/backend.js';
 import { resolveGitHubUsername } from '../lib/git.js';
 import { setHelpSections } from '../lib/help.js';
+import { showUrl } from '../lib/open-url.js';
 export function formatSharePublishResult(result, json = false) {
     if (json)
         return JSON.stringify(result, null, 2);
@@ -55,14 +56,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 +158,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 +201,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 +242,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 +270,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 +296,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)
@@ -305,6 +384,49 @@ export async function runShareRevisions(target, opts = {}) {
     }
     return parseShareRevisions(key, res.body);
 }
+/** Mint a one-time login ticket for the signed-in owner and build the URL that
+ * opens their own published page **as the owner**, so the inline visibility
+ * control is live in the browser. Managed backend only — the control is gated on
+ * the Phoenix identity, and BYO (WRITE_TOKEN) endpoints have no per-viewer login.
+ * `target` accepts the same three forms as `visibility`/`unshare` (a full URL,
+ * `<user>/<slug>`, or a bare slug in the caller's namespace). */
+export async function runShareOpen(target, opts = {}) {
+    const backend = resolveShareBackend({
+        githubUser: opts.githubUser,
+        config: opts.config,
+        session: opts.session,
+        requireToken: false,
+    });
+    if (backend.kind !== 'managed') {
+        throw new Error("'agents artifacts share open' needs a managed (Phoenix) endpoint — the page's inline " +
+            "visibility control is gated on your signed-in identity. Run 'agents auth login' first.");
+    }
+    const baseUrl = backend.baseUrl.replace(/\/+$/, '');
+    const { key } = await resolveDeleteTarget(target, { githubUser: backend.namespace });
+    const url = `${baseUrl}/${key}`;
+    const doFetch = opts.fetchTicket ??
+        (async (u, bearer) => {
+            const res = await fetch(u, { method: 'POST', headers: { authorization: `Bearer ${bearer}` } });
+            return { status: res.status, body: await res.text() };
+        });
+    const res = await doFetch(`${baseUrl}/__ticket`, backend.token);
+    if (res.status !== 200) {
+        throw new Error(`Could not mint a login ticket (${res.status}) from ${baseUrl}/__ticket. ` +
+            "The endpoint may predate this feature — run 'agents artifacts share update' to redeploy the Worker.");
+    }
+    let ticket;
+    try {
+        const parsed = JSON.parse(res.body);
+        if (typeof parsed.ticket !== 'string' || !parsed.ticket)
+            throw new Error('no ticket in response');
+        ticket = parsed.ticket;
+    }
+    catch {
+        throw new Error(`Ticket endpoint at ${baseUrl}/__ticket did not return a usable ticket.`);
+    }
+    const ownerUrl = `${url}?phoenix_ticket=${encodeURIComponent(ticket)}`;
+    return { key, url, ownerUrl };
+}
 export function formatShareRevisions(result, json = false) {
     if (json)
         return JSON.stringify(result, null, 2);
@@ -341,6 +463,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 +560,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 +600,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 +721,84 @@ ${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,
+    });
+    const shareOpenCmd = shareCmd
+        .command('open')
+        .description("Open your own published page in the browser signed in as the owner, so the page's inline visibility control is live. Mints a one-time login ticket and appends it to the URL.")
+        .addArgument(new Argument('<target>', 'the published page: a full URL, <user>/<slug>, or a bare slug in your namespace'))
+        .option('--for-user <user>', 'GitHub username for resolving a bare-slug target (default: resolved from your Phoenix handle)')
+        .option('--no-open', 'print the owner URL instead of opening a browser')
+        .option('--json', 'emit a machine-readable result (includes the ticketed owner URL)')
+        .action(async (target, opts) => {
+        try {
+            const result = await runShareOpen(target, { githubUser: opts.forUser });
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            if (opts.open === false) {
+                console.log(chalk.green(result.ownerUrl));
+                console.log(chalk.dim('  open this to land on the page as the owner (the visibility chip becomes a control)'));
+                return;
+            }
+            const shown = await showUrl(result.ownerUrl);
+            if (shown.via === 'none') {
+                console.log(chalk.green(result.ownerUrl));
+                console.error(chalk.dim('  could not open a browser — open the URL above yourself'));
+            }
+            else {
+                console.log(chalk.green(`Opened ${result.url} as owner — the visibility chip is now a live control.`));
+            }
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exitCode = 1;
+        }
+    });
+    setHelpSections(shareOpenCmd, {
+        examples: `agents artifacts share open q3-plan               # open your page, signed in, ready to re-scope
+agents artifacts share open octocat/q3-plan
+agents artifacts share open https://share.agents-cli.sh/octocat/q3-plan --no-open`,
+        notes: `The shared page's visibility chip is an interactive control only for the signed-in owner; a plain link has no login, so the chip renders as a static cue. This mints a short-lived, single-use login ticket (self-signed by your share Worker) and opens the page with it, so the chip becomes a dropdown you can switch in place.
+Managed (Phoenix) endpoints only — run 'agents auth login' first. If the mint 501s/404s, your Worker predates the feature: run 'agents artifacts share update' to redeploy it.
+Prefer to change visibility without a browser? Use 'agents artifacts share visibility <target> <level>'.`,
+    });
     shareCmd
         .command('join')
         .description('Use an existing synced share endpoint and write token (no provisioning).')
@@ -664,20 +910,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 +950,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 +964,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).
  *