@phnx-labs/agents-cli 1.22.60 → 1.22.61

package/dist/lib/session/trajectory.js

@@ -45,7 +45,7 @@ const SHELL_NOISE_PROGRAMS = new Set(['export', 'cd', 'set', 'source', '.', 'uns
  * matching how the parser orders occurrences. Undefined when nothing static is
  * identifiable. Never executes anything.
  */
-function effectiveProgram(command) {
+export function effectiveProgram(command) {
     if (!command)
         return undefined;
     const { occurrences, programs } = extractShellPrograms(command);
@@ -174,36 +174,26 @@ function resultDetail(event, redact, knownSecrets) {
     const clipped = clip(text, DETAIL_MAX);
     return redact ? redactSecrets(clipped, knownSecrets) : clipped;
 }
+/** Absolute ms per event index (NaN when the timestamp is unparseable). */
+export function eventTimestampsMs(events) {
+    return events.map((e) => toMs(e.timestamp));
+}
 /**
- * Build the derived trajectory for one session's normalized events.
- *
- * Pairs each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
+ * Draw a step for each thinking block and each non-local tool_use, in order, and
+ * pair 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.
+ *
+ * `_local` tool calls (Claude `!`-prefixed shell) are excluded to match the
+ * header's tool count (`computeSummaryStats` skips them, `render.ts:224`).
+ *
+ * The single source of the pairing: both {@link buildTrajectory} and
+ * `buildSessionDetailV2` consume the returned drafts (each draft's `eventIndex` +
+ * `resultEventIndex` are the use/result event indices) so the schema-2 producer
+ * never re-implements the loop. Durations/outcomes are still resolved by the
+ * caller — this only draws and pairs.
  */
-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`).
+export function pairSteps(events, eventMs, firstTs, redact, knownSecrets) {
     const drafts = [];
     const pendingByCallId = new Map();
     for (let i = 0; i < events.length; i++) {
@@ -261,6 +251,35 @@ export function buildTrajectory(events, meta, options = {}) {
             }
         }
     }
+    return drafts;
+}
+/**
+ * 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;
+    const eventMs = eventTimestampsMs(events);
+    // 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];
+    }
+    const drafts = pairSteps(events, eventMs, firstTs, redact, knownSecrets);
     // Resolve durations, outcomes, and detail now that pairing is complete.
     for (const draft of drafts) {
         const { step } = draft;

package/dist/lib/ssh-exec.d.ts

@@ -61,6 +61,36 @@ export declare class RemoteUtf8Accumulator {
     end(): string;
     current(): string;
 }
+/**
+ * How long OpenSSH keeps a multiplex master alive after its last client exits
+ * (`ControlPersist`, in seconds).
+ *
+ * The master only survives while it stays IDLE under this window, so it helps
+ * exactly a *repeated* touch of the same host that arrives within the window; a
+ * touch that arrives after the master has expired pays the full cold TCP+auth
+ * handshake again (~100-300ms direct, up to ~500ms relayed; measured on the live
+ * fleet 2026-08-10, PHNX-2582).
+ *
+ * The repeated same-host touches are the ad-hoc `--device` and fleet fan-out
+ * calls — `sessions --active`, `fleet ping`/`status`, `doctor`, `teams`, a
+ * `--device <box>` command run a few times while working — which arrive in
+ * BURSTS spread over minutes, not on a fixed clock. (The one truly high-frequency
+ * caller, `followHostTask`'s ~1.5s follow poll, was already warm even at 60s and
+ * is not the target here.) At the old 60s window any two touches of the same box
+ * more than a minute apart were both cold, so a burst paid a fresh handshake
+ * almost every time.
+ *
+ * 10 minutes keeps a multi-minute burst warm (3-5ms per reuse) while still
+ * bounding how long an idle master lingers — an important limit, because a reused
+ * master to a box that has since slept costs a ~45s ServerAlive teardown on the
+ * first touch (`ServerAliveInterval=15 × ServerAliveCountMax=3`), and a wider
+ * window would only widen the chance of hitting that. The daemon's periodic
+ * SSH-touching services (`usage-sync`/`auth-sync`) tick every 15 minutes, longer
+ * than this window ON PURPOSE: warming them would need a wider window for a
+ * handshake that is negligible at that cadence. Fan-outs stay bounded regardless
+ * by their own per-peer `timeoutMs`.
+ */
+export declare const SSH_CONTROL_PERSIST_SECONDS: number;
 export declare function controlOpts(): string[];
 /**
  * Compose an ssh connection-option prefix.

package/dist/lib/ssh-exec.js

@@ -87,20 +87,52 @@ export class RemoteUtf8Accumulator {
         return this.value;
     }
 }
+/**
+ * How long OpenSSH keeps a multiplex master alive after its last client exits
+ * (`ControlPersist`, in seconds).
+ *
+ * The master only survives while it stays IDLE under this window, so it helps
+ * exactly a *repeated* touch of the same host that arrives within the window; a
+ * touch that arrives after the master has expired pays the full cold TCP+auth
+ * handshake again (~100-300ms direct, up to ~500ms relayed; measured on the live
+ * fleet 2026-08-10, PHNX-2582).
+ *
+ * The repeated same-host touches are the ad-hoc `--device` and fleet fan-out
+ * calls — `sessions --active`, `fleet ping`/`status`, `doctor`, `teams`, a
+ * `--device <box>` command run a few times while working — which arrive in
+ * BURSTS spread over minutes, not on a fixed clock. (The one truly high-frequency
+ * caller, `followHostTask`'s ~1.5s follow poll, was already warm even at 60s and
+ * is not the target here.) At the old 60s window any two touches of the same box
+ * more than a minute apart were both cold, so a burst paid a fresh handshake
+ * almost every time.
+ *
+ * 10 minutes keeps a multi-minute burst warm (3-5ms per reuse) while still
+ * bounding how long an idle master lingers — an important limit, because a reused
+ * master to a box that has since slept costs a ~45s ServerAlive teardown on the
+ * first touch (`ServerAliveInterval=15 × ServerAliveCountMax=3`), and a wider
+ * window would only widen the chance of hitting that. The daemon's periodic
+ * SSH-touching services (`usage-sync`/`auth-sync`) tick every 15 minutes, longer
+ * than this window ON PURPOSE: warming them would need a wider window for a
+ * handshake that is negligible at that cadence. Fan-outs stay bounded regardless
+ * by their own per-peer `timeoutMs`.
+ */
+export const SSH_CONTROL_PERSIST_SECONDS = 10 * 60;
 /**
  * OpenSSH connection-multiplexing options. The first connection to a host opens
  * a control socket; subsequent connections (even from a *separate* `agents`
  * invocation) reuse it, skipping the TCP+auth handshake — so repeated
  * `--device <name>` calls to the same box feel local instead of paying ~100-300ms
- * each. `ControlPersist=60s` keeps the master alive briefly after the last
- * client exits. `%C` (a short fixed-length hash of local-host/remote/port/user)
- * keeps the socket path well under macOS's 104-char `sun_path` limit.
+ * each. `ControlPersist` keeps the master alive after the last client exits, sized
+ * to span a multi-minute burst of repeated touches — see
+ * {@link SSH_CONTROL_PERSIST_SECONDS} for the value and the rationale. `%C` (a
+ * short fixed-length hash of local-host/remote/port/user) keeps the socket path
+ * well under macOS's 104-char `sun_path` limit.
  *
  * This is **on by default** for every `sshExec`/`sshStream` call: the poll loops
  * (`followHostTask`), readiness probes, and per-host fan-outs are exactly the
  * high-frequency callers that benefit most from socket reuse, and they should
  * never have to remember to opt in. A caller passes `multiplex: false` only for
- * a genuine one-shot where a lingering 60s master is pure overhead.
+ * a genuine one-shot where a lingering master is pure overhead.
  *
  * The socket directory is created lazily; if ssh can't open the control socket
  * it falls back to a normal connection (multiplexing is an optimisation, never a
@@ -126,7 +158,7 @@ export function controlOpts() {
     return [
         '-o', 'ControlMaster=auto',
         '-o', `ControlPath=${path.join(dir, 'cm-%C')}`,
-        '-o', 'ControlPersist=60s',
+        '-o', `ControlPersist=${SSH_CONTROL_PERSIST_SECONDS}s`,
     ];
 }
 /**

package/dist/lib/startup/command-registry.js

@@ -5,7 +5,7 @@ const LOADED_COMMAND_NAMES = [
     'routines', 'monitors', 'projects', 'run', 'open', 'reconnect', 'fork', 'config',
     'models', 'modes', 'trash', 'restore', 'doctor',
     'route', 'harness', 'harnesses', 'secrets', 'menubar', 'sync',
-    'refresh-rules', 'factory', 'insights', 'trace',
+    'refresh-rules', 'factory', 'insights', 'trace', 'reminders',
     'pty', 'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
     'teams', 'cloud', 'message', 'send', 'notify', 'feed',

package/dist/lib/subagents-registry.d.ts

@@ -29,6 +29,17 @@ export interface SubagentTarget {
     occupied(dir: string, name: string): OccupiedEntry[];
     /** Rich metadata for `name`; `null` skips it from the listing. */
     read(dir: string, name: string): SubagentMeta | null;
+    /**
+     * True when the installed subagent `sub` in `dir` byte-matches what `write`
+     * would materialize from `sub.path` NOW — the content-drift check `agents
+     * doctor` uses. Re-renders the CURRENT source through the same transform the
+     * writer uses (never a stored hash), so a prompt-body edit to the source
+     * surfaces as drift even though the filename is unchanged.
+     */
+    matches(dir: string, sub: {
+        name: string;
+        path: string;
+    }): boolean;
 }
 /**
  * Copy every file in `src` into `dest` (created if missing), applying
@@ -55,6 +66,13 @@ export declare function writeSubagentToHome(agent: AgentId, home: string, sub: {
 }): boolean;
 /** Installed subagent names for `agent` under `home` (detector + orphan diff). */
 export declare function listInstalledSubagentNames(agent: AgentId, home: string): string[];
+/**
+ * True when subagent `name` installed for `agent` under `home` byte-matches what
+ * the writer would produce NOW from `sourceDir` — the content-drift predicate
+ * `agents doctor` uses. Returns false when the agent has no registry entry
+ * (nothing could have been written) so an unexpected home copy reads as drift.
+ */
+export declare function subagentContentMatches(agent: AgentId, home: string, name: string, sourceDir: string): boolean;
 /**
  * Rich listing of subagents installed for `agent` under `home`, with parsed
  * metadata. Enumerates names, then reads each -- entries whose metadata is

package/dist/lib/subagents-registry.js

@@ -34,7 +34,17 @@ import * as path from 'path';
 import * as TOML from 'smol-toml';
 import * as yaml from 'yaml';
 import { safeJoin } from './paths.js';
+import { filesContentMatch, normalizeResourceContent } from './resource-content-diff.js';
 import { parseSubagentFrontmatter, transformSubagentForClaude, transformSubagentForCodex, transformSubagentForCopilot, transformSubagentForCursor, transformSubagentForDroid, transformSubagentForGoose, transformSubagentForKiro, transformSubagentForOpenCode, transformSubagentForAntigravity, } from './subagents.js';
+/** Read a file's UTF-8 content, or null when it is missing/unreadable. */
+function readFileSafe(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
 // ── metadata readers (the per-format escape hatch) ───────────────────────────
 /** Frontmatter, skipping files that lack a valid block (claude/grok/droid). */
 function metaFrontmatterSkip(filePath) {
@@ -130,6 +140,13 @@ function flatFile(opts) {
                 return null;
             return { frontmatter, files: [`${name}${opts.ext}`], path: filePath };
         },
+        matches(dir, sub) {
+            const filePath = path.join(dir, `${sub.name}${opts.ext}`);
+            const installed = readFileSafe(filePath);
+            if (installed == null)
+                return false;
+            return normalizeResourceContent(installed) === normalizeResourceContent(opts.transform(sub.path));
+        },
     };
 }
 /** A `<name>/` directory holding one generated `<file>` per subagent. */
@@ -162,6 +179,13 @@ function dirFile(opts) {
                 return null;
             return { frontmatter, files: [opts.file], path: filePath };
         },
+        matches(dir, sub) {
+            const filePath = path.join(dir, sub.name, opts.file);
+            const installed = readFileSafe(filePath);
+            if (installed == null)
+                return false;
+            return normalizeResourceContent(installed) === normalizeResourceContent(opts.transform(sub.path));
+        },
     };
 }
 /** Copy the whole source directory to `<name>/`, detected by `marker`. */
@@ -204,6 +228,49 @@ function dirCopy(opts) {
                 .sort();
             return { frontmatter, files, path: subagentDir };
         },
+        matches(dir, sub) {
+            // dirCopy materializes every source file (with rename) into <dir>/<name>/.
+            // Re-derive the expected file set from source and byte-compare each, so an
+            // edit to any copied file — or an added/removed source file — is drift.
+            const dest = path.join(dir, sub.name);
+            let sourceFiles;
+            try {
+                sourceFiles = fs.readdirSync(sub.path).filter((f) => {
+                    try {
+                        return fs.statSync(path.join(sub.path, f)).isFile();
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            }
+            catch {
+                return false;
+            }
+            const expectedDestNames = new Set();
+            for (const file of sourceFiles) {
+                const destName = opts.rename?.[file] ?? file;
+                expectedDestNames.add(destName);
+                if (!filesContentMatch(path.join(sub.path, file), path.join(dest, destName)))
+                    return false;
+            }
+            // An extra file left in the installed dir (source file removed) is drift.
+            let destFiles;
+            try {
+                destFiles = fs.readdirSync(dest).filter((f) => {
+                    try {
+                        return fs.statSync(path.join(dest, f)).isFile();
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            }
+            catch {
+                return false;
+            }
+            return destFiles.every((f) => expectedDestNames.has(f));
+        },
     };
 }
 // ── the registry ─────────────────────────────────────────────────────────────
@@ -295,6 +362,18 @@ export function listInstalledSubagentNames(agent, home) {
         return [];
     return target.names(target.dir(home));
 }
+/**
+ * True when subagent `name` installed for `agent` under `home` byte-matches what
+ * the writer would produce NOW from `sourceDir` — the content-drift predicate
+ * `agents doctor` uses. Returns false when the agent has no registry entry
+ * (nothing could have been written) so an unexpected home copy reads as drift.
+ */
+export function subagentContentMatches(agent, home, name, sourceDir) {
+    const target = SUBAGENT_TARGETS[agent];
+    if (!target)
+        return false;
+    return target.matches(target.dir(home), { name, path: sourceDir });
+}
 /**
  * Rich listing of subagents installed for `agent` under `home`, with parsed
  * metadata. Enumerates names, then reads each -- entries whose metadata is

package/dist/lib/teams/agents.d.ts

@@ -101,6 +101,18 @@ export { captureProcessStartTime };
  * model_reasoning_effort override). Mode (plan/edit/full) is a separate knob.
  */
 export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
+/**
+ * Append {@link TEAMMATE_PR_POLICY} to a teammate prompt for every WRITE-capable
+ * mode (all but plan, which is read-only and opens no PR). Exported so the CLOUD
+ * dispatch path (`cloudDispatchOptions` in `commands/teams.ts`) applies the SAME
+ * boundary this file's `buildRunArgv` applies to LOCAL and REMOTE teammates. A
+ * cloud teammate is the case that needs it MOST: it runs in the provider's
+ * sandbox, not the shared local version home, so it never inherits the
+ * `merge-guard.sh` PreToolUse hook — the prompt policy is then its ONLY
+ * self-merge layer. Routing every dispatch surface through one helper keeps that
+ * parity from drifting (PHNX-3236).
+ */
+export declare function withTeammatePrPolicy(prompt: string, mode: string): string;
 export declare const VALID_MODES: readonly ["plan", "edit", "auto", "skip", "full"];
 type Mode = 'plan' | 'edit' | 'auto' | 'skip';
 /** Resolve a mode string to a validated Mode, falling back to the given default. */

package/dist/lib/teams/agents.js

@@ -255,6 +255,49 @@ When you're done, provide a brief summary of:
 const CLAUDE_PLAN_MODE_PREFIX = `You are running in HEADLESS PLAN MODE. This mode works like normal plan mode with one exception: you cannot write to ~/.claude/plans/ directory. Instead of writing a plan file, output your complete plan/response as your final message.
 
 `;
+// PHNX-3236: the teammate self-merge boundary, injected as a DISPATCH DEFAULT.
+// A write-capable teammate has `gh pr merge` and authenticates as the repo owner,
+// so it can merge its OWN PR past the required non-author-review gate — which is
+// exactly what happened in the RUSH-2988 wave-1 dispatch (PR #1817, #1820). The
+// root cause was that the boundary lived in per-brief wording: one teammate in the
+// batch was told "open the PR, don't merge" and held off; the others weren't and
+// self-merged. Making it a default the runner appends to every non-plan teammate
+// gives one HARNESS-INDEPENDENT layer instead of relying on each dispatch prompt
+// remembering to say it. The HARD enforcement is merge-guard.sh — a PreToolUse hook
+// the teammate inherits from the shared version home, whose self-authored-verdict
+// exclusion was closed in the same ticket (.agents-system #395) so a verdict a
+// teammate posts on its own PR no longer clears the gate. The two layers do NOT
+// overlap everywhere: hook-capable local/remote teammates get both, but cloud
+// teammates (provider sandbox, no inherited hook) and hook-incapable harnesses
+// (Warp/oz — no hook surface, no allowlist) get ONLY this prompt, so for them it is
+// a soft control. That residual is documented in cli/AGENTS.md §6; server-side
+// branch protection is the client-independent way to close it. This is the
+// harness-independent layer plus the operator hand-off contract, not a replacement
+// for the hard block where the hard block can run.
+const TEAMMATE_PR_POLICY = `
+
+Teammate PR policy (agents teams): when your work opens a pull request, open it and
+hand it off — do NOT merge your OWN PR unless a NON-AUTHOR review verdict has been
+posted on that same PR. You authenticate as the repo owner and share that one
+GitHub identity with every other teammate, so an APPROVE you post on your own PR
+does not count as a non-author review. \`gh pr merge\` on your own PR is blocked by
+merge-guard until a genuine non-author verdict exists on it; never pass --admin or
+otherwise route around that guard. Report the PR as open and let the orchestrator
+or a separate reviewer take it to merge.`;
+/**
+ * Append {@link TEAMMATE_PR_POLICY} to a teammate prompt for every WRITE-capable
+ * mode (all but plan, which is read-only and opens no PR). Exported so the CLOUD
+ * dispatch path (`cloudDispatchOptions` in `commands/teams.ts`) applies the SAME
+ * boundary this file's `buildRunArgv` applies to LOCAL and REMOTE teammates. A
+ * cloud teammate is the case that needs it MOST: it runs in the provider's
+ * sandbox, not the shared local version home, so it never inherits the
+ * `merge-guard.sh` PreToolUse hook — the prompt policy is then its ONLY
+ * self-merge layer. Routing every dispatch surface through one helper keeps that
+ * parity from drifting (PHNX-3236).
+ */
+export function withTeammatePrPolicy(prompt, mode) {
+    return mode === 'plan' ? prompt : prompt + TEAMMATE_PR_POLICY;
+}
 // Canonical modes plus the historical `full` alias (rewritten to `skip` by
 // normalizeModeValue). Keep `full` listed so user-typed CLI flags and stored
 // metadata that pre-date the rename continue to parse.
@@ -2530,6 +2573,14 @@ export class AgentManager {
                 fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
             }
         }
+        // PHNX-3236: append the self-merge boundary to every WRITE-capable teammate,
+        // fresh or resumed. A plan-mode teammate produces no PR (read-only), so it is
+        // skipped to keep its prompt clean; every other mode can open — and could
+        // self-merge — a PR, so the policy rides along regardless of harness. The
+        // hard block is still merge-guard.sh (inherited hook); see TEAMMATE_PR_POLICY.
+        // The cloud dispatch path applies the SAME helper (withTeammatePrPolicy) so
+        // local, remote, and cloud teammates never diverge on this boundary.
+        fullPrompt = withTeammatePrPolicy(fullPrompt, mode);
         // Profile target takes precedence — `agents run <profile>` resolves the
         // host harness, version pin, and env injection in one place. Plain
         // version pins only apply when no profile is selected.

package/dist/lib/traces/schema2-build.d.ts

@@ -0,0 +1,85 @@
+/**
+ * schema2-build — the PRODUCER's per-tool mappers + `buildSessionDetailV2`
+ * (PHNX-3442 step 2, increments 2-4).
+ *
+ * Populates the `SessionStepV2` discriminated union (schema2.ts) from the parsed
+ * session events, reusing the SAME infrastructure the schema-1 path already uses:
+ *
+ *   - the callId pairing loop (`pairSteps` in session/trajectory.ts) — so a step's
+ *     (use event, result event) triple is recovered without a duplicate loop;
+ *   - bash unwrap/tokenize/classify (`session/bash-command.ts`) + the effective
+ *     program resolver (`effectiveProgram`);
+ *   - the meta / whereItWentWrong / surfacedToolFailures / active-time helpers
+ *     factored out of sync.ts (`buildDetailMeta`, `buildWhereItWentWrong`, …).
+ *
+ * The command/patch/output PARSING lives here; the worker stores the shard
+ * opaquely and the console reads the union directly and never reparses (spec §5).
+ *
+ * category / risk / categoryMetrics are DELIBERATELY omitted from the schema-2
+ * detail: the shipped consumer (`decodeSessionDetail` → coerceCategory/Risk/Metrics)
+ * backfills them to the same neutral defaults it uses for schema-1, so computing
+ * them here would be inventing session-level signal this step does not own.
+ */
+import { type BashCategory as ClassifierCategory } from '../session/bash-command.js';
+import { type SessionTrajectory } from '../session/trajectory.js';
+import type { SessionEvent } from '../session/types.js';
+import type { BashAction, BashCategory, SessionStepV2 } from './schema2.js';
+import { activeMsFromTrajectory, type SessionDetail } from './sync.js';
+/**
+ * SessionDetailV2 — the schema-2 shard this producer emits.
+ *
+ * `category` / `risk` / `categoryMetrics` are DELIBERATELY OMITTED. The consumer's
+ * `SessionDetailV2` declares them, but its `decodeSchema2` backfills neutral
+ * defaults via `coerceCategory`/`coerceRisk`/`coerceMetrics` (never throws) — the
+ * same defaulting it applies to schema-1 shards today. This producer does not yet
+ * author those fields (their provenance is the prix/api PHNX-3351 hosted backend,
+ * not agents-cli), so emitting them here would fabricate classification. Omission
+ * is the honest choice and is asserted as a tested contract in
+ * `schema2-fixture.test.ts`. Wire real category/risk here once its source is settled.
+ */
+export interface SessionDetailV2 {
+    schema: 2;
+    id: string;
+    meta: SessionDetail['meta'];
+    steps: SessionStepV2[];
+    gaps: SessionTrajectory['gaps'];
+    truncatedSteps: number;
+    whereItWentWrong: string | null;
+    surfacedToolFailures: Array<{
+        tool?: string;
+        label: string;
+        detail?: string;
+    }>;
+}
+/**
+ * `unwrapCommand` (bash-command.ts) strips VAR=/sudo/cd&&/npx/loops/subshells but
+ * NOT an interpreter wrapper like `/bin/zsh -lc "…"`, `bash -lc '…'`, or `sh -c …`
+ * — the exact shape the managed runner wraps every command in. Peel that first,
+ * then hand the inner payload to the existing unwrapper so all the wrappers it DOES
+ * know still apply. One extra rule, at the source, not a fork of unwrapCommand.
+ */
+export declare function unwrapShellExec(command: string): string;
+/**
+ * Map a classifier `BashCategory` (the rich vcs|build-test|install|… taxonomy) to
+ * the coarse schema-2 `BashCategory` (build|test|git|network|other). `build-test`
+ * needs the argv/subcommand to decide build vs test — `bun test` is test, `bun
+ * build` is build — so this takes the tokenized argv too.
+ */
+export declare function mapBashCategory(cat: ClassifierCategory, argv: string[]): BashCategory;
+/** Build the per-segment BashAction list for a bash command. */
+export declare function buildBashActions(unwrapped: string): BashAction[];
+export interface BuildDetailV2Options {
+    redact?: boolean;
+    knownSecrets?: readonly string[];
+}
+/**
+ * Build the schema-2 per-session detail from a pre-built trajectory and its raw
+ * events. The trajectory supplies meta/gaps/whereItWentWrong/surfacedToolFailures
+ * (via the shared sync.ts helpers) and the truncation count; the raw events supply
+ * the per-tool detail the schema-1 flat step could not carry.
+ *
+ * Re-pairs the events with `pairSteps` (the SAME loop buildTrajectory ran) to
+ * recover each step's (use event, result event) triple, then dispatches per tool.
+ */
+export declare function buildSessionDetailV2(traj: SessionTrajectory, events: SessionEvent[], options?: BuildDetailV2Options): SessionDetailV2;
+export { activeMsFromTrajectory };