@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/session/remote-list.js

@@ -523,22 +523,59 @@ export async function resolvePeerTarget(machine) {
     }
     return undefined;
 }
+/** Interactive ceiling for a picker-driven peer preview fetch. Tighter than the
+ * fan-out's 60s: the user is arrowing through rows, and a peer that can't
+ * answer a one-session digest in this window should degrade to the metadata
+ * card rather than hold a "fetching…" pane open. */
+const PEER_PREVIEW_TIMEOUT_MS = 15_000;
+/**
+ * Fetch one remote session's preview digest from its owning peer — the data
+ * behind the picker pane for a `_remote` row, whose transcript file this
+ * machine cannot parse. Runs the peer's own `agents sessions preview <id>
+ * --local --json` (the same envelope `agents sessions preview` already
+ * delegates to for a remote id) and returns its `preview` object, verbatim and
+ * UNSANITIZED — the caller owns scrubbing peer-supplied strings before any of
+ * them reach a TTY. Undefined on every failure: unregistered machine, SSH
+ * error, timeout, version-skewed peer with no `--json` preview envelope.
+ */
+export async function fetchPeerPreviewDigest(sessionId, machine, timeoutMs = PEER_PREVIEW_TIMEOUT_MS) {
+    const peer = await resolvePeerTarget(machine);
+    if (!peer)
+        return undefined;
+    const cmd = remoteListCommand(['sessions', 'preview', sessionId, '--local', '--json'], peer.os);
+    const capture = await sshCapture(peer.target, cmd, timeoutMs);
+    if (capture.code !== 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(stripClixml(capture.stdout));
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    const preview = parsed.preview;
+    if (!preview || typeof preview !== 'object' || Array.isArray(preview))
+        return undefined;
+    return preview;
+}
 /**
  * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
  * stdio). `args` is the full arg vector after the binary — callers pass e.g.
  * `['sessions', id, '--markdown']` or `['sessions', 'resume', id]`. Used when a
  * picked session lives on another machine: its transcript and agent binary are
  * there, so both reading (no TTY) and resuming (TTY) must execute on the peer —
- * not via a local `--host` hop, which would discover locally and dead-end for a
+ * not via a local `--device` hop, which would discover locally and dead-end for a
  * session that exists only on the peer. Resolves 'no-target' when the machine
  * isn't a dialable registered device; the caller surfaces a clear message.
  *
  * `opts.env` adds variables to the remote command. It deliberately does NOT
- * carry `AGENTS_FLEET_REMOTE` the way the `--host` passthrough does: that marker
+ * carry `AGENTS_FLEET_REMOTE` the way the `--device` passthrough does: that marker
  * gates consent-sensitive actions on the far side
  * (lib/browser/remote-control.ts), and a resumed agent is a long-lived session
  * that would inherit it for its whole life — `agents browser start` inside it
- * would then be refused as a cross-machine drive. A one-shot `--host` command
+ * would then be refused as a cross-machine drive. A one-shot `--device` command
  * can carry the marker; a session cannot.
  */
 export async function runOnPeer(args, machine, opts = {}) {

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

@@ -6,11 +6,11 @@
  */
 export declare function shellQuote(s: string): string;
 /**
- * Strip the `--host`/`-H` flag (and its value) from a raw `agents sessions` argv,
+ * Strip the `--device`/`-D` flag (and its value) from a raw `agents sessions` argv,
  * leaving the args to forward to the remote unchanged. The remote runs the same
  * binary, so every other flag (`--since`, `--last`, `--json`, query, …) carries
- * over for free. Handles every form commander accepts: `--host h`, `--host=h`,
- * `-H h`, `-H=h`, and the glued short form `-Hh`.
+ * over for free. Handles every form commander accepts: `--device h`, `--device=h`,
+ * `-D h`, `-D=h`, and the glued short form `-Dh`.
  *
  * @param argv full process argv; the sessions args begin at index 2
  *             (`[runtime, script, 'sessions', ...]`).
@@ -20,9 +20,9 @@ export declare function buildForwardedArgs(argv: string[], hosts?: Set<string>):
  * Force a forwarded `agents sessions` listing to span the peer's WHOLE index.
  *
  * A remote listing runs in the peer's SSH-login cwd — its home dir — and the
- * default listing is silently cwd-scoped, so `sessions --host box` reads as
+ * default listing is silently cwd-scoped, so `sessions --device box` reads as
  * empty even when the box's index is full (`No sessions found for /home/<user>`).
- * Across SSH a peer's cwd is meaningless, so `--host` defaults to `--all`
+ * Across SSH a peer's cwd is meaningless, so `--device` defaults to `--all`
  * (whole-index) scope. This only drops the *cwd* narrowing — an explicit path
  * query, `--project`, `--since`, or `--agent` filter still narrows on top, and
  * a query that looks like a path takes precedence over `--all` on the remote.

package/dist/lib/session/remote.js

@@ -1,5 +1,5 @@
 /**
- * `agents sessions --host <target>` — run the session query on a remote machine
+ * `agents sessions --device <target>` — run the session query on a remote machine
  * over SSH and stream its output back. Session transcripts and the index DB live
  * on the machine that produced them (see `discover.ts`, all `os.homedir()`-rooted),
  * so instead of syncing the bytes here we invoke the *remote's own* `agents
@@ -18,7 +18,7 @@
  * banner. The cache is a byproduct of fetches you already made — freely
  * deletable — so the fetch-don't-replicate model holds.
  *
- * Mirrors the transport already used by `agents secrets export --host`
+ * Mirrors the transport already used by `agents secrets export --device`
  * (`src/commands/secrets.ts`): `ssh -o BatchMode=yes <host> bash -lc '<cmd>'`,
  * with `bash -lc` so the remote login PATH resolves `agents`.
  */
@@ -44,11 +44,11 @@ export function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
 /**
- * Strip the `--host`/`-H` flag (and its value) from a raw `agents sessions` argv,
+ * Strip the `--device`/`-D` flag (and its value) from a raw `agents sessions` argv,
  * leaving the args to forward to the remote unchanged. The remote runs the same
  * binary, so every other flag (`--since`, `--last`, `--json`, query, …) carries
- * over for free. Handles every form commander accepts: `--host h`, `--host=h`,
- * `-H h`, `-H=h`, and the glued short form `-Hh`.
+ * over for free. Handles every form commander accepts: `--device h`, `--device=h`,
+ * `-D h`, `-D=h`, and the glued short form `-Dh`.
  *
  * @param argv full process argv; the sessions args begin at index 2
  *             (`[runtime, script, 'sessions', ...]`).
@@ -58,12 +58,10 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
     const out = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === '--host' || a === '-H' || a === '--device' || a === '--devices') {
-            // Commander's `<target...>` variadic accepts both `--host a --host b` and
-            // `--host a b` — consume every consecutive token that is a known host so
-            // the variadic form doesn't leak the extra hosts into the remote argv.
-            // `--device` is an alias for `--host` (its values are merged into the same
-            // host set), so strip it the same way — else the peer would re-fan-out.
+        if (a === '--device' || a === '--devices') {
+            // Commander's `<target...>` variadic accepts both `--device a --device b`
+            // and `--device a b` — consume every consecutive token that is a known host
+            // so the variadic form doesn't leak the extra hosts into the remote argv.
             // Fall back to consuming the single next token when we have no host set
             // (e.g. malformed input) so the flag value never leaks either way.
             if (hosts.size > 0) {
@@ -75,10 +73,8 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
             }
             continue;
         }
-        if (a.startsWith('--host=') || a.startsWith('-H=') || a.startsWith('--device=') || a.startsWith('--devices='))
+        if (a.startsWith('--device=') || a.startsWith('--devices='))
             continue;
-        if (/^-H.+/.test(a))
-            continue; // glued short form: -Hyosemite-s1
         out.push(a);
     }
     return out;
@@ -87,9 +83,9 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
  * Force a forwarded `agents sessions` listing to span the peer's WHOLE index.
  *
  * A remote listing runs in the peer's SSH-login cwd — its home dir — and the
- * default listing is silently cwd-scoped, so `sessions --host box` reads as
+ * default listing is silently cwd-scoped, so `sessions --device box` reads as
  * empty even when the box's index is full (`No sessions found for /home/<user>`).
- * Across SSH a peer's cwd is meaningless, so `--host` defaults to `--all`
+ * Across SSH a peer's cwd is meaningless, so `--device` defaults to `--all`
  * (whole-index) scope. This only drops the *cwd* narrowing — an explicit path
  * query, `--project`, `--since`, or `--agent` filter still narrows on top, and
  * a query that looks like a path takes precedence over `--all` on the remote.
@@ -110,7 +106,7 @@ export function ensureWholeIndex(forwardedArgs) {
  * remote renders its table to the local screen.
  */
 export function buildRemoteCommand(forwardedArgs, columns, os) {
-    // `--host <box>` means "that box's own sessions" — so the peer must answer for
+    // `--device <box>` means "that box's own sessions" — so the peer must answer for
     // ITSELF and not re-sweep its fleet. Without this the remote `agents sessions`
     // fans back out to every device IT knows (including us), printing a spurious
     // `<this-machine>: unreachable`. AGENTS_SESSIONS_LOCAL=1 pins the peer local,

package/dist/lib/session/resume-command.d.ts

@@ -1,6 +1,7 @@
 /**
  * The one public command used by UI and lifecycle consumers to reopen a session.
- * `agents resume` owns identity resolution, source-device routing, version/home
- * selection, and harness-specific continuation; callers must not recreate it.
+ * `agents sessions resume` owns identity resolution, source-device routing,
+ * version/home selection, and harness-specific continuation; callers must not
+ * recreate it.
  */
 export declare function buildCanonicalResumeCommand(sessionId: string): string[];

package/dist/lib/session/resume-command.js

@@ -1,8 +1,9 @@
 /**
  * The one public command used by UI and lifecycle consumers to reopen a session.
- * `agents resume` owns identity resolution, source-device routing, version/home
- * selection, and harness-specific continuation; callers must not recreate it.
+ * `agents sessions resume` owns identity resolution, source-device routing,
+ * version/home selection, and harness-specific continuation; callers must not
+ * recreate it.
  */
 export function buildCanonicalResumeCommand(sessionId) {
-    return ['agents', 'resume', sessionId];
+    return ['agents', 'sessions', 'resume', sessionId];
 }

package/dist/lib/session/resume-owner.d.ts

@@ -20,10 +20,10 @@
  * remote session resumed in whatever directory the user happened to be in.
  *
  * Callers act on the answer differently, and the difference is deliberate:
- * `agents resume` and `agents sessions attach` HOP to the owner over SSH, while
+ * `agents sessions resume` and `agents sessions attach` HOP to the owner over SSH, while
  * `resumeSessionInPlace` — the local takeover every routed caller reaches only
  * after deciding — REFUSES. The batch `sessions resume` needs no check of its
- * own: each of its tabs runs the canonical `agents resume <id>`
+ * own: each of its tabs runs the canonical `agents sessions resume <id>`
  * (lib/session/resume-command.ts), which routes itself.
  */
 import type { SessionMeta } from './types.js';
@@ -41,7 +41,7 @@ import type { SessionMeta } from './types.js';
 export declare const RESUME_PINNED_ENV = "AGENTS_RESUME_PINNED";
 /**
  * Whether this process was handed a resume by its owner-routing hop — read once,
- * then cleared so a nested `agents resume` inside the running agent still routes
+ * then cleared so a nested `agents sessions resume` inside the running agent still routes
  * normally.
  */
 export declare function consumeResumePinned(): boolean;

package/dist/lib/session/resume-owner.js

@@ -20,10 +20,10 @@
  * remote session resumed in whatever directory the user happened to be in.
  *
  * Callers act on the answer differently, and the difference is deliberate:
- * `agents resume` and `agents sessions attach` HOP to the owner over SSH, while
+ * `agents sessions resume` and `agents sessions attach` HOP to the owner over SSH, while
  * `resumeSessionInPlace` — the local takeover every routed caller reaches only
  * after deciding — REFUSES. The batch `sessions resume` needs no check of its
- * own: each of its tabs runs the canonical `agents resume <id>`
+ * own: each of its tabs runs the canonical `agents sessions resume <id>`
  * (lib/session/resume-command.ts), which routes itself.
  */
 import { isSelfHost } from '../devices/self-host.js';
@@ -41,7 +41,7 @@ import { isSelfHost } from '../devices/self-host.js';
 export const RESUME_PINNED_ENV = 'AGENTS_RESUME_PINNED';
 /**
  * Whether this process was handed a resume by its owner-routing hop — read once,
- * then cleared so a nested `agents resume` inside the running agent still routes
+ * then cleared so a nested `agents sessions resume` inside the running agent still routes
  * normally.
  */
 export function consumeResumePinned() {

package/dist/lib/session/session-cache.d.ts

@@ -154,6 +154,10 @@ export interface LoadFleetActiveSessionsOptions {
     gather: () => Promise<{
         sessions: ActiveSession[];
         remoteDeviceCount: number;
+        /** Peer names that went unheard on this gather (RUSH-2507). Undefined when the gather didn't compute it. */
+        remoteSkipped?: string[];
+        /** True when the device list itself could not be loaded — no peer was even attempted. */
+        remoteDiscoveryFailed?: boolean;
     }>;
     readCache?: typeof readActiveSessionsCache;
     writeCache?: typeof writeActiveSessionsCache;
@@ -163,6 +167,14 @@ export interface LoadFleetActiveSessionsResult {
     remoteDeviceCount: number;
     servedFromCache: boolean;
     capturedAt: number;
+    /**
+     * Diagnostics from the gather that produced this result. Only populated on a
+     * live gather (`servedFromCache: false`) — a cache hit serves a prior
+     * snapshot that never persisted these fields, so they read `undefined`
+     * ("not probed this call") rather than falsely claiming a clean fleet.
+     */
+    remoteSkipped?: string[];
+    remoteDiscoveryFailed?: boolean;
 }
 /**
  * Cache-first load of the fleet-wide active set. A prior gather (or any surface

package/dist/lib/session/session-cache.js

@@ -442,6 +442,8 @@ export async function loadFleetActiveSessions(opts) {
         remoteDeviceCount: live.remoteDeviceCount,
         servedFromCache: false,
         capturedAt: snap.capturedAt,
+        remoteSkipped: live.remoteSkipped,
+        remoteDiscoveryFailed: live.remoteDiscoveryFailed,
     };
 }
 /**

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

@@ -0,0 +1,55 @@
+import type { SessionMeta } from './types.js';
+export interface SessionHtmlOptions {
+    /** Whether the Markdown was rendered with redaction on — shown in the footer. */
+    redacted?: boolean;
+}
+/** One metadata chip in the page header. */
+interface Chip {
+    label: string;
+    value: string;
+}
+export declare function escapeHtml(text: string): string;
+/**
+ * Lift every folded reasoning block out of the Markdown, leaving a sentinel.
+ *
+ * `renderer.html` escapes raw HTML unconditionally — the transcript body is model
+ * and tool output, so nothing in it may round-trip as markup. That also escaped
+ * the `<details>` wrapper `--reasoning fold` emits, which is why the disclosure
+ * element has to be reconstructed here instead of allowlisted through.
+ *
+ * Allowlisting was tried twice and is the wrong shape: marked hands the same
+ * markup over as several different raw strings depending on context (a whole-token
+ * gate passed the opening tag and escaped the closing one in a real document), and
+ * a bare `<details>` in ordinary prose is a complete INLINE html token — so prose
+ * that merely mentions the tag would emit a live, unclosed element that swallows
+ * every later turn into it. Reconstructing both ends here makes the pairing
+ * structural: it cannot be unbalanced by anything the transcript contains.
+ */
+export declare function liftFoldBlocks(markdown: string): {
+    text: string;
+    blocks: string[];
+};
+/** Human duration — "13 minutes", never "12m 49s". */
+export declare function formatDuration(ms: number): string;
+/**
+ * The chips shown under the title.
+ *
+ * Deliberately excludes `account` (an email — the publish-time sensitive-content
+ * scan rejects those, and correctly), `cwd`, and `machine`: a published transcript
+ * should not carry the operator's identity or local paths in its chrome. Host and
+ * repo already ride in the share object's provenance metadata, which is the right
+ * home for them.
+ */
+export declare function buildChips(session: SessionMeta): Chip[];
+/**
+ * The page's `<title>` — `deriveLabel()` reads this as the share's gallery label.
+ *
+ * The document heading is derived from the session's first prompt, which in a real
+ * session is routinely a pasted URL plus a file path plus the actual request. Left
+ * whole it renders as a three-line wall above the transcript and an unreadable
+ * gallery row, so it is collapsed to one line and cut at a word boundary. `--label`
+ * overrides it outright.
+ */
+export declare function sessionPageTitle(session: SessionMeta, markdown: string): string;
+export declare function renderSessionHtmlDocument(session: SessionMeta, markdown: string, options?: SessionHtmlOptions): string;
+export {};

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

@@ -0,0 +1,319 @@
+/**
+ * Wrap an already-rendered session transcript in ONE self-contained HTML page for
+ * `agents sessions share`.
+ *
+ * Takes the Markdown document as an argument rather than producing it, so the
+ * decisions that make a transcript safe to publish — redaction, synthetic-turn
+ * filtering, tool-output truncation, reasoning visibility — stay in
+ * `renderSessionMarkdownDocument()` and the HTML path can never drift from the
+ * Markdown one. That also keeps this a pure presentation function with no import
+ * back into the command layer.
+ *
+ * Self-contained on purpose: an inline <style>, no external assets, no CDN, no
+ * dependency on the artifacts-cli host CLI (which is not configured on every box,
+ * RUSH-2728). The page is uploaded verbatim to the share Worker.
+ *
+ * Terminal-coded per the agents-cli brand (#0a0a0a bg, #a3e635 lime accent,
+ * JetBrains Mono), with a light theme under `prefers-color-scheme: light` and an
+ * in-page toggle so a published link is readable in bright light and dim alike.
+ */
+import { marked, Renderer } from 'marked';
+export function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * A transcript is untrusted text: it carries whatever the model wrote and whatever
+ * a tool printed. marked passes raw HTML through by default, so a session that
+ * merely *discussed* a `<script>` tag would ship an executable one on a public URL.
+ * Escaping the html token's raw source neutralizes that without mangling the
+ * visible text, and non-http(s) link schemes are dropped so `javascript:` cannot
+ * ride in through a Markdown link.
+ */
+/**
+ * The only raw HTML the transcript renderer itself emits: `--reasoning fold` wraps
+ * each thinking block in a disclosure element (`session/render.ts` — the `fold`
+ * branch pushes `<details>\n<summary>Reasoning</summary>` and `</details>`).
+ *
+ * Escaping those along with everything else published `&lt;details&gt;` as visible
+ * text and no collapsing, so `--reasoning fold` shipped broken. They are allowed
+ * back through by EXACT match on the token's raw source, not by parsing tags:
+ * attribute-free `details`/`summary` carry no script, no URL, and no event handler,
+ * and an exact-string gate cannot be widened by crafted input the way a tag parser
+ * can. Anything else — including `<details onclick=…>` — still escapes.
+ */
+/**
+ * Sentinel standing in for one folded reasoning block while the document goes
+ * through marked. Deliberately not valid Markdown or HTML, and any pre-existing
+ * occurrence in the transcript is neutralized before substitution.
+ */
+const FOLD_SENTINEL = 'aGeNtSfOlDbLoCk';
+// The neutralization below is only sound because this literal is BORDER-FREE: its
+// first character occurs nowhere else in it, so no occurrence can overlap another
+// and splitting on it cannot leave a fresh one behind. A bordered literal (`aba`
+// splits into a leftover `a` + `ba`) is defeatable. Keep that property if you
+// ever change the string.
+/** The exact block `session/render.ts` pushes on its `fold` branch. */
+const FOLD_BLOCK = /<details>\n<summary>Reasoning<\/summary>\n\n([\s\S]*?)\n\n<\/details>/g;
+/**
+ * Lift every folded reasoning block out of the Markdown, leaving a sentinel.
+ *
+ * `renderer.html` escapes raw HTML unconditionally — the transcript body is model
+ * and tool output, so nothing in it may round-trip as markup. That also escaped
+ * the `<details>` wrapper `--reasoning fold` emits, which is why the disclosure
+ * element has to be reconstructed here instead of allowlisted through.
+ *
+ * Allowlisting was tried twice and is the wrong shape: marked hands the same
+ * markup over as several different raw strings depending on context (a whole-token
+ * gate passed the opening tag and escaped the closing one in a real document), and
+ * a bare `<details>` in ordinary prose is a complete INLINE html token — so prose
+ * that merely mentions the tag would emit a live, unclosed element that swallows
+ * every later turn into it. Reconstructing both ends here makes the pairing
+ * structural: it cannot be unbalanced by anything the transcript contains.
+ */
+export function liftFoldBlocks(markdown) {
+    const blocks = [];
+    // A transcript that literally contains the sentinel must not be able to forge a
+    // disclosure element, so break any occurrence before inserting our own.
+    const safe = markdown.split(FOLD_SENTINEL).join(`${FOLD_SENTINEL[0]}​${FOLD_SENTINEL.slice(1)}`);
+    const text = safe.replace(FOLD_BLOCK, (_match, inner) => {
+        blocks.push(inner);
+        return `${FOLD_SENTINEL}${blocks.length - 1}${FOLD_SENTINEL}`;
+    });
+    return { text, blocks };
+}
+function safeRenderer() {
+    const renderer = new Renderer();
+    renderer.html = ({ raw }) => escapeHtml(raw);
+    const isSafeHref = (href) => /^(https?:|mailto:|#|\/)/i.test(href.trim());
+    renderer.link = ({ href, title, tokens }) => {
+        const text = renderer.parser.parseInline(tokens);
+        if (!isSafeHref(href))
+            return text;
+        const attrs = title ? ` title="${escapeHtml(title)}"` : '';
+        return `<a href="${escapeHtml(href)}"${attrs} rel="noopener noreferrer nofollow">${text}</a>`;
+    };
+    renderer.image = ({ href, title, text }) => {
+        if (!isSafeHref(href))
+            return escapeHtml(text);
+        const attrs = title ? ` title="${escapeHtml(title)}"` : '';
+        return `<img src="${escapeHtml(href)}" alt="${escapeHtml(text)}"${attrs} loading="lazy" />`;
+    };
+    return renderer;
+}
+/** Human duration — "13 minutes", never "12m 49s". */
+export function formatDuration(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 1)
+        return 'under a minute';
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+    const hours = Math.round(ms / 3_600_000);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? '' : 's'}`;
+    const days = Math.round(ms / 86_400_000);
+    return `${days} day${days === 1 ? '' : 's'}`;
+}
+/**
+ * The chips shown under the title.
+ *
+ * Deliberately excludes `account` (an email — the publish-time sensitive-content
+ * scan rejects those, and correctly), `cwd`, and `machine`: a published transcript
+ * should not carry the operator's identity or local paths in its chrome. Host and
+ * repo already ride in the share object's provenance metadata, which is the right
+ * home for them.
+ */
+export function buildChips(session) {
+    const chips = [{ label: 'agent', value: session.agent }];
+    if (session.model)
+        chips.push({ label: 'model', value: session.model });
+    if (session.mode)
+        chips.push({ label: 'mode', value: session.mode });
+    if (session.project)
+        chips.push({ label: 'project', value: session.project });
+    if (session.gitBranch)
+        chips.push({ label: 'branch', value: session.gitBranch });
+    if (session.ticketId)
+        chips.push({ label: 'ticket', value: session.ticketId });
+    const date = (session.timestamp || '').slice(0, 10);
+    if (date)
+        chips.push({ label: 'date', value: date });
+    if (session.durationMs)
+        chips.push({ label: 'duration', value: formatDuration(session.durationMs) });
+    if (session.messageCount)
+        chips.push({ label: 'turns', value: String(session.messageCount) });
+    if (session.toolCallCount)
+        chips.push({ label: 'tools', value: String(session.toolCallCount) });
+    return chips;
+}
+/** Longest title that stays one readable line in the header and the gallery. */
+const TITLE_MAX = 90;
+/**
+ * The page's `<title>` — `deriveLabel()` reads this as the share's gallery label.
+ *
+ * The document heading is derived from the session's first prompt, which in a real
+ * session is routinely a pasted URL plus a file path plus the actual request. Left
+ * whole it renders as a three-line wall above the transcript and an unreadable
+ * gallery row, so it is collapsed to one line and cut at a word boundary. `--label`
+ * overrides it outright.
+ */
+export function sessionPageTitle(session, markdown) {
+    const heading = /^#\s+(.+)$/m.exec(markdown)?.[1]?.replace(/\s+/g, ' ').trim();
+    if (!heading)
+        return `${session.agent} session ${session.shortId || session.id}`;
+    if (heading.length <= TITLE_MAX)
+        return heading;
+    const cut = heading.slice(0, TITLE_MAX);
+    const lastSpace = cut.lastIndexOf(' ');
+    // A single unbroken token longer than the cap (a URL) has no boundary to cut on;
+    // a hard slice beats returning the whole thing.
+    return `${(lastSpace > TITLE_MAX / 2 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+export function renderSessionHtmlDocument(session, markdown, options = {}) {
+    const title = sessionPageTitle(session, markdown);
+    // The <h1> is re-rendered as the page header, so drop it from the body to
+    // avoid printing the title twice.
+    const { text, blocks } = liftFoldBlocks(markdown.replace(/^#\s+.+\n/, ''));
+    const render = (md) => marked.parse(md, { renderer: safeRenderer(), async: false });
+    // Reconstruct each disclosure element around its own separately-rendered
+    // content, so the open/close pairing is ours and cannot be unbalanced by the
+    // transcript.
+    const body = blocks.reduce((html, inner, i) => html.replace(new RegExp(`<p>${FOLD_SENTINEL}${i}${FOLD_SENTINEL}</p>`), 
+    // A FUNCTION replacement, never a string one. String.replace expands `$&`,
+    // `` $` ``, `$'` and `$n` inside a string replacement, and marked turns
+    // `& < > " '` into entities — so reasoning text containing `$'` (bash
+    // ANSI-C quoting), `$&` (sed), or `$<` (make) would splice the matched
+    // sentinel back into the page and destroy the character after it. A
+    // function's return value is inserted verbatim.
+    () => `<details><summary>Reasoning</summary>\n${render(inner)}</details>`), render(text));
+    const chips = buildChips(session)
+        .map((c) => `<span class="chip"><span class="k">${escapeHtml(c.label)}</span>${escapeHtml(c.value)}</span>`)
+        .join('\n      ');
+    const redacted = options.redacted !== false;
+    return `<!DOCTYPE html>
+<html lang="en" data-theme="auto">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex" />
+<title>${escapeHtml(title)}</title>
+<style>
+  :root {
+    --bg: #0a0a0a; --panel: #121212; --border: #262626; --fg: #e5e5e5;
+    --dim: #737373; --accent: #a3e635; --quote: #1a1a1a;
+  }
+  html[data-theme="light"] {
+    --bg: #fafafa; --panel: #ffffff; --border: #e5e5e5; --fg: #171717;
+    --dim: #737373; --accent: #4d7c0f; --quote: #f5f5f5;
+  }
+  @media (prefers-color-scheme: light) {
+    html[data-theme="auto"] {
+      --bg: #fafafa; --panel: #ffffff; --border: #e5e5e5; --fg: #171717;
+      --dim: #737373; --accent: #4d7c0f; --quote: #f5f5f5;
+    }
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--fg);
+    font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Inter, sans-serif;
+    font-size: 15px; line-height: 1.65;
+  }
+  header {
+    border-bottom: 1px solid var(--border); padding: 28px 20px 20px;
+  }
+  header .inner, main { max-width: 900px; margin: 0 auto; }
+  header .mark {
+    color: var(--accent); font-weight: 700; letter-spacing: .5px; font-size: 12px;
+    text-transform: uppercase; font-family: ui-monospace, "JetBrains Mono", Menlo, monospace;
+  }
+  header h1 { font-size: 24px; line-height: 1.3; margin: 10px 0 14px; }
+  .chips { display: flex; flex-wrap: wrap; gap: 6px; }
+  .chip {
+    font-family: ui-monospace, "JetBrains Mono", Menlo, monospace; font-size: 11px;
+    color: var(--fg); background: var(--panel); border: 1px solid var(--border);
+    border-radius: 10px; padding: 2px 9px;
+  }
+  .chip .k { color: var(--dim); margin-right: 6px; }
+  .toggle {
+    float: right; cursor: pointer; background: none; border: 1px solid var(--border);
+    color: var(--dim); border-radius: 6px; padding: 2px 8px; font-size: 14px;
+  }
+  main { padding: 24px 20px 64px; }
+  h2 {
+    font-size: 13px; color: var(--accent); border-bottom: 1px solid var(--border);
+    padding-bottom: 6px; margin: 36px 0 14px; text-transform: uppercase;
+    letter-spacing: 1px; font-family: ui-monospace, "JetBrains Mono", Menlo, monospace;
+  }
+  h3 { font-size: 15px; margin: 26px 0 8px; }
+  h4 { font-size: 13px; color: var(--dim); margin: 20px 0 6px; font-weight: 600; }
+  a { color: var(--accent); }
+  blockquote {
+    margin: 0 0 20px; padding: 12px 16px; background: var(--quote);
+    border-left: 2px solid var(--border); border-radius: 0 6px 6px 0; color: var(--dim);
+  }
+  blockquote p { margin: 0 0 6px; }
+  blockquote p:last-child { margin: 0; }
+  pre {
+    background: var(--panel); border: 1px solid var(--border); border-radius: 6px;
+    padding: 12px 14px; overflow-x: auto;
+  }
+  code {
+    font-family: ui-monospace, "JetBrains Mono", Menlo, monospace; font-size: 12.5px;
+  }
+  :not(pre) > code {
+    background: var(--panel); border: 1px solid var(--border);
+    border-radius: 4px; padding: 1px 5px;
+  }
+  hr { border: none; border-top: 1px solid var(--border); margin: 32px 0; }
+  details { margin: 0 0 12px; }
+  summary { cursor: pointer; color: var(--dim); font-size: 13px; }
+  table { border-collapse: collapse; width: 100%; font-size: 13px; }
+  th, td { border: 1px solid var(--border); padding: 6px 10px; text-align: left; }
+  footer {
+    max-width: 900px; margin: 0 auto; padding: 0 20px 48px;
+    color: var(--dim); font-size: 12px;
+    font-family: ui-monospace, "JetBrains Mono", Menlo, monospace;
+  }
+  footer a { color: var(--dim); }
+</style>
+</head>
+<body>
+<header>
+  <div class="inner">
+    <button class="toggle" id="theme" title="Toggle light and dark">&#9689;</button>
+    <div class="mark">agents session</div>
+    <h1>${escapeHtml(title)}</h1>
+    <div class="chips">
+      ${chips}
+    </div>
+  </div>
+</header>
+<main>
+${body}
+</main>
+<footer>
+  ${redacted ? 'Secret-redacted transcript' : 'Unredacted transcript'} rendered by
+  <a href="https://agents-cli.sh">agents-cli</a> &middot; <code>agents sessions share</code>
+</footer>
+<script>
+  (function () {
+    var root = document.documentElement;
+    var saved = null;
+    try { saved = localStorage.getItem('agents-share-theme'); } catch (e) {}
+    if (saved) root.setAttribute('data-theme', saved);
+    document.getElementById('theme').addEventListener('click', function () {
+      var dark = getComputedStyle(root).getPropertyValue('--bg').trim() === '#0a0a0a';
+      var next = dark ? 'light' : 'dark';
+      root.setAttribute('data-theme', next);
+      try { localStorage.setItem('agents-share-theme', next); } catch (e) {}
+    });
+  })();
+</script>
+</body>
+</html>
+`;
+}