@phnx-labs/agents-cli 1.22.53 → 1.22.55

package/dist/lib/session/state.js

@@ -16,6 +16,7 @@
  */
 import * as path from 'path';
 import { isCompletedTodoStatus, SNAPSHOT_TODO_TOOLS, summarizeToolUse } from './parse.js';
+import { isShellExecTool } from './shell-programs.js';
 /**
  * Detect per-session rate-limit / usage-limit signals in assistant or error
  * text (RUSH-1523). Matches the same shapes the ext's prewarm detectBlockingPrompt
@@ -174,7 +175,7 @@ export function extractRecentDirectoriesTouched(events, cwd) {
         if (['Edit', 'Write', 'edit_file', 'write_file', 'create_file', 'edit', 'write'].includes(tool)) {
             add(args.file_path ?? args.filePath ?? args.path ?? event.path, true);
         }
-        else if (['Bash', 'exec_command', 'exec', 'run_shell_command', 'shell', 'Execute'].includes(tool)) {
+        else if (isShellExecTool(tool)) {
             add(args.cwd ?? args.Cwd ?? args.workdir ?? args.working_directory ?? cwd);
         }
     }

package/dist/lib/session/stream-render.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { truncate } from '../format.js';
 import { parseClaudeContent, parseCodexContent, sanitizeEvents, summarizeToolUse } from './parse.js';
 import { linkPath, relativeToCwd } from './render.js';
+import { isShellExecTool } from './shell-programs.js';
 const LINE_MAX = 120;
 function timeOf(event) {
     const d = new Date(event.timestamp);
@@ -11,7 +12,7 @@ function timeOf(event) {
 }
 function paintTool(tool) {
     const label = tool.padEnd(10);
-    if (tool === 'Bash' || tool === 'exec_command')
+    if (isShellExecTool(tool))
         return chalk.yellow(label);
     if (tool === 'Edit' || tool === 'Write' || tool === 'Read')
         return chalk.cyan(label);

package/dist/lib/session/tool-calls.js

@@ -1,7 +1,7 @@
 import { createHash } from 'crypto';
 import { parse } from 'acorn';
 import { knownSecretValuesFromEnv, redactSecrets, sanitizeForTerminal } from '../redact.js';
-import { extractShellPrograms } from './shell-programs.js';
+import { extractShellPrograms, isShellExecTool } from './shell-programs.js';
 export const TOOL_INPUT_MAX_BYTES = 16 * 1024;
 export const TOOL_SUCCESS_OUTPUT_MAX_BYTES = 1024;
 export const TOOL_ERROR_OUTPUT_MAX_BYTES = 4 * 1024;
@@ -13,9 +13,6 @@ export const TOOL_INDEX_LIMIT_ORDINAL = Number.MAX_SAFE_INTEGER;
 export const TOOL_TEXT_PROCESSING_MAX_BYTES = 64 * 1024;
 export const TOOL_SHELL_PARSE_MAX_BYTES = 64 * 1024;
 export const TOOL_INDEX_VERSION = 7;
-const SHELL_TOOLS = new Set([
-    'bash', 'exec', 'execute', 'exec_command', 'run_command', 'run_shell_command', 'shell',
-]);
 const BASE64_BLOCK = /(?:[A-Za-z0-9+/]{256,}={0,2})/g;
 const SECRET_FIELD = /(?:token|secret|password|authorization|cookie|api[_-]?key|private[_-]?key)$/i;
 const KNOWN_SECRET_VALUES = knownSecretValuesFromEnv();
@@ -225,7 +222,7 @@ export function commandsFromCodexExec(source) {
     return commands;
 }
 function commandFor(tool, args, command) {
-    if (!SHELL_TOOLS.has(tool.toLowerCase()))
+    if (!isShellExecTool(tool))
         return undefined;
     const direct = command
         ?? (typeof args?.command === 'string' ? args.command : undefined)

package/dist/lib/session/trajectory-html.js

@@ -14,6 +14,7 @@
  */
 import { formatDuration, formatTokenCount } from './render.js';
 import { escapeHtml } from './share-html.js';
+import { isShellExecTool } from './shell-programs.js';
 /**
  * The honest footer prefix for a rendered trace: the redacted label only when
  * something was actually redacted, else the "local only" disclaimer under
@@ -30,7 +31,7 @@ function toolColor(step) {
     if (step.kind === 'thinking')
         return '#3a3a55';
     const tool = (step.tool ?? '').toLowerCase();
-    if (tool === 'bash' || tool === 'shell' || tool.includes('exec') || tool === 'run_command')
+    if (isShellExecTool(tool))
         return '#e0b341';
     if (tool === 'read' || tool === 'grep' || tool === 'glob' || tool === 'search' || tool === 'codebase_search')
         return '#4a9eff';

package/dist/lib/session/trajectory.js

@@ -22,22 +22,13 @@
  */
 import { redactSecrets } from '../redact.js';
 import { computeSummaryStats } from './render.js';
-import { extractShellPrograms } from './shell-programs.js';
+import { extractShellPrograms, isShellExecTool } from './shell-programs.js';
 const DEFAULT_IDLE_THRESHOLD_MS = 120_000;
 const DEFAULT_MAX_STEPS = 5000;
 const LABEL_MAX = 140;
 const DETAIL_MAX = 400;
 /** Tools that spawn an inline sub-agent inside THIS transcript (a `tool_use` row). */
 const INLINE_TASK_TOOLS = new Set(['Task', 'Agent']);
-/**
- * Shell tools whose command is worth resolving to an effective program — every
- * harness's shell-exec tool, kept in lockstep with the canonical set in
- * `state.ts` (`['Bash', 'exec_command', 'exec', 'run_shell_command', 'shell', 'Execute']`)
- * so Codex's `exec_command`/`exec` and the rest are covered, not just Claude's `Bash`.
- * `exec` is newer Codex (gpt-5.6-sol) whose real command the parser unwraps from a
- * JS cell into the event's `command` before this runs.
- */
-const SHELL_TOOLS = new Set(['Bash', 'exec_command', 'exec', 'run_shell_command', 'shell', 'Execute']);
 /**
  * Shell builtins/assignments that are rarely the POINT of a command — the action
  * is whatever runs after them (`export X=Y; git push` → `git`, `cd dir && bun test`
@@ -141,7 +132,7 @@ function stripLeadingShellNoise(command) {
 function toolLabel(tool, args, command, redact, knownSecrets) {
     let raw;
     const lower = tool.toLowerCase();
-    if (lower === 'bash' || lower === 'shell' || lower === 'run_command' || lower.includes('exec')) {
+    if (isShellExecTool(tool)) {
         const cmd = command ?? stringArg(args, 'command', 'cmd', 'script');
         raw = cmd ? stripLeadingShellNoise(cmd) : cmd;
     }
@@ -247,7 +238,7 @@ export function buildTrajectory(events, meta, options = {}) {
                     label: toolLabel(tool, e.args, e.command, redact, knownSecrets),
                     delegation: INLINE_TASK_TOOLS.has(tool) ? 'inline-task' : undefined,
                     callId: e.callId,
-                    program: SHELL_TOOLS.has(tool) ? effectiveProgram(e.command ?? (typeof e.args?.command === 'string' ? e.args.command : undefined)) : undefined,
+                    program: isShellExecTool(tool) ? effectiveProgram(e.command ?? (typeof e.args?.command === 'string' ? e.args.command : undefined)) : undefined,
                     exitCode: typeof e.exitCode === 'number' ? e.exitCode : undefined,
                 },
                 eventIndex: i,

package/dist/lib/session/types.d.ts

@@ -384,6 +384,14 @@ export interface SessionMeta {
     _matchedTerms?: string[];
     /** BM25 relevance score from the most recent content-index search */
     _bm25Score?: number;
+    /**
+     * A short highlighted excerpt (`**term**`) around the best-matching FTS5
+     * column (label/topic/project/user content/assistant answer) for the most
+     * recent content-index search. Unlike `_matchedTerms`/`_bm25Score` this is
+     * NOT stripped from `--json` output — it's the searchable-context payload a
+     * content-search result carries, not internal ranking bookkeeping.
+     */
+    snippet?: string;
 }
 /** Output format for rendering a session's content. */
 export type ViewMode = 'summary' | 'markdown' | 'json';

package/dist/lib/share/capture.js

@@ -36,8 +36,17 @@ export function candidateBrowsers() {
         if (p && fs.existsSync(p) && !out.includes(p))
             out.push(p);
     };
-    // 1) An explicit override always wins.
-    push(process.env.PUPPETEER_EXECUTABLE_PATH || process.env.AGENTS_SHARE_BROWSER);
+    // 1) Explicit overrides are contracts, not hints. A typo must fail at the
+    // boundary instead of silently falling through to an unrelated browser.
+    for (const name of ['PUPPETEER_EXECUTABLE_PATH', 'AGENTS_SHARE_BROWSER']) {
+        const value = process.env[name]?.trim();
+        if (!value)
+            continue;
+        if (!fs.existsSync(value)) {
+            throw new Error(`${name} points to a browser that does not exist: ${value}`);
+        }
+        push(value);
+    }
     // 2) Managed Chromium in the Playwright / Puppeteer caches — purpose-built for
     //    headless, so it's the most reliable capture host when present.
     for (const bin of scanCaches())

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

@@ -1,4 +1,5 @@
 import { type ShareConfig } from './config.js';
+import { type ShareBackendKind } from './backend.js';
 export type PutFn = (url: string, body: Buffer, headers: Record<string, string>) => Promise<{
     ok: boolean;
     status: number;
@@ -9,6 +10,8 @@ export interface PublishEndpoint {
     token: string;
 }
 export interface PublishOptions {
+    /** Internal resolved backend; publishFile sets this after authentication. */
+    backendKind?: ShareBackendKind;
     slug?: string;
     /**
      * Auto-expire window. Relative (`30d`, `12h`), absolute (`2026-08-01`), or
@@ -53,6 +56,12 @@ export interface PublishOptions {
     writeToken?: string;
     /** DI seam for tests — override `readSession()`. `null` means signed out. */
     session?: import('../identity/client.js').PhoenixSession | null;
+    /**
+     * Override the sharer's avatar URL stamped on the object (test seam). When
+     * omitted it is derived from the signed-in email via {@link resolveShareAvatar};
+     * an empty string suppresses the stamp (initials-only bar).
+     */
+    avatar?: string;
     /** Force the BYO Cloudflare path even when signed in. */
     byo?: boolean;
     /** DI seam for tests — override the real HTTP PUT. */
@@ -83,6 +92,9 @@ export interface PublishOptions {
     provenance?: ShareProvenance;
 }
 export type ShareVisibility = 'public' | 'unlisted' | 'me' | 'org';
+/** The visibility levels a share may carry — the Worker's own set, used to
+ * validate `--visibility` and `share visibility <target> <level>`. */
+export declare const SHARE_VISIBILITY_LEVELS: readonly ShareVisibility[];
 export interface PublishResult {
     url: string;
     /** URL-safe object name, explicit (`--slug`) or deterministically derived. */
@@ -124,7 +136,7 @@ export interface ShareProvenance {
  * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
  * `owner` which the Worker stamps itself.
  */
-export declare const RESERVED_META_KEYS: readonly ["expires-at", "visibility", "owner", "agent", "session", "host", "repo", "date", "label", "label-source"];
+export declare const RESERVED_META_KEYS: readonly ["expires-at", "published-at", "visibility", "owner", "org_domain", "agent", "session", "host", "repo", "date", "avatar", "label", "label-source", "og-title", "og-description", "og-generated", "og-source-etag"];
 /**
  * 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
@@ -139,6 +151,21 @@ export declare function resolveShareProvenance(opts?: {
     dir?: string;
     now?: Date;
 }): ShareProvenance;
+/**
+ * The sharer's avatar URL, stamped so the share bar can show a real profile
+ * picture instead of only the initials circle. We key a Gravatar on the SHA-256
+ * of the signed-in user's lowercased email (Gravatar resolves either MD5 or
+ * SHA-256), with `d=404` so Gravatar returns 404 for a user who has none — the
+ * bar's `<img>` onerror then falls back to the initials circle. Only the hash
+ * lands in public metadata, never the raw email. Returns '' when signed out
+ * (BYO without a Phoenix session), leaving the bar on the initials circle.
+ *
+ * `opts.session === null` means "explicitly signed out" (a test seam / BYO) and
+ * yields ''; `undefined` reads the real persisted session.
+ */
+export declare function resolveShareAvatar(opts?: {
+    session?: import('../identity/client.js').PhoenixSession | null;
+}): string;
 /**
  * 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
@@ -172,12 +199,36 @@ export declare function sanitizeLabel(text: string): string;
  * The transliterations above cover what actually shows up; anything else outside
  * latin1 is dropped, and a value that transliterates to nothing at all (a title
  * written entirely in a non-latin script) degrades to a marker rather than an
- * empty header. Lossy on purpose: carrying full Unicode needs percent-encoding
- * here AND a matching decode in the Worker, which every already-deployed Worker
- * would render as `%E2%80%A6` until its operator ran `agents artifacts share
- * update` — tracked as RUSH-2786.
+ * empty header. This value is the **latin1-safe floor** every Worker can read: a
+ * pre-Unicode Worker only ever sees `x-share-<field>`, so it MUST stay folded.
+ * Full Unicode rides ALONGSIDE it in a percent-encoded companion header
+ * (`toPercentHeaderValue` / {@link needsUnicodeCompanion}), which a new Worker
+ * opts into via `x-share-encoding: percent` and an old one ignores — so a
+ * Japanese/emoji title renders in full on an updated Worker and still folds
+ * gracefully everywhere else (PHNX-2786).
  */
 export declare function toHeaderValue(text: string): string;
+/**
+ * Whether text carries a code point above latin1 (U+00FF) — the meaningful
+ * display content `fetch`'s ByteString cannot hold, which {@link toHeaderValue}
+ * therefore transliterates or drops. This is the range worth carrying in the
+ * percent-encoded companion: an em dash, a curly quote, an emoji, or any
+ * CJK/Arabic/Hindi text. A plain accented latin1 name (`José`, é = U+00E9) is
+ * NOT lossy and needs no companion.
+ *
+ * `toHeaderValue` ALSO strips C0/C1 control characters (below U+0020, and
+ * U+007F–U+009F), which this deliberately does not flag: a raw ANSI/control
+ * sequence is not display text and must not be reconstructed into a page's
+ * rendered metadata, so it stays dropped on both the old and new Worker paths.
+ */
+export declare function needsUnicodeCompanion(text: string): boolean;
+/**
+ * Percent-encode a single-line free-text value for the `x-share-<field>-u`
+ * companion header. Whitespace is collapsed first (matching the folded value's
+ * single-line shape), then `encodeURIComponent` makes it pure-ASCII and
+ * header-safe. The Worker recovers the original with `decodeURIComponent`.
+ */
+export declare function toPercentHeaderValue(text: string): string;
 /**
  * Best-effort human title when `--label` is omitted: the HTML `<title>`, else a
  * Markdown frontmatter `title:`, else the filename. Always returns something —

package/dist/lib/share/publish.js

@@ -9,6 +9,8 @@ import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { hostname as osHostname } from 'node:os';
+import { createHash } from 'node:crypto';
+import { readSession } from '../identity/client.js';
 import { readShareConfig } from './config.js';
 import { resolveGitHubUsername } from '../git.js';
 import { resolveShareBackend, sanitizeShareNamespace } from './backend.js';
@@ -16,6 +18,9 @@ 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';
+/** The visibility levels a share may carry — the Worker's own set, used to
+ * validate `--visibility` and `share visibility <target> <level>`. */
+export const SHARE_VISIBILITY_LEVELS = ['public', 'unlisted', 'me', 'org'];
 /**
  * `--unlisted` / `{ unlisted: true }` map to `unlisted`; `--visibility me|org`
  * passes through; otherwise `visibility` (default public).
@@ -35,15 +40,22 @@ export function resolveShareVisibility(opts = {}) {
  */
 export const RESERVED_META_KEYS = [
     'expires-at',
+    'published-at',
     'visibility',
     'owner',
+    'org_domain',
     'agent',
     'session',
     'host',
     'repo',
     'date',
+    'avatar',
     'label',
     'label-source',
+    'og-title',
+    'og-description',
+    'og-generated',
+    'og-source-etag',
 ];
 const META_KEY_RE = /^[a-z0-9-]{1,64}$/;
 /**
@@ -64,6 +76,26 @@ export function resolveShareProvenance(opts = {}) {
         date: (opts.now ?? new Date()).toISOString().slice(0, 10),
     };
 }
+/**
+ * The sharer's avatar URL, stamped so the share bar can show a real profile
+ * picture instead of only the initials circle. We key a Gravatar on the SHA-256
+ * of the signed-in user's lowercased email (Gravatar resolves either MD5 or
+ * SHA-256), with `d=404` so Gravatar returns 404 for a user who has none — the
+ * bar's `<img>` onerror then falls back to the initials circle. Only the hash
+ * lands in public metadata, never the raw email. Returns '' when signed out
+ * (BYO without a Phoenix session), leaving the bar on the initials circle.
+ *
+ * `opts.session === null` means "explicitly signed out" (a test seam / BYO) and
+ * yields ''; `undefined` reads the real persisted session.
+ */
+export function resolveShareAvatar(opts = {}) {
+    const session = opts.session !== undefined ? opts.session : readSession();
+    const email = session?.email?.trim().toLowerCase();
+    if (!email)
+        return '';
+    const hash = createHash('sha256').update(email).digest('hex');
+    return `https://www.gravatar.com/avatar/${hash}?d=404&s=52`;
+}
 /**
  * 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
@@ -80,12 +112,12 @@ export function parseMetaEntries(pairs) {
         }
         const key = pair.slice(0, eq).trim();
         const value = pair.slice(eq + 1);
-        if (!META_KEY_RE.test(key)) {
-            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 (Worker-stamped, or set automatically from your session/git) — pass a different key.`);
         }
+        if (!META_KEY_RE.test(key)) {
+            throw new Error(`Bad --meta key '${key}'. Keys are lowercase letters, digits, and hyphens, up to 64 characters.`);
+        }
         meta[key] = value;
     }
     return meta;
@@ -142,10 +174,13 @@ const HEADER_TRANSLITERATIONS = [
  * The transliterations above cover what actually shows up; anything else outside
  * latin1 is dropped, and a value that transliterates to nothing at all (a title
  * written entirely in a non-latin script) degrades to a marker rather than an
- * empty header. Lossy on purpose: carrying full Unicode needs percent-encoding
- * here AND a matching decode in the Worker, which every already-deployed Worker
- * would render as `%E2%80%A6` until its operator ran `agents artifacts share
- * update` — tracked as RUSH-2786.
+ * empty header. This value is the **latin1-safe floor** every Worker can read: a
+ * pre-Unicode Worker only ever sees `x-share-<field>`, so it MUST stay folded.
+ * Full Unicode rides ALONGSIDE it in a percent-encoded companion header
+ * (`toPercentHeaderValue` / {@link needsUnicodeCompanion}), which a new Worker
+ * opts into via `x-share-encoding: percent` and an old one ignores — so a
+ * Japanese/emoji title renders in full on an updated Worker and still folds
+ * gracefully everywhere else (PHNX-2786).
  */
 export function toHeaderValue(text) {
     let safe = text;
@@ -159,6 +194,31 @@ export function toHeaderValue(text) {
         return safe;
     return text.trim() ? '(unnamed)' : '';
 }
+/**
+ * Whether text carries a code point above latin1 (U+00FF) — the meaningful
+ * display content `fetch`'s ByteString cannot hold, which {@link toHeaderValue}
+ * therefore transliterates or drops. This is the range worth carrying in the
+ * percent-encoded companion: an em dash, a curly quote, an emoji, or any
+ * CJK/Arabic/Hindi text. A plain accented latin1 name (`José`, é = U+00E9) is
+ * NOT lossy and needs no companion.
+ *
+ * `toHeaderValue` ALSO strips C0/C1 control characters (below U+0020, and
+ * U+007F–U+009F), which this deliberately does not flag: a raw ANSI/control
+ * sequence is not display text and must not be reconstructed into a page's
+ * rendered metadata, so it stays dropped on both the old and new Worker paths.
+ */
+export function needsUnicodeCompanion(text) {
+    return /[^\u0000-\u00ff]/.test(text);
+}
+/**
+ * Percent-encode a single-line free-text value for the `x-share-<field>-u`
+ * companion header. Whitespace is collapsed first (matching the folded value's
+ * single-line shape), then `encodeURIComponent` makes it pure-ASCII and
+ * header-safe. The Worker recovers the original with `decodeURIComponent`.
+ */
+export function toPercentHeaderValue(text) {
+    return encodeURIComponent(text.replace(/\s+/g, ' ').trim());
+}
 /**
  * Best-effort human title when `--label` is omitted: the HTML `<title>`, else a
  * Markdown frontmatter `title:`, else the filename. Always returns something —
@@ -450,6 +510,7 @@ export async function publishFile(filePath, opts = {}) {
         ...opts,
         githubUser: username,
         analyticsToken,
+        backendKind: backend.kind,
     });
 }
 export async function publishToEndpoint(filePath, endpoint, opts = {}) {
@@ -462,6 +523,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const unlisted = visibility === 'unlisted';
     const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
     const provenance = opts.provenance ?? resolveShareProvenance();
+    const avatarUrl = opts.avatar ?? resolveShareAvatar({ session: opts.session });
     const meta = opts.meta ?? {};
     const put = opts.uploader ??
         (async (u, b, h) => {
@@ -479,6 +541,19 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     // is only reached when --label is omitted.
     const label = explicitLabel ? sanitizeLabel(explicitLabel) : deriveLabel(filePath, body);
     const labelSource = explicitLabel ? 'explicit' : 'derived';
+    const ogMeta = isHtml ? deriveMeta(body.toString('utf8')) : undefined;
+    // The managed Worker owns deterministic OG generation. Point crawlers at the
+    // lazy sibling route without invoking a browser on the publishing machine.
+    if (isHtml && opts.cover !== false && opts.backendKind === 'managed' && ogMeta) {
+        coverUrl = `${pageUrl}.png`;
+        body = Buffer.from(injectOgMeta(body.toString('utf8'), {
+            ...ogMeta,
+            imageUrl: coverUrl,
+            pageUrl,
+            imageWidth: OG_WIDTH,
+            imageHeight: OG_HEIGHT,
+        }), 'utf8');
+    }
     // Pre-publish scan (RUSH-2443/RUSH-2683): refuse emails / credential-shaped
     // strings unless --force. Runs on the raw file body AND on every piece of
     // free-text metadata that lands in public customMetadata — --label (explicit
@@ -501,6 +576,10 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     // Validate the FULL customMetadata payload before any network call — fail
     // fast, not mid-upload.
     const metadataPreview = { ...meta, label, 'label-source': labelSource };
+    if (ogMeta && opts.backendKind === 'managed') {
+        metadataPreview['og-title'] = ogMeta.title;
+        metadataPreview['og-description'] = ogMeta.description;
+    }
     if (provenance.agent)
         metadataPreview.agent = provenance.agent;
     if (provenance.session)
@@ -511,35 +590,64 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         metadataPreview.repo = provenance.repo;
     if (provenance.date)
         metadataPreview.date = provenance.date;
+    if (avatarUrl)
+        metadataPreview.avatar = avatarUrl;
     assertMetadataSize(metadataPreview);
     const authHeaders = (contentType) => {
         const h = { authorization: `Bearer ${endpoint.token}`, 'content-type': contentType };
         if (expiresAt)
             h['x-share-expires-at'] = expiresAt;
         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.
+        // Two headers per free-text field, backward-compatible by construction
+        // (PHNX-2786): `x-share-<field>` always carries the latin1-safe folded value
+        // an already-deployed Worker reads verbatim, and — only when the fold is lossy
+        // (a curly quote, em dash, emoji, CJK/Arabic/Hindi) — a percent-encoded
+        // `x-share-<field>-u` companion carries the full Unicode. A new Worker opts
+        // into the companions via `x-share-encoding: percent`; an old one ignores the
+        // unknown headers and keeps folding gracefully. The floor also keeps the
+        // ByteString crash fixed: a non-latin1 code point never reaches a raw header.
+        let unicodeCompanion = false;
+        const setText = (name, value) => {
+            h[name] = toHeaderValue(value);
+            if (needsUnicodeCompanion(value)) {
+                h[`${name}-u`] = toPercentHeaderValue(value);
+                unicodeCompanion = true;
+            }
+        };
         if (provenance.agent)
-            h['x-share-agent'] = toHeaderValue(provenance.agent);
+            setText('x-share-agent', provenance.agent);
         if (provenance.session)
-            h['x-share-session'] = toHeaderValue(provenance.session);
+            setText('x-share-session', provenance.session);
         if (provenance.host)
-            h['x-share-host'] = toHeaderValue(provenance.host);
+            setText('x-share-host', provenance.host);
         if (provenance.repo)
-            h['x-share-repo'] = toHeaderValue(provenance.repo);
+            setText('x-share-repo', provenance.repo);
         if (provenance.date)
-            h['x-share-date'] = toHeaderValue(provenance.date);
-        h['x-share-label'] = toHeaderValue(label);
+            setText('x-share-date', provenance.date);
+        if (avatarUrl)
+            setText('x-share-avatar', avatarUrl);
+        setText('x-share-label', label);
         h['x-share-label-source'] = labelSource;
+        if (ogMeta && opts.backendKind === 'managed') {
+            setText('x-share-og-title', ogMeta.title);
+            setText('x-share-og-description', ogMeta.description);
+        }
         // Per VALUE, before JSON.stringify — folding the serialized form would rewrite
         // a curly quote inside a value into a bare `"`, which is structural in JSON and
         // makes the Worker's JSON.parse throw. It swallows that error, so every --meta
-        // key would silently vanish on a 200.
+        // key would silently vanish on a 200. The companion carries the whole raw meta
+        // object percent-encoded once, so a new Worker recovers full-Unicode keys AND
+        // values in one JSON.parse rather than per-field.
         if (Object.keys(meta).length > 0) {
             const headerMeta = Object.fromEntries(Object.entries(meta).map(([k, v]) => [toHeaderValue(k), toHeaderValue(v)]));
             h['x-share-meta'] = JSON.stringify(headerMeta);
+            if (Object.entries(meta).some(([k, v]) => needsUnicodeCompanion(k) || needsUnicodeCompanion(v))) {
+                h['x-share-meta-u'] = encodeURIComponent(JSON.stringify(meta));
+                unicodeCompanion = true;
+            }
         }
+        if (unicodeCompanion)
+            h['x-share-encoding'] = 'percent';
         if (opts.noRevision)
             h['x-share-no-revision'] = '1';
         return h;
@@ -551,7 +659,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     // Cover: screenshot the page's hero → upload <slug>.png → inject og:image meta.
     // Unlisted pages still get a cover (the direct URL is the capability), but the
     // cover inherits visibility=unlisted so it is also omitted from the gallery.
-    if (isHtml && opts.cover !== false) {
+    if (isHtml && opts.cover !== false && opts.backendKind !== 'managed') {
         const res = await attachOgCover(filePath, body, {
             pngUrl: `${pageUrl}.png`,
             pageUrl,

package/dist/lib/share/worker-template.d.ts

@@ -1,13 +1,4 @@
-/**
- * Render the Worker source. Pure — the R2 binding + token are wired at deploy time.
- *
- * The literal below still spells the CLI `agents share` in its provenance comment,
- * its root response, and its gallery title, even though the command is now
- * `agents artifacts share` (RUSH-2580). That is deliberate: `hashWorkerScript` of
- * this exact text is what `shareTemplateStatus` compares a provisioned endpoint's
- * recorded `templateHash` against, so editing ANY byte here marks every already-
- * deployed endpoint `outdated` — which makes `agents artifacts share list` refuse
- * until its owner re-runs `agents artifacts share update`. Cosmetic renames are not
- * worth that; change this text only alongside a real Worker behavior change.
- */
+/** Bundle the Worker and its renderer into one uploadable ES module. */
 export declare function renderWorkerScript(): string;
+/** Unbundled Worker source. Kept separate so esbuild can resolve npm modules. */
+export declare function renderWorkerSource(): string;