pi-jar 0.1.4 → 0.1.5

package/README.md

@@ -18,14 +18,14 @@ The showcase is captured from a real pi-jar terminal session: the torch-style `
 | **Composer** | Rounded input that grows with your draft (up to ~60% of the terminal), click-to-place cursor in fullscreen, dim **next-prompt suggestions** you accept with <kbd>Tab</kbd>, and **Ember** — a tiny flame mascot that blinks, cheers, focuses, dozes and reacts. |
 | **Plan mode** | Read-only exploration; the agent must write a structured plan file and submit it. You review it in a split view (headings on the left, section on the right) and approve, compact-and-approve, refine or stop. |
 | **Goal mode** | Set an outcome; the agent must break it into tracked tasks and keeps working until they are done, then an **auditor** pass verifies the goal before it can be marked complete. |
-| **Roles** | Named model roles (`default`, `smol`, `slow`, `plan`, `implement`, `advisor`, `task`, `commit`, plus your own) with `@alias` chains, `:effort` suffixes and project overrides; switched automatically as you move between plan, execution, goal rounds and audits, and never over a model you picked yourself. |
+| **Roles** | Named model roles (`default`, `smol`, `slow`, `plan`, `implement`, `advisor`, `moderator`, `scout`, `worker`, `reviewer`, `task`, `commit`, plus your own) with aliases, effort, per-role fallback models and project overrides. |
 | **Advisor** | A second-opinion model: the agent calls `jar_advisor` for risky decisions or when stuck, `/advisor [focus]` asks on demand, and automatic gates consult it when the agent repeats the same tool call or keeps failing. |
 | **Usage & context** | `/usage` shows session cost and tokens per model (advisor and commit calls included) and plan-limit bars with reset times; `/context` draws a grid of what fills the context window, with a per-file, per-skill and per-tool breakdown. |
 | **Commit** | `/jar commit [note]` drafts a message for the staged changes with the `commit` role, lets you edit it, then commits (never pushes). |
 | **Tasks & questions** | A Claude/omp-style `jar_todo` checklist with subtasks and per-task progress that the agent maintains itself, and `jar_ask` structured questions with options, multi-select and free-form answers. |
 | **Change review** | Every file the agent or its editing subagents change is remembered as it was; `/diff` (<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>D</kbd>) shows changed files (each counted once) next to a colored diff, with accept or revert per file or all at once. |
 | **Background shells** | `jar_shell` runs dev servers, watchers and long tests in the background; the agent is woken when a watch pattern matches or the process exits, so it never polls. Running shells get a footer row; click it (or <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>A</kbd>) to tail or kill them. |
-| **Subagents** | `jar_delegate` fans out up to four read-only (or opt-in editing) subagents in parallel on your model roles. Each gets a live footer row; click it to open its checklist and an omp-style collapsible transcript, steer it with a message, or stop it. The parent gets a detailed report (tools, files, tasks, failures) from each. |
+| **Subagents** | The main agent becomes a moderator over a configurable retained pool (2, 4, 6, 8 or 16; default 4). `jar_delegate` spawns `scout`, `fork` or sandboxed `worktree` agents; `jar_subagent` peeks, steers, asks BTW questions, pauses, resumes and stops them. Workers can exchange bounded structured Q/A through `jar_discuss`; worktree changes stay isolated until stop, then safely enter `/diff`. |
 | **Sessions & history** | Recent sessions (with their goal and plan) on the welcome card, one click from resuming; <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>H</kbd> searches earlier prompts; pasted images show as chips under the composer. |
 | **Footer & themes** | Responsive footer (model, effort, session, cwd, context, RAM, cost, quota, goal, roles, branch, live subagents and shells) with unicode, [Nerd Font](https://www.nerdfonts.com) or ascii icons, and seven dark themes. |
 
@@ -175,10 +175,15 @@ Roles map a purpose to a model. They live in `~/.pi/agent/pi-jar-roles.json` (Pi
     "plan": "@slow",
     "advisor": "@slow:xhigh",
     "smol": "anthropic/claude-haiku-4-5-20251001",
-    "review": "openai/gpt-5:medium"
+    "scout": "@smol:minimal",
+    "worker": "anthropic/claude-sonnet-5:medium",
+    "reviewer": "@default:medium"
   },
-  "cycleOrder": ["smol", "default", "slow"],
-  "tags": { "review": { "name": "Reviewer" } }
+  "fallbacks": {
+    "scout": ["openai/gpt-5-mini:low"],
+    "worker": ["@default"]
+  },
+  "cycleOrder": ["smol", "default", "slow"]
 }
 ```
 
@@ -190,13 +195,17 @@ Roles map a purpose to a model. They live in `~/.pi/agent/pi-jar-roles.json` (Pi
   | `plan` | plan mode (restored when you leave it) |
   | `implement` | executing an approved plan and goal implement rounds (falls back to the current model) |
   | `advisor` | `jar_advisor`, `/advisor`, stuck-work gates and the goal audit |
-  | `task` | `jar_delegate` subagents |
+  | `moderator` | optional model assignment for the coordinating main agent |
+  | `scout` | default for fresh read-only delegated discovery; ideal for a cheap model |
+  | `worker` | default for sandboxed worktree implementation |
+  | `reviewer` | default for context-forked read-only review |
+  | `task` | legacy/generic explicit subagent role |
   | `commit` | `/jar commit` messages |
   | `smol` / `slow` | cycling with <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>M</kbd> |
 
   Any other valid name (`a-z`, `0-9`, `-`) is a custom role.
 - **Switching is automatic and scoped.** Entering plan mode applies `plan`; approving applies your chosen role or `implement` for the run; goal rounds alternate `implement` and `advisor`. Each temporary switch restores the previous model afterwards — unless you picked a model or effort yourself in the meantime, which always wins.
-- `/roles` opens a split manager: role list on the left; resolved model, alias chain, effort, scope and usage on the right. Keys: `m` model, `a` alias, `t` effort, `s` move between global/project scope, <kbd>Enter</kbd> activate, `c` clear, `n` new role, `d` delete custom role.
+- `/roles` opens a split manager: role list on the left; resolved model, alias chain, effort, **fallback model**, scope and usage on the right. Keys: `m` primary model, `f` fallback model, `a` alias, `t` effort, `s` move between global/project scope, <kbd>Enter</kbd> activate, `c` clear, `n` new role, `d` delete custom role. The CLI still supports an ordered chain with `/roles fallback ROLE MODEL...`.
 - Older v1 files are read and upgraded in memory; they are rewritten as v2 only when you change a role.
 
 ## Advisor
@@ -208,9 +217,9 @@ The advisor is a second model (the `advisor` role; the current model if unassign
 - **Gates** — when the agent makes the same tool call three times within its last eight calls, the call is blocked and the advisor's review is returned instead; after three failing tool results in a row, the advice is steered into the running turn. At most two automatic consultations per prompt.
 - Settings → Pi toggles the advisor and the gates. Advisor calls are counted in `/usage`. The footer and welcome show it as a working teammate while it thinks.
 
-### Advisor fallback models
+### Role fallback models
 
-Configure an ordered fallback chain (the primary advisor remains configured with `/roles set advisor`):
+Every role can have an ordered fallback chain. The primary remains configured with `/roles set ROLE`:
 
 ```text
 /roles fallback advisor openai/gpt-5:high @smol
@@ -224,7 +233,7 @@ Add `--project` when saving or clearing to override the global chain for this pr
 "fallbacks": { "advisor": ["openai/gpt-5:high", "@smol"] }
 ```
 
-One-shot advisor calls (`jar_advisor`, `/advisor`, and stuck-work gates) try the primary first, then up to eight configured fallbacks on missing models, authentication/provider errors (including rate limits), or empty answers. Cancellation never starts another attempt. Aliases and per-model thinking levels are supported; duplicate model/effort pairs are skipped. Answers identify the successful model, returned attempts are counted in `/usage`, and exhaustion reports every failure. An empty project list disables inherited global fallbacks. No fallback is used unless explicitly configured; context is sent only to the models you choose. The same configuration works for other one-shot roles such as `commit`, but not interactive role activation or goal audit model switches.
+Role activation and delegated model selection try the primary first and then configured fallbacks in order; aliases and per-model effort are supported and duplicate model/effort pairs are skipped. Side-model workflows such as advisor and commit keep their own retry/error reporting while using the same fallback configuration. An empty project fallback list disables inherited global fallbacks. This makes roles such as `scout` practical to pin to a cheap model with a more capable fallback instead of silently escalating every task.
 
 This is a pi-jar enhancement: [pi-advisor](https://github.com/philipbrembeck/pi-advisor/) currently resolves one configured advisor model rather than a fallback chain.
 
@@ -237,17 +246,21 @@ This is a pi-jar enhancement: [pi-advisor](https://github.com/philipbrembeck/pi-
 
 ## Tasks, questions and history
 
-- **`jar_todo`** — a Claude/omp-style task list the agent keeps for any multi-step request. Prefer incremental `append` (new tasks only), `replace` (update one stable `id`), and `remove` (delete one task and its subtasks); IDs are returned for every task. Omitted replacement fields and subtasks stay intact. Legacy `write` (or `todos` without an action) still replaces the entire list, removing omitted tasks. Invalid updates leave the list unchanged. Each task is `pending`, `in_progress` (exactly one at a time) or `completed`, with an `activeForm` ("Running tests") that replaces the working spinner text while it runs. Tasks can have one level of **subtasks**: a parent's status follows its subtasks, its row shows `(done/total)`, and progress counts every subtask (and every task without subtasks). The live checklist above the composer shows `✔` struck-through done tasks, a bold `◼` current task and `☐` pending ones, with subtasks indented; a finished list stays until your next prompt. `/jar tasks` is your view/editor: `a` add, <kbd>Space</kbd>/<kbd>Enter</kbd> check, `e` edit, `d` delete, `f` filter.
+- **`jar_todo`** — a Claude/omp-style task list the agent keeps for multi-step work. A new request starts with `write`: the complete fresh plan, replacing old completed work. `update` changes one stable `id` without disturbing omitted fields/subtasks, and `remove` deletes one task tree. `append` is reserved mainly for new requirements introduced while an existing checklist is already active, such as user steering; if the previous list is fully completed, the agent writes a new list instead of extending the fossil record. IDs are returned for every task. Each task is `pending`, `in_progress` (exactly one leaf at a time) or `completed`, with optional `activeForm`. `start` and `done` deliberately return only the task they changed, while the internal details still carry the checklist state needed by the UI and parent/subagent mirroring. Tasks can have one level of **subtasks**; parent status and progress roll up automatically. The live checklist above the composer shows `✔`, `◼` and `☐`; `/jar tasks` remains the human editor.
   ```json
-  { "action": "append", "todos": [{ "content": "Run tests", "status": "pending", "activeForm": "Running tests" }] }
-  { "action": "replace", "id": "<returned-id>", "status": "in_progress" }
-  { "action": "remove", "id": "<returned-id>" }
+  { "action": "write", "todos": [{ "content": "Implement feature", "status": "in_progress" }, { "content": "Run tests", "status": "pending" }] }
+  { "action": "update", "id": "<returned-id>", "status": "completed" }
+  { "action": "append", "todos": [{ "content": "Handle newly requested edge case", "status": "pending" }] }
   ```
-  Use `parent` with `append` to add subtasks; `start`, `done`, `open`, `edit`, and `list` remain available (`add`/`delete` also remain supported).
+  Use `parent` with `append` to add a genuinely new subtask to active work; `start`, `done`, `open`, `edit`, `list`, `add` and `delete` remain available.
 - **`jar_ask`** — structured questions: numbered options with descriptions, single or multi-select, *Type your own answer* (multi-line, paste-friendly) and *Chat about this* to discuss before choosing.
 - **`/diff`** — review what the agent (and its editing subagents) changed since the first edit to each file: files with `+/−` counts on the left, a numbered, colored diff on the right. `a` accept (keep, stop tracking), `r` then `y` revert (restore the original, or remove a file it created), `A`/`R` for all. The footer shows `± N files · /diff` while anything is unreviewed; each file counts once no matter who edited it. Only `edit`/`write` changes inside the project are tracked; shell-made changes are not.
 - **`jar_shell`** — `start` (with optional `name`, `watch` regex and `notify`), `list`, `output`, `kill`. Output is ANSI-stripped and bounded (2000 lines). When a watch matches or the process ends, a visible message wakes the agent (queued if it is busy). Each running shell gets a footer row; the activity view (`/jar shells`, a click on the row) tails it live (`x` kill, `f` follow). All shells stop when the session ends.
-- **`jar_delegate`** — up to four subagents run in parallel as separate Pi processes (RPC mode) with a fresh context, on a role (default `task`, then `default`, then the current model). They are read-only (`read`, `grep`, `find`, `ls`, plus `jar_todo`) unless `write: true`; subagents cannot delegate further; aborting the turn stops them. Each has a live footer row. When they finish, the parent gets a detailed report per subagent: outcome, duration, tool calls by name, files read and edited, its task checklist, failed calls, then its own Summary / Details / Verification / Open issues.
+- **`jar_delegate`** — spawns **retained session-scoped** subagents up to **Max subagents** in `/jar settings` (2, 4, 6, 8 or 16; default 4). Idle/paused children and live legacy workers count toward the shared limit, not the parent; over-cap batches are rejected before launch. Lowering the limit does not terminate existing children, but blocks new launches until there is room. The parent is given moderator context and should coordinate rather than duplicate their work. `mode: "scout"` is fresh/read-only and defaults to the `scout` role; `fork` is a true Pi session fork, read-only, and defaults to `reviewer`; `worktree` forks context and defaults to `worker`, editing inside a path-guarded disposable Git worktree. A settled retained agent becomes `idle`, keeping its process, model context and workspace for reuse. The old `write: true` direct shared-workspace mode remains one-shot for compatibility.
+- **`jar_subagent`** — moderator control plane: `peek` returns high-level task/checklist progress, current activity, changed files, remaining work, workspace and last report; `steer` redirects a running worker; `ask` injects a terse BTW question and waits for its answer; `pause` aborts the current operation but keeps context/workspace; `resume` wakes that same agent with an optional instruction; `stop` retires it and returns a structured handoff with progress, work directory, changed/applied files and what remains.
+- **Worktree finalization** — worktree edits do **not** touch the parent merely because a worker becomes idle. They remain private across pause/resume cycles. On `jar_subagent stop`, pi-jar verifies parent drift and reviewability, applies safe changes, and adds them to `/diff`; conflicts remain isolated and the workspace path is reported. Resolve parent drift and retry `stop` to reconcile; failed workspaces are retained rather than trimmed out of report history. Process closure is awaited before finalization. All replacements/rollback backups are prepared before parent mutation; failed multi-file application rolls back rather than silently leaving a partial result.
+- **`jar_democracy`** — **exceptional only**, for a persistent **super-complex** issue with several viable options and evidence of at least two distinct failed approaches. The moderator opens 2–8 evidence-backed options, resumes explicitly relevant idle/paused **fresh-context read-only scouts** or spawns fresh scouts within the same pool limit, and collects one private ballot per voter before publishing the tally. A **strict majority of the invited electorate** wins; ties, plurality without majority, and missing/invalid ballots require the user to choose among leading options, with evidence/tradeoffs rather than invented probabilities. TUI uses the structured question picker; RPC returns `needs-user` for the moderator to resolve with `jar_ask`. Voting returns a recommendation and **never implements it** or bypasses safety/approval. Prefer new scouts if past discussions could bias reused agents. Do not use democracy for ordinary complexity or routine decisions.
+- **`jar_discuss`** — a bounded shared discussion paper for virtual agent-to-agent discussion. Questions and answers have stable IDs plus author/target metadata; entries are capped at 1600 characters, the newest 64 are retained, and serialized UTF-8 is capped at 64 KiB (older entries are evicted until it fits). Agents use it for narrow Q/A, not as another transcript.
 - **Activity view** — one split view (<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>A</kbd>, `/jar activity`, or a click on a footer row) for subagents, background shells and other extensions' teammates: list on the left, live details on the right (auto-follows; scroll up to pause, `f` to follow again). For a subagent the details show its task, its own checklist with subtasks, and a transcript like omp's: each tool call and message is one collapsed line that expands on demand (`Tab` into it, `↑↓`, `Enter`, or click) to show arguments and output, while streaming text shows live. `s` opens a steering input: type a message and press `Enter` to redirect the running subagent. `x` stops just that one. Finished runs stay listed for review.
 - **`/jar history`** — separate, read-only timeline of the active branch (paging, search, expandable details). Pi's native transcript is untouched.
 - Pi's built-in read/shell/edit/write tool cards render compactly; the full output or diff stays one click or <kbd>Ctrl</kbd>+<kbd>O</kbd> away.
@@ -258,7 +271,7 @@ This is a pi-jar enhancement: [pi-advisor](https://github.com/philipbrembeck/pi-
 
 - **Appearance** — accent, motion, rounded composer, Ember mascot, next-prompt suggestions, pi-jar UI, icons (`unicode` default, `nerd` for a [Nerd Font](https://www.nerdfonts.com) terminal like omp's nerd preset, `ascii` for plain labels).
 - **Footer** — field visibility. In fullscreen mode the session name (or `sessions` for an unnamed session) opens the session picker and each subagent/shell row opens the activity view. SoL-Pi's savings status is not repeated in the footer (it already notifies).
-- **Pi** — mouse clicks (Pi fullscreen mode), copy on select, goal auto rounds, advisor, advisor gates.
+- **Pi** — mouse clicks (Pi fullscreen mode), copy on select, goal auto rounds, **Max subagents** (explicit choice then Save; default 4), advisor, advisor gates.
 
 pi-jar preferences are saved in `pi-jar-settings.json` in Pi's agent directory; the Pi tab writes Pi's own settings.
 
@@ -287,7 +300,10 @@ pi-jar/
 │   ├── split-view.ts     shared two-pane frame
 │   ├── changes.ts        change tracker and line diff; diff-view.ts is /diff
 │   ├── shells.ts         background shells and jar_shell
-│   ├── delegate.ts       jar_delegate subagents and their live registry
+│   ├── delegate.ts       retained subagents, moderator controls and RPC lifecycle
+│   ├── delegate-worktree.ts isolated Git worktrees, path guard and safe reconciliation
+│   ├── discussion.ts     bounded structured cross-agent Q/A paper
+│   ├── democracy.ts      exceptional scout ballots, strict majority and user tie-break
 │   ├── activity-view.ts  subagent/shell details view
 │   ├── icons.ts          unicode / nerd / ascii glyph sets
 │   ├── attachments.ts    image chips; prompt-search.ts is prompt history

package/docs/WORKFLOWS.md

@@ -78,8 +78,9 @@ Resolution for a role name:
 
 1. Merge global (`<agent dir>/pi-jar-roles.json`) and project (`<cwd>/.pi/pi-jar-roles.json`) roles; project wins per role.
 2. If the spec is `@other[:effort]`, remember the effort (first one wins) and follow `other`; stop after five hops or on a cycle.
-3. A `provider/model[:effort]` spec resolves through Pi's model registry; activation fails with a notice if the model is unknown or unauthenticated.
-4. An unassigned role "follows the current model" (activating it only labels the footer).
+3. A `provider/model[:effort]` spec resolves through Pi's model registry.
+4. For an assigned role, activation tries the primary then that role's configured fallback specs in order. Delegated agents also choose the first currently available candidate. An explicit empty project fallback list disables the inherited global list.
+5. An unassigned role "follows the current model" (activating it only labels the footer).
 
 `activateTemporary(role)` returns a restore function that puts back the previous model, effort and active role — used by plan mode (`plan`), approved-plan execution (`implement`), goal rounds (`implement` / `advisor`).
 
@@ -108,13 +109,21 @@ Manual choices win: a model or effort you select yourself (model picker, cycling
 - If a completed turn did not suggest, a single hidden reminder asks for one (never while plan or goal automation owns the next step, and never after an interrupt).
 - The suggestion is sanitized to one line (≤ 160 characters) and kept in memory only. It is cleared by your next prompt, a new run, typing, or branch navigation.
 
+## Task tracking discipline
+
+- `jar_todo write` is the normal way to establish the checklist for a new multi-step request. It represents the complete current plan, so completed work from an earlier request is naturally dropped.
+- `update` changes one stable task id while preserving omitted fields and subtasks. `remove` deletes one task tree.
+- `append` is for genuinely new work introduced while an existing checklist is still active, especially user steering or an added requirement. When the current checklist is already fully completed, start a fresh list with `write` instead of appending.
+- `start` and `done` deliberately return/render only the single task they changed. Their structured result still carries the bounded checklist (the full list inside subagents) so parent/subagent progress mirroring remains accurate.
+- Exactly one leaf task may be `in_progress`; starting another leaf parks the previous one. Parent status is derived from its subtasks.
+
 ## Change review
 
 - A `tool_call` hook records a file's content right before the agent's **first** `edit` or `write` to it (project files only, up to 200 files, 1 MB each, text only). Later edits keep that baseline, so the review always shows everything since the agent started on the file.
 - `/diff` (or <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>D</kbd>) compares the baseline with the file on disk using a line diff with 3 lines of context. Files that are back to their baseline drop out.
 - **Accept** forgets the baseline. **Revert** writes the baseline back (or removes a file the agent created) after a second key press to confirm. Errors are reported and the file stays listed.
 - Baselines live in memory for the session; changes made through `bash` or by you are not tracked.
-- **Subagent edits** join the same review. An editing `jar_delegate` batch gets a private temporary directory (`PI_JAR_BASELINE_DIR`); pi-jar inside each subagent writes a file's baseline there right before the subagent's first edit to it. After each successful subagent `edit`/`write` the parent adopts that baseline, unless it already tracks the file (the older baseline wins), so every file is counted once in the footer and `/diff`. The directory is removed when the batch ends. A subagent without pi-jar loaded cannot record baselines, so its edits are listed in its report but not in `/diff`.
+- **Subagent edits** join the same review in two ways. Retained `worktree` writers remain isolated while working, idle or paused. Only `jar_subagent stop` finalizes them: pi-jar verifies that each parent target still equals the private baseline snapshot, copies reviewable safe results back, then captures/marks those parent files in the normal `ChangeTracker`. The deprecated one-shot `write: true` shared-workspace mode keeps its older `PI_JAR_BASELINE_DIR` bridge for compatibility.
 
 ## Background shells
 
@@ -130,13 +139,26 @@ watch matches  or  process exits  →  pi-jar.shell message  →  agent wakes (o
 
 ## Subagents
 
-- `jar_delegate` takes 1–4 tasks. Each runs `pi --mode rpc --no-session [parent's -e/--extension/-ne flags] --model <role model> [--thinking <effort>] [--tools read,grep,find,ls,jar_todo]` in the project directory, with `PI_JAR_CHILD=1`, and receives the task as an RPC `prompt` (with instructions to track work in `jar_todo` and to report in Summary / Details / Verification / Open issues sections). Once the child emits `agent_settled`, stdin is closed and Pi exits in order. Dialogs a child opens are answered as cancelled so it never blocks.
-- The model comes from the task's role (default `task`), falling back to `default` and then the current model.
-- Progress (current tool, streaming text, tools used, turns, cost) streams into the tool card; each running subagent is published as a teammate for the welcome TEAM row and footer, and cleared when it ends.
-- The activity view keeps a structured transcript per subagent: every tool call (arguments, streamed and final output, duration, success) and each assistant message, plus steering messages; the newest 200 entries, each clipped to 4000 characters, and the text still streaming. Entries are collapsed to one line and rendered only when expanded (`Tab` into the transcript, `↑↓`, `Enter`, or a click on the entry). The subagent's own `jar_todo` checklist (with subtasks) is mirrored from its tool results. It all lives only in memory with the 8 most recent finished runs; the tool result saved in the session carries the reports, not the transcript.
-- **Steering:** `s` in the activity view (or a click on the input row) opens an input; `Enter` sends the text as an RPC `steer` message, delivered after the subagent's current tool calls. Steering works while the subagent is running.
-- **Report back:** for each subagent the parent reads its outcome and duration, turns, tool calls by name, files read and edited, its checklist with per-task progress, failed tool calls, and then the subagent's own report.
-- Subagents time out after 20 minutes and stop when the turn is aborted; `x` in the activity view stops one without touching the rest of its batch (its report reads `failed: stopped`). In goal mode, `write: true` needs an open task.
+- The main agent is the **moderator** while a retained fleet exists. A hidden bounded context lists the fleet and tells the parent to decompose, route, peek, steer, resolve disagreements and synthesize instead of duplicating a worker's task. The optional `moderator` role gives this purpose a configurable model without forcing a model switch.
+- `jar_delegate` shares a session-wide **Max subagents** setting in `/jar settings`: exactly 2, 4, 6, 8 or 16, default 4. All retained live children (including idle/paused and live legacy one-shots) count; the moderator does not. Concurrent/reentrant batches reserve capacity atomically and reject over-cap requests before any launch. Lowering the limit preserves the fleet and prevents further spawning until room is available. `scout` runs `pi --mode rpc --no-session`, is read-only and defaults to the `scout` role. `fork` uses `--fork <parent-session>`, is read-only and defaults to `reviewer`. `worktree` uses the same real context fork, defaults to `worker`, and runs in a detached disposable Git worktree. Explicit `task.role` overrides those defaults; each role uses its primary/fallback candidates before falling back to the parent's current model.
+- Retained children do not exit on `agent_settled`. They become `idle`, keeping the same RPC process and model context. `jar_subagent pause` sends `clear_queue` + `abort` and leaves the agent `paused`; `resume` sends a new prompt to that same child. `steer` redirects a working child. `ask` pauses an active task, crosses a settled boundary, then starts a compact BTW-only prompt, so the old task report cannot be mistaken for the answer. It preserves the prior paused state and assigned scope for later resume.
+- `jar_subagent peek` is the moderator's cheap status surface: task, state, model/role/mode, checklist progress, current activity, changed files, remaining checklist leaves, workspace and last report. `stop` is destructive/final: abort an active operation if necessary, close the child, return a handoff (workspace, changed/applied files, remaining work, last report), and finalize safe worktree changes.
+- Worktree setup snapshots the exact starting workspace: `HEAD` plus tracked dirty changes and non-ignored untracked files are committed only inside the detached worktree. The worktree persists across idle/pause/resume. On stop, the parent target must still byte/mode-match the snapshot and the change must be trackable by `/diff`; otherwise nothing is overwritten and the workspace/error is reported. Conflicted workspaces survive report-history trimming; after resolving parent drift, retry `stop`. Finalization waits for RPC stdio closure. Snapshot blobs preserve filesystem bytes without executing clean/smudge filters or hooks. The path guard handles Pi path normalization, rejects lexical/symlink/dangling-link escapes and Git control metadata, checks read-tool filename fallbacks (NFD, curly apostrophes, AM/PM spaces), and rechecks both source and destination ancestors during reconciliation. All replacements/rollback backups are prepared before parent mutation; failed multi-file application restores earlier files. Exceptional rollback failures explicitly report actual applied paths for recovery. Worktree children receive only `read,edit,write,grep,find,ls,jar_todo,jar_discuss`; shell tools are absent. This is filesystem-write isolation, not a network/process sandbox.
+- `jar_discuss` gives moderator and children a session-scoped structured paper. `ask` appends a question with stable id/from/to fields, `answer` references the question id, and `list` reads recent entries. Text is capped at 1600 characters per entry, at most 64 entries are retained, and the serialized UTF-8 JSON paper is strictly bounded to 64 KiB with oldest-entry eviction and atomic rewrites. It is intentionally for terse inter-agent Q/A rather than another transcript.
+- Fork/worktree children inherit the parent model conversation but reset pi-jar goal/plan/todo automation. All child modes inherit explicit extension flags, set `PI_JAR_CHILD=1` to prevent recursive delegation, and share the discussion-paper path/name through environment variables.
+- Progress (current tool, streaming text, tools used, turns, cost) stays in the activity view. Retained `idle` and `paused` agents remain visible in the footer/activity fleet; the newest eight ordinary retired reports remain for review, while unresolved private workspaces remain recoverable until explicit finalization/session cleanup. `s` in the activity view still steers a working subagent and `x` stops the selected agent through the same registry.
+- The deprecated `write: true` mode remains a one-shot shared-workspace compatibility path. New delegated implementation should use `mode: "worktree"`.
+
+### Exceptional agentic democracy
+
+`jar_democracy` is **not** a default decomposition or decision tool. The moderator must supply `complexity: "super-complex"`, a concrete complexity justification, the persistent issue, at least two distinct failed approaches with evidence, and 2–8 uniquely identified options with tradeoffs. These gates are runtime-validated in addition to prompt guidance; the moderator is responsible for truthful evidence.
+
+- Nominate relevant idle/paused **scouts** with `agents`, and set the total electorate with `voters` (default 4, or 2 at a cap of 2; always bounded by the configured cap). Forks, writable workers, busy agents and duplicate nominations are rejected. Reuse preserves context; prefer fresh scouts if discussion history could bias a ballot.
+- Unfilled seats spawn fresh read-only scouts through the normal delegate controller. The same session-wide capacity applies; the moderator must explicitly stop unneeded agents if there is no room. Voting never silently kills existing workers. Voters are retained for follow-up.
+- Each voter investigates independently and returns one nonce-bound option ID with a short evidence-based rationale. Voters are instructed not to use shared discussion. Results are collected before any tally is exposed; malformed/stale/missing/error ballots are recorded, never inferred.
+- A **strict majority** means more than half of **all invited voters**, with at least two valid ballots. The largest plurality is not a majority. Missing ballots do not reduce this denominator or allow a single response to decide.
+- Ties, plurality without majority, and insufficient ballots return `needs-user`. The leading options are presented to the user with their evidence/tradeoffs in the TUI question picker, including custom/chat/cancel paths. In RPC, the moderator must use `jar_ask` before proceeding. Recommend the most plausible option from actual evidence; do not fabricate numerical probabilities or silently break a tie.
+- A majority is a recommendation, not permission to execute dangerous work. The tool never implements the selected option, and ordinary safety/user-approval requirements remain in force. Only one round may run at a time; abort invalidates incomplete results.
 
 ## Sessions and prompt history
 

package/extensions/index.ts

@@ -5,6 +5,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { Key, truncateToWidth, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { ACCENT_NAMES, loadedAccents, selectAccent } from "../src/accent.ts";
 import { registerAskTool } from "../src/ask-tool.ts";
+import { registerDemocracy } from "../src/democracy.ts";
+import type { DelegateController } from "../src/delegate.ts";
 import { ComposerStyle } from "../src/composer.ts";
 import { installCompactBuiltinTools } from "../src/compact-tools.ts";
 import { WELCOME_INTERVAL_MS } from "../src/animations.ts";
@@ -34,7 +36,9 @@ import { TASK_ENTRY, TodoStore, todoProgress, todoTotals } from "../src/tasks.ts
 import { formatCost, sessionCost } from "../src/usage.ts";
 import { WorkingState } from "../src/working.ts";
 import { ChangeTracker } from "../src/changes.ts";
-import { DelegateRegistry, registerDelegate, type DelegateRun } from "../src/delegate.ts";
+import { CHILD_ENV, DelegateRegistry, registerDelegate, type DelegateRun } from "../src/delegate.ts";
+import { CHILD_WORKTREE_ENV, workspacePathAllowed } from "../src/delegate-worktree.ts";
+import { createDiscussionPaper, DISCUSSION_FILE_ENV, disposeDiscussionPaper, registerDiscussionTool, SUBAGENT_NAME_ENV } from "../src/discussion.ts";
 import { openActivityView, type ActivityTarget } from "../src/activity-view.ts";
 import { ICON_SETS, setIconSet, withIcon } from "../src/icons.ts";
 import { collectPrompts, openPromptSearch } from "../src/prompt-search.ts";
@@ -55,6 +59,40 @@ const LARGE_SESSION_ENTRIES = 800;
 /** Entries Pi writes when a fresh session starts; a branch holding only these has no transcript yet. */
 const SESSION_SETUP_ENTRIES = new Set(["thinking_level_change", "model_change", "session_info"]);
 export default function piJar(pi: ExtensionAPI): void {
+  const delegatedChild = process.env[CHILD_ENV] === "1";
+  const delegatedWorktree = delegatedChild ? process.env[CHILD_WORKTREE_ENV] : undefined;
+  if (delegatedChild) {
+    // Forked transcripts retain custom prompt messages even though their automation stores
+    // and handlers are disabled. Remove only parent automation, not task/user context.
+    const parentAutomation = new Set([
+      "pi-jar.goal-context", "pi-jar.goal-continuation",
+      "pi-jar.plan-context", "pi-jar.plan-reminder", "pi-jar.moderator-context"
+    ]);
+    pi.on("context", (event) => {
+      const messages = event.messages.filter((message) => !parentAutomation.has((message as { customType?: string }).customType ?? ""));
+      if (messages.length !== event.messages.length) return { messages };
+    });
+  }
+  if (delegatedWorktree) {
+    const pathTools = new Set(["read", "edit", "write", "grep", "find", "ls"]);
+    const shellTools = new Set(["bash", "powershell", "jar_shell"]);
+    pi.on("tool_call", (event, ctx) => {
+      if (shellTools.has(event.toolName)) {
+        return { block: true, reason: "Sandboxed worktree subagents cannot run shell tools." };
+      }
+      if (!pathTools.has(event.toolName)) return;
+      const input = event.input && typeof event.input === "object" ? event.input as Record<string, unknown> : {};
+      if (!workspacePathAllowed(delegatedWorktree, ctx.cwd, ".")) {
+        return { block: true, reason: "Sandboxed worktree subagent working directory is outside its workspace." };
+      }
+      for (const key of ["path", "file_path", "cwd"]) {
+        const value = input[key];
+        if (typeof value === "string" && value && !workspacePathAllowed(delegatedWorktree, ctx.cwd, value, event.toolName === "read")) {
+          return { block: true, reason: `Sandboxed worktree subagent cannot access outside its workspace: ${value}` };
+        }
+      }
+    });
+  }
   installCompactBuiltinTools(pi);
   let demo = false;
   let visualSettings = defaultVisualSettings();
@@ -94,6 +132,8 @@ export default function piJar(pi: ExtensionAPI): void {
   let workingIndicatorKey = "";
   let openSettings: (ctx: ExtensionContext) => Promise<void> = async () => {};
   let settingsOpen = false;
+  let discussionFile: string | undefined = process.env[DISCUSSION_FILE_ENV];
+  registerDiscussionTool(pi, () => discussionFile, () => process.env[SUBAGENT_NAME_ENV] ?? "moderator");
 
   // A finished list stays visible (all struck through) until the user's next prompt, like Claude.
   let todosAcknowledged = false;
@@ -163,14 +203,15 @@ export default function piJar(pi: ExtensionAPI): void {
   /** Finished work stays visible briefly so a quick run is not a flicker. */
   const ACTIVITY_LINGER_MS = 5000;
   const subagentState = (run: DelegateRun): ActivityState => run.state === "working" ? "running" : run.state === "queued" ? "queued"
-    : run.state === "done" ? "done" : run.error === "stopped" ? "stopped" : "failed";
+    : run.state === "idle" ? "idle" : run.state === "paused" ? "paused" : run.state === "stopped" ? "stopped"
+      : run.state === "done" ? "done" : "failed";
   const shellActivityState = (job: Omit<ShellJob, "lines">): ActivityState => job.status === "running" ? "running"
     : job.status === "killed" ? "stopped" : job.status === "exited" && job.exitCode === 0 ? "done" : "failed";
   const seconds = (ms: number) => { const s = Math.max(0, Math.round(ms / 1000)); return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`; };
   const footerActivity = (now: number): FooterActivity[] => {
     const rows: FooterActivity[] = [];
     for (const { key, run } of subagents.records()) {
-      if (run.endedAt && now - run.endedAt > ACTIVITY_LINGER_MS) continue;
+      if ((run.state === "done" || run.state === "failed" || run.state === "stopped") && run.endedAt && now - run.endedAt > ACTIVITY_LINGER_MS) continue;
       rows.push({ kind: "subagent", id: key, name: run.name, state: subagentState(run),
         detail: run.error ?? run.activity ?? cleanText(run.task, 120),
         stats: [run.tools ? `${run.tools} tools` : "", run.startedAt ? seconds((run.endedAt ?? now) - run.startedAt) : ""].filter(Boolean).join(" · ") });
@@ -227,17 +268,21 @@ export default function piJar(pi: ExtensionAPI): void {
   registerAdvisor(pi, modelRoles, { enabled: () => visualSettings.advisor, gates: () => visualSettings.advisorGates, usage: sideUsage });
   registerInfoPanels(pi, { side: sideUsage, quotaEnabled: () => quotaCache?.enabled ?? false,
     quota: (ctx) => quotaCache?.get(ctx.model?.provider, welcomeStatuses(), Date.now()) });
-  modelRoles.register((ctx) => openRolesUi(ctx, modelRoles));
-  registerDelegate(pi, modelRoles, subagents, { changes: () => changes, changed: refreshChanges });
+  modelRoles.register((ctx) => openRolesUi(ctx, modelRoles), { activateDefault: () => !delegatedChild });
+  let delegateController: DelegateController | undefined;
+  registerDelegate(pi, modelRoles, subagents, { changes: () => changes, changed: refreshChanges, discussionFile: () => discussionFile,
+    getMaxSubagents: () => visualSettings.maxSubagents, onController: (controller) => { delegateController = controller; } });
+  if (!delegatedChild) registerDemocracy(pi, () => delegateController, () => visualSettings.maxSubagents);
   const planMode = new PlanMode(pi, () => todos, modelRoles, updateTaskWidget);
-  planMode.register();
+  if (!delegatedChild) planMode.register();
   const goalLoop = new GoalLoop(pi, {
     goals: () => goals, todos: () => todos, roles: modelRoles, planActive: () => planMode.isEnabled(),
     maxRounds: () => visualSettings.goalRounds,
+    subagentMode: (agent) => subagents.resolve(agent)?.run.mode,
     changed: (ctx) => { footerTui?.requestRender(); welcomeTui?.requestRender(); updateTaskWidget(ctx); },
     completed: () => composer.flash("complete", 4000)
   });
-  goalLoop.register();
+  if (!delegatedChild) goalLoop.register();
   planMode.setOnEnter((ctx) => goalLoop.pause(ctx, "plan mode is on"));
   const suggestions = new SuggestionState();
   composer.attachSuggestions(suggestions);
@@ -603,13 +648,22 @@ export default function piJar(pi: ExtensionAPI): void {
     changeCount = 0;
     shells?.dispose();
     subagents.clear();
+    if (!delegatedChild) {
+      disposeDiscussionPaper(discussionFile);
+      discussionFile = createDiscussionPaper();
+    }
     shells = new ShellManager(onShellEvent);
     shells.onChange = () => footerTui?.requestRender();
     goals = new GoalStore((entry) => pi.appendEntry(GOAL_ENTRY, entry));
     let branch: readonly unknown[] = [];
     try { branch = sessionBranch(ctx); } catch { /* keep empty */ }
-    restoreTodos(ctx, branch);
-    restoreGoal(ctx, branch);
+    if (delegatedChild) {
+      todos.restore([]);
+      goals.restore([]);
+    } else {
+      restoreTodos(ctx, branch);
+      restoreGoal(ctx, branch);
+    }
     // Quota is enabled per session; no credentials or consent are persisted.
     quotaCache = new QuotaCache(
       (provider: QuotaProvider, signal) => fetchQuota(provider, (id) => ctx.modelRegistry.getProviderAuth(id), signal),
@@ -641,7 +695,7 @@ export default function piJar(pi: ExtensionAPI): void {
     // A fresh session is not empty: Pi records the startup thinking level/model as entries.
     const resumed = branch.some((entry) => !(typeof entry === "object" && entry !== null && "type" in entry
       && typeof entry.type === "string" && SESSION_SETUP_ENTRIES.has(entry.type)));
-    if (!resumed) showWelcome(ctx);
+    if (!delegatedChild && !resumed) showWelcome(ctx);
   });
   // Any real prompt dismisses the welcome. Slash commands bypass `input`, so `agent_start` covers them.
   const dismissWelcome = (ctx: ExtensionContext) => {
@@ -684,13 +738,19 @@ export default function piJar(pi: ExtensionAPI): void {
   pi.on("session_tree", (_event, ctx) => {
     let branch: readonly unknown[] = [];
     try { branch = sessionBranch(ctx); } catch { /* keep empty */ }
-    restoreTodos(ctx, branch);
-    restoreGoal(ctx, branch);
+    if (!delegatedChild) {
+      restoreTodos(ctx, branch);
+      restoreGoal(ctx, branch);
+    }
     updateCost(ctx);
     composer.refreshSession(ctx);
     sampleFooter(ctx);
   });
-  pi.on("session_compact", (_event, ctx) => { restoreTodos(ctx); restoreGoal(ctx); updateCost(ctx); sampleFooter(ctx); });
+  pi.on("session_compact", (_event, ctx) => {
+    if (!delegatedChild) { restoreTodos(ctx); restoreGoal(ctx); }
+    updateCost(ctx);
+    sampleFooter(ctx);
+  });
   pi.on("model_select", (_event, ctx) => sampleFooter(ctx));
   pi.on("thinking_level_select", (_event, _ctx) => footerTui?.requestRender());
   pi.on("session_info_changed", (_event, ctx) => { composer.refreshSession(ctx); sampleFooter(ctx); });
@@ -703,6 +763,7 @@ export default function piJar(pi: ExtensionAPI): void {
     try { if (ctx.hasUI && ctx.mode === "tui") { ctx.ui.setWorkingMessage?.(); ctx.ui.setWorkingIndicator(); ctx.ui.setWidget("pi-jar.todos", undefined); } } catch {}
     quotaCache?.stop();
     quotaCache = undefined;
+    if (!delegatedChild) { disposeDiscussionPaper(discussionFile); discussionFile = undefined; }
     todos = undefined;
     changes = undefined;
     changeCount = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jar",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "A warm, role-aware Pi terminal workspace with animated UI, plan and goal workflows, tasks, change review, model roles, background shells and subagents.",
   "type": "module",
   "license": "MIT",

package/src/activity-view.ts

@@ -46,7 +46,8 @@ function collect(sources: ActivitySources): Item[] {
   if (records.length) items.push({ kind: "header", label: withIcon("subagents", "SUBAGENTS") });
   for (const record of records) {
     const { run } = record;
-    const status: Status = run.state === "working" ? "running" : run.state === "queued" ? "pending" : run.state === "done" ? "success" : run.error === "stopped" ? "stopped" : "error";
+    const status: Status = run.state === "working" ? "running" : run.state === "queued" || run.state === "idle" ? "pending"
+      : run.state === "paused" || run.state === "stopped" ? "stopped" : run.state === "done" ? "success" : "error";
     items.push({ kind: "subagent", id: record.key, status, label: run.name, record });
   }
   const jobs = sources.shells?.summaries() ?? [];
@@ -215,7 +216,7 @@ function subagentHead(run: DelegateRun, status: Status, width: number, fg: Fg):
   ].filter(Boolean);
   const head = [
     fg("accent", [run.name, run.role, run.model].filter(Boolean).join(" · ")),
-    fg(COLOR[status], withIcon(status, status === "stopped" ? "stopped" : run.state)) + fg("dim", " · " + facts.join(" · "))
+    fg(COLOR[status], withIcon(status, run.state === "paused" ? "paused" : status === "stopped" ? "stopped" : run.state)) + fg("dim", " · " + facts.join(" · "))
   ];
   // A turning glyph on the 1 s tick: a long tool call or a slow model still looks alive.
   if (run.activity) head.push(fg("muted", (run.state === "working" ? SPINNER[Math.floor(Date.now() / 1000) % SPINNER.length] + " " : "") + run.activity));
@@ -348,9 +349,14 @@ export async function openActivityView(ctx: ExtensionContext, sources: ActivityS
     };
     const stopSelected = () => {
       const item = selected();
-      if (!item || item.kind === "role" || (item.status !== "running" && item.status !== "pending")) return;
+      if (!item || item.kind === "role") return;
+      const subagentLive = item.kind === "subagent" && !["done", "failed", "stopped"].includes(item.record.run.state);
+      const shellLive = item.kind === "shell" && item.status === "running";
+      if (!subagentLive && !shellLive) return;
       try {
-        if (item.kind === "subagent") sources.subagents.stop(item.id);
+        if (item.kind === "subagent") void sources.subagents.stop(item.id).catch((error: unknown) => {
+ctx.ui.notify("pi-jar: " + (error instanceof Error ? error.message : String(error)), "error");
+});
         else shells?.kill(item.id);
       } catch (error) { ctx.ui.notify("pi-jar: " + (error instanceof Error ? error.message : String(error)), "error"); }
     };
@@ -445,7 +451,8 @@ export async function openActivityView(ctx: ExtensionContext, sources: ActivityS
         // Footer: the two actions, the steering input for subagents, then key hints.
         const actions = optionList(theme, [item?.kind === "shell" ? "Kill the selected shell" : item?.kind === "role" ? "Stop (teammates from other extensions are read-only)" : "Stop the selected subagent",
           "Follow the latest output"], -1, ACTIONS.map((action) => action.key));
-        const stoppable = item?.kind === "subagent" ? item.status === "running" || item.status === "pending" : item?.kind === "shell" && item.status === "running";
+        const stoppable = item?.kind === "subagent" ? !["done", "failed", "stopped"].includes(item.record.run.state)
+          : item?.kind === "shell" && item.status === "running";
         if (!stoppable) actions[0] = fg("dim", stripTerminalSequences(actions[0]!));
         const footer = [...actions];
         if (subagent) {

package/src/ask-tool.ts

@@ -26,13 +26,18 @@ type PickResult = { kind: "answer"; selected: string[] } | { kind: "custom" } |
 
 const fit = (line: string, width: number) => truncateToWidth(line, Math.max(0, width));
 
-async function pickQuestion(ctx: ExtensionContext, question: AskQuestion, index: number, total: number): Promise<PickResult> {
+async function pickQuestion(ctx: ExtensionContext, question: AskQuestion, index: number, total: number, signal?: AbortSignal): Promise<PickResult> {
   const options = (question.options ?? []).map((option) => ({
     label: cleanText(option.label, 120),
     description: option.description ? cleanText(option.description, 240) : undefined
   })).filter((option) => !!option.label);
-  if (!ctx.hasUI || ctx.mode !== "tui") return { kind: "cancel" };
-  return ctx.ui.custom<PickResult>((tui, theme, _keys, done) => {
+  if (!ctx.hasUI || ctx.mode !== "tui" || signal?.aborted) return { kind: "cancel" };
+  let abort: (() => void) | undefined;
+  try { return await ctx.ui.custom<PickResult>((tui, theme, _keys, complete) => {
+    const done = (result: PickResult) => { if (abort) signal?.removeEventListener("abort", abort); complete(result); };
+    abort = () => done({ kind: "cancel" });
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) queueMicrotask(abort);
     const multi = !!question.multi;
     const allowCustom = question.allowCustom !== false;
     const actions = [
@@ -131,13 +136,13 @@ async function pickQuestion(ctx: ExtensionContext, question: AskQuestion, index:
         return lines.map((line) => visibleWidth(line) <= width ? line : fit(line, width));
       }
     };
-  });
+  }); } finally { if (abort) signal?.removeEventListener("abort", abort); }
 }
 
-async function askOne(ctx: ExtensionContext, question: AskQuestion, index: number, total: number): Promise<AskAnswer> {
+export async function askOne(ctx: ExtensionContext, question: AskQuestion, index = 0, total = 1, signal?: AbortSignal): Promise<AskAnswer> {
   const id = cleanText(question.id ?? "q" + String(index + 1), 64) || "q" + String(index + 1);
-  const picked = await pickQuestion(ctx, question, index, total);
-  if (!picked || picked.kind === "cancel") return { id, cancelled: true };
+  const picked = await pickQuestion(ctx, question, index, total, signal);
+  if (signal?.aborted || !picked || picked.kind === "cancel") return { id, cancelled: true };
   if (picked.kind === "custom") {
     const text = await ctx.ui.editor("✎ Your answer · " + cleanText(question.header ?? "Question", 48), "");
     return text?.trim() ? { id, answer: text.trim() } : { id, cancelled: true };