@phnx-labs/agents-cli 1.22.52 → 1.22.54

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

@@ -85,6 +85,20 @@ export interface InsightFacets {
     assistantTurns: number;
     toolCount: number;
     errorCount: number;
+    /**
+     * Shell invocations bucketed by the actual executable + first subcommand token, not
+     * lumped under the harness tool name. `bucketKey` collapses each command to
+     * `git commit`, `gh pr`, `agents ssh`, `find`, `ssh→git pull`, … so the tool mix says
+     * which binary ran, not just that `Bash` did. Cross-harness: keyed on `e.command`,
+     * which the codex parser sets for `exec_command` too, so it is not Claude-`Bash`-only.
+     */
+    bashCommands: Record<string, number>;
+    /**
+     * Same bucketing for the shell command that was running when a tool call failed —
+     * turns one `failed tool loop: Bash` line into per-binary failure counts
+     * (`git reconcile`, `find`, `gh`) so the friction is attributable to a command.
+     */
+    bashCommandFailures: Record<string, number>;
     /** Deterministic evidence buckets used by the actions-forward report. */
     frictionSignals: Record<string, number>;
     correctionSignals: Record<string, number>;

package/dist/lib/session/insights.js

@@ -22,6 +22,7 @@
  */
 import { computeSummaryStats, shortenModel } from './render.js';
 import { classifyFileChanges, EDIT_TOOLS, WRITE_TOOLS } from './digest.js';
+import { bucketKey } from './bash-command.js';
 /** File extension → language label. Mirrors the set `/insights` attributes by. */
 const LANGUAGE_BY_EXT = {
     '.ts': 'TypeScript', '.tsx': 'TypeScript', '.mts': 'TypeScript', '.cts': 'TypeScript',
@@ -82,6 +83,7 @@ function emptyFacets() {
         shellCommandsSeen: 0,
         messageHours: new Array(24).fill(0), userTurns: 0, assistantTurns: 0,
         toolCount: 0, errorCount: 0,
+        bashCommands: {}, bashCommandFailures: {},
         frictionSignals: {}, correctionSignals: {}, automationSignals: {},
     };
 }
@@ -172,6 +174,9 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
     /** Shortened model id of the last assistant activity (for stall attribution). */
     let lastAssistantModel = null;
     let lastFailedTool = null;
+    // Most recent shell command seen per tool, so an `error` event (which carries the
+    // failing tool name but not its command) can attribute the failure to a binary.
+    const lastCommandByTool = {};
     for (const e of events) {
         const ts = new Date(e.timestamp).getTime();
         const hasTs = !Number.isNaN(ts);
@@ -191,16 +196,27 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
                     lastAssistantModel = m;
                 }
                 break;
-            case 'error':
+            case 'error': {
                 bump(f.errorCategories, categorizeError(e.content ?? e.output ?? ''));
                 if (e.tool && e.tool === lastFailedTool)
                     bump(f.frictionSignals, `failed tool loop: ${e.tool}`);
+                // Attribute the failure to the binary of that tool's most recent command,
+                // so `Bash` failures split into `git reconcile`/`find`/`gh` rather than one lump.
+                const failedCmd = e.tool ? lastCommandByTool[e.tool] : undefined;
+                if (failedCmd)
+                    bump(f.bashCommandFailures, bucketKey(failedCmd));
                 lastFailedTool = e.tool ?? null;
                 classifyFriction(e.content ?? e.output ?? '', f.frictionSignals);
                 break;
+            }
             case 'tool_result':
-                if (e.success !== false && e.outcome !== 'error')
+                if (e.success !== false && e.outcome !== 'error') {
                     lastFailedTool = null;
+                    // Drop the succeeded tool's remembered command so a later failing call that
+                    // carries no command of its own is not misattributed to this stale binary.
+                    if (e.tool)
+                        delete lastCommandByTool[e.tool];
+                }
                 break;
             case 'message':
                 if (e.role === 'assistant') {
@@ -277,6 +293,9 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
                     f.gitCommits += countGitOp(e.command, 'commit');
                     f.gitPushes += countGitOp(e.command, 'push');
                     classifyAutomation(e.command, f.automationSignals);
+                    bump(f.bashCommands, bucketKey(e.command));
+                    if (toolName)
+                        lastCommandByTool[toolName] = e.command;
                 }
                 break;
             }
@@ -430,6 +449,10 @@ export function mergeFacets(into, add) {
         bump(into.slashCommands, k, v);
     for (const [k, v] of Object.entries(add.errorCategories))
         bump(into.errorCategories, k, v);
+    for (const [k, v] of Object.entries(add.bashCommands ?? {}))
+        bump(into.bashCommands, k, v);
+    for (const [k, v] of Object.entries(add.bashCommandFailures ?? {}))
+        bump(into.bashCommandFailures, k, v);
     for (const [k, v] of Object.entries(add.frictionSignals ?? {}))
         bump(into.frictionSignals, k, v);
     for (const [k, v] of Object.entries(add.correctionSignals ?? {}))

package/dist/lib/session/linear.js

@@ -9,7 +9,7 @@
  *   2. `workspaceUrlKey` in the linear-cli config (`~/.linear-cli/config.json`).
  *
  * When neither is set the ticket stays plain text — it's still shown, just not
- * linked. This keeps the OSS CLI free of any Rush/workspace-specific string.
+ * linked. This keeps the published CLI free of any Rush/workspace-specific string.
  */
 import fs from 'node:fs';
 import os from 'node:os';

package/dist/lib/session/live-metadata.js

@@ -37,6 +37,7 @@ export function activeSessionToSessionMeta(active, self, nowMs) {
         id,
         shortId: deriveShortId(id),
         agent: active.kind,
+        harness: active.harness,
         timestamp: new Date(startedMs).toISOString(),
         lastActivity: new Date(lastMs).toISOString(),
         // An empty file path is honest — a just-created session may have no

package/dist/lib/session/pid-registry.d.ts

@@ -1,6 +1,13 @@
 export interface PidSessionEntry {
     pid: number;
     agent: string;
+    /**
+     * Custom harness / profile name when this pid was launched via
+     * `agents run <profile>` (e.g. `deepseek`). `agent` stays the HOST
+     * CLI (`claude`) so process matching and transcript discovery keep
+     * working. `sessions --active` displays this when set (PHNX-2935).
+     */
+    harness?: string;
     /** The launch session id. Present for agents launched with a known id (Claude). */
     sessionId?: string;
     cwd?: string;

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

@@ -69,5 +69,20 @@ export interface ClassifiedPrompt {
 export declare function classifyUserPrompt(raw: string | undefined, opts?: {
     hasImageAttachment?: boolean;
 }): ClassifiedPrompt;
+/**
+ * Collapse a harness-generated session title when it is injected skill
+ * scaffolding; otherwise leave the title as the harness wrote it.
+ *
+ * Claude's `ai-title` and Cursor's `chatMeta.title` are both derived from the
+ * first turn, so a session opened with a skill gets named after the injected
+ * "Base directory for this skill: …" line. {@link classifyUserPrompt} reports
+ * `kind: 'skill'` only for that line, so collapse it to `/<skill>`. Empty or
+ * whitespace-only input yields `undefined` so the caller falls through to the
+ * first-prompt topic.
+ *
+ * A user-authored title (Claude `/rename` / `custom-title`) is never passed
+ * here — the caller keeps it verbatim.
+ */
+export declare function cleanGeneratedSessionLabel(title: string | undefined): string | undefined;
 /** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export declare function extractSessionTopic(raw: string): string | undefined;

package/dist/lib/session/prompt.js

@@ -201,6 +201,27 @@ export function classifyUserPrompt(raw, opts = {}) {
     const display = (cleanedFirst || firstLine).replace(IMAGE_PATH_RE, '[image]').trim();
     return { clean: display, kind: 'text' };
 }
+/**
+ * Collapse a harness-generated session title when it is injected skill
+ * scaffolding; otherwise leave the title as the harness wrote it.
+ *
+ * Claude's `ai-title` and Cursor's `chatMeta.title` are both derived from the
+ * first turn, so a session opened with a skill gets named after the injected
+ * "Base directory for this skill: …" line. {@link classifyUserPrompt} reports
+ * `kind: 'skill'` only for that line, so collapse it to `/<skill>`. Empty or
+ * whitespace-only input yields `undefined` so the caller falls through to the
+ * first-prompt topic.
+ *
+ * A user-authored title (Claude `/rename` / `custom-title`) is never passed
+ * here — the caller keeps it verbatim.
+ */
+export function cleanGeneratedSessionLabel(title) {
+    const trimmed = title?.trim();
+    if (!trimmed)
+        return undefined;
+    const classified = classifyUserPrompt(trimmed);
+    return classified.kind === 'skill' ? classified.clean : trimmed;
+}
 /** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export function extractSessionTopic(raw) {
     if (!raw.trim())

package/dist/lib/session/shell-programs.d.ts

@@ -9,6 +9,23 @@ export interface ShellProgramOccurrence {
     program: string;
     role: ShellProgramRole;
 }
+/**
+ * Harness tool NAMES that run a shell command — Claude's `Bash`, Codex's
+ * `exec_command`/`exec` (`exec` is newer gpt-5.6-sol), Droid's `Execute`, plus the
+ * generic `shell`/`run_shell_command`/`run_command`/`execute`. This is the single
+ * source of truth for "does this tool row carry a shell command?", consumed by the
+ * trajectory model (program resolution + command-arg extraction), the directory-touched
+ * scan in `state.ts`, the tool-call indexer, and stream rendering — replacing five
+ * hand-synced copies that had already drifted apart.
+ *
+ * Distinct from {@link SHELL_WRAPPERS}, which is interpreter binaries (`bash`, `sh`…)
+ * found INSIDE a command string, not the harness's tool name. Match through
+ * {@link isShellExecTool} so casing is normalized in one place — harnesses disagree on
+ * case (`Bash` vs `bash`, `Execute` vs `exec_command`).
+ */
+export declare const SHELL_EXEC_TOOLS: Set<string>;
+/** Case-insensitive membership test for {@link SHELL_EXEC_TOOLS}. */
+export declare function isShellExecTool(tool: string | undefined): boolean;
 /** Return a word only when Bash expansion cannot change its value. */
 export declare function staticShellWord(word: Word | undefined): string | undefined;
 /** Parse Bash without executing it and return every statically identifiable program. */

package/dist/lib/session/shell-programs.js

@@ -1,5 +1,26 @@
 import path from 'path';
 import { parse, } from 'unbash';
+/**
+ * Harness tool NAMES that run a shell command — Claude's `Bash`, Codex's
+ * `exec_command`/`exec` (`exec` is newer gpt-5.6-sol), Droid's `Execute`, plus the
+ * generic `shell`/`run_shell_command`/`run_command`/`execute`. This is the single
+ * source of truth for "does this tool row carry a shell command?", consumed by the
+ * trajectory model (program resolution + command-arg extraction), the directory-touched
+ * scan in `state.ts`, the tool-call indexer, and stream rendering — replacing five
+ * hand-synced copies that had already drifted apart.
+ *
+ * Distinct from {@link SHELL_WRAPPERS}, which is interpreter binaries (`bash`, `sh`…)
+ * found INSIDE a command string, not the harness's tool name. Match through
+ * {@link isShellExecTool} so casing is normalized in one place — harnesses disagree on
+ * case (`Bash` vs `bash`, `Execute` vs `exec_command`).
+ */
+export const SHELL_EXEC_TOOLS = new Set([
+    'bash', 'exec', 'execute', 'exec_command', 'run_command', 'run_shell_command', 'shell',
+]);
+/** Case-insensitive membership test for {@link SHELL_EXEC_TOOLS}. */
+export function isShellExecTool(tool) {
+    return tool !== undefined && SHELL_EXEC_TOOLS.has(tool.toLowerCase());
+}
 const SHELL_WRAPPERS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh']);
 const PROGRAM_WRAPPERS = new Set(['command', 'builtin', 'env', 'nohup', 'sudo']);
 const MAX_NESTED_DEPTH = 3;

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

@@ -31,6 +31,16 @@ export declare const AG_TMUX_NAME_RE: RegExp;
 /** Whether `name` is an `ag-<agent>-<shortid>` tmux session name. */
 export declare function isAgentTmuxAlias(name: string): boolean;
 export declare function isSessionTrackedAgent(agent: string): agent is SessionAgentId;
+/**
+ * The name `agents sessions` shows for a run. A custom harness launched via a
+ * profile (`agents run deepseek`) keeps its host agent for transcript discovery
+ * and parsing (`claude`) and stamps the profile name on `harness`. Display
+ * prefers that stamp so a deepseek run is not listed as claude (PHNX-2935).
+ */
+export declare function sessionDisplayAgent(session: {
+    agent: string;
+    harness?: string | null;
+}): string;
 /** A single normalized event within a session (message, tool call, thinking, etc.). */
 export interface SessionEvent {
     type: 'message' | 'tool_use' | 'tool_result' | 'thinking' | 'error' | 'init' | 'result' | 'usage' | 'attachment' | 'hook' | 'interrupt';
@@ -154,6 +164,13 @@ export interface SessionMeta {
     id: string;
     shortId: string;
     agent: SessionAgentId;
+    /**
+     * Custom harness / profile name when this session was launched via
+     * `agents run <profile>` (e.g. `deepseek`). `agent` stays the HOST
+     * harness that produced the transcript (`claude`, …) so discovery and
+     * parsing keep working. Display surfaces this when set (PHNX-2935).
+     */
+    harness?: string;
     /** Where the indexed transcript came from. Routine rows are archived from a run directory. */
     origin?: 'cli' | 'routine';
     /** Routine name for transcripts archived from ~/.agents/.history/runs/<name>/<runId>/. */
@@ -367,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/session/types.js

@@ -31,3 +31,13 @@ export function isAgentTmuxAlias(name) {
 export function isSessionTrackedAgent(agent) {
     return SESSION_AGENTS.includes(agent);
 }
+/**
+ * The name `agents sessions` shows for a run. A custom harness launched via a
+ * profile (`agents run deepseek`) keeps its host agent for transcript discovery
+ * and parsing (`claude`) and stamps the profile name on `harness`. Display
+ * prefers that stamp so a deepseek run is not listed as claude (PHNX-2935).
+ */
+export function sessionDisplayAgent(session) {
+    const harness = session.harness?.trim();
+    return harness || session.agent;
+}

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

@@ -53,6 +53,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 +89,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 +133,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"];
 /**
  * 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 +148,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 +196,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 —