@oh-my-pi/pi-wire 18.15.0 → 18.17.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [18.17.0] - 2026-11-06
+
+### Added
+
+- Added shell trace visualization: `ShellTrace` model and TSP `shell` kind for shell runs, node state, and layout.
+- Code views gain score-based line shading, labeled collapsible folds with notes, tones, and hover cards, and an overview strip.
+
+## [18.16.0] - 2026-11-02
+
+### Added
+
+- Added the collab envelope helpers `packEnvelope`, `unpackEnvelope` and `rewriteEnvelopePeer`
+
 ## [18.14.2] - 2026-10-31
 
 ### Added

package/dist/types/index.d.ts

@@ -430,6 +430,19 @@ export declare const COLLAB_PROTO = 3;
 export declare const INTENT_FIELD = "i";
 /** Plaintext envelope prefix: `[4B uint32 BE peerId][sealed payload]`. */
 export declare const ENVELOPE_HEADER_LENGTH = 4;
+/**
+ * Prefix `sealed` with its envelope header. Host→relay: peerId 0 broadcasts to
+ * all guests, peerId N targets guest N. Guest→relay: always 0; the relay
+ * rewrites it to the sender's id.
+ */
+export declare function packEnvelope(peerId: number, sealed: Uint8Array): Uint8Array<ArrayBuffer>;
+/** Split an envelope into its peerId and sealed payload; `null` when shorter than the header. */
+export declare function unpackEnvelope(data: Uint8Array): {
+    peerId: number;
+    payload: Uint8Array;
+} | null;
+/** Rewrite the peerId in place without copying the payload. */
+export declare function rewriteEnvelopePeer(data: Uint8Array, peerId: number): void;
 export declare const ROOM_ID_BYTES = 16;
 /** AES-256-GCM room key; the seal key for every collab frame. */
 export declare const ROOM_KEY_BYTES = 32;
@@ -461,5 +474,7 @@ export type RelayControlToGuest = {
     t: "room-closed";
 };
 export type RelayControlMessage = RelayControlToHost | RelayControlToGuest;
+export * from "./shell-trace.js";
+export * from "./shell-viz.js";
 export * from "./stream.js";
 export * from "./tsp.js";

package/dist/types/shell-trace.d.ts

@@ -0,0 +1,173 @@
+/**
+ * `ShellTrace`: the live model of one embedded-shell run, produced by pi-shell's
+ * `RunTrace` (`crates/pi-shell/src/bash/trace.rs`), polled over napi, carried in
+ * the bash tool's `details.trace`, and forwarded verbatim to Tern as the `shell`
+ * node's props. Every offset is a BYTE offset; UIs convert bytes to characters
+ * when the script is not ASCII. Fields at their default are omitted.
+ */
+/** NodeKind of the engine's AST, snake_case. `assign` and `word` are not statements. */
+export type ShellTraceNodeKind = "and_or" | "pipeline" | "simple" | "brace" | "subshell" | "if" | "while" | "until" | "for" | "arith_for" | "select" | "case" | "arith" | "cond" | "func_def" | "coproc" | "assign" | "word";
+/** How the engine resolved a simple command's name. */
+export type ShellTraceResolved = "function" | "intrinsic" | "tool" | "native" | "device" | "self_shell" | "external" | "not_found" | "none";
+/** Derived at snapshot time (contract §3); always present. */
+export type ShellTraceState = "pending" | "running" | "ok" | "fail" | "skipped";
+export interface ShellTraceRedir {
+    fd: number;
+    op: string;
+    target: string;
+}
+export interface ShellTraceDiag {
+    code: string;
+    message: string;
+}
+/** One AST node of a unit; the unit's `nodes` index is the AstNodeId. */
+export interface ShellTraceNode {
+    k: ShellTraceNodeKind;
+    /** Byte span relative to the unit source. */
+    lo: number;
+    hi: number;
+    /** Parent node id; absent for the root. */
+    p?: number;
+    state: ShellTraceState;
+    /** CmdStart count. */
+    runs?: number;
+    /** CmdStart − CmdEnd. */
+    live?: number;
+    /** Status of the last CmdEnd. */
+    st?: number;
+    /** CmdEnds with a non-zero status. */
+    fails?: number;
+    /** Sum of `dur_ns` over the ended runs. */
+    ns?: number;
+    /** `t_ns` of the last CmdStart, relative to RunStart. */
+    at?: number;
+    /** Last CmdExpanded argv (each arg ≤ 256 bytes, ≤ 64 args). */
+    argv?: string[];
+    /** The full argv length when `argv` was cut. */
+    argc?: number;
+    /** Last CmdExpanded assigns. */
+    env?: [string, string][];
+    res?: ShellTraceResolved;
+    redirs?: ShellTraceRedir[];
+    /** Pipestatus of the last CmdEnd. */
+    pipe?: number[];
+    /** Last IterStart n. */
+    iter?: number;
+    /** LoopEnd iterations. */
+    iters?: number;
+    /** Last Branch decision. */
+    taken?: boolean;
+    /** A Background event named this node. */
+    bg?: boolean;
+    /** Last Spawn pid. */
+    pid?: number;
+    /** Actual last command completion timestamp and trace revision. */
+    end_ns?: number;
+    end_seq?: number;
+}
+/** One compiled unit (a top-level command, or an eval/function body). */
+export interface ShellTraceUnit {
+    /** Byte offset of the unit inside `script`; absent when the unit is not part of the script. */
+    at?: number;
+    /** 1-based script line. */
+    line: number;
+    /** Exact UTF-8 source byte length, including heredocs; absent in older traces. */
+    bytes?: number;
+    /** The unit's source; present only for unlocated units. */
+    source?: string;
+    /** Opaque canonical native syntax archive. Only pi-shell may interpret it. */
+    syntax?: unknown;
+    /** Compiler-known wrapper bytes removed from this unit's displayed source. */
+    projection?: number;
+    /** Script a callout (`timeout`, `git`, `xargs`, …) ran for its operands; its calling command stands for it. */
+    callout?: boolean;
+    nodes: ShellTraceNode[];
+}
+/** Exact output/execution identity; repeated visits to one node have distinct seq values. */
+export interface ShellTraceCommandTag {
+    /** Actual engine field: descendant vprocs without a root run queue use 0.
+     * Do not reject those tags; capture generation and explicit fork events
+     * establish run ownership, while vpid/seq distinguish the producer. */
+    run: number;
+    vpid: number;
+    seq: number;
+}
+/** Proven byte fragment of a decoded scalar spanning different producers.
+ * The containing Output has no single primary producer; these at-most-four
+ * bytes retain the exact contributing executions without guessing ownership. */
+export interface ShellTraceOutputContributor {
+    t_ns: number;
+    bytes: number[];
+    command?: ShellTraceCommandTag;
+    vpid?: number;
+    u?: number;
+    n?: number;
+}
+/** Bounded replay journal entry. Missing u/n explicitly means unknown attribution. */
+export interface ShellTraceHistoryEvent {
+    /** Trace revision, including coalesced output growth. */
+    seq: number;
+    /** Measured monotonic engine/host nanoseconds since RunStart, like node.at. */
+    t_ns: number;
+    /** Original engine event sequence; absent for Output callbacks. */
+    event_seq?: number;
+    /** Zero-based actual minimizer segment submission; lifecycle entries remain real engine events. */
+    segment?: number;
+    /** The last real root RunEnd finalized the entire logical segmented call. */
+    logicalEnd?: boolean;
+    /** Actual host outcome after output/close draining, without replacing engine status. */
+    logicalStatus?: number;
+    /** Actual emitting vproc, present on semantic entries even without a command tag. */
+    vpid?: number;
+    kind: "CmdStart" | "CmdExpanded" | "CmdEnd" | "Pipeline" | "Branch" | "IterStart" | "LoopEnd" | "Background" | "FuncEnter" | "FuncExit" | "Assign" | "RunStart" | "RunEnd" | "Output" | "Diag" | "Exit" | "ErrExit" | "Spawn";
+    u?: number;
+    n?: number;
+    command?: ShellTraceCommandTag;
+    status?: number;
+    dur_ns?: number;
+    pipestatus?: number[];
+    argv?: string[];
+    assigns?: [string, string][];
+    resolved?: ShellTraceResolved;
+    redirs?: ShellTraceRedir[];
+    name?: string;
+    value?: string;
+    full_len?: number;
+    scope?: string;
+    iteration?: number;
+    iterations?: number;
+    taken?: boolean;
+    construct?: string;
+    text?: string;
+    contributors?: ShellTraceOutputContributor[];
+    /** Final visible capture descriptor; merged stderr uses stdout's descriptor. */
+    fd?: number;
+    pid?: number;
+}
+export interface ShellTrace {
+    v: 1;
+    /** Semantic/output revision, including assignments/coalesced bytes; monotonic poll key. */
+    seq: number;
+    /** Root RunEnd status; absent while running. */
+    status?: number;
+    /** Actual root vproc, even if history trimming removed its RunStart. */
+    rootVpid?: number;
+    /** Run clock (ns since RunStart) at the last folded event. */
+    t_ns: number;
+    /** The command text given at construction. */
+    script: string;
+    /** Compiled units, in announce order. */
+    units: ShellTraceUnit[];
+    /** Newest ≤20,000 semantic/output records, ≤2 MiB visible output and ≤8 MiB retained payload.
+     * Adjacent output from the same execution may coalesce; its seq changes
+     * when text grows. Consumers must replace the full journal on revision. */
+    history?: ShellTraceHistoryEvent[];
+    /** True when any replay record or output byte was evicted. */
+    historyTruncated?: boolean;
+    /** The last ≤ 8 diagnostics. */
+    diags?: ShellTraceDiag[];
+}
+/** Validate an untrusted persisted/native trace, including nested nodes and replay entries.
+ * Callers should memoize by input reference; validating a journal is linear in its retained size.
+ * This guard never caches mutable input objects as trusted. */
+export declare function isShellTrace(value: unknown): value is ShellTrace;

package/dist/types/shell-viz.d.ts

@@ -0,0 +1,114 @@
+import type { ShellTraceState } from "./shell-trace.js";
+/** Supported shell presentation modes. */
+export type ShellVizView = "raw" | "pseudo";
+/** Independently toggleable, non-executing presentation transformations. */
+export type ShellVizLayer = "color" | "inline" | "idioms" | "effects" | "unwrap";
+/** Every layer is explicit so persisted preferences have deterministic meaning. */
+export interface ShellVizLayers {
+    color: boolean;
+    inline: boolean;
+    idioms: boolean;
+    effects: boolean;
+    unwrap: boolean;
+}
+/** Per-tool-call preferences. Node identifiers are opaque native `unit:source:node` keys. */
+export interface ShellVizPreferences {
+    view: ShellVizView;
+    layers: ShellVizLayers;
+    split: boolean;
+    /** Number of retained history records applied; absent means live. */
+    cursor?: number;
+    playing: boolean;
+    speed: number;
+    selectedNode?: string;
+    expandedNodes: string[];
+}
+/** Semantic text. All ranges are UTF-16 [lo, hi) in the original outermost source. */
+export interface ShellVizSegment {
+    text: string;
+    /** True only on an executing leaf span; dim other spans while presentation.running. */
+    active?: boolean;
+    /** Actual governing leaf outcome, including failures inside otherwise successful pipelines/chains. */
+    state?: ShellTraceState;
+    /** Actual last leaf CmdEnd clock/sequence; identity is executionNode (or node) + executionSeq. */
+    executedAtNs?: number;
+    executionSeq?: number;
+    /** Space-separated semantic tokens; structural chip/badge tokens survive Color off. */
+    style?: string;
+    /** Source-token identity used only for selection and source links. */
+    node?: string;
+    /** Actual command owning state/completion when this token has a different source identity. */
+    executionNode?: string;
+    range?: [number, number];
+    tip?: string;
+    /** Complete original text revealed by inspection or expansion. */
+    expanded?: string;
+    /** Embedded language, with semantic tokenization already performed. */
+    language?: string;
+}
+/** Heuristic effect annotation, never a guarantee of safety or completeness. */
+export interface ShellVizEffect {
+    kind: "network" | "write" | "destructive" | "secret" | "privilege" | "background";
+    glyph: string;
+    label: string;
+    why: string;
+}
+/** One physical Raw/Pseudo presentation row; structural line breaks are separate rows, not terminal LF text. */
+export interface ShellVizRow {
+    id: string;
+    depth: number;
+    node?: string;
+    range?: [number, number];
+    /** This row contains an active executable leaf, not merely an enclosing scope. */
+    active?: boolean;
+    role?: "stmt" | "head" | "mid" | "tail" | "raw" | "document";
+    state?: ShellTraceState;
+    segments: ShellVizSegment[];
+    effects: ShellVizEffect[];
+    /** Actual last leaf completion, never copied onto enclosing scope/scaffold rows. */
+    executedAtNs?: number;
+    executionSeq?: number;
+    /** Human-readable runtime metadata, not a machine-readable protocol. */
+    meta?: string;
+    detail?: string;
+    /** Latest real variable values whose last setter is represented by this row; never a detached watch strip. */
+    annotations?: ShellVizWatch[];
+}
+/** Latest observed setter of one scoped variable, never a statically guessed runtime value. */
+export interface ShellVizWatch {
+    name: string;
+    value: string;
+    fullLength?: number;
+    scope?: string;
+    /** Proven scope/process identity; unknown binding identity is not replaced with a guessed function frame. */
+    scopeId?: string;
+    /** Owning executable/header AST node, promoted from assignment/word event ids. Absent means unlocated. */
+    node?: string;
+    /** Actual setter span in original outer-script UTF-16 coordinates; absent for unlocated dynamic source. */
+    range?: [number, number];
+    /** Retained journal seq of the actual last setter, so replay moves or removes the annotation. */
+    setterSeq?: number;
+}
+/** Browser-independent presentation shared by ANSI and native GUI renderers. */
+export interface ShellVizPresentation {
+    preferences: ShellVizPreferences;
+    rows: ShellVizRow[];
+    /** Raw counterpart for Pseudo split; empty when that pane is not requested. */
+    original: ShellVizRow[];
+    /** Actual captured stdout/stderr through the replay cursor, in event order. */
+    output: string;
+    /** At least one actual executable leaf is running; dim all inactive content. */
+    running?: boolean;
+    /** Native run has not ended, even when currently between executable leaves. */
+    executing: boolean;
+    /** Canonical latest observed values; consumers render row.annotations, not a detached strip. */
+    watches: ShellVizWatch[];
+    timeline: {
+        length: number;
+        cursor: number;
+        elapsedNs: number;
+        durationNs: number;
+        trimmed?: boolean;
+    };
+    message?: string;
+}

package/dist/types/tsp.d.ts

@@ -17,6 +17,7 @@
  * Unknown fields and verbs are ignored in both directions, so every addition
  * here is optional.
  */
+import type { ShellVizPresentation } from "./shell-viz.js";
 /** Protocol version this build speaks. */
 export declare const TSP_VERSION = 1;
 /** APC identifier: every TSP message body starts with `tsp;`. */
@@ -28,7 +29,7 @@ export declare const TSP_DEFAULT_CREDITS = 2;
 /** One-letter message verb. */
 export type TspVerb = "q" | "o" | "f" | "b" | "x" | "r" | "e";
 /** Every component kind in the v1 vocabulary. */
-export declare const TSP_KINDS: readonly ["col", "row", "card", "section", "rule", "spacer", "text", "md", "code", "diff", "ansi", "math", "image", "media", "kv", "table", "tree", "json", "badge", "kbd", "icon", "spinner", "shimmer", "elapsed", "progress", "rate", "list", "item", "tabs", "editor", "input", "button", "status", "seg", "overlay", "toast", "rows", "picker", "prefs", "tool", "checklist", "agent", "chart", "meter", "effort"];
+export declare const TSP_KINDS: readonly ["col", "row", "card", "section", "rule", "spacer", "text", "md", "code", "diff", "ansi", "math", "image", "media", "kv", "table", "tree", "json", "badge", "kbd", "icon", "spinner", "shimmer", "elapsed", "progress", "rate", "list", "item", "tabs", "editor", "input", "button", "status", "seg", "overlay", "toast", "rows", "picker", "prefs", "tool", "checklist", "agent", "chart", "meter", "effort", "shell"];
 export type TspKind = (typeof TSP_KINDS)[number];
 /** Semantic colour of a node's chrome. */
 export type TspTone = "neutral" | "accent" | "info" | "success" | "warning" | "error" | "pending" | "muted" | "user";
@@ -170,6 +171,33 @@ export interface TspMarkdownProps {
     /** Literal runs drawn as these spans wherever they occur in prose (a sent prompt's chip tokens). */
     marks?: readonly TspSpan[];
 }
+/** One marked line of a {@link TspCodeProps.marks}. */
+export interface TspCodeMark {
+    line: number;
+    tone?: TspTone;
+    heat?: number;
+    /**
+     * Scores in [0, 1] washing the row on the `heat` ramp in place of `heat`'s wash: one flat, several a gradient across
+     * the row, an evenly spaced stop per score from left to right. `heat` still sizes the line's overview bar.
+     */
+    wash?: readonly number[];
+}
+/** A run of lines a {@link TspCodeProps} draws as one row until it is opened. */
+export interface TspCodeFold {
+    /** First and last folded line, in the gutter's numbering. */
+    from: number;
+    to: number;
+    /** The folded row's text, in the code's face (default `… [lines {from}-{to}]`, `… [line {from}]` for one line). */
+    label?: string;
+    /** What the fold hides, after a sparkline of its lines' mark `heat`. */
+    note?: TspText;
+    /** `error` tints the row; any tone colors the note. */
+    tone?: TspTone;
+    /** Drawn open; a click on the folded row (or on an open fold's head) toggles it in place. */
+    open?: boolean;
+    /** A card shown while the pointer rests on the folded row, as the common {@link TspCommonProps.hovercard}. */
+    hovercard?: TspPropNode;
+}
 export interface TspCodeProps {
     text?: string;
     /** The language of text that is no file's (`bash`, `json`); wins over `path`. */
@@ -186,13 +214,23 @@ export interface TspCodeProps {
      */
     nums?: readonly number[];
     numbers?: boolean;
-    marks?: readonly {
-        line: number;
-        tone: TspTone;
-    }[];
+    /**
+     * Marked lines (`line` is the drawn line number). `heat` in [0, 1] washes the row in a heat ramp, `wash` runs that
+     * ramp across it; `tone` draws a bar, and any tone but `accent` also tints an unwashed row. A mark without `heat`
+     * or `wash` has tone `accent` by default; one with only those draws no bar.
+     */
+    marks?: readonly TspCodeMark[];
     wrap?: boolean;
     /** Clamp to the first `lines` drawn lines under a "N more lines" button; gives way inside an open disclosure. */
     preview?: TspPreview;
+    /** Runs of lines drawn folded: sorted, not overlapping; marks inside apply once a fold is open. */
+    folds?: readonly TspCodeFold[];
+    /**
+     * An overview strip above the lines: one bar per line (its height the mark's `heat`, its color the mark's tone),
+     * a band under it over the lines outside folds, and a bracket over the lines in view. A click or drag on it
+     * scrolls the code there.
+     */
+    overview?: boolean;
 }
 export interface TspDiffHunk {
     oldStart: number;
@@ -930,6 +968,27 @@ export interface TspChartProps {
     /** Pixel-free size hint: cell size step for heatmaps, height in lines for bars/spark. */
     size?: "sm" | "md" | "lg";
 }
+/** Engine-produced shell presentation; hosts render rows and forward controls, never syntax or history. */
+export interface TspShellProps {
+    /** Canonical semantic presentation, shared with the ANSI inspector. */
+    presentation: ShellVizPresentation;
+    /** Show replay controls only in the explicitly opened inspector. */
+    inspector?: boolean;
+    /** Changed only by explicit seek/reset/live-mode transitions, clearing native highlight trails. */
+    replayEpoch?: number;
+    /** This mounted call received a real execution-start event, not a settled historical load. */
+    liveOrigin?: boolean;
+    /** Working directory shown ahead of the script when it differs from the project's. */
+    cwd?: string;
+    lang?: "bash" | "zsh";
+    /**
+     * Clamp the command to its first `lines` drawn lines under a "N more lines" button; gives way inside an open
+     * disclosure, and never applies in the inspector. The Raw/Pseudo switch and menu stay on the first line.
+     */
+    preview?: {
+        lines: number;
+    };
+}
 /** Kind-specific props, indexed by kind. */
 export interface TspPropsByKind {
     col: TspColProps;
@@ -977,6 +1036,7 @@ export interface TspPropsByKind {
     chart: TspChartProps;
     meter: TspMeterProps;
     effort: TspEffortProps;
+    shell: TspShellProps;
 }
 /**
  * Props of a node of kind `K`: its kind-specific props plus the common ones.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-wire",
-	"version": "18.15.0",
+	"version": "18.17.0",
 	"description": "Shared wire protocol types for omp packages",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -27,7 +27,7 @@
 	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "bun check --no-script -p tsconfig.json",
 		"lint": "oxlint .",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"

package/src/index.ts

@@ -410,6 +410,30 @@ export const INTENT_FIELD = "i";
 /** Plaintext envelope prefix: `[4B uint32 BE peerId][sealed payload]`. */
 export const ENVELOPE_HEADER_LENGTH = 4;
 
+/**
+ * Prefix `sealed` with its envelope header. Host→relay: peerId 0 broadcasts to
+ * all guests, peerId N targets guest N. Guest→relay: always 0; the relay
+ * rewrites it to the sender's id.
+ */
+export function packEnvelope(peerId: number, sealed: Uint8Array): Uint8Array<ArrayBuffer> {
+	const out = new Uint8Array(ENVELOPE_HEADER_LENGTH + sealed.byteLength);
+	new DataView(out.buffer).setUint32(0, peerId, false);
+	out.set(sealed, ENVELOPE_HEADER_LENGTH);
+	return out;
+}
+
+/** Split an envelope into its peerId and sealed payload; `null` when shorter than the header. */
+export function unpackEnvelope(data: Uint8Array): { peerId: number; payload: Uint8Array } | null {
+	if (data.byteLength < ENVELOPE_HEADER_LENGTH) return null;
+	const peerId = new DataView(data.buffer, data.byteOffset, ENVELOPE_HEADER_LENGTH).getUint32(0, false);
+	return { peerId, payload: data.subarray(ENVELOPE_HEADER_LENGTH) };
+}
+
+/** Rewrite the peerId in place without copying the payload. */
+export function rewriteEnvelopePeer(data: Uint8Array, peerId: number): void {
+	new DataView(data.buffer, data.byteOffset, ENVELOPE_HEADER_LENGTH).setUint32(0, peerId, false);
+}
+
 export const ROOM_ID_BYTES = 16;
 
 /** AES-256-GCM room key; the seal key for every collab frame. */
@@ -447,5 +471,7 @@ export type RelayControlToHost = { t: "peer-joined" | "peer-left"; peer: number
 export type RelayControlToGuest = { t: "room-closed" };
 export type RelayControlMessage = RelayControlToHost | RelayControlToGuest;
 
+export * from "./shell-trace";
+export * from "./shell-viz";
 export * from "./stream";
 export * from "./tsp";

package/src/shell-trace.ts

@@ -0,0 +1,448 @@
+/**
+ * `ShellTrace`: the live model of one embedded-shell run, produced by pi-shell's
+ * `RunTrace` (`crates/pi-shell/src/bash/trace.rs`), polled over napi, carried in
+ * the bash tool's `details.trace`, and forwarded verbatim to Tern as the `shell`
+ * node's props. Every offset is a BYTE offset; UIs convert bytes to characters
+ * when the script is not ASCII. Fields at their default are omitted.
+ */
+
+/** NodeKind of the engine's AST, snake_case. `assign` and `word` are not statements. */
+export type ShellTraceNodeKind =
+	| "and_or"
+	| "pipeline"
+	| "simple"
+	| "brace"
+	| "subshell"
+	| "if"
+	| "while"
+	| "until"
+	| "for"
+	| "arith_for"
+	| "select"
+	| "case"
+	| "arith"
+	| "cond"
+	| "func_def"
+	| "coproc"
+	| "assign"
+	| "word";
+
+/** How the engine resolved a simple command's name. */
+export type ShellTraceResolved =
+	| "function"
+	| "intrinsic"
+	| "tool"
+	| "native"
+	| "device"
+	| "self_shell"
+	| "external"
+	| "not_found"
+	| "none";
+
+/** Derived at snapshot time (contract §3); always present. */
+export type ShellTraceState = "pending" | "running" | "ok" | "fail" | "skipped";
+
+export interface ShellTraceRedir {
+	fd: number;
+	op: string;
+	target: string;
+}
+
+export interface ShellTraceDiag {
+	code: string;
+	message: string;
+}
+
+/** One AST node of a unit; the unit's `nodes` index is the AstNodeId. */
+export interface ShellTraceNode {
+	k: ShellTraceNodeKind;
+	/** Byte span relative to the unit source. */
+	lo: number;
+	hi: number;
+	/** Parent node id; absent for the root. */
+	p?: number;
+	state: ShellTraceState;
+	/** CmdStart count. */
+	runs?: number;
+	/** CmdStart − CmdEnd. */
+	live?: number;
+	/** Status of the last CmdEnd. */
+	st?: number;
+	/** CmdEnds with a non-zero status. */
+	fails?: number;
+	/** Sum of `dur_ns` over the ended runs. */
+	ns?: number;
+	/** `t_ns` of the last CmdStart, relative to RunStart. */
+	at?: number;
+	/** Last CmdExpanded argv (each arg ≤ 256 bytes, ≤ 64 args). */
+	argv?: string[];
+	/** The full argv length when `argv` was cut. */
+	argc?: number;
+	/** Last CmdExpanded assigns. */
+	env?: [string, string][];
+	res?: ShellTraceResolved;
+	redirs?: ShellTraceRedir[];
+	/** Pipestatus of the last CmdEnd. */
+	pipe?: number[];
+	/** Last IterStart n. */
+	iter?: number;
+	/** LoopEnd iterations. */
+	iters?: number;
+	/** Last Branch decision. */
+	taken?: boolean;
+	/** A Background event named this node. */
+	bg?: boolean;
+	/** Last Spawn pid. */
+	pid?: number;
+	/** Actual last command completion timestamp and trace revision. */
+	end_ns?: number;
+	end_seq?: number;
+}
+
+/** One compiled unit (a top-level command, or an eval/function body). */
+export interface ShellTraceUnit {
+	/** Byte offset of the unit inside `script`; absent when the unit is not part of the script. */
+	at?: number;
+	/** 1-based script line. */
+	line: number;
+	/** Exact UTF-8 source byte length, including heredocs; absent in older traces. */
+	bytes?: number;
+	/** The unit's source; present only for unlocated units. */
+	source?: string;
+	/** Opaque canonical native syntax archive. Only pi-shell may interpret it. */
+	syntax?: unknown;
+	/** Compiler-known wrapper bytes removed from this unit's displayed source. */
+	projection?: number;
+	/** Script a callout (`timeout`, `git`, `xargs`, …) ran for its operands; its calling command stands for it. */
+	callout?: boolean;
+	nodes: ShellTraceNode[];
+}
+
+/** Exact output/execution identity; repeated visits to one node have distinct seq values. */
+export interface ShellTraceCommandTag {
+	/** Actual engine field: descendant vprocs without a root run queue use 0.
+	 * Do not reject those tags; capture generation and explicit fork events
+	 * establish run ownership, while vpid/seq distinguish the producer. */
+	run: number;
+	vpid: number;
+	seq: number;
+}
+
+/** Proven byte fragment of a decoded scalar spanning different producers.
+ * The containing Output has no single primary producer; these at-most-four
+ * bytes retain the exact contributing executions without guessing ownership. */
+export interface ShellTraceOutputContributor {
+	t_ns: number;
+	bytes: number[];
+	command?: ShellTraceCommandTag;
+	vpid?: number;
+	u?: number;
+	n?: number;
+}
+
+/** Bounded replay journal entry. Missing u/n explicitly means unknown attribution. */
+export interface ShellTraceHistoryEvent {
+	/** Trace revision, including coalesced output growth. */
+	seq: number;
+	/** Measured monotonic engine/host nanoseconds since RunStart, like node.at. */
+	t_ns: number;
+	/** Original engine event sequence; absent for Output callbacks. */
+	event_seq?: number;
+	/** Zero-based actual minimizer segment submission; lifecycle entries remain real engine events. */
+	segment?: number;
+	/** The last real root RunEnd finalized the entire logical segmented call. */
+	logicalEnd?: boolean;
+	/** Actual host outcome after output/close draining, without replacing engine status. */
+	logicalStatus?: number;
+	/** Actual emitting vproc, present on semantic entries even without a command tag. */
+	vpid?: number;
+	kind:
+		| "CmdStart"
+		| "CmdExpanded"
+		| "CmdEnd"
+		| "Pipeline"
+		| "Branch"
+		| "IterStart"
+		| "LoopEnd"
+		| "Background"
+		| "FuncEnter"
+		| "FuncExit"
+		| "Assign"
+		| "RunStart"
+		| "RunEnd"
+		| "Output"
+		| "Diag"
+		| "Exit"
+		| "ErrExit"
+		| "Spawn";
+	u?: number;
+	n?: number;
+	command?: ShellTraceCommandTag;
+	status?: number;
+	dur_ns?: number;
+	pipestatus?: number[];
+	argv?: string[];
+	assigns?: [string, string][];
+	resolved?: ShellTraceResolved;
+	redirs?: ShellTraceRedir[];
+	name?: string;
+	value?: string;
+	full_len?: number;
+	scope?: string;
+	iteration?: number;
+	iterations?: number;
+	taken?: boolean;
+	construct?: string;
+	text?: string;
+	contributors?: ShellTraceOutputContributor[];
+	/** Final visible capture descriptor; merged stderr uses stdout's descriptor. */
+	fd?: number;
+	pid?: number;
+}
+
+export interface ShellTrace {
+	v: 1;
+	/** Semantic/output revision, including assignments/coalesced bytes; monotonic poll key. */
+	seq: number;
+	/** Root RunEnd status; absent while running. */
+	status?: number;
+	/** Actual root vproc, even if history trimming removed its RunStart. */
+	rootVpid?: number;
+	/** Run clock (ns since RunStart) at the last folded event. */
+	t_ns: number;
+	/** The command text given at construction. */
+	script: string;
+	/** Compiled units, in announce order. */
+	units: ShellTraceUnit[];
+	/** Newest ≤20,000 semantic/output records, ≤2 MiB visible output and ≤8 MiB retained payload.
+	 * Adjacent output from the same execution may coalesce; its seq changes
+	 * when text grows. Consumers must replace the full journal on revision. */
+	history?: ShellTraceHistoryEvent[];
+	/** True when any replay record or output byte was evicted. */
+	historyTruncated?: boolean;
+	/** The last ≤ 8 diagnostics. */
+	diags?: ShellTraceDiag[];
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function finite(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value);
+}
+
+function strings(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item: unknown) => typeof item === "string");
+}
+
+function numbers(value: unknown): value is number[] {
+	return Array.isArray(value) && value.every(finite);
+}
+
+function pairs(value: unknown): value is [string, string][] {
+	return (
+		Array.isArray(value) &&
+		value.every(
+			(item: unknown) =>
+				Array.isArray(item) && item.length === 2 && typeof item[0] === "string" && typeof item[1] === "string",
+		)
+	);
+}
+
+function optional(value: Record<string, unknown>, key: string, check: (item: unknown) => boolean): boolean {
+	return value[key] === undefined || check(value[key]);
+}
+
+function string(value: unknown): value is string {
+	return typeof value === "string";
+}
+
+function boolean(value: unknown): value is boolean {
+	return typeof value === "boolean";
+}
+
+function resolved(value: unknown): value is ShellTraceResolved {
+	return (
+		value === "function" ||
+		value === "intrinsic" ||
+		value === "tool" ||
+		value === "native" ||
+		value === "device" ||
+		value === "self_shell" ||
+		value === "external" ||
+		value === "not_found" ||
+		value === "none"
+	);
+}
+
+function redirection(value: unknown): value is ShellTraceRedir {
+	return record(value) && finite(value.fd) && string(value.op) && string(value.target);
+}
+
+function redirections(value: unknown): value is ShellTraceRedir[] {
+	return Array.isArray(value) && value.every(redirection);
+}
+
+function traceNode(value: unknown): value is ShellTraceNode {
+	if (!record(value) || !finite(value.lo) || !finite(value.hi)) return false;
+	if (
+		!string(value.k) ||
+		![
+			"and_or",
+			"pipeline",
+			"simple",
+			"brace",
+			"subshell",
+			"if",
+			"while",
+			"until",
+			"for",
+			"arith_for",
+			"select",
+			"case",
+			"arith",
+			"cond",
+			"func_def",
+			"coproc",
+			"assign",
+			"word",
+		].includes(value.k)
+	)
+		return false;
+	if (
+		value.state !== "pending" &&
+		value.state !== "running" &&
+		value.state !== "ok" &&
+		value.state !== "fail" &&
+		value.state !== "skipped"
+	)
+		return false;
+	for (const key of ["p", "runs", "live", "st", "fails", "ns", "at", "argc", "iter", "iters", "pid"]) {
+		if (!optional(value, key, finite)) return false;
+	}
+	return (
+		optional(value, "argv", strings) &&
+		optional(value, "env", pairs) &&
+		optional(value, "res", resolved) &&
+		optional(value, "redirs", redirections) &&
+		optional(value, "pipe", numbers) &&
+		optional(value, "taken", boolean) &&
+		optional(value, "bg", boolean)
+	);
+}
+
+function traceUnit(value: unknown): value is ShellTraceUnit {
+	return (
+		record(value) &&
+		finite(value.line) &&
+		optional(value, "at", finite) &&
+		optional(value, "bytes", finite) &&
+		optional(value, "source", string) &&
+		optional(value, "callout", boolean) &&
+		Array.isArray(value.nodes) &&
+		value.nodes.every(traceNode)
+	);
+}
+
+function commandTag(value: unknown): value is ShellTraceCommandTag {
+	return record(value) && finite(value.run) && finite(value.vpid) && finite(value.seq);
+}
+
+function outputContributor(value: unknown): value is ShellTraceOutputContributor {
+	return (
+		record(value) &&
+		finite(value.t_ns) &&
+		Array.isArray(value.bytes) &&
+		value.bytes.every((byte: unknown) => finite(byte) && Number.isInteger(byte) && byte >= 0 && byte <= 255) &&
+		optional(value, "u", finite) &&
+		optional(value, "n", finite) &&
+		optional(value, "vpid", finite) &&
+		optional(value, "command", commandTag)
+	);
+}
+
+function historyEntry(value: unknown): value is ShellTraceHistoryEvent {
+	if (!record(value) || !finite(value.seq) || !finite(value.t_ns)) return false;
+	if (
+		!string(value.kind) ||
+		![
+			"CmdStart",
+			"CmdExpanded",
+			"CmdEnd",
+			"Pipeline",
+			"Branch",
+			"IterStart",
+			"LoopEnd",
+			"Background",
+			"FuncEnter",
+			"FuncExit",
+			"Assign",
+			"RunStart",
+			"RunEnd",
+			"Output",
+			"Diag",
+			"Exit",
+			"ErrExit",
+			"Spawn",
+		].includes(value.kind)
+	)
+		return false;
+	for (const key of [
+		"event_seq",
+		"segment",
+		"logicalStatus",
+		"vpid",
+		"u",
+		"n",
+		"status",
+		"dur_ns",
+		"full_len",
+		"iteration",
+		"iterations",
+		"fd",
+		"pid",
+	]) {
+		if (!optional(value, key, finite)) return false;
+	}
+	for (const key of ["name", "value", "scope", "construct", "text"]) {
+		if (!optional(value, key, string)) return false;
+	}
+	return (
+		optional(value, "argv", strings) &&
+		optional(value, "assigns", pairs) &&
+		optional(value, "redirs", redirections) &&
+		optional(value, "resolved", resolved) &&
+		optional(value, "pipestatus", numbers) &&
+		optional(value, "taken", boolean) &&
+		optional(value, "logicalEnd", boolean) &&
+		optional(value, "command", commandTag) &&
+		optional(value, "contributors", items => Array.isArray(items) && items.every(outputContributor)) &&
+		(value.kind !== "Output" || (string(value.text) && finite(value.fd))) &&
+		(value.kind !== "Assign" ||
+			(string(value.name) && string(value.value) && finite(value.full_len) && string(value.scope)))
+	);
+}
+
+/** Validate an untrusted persisted/native trace, including nested nodes and replay entries.
+ * Callers should memoize by input reference; validating a journal is linear in its retained size.
+ * This guard never caches mutable input objects as trusted. */
+export function isShellTrace(value: unknown): value is ShellTrace {
+	if (!record(value) || value.v !== 1 || !finite(value.seq) || !finite(value.t_ns) || !string(value.script))
+		return false;
+	return (
+		optional(value, "status", finite) &&
+		optional(value, "rootVpid", finite) &&
+		Array.isArray(value.units) &&
+		value.units.every(traceUnit) &&
+		optional(
+			value,
+			"diags",
+			items =>
+				Array.isArray(items) &&
+				items.every((item: unknown) => record(item) && string(item.code) && string(item.message)),
+		) &&
+		optional(value, "history", items => Array.isArray(items) && items.every(historyEntry)) &&
+		optional(value, "historyTruncated", boolean)
+	);
+}

package/src/shell-viz.ts

@@ -0,0 +1,109 @@
+import type { ShellTraceState } from "./shell-trace";
+
+/** Supported shell presentation modes. */
+export type ShellVizView = "raw" | "pseudo";
+/** Independently toggleable, non-executing presentation transformations. */
+export type ShellVizLayer = "color" | "inline" | "idioms" | "effects" | "unwrap";
+/** Every layer is explicit so persisted preferences have deterministic meaning. */
+export interface ShellVizLayers {
+	color: boolean;
+	inline: boolean;
+	idioms: boolean;
+	effects: boolean;
+	unwrap: boolean;
+}
+/** Per-tool-call preferences. Node identifiers are opaque native `unit:source:node` keys. */
+export interface ShellVizPreferences {
+	view: ShellVizView;
+	layers: ShellVizLayers;
+	split: boolean;
+	/** Number of retained history records applied; absent means live. */
+	cursor?: number;
+	playing: boolean;
+	speed: number;
+	selectedNode?: string;
+	expandedNodes: string[];
+}
+/** Semantic text. All ranges are UTF-16 [lo, hi) in the original outermost source. */
+export interface ShellVizSegment {
+	text: string;
+	/** True only on an executing leaf span; dim other spans while presentation.running. */
+	active?: boolean;
+	/** Actual governing leaf outcome, including failures inside otherwise successful pipelines/chains. */
+	state?: ShellTraceState;
+	/** Actual last leaf CmdEnd clock/sequence; identity is executionNode (or node) + executionSeq. */
+	executedAtNs?: number;
+	executionSeq?: number;
+	/** Space-separated semantic tokens; structural chip/badge tokens survive Color off. */
+	style?: string;
+	/** Source-token identity used only for selection and source links. */
+	node?: string;
+	/** Actual command owning state/completion when this token has a different source identity. */
+	executionNode?: string;
+	range?: [number, number];
+	tip?: string;
+	/** Complete original text revealed by inspection or expansion. */
+	expanded?: string;
+	/** Embedded language, with semantic tokenization already performed. */
+	language?: string;
+}
+/** Heuristic effect annotation, never a guarantee of safety or completeness. */
+export interface ShellVizEffect {
+	kind: "network" | "write" | "destructive" | "secret" | "privilege" | "background";
+	glyph: string;
+	label: string;
+	why: string;
+}
+/** One physical Raw/Pseudo presentation row; structural line breaks are separate rows, not terminal LF text. */
+export interface ShellVizRow {
+	id: string;
+	depth: number;
+	node?: string;
+	range?: [number, number];
+	/** This row contains an active executable leaf, not merely an enclosing scope. */
+	active?: boolean;
+	role?: "stmt" | "head" | "mid" | "tail" | "raw" | "document";
+	state?: ShellTraceState;
+	segments: ShellVizSegment[];
+	effects: ShellVizEffect[];
+	/** Actual last leaf completion, never copied onto enclosing scope/scaffold rows. */
+	executedAtNs?: number;
+	executionSeq?: number;
+	/** Human-readable runtime metadata, not a machine-readable protocol. */
+	meta?: string;
+	detail?: string;
+	/** Latest real variable values whose last setter is represented by this row; never a detached watch strip. */
+	annotations?: ShellVizWatch[];
+}
+/** Latest observed setter of one scoped variable, never a statically guessed runtime value. */
+export interface ShellVizWatch {
+	name: string;
+	value: string;
+	fullLength?: number;
+	scope?: string;
+	/** Proven scope/process identity; unknown binding identity is not replaced with a guessed function frame. */
+	scopeId?: string;
+	/** Owning executable/header AST node, promoted from assignment/word event ids. Absent means unlocated. */
+	node?: string;
+	/** Actual setter span in original outer-script UTF-16 coordinates; absent for unlocated dynamic source. */
+	range?: [number, number];
+	/** Retained journal seq of the actual last setter, so replay moves or removes the annotation. */
+	setterSeq?: number;
+}
+/** Browser-independent presentation shared by ANSI and native GUI renderers. */
+export interface ShellVizPresentation {
+	preferences: ShellVizPreferences;
+	rows: ShellVizRow[];
+	/** Raw counterpart for Pseudo split; empty when that pane is not requested. */
+	original: ShellVizRow[];
+	/** Actual captured stdout/stderr through the replay cursor, in event order. */
+	output: string;
+	/** At least one actual executable leaf is running; dim all inactive content. */
+	running?: boolean;
+	/** Native run has not ended, even when currently between executable leaves. */
+	executing: boolean;
+	/** Canonical latest observed values; consumers render row.annotations, not a detached strip. */
+	watches: ShellVizWatch[];
+	timeline: { length: number; cursor: number; elapsedNs: number; durationNs: number; trimmed?: boolean };
+	message?: string;
+}

package/src/tsp.ts

@@ -18,6 +18,8 @@
  * here is optional.
  */
 
+import type { ShellVizPresentation } from "./shell-viz";
+
 /** Protocol version this build speaks. */
 export const TSP_VERSION = 1;
 /** APC identifier: every TSP message body starts with `tsp;`. */
@@ -81,6 +83,7 @@ export const TSP_KINDS = [
 	"chart",
 	"meter",
 	"effort",
+	"shell",
 ] as const;
 
 export type TspKind = (typeof TSP_KINDS)[number];
@@ -223,6 +226,33 @@ export interface TspMarkdownProps {
 	/** Literal runs drawn as these spans wherever they occur in prose (a sent prompt's chip tokens). */
 	marks?: readonly TspSpan[];
 }
+/** One marked line of a {@link TspCodeProps.marks}. */
+export interface TspCodeMark {
+	line: number;
+	tone?: TspTone;
+	heat?: number;
+	/**
+	 * Scores in [0, 1] washing the row on the `heat` ramp in place of `heat`'s wash: one flat, several a gradient across
+	 * the row, an evenly spaced stop per score from left to right. `heat` still sizes the line's overview bar.
+	 */
+	wash?: readonly number[];
+}
+/** A run of lines a {@link TspCodeProps} draws as one row until it is opened. */
+export interface TspCodeFold {
+	/** First and last folded line, in the gutter's numbering. */
+	from: number;
+	to: number;
+	/** The folded row's text, in the code's face (default `… [lines {from}-{to}]`, `… [line {from}]` for one line). */
+	label?: string;
+	/** What the fold hides, after a sparkline of its lines' mark `heat`. */
+	note?: TspText;
+	/** `error` tints the row; any tone colors the note. */
+	tone?: TspTone;
+	/** Drawn open; a click on the folded row (or on an open fold's head) toggles it in place. */
+	open?: boolean;
+	/** A card shown while the pointer rests on the folded row, as the common {@link TspCommonProps.hovercard}. */
+	hovercard?: TspPropNode;
+}
 export interface TspCodeProps {
 	text?: string;
 	/** The language of text that is no file's (`bash`, `json`); wins over `path`. */
@@ -239,10 +269,23 @@ export interface TspCodeProps {
 	 */
 	nums?: readonly number[];
 	numbers?: boolean;
-	marks?: readonly { line: number; tone: TspTone }[];
+	/**
+	 * Marked lines (`line` is the drawn line number). `heat` in [0, 1] washes the row in a heat ramp, `wash` runs that
+	 * ramp across it; `tone` draws a bar, and any tone but `accent` also tints an unwashed row. A mark without `heat`
+	 * or `wash` has tone `accent` by default; one with only those draws no bar.
+	 */
+	marks?: readonly TspCodeMark[];
 	wrap?: boolean;
 	/** Clamp to the first `lines` drawn lines under a "N more lines" button; gives way inside an open disclosure. */
 	preview?: TspPreview;
+	/** Runs of lines drawn folded: sorted, not overlapping; marks inside apply once a fold is open. */
+	folds?: readonly TspCodeFold[];
+	/**
+	 * An overview strip above the lines: one bar per line (its height the mark's `heat`, its color the mark's tone),
+	 * a band under it over the lines outside folds, and a bracket over the lines in view. A click or drag on it
+	 * scrolls the code there.
+	 */
+	overview?: boolean;
 }
 export interface TspDiffHunk {
 	oldStart: number;
@@ -896,6 +939,26 @@ export interface TspChartProps {
 	size?: "sm" | "md" | "lg";
 }
 
+/** Engine-produced shell presentation; hosts render rows and forward controls, never syntax or history. */
+export interface TspShellProps {
+	/** Canonical semantic presentation, shared with the ANSI inspector. */
+	presentation: ShellVizPresentation;
+	/** Show replay controls only in the explicitly opened inspector. */
+	inspector?: boolean;
+	/** Changed only by explicit seek/reset/live-mode transitions, clearing native highlight trails. */
+	replayEpoch?: number;
+	/** This mounted call received a real execution-start event, not a settled historical load. */
+	liveOrigin?: boolean;
+	/** Working directory shown ahead of the script when it differs from the project's. */
+	cwd?: string;
+	lang?: "bash" | "zsh";
+	/**
+	 * Clamp the command to its first `lines` drawn lines under a "N more lines" button; gives way inside an open
+	 * disclosure, and never applies in the inspector. The Raw/Pseudo switch and menu stay on the first line.
+	 */
+	preview?: { lines: number };
+}
+
 /** Kind-specific props, indexed by kind. */
 export interface TspPropsByKind {
 	col: TspColProps;
@@ -943,6 +1006,7 @@ export interface TspPropsByKind {
 	chart: TspChartProps;
 	meter: TspMeterProps;
 	effort: TspEffortProps;
+	shell: TspShellProps;
 }
 
 /**