@bastani/atomic 0.8.4 → 0.8.5-0

package/dist/builtin/web-access/README.md

@@ -235,7 +235,7 @@ Show the active Google account currently authenticated for Gemini Web. Useful wh
 
 ## Activity Monitor
 
-Toggle with **Ctrl+Shift+W** to see live request/response activity:
+Toggle with **CTRL+SHIFT+W** to see live request/response activity:
 
 ```
 ─── Web Search Activity ────────────────────────────────────

package/dist/builtin/web-access/curator-page.ts

@@ -125,9 +125,9 @@ ${CSS}
 
 <footer class="action-bar">
 <div class="action-shortcuts">
-<span class="shortcut"><kbd>A</kbd> <span>Toggle all</span></span>
+<span class="shortcut"><kbd>A</kbd> <span>Toggle All</span></span>
 <span class="shortcut"><kbd>Enter</kbd> <span>Generate</span></span>
-<span class="shortcut"><kbd>Esc</kbd> <span>Cancel</span></span>
+<span class="shortcut"><kbd>Escape</kbd> <span>Cancel</span></span>
 </div>
 <div class="action-buttons">
 <button class="btn btn-submit" id="btn-send" disabled>Waiting for results\u2026</button>

package/dist/builtin/web-access/index.ts

@@ -1523,7 +1523,7 @@ export default function (pi: ExtensionAPI) {
 				}
 				const moreLines = Math.max(0, totalLines - collapsedLines);
 				if (moreLines > 0) {
-					box.addChild(new Text(theme.fg("muted", `\n... (${moreLines} more lines, ${totalLines} total, ctrl+o to expand)`), 0, 0));
+					box.addChild(new Text(theme.fg("muted", `\n... (${moreLines} more lines, ${totalLines} total, CTRL+O Expand)`), 0, 0));
 				}
 				return box;
 			}

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.4",
+  "version": "0.8.5-0",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction.",
   "contributors": [

package/dist/builtin/workflows/README.md

@@ -69,7 +69,7 @@ export default defineWorkflow("parallel-research")
       { name: "auth-specialist", task: `Research authentication patterns for: ${topic}` },
       { name: "db-specialist", task: `Research database layer for: ${topic}` },
       { name: "api-specialist", task: `Research API surface for: ${topic}` },
-    ]);
+    ], { concurrency: 2, failFast: false });
 
     const summary = await ctx.task("aggregator", {
       prompt: "Synthesize these specialist reports:\n\n{previous}",
@@ -189,7 +189,8 @@ registry.get("alpha"); // compiled workflow definition | undefined
 | `/workflow connect [run-id]`          | Attach to a workflow run overlay                         |
 | `/workflow attach [run-id] [stage]`   | Open the attach/chat pane for a run or stage             |
 | `/workflow pause [run-id] [stage]`    | Pause a live run or stage                                |
-| `/workflow interrupt [run-id\|--all]` | Stop the active run, a named run, or all active runs     |
+| `/workflow interrupt [run-id\|--all]` | Pause active/named/all active runs so they can resume    |
+| `/workflow kill [run-id\|--all]`      | Kill and remove active/named/all active runs from status |
 | `/workflow resume <run-id>`           | Resume paused work or re-open a run snapshot             |
 | `/workflow inputs <name>`             | Print the input schema for a workflow                    |
 
@@ -206,7 +207,11 @@ Workflows always run as **background tasks** — the chat editor stays free whil
   "parameters": {
     "workflow": "string (optional) — workflow ID or normalized name",
     "inputs": "object (optional) — key/value map of workflow inputs",
-    "action": "'run' | 'list' | 'get' | 'inputs' | 'status' | 'interrupt' | 'resume'",
+    "action": "'run' | 'list' | 'get' | 'inputs' | 'status' | 'interrupt' | 'kill' | 'resume'",
+    "runId": "optional run id or unique prefix; interrupt/kill default to the active run; use '--all' or all:true for interrupt/kill all",
+    "stageId": "optional stage id, prefix, or name for resume",
+    "message": "optional resume message",
+    "all": "optional boolean for interrupt/kill all",
     "task/tasks/chain": "optional direct workflow-native orchestration modes"
   }
 }
@@ -234,14 +239,35 @@ const definition = {
   inputs: {
     prompt: "Investigate the auth module",
     max_partitions: 6,
+    max_concurrency: 4,
   },
 } as const;
 
 const options: WorkflowOptions = {};
 
 await runWorkflow(definition, options);
+
+await runWorkflow({
+  mode: "parallel",
+  task: "Audit auth changes",
+  tasks: [
+    { name: "security", task: "Review security risks" },
+    { name: "runtime", task: "Review runtime risks" },
+  ],
+  concurrency: 2,
+  reads: ["research/context.md"],
+  output: "research/auth-audit.md",
+  outputMode: "inline",
+  worktree: false,
+  maxOutput: { lines: 2000 },
+  artifacts: true,
+});
 ```
 
+The programmatic definition object mirrors the workflow tool: named workflow runs, single-task runs, parallel `tasks`, and mixed `chain` runs accept the same direct options (`reads`, `output`, `outputMode`, `worktree`, `maxOutput`, `artifacts`, `concurrency`, `failFast`, and stage/session options such as `cwd`, `agentDir`, `model`, `tools`, `context`, and `sessionDir`). `chainDir` is chain-only: it provides the shared artifact directory for chain reads, outputs, and worktree diffs.
+
+Workflow stage sessions follow Atomic SDK directory defaults: `DefaultResourceLoader` is initialized with the project `cwd` and the Atomic default `~/.atomic/agent` directory, while legacy `.pi` paths remain readable where the SDK supports multiple config directories. A stage-supplied `agentDir` is treated as an explicit user override; a stage-supplied `resourceLoader` owns discovery, with `cwd`/`agentDir` left for session naming and tool path resolution.
+
 To inspect a workflow's input schema inside pi, use `/workflow inputs <name>` or `/workflow <name> --help`.
 
 ---
@@ -256,10 +282,11 @@ Scout + research-history chain → two parallel specialist waves → aggregator.
 /workflow deep-research-codebase prompt="How does session persistence work?"
 ```
 
-| Input            | Type     | Required | Default | Description                                       |
-| ---------------- | -------- | -------- | ------- | ------------------------------------------------- |
-| `prompt`         | `text`   | ✓        | —       | Research question or topic to investigate.        |
-| `max_partitions` | `number` | —        | `100`   | Maximum number of codebase partitions to explore. |
+| Input             | Type     | Required | Default | Description                                               |
+| ----------------- | -------- | -------- | ------- | --------------------------------------------------------- |
+| `prompt`          | `text`   | ✓        | —       | Research question or topic to investigate.                |
+| `max_partitions`  | `number` | —        | `100`   | Maximum number of codebase partitions to explore.         |
+| `max_concurrency` | `number` | —        | `4`     | Maximum number of workflow stages to run concurrently.    |
 
 ### `ralph`
 

package/dist/builtin/workflows/builtin/deep-research-codebase.ts

@@ -15,6 +15,7 @@ import type {
 } from "../src/shared/types.js";
 
 const DEFAULT_MAX_PARTITIONS = 100;
+const DEFAULT_MAX_CONCURRENCY = 4;
 const LOC_PER_PARTITION = 10_000;
 
 type PromptSection = readonly [tag: string, content: string];
@@ -169,23 +170,34 @@ export default defineWorkflow("deep-research-codebase")
     description:
       "Maximum number of codebase partitions to explore in parallel. Actual partitions scale by one per 10K LoC, capped by this value.",
   })
+  .input("max_concurrency", {
+    type: "number",
+    default: DEFAULT_MAX_CONCURRENCY,
+    description:
+      "Maximum number of workflow stages to run concurrently during deep research.",
+  })
   .run(async (ctx) => {
     const inputs = ctx.inputs as {
       prompt?: string;
       max_partitions?: number;
+      max_concurrency?: number;
     };
     const prompt = inputs.prompt ?? "";
     const requestedMaxPartitions = positiveInteger(
       inputs.max_partitions,
       DEFAULT_MAX_PARTITIONS,
     );
+    const maxConcurrency = positiveInteger(
+      inputs.max_concurrency,
+      DEFAULT_MAX_CONCURRENCY,
+    );
     const codebaseLines = countCodebaseLines();
     const partitionCap = calculatePartitionCap(
       requestedMaxPartitions,
       codebaseLines,
     );
 
-    let noAskQuestionToolSet = ["read, bash, edit, write, todo"];
+    let noAskQuestionToolSet = ["read", "bash", "edit", "write", "todo"];
 
     let plannerModelConfig = {
       model: "openai/gpt-5.5",
@@ -274,7 +286,7 @@ export default defineWorkflow("deep-research-codebase")
           ...explorerModelConfig,
         },
       ],
-      { task: prompt },
+      { task: prompt, concurrency: maxConcurrency },
     );
 
     const scout =
@@ -427,7 +439,10 @@ export default defineWorkflow("deep-research-codebase")
       },
     );
 
-    const wave1 = await ctx.parallel(wave1Steps, { task: prompt });
+    const wave1 = await ctx.parallel(wave1Steps, {
+      task: prompt,
+      concurrency: maxConcurrency,
+    });
 
     const wave2Steps: WorkflowTaskStep[] = partitions.flatMap(
       (partition, index) => {
@@ -512,7 +527,10 @@ export default defineWorkflow("deep-research-codebase")
       },
     );
 
-    const wave2 = await ctx.parallel(wave2Steps, { task: prompt });
+    const wave2 = await ctx.parallel(wave2Steps, {
+      task: prompt,
+      concurrency: maxConcurrency,
+    });
     const historyOverview = history.at(-1)?.text ?? "";
     const specialistReports = specialistSummary(partitions, wave1, wave2);
 
@@ -567,6 +585,7 @@ export default defineWorkflow("deep-research-codebase")
       partitions,
       explorer_count: partitions.length,
       specialist_count: wave1.length + wave2.length,
+      max_concurrency: maxConcurrency,
       history: historyOverview,
     };
   })

package/dist/builtin/workflows/builtin/ralph.ts

@@ -152,7 +152,7 @@ export default defineWorkflow("ralph")
     let approved = false;
     let iterationsCompleted = 0;
 
-    let noAskQuestionToolSet = ["read, bash, edit, write, todo"];
+    let noAskQuestionToolSet = ["read", "bash", "edit", "write", "todo"];
 
     let plannerModelConfig = {
       model: "openai/gpt-5.5",

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.4",
+  "version": "0.8.5-0",
   "private": true,
   "description": "pi extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/skills/workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow
-description: Create, run, inspect, and improve pi/atomic workflows. Use whenever the user wants reusable multi-stage automation, a DAG or staged agent pipeline, workflow definitions with defineWorkflow, ctx.task/ctx.parallel/ctx.chain/ctx.stage/ctx.ui orchestration, workflow tool calls, /workflow list/inputs/connect/attach/pause/resume/status help, custom workflow discovery, model fallback chains, or context-engineered multi-session processes.
+description: Create, run, inspect, and improve pi/atomic workflows. Use whenever the user wants reusable multi-stage automation, a DAG or staged agent pipeline, workflow definitions with defineWorkflow, ctx.task/ctx.parallel/ctx.chain/ctx.stage/ctx.ui orchestration, workflow tool calls, /workflow list/inputs/connect/attach/pause/interrupt/resume/kill/status help, custom workflow discovery, model fallback chains, or context-engineered multi-session processes.
 ---
 
 # Workflow Skill
@@ -55,6 +55,10 @@ workflow({ action: "list" })
 workflow({ action: "get", workflow: "deep-research-codebase" })
 workflow({ action: "inputs", workflow: "deep-research-codebase" })
 workflow({ action: "run", workflow: "deep-research-codebase", inputs: { prompt: "map workflow runtime" } })
+workflow({ action: "status" })
+workflow({ action: "interrupt", runId: "<run-id-or-prefix>" })
+workflow({ action: "resume", runId: "<run-id-or-prefix>", stageId: "<optional-stage>", message: "continue" })
+workflow({ action: "kill", runId: "<run-id-or-prefix>" })
 ```
 
 Slash equivalents:
@@ -70,10 +74,19 @@ Slash equivalents:
 /workflow status --all
 /workflow status <run-id>
 /workflow interrupt <run-id|--all>
+/workflow kill <run-id|--all>
 /workflow resume <run-id> [stage-id-or-name] [message]
 ```
 
-Named workflow dispatch is always background-oriented: expect a run id, then monitor status/attention states. Press F2 or run `/workflow connect <run-id>` to open the live graph viewer. HIL prompts from `ctx.ui.input/confirm/select/editor` appear in that workflow UI, not as modal chat dialogs.
+Named workflow dispatch is always background-oriented: expect a run id, then monitor status/attention states. Press F2 or run `/workflow connect <run-id>` to open the live graph viewer. Use `workflow({ action: "interrupt" })` or `/workflow interrupt` for resumable interruption, and `workflow({ action: "kill" })` or `/workflow kill` only when the run should be terminated and removed from live history/status. HIL prompts from `ctx.ui.input/confirm/select/editor` appear in that workflow UI, not as modal chat dialogs.
+
+Workflow tool run-control parity:
+
+- `interrupt`, `kill`, and `resume` accept full run ids or unique prefixes via `runId`.
+- `interrupt` and `kill` default to the active run when `runId` is omitted.
+- `interrupt` and `kill` support all in-flight runs with `all: true` or `runId: "--all"`.
+- `resume` supports `stageId` as a stage id, unique prefix, or stage name, plus an optional `message` forwarded to paused work.
+- `kill` is destructive: it aborts in-flight work and removes the run from live history/status. `interrupt` is resumable and keeps the run visible.
 
 ## Direct Workflow-Native Orchestration
 
@@ -127,18 +140,41 @@ workflow({
 })
 ```
 
-Task options mirror pi session options plus workflow-owned fields such as `output`, `reads`, `progress`, `worktree`, `maxOutput`, `artifacts`, `sessionDir`, `model`, `fallbackModels`, `thinkingLevel`, and per-stage `mcp` allow/deny.
+Task options mirror pi session options plus workflow-owned fields such as `output`, `outputMode`, `reads`, `worktree`, `maxOutput`, `artifacts`, `sessionDir`, `cwd`, `agentDir`, `model`, `fallbackModels`, `thinkingLevel`, `context`, `tools`, `noTools`, `customTools`, `forkFromSessionFile`, and per-stage `mcp` allow/deny. Direct chain orchestration also supports `chainName` and `chainDir` for artifact grouping and shared chain-relative files.
 
 ## Authoring Process
 
 ### 1. Locate the workflow surface
 
-For user-authored workflows, place definitions where pi discovers them:
+Atomic/pi discovers workflow definitions in this override order:
+
+1. Configured project files from `.atomic/extensions/workflow/config.json` (`workflows.<name>.path`). Legacy `.pi/...` config paths are also considered.
+2. Project-local files in `.atomic/workflows/*.{ts,js,mjs,cjs}`. Legacy `.pi/workflows/` is also checked.
+3. Configured global files from `~/.atomic/agent/extensions/workflow/config.json`. Legacy `~/.pi/...` config paths are also considered.
+4. User-global files in `~/.atomic/agent/workflows/*.{ts,js,mjs,cjs}`. Legacy `~/.pi/agent/workflows/` is also checked.
+5. Package-provided workflow files from installed Atomic/pi packages.
+6. Bundled workflows shipped with `@bastani/workflows`.
+
+A workflow module may export one default workflow definition and/or named workflow definitions; discovery checks the default export first, then named exports.
+
+Extension config can also tune runtime behavior:
+
+```json
+{
+  "workflows": {
+    "team": { "path": "./workflows/team.ts" }
+  },
+  "defaultConcurrency": 4,
+  "maxDepth": 4,
+  "persistRuns": true,
+  "statusFile": false,
+  "resumeInFlight": "ask"
+}
+```
+
+Project config relative workflow paths resolve from the project root. Global config relative paths resolve from the user agent directory. When `statusFile` is enabled, the derived status file defaults under `.atomic/workflows/status.json` for the project.
 
-- Project-local: `.atomic/workflows/*.{ts,js,mjs,cjs}` inside the current project. Legacy `.pi/workflows/` is also checked for compatibility.
-- User-global: `~/.atomic/agent/workflows/*.{ts,js,mjs,cjs}` for workflows available across projects. Legacy `~/.pi/agent/workflows/` is also checked.
-- Configured directories: `.atomic/extensions/workflow/config.json` or `~/.atomic/agent/extensions/workflow/config.json` may add named `workflows.<name>.path` entries; legacy `.pi/...` config paths are also considered.
-- Package workflows: a pi package can expose bundled workflow directories through `package.json` under `pi.builtin`.
+Package-provided workflows can be exposed through host package metadata or a conventional `workflows/` directory; singular `workflow/` is accepted as an alias. For new Atomic package examples, prefer app-name keys when supported (for example `atomic.workflows` / `atomic.extensions`); keep `pi.workflows` / `pi.extensions` in mind for pi compatibility and existing first-party package metadata.
 
 If an existing project has workflow examples, inspect those first for import style and naming conventions. In a normal consumer project, import from the package:
 
@@ -193,18 +229,22 @@ Builder rules:
 - `.run(async (ctx) => ({ ... }))` defines the workflow body.
 - `.compile()` returns the workflow definition for discovery.
 
+**Anti-pattern: no-stage workflows.** Do not author workflows whose `run` body only performs deterministic code and returns a value without creating a tracked workflow stage. A registered workflow must call at least one of `ctx.task()`, `ctx.chain()`, `ctx.parallel()`, or `ctx.stage()` in its run body. Pure no-stage workflows are invalid, are skipped during discovery, and surface startup diagnostics because they defeat workflow orchestration and render an empty graph (`cachedLayout.length === 0`). If all work is deterministic TypeScript with no LLM/session stage, write a script or extension command instead of a workflow.
+
 Input types: `text`, `string`, `number`, `boolean`, `select`. All support `description` and `required`; defaults are type-specific; `select` requires `choices`. Runtime validation rejects unknown keys, missing required values, type mismatches, and select values outside `choices`.
 
 ### 4. Pick the right primitive
 
-| Need | Use |
+Default to the high-level primitives because they create tracked graph nodes, standardize handoffs, and keep workflow definitions readable:
+
+| Need | Preferred primitive |
 | --- | --- |
-| One LLM task with workflow tracking | `ctx.task(name, options)` |
-| Independent branches | `ctx.parallel(steps, { task? })` |
-| Dependent stages | `ctx.chain(steps, { task? })` |
-| Low-level session controls | `ctx.stage(name, options)` then `stage.prompt/complete` |
-| User interaction during run | `ctx.ui.input/confirm/select/editor` |
-| Pure computation / file I/O / parsing | Plain TypeScript in `.run()` or helpers |
+| One LLM/session task with workflow tracking | `ctx.task(name, options)` |
+| Dependent sequential tasks | `ctx.chain(steps, { task? })` |
+| Independent/concurrent branches | `ctx.parallel(steps, { task?, concurrency?, failFast? })` |
+| Human-in-the-loop decision in the workflow run | `ctx.ui.input/confirm/select/editor` |
+| Pure deterministic computation, parsing, or file I/O | Plain TypeScript in `.run()` or helpers, paired with a nearby tracked stage when it contributes to stage output |
+| Advanced/fine-grained session control | `ctx.stage(name, options)` then `stage.prompt/complete`; use when you need lower-level controls such as steer/follow-up messages, model switching, subscriptions, tree navigation, compaction, or abort |
 
 Use `previous` plus `{previous}` for context handoff. If no placeholder is present, the runtime appends context. Chain defaults: first missing task uses `{task}`, later missing tasks use `{previous}`, and missing tasks inside chain-parallel groups use `{previous}`.
 
@@ -223,7 +263,7 @@ Prefer concise structured returns and durable artifacts over dumping full transc
 
 ## Execution Model
 
-`@bastani/workflows` follows pi's package/extension model: pi loads the extension from the package manifest, and the extension registers the `workflow` tool, `/workflow` command, UI renderers, widgets, and lifecycle hooks in-process.
+`@bastani/workflows` follows Atomic/pi's package/extension model: the host loads extension metadata from supported package manifest keys (new app-name keys where available plus pi-compatible metadata used by existing packages), then the extension registers the `workflow` tool, `/workflow` command, UI renderers, widgets, and lifecycle hooks in-process.
 
 Use these supported workflow surfaces:
 
@@ -243,19 +283,38 @@ const definition = {
   inputs: {
     prompt: "map workflow sdk",
     max_partitions: 1,
+    max_concurrency: 4,
   },
 } as const;
 
 const options: WorkflowOptions = {};
 
 await runWorkflow(definition, options);
+
+await runWorkflow({
+  mode: "parallel",
+  task: "Audit auth changes",
+  tasks: [
+    { name: "security", task: "Review security risks" },
+    { name: "runtime", task: "Review runtime risks" },
+  ],
+  concurrency: 2,
+  reads: ["research/context.md"],
+  output: "research/auth-audit.md",
+  outputMode: "inline",
+  maxOutput: { lines: 2000 },
+  artifacts: true,
+});
 ```
 
+The programmatic definition object mirrors the workflow tool for named runs (`mode: "workflow"` / `"named"`), direct single-task runs (`"single"`), parallel `tasks` (`"parallel"`), mixed `chain` runs (`"chain"`), direct options, and stage/session options. Use `chainDir` for chain-local shared artifacts/relative reads/outputs/worktree diffs and `chainName` for status/artifact grouping.
+
 ## Safety and Compatibility Rules
 
 - Do not fabricate workflow names or inputs; list/inspect first with `list`, `get`, or `inputs`.
 - Do not use legacy workflow tool fields such as `agent`, `stage`, or run-control `name`.
 - Do not expect workflow-tool `create`, `update`, or `delete`; reusable definitions are code-authored.
+- For new Atomic package metadata, prefer app-name manifest keys such as `atomic.workflows`/`atomic.extensions` when supported; preserve `pi.workflows`/`pi.extensions` compatibility for existing pi packages and current first-party package metadata.
 - Use `/workflow` slash commands for named runs, input picker/help, graph attach, pause/resume, status, and diagnostics.
 - Prefer `ctx.task`, `ctx.parallel`, and `ctx.chain`; drop to `ctx.stage` only for lower-level controls.
 - Keep stage names user-readable because they appear in workflow status/UI.

package/dist/builtin/workflows/skills/workflow/references/running-workflows.md

@@ -20,19 +20,19 @@ If required inputs are missing and cannot be inferred, ask the user with `ask_us
 workflow({
   action: "run",
   workflow: "deep-research-codebase",
-  inputs: { prompt: "map workflow dispatch" },
+  inputs: { prompt: "map workflow dispatch", max_concurrency: 4 },
 })
 ```
 
 Slash equivalent:
 
 ```text
-/workflow deep-research-codebase prompt="map workflow dispatch"
+/workflow deep-research-codebase prompt="map workflow dispatch" max_concurrency=4
 ```
 
 Input overrides are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=3`, `flag=true`, and `prompt="multi word value"` preserve useful types. A whole input object can also be passed as one JSON token.
 
-Named workflow dispatch is always background-oriented: expect a run id and then monitor status. Press F2 or use `/workflow connect <run-id>` to attach to the graph viewer. If the TUI is available and required inputs are missing, `/workflow <name>` opens an input picker unless the user passes `--no-picker`.
+Named workflow dispatch is always background-oriented: expect a run id and then monitor status. Press F2 or use `/workflow connect <run-id>` to attach to the graph viewer. In the TUI, `/workflow <name>` opens an input picker when the workflow declares inputs and either no arguments were supplied or required inputs are missing; supplied values seed the picker. Pass `--no-picker` to skip that interactive flow.
 
 ## Slash command surface
 
@@ -47,10 +47,11 @@ Named workflow dispatch is always background-oriented: expect a run id and then
 /workflow status [run-id]
 /workflow status --all
 /workflow interrupt <run-id|--all>
+/workflow kill <run-id|--all>
 /workflow resume <run-id> [stage-id-or-name] [message]
 ```
 
-Use `connect` for the orchestrator graph. Use `attach` when the user wants to open a chat pane for a specific stage. Use `pause`/`resume` for live paused work; `resume` on a non-paused run reopens the saved snapshot/overlay.
+Use `connect` for the orchestrator graph. Use `attach` when the user wants to open a chat pane for a specific stage. Use `interrupt`/`pause`/`resume` for resumable live work; `resume` on a non-paused run reopens the saved snapshot/overlay. Use `kill` only when the run should be terminated and removed from live history/status. `/workflow status` lists in-flight runs by default; `/workflow status --all` includes retained ended runs as well.
 
 Human-in-the-loop prompts from `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, and `ctx.ui.editor` surface in the workflow UI/graph viewer, not as ordinary chat modals.
 
@@ -95,21 +96,42 @@ workflow({
 })
 ```
 
-Direct mode supports top-level/default options and per-task options such as `context`, `model`, `fallbackModels`, `thinkingLevel`, `mcp`, `output`, `reads`, `progress`, `worktree`, `maxOutput`, `artifacts`, `sessionDir`, and `cwd`. For large fan-outs, prefer `outputMode: "file-only"`.
+Direct mode supports top-level/default options and per-task options such as `context`, `forkFromSessionFile`, `model`, `fallbackModels`, `thinkingLevel`, `tools`, `noTools`, `customTools`, `mcp`, `output`, `outputMode`, `reads`, `worktree`, `maxOutput`, `artifacts`, `sessionDir`, `cwd`, and `agentDir`. Direct chains also support `chainName`, `chainDir`, and `failFast`; use `chainDir` for shared relative reads/outputs/worktree diffs. For large fan-outs, prefer `outputMode: "file-only"`.
 
 ## Monitor/control with the workflow tool
 
+The LLM-callable workflow tool exposes lifecycle controls with the same targeting affordances as the slash commands where a non-interactive tool call makes sense.
+
 ```ts
 workflow({ action: "status" })
-workflow({ action: "status", runId: "<id>" })
-workflow({ action: "interrupt", runId: "<id>" })
+workflow({ action: "status", runId: "<id-or-prefix>" })
+
+// Resumable interruption. Omit runId to target the active run.
+workflow({ action: "interrupt" })
+workflow({ action: "interrupt", runId: "<id-or-prefix>" })
+workflow({ action: "interrupt", all: true })
 workflow({ action: "interrupt", runId: "--all" })
-workflow({ action: "resume", runId: "<id>" })
+
+// Resume a run, optionally targeting a stage by id, prefix, or name.
+workflow({ action: "resume", runId: "<id-or-prefix>" })
+workflow({ action: "resume", runId: "<id-or-prefix>", stageId: "review", message: "continue with the approved fix" })
+
+// Destructive termination. Omit runId to target the active run.
+workflow({ action: "kill" })
+workflow({ action: "kill", runId: "<id-or-prefix>" })
+workflow({ action: "kill", all: true })
+workflow({ action: "kill", runId: "--all" })
 ```
 
-The LLM-callable tool exposes status/interrupt/resume controls. Use slash commands for graph connect, stage attach, and pause because those are interactive TUI surfaces.
+Control semantics:
+
+- `runId` accepts full run ids or unique prefixes for `status`, `interrupt`, `resume`, and `kill`.
+- `interrupt` and `kill` default to the active run when `runId` is omitted.
+- `interrupt` is resumable: it pauses live work when pausable stages exist and keeps the run in live history/status.
+- `resume` can target a stage with `stageId`; the target may be a stage id, unique prefix, or stage name. `message` is forwarded to paused work.
+- `kill` is destructive: it aborts in-flight work and removes the run from live history/status. Use it only when the user wants the workflow gone.
 
-When a run needs user input or attention, surface that to the user instead of polling silently.
+Use slash commands for graph connect and stage attach because those are interactive TUI surfaces. When a run needs user input or attention, surface that to the user instead of polling silently.
 
 ## Intercom
 
@@ -133,4 +155,5 @@ Treat intercom payloads as user-visible workflow output.
 - Do not use legacy tool fields like `agent`, `stage`, or run-control `name`.
 - Do not expect named workflow runs to block the chat turn; they are background tasks.
 - Prefer `outputMode: "file-only"` for large fan-outs.
-- Use status/resume controls for run lifecycle; inspect workflow output and artifacts for behavior.
+- Use status/interrupt/resume/kill controls for run lifecycle; inspect workflow output and artifacts for behavior.
+- Do not call `kill` when the user asks to interrupt or pause resumably; kill removes the run from live history/status.