@chrok/pi-braid 0.4.0 → 0.5.0

package/README.md

@@ -2,37 +2,38 @@
 
 [![npm](https://img.shields.io/npm/v/%40chrok%2Fpi-braid?label=%40chrok%2Fpi-braid)](https://www.npmjs.com/package/@chrok/pi-braid)
 
-This optional Pi extension runs Braid agent graphs as background jobs by default, with
+This optional Pi extension runs Braid agent graphs as background jobs, with
 bounded loops, live updates, pause/resume, and a live flow panel.
 
-**0.4 API:** The npm badge shows the published version; see
+**0.5 API:** The npm badge shows the published version; see
 [GitHub releases](https://github.com/Epsirom/braid/releases) for release notes.
-Review the [0.3 → 0.4 migration guide](https://github.com/Epsirom/braid/blob/v0.4.0/docs/compatibility.md#migrating-from-03-to-04)
-before upgrading: print and JSON runs wait for background jobs, Pi SDK sessions
-in the default print mode drain jobs before `session.prompt()` returns, and
-blocking mode is deprecated. Users coming from 0.2 also need the
-[0.2 → 0.3 guide](https://github.com/Epsirom/braid/blob/v0.4.0/docs/compatibility.md#migrating-from-02-to-03),
+Review the [0.4 → 0.5 migration guide](https://github.com/Epsirom/braid/blob/v0.5.0/docs/compatibility.md#migrating-from-04-to-05)
+before upgrading: running executions can pause and resume, configured node
+timeouts pause by default, and blocking mode is removed. Users coming from
+0.3 also need the [0.3 → 0.4 guide](https://github.com/Epsirom/braid/blob/v0.5.0/docs/compatibility.md#migrating-from-03-to-04)
+for print/JSON job draining and Pi SDK behavior. Users coming from 0.2 also need the
+[0.2 → 0.3 guide](https://github.com/Epsirom/braid/blob/v0.5.0/docs/compatibility.md#migrating-from-02-to-03),
 and users coming from 0.1 the
-[0.1 → 0.2 guide](https://github.com/Epsirom/braid/blob/v0.4.0/docs/compatibility.md#migrating-from-01-to-02).
+[0.1 → 0.2 guide](https://github.com/Epsirom/braid/blob/v0.5.0/docs/compatibility.md#migrating-from-01-to-02).
 For the previous release, use the
-[0.3.6 guide](https://github.com/Epsirom/braid/blob/v0.3.6/integrations/pi/README.md).
+[0.4.0 guide](https://github.com/Epsirom/braid/blob/v0.4.0/integrations/pi/README.md).
 
 It registers:
 
 - `braid` — submit a graph with optional bounded loops; receive a `jobId`
-  immediately in background mode (print/JSON runs wait for it before exiting), or
-  final results in deprecated blocking mode.
+  immediately (print/JSON runs wait for it before exiting).
 - `braid_status` — retrieve progress and results with `{ "jobId": "..." }`, or
   add `"executionId": "..."` for an exact invocation's full output/error.
   `"nodeId": "..."` selects that definition's latest invocation. Omit all IDs
   to list jobs in the current session.
 - `braid_update` / `braid_resume` — edit live definitions or release paused executions.
-- `braid_cancel` — cancel a job with `{ "jobId": "..." }`.
+- `braid_pause` — pause running executions, or the whole job, without losing their
+  work; with `after: true`, hold a running execution's result once it finishes.
+- `braid_cancel` — cancel a job with `{ "jobId": "..." }`, or add
+  `"executionIds"` to fail only those executions.
 - `braid_finish` — print/JSON runs only: record the run outcome with
   `{ "status": "success" | "failure", "summary": "..." }`.
 - `/braid [jobId]` — open a live flow panel in interactive Pi.
-- `/braid:blocking [on|off]` — deprecated, removed in 0.5.0: enable or disable
-  blocking for new `braid` tool calls; omit the argument to show the current mode.
 - `/braid:review [target or focus]` — run a bounded parallel review/fix loop.
 - `/braid:clear` — clear the progress widget above the editor; run it again while
   the widget is empty to restore what was cleared.
@@ -107,41 +108,13 @@ after outstanding Braid jobs drain. Hosts that stay running and want reminders
 to start new runs after settling should bind with another mode, for example
 `session.bindExtensions({ mode: "rpc" })`.
 
-### Blocking mode (deprecated)
+### Migrating from blocking mode
 
-> **Deprecated:** `--braid-blocking` and `/braid:blocking` will be removed in
-> 0.5.0. Print and JSON runs now wait for background jobs (see above), which keeps
-> `pauseAfter`, reminders, and live updates, and `braid_finish` sets the exit
-> status. To migrate, drop `--braid-blocking` (or `/braid:blocking on`) from the
-> command line ([#80](https://github.com/Epsirom/braid/issues/80)). Using either
-> prints a one-time warning: on stderr in print/JSON mode, or as a UI notice.
-
-Until then, to make each `braid` call wait in the foreground, enable blocking when starting Pi:
-
-```sh
-pi --braid-blocking -p "Use Braid to review the changes and summarize the results."
-```
-
-With `@chrok/pi-braid` installed, `--braid-blocking` makes every `braid` tool call
-wait for the entire graph and workspace cleanup, then return final status, outputs,
-and usage directly. The parent can summarize those results before `pi -p` exits.
-It also works with `--mode json` for structured tool results. The CLI flag sets the
-initial mode; within a session, use `/braid:blocking on` to enable it,
-`/braid:blocking off` to disable it, or `/braid:blocking` to check the current mode.
-Switching affects only new `braid` tool calls; running jobs keep their original
-mode. The session override is not persisted. These are user controls, not model
-tool parameters; the default remains background execution.
-For CI pass/fail decisions, inspect the returned job status: a failed graph does
-not by itself set Pi's process exit code.
-Blocking calls emit an initial progress update with the job handle while waiting.
-They suppress node/job completion reminders except for cancellation: stopping the
-foreground response cancels their work, waits for cleanup, and sends a reminder
-so the next turn can retrieve partial outputs and recovery checkpoints.
-Wait/result retrieval errors include the existing job handle and any terminal
-usage; retrieve that job with `braid_status` instead of submitting the graph again.
-`pauseAfter: true` is rejected before starting a blocking job because it requires
-a later resume call. The interactive
-`/braid:review` command continues to use its background review workflow.
+Blocking mode, `--braid-blocking`, and `/braid:blocking` are removed in 0.5.0.
+Drop the flag or command. Print and JSON runs wait for background jobs before
+exiting, and `braid_finish` sets the run outcome. The parent submits the graph,
+ends its turn, and retrieves results with `braid_status` after the completion
+reminder. `pauseAfter`, reminders, and live updates remain available.
 
 Jobs live in memory for the current Pi session. Quitting, reloading extensions,
 or switching/forking sessions aborts outstanding work and suppresses its
@@ -261,7 +234,18 @@ the current graph revision and paused execution IDs, then:
 ```
 
 Pass this to `braid_update`. It validates and commits the full change and resume
-atomically. To continue without edits, call `braid_resume({jobId,
+atomically.
+
+`pauseAfter` is captured when an execution starts, so changing it with
+`braid_update` affects only later executions. To review the result of an
+execution that is already running, call `braid_pause({jobId, executionIds,
+after: true})`. The execution is not suspended: it keeps running, and once it
+finishes, completed or failed, it is held exactly like `pauseAfter`, with a pause
+reminder. `braid_resume({jobId, executionIds, after: true})` removes the hold
+while it is still running, including one that came from `pauseAfter`. Either
+way only those executions change, not their node definitions. A result that is
+already held is released with the usual `braid_resume` or `braid_update`
+`resume`. To continue without edits, call `braid_resume({jobId,
 expectedRevision, executionIds})`. Definitions can be changed while executions
 are running or waiting, including inside a loop. Existing instances keep their
 captured prompt, inputs, and policy; completion routes through the latest graph.
@@ -298,6 +282,50 @@ See [execution control](../../docs/execution-control.md) for loop schemas, exact
 update semantics, historical dependencies, and workspace lineage. There is no
 scheduler persistence across Pi reloads. Reminders alone do not pause execution.
 
+### Pausing running executions
+
+`pauseAfter` holds a result after the execution finishes. To stop work that is
+still running, call `braid_pause({jobId, executionIds})`. Each execution finishes
+its running tool, then stops before its next model request. It keeps its
+conversation, workspace, and tool budgets, and releases its concurrency slot to
+other nodes. Messages sent to it from the `/braid` assistant while it is paused
+are delivered when it resumes. Resume with `braid_resume({jobId, expectedRevision,
+executionIds})` or `braid_update` with `resume`; the worker continues the same
+conversation. A transient-error retry also waits at the pause point before resending.
+
+Omit `executionIds` to pause the whole job: no new executions start and running
+ones pause. `braid_resume({jobId})` resumes the job and the executions that the
+job pause paused; executions paused separately stay paused.
+
+The node timeout stops while an execution is suspended; the graph timeout keeps
+running. `braid_status` shows suspended executions, a job pause, and who paused
+them.
+
+### Node timeouts
+
+When an execution exceeds `options.nodeTimeoutMs`, it is paused instead of
+failed. Its current model request or shell command is stopped; the interrupted
+call, with any output it produced, and any calls after it in the same batch are
+recorded in its conversation. Its conversation, workspace, and tool budgets are
+kept, and its successors wait. The parent is woken with a reminder that says how
+long the execution ran, what it was doing, and what it can do next:
+
+- `braid_resume({jobId, expectedRevision, executionIds})` gives it the job's
+  `nodeTimeoutMs` again; add `nodeTimeoutMs` for a different budget.
+- `braid_update` with `resume` and `resumeOptions: { nodeTimeoutMs }` resumes it
+  together with graph changes.
+- `braid_cancel({jobId, executionIds})` fails only that execution with
+  `NODE_TIMEOUT`; its successors follow the usual failure rules.
+
+Resuming the whole job does not resume a timeout pause. Set
+`options.onNodeTimeout: "fail"` to fail on timeout instead.
+
+Users can pause and hold from the panel too (`p` and `h`, below). The parent is not woken for
+that: one notice with the latest state per execution or job is added to its next
+turn, and it is told not to resume work the user paused unless the user asks.
+In print and JSON runs, a job held only by pauses counts as stalled: the parent
+gets one warning, and the job is cancelled if it ends the next turn without resuming.
+
 ## Live flow panel
 
 In interactive Pi, background progress appears automatically **above the input
@@ -323,13 +351,24 @@ 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,
 and pass outputs downstream.
 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
+cancel the selected job, `p` to pause or resume it, and Escape or `q` to close the panel.
+In node selection or an open session, `p` pauses or resumes that node's latest
+execution instead; a suspended node shows `‖ PAUSED`, and one paused by its node
+timeout also shows `timed out`. `h` holds that execution's result once it
+finishes, removes the hold if one is set (its status shows `· hold`), or
+releases a result that is already held. Press `x` twice there to cancel only
+that execution; the parent gets a notice with its next turn. 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.
 
+For loops, a forward edge opposite a feedback edge is drawn dotted, while the
+retry feedback edge stays solid. For example, `/braid:review` shows the direct
+`scope → check` handoff dotted and `check → scope` (`retry`) solid. All edges and
+choice labels remain visible; runtime dependencies and handoffs are unchanged.
+
 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
@@ -617,7 +656,9 @@ pass any of these fields in the `braid` tool's `options`:
 | --- | --- |
 | `maxToolRounds` | Maximum assistant responses containing tool calls, per node |
 | `maxToolCalls` | Maximum total requested tool calls, per node |
-| `nodeTimeoutMs` | Time allowed for each node after it starts, in milliseconds |
+| `maxModelRetries` | Retries per model request for transient provider errors; default 3, `0` disables, at most 10 |
+| `nodeTimeoutMs` | Active time allowed for each node after it starts, excluding pauses, in milliseconds |
+| `onNodeTimeout` | `pause` (default) suspends a timed-out node and wakes the parent; `fail` fails it with `NODE_TIMEOUT` |
 | `graphTimeoutMs` | Time allowed for the entire graph, including queueing and pauses, in milliseconds |
 | `maxExecutions` | Total materialized execution records, including skips; default 1000, positive safe integer |
 
@@ -695,9 +736,8 @@ fails that node cleanly and does not invoke another provider.
 
 The Pi extension has no node or graph time limit by default. Use `braid_cancel`
 or press `c` in the flow panel to abort running nodes and mark queued nodes
-`cancelled`. In the default background mode, Escape stops the foreground response
-or closes the panel without cancelling jobs. In blocking mode, stopping the
-foreground response also cancels its Braid job. To set a node or graph timeout,
+`cancelled`. Escape stops the foreground response or closes the panel without
+cancelling jobs. To set a node or graph timeout,
 supply milliseconds in the submission tool input under `options`; each omitted
 timeout remains unlimited:
 
@@ -709,8 +749,8 @@ timeout remains unlimited:
 }
 ```
 
-The adapter sets `maxRetries: 0`, `cacheRetention: "none"`, and gives each node a
-fresh provider context. Tool budgets are unlimited unless `maxToolRounds` or
+The adapter sets `cacheRetention: "none"` and gives each node a fresh provider
+context. Tool budgets are unlimited unless `maxToolRounds` or
 `maxToolCalls` is set. Missing paths, invalid arguments, disallowed writes, and
 unavailable tools are returned as tool errors so the node can recover. Provider
 authentication and calls may still incur normal provider costs. Braid cannot
@@ -719,6 +759,29 @@ cancellation. Cancellation prevents further tool calls but does not roll back
 writes already made. Core waits for tracked writes, preserves checkpoints, and
 removes worker worktrees before completing cancellation.
 
+### Transient model errors
+
+A transient provider error, such as a rate limit (HTTP 429), overload, a 5xx
+response, or a dropped connection, is retried inside the running node execution.
+The node keeps its conversation, tool results, workspace, decision, merge state,
+and tool-budget counts; the failed request is sent again with the same context.
+Tools run only after a complete model response, so a retry never repeats a
+completed tool call. `options.maxModelRetries` sets the retries for each model
+request (default 3; `0` disables them):
+
+- If the provider rejects a request before its response starts, Pi's provider
+  client retries it with exponential backoff and honors `Retry-After`. A requested
+  wait longer than 60 seconds fails immediately.
+- If a response stream fails after it started, Braid discards the partial
+  response and restarts the request after 2, 4, then 8 seconds.
+
+Quota, billing, and other non-transient errors are not retried. Retries stop on
+cancellation, and Braid does not start a wait that would outlast the node or
+graph deadline. When retries run out, the node fails with the provider error and
+follows the usual failure rules, including `requireSuccess`. Failed attempts stay
+visible in the session view, and their reported usage is counted. Braid does not
+retry a whole node execution.
+
 The tool output is capped at 50KB/2000 lines to protect Pi context. When exceeded,
 the adapter writes the complete text to a temporary file (mode 600 on POSIX;
 inherited ACLs on Windows) and ends the preview with its path, for running jobs

package/dist/command.js

@@ -38,6 +38,10 @@ export class BraidPanel {
     chatOffset = 0;
     chatMaxOffset = 0;
     chatScope;
+    /** The outcome of the last pause, resume, or cancel key, until the next key. */
+    notice;
+    /** An execution x was pressed for once; a second x cancels it. */
+    cancelling;
     input;
     session;
     chat;
@@ -163,20 +167,20 @@ export class BraidPanel {
             ? ["Enter send   Esc stop or hide   Tab hide   PgUp/PgDn or wheel scroll   ctrl+c close",
                 "Enter send · Esc hide · Tab hide", "Enter send · Tab hide"]
             : this.focus
-                ? [`${tab}Esc back   ←/→ executions   ↑/↓ scroll   End follow   ctrl+o tools   c cancel   q close`,
-                    "Esc back · ←/→ executions · ↑/↓ scroll · q close", "Esc back · q close"]
+                ? [`${tab}Esc back   ←/→ executions   ↑/↓ scroll   End follow   ctrl+o tools   p pause   h hold   x cancel execution   c cancel job   q close`,
+                    "Esc back · ←/→ executions · p pause · q close", "Esc back · q close"]
                 : this.choosing !== undefined
-                    ? [`${tab}↑/↓/←/→ choose node   Enter open session   Esc back   PgUp/PgDn page   q close`,
-                        "↑/↓ choose · Enter open · Esc back", "Enter open · Esc back"]
-                    : [`${tab}v select node   ←/→ jobs   ↑/↓ scroll   PgUp/PgDn page   c cancel   Esc close`,
-                        "v select node · ←/→ jobs · ↑/↓ scroll · Esc close", "v select · Esc close"];
+                    ? [`${tab}↑/↓/←/→ choose node   Enter open session   p pause   h hold   x cancel execution   Esc back   PgUp/PgDn page   q close`,
+                        "↑/↓ choose · Enter open · p pause · Esc back", "Enter open · Esc back"]
+                    : [`${tab}v select node   ←/→ jobs   ↑/↓ scroll   p pause job   c cancel   Esc close`,
+                        "v select node · ←/→ jobs · p pause job · Esc close", "v select · Esc close"];
         const help = contentWidth >= 80 ? wide : contentWidth >= 42 ? medium : narrow;
         const status = graph ? graph.range : "Assistant";
         return [
             ...header,
             ...body.map(line => line === SEPARATOR ? rule("├", "┤") : row(line)),
             rule("├", "┤"),
-            row(this.theme.fg("dim", `${status}${contentWidth >= 60 ? "  ·  Jobs keep running when this panel closes" : ""}`)),
+            row(this.theme.fg("dim", this.notice ? plain(this.notice) : `${status}${contentWidth >= 60 ? "  ·  Jobs keep running when this panel closes" : ""}`)),
             row(this.theme.fg("muted", help)),
             rule("╰", "╯"),
         ];
@@ -396,6 +400,24 @@ export class BraidPanel {
         const jobs = this.jobs.list();
         const index = Math.max(0, jobs.findIndex((job) => job.jobId === this.selected));
         const job = this.selected ? this.jobs.get(this.selected) : undefined;
+        this.notice = undefined;
+        const confirming = this.cancelling;
+        this.cancelling = undefined;
+        if (data === "p" && job) {
+            this.togglePause(job);
+            this.refresh();
+            return;
+        }
+        if (data === "h" && job && (this.focus || this.choosing !== undefined)) {
+            this.toggleHold(job);
+            this.refresh();
+            return;
+        }
+        if (data === "x" && job && (this.focus || this.choosing !== undefined)) {
+            this.cancelExecution(job, confirming);
+            this.refresh();
+            return;
+        }
         if (this.focus)
             this.sessionInput(data, job);
         else if (this.choosing !== undefined && job)
@@ -419,6 +441,103 @@ export class BraidPanel {
             this.jobs.cancel(this.selected);
         this.refresh();
     }
+    /**
+     * p pauses or resumes what is in view: the open execution, the selected
+     * node's latest execution, or the whole job. The parent agent gets a notice.
+     */
+    togglePause(job) {
+        const execution = job.execution;
+        try {
+            if (!execution || job.status !== "running")
+                throw new Error("Only a running job can be paused");
+            const executionId = this.executionInView(job);
+            if (!this.focus && this.choosing === undefined) {
+                if (execution.pause) {
+                    this.jobs.resumeJob(job.jobId, "user");
+                    this.notice = "Job resumed";
+                }
+                else {
+                    this.jobs.pause(job.jobId, undefined, "user");
+                    this.notice = "Job paused · no new executions start; running ones stop before their next model request";
+                }
+                return;
+            }
+            if (!executionId)
+                throw new Error("This node has not run yet");
+            const record = execution.executions[executionId];
+            if (record?.suspension && record.suspension.state !== "resuming") {
+                this.jobs.resume(job.jobId, [executionId], execution.revision, "user");
+                this.notice = "Execution resumed";
+            }
+            else {
+                this.jobs.pause(job.jobId, [executionId], "user");
+                this.notice = "Pausing · the execution stops before its next model request";
+            }
+        }
+        catch (error) {
+            this.notice = `Cannot pause or resume: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
+    /**
+     * h toggles the hold on the execution in view: a running one keeps running and
+     * is held when it finishes; a held result is released. The parent agent gets a notice.
+     */
+    toggleHold(job) {
+        const execution = job.execution;
+        try {
+            if (!execution || job.status !== "running")
+                throw new Error("Only a running job can hold results");
+            const executionId = this.focus
+                ? "executionId" in this.focus ? this.focus.executionId : this.executionsOf(job, this.focus.nodeId).at(-1)
+                : this.executionsOf(job, this.choosing).at(-1);
+            if (!executionId)
+                throw new Error("This node has not run yet");
+            if (execution.pausedExecutionIds.includes(executionId)) {
+                this.jobs.resume(job.jobId, [executionId], execution.revision, "user");
+                this.notice = "Released · the result goes downstream";
+            }
+            else if (execution.executions[executionId]?.holdAfter) {
+                this.jobs.holdAfter(job.jobId, [executionId], false, "user");
+                this.notice = "Hold removed · the result goes downstream when the execution finishes";
+            }
+            else {
+                this.jobs.holdAfter(job.jobId, [executionId], true, "user");
+                this.notice = "Holding · the execution keeps running; its result waits for release when it finishes";
+            }
+        }
+        catch (error) {
+            this.notice = `Cannot hold or release: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
+    /** The open execution, or the selected node's latest one. */
+    executionInView(job) {
+        return this.focus
+            ? "executionId" in this.focus ? this.focus.executionId : this.executionsOf(job, this.focus.nodeId).at(-1)
+            : this.choosing !== undefined ? this.executionsOf(job, this.choosing).at(-1) : undefined;
+    }
+    /**
+     * x cancels the execution in view after a second x: only it fails, and its
+     * successors follow the usual failure rules. The parent agent gets a notice.
+     */
+    cancelExecution(job, confirming) {
+        try {
+            if (!job.execution || job.status !== "running")
+                throw new Error("The job is not running");
+            const executionId = this.executionInView(job);
+            if (!executionId)
+                throw new Error("This node has not run yet");
+            if (confirming !== executionId) {
+                this.cancelling = executionId;
+                this.notice = "Press x again to cancel this execution · it fails and its successors follow the failure rules";
+                return;
+            }
+            this.jobs.cancelExecutions(job.jobId, [executionId], "user");
+            this.notice = "Execution cancelled";
+        }
+        catch (error) {
+            this.notice = `Cannot cancel: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
     chooseInput(data, job) {
         const ids = this.nodeIds(job);
         const at = Math.max(0, ids.indexOf(this.choosing));

package/dist/display.js

@@ -1,6 +1,6 @@
 import { render as renderMermaid } from "grok-mermaid";
 import { Text, sliceByColumn, stripTerminalSequences, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
-import { formatActivityStatus, } from "@chrok/braid";
+import { formatActivityStatus, formatPauseSource, } from "@chrok/braid";
 export const MAX_VISIBLE_EVENTS = 80;
 export const MAX_VISIBLE_NODES = 80;
 class FixedLines {
@@ -123,6 +123,8 @@ function graphParts(result) {
                 from: event.from,
                 to: event.to,
                 ...(event.choice ? { choice: event.choice } : {}),
+                ...(event.feedback ? { feedback: event.feedback } : {}),
+                ...(event.executionId ? { executionId: event.executionId } : {}),
             });
         }
     }
@@ -164,22 +166,27 @@ function mermaidLabelLines(id, result, selected = false) {
     const node = result.nodes[id];
     if (!node)
         return [compact(id, 24), "pending"];
-    const icon = node.status === "running"
-        ? "▶ ACTIVE"
-        : {
-            completed: "✓",
-            failed: "✗",
-            skipped: "·",
-            runnable: "◇",
-            pending: "○",
-        }[node.status];
-    const status = node.status === "completed" ? "done" : node.status;
+    const suspended = node.suspension && node.suspension.state !== "pausing";
+    const icon = suspended
+        ? "‖ PAUSED"
+        : node.status === "running"
+            ? "▶ ACTIVE"
+            : {
+                completed: "✓",
+                failed: "✗",
+                skipped: "·",
+                runnable: "◇",
+                pending: "○",
+            }[node.status];
+    const status = node.suspension
+        ? `${node.suspension.state}${node.suspension.source === "node_timeout" ? " · timed out" : ""}`
+        : node.status === "completed" ? "done" : node.status;
     const decision = node.decision === undefined ? "" : ` → ${compact(node.decision, 16)}`;
     const now = "observedAt" in result ? result.observedAt : Date.now();
     const iteration = "executions" in result ? result.executions[node.executionId ?? ""]?.iteration : result.iterations?.[id];
     const lines = [
         `${selected ? SELECTED_NODE_MARK + icon.slice(1) : icon} ${compact(id, 24)}${iteration ? ` #${iteration}` : ""}`,
-        `${status}${decision} · ${nodeElapsed(node, now)}`,
+        `${status}${node.holdAfter && (node.status === "running" || node.status === "runnable") ? " · hold" : ""}${decision} · ${nodeElapsed(node, now)}`,
     ];
     if (progress) {
         const window = progress.contextWindow === undefined
@@ -192,6 +199,7 @@ function mermaidLabelLines(id, result, selected = false) {
 }
 function mermaidSource(result, selected) {
     const parts = graphParts(result);
+    const feedbackSources = new Map(parts.edges.filter(edge => edge.feedback !== undefined).map(edge => [edge.to, edge.from]));
     const ids = Object.keys(parts.nodes);
     const names = new Map(ids.map((id, index) => [id, `n${index}`]));
     const escapeMermaidText = (value) => stripTerminalSequences(value)
@@ -214,7 +222,9 @@ function mermaidSource(result, selected) {
         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)}`);
+        // Distinguish the direct data handoff from its reverse retry edge.
+        const arrow = edge.feedback === undefined && feedbackSources.get(edge.from) === edge.to ? "-.->" : "-->";
+        lines.push(`  ${names.get(edge.from)} ${arrow}${edge.choice ? `|${escapeMermaidText(edge.choice)}|` : ""} ${names.get(edge.to)}`);
     }
     return lines.join("\n");
 }
@@ -285,6 +295,12 @@ function eventText(event) {
         case "graph_updated": return `graph updated · revision ${event.revision}`;
         case "execution_paused": return `paused · ${compact(event.nodeId, 40)} · ${event.executionId}`;
         case "execution_resumed": return `resumed · ${compact(event.nodeId, 40)} · ${event.executionId}`;
+        case "execution_suspending": return `pausing · ${compact(event.nodeId, 40)} · by ${compact(formatPauseSource(event.source), 20)}`;
+        case "execution_suspended": return `suspended · ${compact(event.nodeId, 40)} · by ${compact(formatPauseSource(event.source), 20)}`;
+        case "execution_hold_added": return `hold added · ${compact(event.nodeId, 40)} · by ${compact(event.source, 20)}`;
+        case "execution_hold_removed": return `hold removed · ${compact(event.nodeId, 40)} · by ${compact(event.source, 20)}`;
+        case "graph_paused": return `job paused · by ${compact(event.source, 20)}`;
+        case "graph_resumed": return "job resumed";
         case "loop_started": return `loop ${compact(event.loopId, 40)} · iteration ${event.iteration}`;
         case "loop_completed": return `loop ${compact(event.loopId, 40)} completed · iteration ${event.iteration}`;
         case "graph_created":
@@ -347,7 +363,7 @@ export function createLiveState() {
         progress: Object.create(null),
         events: [],
         latencyMs: 0,
-        observedAt: Date.now(), revision: 0, pausedExecutionIds: [], iterations: Object.create(null),
+        observedAt: Date.now(), revision: 0, pausedExecutionIds: [], suspendedExecutionIds: [], iterations: Object.create(null),
     };
 }
 export function applyEvent(state, event) {
@@ -374,12 +390,16 @@ export function applyEvent(state, event) {
             from: event.from,
             to: event.to,
             ...(event.choice ? { choice: event.choice } : {}),
+            ...(event.feedback ? { feedback: event.feedback } : {}),
+            ...(event.executionId ? { executionId: event.executionId } : {}),
         });
     if (state.events.length > MAX_VISIBLE_EVENTS)
         state.events.shift();
     if (event.type === "graph_completed" || event.type === "graph_failed") {
         state.status = event.type === "graph_completed" ? "completed" : "failed";
         state.pausedExecutionIds = [];
+        state.suspendedExecutionIds = [];
+        delete state.pause;
         if (event.type === "graph_failed")
             state.error = { ...event.error };
         return;
@@ -416,8 +436,16 @@ export function applyEvent(state, event) {
     }
     if (event.type === "execution_paused")
         state.pausedExecutionIds = [...(state.pausedExecutionIds ?? []), event.executionId];
+    if (event.type === "graph_paused")
+        state.pause = { source: event.source, pausedAt: event.timestamp };
+    if (event.type === "graph_resumed")
+        delete state.pause;
+    if (event.type === "execution_suspended")
+        state.suspendedExecutionIds = [...(state.suspendedExecutionIds ?? []), event.executionId];
     if (event.type === "execution_resumed")
         state.pausedExecutionIds = state.pausedExecutionIds?.filter(id => id !== event.executionId) ?? [];
+    if (event.type === "execution_resumed" || event.type === "node_completed" || event.type === "node_failed")
+        state.suspendedExecutionIds = state.suspendedExecutionIds?.filter(id => id !== event.executionId) ?? [];
     const node = "nodeId" in event && Object.hasOwn(state.nodes, event.nodeId)
         ? state.nodes[event.nodeId]
         : undefined;
@@ -445,8 +473,24 @@ export function applyEvent(state, event) {
             node.status = "running";
             node.startedAt = event.timestamp;
             break;
+        case "execution_suspending":
+            node.suspension = { state: "pausing", source: event.source, requestedAt: event.timestamp };
+            break;
+        case "execution_suspended":
+            node.suspension = { state: "suspended", source: event.source, requestedAt: node.suspension?.requestedAt ?? event.timestamp, suspendedAt: event.timestamp };
+            break;
+        case "execution_resumed":
+            delete node.suspension;
+            break;
+        case "execution_hold_added":
+            node.holdAfter = { source: event.source, requestedAt: event.timestamp };
+            break;
+        case "execution_hold_removed":
+            delete node.holdAfter;
+            break;
         case "node_completed":
         case "node_failed":
+            delete node.suspension;
             node.status = event.type === "node_completed" ? "completed" : "failed";
             node.finishedAt = event.timestamp;
             node.latencyMs = event.latencyMs;
@@ -625,8 +669,12 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
     }
     if (result.error)
         lines.push(theme.fg("error", `${result.error.code}: ${compact(result.error.message, 120)}`));
+    if ("pause" in result && result.pause)
+        lines.push(theme.fg("warning", `job paused by ${compact(result.pause.source, 20)} · no new executions start`));
     if ("pausedExecutionIds" in result && result.pausedExecutionIds?.length)
         lines.push(theme.fg("warning", `${result.pausedExecutionIds.length} paused executions · revision ${result.revision ?? 0}`));
+    if ("suspendedExecutionIds" in result && result.suspendedExecutionIds?.length)
+        lines.push(theme.fg("warning", `${result.suspendedExecutionIds.length} suspended executions · revision ${result.revision ?? 0}`));
     if ("executions" in result)
         lines.push(theme.fg("dim", `${Object.keys(result.executions).length} executions · revision ${result.revision}`));
     const chartStart = lines.length;

package/dist/drain.js

@@ -3,7 +3,7 @@ import { defineTool, } from "@earendil-works/pi-coding-agent";
 /** Pi exits once print and JSON runs settle, so Braid drains jobs before that. */
 export const isSingleShot = (ctx) => ctx.mode === "print" || ctx.mode === "json";
 export const BRAID_DRAIN_GUIDANCE = "This is a single-shot run. It stays open until every Braid job finishes and its reminder is delivered, so submit, end your turn, and continue from the reminder as usual. " +
-    "Paused executions are not resumed automatically: resume or cancel them before ending your turn. If only paused executions remain when you end a turn, you get one warning; ending the next turn without resuming them cancels their jobs and the run exits with a failure status.";
+    "Paused executions and paused jobs are not resumed automatically: resume or cancel them before ending your turn. If only paused work remains when you end a turn, you get one warning; ending the next turn without resuming it cancels those jobs and the run exits with a failure status.";
 export const BRAID_FINISH_GUIDANCE = "When the task is done and no Braid job is outstanding, call braid_finish once with status success or failure and a short summary of the outcome, then end your turn with your final response. " +
     "A failure status makes the run exit 1. braid_finish only records the outcome: the run still ends when your turn ends and every Braid job has finished. Call it again to replace the outcome if more work follows.";
 /** The run's wall-clock budget is checked by a timer, so the drain also wakes periodically. */
@@ -16,9 +16,15 @@ export function parseDuration(value) {
         throw new Error(`Invalid --braid-ci-timeout ${JSON.stringify(value)}: use a positive duration such as 90000, 90s, 30m, or 2h`);
     return ms;
 }
+const waitingOn = (job) => [
+    job.pausedExecutionIds.length ? `paused executions ${JSON.stringify(job.pausedExecutionIds)}` : "",
+    job.suspendedExecutionIds.length ? `suspended executions ${JSON.stringify(job.suspendedExecutionIds)}` +
+        (job.timedOutExecutionIds?.length ? ` (paused by their node timeout: ${JSON.stringify(job.timedOutExecutionIds)})` : "") : "",
+    job.paused ? "its job pause" : "",
+].filter(Boolean).join(" and ") || "paused work";
 const stalledReminder = (jobs) => `[system-reminder] This single-shot run cannot end while Braid jobs are outstanding, and nothing can progress: ` +
-    jobs.map(job => `${job.handle} is waiting on paused executions ${JSON.stringify(job.pausedExecutionIds)} at revision ${job.revision}`).join("; ") +
-    `. Resume them with braid_resume or braid_update with resume, or cancel the job with braid_cancel, then continue the original task. ` +
+    jobs.map(job => `${job.handle} is waiting on ${waitingOn(job)} at revision ${job.revision}`).join("; ") +
+    `. Resume executions with braid_resume or braid_update with resume, resume a paused job with braid_resume({jobId}), fail single executions with braid_cancel and executionIds, or cancel the job with braid_cancel, then continue the original task. ` +
     `If you end your turn again without doing so, Braid cancels these jobs and the run exits with a failure status. [/system-reminder]`;
 /**
  * Keeps print and JSON runs alive until every Braid job reaches a terminal
@@ -138,7 +144,7 @@ export function registerDrain(pi, jobs, hasPendingReminders) {
             if (!outstanding.length)
                 return settle(event);
             if (outstanding.every(job => job.stalled)) {
-                const key = JSON.stringify(outstanding.map(job => [job.jobId, job.revision, job.pausedExecutionIds]));
+                const key = JSON.stringify(outstanding.map(job => [job.jobId, job.revision, job.pausedExecutionIds, job.suspendedExecutionIds, job.paused]));
                 if (key !== warnedStall) {
                     warnedStall = key;
                     return {
@@ -153,7 +159,7 @@ export function registerDrain(pi, jobs, hasPendingReminders) {
                     };
                 }
                 // Cancellation reminders give the parent a final turn to report the outcome.
-                cancelOutstanding(`paused executions were never resumed; cancelled ${outstanding.map(job => job.handle).join(", ")}`);
+                cancelOutstanding(`paused work was never resumed; cancelled ${outstanding.map(job => job.handle).join(", ")}`);
             }
             await nextChange();
         }