@chrok/pi-braid 0.3.1 → 0.3.3

package/dist/display.js

@@ -1,26 +1,46 @@
 import { render as renderMermaid } from "grok-mermaid";
-import { Text, stripTerminalSequences, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+import { Text, sliceByColumn, stripTerminalSequences, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+import { formatActivityStatus, } from "@chrok/braid";
 export const MAX_VISIBLE_EVENTS = 80;
 export const MAX_VISIBLE_NODES = 80;
 class FixedLines {
     lines;
     chartStart;
     chartLength;
-    constructor(lines, chartStart = lines.length, chartLength = 0) {
+    fallback;
+    focusMarks;
+    /**
+     * A too-wide chart is cropped to the terminal width around the first
+     * `focusMarks` entry drawn in it (the selected node, then a running node),
+     * or from its left edge. `fallback` (a node list while selecting) appears when
+     * there is no chart, or when the selected node cannot be found in it.
+     */
+    constructor(lines, chartStart = lines.length, chartLength = 0, fallback = [], focusMarks = []) {
         this.lines = lines;
         this.chartStart = chartStart;
         this.chartLength = chartLength;
+        this.fallback = fallback;
+        this.focusMarks = focusMarks;
     }
     render(width) {
         const chart = this.lines.slice(this.chartStart, this.chartStart + this.chartLength);
-        if (chart.length === 0)
+        const fallback = this.fallback.map((line) => truncateToWidth(line, width, ""));
+        if (chart.length === 0 && fallback.length === 0)
             return this.lines.map((line) => truncateToWidth(line, width, ""));
-        const chartWidth = Math.max(...chart.map((line) => visibleWidth(line)));
-        const chartOutput = chartWidth <= width
-            ? chart
-            : [
-                truncateToWidth(`[Flowchart needs ${chartWidth} columns; terminal width is ${width}. Expand your terminal to see it.]`, width, ""),
+        const chartWidth = chart.length ? Math.max(...chart.map((line) => visibleWidth(line))) : 0;
+        let chartOutput = chart;
+        if (!chart.length)
+            chartOutput = fallback;
+        else if (chartWidth > width) {
+            const focus = this.focus(chart);
+            const start = focus === undefined ? 0 : Math.max(0, Math.min(chartWidth - width, focus.column - Math.floor(width / 2)));
+            chartOutput = [
+                truncateToWidth(`[chart ${start + 1}–${start + width} of ${chartWidth} cols${focus ? ` · ${focus.label}` : ""}]`, width, ""),
+                ...chart.map((line) => sliceByColumn(line, start, width, true)),
+                // The first mark is the selection; list nodes if it is not drawn.
+                ...(this.focusMarks.length && focus?.mark !== this.focusMarks[0].mark ? fallback : []),
             ];
+        }
         const output = [];
         let chartInserted = false;
         for (let index = 0; index < this.lines.length; index++) {
@@ -37,6 +57,22 @@ class FixedLines {
             output.push(...chartOutput);
         return output;
     }
+    /** The first focus mark drawn in the chart and its centre column. */
+    focus(chart) {
+        for (const { mark, label } of this.focusMarks) {
+            for (const line of chart) {
+                const plain = stripTerminalSequences(line);
+                const index = plain.indexOf(mark);
+                if (index < 0)
+                    continue;
+                // Centre on the label: from the mark to the node's right border, when drawn.
+                const border = plain.indexOf("│", index);
+                const end = border < 0 ? index : border;
+                return { mark, label, column: Math.floor((visibleWidth(plain.slice(0, index)) + visibleWidth(plain.slice(0, end))) / 2) };
+            }
+        }
+        return undefined;
+    }
     invalidate() { }
 }
 function record(value) {
@@ -121,7 +157,9 @@ function nodeElapsed(node, now) {
     }
     return "—";
 }
-function mermaidLabelLines(id, result) {
+/** Replaces the selected node's one-column status icon, so selection never moves the layout. */
+export const SELECTED_NODE_MARK = "◆";
+function mermaidLabelLines(id, result, selected = false) {
     const progress = "progress" in result ? result.progress?.[id] : undefined;
     const node = result.nodes[id];
     if (!node)
@@ -140,7 +178,7 @@ function mermaidLabelLines(id, result) {
     const now = "observedAt" in result ? result.observedAt : Date.now();
     const iteration = "executions" in result ? result.executions[node.executionId ?? ""]?.iteration : result.iterations?.[id];
     const lines = [
-        `${icon} ${compact(id, 24)}${iteration ? ` #${iteration}` : ""}`,
+        `${selected ? SELECTED_NODE_MARK + icon.slice(1) : icon} ${compact(id, 24)}${iteration ? ` #${iteration}` : ""}`,
         `${status}${decision} · ${nodeElapsed(node, now)}`,
     ];
     if (progress) {
@@ -152,7 +190,7 @@ function mermaidLabelLines(id, result) {
     }
     return lines;
 }
-function mermaidSource(result) {
+function mermaidSource(result, selected) {
     const parts = graphParts(result);
     const ids = Object.keys(parts.nodes);
     const names = new Map(ids.map((id, index) => [id, `n${index}`]));
@@ -173,15 +211,22 @@ function mermaidSource(result) {
     for (const id of ids) {
         const shape = parts.nodeTypes[id] === "decision" ? "{" : "[";
         const close = parts.nodeTypes[id] === "decision" ? "}" : "]";
-        lines.push(`  ${names.get(id)}${shape}"${mermaidLabelLines(id, result).map(escapeMermaidText).join("<br/>")}"${close}`);
+        lines.push(`  ${names.get(id)}${shape}"${mermaidLabelLines(id, result, id === selected).map(escapeMermaidText).join("<br/>")}"${close}`);
     }
     for (const edge of parts.edges) {
         lines.push(`  ${names.get(edge.from)} -->${edge.choice ? `|${escapeMermaidText(edge.choice)}|` : ""} ${names.get(edge.to)}`);
     }
     return lines.join("\n");
 }
-function mermaidLines(result, theme) {
-    const art = renderMermaid(mermaidSource(result));
+function mermaidLines(result, theme, selected) {
+    let art;
+    try {
+        art = renderMermaid(mermaidSource(result, selected));
+    }
+    catch {
+        // The chart is a view of state already listed elsewhere; never fail the panel for it.
+        return [];
+    }
     if (!art)
         return [];
     return art.styled.map((row) => row
@@ -190,6 +235,8 @@ function mermaidLines(result, theme) {
             case "border":
                 return theme.fg("borderMuted", span.text);
             case "text":
+                if (selected !== undefined && span.text.includes(SELECTED_NODE_MARK))
+                    return theme.bg("selectedBg", theme.bold(theme.fg("warning", span.text)));
                 return span.text.includes("▶ ACTIVE")
                     ? theme.bg("selectedBg", theme.bold(theme.fg("accent", span.text)))
                     : theme.fg("text", span.text);
@@ -428,23 +475,111 @@ export function applyProgress(state, progress) {
         writable: true,
     });
 }
+export const COLLAPSED_ACTIVITY_ENTRIES = 6;
+/** Live phase, waits, and chronological history; absence of activity is shown, not judged. */
+export function renderActivity(activity, expanded, theme, now, part = "all") {
+    const ago = (at) => elapsed(Math.max(0, now - at));
+    if (part === "history")
+        return renderActivity(activity, expanded, theme, now).slice(renderActivity(activity, expanded, theme, now, "summary").length);
+    const lines = [theme.fg(activity.finishedAt === undefined ? "accent" : "muted", `activity: ${compact(formatActivityStatus(activity, now), 200)}`)];
+    const model = activity.model;
+    if (model && model.completedAt === undefined) {
+        lines.push(theme.fg("muted", model.firstStreamAt === undefined
+            ? `  model request #${model.round} sent ${ago(model.startedAt)} ago · no stream events received yet`
+            : `  model request #${model.round} sent ${ago(model.startedAt)} ago · ${model.streamEvents} stream events, ${compactCount(model.receivedChars)} chars · last ${ago(model.lastStreamAt)} ago`));
+        if (model.tail)
+            lines.push(theme.fg("dim", `  receiving ${model.receiving === "tool_call" ? `${compact(model.toolName ?? "tool call", 40)} arguments` : model.receiving ?? "output"}: …${compact(model.tail, 160)}`));
+    }
+    for (const tool of activity.tools) {
+        lines.push(theme.fg("warning", `  tool ${compact(tool.name, 40)} running ${ago(tool.startedAt)} · ${tool.lastOutputAt === undefined ? "no output yet" : `last output ${ago(tool.lastOutputAt)} ago`}`));
+        lines.push(theme.fg("dim", `    args: ${compact(tool.arguments, 200)}`));
+        if (tool.outputTail)
+            lines.push(theme.fg("dim", `    output: …${compact(tool.outputTail, 200)}`));
+    }
+    for (const limitation of activity.limitations)
+        lines.push(theme.fg("muted", `  unavailable: ${compact(limitation, 200)}`));
+    if (part === "summary")
+        return lines;
+    const visible = expanded ? activity.entries : activity.entries.slice(-COLLAPSED_ACTIVITY_ENTRIES);
+    const hidden = activity.droppedEntries + activity.entries.length - visible.length;
+    lines.push(theme.fg("dim", `history · ${activity.sequence} events${hidden ? ` · ${hidden} earlier ${expanded ? "trimmed" : "hidden (expand for more)"}` : ""}:`));
+    for (const entry of visible) {
+        const color = entry.isError ? "error" : entry.kind === "tool_call" ? "accent" : entry.kind === "assistant" ? "text" : "muted";
+        lines.push(theme.fg(color, `  ${`+${elapsed(Math.max(0, entry.timestamp - activity.startedAt))}`.padStart(7)} ${compact(entry.summary, 200)}`));
+        // Show a detail preview only when the summary line does not already contain it.
+        if (expanded && entry.detail && entry.kind !== "workspace" && !compact(entry.summary, 400).includes(compact(entry.detail, 400))) {
+            lines.push(theme.fg("dim", `          ${compact(entry.detail, 300)}${entry.detailLength ? ` (${compactCount(entry.detailLength)} chars)` : ""}`));
+        }
+    }
+    return lines;
+}
 /** Focused status reads must show the requested execution, including historical ones. */
-export function renderNodeResult(node, expanded, theme, fullOutputPath) {
+export function renderNodeResult(node, expanded, theme, fullOutputPath, progress, now = Date.now(), activity) {
     const failed = node.status === "failed";
     const clean = (value) => stripTerminalSequences(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, "");
+    const timing = [
+        ...(node.model ? [`model ${compact(node.model, 60)}`] : []),
+        ...(node.iteration ? [`iteration #${node.iteration}`] : []),
+        ...(node.startedAt !== undefined || node.latencyMs !== undefined ? [`elapsed ${nodeElapsed(node, now)}`] : []),
+        ...(node.usage ? [`${compactCount(node.usage.inputTokens)} in / ${compactCount(node.usage.outputTokens)} out tokens`] : []),
+    ];
+    // Progress is tracked per node ID; only show it for the execution it describes.
+    const live = progress && (!progress.executionId || progress.executionId === node.executionId) ? progress : undefined;
+    const workspace = node.workspace;
+    // Cleaned-up worktrees are gone; their checkpoint ref is what can be recovered.
+    const workspaceActive = workspace && ["preparing", "ready", "failed"].includes(workspace.state);
+    const workspaceRef = workspaceActive ? workspace.worktreeRoot : workspace?.checkpointRef ?? workspace?.reason;
     const lines = [
         theme.fg(failed ? "error" : "accent", `${failed ? "✗" : node.status === "completed" ? "✓" : "○"} Braid node ${compact(node.id, 80)} · ${node.status}`),
         ...(node.executionId ? [theme.fg("dim", `execution: ${compact(node.executionId, 80)}`)] : []),
+        ...(timing.length ? [theme.fg("muted", timing.join(" · "))] : []),
+        ...(live ? [theme.fg("muted", `context ${live.contextSource === "estimate" ? "~" : ""}${compactCount(live.contextTokens)}/${live.contextWindow === undefined ? "—" : compactCount(live.contextWindow)} · ${live.toolCalls} tool calls in ${live.toolRounds} rounds · ${live.phase} phase`)] : []),
+        ...(workspace ? [theme.fg("dim", `workspace: ${workspace.mode} · ${workspace.state}${workspaceRef ? ` · ${compact(workspaceRef, 160)}` : ""}`)] : []),
         ...(node.decision ? [theme.fg("accent", `decision: ${compact(node.decision, 80)}`)] : []),
         ...(node.error ? [theme.fg("error", `${node.error.code}: ${clean(node.error.message)}`)] : []),
         ...(node.skipReason ? [theme.fg("muted", `skipped: ${node.skipReason}`)] : []),
+        // Activity describes one execution; never mix histories from repeated visits.
+        ...(activity && activity.executionId === node.executionId ? renderActivity(activity, expanded, theme, now) : []),
         ...(node.output ? [expanded ? clean(node.output) : compact(node.output, 400)] : []),
         ...(!expanded && node.output && (node.output.length > 400 || node.output.includes("\n")) ? [theme.fg("dim", "Expand for full node output")] : []),
         ...(fullOutputPath ? [theme.fg("dim", `full node result: ${compact(fullOutputPath, 240)}`)] : []),
     ];
     return new Text(lines.join("\n"), 0, 0);
 }
-export function renderGraphResult(result, expanded, isPartial, theme, fallback = "", isError = false) {
+/** Status, timing, and live waits above a node's session transcript. */
+export function renderSessionHeader(node, theme, now, progress, activity) {
+    const failed = node.status === "failed";
+    const live = progress && (!progress.executionId || progress.executionId === node.executionId) ? progress : undefined;
+    const facts = [
+        ...(node.executionId ? [compact(node.executionId, 80)] : []),
+        ...(node.iteration ? [`iteration #${node.iteration}`] : []),
+        ...(node.model ? [compact(node.model, 60)] : []),
+        ...(node.startedAt !== undefined || node.latencyMs !== undefined ? [`elapsed ${nodeElapsed(node, now)}`] : []),
+        ...(node.usage ? [`${compactCount(node.usage.inputTokens)} in / ${compactCount(node.usage.outputTokens)} out tokens`] : []),
+    ];
+    return [
+        theme.fg(failed ? "error" : "accent", `${failed ? "✗" : node.status === "completed" ? "✓" : node.status === "running" ? "▶" : "○"} Braid node ${compact(node.id, 80)} · ${node.status}`),
+        ...(facts.length ? [theme.fg("muted", facts.join(" · "))] : []),
+        ...(live ? [theme.fg("muted", `context ${live.contextSource === "estimate" ? "~" : ""}${compactCount(live.contextTokens)}/${live.contextWindow === undefined ? "—" : compactCount(live.contextWindow)} · ${live.toolCalls} tool calls in ${live.toolRounds} rounds · ${live.phase} phase`)] : []),
+        ...(activity && activity.executionId === node.executionId ? renderActivity(activity, false, theme, now, "summary") : []),
+        ...(node.error ? [theme.fg("error", `${node.error.code}: ${compact(node.error.message, 300)}`)] : []),
+    ];
+}
+/** What a node view shows below its pinned header when no live session is retained. */
+export function renderNodeDetails(node, theme, now, activity) {
+    const clean = (value) => stripTerminalSequences(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, "");
+    const workspace = node.workspace;
+    const workspaceActive = workspace && ["preparing", "ready", "failed"].includes(workspace.state);
+    const workspaceRef = workspaceActive ? workspace.worktreeRoot : workspace?.checkpointRef ?? workspace?.reason;
+    return [
+        ...(workspace ? [theme.fg("dim", `workspace: ${workspace.mode} · ${workspace.state}${workspaceRef ? ` · ${compact(workspaceRef, 160)}` : ""}`)] : []),
+        ...(node.decision ? [theme.fg("accent", `decision: ${compact(node.decision, 80)}`)] : []),
+        ...(node.skipReason ? [theme.fg("muted", `skipped: ${node.skipReason}`)] : []),
+        ...(activity && activity.executionId === node.executionId ? renderActivity(activity, true, theme, now, "history") : []),
+        ...(node.output ? ["", ...clean(node.output).split("\n")] : []),
+    ];
+}
+export function renderGraphResult(result, expanded, isPartial, theme, fallback = "", isError = false, selectedNodeId) {
     if (isError || !result?.nodes) {
         const message = fallback ||
             (isPartial ? "Braid is running…" : "Braid returned no execution details");
@@ -480,8 +615,17 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
     if ("executions" in result)
         lines.push(theme.fg("dim", `${Object.keys(result.executions).length} executions · revision ${result.revision}`));
     const chartStart = lines.length;
-    const chart = mermaidLines(result, theme);
+    const chart = mermaidLines(result, theme, selectedNodeId);
     lines.push(...chart);
+    // Selection must stay usable when the chart cannot be drawn or does not fit.
+    const nodeList = selectedNodeId === undefined ? [] : [
+        theme.fg("dim", chart.length ? "nodes (selected node not found in the flowchart):" : "nodes (flowchart unavailable):"),
+        ...Object.keys(graphParts(result).nodes).map(id => {
+            const node = result.nodes[id];
+            const text = `${id === selectedNodeId ? `${SELECTED_NODE_MARK} ` : "  "}${compact(id, 60)} · ${node?.status ?? "pending"}`;
+            return id === selectedNodeId ? theme.bg("selectedBg", theme.bold(theme.fg("warning", text))) : theme.fg("muted", text);
+        }),
+    ];
     const workspaces = Object.values(result.workspaces ?? {}).filter(workspace => workspace.worktreeRoot);
     if (workspaces.length) {
         const active = workspaces.filter(workspace => ["preparing", "ready", "failed"].includes(workspace.state)).length;
@@ -497,5 +641,8 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
         lines.push(...renderEventLog(result.events ?? [], true, theme));
     if ("fullOutputPath" in result && result.fullOutputPath)
         lines.push(theme.fg("dim", `full result/log: ${compact(result.fullOutputPath, 240)}`));
-    return new FixedLines(lines, chartStart, chart.length);
+    return new FixedLines(lines, chartStart, chart.length, nodeList, [
+        ...(selectedNodeId === undefined ? [] : [{ mark: SELECTED_NODE_MARK, label: "selected node" }]),
+        { mark: "▶ ACTIVE", label: "running node" },
+    ]);
 }

package/dist/index.js

@@ -5,7 +5,8 @@ import { join } from "node:path";
 import { defineTool, truncateHead, } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { BraidJobs } from "./jobs.js";
-import { registerBraidCommand } from "./command.js";
+import { registerBraidCommand, registerBraidWidget } from "./command.js";
+import { registerReviewCommand } from "./review.js";
 import { renderGraphCall, renderGraphResult, renderNodeResult } from "./display.js";
 const text = (description) => Type.String({ minLength: 1, pattern: "\\S", ...(description ? { description } : {}) });
 const prompt = () => Type.Union([
@@ -107,6 +108,8 @@ function isJobSnapshot(value) {
         ["running", "completed", "failed", "cancelled"].includes(job.status ?? "") &&
         !!job.live && typeof job.live.nodes === "object" && job.live.nodes !== null;
 }
+/** Focused reads return the latest activity entries; activityBefore pages earlier ones. */
+export const STATUS_ACTIVITY_ENTRIES = 40;
 function executionControl(job) {
     return job.execution && {
         status: job.execution.status,
@@ -201,11 +204,12 @@ export function createBraidTools(jobs) {
         jobId: Type.Optional(text("Exact session handle (e.g. job-1) or UUID; omit all IDs to list jobs.")),
         executionId: Type.Optional(text("Exact execution ID from braid_status or a reminder; requires jobId. Takes precedence over nodeId; if both are provided they must match.")),
         nodeId: Type.Optional(text("Exact node ID; requires jobId. Retrieve this node's latest full output/error even while the job is running.")),
+        activityBefore: Type.Optional(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description: `Focused reads include activity: the current phase, model/tool waits, and the latest ${STATUS_ACTIVITY_ENTRIES} history entries. Pass an entry sequence to page earlier entries.` })),
     }, { additionalProperties: false });
     const statusTool = defineTool({
         name: "braid_status",
         label: "Braid status",
-        description: "Retrieve a background Braid job's status, node progress, and final results by exact session handle (e.g. job-1) or UUID in jobId. Add executionId for an exact execution, or nodeId for the latest instance, including intermediate results while the job runs. All job reads include current execution.revision and execution.pausedExecutionIds for live control; node.revision is the historical invocation revision. Large results include a path to the full JSON, including while running. For usage totals use usage (Pi provider accounting, including rounds from failed nodes), or piUsage in the saved final result. Prefer the short handle from submission/reminders. Omit all IDs to list jobs in this session. Completion reminders arrive automatically; avoid repeated polling.",
+        description: "Retrieve a background Braid job's status, node progress, and final results by exact session handle (e.g. job-1) or UUID in jobId. Add executionId for an exact execution, or nodeId for the latest instance, including intermediate results while the job runs. Focused reads include live activity: phase, time in phase and since the last observed signal, model request/stream state, running tools, and recent history. Lack of observed activity is a diagnostic signal, not proof of a stall. All job reads include current execution.revision and execution.pausedExecutionIds for live control; node.revision is the historical invocation revision. Large results include a path to the full JSON, including while running. For usage totals use usage (Pi provider accounting, including rounds from failed nodes), or piUsage in the saved final result. Prefer the short handle from submission/reminders. Omit all IDs to list jobs in this session. Completion reminders arrive automatically; avoid repeated polling.",
         parameters: statusParameters,
         renderResult(result, options, theme, ctx) {
             const job = result.details;
@@ -224,8 +228,9 @@ export function createBraidTools(jobs) {
             const selectedNode = job.selectedNode ?? (executionId
                 ? state && Object.hasOwn(state.executions, executionId) ? state.executions[executionId] : undefined
                 : nodeId && state && Object.hasOwn(state.nodes, nodeId) ? state.nodes[nodeId] : undefined);
+            // Render at the read's observation time so a saved result never keeps counting.
             if (selectedNode)
-                return renderNodeResult(selectedNode, options.expanded, theme, job.nodeOutputPath);
+                return renderNodeResult(selectedNode, options.expanded, theme, job.nodeOutputPath, job.live.progress?.[selectedNode.id], job.live.observedAt, job.selectedActivity);
             if (executionId || nodeId)
                 return new Text(fallback || "Braid returned no node details", 0, 0);
             if (job.error)
@@ -240,6 +245,8 @@ export function createBraidTools(jobs) {
         async execute(_id, params) {
             if ((params.nodeId !== undefined || params.executionId !== undefined) && !params.jobId)
                 throw new Error("nodeId/executionId requires jobId");
+            if (params.activityBefore !== undefined && params.nodeId === undefined && params.executionId === undefined)
+                throw new Error("activityBefore requires nodeId or executionId");
             if (!params.jobId)
                 return {
                     content: [{ type: "text", text: JSON.stringify(jobs.list()) }],
@@ -251,9 +258,18 @@ export function createBraidTools(jobs) {
             if (params.nodeId !== undefined || params.executionId !== undefined) {
                 const node = jobs.getNode(params.jobId, params.nodeId, params.executionId);
                 const { id, executionId, status, error, output, ...nodeDetails } = node;
+                const activity = executionId ? jobs.getActivity(params.jobId, executionId, {
+                    limit: STATUS_ACTIVITY_ENTRIES, ...(params.activityBefore === undefined ? {} : { before: params.activityBefore }),
+                }) : undefined;
+                // While running, activity is the useful part; afterwards the output is,
+                // so it comes first and history cannot push it out of the preview.
+                const running = activity && activity.finishedAt === undefined;
+                const live = activity ? { observedAt: job.live.observedAt, activity } : {};
                 const full = JSON.stringify({
                     jobId: job.jobId, handle: job.handle, status: job.status, execution: executionControl(job),
+                    ...(running ? live : {}),
                     node: { id, executionId, status, error, output, ...nodeDetails },
+                    ...(running ? {} : live),
                 }, null, 2);
                 const preview = truncateHead(full);
                 let suffix = "";
@@ -267,7 +283,7 @@ export function createBraidTools(jobs) {
                 }
                 // Focused reads do not claim the whole job's usage; final job retrieval does.
                 return { content: [{ type: "text", text: preview.content + suffix }], details: {
-                        ...job, selectedNode: node, ...(nodeOutputPath ? { nodeOutputPath } : {}),
+                        ...job, selectedNode: node, ...(activity ? { selectedActivity: activity } : {}), ...(nodeOutputPath ? { nodeOutputPath } : {}),
                     } };
             }
             const { jobId, handle, status, error, usage: providerUsage, fullOutputPath, execution, ...snapshot } = job;
@@ -422,6 +438,8 @@ export default function braidExtension(pi) {
     });
     const { braidTool, statusTool, cancelTool, updateTool, resumeTool } = createBraidTools(jobs);
     registerBraidCommand(pi, jobs);
+    registerReviewCommand(pi, jobs);
+    const disposeWidget = registerBraidWidget(pi, jobs);
     pi.registerTool(braidTool);
     pi.registerTool(statusTool);
     pi.registerTool(cancelTool);
@@ -430,6 +448,7 @@ export default function braidExtension(pi) {
     pi.on("session_shutdown", () => {
         pending.clear();
         jobs.dispose();
+        disposeWidget();
     });
     pi.on("before_agent_start", (event) => ({
         systemPrompt: `${event.systemPrompt}\n\n## Braid execution policy\n${BRAID_USAGE_GUIDANCE}\n\nFor the current user request, make this delegation choice before using read, grep, find, edit, write, or bash. Completion reminders refer to existing jobs: retrieve their results instead of submitting the same graph again.`,

package/dist/jobs.js

@@ -3,9 +3,10 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setImmediate as nextTurn } from "node:timers/promises";
 import { truncateHead, } from "@earendil-works/pi-coding-agent";
-import { startBraid, validateGraph, } from "@chrok/braid";
+import { ExecutionActivityTracker, startBraid, validateGraph, } from "@chrok/braid";
 import { applyEvent, applyProgress, createLiveState, } from "./display.js";
 import { createPiRunner, sumPiUsage } from "./runner.js";
+import { PiTranscripts } from "./transcript.js";
 /** Jobs belong to one extension/session lifetime, independently of foreground turns. */
 export class BraidJobs {
     onFinished;
@@ -56,6 +57,9 @@ export class BraidJobs {
             controller: new AbortController(),
             done: Promise.resolve(),
             usageClaimed: false,
+            runningExecutions: new Map(),
+            activity: new ExecutionActivityTracker({ onChange: () => this.changed() }),
+            transcripts: new PiTranscripts(() => this.changed()),
             nodeResults: new Map(snapshot.nodes.map((node) => [node.id, { id: node.id, status: "pending" }])),
         };
         this.jobs.set(job.jobId, job);
@@ -78,6 +82,8 @@ export class BraidJobs {
                 runner: (() => {
                     const invoke = createPiRunner(registry, {
                         cwd,
+                        activity: job.activity,
+                        transcripts: job.transcripts,
                         maxToolRounds: options.maxToolRounds ?? Infinity,
                         maxToolCalls: options.maxToolCalls ?? Infinity,
                         onUsage: (usage) => {
@@ -91,15 +97,35 @@ export class BraidJobs {
                             this.changed();
                         },
                     });
-                    return async (request) => { await nextTurn(); return invoke(request); };
+                    return async (request) => {
+                        try {
+                            await nextTurn();
+                            return await invoke(request);
+                        }
+                        finally {
+                            job.activity.workerFinished(request.execution.executionId);
+                            job.transcripts.finish(request.execution.executionId, request.signal.aborted ? "Execution was stopped before this step finished" : undefined);
+                        }
+                    };
                 })(),
                 onEvent: (event) => {
+                    job.activity.observe(event);
                     if (event.type === "workspace_updated") {
                         job.workspaces ??= {};
                         Object.defineProperty(job.workspaces, event.workspace.executionId ?? event.workspace.nodeId, {
                             value: { ...event.workspace }, enumerable: true, configurable: true, writable: true,
                         });
                     }
+                    // Definition edits can remove nodes whose executions are still running.
+                    if (event.type === "node_started" && event.executionId) {
+                        job.runningExecutions.set(event.executionId, event.nodeId);
+                    }
+                    else if ((event.type === "node_completed" || event.type === "node_failed") && event.executionId) {
+                        job.runningExecutions.delete(event.executionId);
+                    }
+                    else if (event.type === "graph_completed" || event.type === "graph_failed") {
+                        job.runningExecutions.clear();
+                    }
                     applyEvent(job.live, event);
                     if ("nodeId" in event && Object.hasOwn(job.live.nodes, event.nodeId)) {
                         // The panel keeps short previews; node retrieval needs the complete
@@ -161,6 +187,7 @@ export class BraidJobs {
             job.status = "failed";
             job.live.status = "failed";
             job.live.pausedExecutionIds = [];
+            job.runningExecutions.clear();
             job.error = error instanceof Error ? error.message : String(error);
             if (reports.length)
                 job.usage = sumPiUsage(reports);
@@ -186,7 +213,7 @@ export class BraidJobs {
         const job = this.lookup(jobId);
         if (!job)
             return undefined;
-        const { run: _run, controller: _controller, done: _done, usageClaimed: _claimed, nodeResults: _nodeResults, ...snapshot } = job;
+        const { run: _run, controller: _controller, done: _done, usageClaimed: _claimed, nodeResults: _nodeResults, runningExecutions: _runningExecutions, activity: _activity, transcripts: _transcripts, ...snapshot } = job;
         const copy = structuredClone(snapshot);
         if (job.run)
             copy.execution = job.run.snapshot();
@@ -208,6 +235,20 @@ export class BraidJobs {
             throw new Error(`Unknown Braid node or execution in ${job.handle}. Use braid_status with only jobId to list executions.`);
         return structuredClone(node);
     }
+    /** Live activity for one exact execution; undefined until it is first observed. */
+    getActivity(jobId, executionId, page) {
+        const job = this.lookup(jobId);
+        if (!job)
+            throw this.unknownJob(jobId);
+        return job.activity.get(executionId, page);
+    }
+    /** The live conversation for one execution; read-only, and absent once evicted. */
+    getTranscript(jobId, executionId) {
+        const job = this.lookup(jobId);
+        if (!job)
+            throw this.unknownJob(jobId);
+        return job.transcripts.get(executionId);
+    }
     update(jobId, patch) {
         const job = this.lookup(jobId);
         if (!job)
@@ -239,6 +280,20 @@ export class BraidJobs {
         }))
             .reverse();
     }
+    /** Editor progress without copying outputs, transcripts, or execution snapshots. */
+    progress(jobId) {
+        const job = this.lookup(jobId);
+        if (!job)
+            return undefined;
+        const nodes = Object.values(job.live.nodes);
+        return {
+            total: nodes.length,
+            done: nodes.filter(node => node.status === "completed" || node.status === "failed" || node.status === "skipped").length,
+            failed: nodes.filter(node => node.status === "failed").length,
+            running: [...new Set(job.runningExecutions.values())],
+            paused: job.live.pausedExecutionIds?.length ?? 0,
+        };
+    }
     cancel(jobId) {
         const job = this.lookup(jobId);
         if (!job)

package/dist/review.js

@@ -0,0 +1,64 @@
+const maxRounds = 3;
+export function registerReviewCommand(pi, jobs) {
+    pi.registerCommand("braid:review", {
+        description: "Parallel review/fix loop, at most 3 review rounds: /braid:review [target or focus]",
+        handler: async (args, ctx) => {
+            const target = args.trim() || "Current uncommitted changes; if there are none, the latest commit.";
+            const input = {
+                goal: `Review the following target, fix concrete in-scope defects, and re-review material fixes. Stop after at most ${maxRounds} review rounds. Respect an explicit review-only request.\n\nTarget or focus:\n${target}`,
+                promptTemplates: {
+                    reviewer: `You are reviewer {{slot}}. Use the distinct angle assigned to you by scope.
+Inspect the repository instructions, actual files, and target diff in your assigned snapshot. Do not rely on conversation history or edit files. Use scope's pinned original baseline and target endpoint for the original target diff, and separately compare its pinned initial job snapshot to YOUR workspace.snapshotCommit for cumulative loop fixes. Never substitute the current snapshot for the original target endpoint: historical ranges and latest-commit reviews exclude later commits and unrelated caller edits, even within target files. Inspect current files for fix validity, but attribute findings only to the original target diff or cumulative fix diff. Plain git diff may be empty because caller edits were captured in a commit.
+Report only concrete current issues within the target, supported by source proof, a test/repro, or a contract contradiction. For diff reviews, require that the issue is caused or made reachable by the diff. Include file/line references, evidence, a suggested fix, and P0/P1/P2: P0 blocks merge, P1 should be fixed before release, P2 is report-only. Do not filter the first pass to blockers only or invent findings to fill your angle.
+On follow-up rounds check whether earlier findings were resolved, whether the fixes introduced defects in their blast radius, and whether deferred notes still stand. You cannot run tests here; distinguish source inspection from executed validation.
+If nothing qualifies, say exactly "No issues found." End with "Merge verdict: BLOCK", "Merge verdict: OK", or "Merge verdict: OK with notes".`,
+                },
+                nodes: [
+                    {
+                        type: "execute", id: "scope", workspace: "worktree", requireSuccess: true,
+                        prompt: `Prepare this review round by inspecting the requested target and relevant repository instructions. You are the only fix writer.
+On the FIRST round only, resolve the target without editing files. For the default target, compare workspace.baseCommit (the caller's original HEAD) to workspace.snapshotCommit, including captured staged/unstaged/non-ignored new files. If identical, review the latest original commit against its parent; for an initial/unborn commit inspect all captured files. Do not mistake a clean isolated worktree for an empty target. For an explicit commit/range target, resolve HEAD against workspace.baseCommit, not the detached snapshot HEAD, and pin all endpoints as commit hashes.
+Pin the original baseline commit, original target endpoint commit, initial job snapshot commit (first-round workspace.snapshotCommit), and original target/file scope in the first handoff. For captured uncommitted changes the original target endpoint is the initial job snapshot; for latest-commit review it is workspace.baseCommit; for an explicit range it is the resolved upper endpoint. On later rounds retain all these exact values from the previous check handoff; never re-resolve HEAD-relative refs or switch target modes. Inspect two separate diffs: original baseline to original target endpoint, and initial job snapshot to current workspace.snapshotCommit for cumulative loop fixes. Do not review baseline-to-current-snapshot as the target: file filtering cannot exclude later commits or unrelated dirty edits in the same target file. Preserve those out-of-target edits and do not fix their defects.
+On RETRY rounds, apply only the concrete, evidenced in-scope P0/P1 fixes synthesized by the previous check. Preserve all user edits and any review-only constraint. No optional polish, scope expansion, architecture decisions, or recursive agents. Use only your own worktree. Run focused validation, repair failures within scope, and report commands with exit codes, evidence, and limitations. If validation remains unsuccessful or no material fix was possible, say so explicitly; do not claim success.
+Choose three distinct, concrete review angles for this change (usually correctness/regressions, tests/contracts, and simplicity; adapt for security, performance, UI/accessibility, or docs when relevant). Assign them to reviewers 1, 2, and 3. Carry forward cumulative fixes, changed files, validation results, unresolved/deferred findings, and current execution.iteration. If a requested target cannot be read with your tools, report that limitation instead of substituting another target. Outside Git, report findings without attempting fixes.`,
+                    },
+                    ...[1, 2, 3].map(slot => ({
+                        type: "execute", id: `review-${slot}`, workspace: "read-only", requireSuccess: true,
+                        prompt: { template: "reviewer", variables: { slot: String(slot) } },
+                    })),
+                    {
+                        type: "decision", id: "check", workspace: "read-only", requireSuccess: true, choices: ["retry", "done"],
+                        prompt: `Synthesize scope and all three reviews. Verify and deduplicate findings against actual files in YOUR workspace.snapshotCommit, which includes scope's completed fixes; separate valid P0/P1 fixes worth doing now, P2 report-only notes, and feedback to ignore/defer with reasons. Do not blindly apply suggestions or add optional polish.
+You are read-only and cannot edit files or run tests. If the target is unavailable, review-only was requested, nothing actionable remains, fixes are unavailable outside Git, or a fix requires an unapproved product/scope/architecture decision, call decide with done. Report the exact stop reason and unresolved findings.
+If the previous fix pass failed validation or made no material progress, stop with done and prohibit integration of unvalidated or unreviewed fixes; do not repeatedly retry the same findings.
+There are at most ${maxRounds} review rounds, including the first. If execution.iteration >= ${maxRounds}, call decide with done; distinguish round-limit exhaustion from a clean review. Never choose retry in the final round.
+Otherwise choose retry only when concrete in-scope P0/P1 fixes are worth doing now. Give scope a narrow, deduplicated fix list with evidence so the next writer pass addresses only those findings before fresh reviewers inspect its checkpoint.
+Your final handoff must retain the pinned original baseline, original target endpoint, initial job snapshot, and target/file scope unchanged, cumulative fixes and changed files from scope, commands and exit codes, validation evidence/limitations, unresolved and deferred findings, whether the cumulative fixes passed review and validation and may be integrated, rounds run, and stop reason. Prohibit integration when unresolved findings invalidate those fixes. Call decide exactly once, then give this handoff.`,
+                    },
+                    {
+                        type: "integrate", id: "apply", requireSuccess: true,
+                        prompt: `Read the final check handoff and inspect the cumulative diff in the merge source. Apply only fixes that passed follow-up review and focused validation; do not implement new fixes here. If review-only, no fixes exist, validation failed, or the handoff prohibits integration, leave the source files unchanged and mark the source discarded or archived as appropriate.
+Use mergeSources.changes.baseCommit (the initial job snapshot, including caller edits) to checkpointRef as the patch baseline. Do not diff from original HEAD or replay pre-existing caller changes. Preserve staged, unstaged, untracked, and concurrent user edits. If new checkout edits conflict, archive the checkpoint and report the conflict; do not create an unreviewed resolution or overwrite user work. Call finish_merge exactly once with the source executionId and an accurate disposition after applying or archiving the changes.
+Inspect the final diff and run or confirm focused validation without changing code. Summarize rounds run, fixes actually applied, validation, remaining/deferred findings, integration outcome, and why the loop stopped. Report round-limit or needs-decision exits honestly; never claim they are clean.`,
+                    },
+                ],
+                edges: [
+                    ...[1, 2, 3].flatMap(slot => [
+                        { from: "scope", to: `review-${slot}` },
+                        { from: `review-${slot}`, to: "check" },
+                    ]),
+                    { from: "scope", to: "check" },
+                    { from: "check", to: "scope", choice: "retry", feedback: "review-loop" },
+                    { from: "check", to: "apply", choice: "done" },
+                ],
+                loops: [{ id: "review-loop", entry: "scope", maxIterations: maxRounds }],
+            };
+            const job = jobs.start(input, { maxConcurrency: 3, maxExecutions: maxRounds * 5 + 1 }, ctx);
+            pi.sendMessage({
+                customType: "braid-review-started", display: true,
+                content: `Review started as Braid ${job.handle}: ${target}\nUp to ${maxRounds} parallel review rounds and ${maxRounds - 1} fix passes. Only reviewed fixes are integrated. Open /braid ${job.handle} for progress, or braid_cancel to stop. Wait for the completion reminder, then retrieve braid_status({"jobId":"${job.handle}"}) and summarize; do not start a replacement review loop.`,
+                details: { jobId: job.jobId, handle: job.handle },
+            }, { triggerTurn: false });
+        },
+    });
+}