@phnx-labs/agents-cli 1.22.46 → 1.22.49

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

@@ -0,0 +1,102 @@
+import { type SessionStats } from './render.js';
+import type { SessionEvent, SessionMeta } from './types.js';
+/** One drawable step on a session's trajectory — a tool call or a thinking block. */
+export interface TrajectoryStep {
+    /** 1-based position among drawn steps, stable for `--errors-only` and step refs. */
+    ordinal: number;
+    kind: 'tool' | 'thinking';
+    /** Tool name for `kind === 'tool'` (e.g. `Bash`, `Read`, `Task`). */
+    tool?: string;
+    /** The waterfall row this draws on — the tool name, or `think` for reasoning. */
+    lane: string;
+    /** Milliseconds from session start (the earliest event) to this step's start. */
+    startMs: number;
+    /**
+     * Duration in ms. Measured by pairing this `tool_use` with its `tool_result`
+     * on `callId`; when no paired result exists (or the harness omits `callId`),
+     * falls back to the delta to the next event and sets `durationEstimated`.
+     */
+    durationMs: number;
+    /** True when `durationMs` is the next-event fallback, not a measured pairing. */
+    durationEstimated: boolean;
+    /** Structured harness outcome from the paired result; never inferred from text. */
+    outcome?: 'ok' | 'error' | 'unknown';
+    /** Redacted one-line summary (command / path / subagent / pattern). */
+    label: string;
+    /** Redacted, bounded output/evidence snippet from the paired result. */
+    detail?: string;
+    /** An inline `Task`/`Agent` sub-agent branch (a cross-session teammate is lineage). */
+    delegation?: 'inline-task' | 'teammate';
+    /** Output tokens attributed from the nearest following usage event. */
+    outputTokens?: number;
+    /** Harness-native call identity, when present. */
+    callId?: string;
+    /**
+     * For a shell tool call (`Bash`), the effective program the command actually
+     * ran — `git`, `gh`, `agents`, `bun`, `sed`… — extracted by the shared shell
+     * parser (`extractShellPrograms`, wrappers like `timeout`/`sudo`/`agents ssh`
+     * unwrapped). Lets a Bash-dominated trajectory read by what it DID, not a wall
+     * of "Bash". Undefined for non-shell tools or an unparseable command.
+     */
+    program?: string;
+    /** Process exit code from the paired result (or the tool_use event), when the harness recorded one. */
+    exitCode?: number;
+}
+/** An idle stall between two events — a candidate "where did it hang" marker. */
+export interface TrajectoryGap {
+    /** Milliseconds from session start to where the gap begins. */
+    startMs: number;
+    /** How long nothing happened, in ms. */
+    durationMs: number;
+    /** Ordinal of the last step before the gap (0 when the gap precedes step 1). */
+    afterOrdinal: number;
+}
+/** The derived trajectory of one session. */
+export interface SessionTrajectory {
+    session: SessionMeta;
+    /** Wall-clock span of the session in ms (last event − first event). */
+    spanMs: number;
+    steps: TrajectoryStep[];
+    gaps: TrajectoryGap[];
+    /**
+     * Fraction of measured tool time per effective program, summing to ~1 (empty if
+     * no time). Keyed by the same tag the step list and badges use — a shell call's
+     * effective program (`git`, `bun`, `gh`), else the raw tool — so a Bash-heavy
+     * session reads as `git / bun / gh`, never a single opaque `Bash`. The single
+     * source both the HTML and text "where the time went" panels read.
+     */
+    programTimeShare: Record<string, number>;
+    /**
+     * Failed steps — steps whose paired result carried `outcome: 'error'`. Distinct
+     * from `stats.errorCount`, which counts only standalone `type: 'error'` events;
+     * a tool that failed via a `tool_result` outcome is invisible there but counted
+     * here, so this is the truthful "how many calls failed" for the trajectory view.
+     */
+    errorCount: number;
+    /** True when derived labels/details were secret-redacted (false under `--no-redact`). */
+    redacted: boolean;
+    /** Reused wholesale from `computeSummaryStats` — turns, tools, tokens, span. */
+    stats: SessionStats;
+    /** Steps dropped by the `maxSteps` cap, surfaced so truncation is never silent. */
+    truncatedSteps: number;
+}
+export interface BuildTrajectoryOptions {
+    /** Redact derived labels/details (default true; `--no-redact` is local-only). */
+    redact?: boolean;
+    /** Known secret values to mask, from `knownSecretValuesFromEnv()`. */
+    knownSecrets?: readonly string[];
+    /** A gap longer than this (ms) is recorded as an idle stall. Default 120000. */
+    idleThresholdMs?: number;
+    /** Cap on drawn steps; the tail is dropped and counted. Default 5000. */
+    maxSteps?: number;
+}
+/**
+ * Build the derived trajectory for one session's normalized events.
+ *
+ * Pairs each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
+ * reused id — never across ids, and never by arrival order for concurrent calls,
+ * matching `ToolCallCollector.takePending`'s refusal to guess, `tool-calls.ts:509`).
+ * A harness with no parseable transcript (OpenClaw, `parse.ts:186`) yields an empty
+ * event array and therefore an empty trajectory — never a crash or a fabricated one.
+ */
+export declare function buildTrajectory(events: SessionEvent[], meta: SessionMeta, options?: BuildTrajectoryOptions): SessionTrajectory;

package/dist/lib/session/trajectory.js

@@ -0,0 +1,384 @@
+/**
+ * Derived session trajectory model — the one genuinely new computation behind
+ * `agents sessions trace`.
+ *
+ * Nothing in the session pipeline records a per-step DURATION: the indexed tool
+ * call (`tool-calls.ts`) keeps only a start timestamp, and `SessionEvent`
+ * (`types.ts:46`) carries a `tool_use` and its `tool_result` as two separate
+ * events. This module pairs them by `callId` to recover how long each call took,
+ * flags the idle gaps between events (stalls), and rolls the per-tool time up
+ * into a "where the time went" share — all DERIVED from the normalized event
+ * stream, never persisted onto `SessionEvent` or the SQLite `tool_calls` index.
+ *
+ * Pure and framework-free: it takes the parsed `SessionEvent[]` and the session
+ * metadata and returns a plain object the three renderers (HTML / text / JSON)
+ * project. Redaction reuses the same `redactSecrets` path as `render`/`share`
+ * (`redact.ts`), applied to the derived one-line labels; the label is the only
+ * place raw command/argument text reaches the model.
+ *
+ * The types (`SessionTrajectory`, `TrajectoryStep`) are shaped to also carry the
+ * later compare + lineage layouts (a stats block, gaps, and time-share per
+ * session), even though this PR renders only the single-session layout.
+ */
+import { redactSecrets } from '../redact.js';
+import { computeSummaryStats } from './render.js';
+import { extractShellPrograms } 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`
+ * → `bun`). Skipped when a real program follows so a Bash row reads by what it did.
+ */
+const SHELL_NOISE_PROGRAMS = new Set(['export', 'cd', 'set', 'source', '.', 'unset', 'local', 'eval']);
+/**
+ * The effective program a shell command ran, via the shared shell parser
+ * (`extractShellPrograms` — which unwraps the wrappers it knows: `env`, `sudo`,
+ * `agents ssh`; note `timeout` is deliberately NOT a wrapper there, per SES-37,
+ * so `timeout 30 npm test` resolves to `timeout`). On top of that this skips
+ * bare builtins/assignments (`cd`, `export`, …) when a real program follows. For
+ * a pipeline it takes the LEFTMOST effective program (`cat f | grep x` → `cat`),
+ * matching how the parser orders occurrences. Undefined when nothing static is
+ * identifiable. Never executes anything.
+ */
+function effectiveProgram(command) {
+    if (!command)
+        return undefined;
+    const { occurrences, programs } = extractShellPrograms(command);
+    const effective = occurrences.filter((o) => o.role === 'effective').map((o) => o.program);
+    const meaningful = effective.find((p) => !SHELL_NOISE_PROGRAMS.has(p))
+        ?? programs.find((p) => !SHELL_NOISE_PROGRAMS.has(p));
+    return meaningful ?? effective[0] ?? programs[0];
+}
+function toMs(timestamp) {
+    const ms = new Date(timestamp).getTime();
+    return Number.isNaN(ms) ? NaN : ms;
+}
+function firstLine(text) {
+    const nl = text.indexOf('\n');
+    return nl === -1 ? text : text.slice(0, nl);
+}
+function clip(text, max) {
+    const collapsed = firstLine(text).replace(/\s+/g, ' ').trim();
+    return collapsed.length <= max ? collapsed : `${collapsed.slice(0, max - 1)}…`;
+}
+function stringArg(args, ...keys) {
+    if (!args)
+        return undefined;
+    for (const key of keys) {
+        const value = args[key];
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    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.
+ *
+ * This is the single place unredacted command/argument text enters the model, so
+ * it runs through the same `redactSecrets` pass `render`/`share` use. `--no-redact`
+ * (local only) skips that pass; the caller passes `redact: false`.
+ */
+function toolLabel(tool, args, command, redact, knownSecrets) {
+    let raw;
+    const lower = tool.toLowerCase();
+    if (lower === 'bash' || lower === 'shell' || lower === 'run_command' || lower.includes('exec')) {
+        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');
+    }
+    else if (lower === 'grep' || lower === 'glob' || lower === 'search' || lower === 'codebase_search') {
+        raw = stringArg(args, 'pattern', 'query', 'q');
+    }
+    else if (lower === 'task' || lower === 'agent') {
+        const subagent = stringArg(args, 'subagent_type', 'agentType', 'subagent');
+        const description = stringArg(args, 'description', 'prompt');
+        raw = subagent ? (description ? `${subagent}: ${description}` : subagent) : description;
+    }
+    else if (lower === 'webfetch' || lower === 'websearch' || lower === 'web_search') {
+        raw = stringArg(args, 'url', 'query', 'q');
+    }
+    else {
+        raw = stringArg(args, 'command', 'cmd', 'file_path', 'path', 'query', 'pattern', 'url', 'description');
+    }
+    const base = raw && raw.trim().length > 0 ? clip(raw, LABEL_MAX) : tool;
+    return redact ? redactSecrets(base, knownSecrets) : base;
+}
+function resultOutcome(event) {
+    if (event.outcome === 'ok' || event.outcome === 'error' || event.outcome === 'unknown')
+        return event.outcome;
+    if (event.success === true)
+        return 'ok';
+    if (event.success === false)
+        return 'error';
+    if (event.type === 'error')
+        return 'error';
+    return 'unknown';
+}
+function resultDetail(event, redact, knownSecrets) {
+    const text = event.output ?? event.content;
+    if (!text || text.trim().length === 0)
+        return undefined;
+    const clipped = clip(text, DETAIL_MAX);
+    return redact ? redactSecrets(clipped, knownSecrets) : clipped;
+}
+/**
+ * Build the derived trajectory for one session's normalized events.
+ *
+ * Pairs each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
+ * reused id — never across ids, and never by arrival order for concurrent calls,
+ * matching `ToolCallCollector.takePending`'s refusal to guess, `tool-calls.ts:509`).
+ * A harness with no parseable transcript (OpenClaw, `parse.ts:186`) yields an empty
+ * event array and therefore an empty trajectory — never a crash or a fabricated one.
+ */
+export function buildTrajectory(events, meta, options = {}) {
+    const redact = options.redact !== false;
+    const knownSecrets = options.knownSecrets;
+    const idleThreshold = options.idleThresholdMs ?? DEFAULT_IDLE_THRESHOLD_MS;
+    const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+    const stats = computeSummaryStats(events);
+    const firstTs = stats.firstTs;
+    const spanMs = stats.lastTs > stats.firstTs ? stats.lastTs - stats.firstTs : 0;
+    // Absolute ms per event index (NaN when the timestamp is unparseable).
+    const eventMs = events.map((e) => toMs(e.timestamp));
+    // The next event index (after i) that carries a valid timestamp — the anchor
+    // for the next-event duration fallback and for idle-gap detection.
+    const nextValidTs = new Array(events.length).fill(NaN);
+    for (let i = events.length - 1, later = NaN; i >= 0; i--) {
+        nextValidTs[i] = later;
+        if (!Number.isNaN(eventMs[i]))
+            later = eventMs[i];
+    }
+    // Draw a step for each thinking block and each non-local tool_use, in order.
+    // `_local` tool calls (Claude `!`-prefixed shell) are excluded to match the
+    // header's tool count (`computeSummaryStats` skips them, `render.ts:224`).
+    const drafts = [];
+    const pendingByCallId = new Map();
+    for (let i = 0; i < events.length; i++) {
+        const e = events[i];
+        if (e.type === 'thinking') {
+            drafts.push({
+                step: {
+                    ordinal: 0,
+                    kind: 'thinking',
+                    lane: 'think',
+                    startMs: Number.isNaN(eventMs[i]) ? 0 : Math.max(0, eventMs[i] - firstTs),
+                    durationMs: 0,
+                    durationEstimated: true,
+                    label: 'thinking',
+                },
+                eventIndex: i,
+            });
+        }
+        else if (e.type === 'tool_use' && !e._local) {
+            const tool = e.tool || 'unknown';
+            const draftIndex = drafts.length;
+            drafts.push({
+                step: {
+                    ordinal: 0,
+                    kind: 'tool',
+                    tool,
+                    lane: tool,
+                    startMs: Number.isNaN(eventMs[i]) ? 0 : Math.max(0, eventMs[i] - firstTs),
+                    durationMs: 0,
+                    durationEstimated: true,
+                    outcome: 'unknown',
+                    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,
+                    exitCode: typeof e.exitCode === 'number' ? e.exitCode : undefined,
+                },
+                eventIndex: i,
+                callId: e.callId,
+            });
+            if (e.callId) {
+                const queue = pendingByCallId.get(e.callId);
+                if (queue)
+                    queue.push(draftIndex);
+                else
+                    pendingByCallId.set(e.callId, [draftIndex]);
+            }
+        }
+        else if ((e.type === 'tool_result' || e.type === 'error') && e.callId) {
+            // Pair strictly by callId, FIFO within a reused id — never across ids.
+            const queue = pendingByCallId.get(e.callId);
+            if (queue && queue.length > 0) {
+                const draftIndex = queue.shift();
+                drafts[draftIndex].resultEventIndex = i;
+            }
+        }
+    }
+    // Resolve durations, outcomes, and detail now that pairing is complete.
+    for (const draft of drafts) {
+        const { step } = draft;
+        const startAbs = Number.isNaN(eventMs[draft.eventIndex]) ? NaN : eventMs[draft.eventIndex];
+        if (draft.resultEventIndex !== undefined) {
+            const resultEvent = events[draft.resultEventIndex];
+            const resultAbs = eventMs[draft.resultEventIndex];
+            if (!Number.isNaN(startAbs) && !Number.isNaN(resultAbs)) {
+                step.durationMs = Math.max(0, resultAbs - startAbs);
+                step.durationEstimated = false;
+            }
+            step.outcome = resultOutcome(resultEvent);
+            // Prefer the exit code recorded on the paired result; keep the tool_use
+            // event's code (set at draft time) only when the result carries none.
+            if (typeof resultEvent.exitCode === 'number')
+                step.exitCode = resultEvent.exitCode;
+            const detail = resultDetail(resultEvent, redact, knownSecrets);
+            if (detail)
+                step.detail = detail;
+        }
+        else {
+            // No paired result — fall back to the delta to the next timestamped event.
+            const nextAbs = nextValidTs[draft.eventIndex];
+            if (!Number.isNaN(startAbs) && !Number.isNaN(nextAbs)) {
+                step.durationMs = Math.max(0, nextAbs - startAbs);
+            }
+            step.durationEstimated = true;
+        }
+    }
+    // Attribute output tokens: each usage event lands on the most recent tool step
+    // (the nearest following usage from that step's point of view).
+    let lastToolDraft;
+    const draftByEventIndex = new Map();
+    for (const draft of drafts)
+        draftByEventIndex.set(draft.eventIndex, draft);
+    for (let i = 0; i < events.length; i++) {
+        const draft = draftByEventIndex.get(i);
+        if (draft && draft.step.kind === 'tool')
+            lastToolDraft = draft;
+        else if (events[i].type === 'usage' && lastToolDraft) {
+            const out = events[i].outputTokens ?? 0;
+            if (out > 0)
+                lastToolDraft.step.outputTokens = (lastToolDraft.step.outputTokens ?? 0) + out;
+        }
+    }
+    // Number the steps and apply the cap (tail dropped, counted — never silent).
+    let steps = drafts.map((d) => d.step);
+    let truncatedSteps = 0;
+    if (steps.length > maxSteps) {
+        truncatedSteps = steps.length - maxSteps;
+        steps = steps.slice(0, maxSteps);
+    }
+    steps.forEach((step, index) => { step.ordinal = index + 1; });
+    // Idle gaps: a long delta between consecutive timestamped events. `afterOrdinal`
+    // is the last step whose event index precedes the gap.
+    const gaps = [];
+    const orderedTs = [];
+    for (let i = 0; i < events.length; i++) {
+        if (!Number.isNaN(eventMs[i]))
+            orderedTs.push({ index: i, ms: eventMs[i] });
+    }
+    const stepOrdinalAtOrBefore = (eventIndex) => {
+        let ordinal = 0;
+        for (const d of drafts) {
+            if (d.eventIndex <= eventIndex && d.step.ordinal > 0)
+                ordinal = d.step.ordinal;
+            else if (d.eventIndex > eventIndex)
+                break;
+        }
+        return ordinal;
+    };
+    for (let k = 1; k < orderedTs.length; k++) {
+        // A span that OPENS on a `tool_use` is that tool executing (waiting on its
+        // own result), not the agent sitting idle — so it is not a stall. Counting
+        // it double-reports a long `bun test` as both its step duration and a fake
+        // "idle" gap. Only spans that open after a completed boundary are idle.
+        if (events[orderedTs[k - 1].index].type === 'tool_use')
+            continue;
+        const delta = orderedTs[k].ms - orderedTs[k - 1].ms;
+        if (delta > idleThreshold) {
+            gaps.push({
+                startMs: Math.max(0, orderedTs[k - 1].ms - firstTs),
+                durationMs: delta,
+                afterOrdinal: stepOrdinalAtOrBefore(orderedTs[k - 1].index),
+            });
+        }
+    }
+    // Where the time went — measured tool duration share per tool.
+    // Sum tool time by the EFFECTIVE PROGRAM (a shell call's `git`/`bun`/`gh`, else
+    // the raw tool) — the same tag the step list and badges show — so both renderers
+    // read one program-keyed source instead of each re-bucketing the steps.
+    const perProgram = {};
+    let totalToolMs = 0;
+    for (const step of steps) {
+        if (step.kind !== 'tool')
+            continue;
+        const tag = step.program ?? step.tool;
+        if (!tag)
+            continue;
+        perProgram[tag] = (perProgram[tag] ?? 0) + step.durationMs;
+        totalToolMs += step.durationMs;
+    }
+    const programTimeShare = {};
+    if (totalToolMs > 0) {
+        for (const [tag, ms] of Object.entries(perProgram)) {
+            if (ms > 0)
+                programTimeShare[tag] = ms / totalToolMs;
+        }
+    }
+    const errorCount = steps.reduce((n, s) => (s.outcome === 'error' ? n + 1 : n), 0);
+    return { session: meta, spanMs, steps, gaps, programTimeShare, errorCount, redacted: redact, stats, truncatedSteps };
+}

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;