@chrok/pi-braid 0.3.1 → 0.3.2

package/README.md

@@ -25,6 +25,7 @@ It registers:
 - `braid_update` / `braid_resume` — edit live definitions or release paused executions.
 - `braid_cancel` — cancel a job with `{ "jobId": "..." }`.
 - `/braid [jobId]` — open a live flow panel in interactive Pi.
+- `/braid:review [target or focus]` — run a bounded parallel review/fix loop.
 
 Submission and completion reminders use short session handles such as `job-1`.
 Status, cancellation and the panel accept either that exact handle or the original
@@ -50,6 +51,44 @@ or switching/forking sessions aborts outstanding work and suppresses its
 reminders. Job IDs cannot be retrieved after that lifecycle ends. They are not
 persistent processes outside Pi.
 
+## Review command
+
+Run `/braid:review` to review current uncommitted changes (including staged, unstaged,
+and non-ignored new files). With no uncommitted changes, it reviews the latest
+commit. Supply a file, commit range, or focus with `/braid:review src/runtime.ts` or
+`/braid:review main..HEAD, focus on cancellation`. Workers inspect the supplied target
+with local tools; they report unavailable remote targets instead of inventing
+their contents. Use `/braid:review review-only, src/runtime.ts` to request findings
+without fixes.
+
+Each round assigns three independent, read-only reviewers distinct angles based
+on the change. Findings need concrete evidence and file/line references, with
+P0/P1/P2 priority and a merge verdict. One writer synthesizes the feedback and
+fixes only evidenced, in-scope P0/P1 problems in an isolated worktree, then runs
+focused validation. Optional P2 polish is reported. A product, scope, or
+architecture decision stops the loop for user input.
+
+The graph enforces a fixed maximum of **three review rounds**, including the
+first, and **two fix passes**. The final round reports remaining issues without
+making further edits; reaching the cap does not mean the review is clean.
+Only fixes that passed re-review and validation are integrated into the invoking
+checkout, preserving existing user changes. Conflicting concurrent edits or
+failed validation leave the fix checkpoint archived for recovery. Outside Git,
+workers can only inspect files and report findings.
+
+The command returns immediately with a job handle. Use `/braid [jobId]` to see
+progress, `braid_status` for results, and `braid_cancel` to stop. The existing
+completion reminder resumes the parent to report rounds, applied fixes,
+validation, remaining findings, and the stop reason. Session shutdown cancels
+the job. Cancellation or failure during integration can leave partial checkout
+changes; Braid retains backup and checkpoint refs for recovery.
+
+The review policy is adapted from pi-subagents'
+[review-loop](https://github.com/nicobailon/pi-subagents/blob/main/prompts/review-loop.md)
+and [parallel-review](https://github.com/nicobailon/pi-subagents/blob/main/prompts/parallel-review.md)
+prompts. Invoking `/braid:review` authorizes the narrow fix passes described above;
+an explicit review-only request disables them.
+
 ## Graph definitions
 
 Each node has a unique `id` and one of these four shapes:
@@ -163,6 +202,21 @@ scheduler persistence across Pi reloads. Reminders alone do not pause execution.
 
 ## Live flow panel
 
+In interactive Pi, background progress appears automatically **above the input
+editor** as soon as a job is submitted; no command or polling is needed:
+
+```text
+Braid job-1 · running · 2/5 done · review
+```
+
+The widget shows node progress, active node IDs, paused gates, and failures.
+It shows up to three active jobs, with an overflow count for the rest. When no
+jobs are active, the newest job's final completed/failed/cancelled status stays
+visible until another job is submitted or the session ends. Counts use the
+latest state of each current node definition; failed and skipped nodes count as
+done, and reruns or live edits can change progress and totals. RPC, JSON, and
+print modes do not create a terminal widget.
+
 Run `/braid` to open the newest job, or `/braid <jobId>` to open a specific job.
 The bordered panel keeps the job header and keyboard controls visible while
 you scroll the flow and event log. It refreshes as nodes start, finish, fail,
@@ -171,6 +225,17 @@ Use Left/Right to select jobs, Up/Down or Page Up/Page Down to scroll, `c` to
 cancel the selected job, and Escape or `q` to close the panel. Closing the panel
 leaves jobs running. In RPC or noninteractive modes, use `braid_status`.
 
+Run `/braid <jobId> <nodeId>` to open the panel on one node's latest invocation,
+or `/braid <jobId> <executionId>` for an exact invocation such as an earlier loop
+iteration. The node view refreshes live with its status, model, elapsed time,
+token usage, context size, tool-call count, workspace, and full output or error.
+Press Backspace to return to the whole graph; switching jobs also returns to it.
+Tab completes job handles and then that job's node IDs.
+IDs with leading/trailing whitespace, terminal controls, or a leading double
+quote use JSON string syntax, such as `/braid job-1 " review "` or
+`/braid job-1 "review\nstep"`. Tab inserts this form automatically and displays
+control characters as escapes.
+
 The panel renders a Mermaid flowchart, node states, elapsed times, context-token
 estimates or provider-reported usage, context-window sizes, filesystem tool-call
 counts, and the execution log. Active nodes are marked `▶ ACTIVE`. The status

package/dist/command.js

@@ -1,5 +1,5 @@
 import { matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
-import { renderGraphResult } from "./display.js";
+import { renderGraphResult, renderNodeResult } from "./display.js";
 // Match the overlay height exactly so Pi never clips the footer or bottom border.
 const panelHeight = (rows) => Math.max(1, Math.floor(rows * 0.9));
 const plain = (value) => stripTerminalSequences(value).replace(/\p{Cc}/gu, " ");
@@ -10,17 +10,19 @@ export class BraidPanel {
     theme;
     done;
     selected;
+    focus;
     offset = 0;
     maxOffset = 0;
     disposed = false;
     unsubscribe;
     ticker;
-    constructor(jobs, tui, theme, done, jobId) {
+    constructor(jobs, tui, theme, done, jobId, focus) {
         this.jobs = jobs;
         this.tui = tui;
         this.theme = theme;
         this.done = done;
         this.selected = jobId ? jobs.get(jobId)?.jobId ?? jobId : undefined;
+        this.focus = focus;
         this.unsubscribe = jobs.subscribe(() => this.refresh());
         this.ticker = setInterval(() => this.refresh(), 1000);
         this.ticker.unref();
@@ -60,8 +62,11 @@ export class BraidPanel {
                 : current?.status === "failed"
                     ? "error"
                     : "muted";
+        const focusLabel = this.focus
+            ? "nodeId" in this.focus ? `node ${plain(this.focus.nodeId)}` : `execution ${plain(this.focus.executionId)}`
+            : "";
         const heading = current
-            ? `Job ${index + 1} of ${jobs.length}  ·  ${this.theme.fg(statusColor, current.status)}`
+            ? `Job ${index + 1} of ${jobs.length}  ·  ${this.theme.fg(statusColor, current.status)}${focusLabel ? `  ·  ${focusLabel}` : ""}`
             : this.theme.fg("muted", "No background jobs");
         // Reserve a body row and the close hint even in a very short terminal.
         if (rows < 10) {
@@ -87,21 +92,23 @@ export class BraidPanel {
                 : "Jobs will appear here as soon as they are submitted.")),
             rule("├", "┤"),
         ];
-        const content = current
-            ? [
-                ...(current.error
-                    ? [this.theme.fg("error", plain(current.error))]
-                    : []),
-                ...renderGraphResult({
-                    ...(current.result ?? current.live),
-                    progress: current.live.progress,
-                    ...(current.workspaces ? { workspaces: current.workspaces } : {}),
-                    ...(current.fullOutputPath
-                        ? { fullOutputPath: current.fullOutputPath }
-                        : {}),
-                }, true, false, this.theme).render(contentWidth),
-            ]
-            : ["No Braid jobs in this session."];
+        const content = current && this.focus
+            ? this.renderFocus(current, this.focus, contentWidth)
+            : current
+                ? [
+                    ...(current.error
+                        ? [this.theme.fg("error", plain(current.error))]
+                        : []),
+                    ...renderGraphResult({
+                        ...(current.result ?? current.live),
+                        progress: current.live.progress,
+                        ...(current.workspaces ? { workspaces: current.workspaces } : {}),
+                        ...(current.fullOutputPath
+                            ? { fullOutputPath: current.fullOutputPath }
+                            : {}),
+                    }, true, false, this.theme).render(contentWidth),
+                ]
+                : ["No Braid jobs in this session."];
         const height = rows - header.length - 4;
         this.maxOffset = Math.max(0, content.length - height);
         this.offset = Math.min(this.offset, this.maxOffset);
@@ -109,11 +116,17 @@ export class BraidPanel {
         while (body.length < height)
             body.push("");
         const range = `Lines ${this.offset + 1}–${Math.min(content.length, this.offset + height)}/${content.length}`;
-        const help = contentWidth >= 72
-            ? "←/→ jobs   ↑/↓ scroll   PgUp/PgDn page   c cancel   Esc close"
-            : contentWidth >= 42
-                ? "←/→ jobs · ↑/↓ scroll · c cancel · Esc close"
-                : "↑/↓ scroll · Esc close";
+        const help = this.focus
+            ? contentWidth >= 72
+                ? "⌫ graph   ←/→ jobs   ↑/↓ scroll   PgUp/PgDn page   c cancel   Esc close"
+                : contentWidth >= 42
+                    ? "⌫ graph · ↑/↓ scroll · c cancel · Esc close"
+                    : "⌫ graph · Esc close"
+            : contentWidth >= 72
+                ? "←/→ jobs   ↑/↓ scroll   PgUp/PgDn page   c cancel   Esc close"
+                : contentWidth >= 42
+                    ? "←/→ jobs · ↑/↓ scroll · c cancel · Esc close"
+                    : "↑/↓ scroll · Esc close";
         return [
             ...header,
             ...body.map(row),
@@ -123,6 +136,27 @@ export class BraidPanel {
             rule("╰", "╯"),
         ];
     }
+    /** A focused node can disappear after a live graph update; say so instead of failing. */
+    renderFocus(job, focus, width) {
+        let node;
+        try {
+            node = "nodeId" in focus
+                ? this.jobs.getNode(job.jobId, focus.nodeId)
+                : this.jobs.getNode(job.jobId, undefined, focus.executionId);
+        }
+        catch {
+            return [
+                this.theme.fg("warning", "This node or execution is no longer in the job's graph."),
+                this.theme.fg("muted", "Press Backspace to return to the graph."),
+            ];
+        }
+        // Latest-node results omit the loop iteration; their execution record has it.
+        const executions = job.result?.executions ?? job.execution?.executions;
+        const iteration = node.iteration ??
+            (node.executionId ? executions?.[node.executionId]?.iteration : undefined);
+        return renderNodeResult(iteration === undefined ? node : { ...node, iteration }, true, this.theme, undefined, job.live.progress[node.id], job.live.observedAt)
+            .render(width);
+    }
     handleInput(data) {
         if (matchesKey(data, "escape") ||
             data === "q" ||
@@ -136,6 +170,11 @@ export class BraidPanel {
         if (matchesKey(data, "left") || matchesKey(data, "right")) {
             const step = matchesKey(data, "right") ? 1 : -1;
             this.selected = jobs[(index + step + jobs.length) % jobs.length]?.jobId;
+            this.focus = undefined;
+            this.offset = 0;
+        }
+        else if (matchesKey(data, "backspace") && this.focus) {
+            this.focus = undefined;
             this.offset = 0;
         }
         else if (matchesKey(data, "up"))
@@ -159,19 +198,76 @@ export class BraidPanel {
         this.unsubscribe();
     }
 }
+export function registerBraidWidget(pi, jobs) {
+    let dispose = () => { };
+    const clear = () => {
+        dispose();
+        dispose = () => { };
+    };
+    pi.on("session_start", (_event, ctx) => {
+        clear();
+        if (ctx.mode !== "tui")
+            return;
+        const refresh = () => {
+            if (!jobs.list().length) {
+                ctx.ui.setWidget("braid-status", undefined);
+                return;
+            }
+            ctx.ui.setWidget("braid-status", (_tui, theme) => ({
+                render(width) {
+                    const all = jobs.list();
+                    const active = all.filter(job => job.status === "running");
+                    const selected = active.length ? active.slice(0, 3) : all.slice(0, 1);
+                    const lines = selected.map(job => {
+                        const progress = jobs.progress(job.jobId);
+                        const status = job.status === "running" && progress.paused && !progress.running.length
+                            ? "paused" : job.status;
+                        const color = status === "completed" ? "success"
+                            : status === "failed" ? "error"
+                                : status === "cancelled" ? "muted" : "warning";
+                        const parts = [
+                            theme.fg("accent", `Braid ${job.handle}`),
+                            theme.fg(color, status),
+                            `${progress.done}/${progress.total} done`,
+                        ];
+                        if (progress.failed)
+                            parts.push(theme.fg("error", `${progress.failed} failed`));
+                        if (progress.paused && status !== "paused")
+                            parts.push(theme.fg("warning", `${progress.paused} paused`));
+                        parts.push(plain(progress.running.length ? progress.running.join(", ") : job.goal));
+                        return truncateToWidth(parts.join(" · "), width, "…");
+                    });
+                    if (active.length > selected.length)
+                        lines.push(truncateToWidth(theme.fg("muted", `Braid · +${active.length - selected.length} active jobs · /braid details`), width, "…"));
+                    return lines;
+                },
+                invalidate() { },
+            }), { placement: "aboveEditor" });
+        };
+        const unsubscribe = jobs.subscribe(refresh);
+        dispose = () => {
+            unsubscribe();
+            ctx.ui.setWidget("braid-status", undefined);
+        };
+        refresh();
+    });
+    return clear;
+}
 export function registerBraidCommand(pi, jobs) {
     pi.registerCommand("braid", {
-        description: "Open the live background-job flow panel: /braid [jobId]",
+        description: "Open the live background-job flow panel: /braid [jobId [nodeId|executionId]]",
+        getArgumentCompletions: (prefix) => braidCompletions(jobs, prefix),
         handler: async (args, ctx) => {
             if (ctx.mode !== "tui")
                 throw new Error("The Braid panel requires interactive Pi. Use braid_status for job status.");
-            const jobId = args.trim() || undefined;
+            const [jobId, target] = splitArguments(args.trim());
             if (jobId && !jobs.get(jobId))
                 throw jobs.unknownJob(jobId);
+            const focus = jobId && target ? resolveFocus(jobs, jobId, target) : undefined;
             let panel;
             try {
                 await ctx.ui.custom((tui, theme, _keys, done) => {
-                    panel = new BraidPanel(jobs, tui, theme, done, jobId);
+                    panel = new BraidPanel(jobs, tui, theme, done, jobId, focus);
                     return panel;
                 }, {
                     overlay: true,
@@ -188,3 +284,65 @@ export function registerBraidCommand(pi, jobs) {
         },
     });
 }
+/** Job IDs never contain whitespace; node IDs may, so the rest is one target. */
+function splitArguments(text) {
+    const split = text.search(/\s/);
+    if (split < 0)
+        return [text || undefined, undefined];
+    const jobId = text.slice(0, split);
+    const target = text.slice(split).trim();
+    if (!target.startsWith('"'))
+        return [jobId, target || undefined];
+    try {
+        return [jobId, JSON.parse(target)];
+    }
+    catch {
+        throw new Error('A quoted Braid target must be a valid JSON string, for example " review ".');
+    }
+}
+/** Quote IDs that would otherwise be trimmed, parsed as quotes, or rendered as controls. */
+function formatTarget(id) {
+    if (id === id.trim() && !id.startsWith('"') && !/[\p{Cc}\u2028\u2029]/u.test(id))
+        return id;
+    return JSON.stringify(id).replace(/\u2028/gu, "\\u2028").replace(/\u2029/gu, "\\u2029");
+}
+/** Node IDs take precedence; anything else must be an exact execution ID. */
+function resolveFocus(jobs, jobId, target) {
+    try {
+        jobs.getNode(jobId, target);
+        return { nodeId: target };
+    }
+    catch { }
+    try {
+        jobs.getNode(jobId, undefined, target);
+        return { executionId: target };
+    }
+    catch { }
+    const handle = jobs.get(jobId)?.handle ?? jobId;
+    throw new Error(`Unknown Braid node or execution "${plain(target)}" in ${handle}. Open /braid ${handle} to see its nodes.`);
+}
+/** Pi replaces the whole argument text, so node suggestions repeat the job handle. */
+function braidCompletions(jobs, prefix) {
+    const text = prefix.trimStart();
+    const split = text.search(/\s/);
+    const jobPrefix = split < 0 ? text : text.slice(0, split);
+    if (split < 0) {
+        const items = jobs.list()
+            .filter((job) => job.handle.startsWith(jobPrefix))
+            .map((job) => ({ value: job.handle, label: job.handle, description: `${job.status} · ${plain(job.goal)}` }));
+        return items.length ? items : null;
+    }
+    const nodePrefix = text.slice(split).trimStart();
+    const job = jobs.get(jobPrefix);
+    if (!job)
+        return null;
+    const nodes = job.result?.nodes ?? job.execution?.nodes ?? job.live.nodes;
+    const items = Object.values(nodes)
+        .flatMap((node) => {
+        const target = formatTarget(node.id);
+        return node.id.startsWith(nodePrefix) || target.startsWith(nodePrefix)
+            ? [{ value: `${job.handle} ${target}`, label: target, description: node.status }]
+            : [];
+    });
+    return items.length ? items : null;
+}

package/dist/display.js

@@ -429,12 +429,27 @@ export function applyProgress(state, progress) {
     });
 }
 /** 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()) {
     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}`)] : []),

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([
@@ -224,8 +225,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);
             if (executionId || nodeId)
                 return new Text(fallback || "Braid returned no node details", 0, 0);
             if (job.error)
@@ -422,6 +424,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 +434,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

@@ -56,6 +56,7 @@ export class BraidJobs {
             controller: new AbortController(),
             done: Promise.resolve(),
             usageClaimed: false,
+            runningExecutions: new Map(),
             nodeResults: new Map(snapshot.nodes.map((node) => [node.id, { id: node.id, status: "pending" }])),
         };
         this.jobs.set(job.jobId, job);
@@ -100,6 +101,16 @@ export class BraidJobs {
                             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 +172,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 +198,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, ...snapshot } = job;
         const copy = structuredClone(snapshot);
         if (job.run)
             copy.execution = job.run.snapshot();
@@ -239,6 +251,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 });
+        },
+    });
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "license": "MIT",
   "description": "Pi extension for Braid: background agent graphs, bounded loops, live updates, and a flow panel",
   "type": "module",
   "dependencies": {
     "grok-mermaid": "^0.2.2",
-    "@chrok/braid": "0.3.1"
+    "@chrok/braid": "0.3.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",