@linxiraos/pi-tui 1.4.0 → 1.4.1

package/src/tools/json-tree.d.ts

@@ -70,6 +70,8 @@ export interface JsonTreeDescribeOptions {
     openDepth?: number;
     /** Root object keys omitted. Defaults to internal tool argument metadata. */
     hiddenRootKeys?: readonly string[];
+    /** Called after the tree is built if a depth, node or scalar cap left part of the value out. */
+    onTruncated?: () => void;
 }
 /**
  * TSP `tree` of a JSON value: containers become expandable nodes labelled with

package/src/tools/json-tree.ts

@@ -402,6 +402,8 @@ export interface JsonTreeDescribeOptions {
 	openDepth?: number;
 	/** Root object keys omitted. Defaults to internal tool argument metadata. */
 	hiddenRootKeys?: readonly string[];
+	/** Called after the tree is built if a depth, node or scalar cap left part of the value out. */
+	onTruncated?: () => void;
 }
 
 type JsonEntry = readonly [key: string, value: unknown];
@@ -438,6 +440,7 @@ export function describeJsonTree(value: unknown, options: JsonTreeDescribeOption
 	const maxScalarLen = Math.max(1, options.maxScalarLen ?? JSON_TREE_SCALAR_LEN_EXPANDED);
 	const openDepth = options.openDepth ?? JSON_TREE_MAX_DEPTH_COLLAPSED;
 	let budget = Math.max(1, options.maxNodes ?? JSON_TREE_MAX_LINES_EXPANDED);
+	let truncated = false;
 	let nextId = 0;
 	const leaf = (label: readonly TspSpan[]): TspTreeNode => ({ id: `${nextId++}`, label });
 
@@ -445,6 +448,7 @@ export function describeJsonTree(value: unknown, options: JsonTreeDescribeOption
 		const out: TspTreeNode[] = [];
 		for (let index = 0; index < entries.length; index++) {
 			if (budget <= 0) {
+				truncated = true;
 				out.push(leaf([span(`… ${entries.length - index} more`, "dim")]));
 				break;
 			}
@@ -463,17 +467,20 @@ export function describeJsonTree(value: unknown, options: JsonTreeDescribeOption
 			const size = Array.isArray(entry) ? `[${entry.length}]` : `{${entries.length}}`;
 			const label = keySpans.length > 0 ? [...keySpans, span(` ${size}`, "dim")] : [span(size, "dim")];
 			if (entries.length === 0) return { id, label };
+			if (depth >= maxDepth) truncated = true;
 			const children = depth >= maxDepth ? [leaf([span("…", "dim")])] : describeEntries(entries, depth + 1);
 			return { id, label, open: depth < openDepth, children };
 		}
 		const prefix = keySpans.length > 0 ? [...keySpans, span(": ", "muted")] : [];
 		if (typeof entry === "string") {
 			const lines = plainText(entry).split("\n");
+			if (lines.some(line => line.length > maxScalarLen)) truncated = true;
 			const first = clipScalar(lines[0], maxScalarLen);
 			if (lines.length === 1) return { id, label: [...prefix, span(`"${first}"`, "syntaxString")] };
 			const children: TspTreeNode[] = [];
 			for (let index = 0; index < lines.length; index++) {
 				if (budget <= 0) {
+					truncated = true;
 					children.push(leaf([span(`… ${lines.length - index} more lines`, "dim")]));
 					break;
 				}
@@ -499,5 +506,6 @@ export function describeJsonTree(value: unknown, options: JsonTreeDescribeOption
 	} else {
 		nodes = [describeValue(undefined, value, 0)];
 	}
+	if (truncated) options.onTruncated?.();
 	return node("tree", { nodes });
 }

package/src/tools/line-ranges.d.ts

@@ -10,12 +10,19 @@ export interface LineRange {
 export declare const LINE_RANGE_CHUNK_SOURCE: string;
 /** Parse a single `N`, `N-M`, `N-`, `N+K`, or `..`-aliased (`N..M`, `N..`) chunk. Throws via {@link ToolError} on invalid bounds. */
 export declare function parseLineRangeChunk(sel: string): LineRange | null;
+/** What a bare `N` selects in a one-chunk list: lines `N` onward (`:50`), or the single line `N`. */
+export type BareLineMode = "onward" | "single";
 /**
  * Parse a comma-separated list of line ranges (e.g. `5-16,960-973` or `19,59`). Returns
  * the ranges in ascending order with overlapping/adjacent ranges merged so
  * downstream consumers can stream the file in a single forward pass per range.
  */
-export declare function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null;
+export declare function parseLineRanges(sel: string, bare?: BareLineMode): [LineRange, ...LineRange[]] | null;
+/**
+ * Sort non-empty `ranges` by start line and merge the ones that overlap or touch;
+ * an open-ended range (`endLine` undefined) reaches EOF and absorbs every later one.
+ */
+export declare function mergeLineRanges(ranges: readonly LineRange[]): [LineRange, ...LineRange[]];
 /**
  * Extract the line-range component from a read-tool selector that may also
  * carry a verbatim/index display mode (`raw`, `conflicts`) — alone or compounded

package/src/tools/line-ranges.ts

@@ -49,16 +49,19 @@ function parseChunk(sel: string, pinBare: boolean): LineRange | null {
 	return { startLine: rawStart, endLine: rawEnd };
 }
 
+/** What a bare `N` selects in a one-chunk list: lines `N` onward (`:50`), or the single line `N`. */
+export type BareLineMode = "onward" | "single";
+
 /**
  * Parse a comma-separated list of line ranges (e.g. `5-16,960-973` or `19,59`). Returns
  * the ranges in ascending order with overlapping/adjacent ranges merged so
  * downstream consumers can stream the file in a single forward pass per range.
  */
-export function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null {
+export function parseLineRanges(sel: string, bare: BareLineMode = "onward"): [LineRange, ...LineRange[]] | null {
 	const chunks = sel.split(",");
-	// A lone `:50` means "from line 50". Inside a comma list, a bare number is
-	// that one line; otherwise `:19,59` collapses to "from 19 through EOF".
-	const pinBare = chunks.length > 1;
+	// A lone `:50` means "from line 50" unless `bare` pins it. Inside a comma list,
+	// a bare number is that one line; otherwise `:19,59` collapses to "from 19 through EOF".
+	const pinBare = bare === "single" || chunks.length > 1;
 	const parsed: LineRange[] = [];
 	for (const chunk of chunks) {
 		const range = parseChunk(chunk, pinBare);
@@ -66,14 +69,19 @@ export function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null
 		parsed.push(range);
 	}
 	if (parsed.length === 0) return null;
-	parsed.sort((a, b) => a.startLine - b.startLine);
+	return mergeLineRanges(parsed);
+}
 
-	const merged: LineRange[] = [parsed[0]];
-	for (let i = 1; i < parsed.length; i++) {
-		const current = parsed[i];
+/**
+ * Sort non-empty `ranges` by start line and merge the ones that overlap or touch;
+ * an open-ended range (`endLine` undefined) reaches EOF and absorbs every later one.
+ */
+export function mergeLineRanges(ranges: readonly LineRange[]): [LineRange, ...LineRange[]] {
+	const [first, ...rest] = [...ranges].sort((a, b) => a.startLine - b.startLine);
+	const merged: [LineRange, ...LineRange[]] = [first];
+	for (const current of rest) {
 		const last = merged[merged.length - 1];
-		// Open-ended (endLine undefined) means "to EOF" — any later range is absorbed.
-		if (last.endLine === undefined) continue;
+		if (last.endLine === undefined) break;
 		// Merge when current starts within (or immediately after) the last range.
 		if (current.startLine <= last.endLine + 1) {
 			if (current.endLine === undefined || current.endLine > last.endLine) {
@@ -83,7 +91,7 @@ export function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null
 		}
 		merged.push(current);
 	}
-	return merged as [LineRange, ...LineRange[]];
+	return merged;
 }
 
 /**
@@ -98,10 +106,12 @@ export function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null
  */
 export function selectorLineRanges(sel: string | undefined): [LineRange, ...LineRange[]] | undefined {
 	if (!sel) return undefined;
-	for (const chunk of sel.split(":")) {
+	const chunks = sel.split(":");
+	const bare = chunks.some(chunk => chunk.toLowerCase() === "raw") ? "single" : "onward";
+	for (const chunk of chunks) {
 		const lower = chunk.toLowerCase();
 		if (lower === "raw" || lower === "conflicts") continue;
-		const ranges = parseLineRanges(chunk);
+		const ranges = parseLineRanges(chunk, bare);
 		if (ranges) return ranges;
 	}
 	return undefined;

package/src/tools/mcp.d.ts

@@ -63,6 +63,27 @@ export interface MCPResourceContent {
 }
 /** Supported MCP result content blocks retained in display metadata. */
 export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
+/** Server-reported progress of an in-flight MCP request. */
+export interface MCPProgress {
+    progress: number;
+    total?: number;
+    message?: string;
+}
+/**
+ * Read MCP progress fields from an untrusted record: `progress` must be a
+ * finite number; `total` is kept only when finite and `message` only when a
+ * string. Shared by the transports, the Eval bridge, and the status renderer.
+ */
+export declare function parseMCPProgress(value: unknown): MCPProgress | undefined;
+/**
+ * One-line display text for MCP progress, at most `maxWidth` cells: the
+ * message, with `progress/total` when the server reports a total. The bare
+ * progress value appears only when there is no message: without a total it is
+ * an opaque counter, not a percentage. Home paths in the message show as `~`,
+ * and a long message is cut before the count, so the count stays visible.
+ * Every progress display (tool card and both Eval status renderers) uses it.
+ */
+export declare function formatMCPProgress(progress: MCPProgress, maxWidth?: number): string;
 /** MCP result details shared by renderers and programmatic tool consumers. */
 export interface MCPToolDetails {
     /** Server name */
@@ -81,6 +102,8 @@ export interface MCPToolDetails {
     provider?: string;
     /** Provider display name (e.g., "Claude Code", "MCP Config") */
     providerName?: string;
+    /** Latest progress of a running call; present only on partial updates. */
+    progress?: MCPProgress;
     /** Structured output metadata (set by the spill wrapper when output is truncated to an artifact). */
     meta?: OutputMeta;
 }

package/src/tools/mcp.ts

@@ -7,6 +7,7 @@
 import { type Component, Markdown } from "../index";
 
 import type { NativeToolHead, NativeToolView, RenderResultOptions } from "./renderer";
+import { isRecord, sanitizeText } from "@linxiraos/pi-utils";
 import { INTENT_FIELD } from "@linxiraos/pi-wire";
 import { ansi, md } from "../native/describe";
 import type { NativeChild } from "../native/node";
@@ -26,7 +27,8 @@ import {
 	renderJsonTreeLines,
 } from "./json-tree";
 import { formatStyledTruncationWarning, stripOutputNotice } from "./output-meta";
-import { clipCollapsed, formatExpandHint } from "../render/render-utils";
+import { clipCollapsed, flattenLine, formatExpandHint, shortenEmbeddedPaths } from "../render/render-utils";
+import { truncateToWidth, visibleWidth } from "../utils";
 import { formatOutputPaneLines, styleToolOutputLine } from "../render/output-pane";
 import type { StatusLineOptions } from "../render/status-line";
 import { plainToolCard, type ToolCardPhase } from "../render/tool-card";
@@ -388,6 +390,45 @@ export interface MCPResourceContent {
 /** Supported MCP result content blocks retained in display metadata. */
 export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
 
+/** Server-reported progress of an in-flight MCP request. */
+export interface MCPProgress {
+	progress: number;
+	total?: number;
+	message?: string;
+}
+
+/**
+ * Read MCP progress fields from an untrusted record: `progress` must be a
+ * finite number; `total` is kept only when finite and `message` only when a
+ * string. Shared by the transports, the Eval bridge, and the status renderer.
+ */
+export function parseMCPProgress(value: unknown): MCPProgress | undefined {
+	if (!isRecord(value) || typeof value.progress !== "number" || !Number.isFinite(value.progress)) return undefined;
+	const progress: MCPProgress = { progress: value.progress };
+	if (typeof value.total === "number" && Number.isFinite(value.total)) progress.total = value.total;
+	if (typeof value.message === "string") progress.message = value.message;
+	return progress;
+}
+
+/**
+ * One-line display text for MCP progress, at most `maxWidth` cells: the
+ * message, with `progress/total` when the server reports a total. The bare
+ * progress value appears only when there is no message: without a total it is
+ * an opaque counter, not a percentage. Home paths in the message show as `~`,
+ * and a long message is cut before the count, so the count stays visible.
+ * Every progress display (tool card and both Eval status renderers) uses it.
+ */
+export function formatMCPProgress(progress: MCPProgress, maxWidth = 200): string {
+	const message =
+		progress.message === undefined ? "" : shortenEmbeddedPaths(flattenLine(sanitizeText(progress.message)));
+	const amount = progress.total === undefined ? `${progress.progress}` : `${progress.progress}/${progress.total}`;
+	if (!message) return truncateToWidth(amount, maxWidth);
+	if (progress.total === undefined) return truncateToWidth(message, maxWidth);
+	const suffix = ` (${amount})`;
+	const messageWidth = maxWidth - visibleWidth(suffix);
+	return messageWidth > 0 ? `${truncateToWidth(message, messageWidth)}${suffix}` : truncateToWidth(amount, maxWidth);
+}
+
 /** MCP result details shared by renderers and programmatic tool consumers. */
 export interface MCPToolDetails {
 	/** Server name */
@@ -406,6 +447,8 @@ export interface MCPToolDetails {
 	provider?: string;
 	/** Provider display name (e.g., "Claude Code", "MCP Config") */
 	providerName?: string;
+	/** Latest progress of a running call; present only on partial updates. */
+	progress?: MCPProgress;
 	/** Structured output metadata (set by the spill wrapper when output is truncated to an artifact). */
 	meta?: OutputMeta;
 }

package/src/tools/output-meta.d.ts

@@ -110,7 +110,7 @@ export interface OutputMeta {
     /** Capture failure of this output itself; aggregate reports keep source failures on their entries. */
     artifactError?: OutputArtifactError;
     source?: SourceMeta;
-    /** The output is a bounded page of session artifact storage its `source` re-reads with line selectors; spill-to-artifact skips it. */
+    /** The output is a bounded page of a file or session artifact its `source` re-reads with line selectors; spill-to-artifact skips it. */
     pagedSource?: true;
     diagnostics?: DiagnosticMeta;
     limits?: LimitsMeta;

package/src/tools/output-meta.ts

@@ -87,7 +87,7 @@ export interface OutputMeta {
 	/** Capture failure of this output itself; aggregate reports keep source failures on their entries. */
 	artifactError?: OutputArtifactError;
 	source?: SourceMeta;
-	/** The output is a bounded page of session artifact storage its `source` re-reads with line selectors; spill-to-artifact skips it. */
+	/** The output is a bounded page of a file or session artifact its `source` re-reads with line selectors; spill-to-artifact skips it. */
 	pagedSource?: true;
 	diagnostics?: DiagnosticMeta;
 	limits?: LimitsMeta;

package/src/tools/read.d.ts

@@ -71,8 +71,14 @@ export interface ReadToolDetails {
      */
     displayReadTargetLinks?: Array<string | null>;
 }
-/** Split a filesystem path from its trailing read selector. */
-export declare function splitPathAndSel(rawPath: string): {
+/**
+ * Split a filesystem path from its trailing read selector. `foldListColons: false`
+ * keeps a colon repeated inside a list as part of the path (`a:1-30,:-30` peels
+ * only `:-30`), for callers checking whether that shorter split names a real file.
+ */
+export declare function splitPathAndSel(rawPath: string, options?: {
+    foldListColons?: boolean;
+}): {
     path: string;
     sel?: string;
 };

package/src/tools/read.ts

@@ -104,11 +104,13 @@ export interface ReadToolDetails {
 // Parsing also recognizes incomplete counts to explain their errors; path splitting
 // only peels complete selectors (not a trailing `+` or `L`).
 const RANGE_SELECTOR_CHUNK = `${LINE_RANGE_CHUNK_SOURCE}(?<=[\\d.-])`;
-const RANGE_LIST_SRC = `${RANGE_SELECTOR_CHUNK}(?:,${RANGE_SELECTOR_CHUNK})*`;
 // A tail selector: `-N` reads the last N lines. Keep in sync with TAIL_SELECTOR_RE.
 const TAIL_CHUNK_SRC = String.raw`-\d+`;
-const FILE_LINE_RANGE_RE = new RegExp(`^(?:${RANGE_LIST_SRC}|${TAIL_CHUNK_SRC}|raw|conflicts|img)$`, "i");
-const FILE_LINE_RANGE_ONLY_RE = new RegExp(`^(?:${RANGE_LIST_SRC}|${TAIL_CHUNK_SRC})$`, "i");
+// A comma list may mix ranges and tails (`1-12,-15`); a lone tail is a one-chunk list.
+const LIST_CHUNK_SRC = `(?:${RANGE_SELECTOR_CHUNK}|${TAIL_CHUNK_SRC})`;
+const RANGE_LIST_SRC = `${LIST_CHUNK_SRC}(?:,${LIST_CHUNK_SRC})*`;
+const FILE_LINE_RANGE_RE = new RegExp(`^(?:${RANGE_LIST_SRC}|raw|conflicts|img)$`, "i");
+const FILE_LINE_RANGE_ONLY_RE = new RegExp(`^(?:${RANGE_LIST_SRC})$`, "i");
 const FILE_RAW_ONLY_RE = /^raw$/i;
 // Permissive selector chunk for internal URLs — accepts well-formed selectors
 // plus common malformed shapes (e.g. `:-N-M`) so the read tool peels the entire
@@ -117,8 +119,33 @@ const INTERNAL_URL_SELECTOR_PART_RE = new RegExp(
 	String.raw`^(?:raw|conflicts|img|${RANGE_LIST_SRC}|-\d+(?:[-+]\d+)?)$`,
 	"i",
 );
-/** Split a filesystem path from its trailing read selector. */
-export function splitPathAndSel(rawPath: string): { path: string; sel?: string } {
+
+/**
+ * Fold the list chunks that repeat the selector colon after a comma (`a:1-30,:-30`)
+ * into the `list` that follows them, so the pair reads as `a:1-30,-30`. Only
+ * colons at or after `minColon` count. Each chunk is tested once.
+ */
+function foldRepeatedListColons(basePath: string, list: string, minColon: number): { basePath: string; list: string } {
+	const chunks = [list];
+	while (basePath.endsWith(",")) {
+		const colon = basePath.lastIndexOf(":");
+		const chunk = basePath.slice(colon + 1, -1);
+		if (colon < minColon || !FILE_LINE_RANGE_ONLY_RE.test(chunk)) break;
+		chunks.push(chunk);
+		basePath = basePath.slice(0, colon);
+	}
+	return { basePath, list: chunks.reverse().join(",") };
+}
+
+/**
+ * Split a filesystem path from its trailing read selector. `foldListColons: false`
+ * keeps a colon repeated inside a list as part of the path (`a:1-30,:-30` peels
+ * only `:-30`), for callers checking whether that shorter split names a real file.
+ */
+export function splitPathAndSel(
+	rawPath: string,
+	options?: { foldListColons?: boolean },
+): { path: string; sel?: string } {
 	const colon = rawPath.lastIndexOf(":");
 	if (colon <= 0) return { path: rawPath };
 
@@ -126,25 +153,33 @@ export function splitPathAndSel(rawPath: string): { path: string; sel?: string }
 	if (!FILE_LINE_RANGE_RE.test(candidate)) return { path: rawPath };
 
 	let basePath = rawPath.slice(0, colon);
-	let sel = candidate;
-
 	// Allow a compound trailing selector: `path:1-50:raw`, `path:raw:1-50`, or
-	// `path:raw:-60`. The two chunks must be one line-range (or tail) plus one
-	// `raw`, in either order.
-	const innerColon = basePath.lastIndexOf(":");
-	if (innerColon > 0) {
+	// `path:raw:-60`. The two chunks must be one line list (ranges and tails)
+	// plus one `raw`, in either order.
+	let list: string | undefined;
+	let rawSuffix = "";
+	if (FILE_LINE_RANGE_ONLY_RE.test(candidate)) {
+		list = candidate;
+	} else if (FILE_RAW_ONLY_RE.test(candidate)) {
+		const innerColon = basePath.lastIndexOf(":");
 		const innerCandidate = basePath.slice(innerColon + 1);
-		const innerIsRaw = FILE_RAW_ONLY_RE.test(innerCandidate);
-		const outerIsRaw = FILE_RAW_ONLY_RE.test(candidate);
-		const innerIsRange = FILE_LINE_RANGE_ONLY_RE.test(innerCandidate);
-		const outerIsRange = FILE_LINE_RANGE_ONLY_RE.test(candidate);
-		if ((innerIsRaw && outerIsRange) || (innerIsRange && outerIsRaw)) {
-			sel = `${innerCandidate}:${candidate}`;
+		if (innerColon > 0 && FILE_LINE_RANGE_ONLY_RE.test(innerCandidate)) {
+			list = innerCandidate;
+			rawSuffix = `:${candidate}`;
 			basePath = basePath.slice(0, innerColon);
 		}
 	}
+	if (list === undefined) return { path: basePath, sel: candidate };
 
-	return { path: basePath, sel };
+	if (options?.foldListColons !== false) ({ basePath, list } = foldRepeatedListColons(basePath, list, 1));
+	if (!rawSuffix) {
+		const innerColon = basePath.lastIndexOf(":");
+		const innerCandidate = basePath.slice(innerColon + 1);
+		if (innerColon > 0 && FILE_RAW_ONLY_RE.test(innerCandidate)) {
+			return { path: basePath.slice(0, innerColon), sel: `${innerCandidate}:${list}` };
+		}
+	}
+	return { path: basePath, sel: `${list}${rawSuffix}` };
 }
 
 /**
@@ -189,9 +224,17 @@ export function splitInternalUrlSel(
 		// Stop before crossing into the scheme separator `://`.
 		if (colon < schemeEnd) break;
 		const tail = path.slice(colon + 1);
-		if (!INTERNAL_URL_SELECTOR_PART_RE.test(tail)) break;
-		chunks.unshift(tail);
-		path = path.slice(0, colon);
+		if (INTERNAL_URL_SELECTOR_PART_RE.test(tail)) {
+			chunks.unshift(tail);
+			path = path.slice(0, colon);
+			continue;
+		}
+		// `artifact://7:1-30,:-30`: a list chunk ending in a comma joins the list peeled after it.
+		if (chunks.length === 0 || !FILE_LINE_RANGE_ONLY_RE.test(chunks[0])) break;
+		const folded = foldRepeatedListColons(path, chunks[0], schemeEnd);
+		if (folded.basePath === path) break;
+		chunks[0] = folded.list;
+		path = folded.basePath;
 	}
 	if (chunks.length === 0) return { path: rawPath };
 	return { path, sel: chunks.join(":") };

package/src/tools/renderer.d.ts

@@ -27,8 +27,9 @@ export interface RenderResultOptions {
     executionStarted?: boolean;
     /**
      * Milliseconds since this call began executing (`tool_execution_start`),
-     * or its total once settled; undefined before it starts. Native describe
-     * hooks only.
+     * or its total once settled; undefined before it starts. The terminal
+     * transcript's options object computes it on read, so a render-time read
+     * is live while the block's spinner ticks.
      */
     elapsedMs?: number;
     /** The call was abandoned without a final result (turn aborted, sealed). Native describe hooks only. */
@@ -177,6 +178,11 @@ export interface ToolRenderer<TArgs = unknown, TDetails = unknown> {
      * `options.spinnerFrame`.
      */
     animatedPartialResult?: boolean | ((args: TArgs) => boolean);
+    /**
+     * Repaint the block once a second while its call executes, for renderers
+     * that show live `options.elapsedMs` without consuming the spinner frame.
+     */
+    tickElapsed?: boolean;
     /**
      * Whether replacing a pending call render with the first result requires a
      * full viewport repaint. Use for merged renderers whose pending rows can be

package/src/tools/renderer.ts

@@ -28,8 +28,9 @@ export interface RenderResultOptions {
 	executionStarted?: boolean;
 	/**
 	 * Milliseconds since this call began executing (`tool_execution_start`),
-	 * or its total once settled; undefined before it starts. Native describe
-	 * hooks only.
+	 * or its total once settled; undefined before it starts. The terminal
+	 * transcript's options object computes it on read, so a render-time read
+	 * is live while the block's spinner ticks.
 	 */
 	elapsedMs?: number;
 	/** The call was abandoned without a final result (turn aborted, sealed). Native describe hooks only. */
@@ -195,6 +196,11 @@ export interface ToolRenderer<TArgs = unknown, TDetails = unknown> {
 	 * `options.spinnerFrame`.
 	 */
 	animatedPartialResult?: boolean | ((args: TArgs) => boolean);
+	/**
+	 * Repaint the block once a second while its call executes, for renderers
+	 * that show live `options.elapsedMs` without consuming the spinner frame.
+	 */
+	tickElapsed?: boolean;
 	/**
 	 * Whether replacing a pending call render with the first result requires a
 	 * full viewport repaint. Use for merged renderers whose pending rows can be

package/src/tools/result-card.d.ts

@@ -16,5 +16,5 @@ export interface CardToolResult {
 export declare function firstText(result: CardToolResult): string;
 /** Sanitize one display line: tabs become spaces, carriage returns are dropped. */
 export declare function safe(value: string): string;
-/** Padded card whose lines are sanitized and truncated, re-rendered when the expanded state flips. */
+/** Card whose lines are sanitized and truncated, re-rendered when the expanded state flips. */
 export declare function card(lines: (width: number, expanded: boolean) => string[], options: RenderResultOptions): Component;

package/src/tools/result-card.ts

@@ -23,7 +23,7 @@ export function safe(value: string): string {
 	return replaceTabs(value).replace(/\r/g, "");
 }
 
-/** Padded card whose lines are sanitized and truncated, re-rendered when the expanded state flips. */
+/** Card whose lines are sanitized and truncated, re-rendered when the expanded state flips. */
 export function card(lines: (width: number, expanded: boolean) => string[], options: RenderResultOptions): Component {
 	return createCachedComponent(
 		() => Boolean(options.expanded),
@@ -31,6 +31,5 @@ export function card(lines: (width: number, expanded: boolean) => string[], opti
 			lines(width, expanded)
 				.flatMap(line => line.split("\n"))
 				.map(line => truncateToWidth(safe(line), width, Ellipsis.Unicode)),
-		{ paddingX: 1 },
 	);
 }

package/src/tools/streaming-output.d.ts

@@ -261,6 +261,7 @@ export declare class OutputSink {
      * Replace the in-memory buffer with the given text. Used when an upstream
      * minimizer rewrites the captured output after the raw bytes have already
      * been streamed.
+     * The replacement is held to the per-line column cap like streamed output.
      *
      * After this call the buffer is authoritative: streaming counters realign
      * to the replacement, the retained head window is cleared, and head

package/src/tools/streaming-output.ts

@@ -1432,6 +1432,7 @@ export class OutputSink {
 	 * Replace the in-memory buffer with the given text. Used when an upstream
 	 * minimizer rewrites the captured output after the raw bytes have already
 	 * been streamed.
+	 * The replacement is held to the per-line column cap like streamed output.
 	 *
 	 * After this call the buffer is authoritative: streaming counters realign
 	 * to the replacement, the retained head window is cleared, and head
@@ -1442,23 +1443,24 @@ export class OutputSink {
 	 */
 	replace(text: string): void {
 		this.#clearPendingChunkTimer();
-		this.#buffer = text;
-		this.#bufferBytes = Buffer.byteLength(text, "utf-8");
+		this.#currentLineBytes = 0;
+		this.#columnEllipsisAdded = false;
+		this.#columnDroppedBytes = 0;
+		this.#columnTruncatedLines = 0;
+		// The artifact keeps the replaced stream, so later line numbers no longer match it.
+		this.#columnCutLinesUnmapped = true;
+		const capped = this.#maxColumns > 0 ? this.#applyColumnCap(text, 0) : text;
+		this.#buffer = capped;
+		this.#bufferBytes = Buffer.byteLength(capped, "utf-8");
 		this.#tailUntrimmed = false;
 		this.#head = "";
 		this.#headBytes = 0;
 		this.#headLines = 0;
 		this.#headRetentionDisabled = true;
-		this.#totalBytes = this.#bufferBytes;
+		this.#totalBytes = Buffer.byteLength(text, "utf-8");
 		this.#totalLines = countNewlines(text);
 		this.#sawData = text.length > 0;
 		this.#truncated = false;
-		this.#currentLineBytes = 0;
-		this.#columnEllipsisAdded = false;
-		this.#columnDroppedBytes = 0;
-		this.#columnTruncatedLines = 0;
-		// The artifact keeps the replaced stream, so later line numbers no longer match it.
-		this.#columnCutLinesUnmapped = true;
 		this.#pendingChunk = "";
 		this.#pendingCarriageReturn = false;
 	}

package/src/tools/task.d.ts

@@ -264,6 +264,18 @@ export interface AgentProgress {
     advisor?: boolean;
     /** The agent's latest self-estimate of task completion (0–100), from the periodic `task.completionProbe` side request. */
     completionPercent?: number;
+    /**
+     * The agent's current step in its own words (one line, ≤ 80 chars), from the
+     * same probe reply as {@link completionPercent}. Running rows prefer it over
+     * `lastIntent`; the job widget uses it as its stage line.
+     */
+    stage?: string;
+    /**
+     * What the agent says shows its progress live (one line, ≤ 200 chars), e.g.
+     * "BENCH lines in bg_2 pipe:1, tok_s higher is better, target 70% of roofline";
+     * from the probe reply. Feeds the job widget author's brief; never rendered.
+     */
+    watch?: string;
     /** Data extracted by registered subprocess tool handlers (keyed by tool name) */
     extractedToolData?: Record<string, unknown[]>;
     /**

package/src/tools/task.ts

@@ -760,6 +760,15 @@ function renderAgentProgress(
 
 	// Current tool (if running) or most recent completed tool
 	if (progress.status === "running") {
+		if (progress.stage) {
+			lines.push(
+				truncateTaskRow(
+					`${continuePrefix}${theme.fg("muted", replaceTabs(sanitizeText(progress.stage)))}`,
+					maxWidth,
+					"",
+				),
+			);
+		}
 		if (progress.currentTool) {
 			let toolLine = `${continuePrefix}${theme.tree.hook} ${theme.fg("muted", sanitizeText(progress.currentTool))}`;
 			const toolDetail = toolCallDetail(
@@ -1869,6 +1878,9 @@ function describeProgressAgent(progress: AgentProgress, state: AgentDescribeStat
 					age: progress.currentToolStartMs ? Math.max(0, nowMs - progress.currentToolStartMs) : undefined,
 				}
 			: null;
+	const summary = taskSummary(progress.description || progress.assignment || progress.task);
+	// The agent's own stage line (from its completion probe) rides beside the task while it runs.
+	const stage = running && progress.stage ? plainText(progress.stage) : "";
 	const retry =
 		running && progress.retryState
 			? {
@@ -1883,7 +1895,7 @@ function describeProgressAgent(progress: AgentProgress, state: AgentDescribeStat
 		{
 			name: formatTaskId(progress.id),
 			agent: progress.agent || undefined,
-			task: taskSummary(progress.description || progress.assignment || progress.task) || undefined,
+			task: stage ? (summary ? [span(summary), span(` · ${stage}`, "muted")] : stage) : summary || undefined,
 			status,
 			model: progress.resolvedModelIdentity ?? progress.resolvedModel,
 			thinking: thinkingToken(progress.resolvedThinkingLevel),
@@ -2379,6 +2391,18 @@ export interface AgentProgress {
 	advisor?: boolean;
 	/** The agent's latest self-estimate of task completion (0–100), from the periodic `task.completionProbe` side request. */
 	completionPercent?: number;
+	/**
+	 * The agent's current step in its own words (one line, ≤ 80 chars), from the
+	 * same probe reply as {@link completionPercent}. Running rows prefer it over
+	 * `lastIntent`; the job widget uses it as its stage line.
+	 */
+	stage?: string;
+	/**
+	 * What the agent says shows its progress live (one line, ≤ 200 chars), e.g.
+	 * "BENCH lines in bg_2 pipe:1, tok_s higher is better, target 70% of roofline";
+	 * from the probe reply. Feeds the job widget author's brief; never rendered.
+	 */
+	watch?: string;
 	/** Data extracted by registered subprocess tool handlers (keyed by tool name) */
 	extractedToolData?: Record<string, unknown[]>;
 	/**

package/src/tools/wait.d.ts

@@ -3,6 +3,7 @@ import type { Theme } from "../theme/theme";
 import { type OutputMeta } from "./output-meta";
 import { type ConfiguredThinkingLevel } from "../render/render-utils";
 import type { StructuredSubagentOutput } from "./task";
+import { type JobWidgetView } from "./job-widget";
 import type { RenderResultOptions, ToolActivitySummary } from "./renderer";
 import type { IrcDeliveryReceipt, IrcMessage } from "./irc";
 import type { NativeToolView, ToolRenderResult } from "./renderer";
@@ -29,6 +30,10 @@ export interface JobSnapshot {
     advisor?: boolean;
     /** The task agent's latest self-estimated completion (0–100); see `AgentProgress.completionPercent`. */
     completionPercent?: number;
+    /** The task agent's latest stage in its own words; see `AgentProgress.stage`. */
+    stage?: string;
+    /** The job's live widget, while one is being drawn; frozen at its last state once the job settles. */
+    widget?: JobWidgetView;
     resultText?: string;
     errorText?: string;
     /** Source-output metadata retained for per-job warnings and persisted row rendering. */