@phnx-labs/agents-cli 1.22.47 → 1.22.49

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

@@ -14,6 +14,15 @@
  */
 import { formatDuration, formatTokenCount } from './render.js';
 import { escapeHtml } from './share-html.js';
+/**
+ * The honest footer prefix for a rendered trace: the redacted label only when
+ * something was actually redacted, else the "local only" disclaimer under
+ * `--no-redact`. One source for all three layouts (single / compare / lineage)
+ * so the label never drifts back to a hardcoded "Secret-redacted" claim.
+ */
+function redactionLabel(redacted) {
+    return redacted ? 'Secret-redacted' : 'Unredacted (local only)';
+}
 /** Color a tool bar by family; an error outcome overrides to red. */
 function toolColor(step) {
     if (step.outcome === 'error')
@@ -31,7 +40,7 @@ function toolColor(step) {
         return '#b98cff';
     return '#8b98a5';
 }
-/** Precise per-step duration for the waterfall: "8m04s", "1.6s", "320ms". */
+/** Precise per-step duration for the waterfall: "2h01m", "8m04s", "1.6s", "320ms". */
 function formatStepDuration(ms) {
     if (ms <= 0)
         return '0s';
@@ -40,6 +49,13 @@ function formatStepDuration(ms) {
     if (ms < 60_000)
         return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)}s`;
     const totalSec = Math.round(ms / 1000);
+    // Beyond an hour, minutes-only reads as "1441m18s" for an overnight idle gap —
+    // roll into hours so a long stall is legible at a glance.
+    if (totalSec >= 3600) {
+        const h = Math.floor(totalSec / 3600);
+        const m = Math.floor((totalSec % 3600) / 60);
+        return `${h}h${String(m).padStart(2, '0')}m`;
+    }
     const m = Math.floor(totalSec / 60);
     const s = totalSec % 60;
     return `${m}m${String(s).padStart(2, '0')}s`;
@@ -242,7 +258,7 @@ export function renderTrajectoryHtml(model) {
   </div>
 </main>
 <footer>
-  ${model.truncatedSteps > 0 ? 'Truncated · ' : ''}${model.redacted ? 'Secret-redacted' : 'Unredacted (local only)'} trajectory rendered by agents-cli &middot; <code>agents sessions trace</code>
+  ${model.truncatedSteps > 0 ? 'Truncated · ' : ''}${redactionLabel(model.redacted)} trajectory rendered by agents-cli &middot; <code>agents sessions trace</code>
 </footer>
 <script>${THEME_SCRIPT}</script>
 </body>
@@ -335,23 +351,7 @@ const BASE_STYLE = `
     color: var(--dim); font-size: 12px;
     font-family: ui-monospace, "JetBrains Mono", Menlo, monospace;
   }
-`;
-/** Compare-only rules layered on top of {@link BASE_STYLE} — lanes, divergence marker, summary table. */
-const COMPARE_STYLE = `
-  svg .diverge { stroke: #e0b341; stroke-width: 1.4; stroke-dasharray: 4 3; }
-  .diverge-note { color: #e0b341; font-size: 12.5px; margin: 6px 0; }
-  table.cmp-table { border-collapse: collapse; width: 100%; font-family: ui-monospace, "JetBrains Mono", Menlo, monospace; font-size: 12.5px; }
-  table.cmp-table th, table.cmp-table td { text-align: left; padding: 6px 10px; border-bottom: 1px solid var(--border); }
-  table.cmp-table th { color: var(--dim); font-weight: 600; text-transform: uppercase; font-size: 10.5px; letter-spacing: .5px; }
-  .diff-cols { display: flex; gap: 24px; flex-wrap: wrap; }
-  .diff-col { flex: 1; min-width: 260px; }
-  .diff-col h3 { font-size: 11px; color: var(--dim); text-transform: uppercase; letter-spacing: .5px; margin: 0 0 8px; }
-  .diff-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 4px; }
-  .diff-list li {
-    font-family: ui-monospace, "JetBrains Mono", Menlo, monospace; font-size: 12px;
-    border: 1px solid var(--border); border-radius: 5px; padding: 5px 8px; background: var(--panel);
-  }
-  /* trace v2 — analysis hero + program-aware step list */
+  /* trace v2 — analysis hero + program-aware step list (single-session view; compare/lineage layer on top of BASE_STYLE, so this must live here) */
   main { padding: 20px; }
   .analysis { display: grid; grid-template-columns: 1.25fr 1fr; gap: 20px; margin-bottom: 26px; }
   @media (max-width: 720px) { .analysis { grid-template-columns: 1fr; } }
@@ -391,6 +391,22 @@ const COMPARE_STYLE = `
   .gap-divider { text-align: center; color: #7a5c3a; font-size: 11px; margin: 8px 0; letter-spacing: .06em; font-family: ui-monospace, "JetBrains Mono", Menlo, monospace; }
   details.step .detail { white-space: pre-wrap; color: var(--dim); font-size: 11px; background: var(--bg); border: 1px solid var(--border); border-radius: 6px; padding: 8px 10px; margin: 2px 0 8px 54px; max-height: 220px; overflow: auto; }
 `;
+/** Compare-only rules layered on top of {@link BASE_STYLE} — lanes, divergence marker, summary table. */
+const COMPARE_STYLE = `
+  svg .diverge { stroke: #e0b341; stroke-width: 1.4; stroke-dasharray: 4 3; }
+  .diverge-note { color: #e0b341; font-size: 12.5px; margin: 6px 0; }
+  table.cmp-table { border-collapse: collapse; width: 100%; font-family: ui-monospace, "JetBrains Mono", Menlo, monospace; font-size: 12.5px; }
+  table.cmp-table th, table.cmp-table td { text-align: left; padding: 6px 10px; border-bottom: 1px solid var(--border); }
+  table.cmp-table th { color: var(--dim); font-weight: 600; text-transform: uppercase; font-size: 10.5px; letter-spacing: .5px; }
+  .diff-cols { display: flex; gap: 24px; flex-wrap: wrap; }
+  .diff-col { flex: 1; min-width: 260px; }
+  .diff-col h3 { font-size: 11px; color: var(--dim); text-transform: uppercase; letter-spacing: .5px; margin: 0 0 8px; }
+  .diff-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 4px; }
+  .diff-list li {
+    font-family: ui-monospace, "JetBrains Mono", Menlo, monospace; font-size: 12px;
+    border: 1px solid var(--border); border-radius: 5px; padding: 5px 8px; background: var(--panel);
+  }
+`;
 const THEME_SCRIPT = `
   (function () {
     var root = document.documentElement;
@@ -521,7 +537,7 @@ export function renderTrajectoryCompareHtml(cmp) {
   ${renderCompareDiffLists(cmp)}
 </main>
 <footer>
-  Secret-redacted compare rendered by agents-cli &middot; <code>agents sessions trace</code>
+  ${redactionLabel(cmp.a.redacted || cmp.b.redacted)} compare rendered by agents-cli &middot; <code>agents sessions trace</code>
 </footer>
 <script>${THEME_SCRIPT}</script>
 </body>
@@ -696,8 +712,12 @@ const LINEAGE_SCRIPT = `
  * auto-discovered from the team records) plus a per-node summary card revealed
  * by clicking a node. Same shell, redaction, and no-CDN rule as the other two
  * layouts; local paths (`filePath`/`cwd`) are deliberately never rendered.
+ *
+ * `redacted` follows the trace's `--no-redact` flag so the footer states the
+ * honest label, exactly as the single-trajectory and compare renderers do; it
+ * defaults to the redacted claim to keep the shared/safe default.
  */
-export function renderLineageHtml(lineage) {
+export function renderLineageHtml(lineage, redacted = true) {
     const root = lineage.nodes[0];
     const title = root ? `${root.agent} · ${root.shortId}` : 'lineage';
     const spawned = Math.max(0, lineage.nodes.length - 1);
@@ -740,7 +760,7 @@ export function renderLineageHtml(lineage) {
   </div>
 </main>
 <footer>
-  Secret-redacted lineage rendered by agents-cli &middot; <code>agents sessions trace --tree</code>
+  ${redactionLabel(redacted)} lineage rendered by agents-cli &middot; <code>agents sessions trace --tree</code>
 </footer>
 <script>${THEME_SCRIPT}</script>
 <script>${LINEAGE_SCRIPT}</script>

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

@@ -12,7 +12,7 @@
 import { formatTokenCount } from './render.js';
 const DEFAULT_MAX_STEPS = 80;
 const LABEL_COL = 40;
-/** Precise, compact per-step duration: "8m04s", "1.6s", "320ms", "—" for zero. */
+/** Precise, compact per-step duration: "2h01m", "8m04s", "1.6s", "320ms", "—" for zero. */
 function dur(ms, estimated) {
     if (ms <= 0)
         return estimated ? '~0s' : '0s';
@@ -23,7 +23,14 @@ function dur(ms, estimated) {
         s = `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)}s`;
     else {
         const totalSec = Math.round(ms / 1000);
-        s = `${Math.floor(totalSec / 60)}m${String(totalSec % 60).padStart(2, '0')}s`;
+        // Beyond an hour, roll into hours so an overnight stall reads "24h01m", not
+        // "1441m18s" (matches the HTML renderer's formatStepDuration).
+        if (totalSec >= 3600) {
+            s = `${Math.floor(totalSec / 3600)}h${String(Math.floor((totalSec % 3600) / 60)).padStart(2, '0')}m`;
+        }
+        else {
+            s = `${Math.floor(totalSec / 60)}m${String(totalSec % 60).padStart(2, '0')}s`;
+        }
     }
     return estimated ? `~${s}` : s;
 }

package/dist/lib/session/trajectory.js

@@ -32,10 +32,12 @@ 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', 'run_shell_command', 'shell', 'Execute']`)
- * so Codex's `exec_command` and the rest are covered, not just Claude's `Bash`.
+ * `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', 'run_shell_command', 'shell', 'Execute']);
+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`
@@ -83,6 +85,52 @@ function stringArg(args, ...keys) {
     }
     return undefined;
 }
+/**
+ * Strip a shell command's leading throwaway statements so its label reads by what
+ * it DID, not by its setup. Real agent commands overwhelmingly open with a
+ * `cd <repo> &&` (or a multi-line script whose first line is `cd <repo>`), plus the
+ * occasional `export X=Y;`, `set -e`, `source …`, or bare `VAR=val` assignment —
+ * exactly the {@link SHELL_NOISE_PROGRAMS} the badge already skips when resolving
+ * the effective program. Without this, every `cd /long/path && git …` row renders
+ * an identical `cd /long/path` and the trajectory is unreadable; here we drop that
+ * prefix so the label agrees with the badge (`git …`, `gh …`, `bun …`).
+ *
+ * Conservative on purpose: only a LEADING run of noise statements separated by
+ * `&&`, `;`, or a newline is removed (an assignment PREFIX like `VAR=val cmd` too),
+ * pipelines (`|`) are left intact, and a command that is nothing but noise (a lone
+ * `cd dir`) is returned unchanged rather than emptied. The separator match is a
+ * plain negated class, not a shell tokenizer, so a separator INSIDE a quoted arg
+ * (`cd "a; b" && x`) would cut mid-quote — guarded by refusing any strip that
+ * leaves the label with unbalanced quotes and falling back to the whole command.
+ * Display-only — the value is still clipped and secret-redacted downstream.
+ */
+function quotesBalanced(text) {
+    const dq = (text.match(/(?<!\\)"/g) ?? []).length;
+    const sq = (text.match(/(?<!\\)'/g) ?? []).length;
+    return dq % 2 === 0 && sq % 2 === 0;
+}
+function stripLeadingShellNoise(command) {
+    // A leading `cd`/`export`/`set`/`source`/`unset`/`local`/`eval` statement, or an
+    // assignment, terminated by a statement separator (`&&`, `;`, or newline).
+    const noiseStatement = /^\s*(?:cd|export|set|source|unset|local|eval)\b[^\n&;|]*(?:&&|;|\n)+/i;
+    // A bare `VAR=val` — either a full statement (with a separator) or a prefix
+    // (followed by whitespace before the real program: `FOO=bar git push`).
+    const assignment = /^\s*[A-Za-z_][A-Za-z0-9_]*=[^\s&;|]*(?:\s*(?:&&|;|\n)+|\s+)/;
+    let cmd = command;
+    let prev = '';
+    while (cmd !== prev) {
+        prev = cmd;
+        cmd = cmd.replace(noiseStatement, '').replace(assignment, '');
+    }
+    const trimmed = cmd.trim();
+    if (trimmed.length === 0)
+        return command.trim();
+    // A strip that severed a quoted argument (a separator lived inside quotes) leaves
+    // a dangling quote — keep the whole command rather than show a mangled fragment.
+    if (!quotesBalanced(trimmed) && quotesBalanced(command))
+        return command.trim();
+    return trimmed;
+}
 /**
  * A redacted one-line label for a tool call, derived from the raw arguments.
  *
@@ -94,7 +142,8 @@ function toolLabel(tool, args, command, redact, knownSecrets) {
     let raw;
     const lower = tool.toLowerCase();
     if (lower === 'bash' || lower === 'shell' || lower === 'run_command' || lower.includes('exec')) {
-        raw = command ?? stringArg(args, 'command', 'cmd', 'script');
+        const cmd = command ?? stringArg(args, 'command', 'cmd', 'script');
+        raw = cmd ? stripLeadingShellNoise(cmd) : cmd;
     }
     else if (lower === 'read' || lower === 'edit' || lower === 'write' || lower === 'notebookedit' || lower === 'multiedit') {
         raw = stringArg(args, 'file_path', 'path', 'notebook_path', 'filePath');

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

@@ -247,6 +247,21 @@ export interface SessionMeta {
      * `isTeamOrigin` (which marks sessions spawned BY a team).
      */
     spawnedTeam?: string;
+    /**
+     * Fan-out this session left behind, captured at scan time so the preview can
+     * show it WITHOUT re-parsing the transcript — which is the only way a remote
+     * or unindexed row (rendered from `SessionMeta` alone) can show it at all.
+     *
+     * `undefined` and `0` are different claims and must render the same way (the
+     * segment omitted): `undefined` means the row predates the field or the
+     * harness cannot report it, `0` means scanned and none found. Rendering a
+     * literal "0 background shells" for a harness that cannot report them would
+     * assert "none running" where the truth is "unknown".
+     *
+     * Counts are "started", never "still running" — see `extractBackgroundShells`.
+     */
+    subAgentCount?: number;
+    backgroundShellCount?: number;
     /**
      * The plan markdown from the LAST `ExitPlanMode` tool call in the transcript
      * (Claude sessions only), captured at scan time. Present whenever the session

package/dist/lib/sha256-asset.d.ts

@@ -0,0 +1,26 @@
+/**
+ * sha256 helpers for verifying downloaded release assets.
+ *
+ * These live in their own LEAF module — importing only `node:crypto` and
+ * `node:fs` — on purpose. They used to sit in `computer/ssh-tunnel.ts`, whose
+ * own import graph reaches `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
+ * `secrets/*`. `helper-download.ts` needs nothing from that graph but these two
+ * pure functions, and importing them from there closed a module-initialization
+ * cycle:
+ *
+ *   helper-download.ts
+ *     -> computer/ssh-tunnel.ts        (evaluated BEFORE `EXPECTED_TEAM_ID`)
+ *       -> browser/drivers/ssh.ts -> browser/chrome.ts
+ *         -> secrets/bundles.ts -> secrets/index.ts -> secrets/install-helper.ts
+ *           -> secrets/download-keychain.ts
+ *             -> helper-download.ts    (still evaluating; const not yet bound)
+ *
+ * which threw `ReferenceError: Cannot access 'EXPECTED_TEAM_ID' before
+ * initialization` at `secrets/download-keychain.ts:45` for any entry point that
+ * reached `helper-download.ts` first (RUSH-3113). Keep this module a leaf: adding
+ * a local import here can reintroduce that cycle.
+ */
+/** Pull the digest out of a `<sha256>  <filename>` release asset. */
+export declare function parseSha256Asset(text: string): string;
+/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
+export declare function sha256File(file: string): Promise<string>;

package/dist/lib/sha256-asset.js

@@ -0,0 +1,41 @@
+/**
+ * sha256 helpers for verifying downloaded release assets.
+ *
+ * These live in their own LEAF module — importing only `node:crypto` and
+ * `node:fs` — on purpose. They used to sit in `computer/ssh-tunnel.ts`, whose
+ * own import graph reaches `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
+ * `secrets/*`. `helper-download.ts` needs nothing from that graph but these two
+ * pure functions, and importing them from there closed a module-initialization
+ * cycle:
+ *
+ *   helper-download.ts
+ *     -> computer/ssh-tunnel.ts        (evaluated BEFORE `EXPECTED_TEAM_ID`)
+ *       -> browser/drivers/ssh.ts -> browser/chrome.ts
+ *         -> secrets/bundles.ts -> secrets/index.ts -> secrets/install-helper.ts
+ *           -> secrets/download-keychain.ts
+ *             -> helper-download.ts    (still evaluating; const not yet bound)
+ *
+ * which threw `ReferenceError: Cannot access 'EXPECTED_TEAM_ID' before
+ * initialization` at `secrets/download-keychain.ts:45` for any entry point that
+ * reached `helper-download.ts` first (RUSH-3113). Keep this module a leaf: adding
+ * a local import here can reintroduce that cycle.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+/** Pull the digest out of a `<sha256>  <filename>` release asset. */
+export function parseSha256Asset(text) {
+    const m = text.trim().match(/^([A-Fa-f0-9]{64})(\s|$)/);
+    if (!m)
+        throw new Error(`malformed .sha256 release asset: ${JSON.stringify(text.slice(0, 80))}`);
+    return m[1].toLowerCase();
+}
+/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
+export function sha256File(file) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        fs.createReadStream(file)
+            .on('error', reject)
+            .on('data', (d) => hash.update(d))
+            .on('end', () => resolve(hash.digest('hex')));
+    });
+}

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

@@ -0,0 +1,95 @@
+/**
+ * ShareBackend — the token-source seam for `agents artifacts share`.
+ *
+ * Two legitimate principals, picked once at publish time:
+ *   - **managed**: the caller is signed in to Phoenix (`readSession()`), no
+ *     explicit BYO override. Token is the Phoenix access_token; endpoint is
+ *     the already-live `share.agents-cli.sh`. Zero Cloudflare setup.
+ *   - **byo**: the existing static WRITE_TOKEN path (`readShareConfig()` +
+ *     `readWriteToken()`). Unchanged for power users / custom domains / fleet
+ *     injection of `SHARE_WRITE_TOKEN`.
+ *
+ * Dispatch is not a fallback: signed-in AND no BYO override → managed;
+ * otherwise BYO. Fail loud when neither principal can authenticate.
+ *
+ * Explicit BYO override (any one is enough):
+ *   - `opts.byo === true`
+ *   - `opts.writeToken` (a caller-supplied static token, including tests)
+ *   - `AGENTS_SHARE_BACKEND=byo`
+ */
+import { type PhoenixSession } from '../identity/client.js';
+import { type ShareConfig } from './config.js';
+export type ShareBackendKind = 'managed' | 'byo';
+export interface ShareBackend {
+    kind: ShareBackendKind;
+    /** Public base URL of the share Worker, no trailing slash. */
+    baseUrl: string;
+    /** Bearer sent as `Authorization`. Phoenix access_token or WRITE_TOKEN. */
+    token: string;
+    /** URL namespace prefix (`<namespace>/<slug>`). Phoenix handle (email local-part) or GitHub username. */
+    namespace: string;
+}
+export interface ResolveShareBackendOpts {
+    /** Force the BYO Cloudflare path even when signed in. */
+    byo?: boolean;
+    /** Override the namespace (BYO: GitHub username; ignored on managed — the
+     * worker 403s a Phoenix PUT whose first segment is not the verified handle). */
+    githubUser?: string;
+    /** DI seam — a static write token selects BYO. */
+    writeToken?: string;
+    /** DI seam — persisted BYO endpoint config. */
+    config?: ShareConfig;
+    /** DI seam — override `readSession()`. `null` means signed out. */
+    session?: PhoenixSession | null;
+    /**
+     * When false, BYO may resolve without a WRITE_TOKEN. Public GET routes
+     * (list / revisions / status) don't need one; publish and delete do.
+     * Default true.
+     */
+    requireToken?: boolean;
+}
+/** Env var that forces the BYO path. Value must be exactly `byo`. */
+export declare const SHARE_BACKEND_ENV = "AGENTS_SHARE_BACKEND";
+/** URL-safe namespace: lowercase `[a-z0-9-]+`. Matches the Worker's sanitize.
+ *
+ * This is URL-safety, not collision-resistance: two values that differ only
+ * in case or punctuation share a prefix. */
+export declare function sanitizeShareNamespace(s: string): string;
+/**
+ * Public managed-share handle from a verified email.
+ *
+ * `muqsitnawaz@gmail.com` → `muqsitnawaz`. Plus-tags are dropped
+ * (`muqsitnawaz+dev@gmail.com` → `muqsitnawaz`) so the URL stays the
+ * account's default name. Empty / missing email → `''` (caller falls
+ * back to userId). Must match the Worker `handleFromEmail`.
+ */
+export declare function handleFromEmail(email: string | undefined): string;
+/** Managed URL namespace: email handle, else sanitized userId (never empty if either is set). */
+export declare function managedShareHandle(session: Pick<PhoenixSession, 'email' | 'userId'>): string;
+export declare function managedShareBaseUrl(): string;
+/**
+ * True when this config is the platform managed endpoint (`share.agents-cli.sh`).
+ * The deploy path uses this — not "the caller is signed in" — to decide whether
+ * to bind `PHOENIX_ID_BASE` on the Worker.
+ */
+export declare function isManagedShareEndpoint(cfg: {
+    baseUrl?: string;
+    domain?: string;
+}): boolean;
+/**
+ * Phoenix ID URL to bind on a managed Worker deploy. `undefined` for a
+ * pure-BYO Worker (WRITE_TOKEN only). Fail loud if this is a managed deploy
+ * but the base is empty — never skip-set a blank secret.
+ */
+export declare function phoenixIdBaseForDeploy(opts?: {
+    managed?: boolean;
+}, cfg?: {
+    baseUrl?: string;
+    domain?: string;
+}): string | undefined;
+/**
+ * Pick the principal. Signed-in (`readSession() != null`) AND no explicit BYO
+ * override → managed; otherwise BYO.
+ */
+export declare function shouldUseManaged(opts?: ResolveShareBackendOpts): boolean;
+export declare function resolveShareBackend(opts?: ResolveShareBackendOpts): ShareBackend;

package/dist/lib/share/backend.js

@@ -0,0 +1,139 @@
+/**
+ * ShareBackend — the token-source seam for `agents artifacts share`.
+ *
+ * Two legitimate principals, picked once at publish time:
+ *   - **managed**: the caller is signed in to Phoenix (`readSession()`), no
+ *     explicit BYO override. Token is the Phoenix access_token; endpoint is
+ *     the already-live `share.agents-cli.sh`. Zero Cloudflare setup.
+ *   - **byo**: the existing static WRITE_TOKEN path (`readShareConfig()` +
+ *     `readWriteToken()`). Unchanged for power users / custom domains / fleet
+ *     injection of `SHARE_WRITE_TOKEN`.
+ *
+ * Dispatch is not a fallback: signed-in AND no BYO override → managed;
+ * otherwise BYO. Fail loud when neither principal can authenticate.
+ *
+ * Explicit BYO override (any one is enough):
+ *   - `opts.byo === true`
+ *   - `opts.writeToken` (a caller-supplied static token, including tests)
+ *   - `AGENTS_SHARE_BACKEND=byo`
+ */
+import { PHOENIX_ID_BASE, readSession } from '../identity/client.js';
+import { DEFAULT_SHARE_DOMAIN, readShareConfig, readWriteToken, readWriteTokenEnv, } from './config.js';
+/** Env var that forces the BYO path. Value must be exactly `byo`. */
+export const SHARE_BACKEND_ENV = 'AGENTS_SHARE_BACKEND';
+/** URL-safe namespace: lowercase `[a-z0-9-]+`. Matches the Worker's sanitize.
+ *
+ * This is URL-safety, not collision-resistance: two values that differ only
+ * in case or punctuation share a prefix. */
+export function sanitizeShareNamespace(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/**
+ * Public managed-share handle from a verified email.
+ *
+ * `muqsitnawaz@gmail.com` → `muqsitnawaz`. Plus-tags are dropped
+ * (`muqsitnawaz+dev@gmail.com` → `muqsitnawaz`) so the URL stays the
+ * account's default name. Empty / missing email → `''` (caller falls
+ * back to userId). Must match the Worker `handleFromEmail`.
+ */
+export function handleFromEmail(email) {
+    if (!email)
+        return '';
+    const local = email.split('@')[0] ?? '';
+    const beforePlus = local.split('+')[0] ?? local;
+    return sanitizeShareNamespace(beforePlus);
+}
+/** Managed URL namespace: email handle, else sanitized userId (never empty if either is set). */
+export function managedShareHandle(session) {
+    return handleFromEmail(session.email) || sanitizeShareNamespace(session.userId ?? '');
+}
+export function managedShareBaseUrl() {
+    return `https://${DEFAULT_SHARE_DOMAIN}`;
+}
+function shareEndpointHost(value) {
+    return value.replace(/^https?:\/\//i, '').replace(/\/+$/, '').toLowerCase();
+}
+/**
+ * True when this config is the platform managed endpoint (`share.agents-cli.sh`).
+ * The deploy path uses this — not "the caller is signed in" — to decide whether
+ * to bind `PHOENIX_ID_BASE` on the Worker.
+ */
+export function isManagedShareEndpoint(cfg) {
+    const managedHost = DEFAULT_SHARE_DOMAIN.toLowerCase();
+    if (cfg.domain && shareEndpointHost(cfg.domain) === managedHost)
+        return true;
+    if (cfg.baseUrl && shareEndpointHost(cfg.baseUrl) === managedHost)
+        return true;
+    return false;
+}
+/**
+ * Phoenix ID URL to bind on a managed Worker deploy. `undefined` for a
+ * pure-BYO Worker (WRITE_TOKEN only). Fail loud if this is a managed deploy
+ * but the base is empty — never skip-set a blank secret.
+ */
+export function phoenixIdBaseForDeploy(opts = {}, cfg) {
+    const managed = opts.managed === true || (cfg != null && isManagedShareEndpoint(cfg));
+    if (!managed)
+        return undefined;
+    const base = PHOENIX_ID_BASE.replace(/\/+$/, '').trim();
+    if (!base) {
+        throw new Error('Managed share deploy requires PHOENIX_ID_BASE so the Worker can verify Phoenix bearers. Set the PHOENIX_ID_BASE env var.');
+    }
+    return base;
+}
+/**
+ * Pick the principal. Signed-in (`readSession() != null`) AND no explicit BYO
+ * override → managed; otherwise BYO.
+ */
+export function shouldUseManaged(opts = {}) {
+    if (opts.byo === true)
+        return false;
+    if (opts.writeToken)
+        return false;
+    if ((process.env[SHARE_BACKEND_ENV] ?? '').trim().toLowerCase() === 'byo')
+        return false;
+    const session = opts.session === undefined ? readSession() : opts.session;
+    return session != null;
+}
+export function resolveShareBackend(opts = {}) {
+    if (shouldUseManaged(opts)) {
+        const session = opts.session === undefined ? readSession() : opts.session;
+        if (!session) {
+            throw new Error("Not signed in. Run 'agents auth login'.");
+        }
+        return resolveManagedBackend(session);
+    }
+    return resolveByoBackend(opts);
+}
+function resolveManagedBackend(session) {
+    if (!session.access_token) {
+        throw new Error("Not signed in. Run 'agents auth login'.");
+    }
+    const namespace = managedShareHandle(session);
+    if (!namespace) {
+        throw new Error("Signed in but the session has no email or user id. Run 'agents auth login' again.");
+    }
+    return {
+        kind: 'managed',
+        baseUrl: managedShareBaseUrl(),
+        token: session.access_token,
+        namespace,
+    };
+}
+function resolveByoBackend(opts) {
+    const cfg = opts.config ?? readShareConfig();
+    if (!cfg) {
+        throw new Error("Not set up yet. Run 'agents auth login' to publish on the managed endpoint (zero Cloudflare setup), or 'agents artifacts setup' / 'agents artifacts share join' for your own Cloudflare.");
+    }
+    const token = opts.writeToken ??
+        (opts.requireToken === false ? (readWriteTokenEnv() ?? '') : readWriteToken());
+    // Namespace is the GitHub username. An explicit --github-user is sanitized
+    // here; otherwise publish fills it via resolveShareUsername (gh/git config).
+    const namespace = opts.githubUser ? sanitizeShareNamespace(opts.githubUser) : '';
+    return {
+        kind: 'byo',
+        baseUrl: cfg.baseUrl.replace(/\/+$/, ''),
+        token,
+        namespace,
+    };
+}

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

@@ -68,7 +68,7 @@ export interface DeleteShareOptions {
     /** Skip deleting the target's retained revisions (`<key>/rev-*`, RUSH-2683
      * revision retention) — default: delete them too. A republished-then-deleted
      * share would otherwise leave its prior world-readable versions live for up
-     * to the bucket's lifecycle max-age (see docs/share.md §Revisions). */
+     * to the bucket's lifecycle max-age (see docs/distribution.md). */
     keepRevisions?: boolean;
     /** Treat an already-missing target as a no-op success instead of an error
      * (mirrors SQL's `DROP ... IF EXISTS`). Default: missing target is an error. */
@@ -77,8 +77,12 @@ export interface DeleteShareOptions {
     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 DELETE. */
     deleter?: DeleteFn;
     /** DI seam for tests — override the real HTTP existence check. */

package/dist/lib/share/delete.js

@@ -7,7 +7,7 @@
 // returns `{"ok":true}` — so `{"ok":true}` alone is never proof of a takedown.
 // Every delete here is followed by a status check that must observe 404 before
 // the operation is reported as successful.
-import { readShareConfig, readWriteToken } from './config.js';
+import { resolveShareBackend } from './backend.js';
 import { buildShareKey, resolveShareUsername } from './publish.js';
 /**
  * Normalize any of the three accepted target forms to the R2 key that publish
@@ -103,7 +103,7 @@ export async function deleteObject(endpoint, key, opts = {}) {
     const existedBefore = before.status !== 404;
     const r = await del(url, { authorization: `Bearer ${endpoint.token}` });
     if (!r.ok) {
-        throw new Error(`Delete failed (${r.status}) for ${url}. Check the write token, or that 'agents artifacts setup' completed.`);
+        throw new Error(`Delete failed (${r.status}) for ${url}. Check the bearer (Phoenix session or WRITE_TOKEN), or that 'agents artifacts setup' completed.`);
     }
     const after = await check(url);
     const verified404 = after.status === 404;
@@ -113,13 +113,12 @@ export async function deleteObject(endpoint, key, opts = {}) {
  * are gone. Throws on an unverified takedown — never reports success for an
  * object that still resolves. */
 export async function deleteShare(target, 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 resolved = await resolveDeleteTarget(target, { githubUser: opts.githubUser });
-    const endpoint = { baseUrl: cfg.baseUrl, token };
+    const backend = resolveShareBackend(opts);
+    const githubUser = backend.kind === 'managed'
+        ? backend.namespace
+        : opts.githubUser || backend.namespace || undefined;
+    const resolved = await resolveDeleteTarget(target, { githubUser });
+    const endpoint = { baseUrl: backend.baseUrl, token: backend.token };
     const page = await deleteObject(endpoint, resolved.key, { deleter: opts.deleter, checker: opts.checker });
     if (!page.existedBefore) {
         if (opts.ifExists) {

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

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+/** Skip inlining a sibling that would bloat the page past a reasonable PUT. */
+export declare const MAX_INLINE_BYTES: number;
+/**
+ * `href="file:///tmp/page.html#purpose"` → `href="#purpose"`.
+ * Bare `file:///tmp/page.html` (no hash) becomes `href="#"`.
+ */
+export declare function rewriteFileAnchors(html: string): string;
+/** Replace local image src/href with a data URI when the file exists next to the page. */
+export declare function inlineLocalAssets(html: string, htmlPath: string): string;
+export declare function prepareShareHtml(html: string, htmlPath: string): string;