@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/lib/share/html.js

@@ -0,0 +1,88 @@
+/**
+ * Make an HTML page self-contained enough to view on share.agents-cli.sh.
+ *
+ * Chrome "Save as" (and some renderers) leave `file:///…html#section` TOC
+ * links and sibling image paths. Those work on disk and 404 on the share
+ * Worker, which only stores the one PUT body. Rewrite same-document file
+ * anchors to `#section`, and inline local image files as data URIs.
+ *
+ * https citations, data: URIs already in the page, and missing files are
+ * left alone. This is not a bundler — it only fixes what would otherwise
+ * render as a broken page after a single-file publish.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Skip inlining a sibling that would bloat the page past a reasonable PUT. */
+export const MAX_INLINE_BYTES = 4 * 1024 * 1024;
+const IMAGE_MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.avif': 'image/avif',
+};
+/**
+ * `href="file:///tmp/page.html#purpose"` → `href="#purpose"`.
+ * Bare `file:///tmp/page.html` (no hash) becomes `href="#"`.
+ */
+export function rewriteFileAnchors(html) {
+    return html.replace(/\b(href\s*=\s*["'])file:\/\/[^"'#]*(#[^"']*)?(["'])/gi, (_m, attr, hash, quote) => `${attr}${hash ?? '#'}${quote}`);
+}
+function isRemoteOrSpecial(url) {
+    return (url.startsWith('data:') ||
+        url.startsWith('http://') ||
+        url.startsWith('https://') ||
+        url.startsWith('//') ||
+        url.startsWith('#') ||
+        url.startsWith('mailto:') ||
+        url.startsWith('javascript:') ||
+        url.startsWith('agents:'));
+}
+function localImagePath(url, htmlDir) {
+    if (!url || isRemoteOrSpecial(url))
+        return null;
+    const withoutHash = url.split('#')[0] ?? url;
+    let fsPath;
+    if (withoutHash.startsWith('file:')) {
+        try {
+            fsPath = fileURLToPath(withoutHash);
+        }
+        catch {
+            return null;
+        }
+    }
+    else {
+        fsPath = resolve(htmlDir, withoutHash);
+    }
+    if (!existsSync(fsPath))
+        return null;
+    const mime = IMAGE_MIME[extname(fsPath).toLowerCase()];
+    if (!mime)
+        return null;
+    return { path: fsPath, mime };
+}
+/** Replace local image src/href with a data URI when the file exists next to the page. */
+export function inlineLocalAssets(html, htmlPath) {
+    const dir = dirname(htmlPath);
+    return html.replace(/\b((?:src|href)\s*=\s*["'])([^"']+)(["'])/gi, (full, pre, url, post) => {
+        const local = localImagePath(url, dir);
+        if (!local)
+            return full;
+        try {
+            const buf = readFileSync(local.path);
+            if (buf.length > MAX_INLINE_BYTES)
+                return full;
+            return `${pre}data:${local.mime};base64,${buf.toString('base64')}${post}`;
+        }
+        catch {
+            return full;
+        }
+    });
+}
+export function prepareShareHtml(html, htmlPath) {
+    return inlineLocalAssets(rewriteFileAnchors(html), htmlPath);
+}

package/dist/lib/share/provision.d.ts

@@ -61,6 +61,18 @@ export interface UpdateWorkerResult {
     /** True when the upload was skipped because `previousHash` already matched. */
     skipped: boolean;
 }
+/** Cloudflare `secret_text` name the Worker reads as `env.PHOENIX_ID_BASE`. */
+export declare const WORKER_PHOENIX_ID_BASE_SECRET = "PHOENIX_ID_BASE";
+export type UpdateWorkerOpts = ProvisionOptions & {
+    force?: boolean;
+    /**
+     * Phoenix ID base URL to bind as `PHOENIX_ID_BASE` after the script upload.
+     * Pass this for a managed deployment; omit it for a pure-BYO Worker (which
+     * authenticates only via WRITE_TOKEN). An empty string is a caller bug and
+     * fails loud — do not pass a blank to "skip".
+     */
+    phoenixIdBase?: string;
+};
 /**
  * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
  * account/worker/bucket `deployWorker` was first called with) and idempotently
@@ -78,7 +90,9 @@ export interface UpdateWorkerResult {
  * API right after the upload — the same two-call sequence first-time
  * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
  * `writeToken` here is the caller's EXISTING token, never a freshly generated
- * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * one. A managed deploy also re-applies `PHOENIX_ID_BASE` the same way (the
+ * Worker reads it to verify Phoenix bearers); a pure-BYO deploy omits it.
+ * Cloudflare's own docs describe exactly this "secrets survive a
  * subsequent write" contract for the sibling `wrangler versions upload
  * --secrets-file` flow ("Secrets not included in the file are preserved from
  * the previous version" —
@@ -86,9 +100,9 @@ export interface UpdateWorkerResult {
  * re-setting the secret to its own value after every deploy gets the same
  * outcome without depending on an unverified upload-time flag.
  */
-export declare function updateWorker(apiToken: string, accountId: string, workerName: string, bucketName: string, script: string, writeToken: string, previousHash: string | undefined, opts?: ProvisionOptions & {
-    force?: boolean;
-}): Promise<UpdateWorkerResult>;
+export declare function updateWorker(apiToken: string, accountId: string, workerName: string, bucketName: string, script: string, writeToken: string, previousHash: string | undefined, opts?: UpdateWorkerOpts): Promise<UpdateWorkerResult>;
+/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
+export declare function putWorkerSecret(apiToken: string, accountId: string, workerName: string, name: string, text: string, opts?: ProvisionOptions): Promise<void>;
 /** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
 export declare function setWorkerSecret(apiToken: string, accountId: string, workerName: string, writeToken: string, opts?: ProvisionOptions): Promise<void>;
 /** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */

package/dist/lib/share/provision.js

@@ -101,6 +101,8 @@ export async function deployWorker(apiToken, accountId, workerName, script, buck
 export function hashWorkerScript(script) {
     return createHash('sha256').update(script, 'utf8').digest('hex');
 }
+/** Cloudflare `secret_text` name the Worker reads as `env.PHOENIX_ID_BASE`. */
+export const WORKER_PHOENIX_ID_BASE_SECRET = 'PHOENIX_ID_BASE';
 /**
  * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
  * account/worker/bucket `deployWorker` was first called with) and idempotently
@@ -118,7 +120,9 @@ export function hashWorkerScript(script) {
  * API right after the upload — the same two-call sequence first-time
  * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
  * `writeToken` here is the caller's EXISTING token, never a freshly generated
- * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * one. A managed deploy also re-applies `PHOENIX_ID_BASE` the same way (the
+ * Worker reads it to verify Phoenix bearers); a pure-BYO deploy omits it.
+ * Cloudflare's own docs describe exactly this "secrets survive a
  * subsequent write" contract for the sibling `wrangler versions upload
  * --secrets-file` flow ("Secrets not included in the file are preserved from
  * the previous version" —
@@ -129,6 +133,13 @@ export function hashWorkerScript(script) {
 export async function updateWorker(apiToken, accountId, workerName, bucketName, script, writeToken, previousHash, opts = {}) {
     const templateHash = hashWorkerScript(script);
     if (!opts.force && previousHash === templateHash) {
+        // Script is current so we skip the upload (which would wipe secrets). A
+        // managed Worker still needs PHOENIX_ID_BASE present — a prior upload from
+        // a CLI that never set it left the secret missing, and this is the heal
+        // that does not require --force or a dummy template bump.
+        if (opts.phoenixIdBase !== undefined) {
+            await applyPhoenixIdBaseSecret(apiToken, accountId, workerName, opts.phoenixIdBase, opts);
+        }
         return { templateHash, skipped: true };
     }
     await deployWorker(apiToken, accountId, workerName, script, bucketName, opts);
@@ -143,18 +154,41 @@ export async function updateWorker(apiToken, accountId, workerName, bucketName,
         const detail = e instanceof Error ? e.message : String(e);
         throw new Error(`Worker deployed but the write token failed to re-apply — re-run \`agents artifacts share update\` to fix this before publishing/deleting anything. (${detail})`);
     }
+    if (opts.phoenixIdBase !== undefined) {
+        try {
+            await applyPhoenixIdBaseSecret(apiToken, accountId, workerName, opts.phoenixIdBase, opts);
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            throw new Error(`Worker deployed but PHOENIX_ID_BASE failed to re-apply — Phoenix-bearer publishes will 401 until you re-run \`agents artifacts share update\`. (${detail})`);
+        }
+    }
     return { templateHash, skipped: false };
 }
-/** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
-export async function setWorkerSecret(apiToken, accountId, workerName, writeToken, opts = {}) {
+/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
+export async function putWorkerSecret(apiToken, accountId, workerName, name, text, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
     await request({
         apiToken,
         method: 'PUT',
         pathname: `/accounts/${accountId}/workers/scripts/${workerName}/secrets`,
-        body: { name: 'WRITE_TOKEN', text: writeToken, type: 'secret_text' },
+        body: { name, text, type: 'secret_text' },
     });
 }
+/** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
+export async function setWorkerSecret(apiToken, accountId, workerName, writeToken, opts = {}) {
+    await putWorkerSecret(apiToken, accountId, workerName, 'WRITE_TOKEN', writeToken, opts);
+}
+function normalizePhoenixIdBase(phoenixIdBase) {
+    const base = phoenixIdBase.replace(/\/+$/, '').trim();
+    if (!base) {
+        throw new Error('Managed share deploy requires a non-empty PHOENIX_ID_BASE so the Worker can verify Phoenix bearers. Set the PHOENIX_ID_BASE env var.');
+    }
+    return base;
+}
+async function applyPhoenixIdBaseSecret(apiToken, accountId, workerName, phoenixIdBase, opts = {}) {
+    await putWorkerSecret(apiToken, accountId, workerName, WORKER_PHOENIX_ID_BASE_SECRET, normalizePhoenixIdBase(phoenixIdBase), opts);
+}
 /** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
 export async function enableWorkersDev(apiToken, accountId, workerName, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;

package/dist/lib/share/publish.d.ts

@@ -18,10 +18,18 @@ export interface PublishOptions {
      */
     expire?: string;
     contentType?: string;
+    /**
+     * Server-enforced visibility (RUSH-3135). `public` (default) is listed in
+     * the gallery; `unlisted` is a capability URL (GET still 200, X-Robots-Tag:
+     * noindex, hidden from gallery/list). `org` is Phase 2 — the Worker 400s it.
+     */
+    visibility?: ShareVisibility;
     /**
      * Hide this page from the public `/<user>` gallery and `agents artifacts share list`
      * (metadata `visibility=unlisted`). The direct URL is still world-readable —
-     * unlisted, not secret (RUSH-2443). Alias of `--private` on the CLI.
+     * unlisted, not secret (RUSH-2443). Alias of `--visibility unlisted` /
+     * `--private` on the CLI. Kept so `sessions share` and existing callers do
+     * not break.
      */
     unlisted?: boolean;
     /**
@@ -39,8 +47,12 @@ export interface PublishOptions {
     githubUser?: string;
     /** DI seam for tests — override the persisted share endpoint config. */
     config?: ShareConfig;
-    /** DI seam for tests — override the keychain-backed write token. */
+    /** DI seam for tests — override the keychain-backed write token. Selects BYO. */
     writeToken?: string;
+    /** DI seam for tests — override `readSession()`. `null` means signed out. */
+    session?: import('../identity/client.js').PhoenixSession | null;
+    /** Force the BYO Cloudflare path even when signed in. */
+    byo?: boolean;
     /** DI seam for tests — override the real HTTP PUT. */
     uploader?: PutFn;
     /** DI seam for tests — override cover capture (returns a PNG buffer or null). */
@@ -55,22 +67,26 @@ export interface PublishOptions {
     /**
      * Structured metadata (`--meta key=value`, repeatable). Keys are validated by
      * {@link parseMetaEntries} — lowercase `[a-z0-9-]`, and may not collide with
-     * {@link RESERVED_META_KEYS}, which the CLI sets automatically.
+     * {@link RESERVED_META_KEYS} (Worker-stamped owner/visibility/expires-at,
+     * plus provenance the CLI sets automatically).
      */
     meta?: Record<string, string>;
     /**
      * Skip revision retention on this publish — overwrite an existing slug's
      * object in place with no `<slug>/rev-<ts>` backup of the version it replaces
-     * (default: keep it; see docs/share.md §Revisions).
+     * (default: keep it; see docs/distribution.md).
      */
     noRevision?: boolean;
     /** DI seam for tests — override provenance auto-capture (agent/session/host/repo/date). */
     provenance?: ShareProvenance;
 }
+export type ShareVisibility = 'public' | 'unlisted';
 export interface PublishResult {
     url: string;
     expiresAt?: string;
     coverUrl?: string;
+    /** Server-enforced visibility stamped on the object. */
+    visibility?: ShareVisibility;
     /** True when the page was published with `visibility=unlisted`. */
     unlisted?: boolean;
     /** The label stored with this share — explicit (`--label`) or derived. */
@@ -78,6 +94,11 @@ export interface PublishResult {
     /** Whether `label` came from `--label` or was auto-derived. */
     labelSource?: 'explicit' | 'derived';
 }
+/** `--unlisted` / `{ unlisted: true }` map to `unlisted`; otherwise `visibility` (default public). */
+export declare function resolveShareVisibility(opts?: {
+    visibility?: ShareVisibility;
+    unlisted?: boolean;
+}): ShareVisibility;
 export interface ShareProvenance {
     /** Harness/agent name (`AGENTS_AGENT_NAME`), when publishing from an agent run. */
     agent?: string;
@@ -91,11 +112,12 @@ export interface ShareProvenance {
     date?: string;
 }
 /**
- * Reserved `customMetadata` keys the CLI sets automatically from the exec env,
- * git, and the local clock (plus `label`/`label-source`) — a `--meta key=value`
- * may not target any of these (see {@link parseMetaEntries}).
+ * Reserved `customMetadata` keys a `--meta key=value` may not target (see
+ * {@link parseMetaEntries}). Matches the Worker's `RESERVED_METADATA_KEYS`:
+ * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
+ * `owner` which the Worker stamps itself.
  */
-export declare const RESERVED_META_KEYS: readonly ["agent", "session", "host", "repo", "date", "label", "label-source"];
+export declare const RESERVED_META_KEYS: readonly ["expires-at", "visibility", "owner", "agent", "session", "host", "repo", "date", "label", "label-source"];
 /**
  * Auto-capture publish provenance from the exec env, git, and the local clock.
  * Every field is present only when the environment genuinely carries it — a
@@ -113,8 +135,9 @@ export declare function resolveShareProvenance(opts?: {
 /**
  * Parse repeated `--meta key=value` CLI args into a validated metadata record.
  * Keys are lowercase `[a-z0-9-]`, up to 64 characters, and may not collide with
- * {@link RESERVED_META_KEYS} (the provenance the CLI sets automatically, plus
- * label/label-source) — throws naming the offending pair on any violation.
+ * {@link RESERVED_META_KEYS} (Worker-stamped owner/visibility/expires-at, plus
+ * the provenance the CLI sets automatically, plus label/label-source) — throws
+ * naming the offending pair on any violation.
  */
 export declare function parseMetaEntries(pairs: string[]): Record<string, string>;
 /** Throws when the combined `customMetadata` payload would exceed {@link MAX_METADATA_BYTES}. */
@@ -201,16 +224,17 @@ export declare function slugify(name: string): string;
 /** The project the file belongs to — git repo name, else the cwd's basename. */
 export declare function detectProject(dir?: string): string;
 /**
- * Notion-style default slug: `<project>-<feature>-<16hex>`. Project scopes the link
- * to the repo the agent is in; the random tail keeps it unguessable + collision-free.
- * A leading `plan-` on the filename is dropped (it's redundant under the project).
+ * Readable slug + view id: `<feature>-<16hex>`. A leading `plan-` on the
+ * filename is dropped. The project no longer prefixes the slug — the URL
+ * namespace is already the publisher's handle (`/<you>/<slug>`).
  *
  * The tail is 8 random bytes (64-bit, 16 hex chars). Reads are public — the URL is
  * the only capability — so the nonce must be genuinely infeasible to brute-force,
- * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/share.md
+ * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/distribution.md
  * §Security for the threat model and `--expire` for sensitive content.)
+ * `--slug` still publishes that exact slug, no view-id appended.
  */
-export declare function defaultSlug(filePath: string, dir?: string): string;
+export declare function defaultSlug(filePath: string, _dir?: string): string;
 /**
  * Best-effort OG cover: capture a screenshot, upload it as `<slug>.png`, and return
  * the page body with og:image meta injected (+ the cover URL). All IO is injected

package/dist/lib/share/publish.js

@@ -10,17 +10,39 @@ import { basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { hostname as osHostname } from 'node:os';
-import { readShareConfig, readWriteToken } from './config.js';
+import { readShareConfig } from './config.js';
 import { resolveGitHubUsername } from '../git.js';
+import { resolveShareBackend, sanitizeShareNamespace } from './backend.js';
 import { captureCover, OG_WIDTH, OG_HEIGHT, OG_SCALE } from './capture.js';
 import { deriveMeta, injectOgMeta } from './og.js';
 import { injectAnalyticsBeacon } from './analytics.js';
+import { prepareShareHtml } from './html.js';
+/** `--unlisted` / `{ unlisted: true }` map to `unlisted`; otherwise `visibility` (default public). */
+export function resolveShareVisibility(opts = {}) {
+    if (opts.unlisted === true)
+        return 'unlisted';
+    if (opts.visibility === 'unlisted')
+        return 'unlisted';
+    return 'public';
+}
 /**
- * Reserved `customMetadata` keys the CLI sets automatically from the exec env,
- * git, and the local clock (plus `label`/`label-source`) — a `--meta key=value`
- * may not target any of these (see {@link parseMetaEntries}).
+ * Reserved `customMetadata` keys a `--meta key=value` may not target (see
+ * {@link parseMetaEntries}). Matches the Worker's `RESERVED_METADATA_KEYS`:
+ * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
+ * `owner` which the Worker stamps itself.
  */
-export const RESERVED_META_KEYS = ['agent', 'session', 'host', 'repo', 'date', 'label', 'label-source'];
+export const RESERVED_META_KEYS = [
+    'expires-at',
+    'visibility',
+    'owner',
+    'agent',
+    'session',
+    'host',
+    'repo',
+    'date',
+    'label',
+    'label-source',
+];
 const META_KEY_RE = /^[a-z0-9-]{1,64}$/;
 /**
  * Auto-capture publish provenance from the exec env, git, and the local clock.
@@ -43,8 +65,9 @@ export function resolveShareProvenance(opts = {}) {
 /**
  * Parse repeated `--meta key=value` CLI args into a validated metadata record.
  * Keys are lowercase `[a-z0-9-]`, up to 64 characters, and may not collide with
- * {@link RESERVED_META_KEYS} (the provenance the CLI sets automatically, plus
- * label/label-source) — throws naming the offending pair on any violation.
+ * {@link RESERVED_META_KEYS} (Worker-stamped owner/visibility/expires-at, plus
+ * the provenance the CLI sets automatically, plus label/label-source) — throws
+ * naming the offending pair on any violation.
  */
 export function parseMetaEntries(pairs) {
     const meta = {};
@@ -59,7 +82,7 @@ export function parseMetaEntries(pairs) {
             throw new Error(`Bad --meta key '${key}'. Keys are lowercase letters, digits, and hyphens, up to 64 characters.`);
         }
         if (RESERVED_META_KEYS.includes(key)) {
-            throw new Error(`--meta ${key}=… is reserved (set automatically from your session/git) — pass a different key.`);
+            throw new Error(`--meta ${key}=… is reserved (Worker-stamped, or set automatically from your session/git) — pass a different key.`);
         }
         meta[key] = value;
     }
@@ -293,7 +316,7 @@ export function slugify(name) {
         .slice(0, 60) || 'page');
 }
 function sanitizeSlugPart(s) {
-    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return sanitizeShareNamespace(s);
 }
 /** The current repo's name, or undefined outside a git checkout — never a
  * fallback guess, since callers that want one (detectProject) supply it themselves. */
@@ -317,18 +340,19 @@ export function detectProject(dir = process.cwd()) {
     return gitRepoName(dir) ?? (sanitizeSlugPart(basename(dir)) || 'share');
 }
 /**
- * Notion-style default slug: `<project>-<feature>-<16hex>`. Project scopes the link
- * to the repo the agent is in; the random tail keeps it unguessable + collision-free.
- * A leading `plan-` on the filename is dropped (it's redundant under the project).
+ * Readable slug + view id: `<feature>-<16hex>`. A leading `plan-` on the
+ * filename is dropped. The project no longer prefixes the slug — the URL
+ * namespace is already the publisher's handle (`/<you>/<slug>`).
  *
  * The tail is 8 random bytes (64-bit, 16 hex chars). Reads are public — the URL is
  * the only capability — so the nonce must be genuinely infeasible to brute-force,
- * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/share.md
+ * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/distribution.md
  * §Security for the threat model and `--expire` for sensitive content.)
+ * `--slug` still publishes that exact slug, no view-id appended.
  */
-export function defaultSlug(filePath, dir) {
+export function defaultSlug(filePath, _dir) {
     const feature = slugify(filePath).replace(/^plan-/, '') || 'page';
-    return `${detectProject(dir)}-${feature}-${randomBytes(8).toString('hex')}`;
+    return `${feature}-${randomBytes(8).toString('hex')}`;
 }
 function guessContentType(filePath) {
     if (/\.html?$/i.test(filePath))
@@ -419,14 +443,12 @@ export function buildShareKey(username, slugPart) {
     return `${user}/${part}`;
 }
 export async function publishFile(filePath, 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 token = opts.writeToken ?? readWriteToken();
-    const username = await resolveShareUsername(opts);
-    const analyticsToken = opts.analyticsToken ?? cfg.analyticsToken;
-    return publishToEndpoint(filePath, { baseUrl: cfg.baseUrl, token }, {
+    const backend = resolveShareBackend(opts);
+    const username = backend.kind === 'managed'
+        ? backend.namespace
+        : await resolveShareUsername({ githubUser: opts.githubUser || backend.namespace || undefined });
+    const analyticsToken = opts.analyticsToken ?? (backend.kind === 'byo' ? (opts.config ?? readShareConfig())?.analyticsToken : undefined);
+    return publishToEndpoint(filePath, { baseUrl: backend.baseUrl, token: backend.token }, {
         ...opts,
         githubUser: username,
         analyticsToken,
@@ -437,7 +459,8 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const slugPart = (opts.slug ?? defaultSlug(filePath)).replace(/^\/+/, '');
     const key = buildShareKey(username, slugPart);
     const expiresAt = resolveExpire(opts.expire);
-    const unlisted = opts.unlisted === true;
+    const visibility = resolveShareVisibility(opts);
+    const unlisted = visibility === 'unlisted';
     const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
     const provenance = opts.provenance ?? resolveShareProvenance();
     const meta = opts.meta ?? {};
@@ -449,6 +472,9 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     let body = readFileSync(filePath);
     let coverUrl;
     const isHtml = /\.html?$/i.test(filePath);
+    if (isHtml) {
+        body = Buffer.from(prepareShareHtml(body.toString('utf8'), filePath), 'utf8');
+    }
     const explicitLabel = opts.label?.trim();
     // sanitizeLabel here (not just inside deriveLabel) covers an explicit
     // --label/--title the caller typed with an embedded newline — deriveLabel
@@ -492,8 +518,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         const h = { authorization: `Bearer ${endpoint.token}`, 'content-type': contentType };
         if (expiresAt)
             h['x-share-expires-at'] = expiresAt;
-        if (unlisted)
-            h['x-share-visibility'] = 'unlisted';
+        h['x-share-visibility'] = visibility;
         // Every free-text header goes through toHeaderValue: a non-latin1 code point
         // anywhere in a label, a repo name, or a --meta value throws inside fetch and
         // crashes the publish outright.
@@ -541,6 +566,9 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     }
     const r = await put(pageUrl, body, authHeaders(opts.contentType ?? guessContentType(filePath)));
     if (!r.ok) {
+        if (r.status === 409) {
+            throw new Error(`Handle '${username}' is already claimed by another account. The public URL namespace is the email local-part; two Phoenix users cannot share it.`);
+        }
         throw new Error(`Publish failed (${r.status}) for ${pageUrl}. Check the write token, or that 'agents artifacts setup' completed.`);
     }
     return {
@@ -549,6 +577,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         coverUrl,
         label,
         labelSource,
+        visibility,
         ...(unlisted ? { unlisted: true } : {}),
     };
 }