@chrok/pi-braid 0.3.1 → 0.3.3

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,12 +225,54 @@ 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`.
 
+A flowchart wider than the terminal is cropped to the terminal width around the
+first running node, or from its left edge; a `[chart 1–76 of 245 cols]` line
+shows the visible columns.
+
+Press `v` to select a node: the arrow keys move a `◆` marker through the
+flowchart (starting at a running node), and the view pans horizontally and
+scrolls vertically to keep the selected node in sight. If the flowchart cannot be
+drawn, a node list replaces it while selecting. Enter opens that node's latest
+invocation as a live session. The session is drawn with Pi's own chat
+components, as in the main conversation: the worker's prompt, streamed
+assistant text and thinking, and tool cards whose arguments and output update
+while they run. The node summary—status, elapsed time, usage, context, and live
+activity (see below)—stays pinned at the top while the session scrolls. The
+session follows the newest lines; scroll up to pause, and press End to follow again. Left/Right switch between
+invocations of the same node (for example loop iterations), and ctrl+o expands
+tool output. Escape steps back one level—session, then node selection, then the
+graph—and closes the panel from the graph; `q` closes it from anywhere. Sessions
+are read-only. Running invocations and the 20 most recently finished ones per
+job keep their session; older ones show the summary and activity history.
+
+Run `/braid <jobId> <nodeId>` to open that node's latest invocation directly in
+the session view, or `/braid <jobId> <executionId>` for an exact invocation such
+as an earlier loop iteration. The header shows live activity for that exact invocation: the current phase
+(workspace preparation, worker, model request, tool, or checkpoint/cleanup) and
+how long it has been in it, time since the last observed signal, total time, the
+in-flight model request (sent, awaiting the first stream event, or streaming
+text/reasoning/tool-call arguments with a character count and latest tail), and
+running tools with their arguments, elapsed time, and latest output. Focused
+`braid_status` reads, and invocations whose session is no longer retained, add a
+chronological history of model requests and responses, assistant text, tool calls
+and results, workspace changes, and completion, with bounded detail previews.
+A quiet period is shown as elapsed time, not declared a stall. If the host cannot
+report a signal—for example a model registry without streaming—the view says so.
+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
 tool also renders a flowchart; expand its result to see more log events.
 When selecting `nodeId` or `executionId`, it instead shows that invocation's
-output/error, with the full text available on expansion.
+output/error and activity, with the full text and history available on expansion.
+The JSON includes `activity` with the latest 40 history entries; pass
+`activityBefore` with an entry sequence to page earlier ones. While the invocation
+runs, `activity` comes before `node` so it survives preview truncation.
 
 `/braid` now opens this panel; it no longer arms the next prompt. To request
 Braid explicitly, ask the agent to analyze the task using Braid.

package/dist/command.js

@@ -1,26 +1,41 @@
 import { matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
-import { renderGraphResult } from "./display.js";
+import { renderGraphResult, renderNodeDetails, renderSessionHeader, SELECTED_NODE_MARK } from "./display.js";
+import { NodeSessionView } from "./session-view.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, " ");
-/** A live, scrollable panel. Closing the panel leaves jobs running. */
+/**
+ * A live, scrollable panel. Esc steps back one level: session → node selection →
+ * graph → close. Closing the panel leaves jobs running.
+ */
 export class BraidPanel {
     jobs;
     tui;
     theme;
     done;
     selected;
+    focus;
+    /** Node highlighted in selection mode (`v`); undefined in the plain graph view. */
+    choosing;
+    /** Keep the newest transcript lines in view until the user scrolls up. */
+    follow = true;
+    /** The selection last scrolled into view, so manual scrolling is not overridden. */
+    revealed;
     offset = 0;
     maxOffset = 0;
     disposed = false;
+    session;
     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;
+        // Pi's tool components only request renders through the TUI.
+        this.session = new NodeSessionView(tui, theme);
         this.unsubscribe = jobs.subscribe(() => this.refresh());
         this.ticker = setInterval(() => this.refresh(), 1000);
         this.ticker.unref();
@@ -60,8 +75,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)}`
+            : this.choosing !== undefined ? "select a node" : "";
         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,35 +105,63 @@ 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 height = rows - header.length - 4;
+        if (current && this.choosing !== undefined && !this.nodeIds(current).includes(this.choosing)) {
+            this.choosing = this.nodeIds(current)[0];
+        }
+        // The node summary (or the selected node) stays pinned while the body scrolls.
+        const focused = current && this.focus ? this.renderFocus(current, this.focus, contentWidth) : undefined;
+        let pinned = focused?.pinned ?? (current && this.choosing !== undefined ? [this.choosingLine(current)] : []);
+        const available = rows - header.length - 4;
+        const maxPinned = Math.max(2, Math.floor(available / 2));
+        if (pinned.length > maxPinned) {
+            pinned = [...pinned.slice(0, maxPinned - 1), this.theme.fg("dim", `… ${pinned.length - maxPinned + 1} more summary lines`)];
+        }
+        const content = focused
+            ? focused.body
+            : 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, "", false, this.choosing).render(contentWidth),
+                ]
+                : ["No Braid jobs in this session."];
+        const height = available - (pinned.length ? pinned.length + 1 : 0);
         this.maxOffset = Math.max(0, content.length - height);
-        this.offset = Math.min(this.offset, this.maxOffset);
+        this.offset = this.focus && this.follow ? this.maxOffset : Math.min(this.offset, this.maxOffset);
+        if (!this.focus && this.choosing !== undefined && this.choosing !== this.revealed) {
+            // Bring a newly selected node's box into view in a tall flowchart.
+            this.revealed = this.choosing;
+            const line = content.findIndex(text => stripTerminalSequences(text).includes(SELECTED_NODE_MARK));
+            if (line >= 0 && (line < this.offset || line > this.offset + height - 3)) {
+                this.offset = Math.max(0, Math.min(this.maxOffset, line - Math.floor(height / 3)));
+            }
+        }
+        if (this.choosing === undefined)
+            this.revealed = undefined;
         const body = content.slice(this.offset, this.offset + height);
         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 [wide, medium, narrow] = this.focus
+            ? ["Esc back   ←/→ executions   ↑/↓ scroll   End follow   ctrl+o tools   c cancel   q close",
+                "Esc back · ←/→ executions · ↑/↓ scroll · q close", "Esc back · q close"]
+            : this.choosing !== undefined
+                ? ["↑/↓/←/→ choose node   Enter open session   Esc back   PgUp/PgDn page   q close",
+                    "↑/↓ choose · Enter open · Esc back", "Enter open · Esc back"]
+                : ["v select node   ←/→ jobs   ↑/↓ scroll   PgUp/PgDn page   c cancel   Esc close",
+                    "v select node · ←/→ jobs · ↑/↓ scroll · Esc close", "v select · Esc close"];
+        const help = contentWidth >= 80 ? wide : contentWidth >= 42 ? medium : narrow;
         return [
             ...header,
+            ...(pinned.length ? [...pinned.map(row), rule("├", "┤")] : []),
             ...body.map(row),
             rule("├", "┤"),
             row(this.theme.fg("dim", `${range}${contentWidth >= 60 ? "  ·  Jobs keep running when this panel closes" : ""}`)),
@@ -123,22 +169,154 @@ export class BraidPanel {
             rule("╰", "╯"),
         ];
     }
+    /** Graph definition order, which is also the flowchart's declaration order. */
+    nodeIds(job) {
+        return Object.keys(job.result?.nodes ?? job.live.nodes);
+    }
+    choosingLine(job) {
+        const nodes = job.result?.nodes ?? job.live.nodes;
+        const node = this.choosing !== undefined ? nodes[this.choosing] : undefined;
+        const ids = this.nodeIds(job);
+        return this.theme.fg("warning", `${SELECTED_NODE_MARK} Selected ${ids.indexOf(this.choosing ?? "") + 1}/${ids.length}: `) +
+            this.theme.bold(plain(this.choosing ?? "")) + this.theme.fg("muted", ` · ${node?.status ?? "pending"} · Enter to open its session`);
+    }
+    /** 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 { pinned: [], body: [
+                    this.theme.fg("warning", "This node or execution is no longer in the job's graph."),
+                    this.theme.fg("muted", "Press Esc 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);
+        const withIteration = iteration === undefined ? node : { ...node, iteration };
+        const activity = node.executionId ? this.jobs.getActivity(job.jobId, node.executionId) : undefined;
+        const transcript = node.executionId ? this.jobs.getTranscript(job.jobId, node.executionId) : undefined;
+        const siblings = this.executionsOf(job, node.id);
+        const position = node.executionId ? siblings.indexOf(node.executionId) : -1;
+        const header = [
+            ...renderSessionHeader(withIteration, this.theme, job.live.observedAt, job.live.progress[node.id], activity),
+            ...(siblings.length > 1 ? [this.theme.fg("dim", `execution ${position + 1} of ${siblings.length} for this node · ←/→ to switch`)] : []),
+        ];
+        let failure;
+        if (transcript) {
+            try {
+                return { pinned: header, body: this.session.render(transcript, width) };
+            }
+            catch (error) {
+                // A rendering failure must not take down the overlay; fall back to the summary.
+                failure = this.theme.fg("error", `Session view unavailable: ${plain(error instanceof Error ? error.message : String(error))}`);
+            }
+        }
+        // Pending, recorded before this session, or evicted: show details and history instead.
+        const note = failure ?? (node.executionId
+            ? this.theme.fg("muted", "The live session for this execution is no longer retained; showing its details and activity history.")
+            : this.theme.fg("muted", "This node has not run yet."));
+        return { pinned: header, body: [note, ...renderNodeDetails(node, this.theme, job.live.observedAt, activity)] };
+    }
+    executionsOf(job, nodeId) {
+        const executions = job.result?.executions ?? job.execution?.executions ?? {};
+        return Object.values(executions).filter(execution => execution.id === nodeId).map(execution => execution.executionId);
+    }
+    open(job, nodeId) {
+        const executionId = this.executionsOf(job, nodeId).at(-1);
+        this.focus = executionId ? { executionId } : { nodeId };
+        this.follow = true;
+        this.offset = 0;
+    }
     handleInput(data) {
-        if (matchesKey(data, "escape") ||
-            data === "q" ||
-            matchesKey(data, "ctrl+c")) {
-            this.dispose();
-            this.done();
+        if (data === "q" || matchesKey(data, "ctrl+c")) {
+            this.close();
             return;
         }
         const jobs = this.jobs.list();
         const index = Math.max(0, jobs.findIndex((job) => job.jobId === this.selected));
-        if (matchesKey(data, "left") || matchesKey(data, "right")) {
+        const job = this.selected ? this.jobs.get(this.selected) : undefined;
+        if (this.focus)
+            this.sessionInput(data, job);
+        else if (this.choosing !== undefined && job)
+            this.chooseInput(data, job);
+        else if (matchesKey(data, "escape")) {
+            this.close();
+            return;
+        }
+        else if (data === "v" && job) {
+            const ids = this.nodeIds(job);
+            this.choosing = ids.find(id => (job.result?.nodes ?? job.live.nodes)[id]?.status === "running") ?? ids[0];
+        }
+        else 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.offset = 0;
         }
-        else if (matchesKey(data, "up"))
+        else
+            this.scroll(data);
+        if (data === "c" && this.selected)
+            this.jobs.cancel(this.selected);
+        this.refresh();
+    }
+    chooseInput(data, job) {
+        const ids = this.nodeIds(job);
+        const at = Math.max(0, ids.indexOf(this.choosing));
+        if (matchesKey(data, "escape") || matchesKey(data, "backspace"))
+            this.choosing = undefined;
+        else if (matchesKey(data, "up") || matchesKey(data, "left"))
+            this.choosing = ids[(at - 1 + ids.length) % ids.length];
+        else if (matchesKey(data, "down") || matchesKey(data, "right"))
+            this.choosing = ids[(at + 1) % ids.length];
+        else if (matchesKey(data, "enter") && this.choosing !== undefined)
+            this.open(job, this.choosing);
+        else
+            this.scroll(data);
+    }
+    sessionInput(data, job) {
+        if (matchesKey(data, "escape") || matchesKey(data, "backspace")) {
+            // Return to selection on the same node, so another node is one keypress away.
+            const focus = this.focus;
+            let nodeId;
+            try {
+                nodeId = job && ("nodeId" in focus ? focus.nodeId : this.jobs.getNode(job.jobId, undefined, focus.executionId).id);
+            }
+            catch { /* The node was removed; fall back to the plain graph. */ }
+            this.focus = undefined;
+            this.choosing = nodeId !== undefined && job && this.nodeIds(job).includes(nodeId) ? nodeId : undefined;
+            this.offset = 0;
+        }
+        else if ((matchesKey(data, "left") || matchesKey(data, "right")) && job) {
+            let node;
+            try {
+                node = "nodeId" in this.focus ? this.jobs.getNode(job.jobId, this.focus.nodeId) : this.jobs.getNode(job.jobId, undefined, this.focus.executionId);
+            }
+            catch {
+                return;
+            }
+            const siblings = this.executionsOf(job, node.id);
+            const at = node.executionId ? siblings.indexOf(node.executionId) : -1;
+            const next = siblings[at + (matchesKey(data, "right") ? 1 : -1)];
+            if (next) {
+                this.focus = { executionId: next };
+                this.follow = true;
+            }
+        }
+        else if (matchesKey(data, "end"))
+            this.follow = true;
+        else if (matchesKey(data, "ctrl+o"))
+            this.session.toggleExpanded();
+        else
+            this.scroll(data);
+    }
+    scroll(data) {
+        const before = this.offset;
+        if (matchesKey(data, "up"))
             this.offset = Math.max(0, this.offset - 1);
         else if (matchesKey(data, "down"))
             this.offset = Math.min(this.maxOffset, this.offset + 1);
@@ -146,9 +324,19 @@ export class BraidPanel {
             this.offset = Math.max(0, this.offset - 10);
         else if (matchesKey(data, "pageDown"))
             this.offset = Math.min(this.maxOffset, this.offset + 10);
-        else if (data === "c" && this.selected)
-            this.jobs.cancel(this.selected);
-        this.refresh();
+        else if (matchesKey(data, "home"))
+            this.offset = 0;
+        else
+            return;
+        // Scrolling up pauses following; reaching the bottom resumes it.
+        if (this.offset < before)
+            this.follow = false;
+        else if (this.offset >= this.maxOffset)
+            this.follow = true;
+    }
+    close() {
+        this.dispose();
+        this.done();
     }
     invalidate() { }
     dispose() {
@@ -159,19 +347,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 +433,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;
+}