@ferris1225/pi-subagents 4.1.13 → 4.1.15

package/README.md

@@ -19,22 +19,25 @@ model dies, how results come back — stays with you. pi-subagents owns that
 burden:
 
 - **The main model actually delegates.** A lean delegation directive is injected
-  into its system prompt: substantive work goes to children so the main context
-  stays lean for orchestration, trivial work stays inline, and nothing is
-  re-explained twice. No custom prompts needed.
+  into its system prompt: child contexts are cheap and yours is scarce —
+  non-trivial implementation defaults to `worker`, trivial work stays inline,
+  and dispatching never blocks or ends the main turn, so it can fire several
+  dispatches and keep working while they run.
 - **Fan-out is the model's call, not a cap.** One parallel dispatch carries as
   many tasks as the work genuinely decomposes into. The runtime paces execution
   at four concurrent child processes; extra tasks simply queue, so wide batches
   never fail and never flood your context (results deliver compact, with the
   full text on disk).
-- **Quality gates are built in.** Successful worker/cleaner runs continue
-  through one independent reviewer gate, and `REVIEW_FAIL` findings return to
-  the main agent with concrete fix instructions — it resolves them itself,
-  without stopping to ask you. No black-box auto-fix chain edits code behind
-  your back.
+- **Quality gates are built in and converge by themselves.** Successful
+  worker/cleaner runs continue through one independent reviewer gate. A failing
+  gate is fixed by the reviewer itself — the same retained session gets write
+  access, applies its own fix instructions, and a fresh gate re-scans the
+  complete diff — looping until the gate passes (bounded rounds; a still-failing
+  gate returns to the main agent with every finding and fix instruction). No
+  guessing what satisfies the reviewer.
 - **Documentation stops drifting.** Writers sync the docs they directly affect;
-  after a passing gate, the documenter runs only when the reviewer actually
-  reports drift.
+  documentation drift is an ordinary gate finding, and dispatching the
+  documenter for real remaining drift stays the main agent's decision.
 - **Parallel edits are safe.** Parallel workers default to isolated Git
   worktrees and integrate back without touching your index; shared-checkout
   writers serialize through one repository lane.
@@ -50,11 +53,11 @@ burden:
 You
  └─ pi main agent
      ├─ explorer ─── retrieval index only (never an automatic gate)
-     ├─ worker ───── implements ─┬─▶ reviewer ─┬─ docs CLEAN → deliver
-     ├─ cleaner ──── cleans up ──┘             └─ NEEDED/missing → documenter
-     ├─ documenter ─ explicit docs/comments task → deliver
-     └─ reviewer ─── advisory report (no VERDICT), or managed gate
-          └─ REVIEW_FAIL → findings + fix instructions → main agent fixes
+     ├─ worker ───── implements ─┬─▶ reviewer ─ PASS → deliver
+     ├─ cleaner ──── cleans up ──┘            └─ FAIL → reviewer fixes itself
+     ├─ documenter ─ explicit docs/comments task → deliver                │
+     └─ reviewer ─── advisory report (no VERDICT), or managed gate ◀──────┘
+          └─ direct REVIEW_FAIL → findings + fix instructions → main agent fixes
 
 Worker and cleaner update existing docs/comments they directly affect. The stable
 parent returns one final result when its complete managed workflow settles.
@@ -72,9 +75,10 @@ Requires **pi >= 0.83.0** and **Node.js >= 22.19.0**.
 pi install npm:@ferris1225/pi-subagents
 ```
 
-Open pi and run `/subagents-setup` to pick agents and models. Fresh installs
-enable `explorer`, `worker`, `cleaner`, and `reviewer`; `documenter` is opt-in.
-Then just ask:
+Open pi and run `/subagents-setup` to pick agents, models, and thinking
+strengths. Fresh installs enable all five built-in agents on the current main
+model, and until a config file exists each session start points you at
+`/subagents-setup`. Then just ask:
 
 ```text
 Map how authentication works, fix the refresh race, run the tests, and review the diff.
@@ -88,10 +92,10 @@ directly for exact control.
 | Agent | Access | Best for |
 | --- | --- | --- |
 | `explorer` | Read-only | Broad search, unfamiliar-area mapping, symbol/dependency tracing. Fast model, returns a retrieval index — never proof. |
-| `worker` | Full | A self-contained implementation, fix, refactor, or test task carried through verification. |
+| `worker` | Full | The default route for any non-trivial, self-contained implementation, fix, refactor, or test task carried through verification. |
 | `cleaner` | Full | Explicitly authorized cleanup, removal, simplification, deduplication. Every safe proven cut applies without item-by-item approval. |
-| `documenter` | Docs/comments | Conditional final diff sync, or an explicit standalone docs/comments task. May make zero edits; never changes runtime behavior. |
-| `reviewer` | Read-only | Audits, code-health checks, plans, PR/issue validation, and independent gates. |
+| `documenter` | Docs/comments | Standalone docs/comments work, including syncing real drift a change left behind. May make zero edits; never changes runtime behavior. |
+| `reviewer` | Read-only (review) / full (fix stage) | Audits, code-health checks, plans, PR/issue validation, and independent gates; a failing managed gate continues into the reviewer's own write-enabled fix stage. |
 
 A good brief carries the goal, exact paths, constraints, and expected output —
 the injected delegation guidance does this automatically when the main agent
@@ -114,7 +118,7 @@ subagent({
 
 The main agent owns the breadth — there is no per-call task cap. The runtime
 runs four child processes at once and queues the rest; a generation that moves
-on to its managed stages (gate review, docs sync) releases its slot, so managed
+on to its managed stages (gate review, fix rounds) releases its slot, so managed
 work never starves new dispatches. One child owns one coherent deliverable and
 its files; dependent work starts only after its prerequisite delivers.
 
@@ -124,17 +128,22 @@ its files; dependent work starts only after its prerequisite delivers.
 subagent({ agent: "reviewer", task: "Gate the current diff for correctness, regressions, and missing tests." });
 ```
 
-A gate ends with `VERDICT: REVIEW_PASS` or `REVIEW_FAIL`, plus
-`DOCUMENTATION: CLEAN`/`NEEDED` when documenter is enabled. Only `REVIEW_PASS`
-continues to documentation: CLEAN delivers immediately; NEEDED or a missing
-marker runs one final docs sync. A `REVIEW_FAIL` delivers the full findings —
-each with a concrete fix instruction — straight back to the main agent, which
-resolves them itself (inline or via a worker it briefs) without waiting for you;
-only a genuinely destructive or scope-changing fix is worth asking about.
-
-Re-verifying your own fixes? Dispatch with `advisory: true`: the report comes
-back to the main window and never starts anything, even if a verdict slips
-through. Generic audits and read-only reviews are advisory by default: no
+A gate ends with exactly one verdict line: `VERDICT: REVIEW_PASS` or
+`REVIEW_FAIL`. Every gate finding carries a concrete fix instruction, and the
+reviewer must surface the complete finding set in one pass — never rationing
+findings across later rounds.
+
+A failing **managed** gate (after a top-level worker/cleaner) converges inside
+the workflow: the same retained reviewer session continues with write access,
+applies its own fix instructions, and a fresh gate re-scans the complete diff.
+The loop repeats until the gate passes — bounded to three fix rounds, after
+which the still-failing gate returns to the main agent with every finding.
+
+A failing gate **you dispatched directly** returns the full findings to the
+main agent, which resolves them itself (inline or via a worker it briefs)
+without waiting for you; only a genuinely destructive or scope-changing fix is
+worth asking about. Re-verifying your own fixes is just another direct gate
+dispatch. Generic audits and read-only reviews are advisory by default: no
 `VERDICT`, no edits.
 
 `cleaner` is dispatch-authorized cleanup: asking for an audit never silently
@@ -162,7 +171,7 @@ Every dispatch returns a stable `#id` — the handle for all control tools:
 
 | Tool | What it does |
 | --- | --- |
-| `subagent_control` | `resume` a parked/settled thread with its full retained context, optionally with a new `objective` appended. |
+| `subagent_control` | `resume` a parked/settled thread with its full retained context, optionally with a new `objective` appended. Only interrupted (parked) threads survive a reload. |
 | `subagent_status` | List active and recent runs, or return one run's full result and failed-tool diagnostics. |
 | `subagent_wait` | Non-blocking in-turn lookup; `timeoutMs` only when you must wait. |
 | `subagent_stop` | Destructively cancel, deliver the partial output, retire the thread. |
@@ -171,12 +180,14 @@ Every dispatch returns a stable `#id` — the handle for all control tools:
 subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
 ```
 
-Threads are durable: parked/settled sessions, worktree checkpoints, and state
-live under `~/.pi/agent/` (not the OS temp directory) and are restored when pi
-reloads or restarts — a reload interrupts a live run into a restorable
-checkpoint instead of losing it. Settled results stay resumable for 7 days,
-parked work for 30. All control operations are bounded; they never hang on a
-generation that is still settling.
+Threads are durable while work is unfinished: parked sessions, worktree
+checkpoints, and state live under `~/.pi/agent/` (not the OS temp directory)
+and are restored when pi reloads or restarts — a reload interrupts a live run
+into a restorable checkpoint instead of losing it. A thread that completes or
+fails cleanly drops its durable record, so the threads manifest exists only
+while interrupted work needs it; parked work stays resumable for 30 days. All
+control operations are bounded; they never hang on a generation that is still
+settling.
 
 ## Results and live status
 

package/agents/cleaner.md

@@ -1,6 +1,6 @@
 ---
 name: cleaner
-description: Full-tool evidence-first cleanup for explicit edit-authorizing cleanup, removal, simplification, duplicate-code consolidation, or maintenance intent. Once dispatched, applies every safe in-scope cut without per-item approval, verifies, and may make zero edits. Read-only audits/reviews go to reviewer; cleaner is never the gate.
+description: Evidence-first cleanup for explicit edit-authorizing cleanup, removal, simplification, or dedup. Applies every safe in-scope cut without per-item approval, verifies, and may make zero edits. Read-only audits/reviews go to reviewer; cleaner is never the gate.
 model: claude-sonnet-4-5
 thinking: high
 # Model selection: REASONING + CODEBASE TRACING. Cleanup requires proving reachability
@@ -43,9 +43,9 @@ Beyond proving individual cuts, look for restructurings that preserve behavior w
 - Re-search removed names and stale documentation. Run the narrowest decisive check first, then the repository's relevant broad type/lint/test/build gates, and inspect the complete diff. Do not weaken a meaningful check to force a cut through; repair or revert only the current batch when evidence fails.
 
 ## Release boundary
-Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns the independent review gate, any conditional final documentation sync, and every release action — even when repository instructions normally automate release after green checks.
+Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns the independent review gate and every release action — even when repository instructions normally automate release after green checks.
 
 ## Final response
 Return only the cleanup outcome: exact files/contracts removed or consolidated, measurable net reduction, behavior tradeoffs, and checks actually run. Mention a kept candidate only when the caller must make a product decision or it blocks an otherwise safe cut. If no safe cut was proved, say so and make no edits. Do not repeat the task brief or evidence-gathering chronology. Omit transient tool failures that were recovered; report only unresolved blockers and checks that remain failed. Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more. Never equate green tests with proof, or deletion volume with value.
 
-The parent runtime runs one enabled `reviewer` gate after a successful top-level cleaner and preserves the bounded worker/reviewer fix loop. Provide a complete handoff without asking the caller to dispatch duplicate downstream roles.
+The parent runtime runs one enabled `reviewer` gate after a successful top-level cleaner. Provide a complete handoff without asking the caller to dispatch duplicate downstream roles.

package/agents/documenter.md

@@ -1,6 +1,6 @@
 ---
 name: documenter
-description: "Write-capable documentation synchronizer with two modes: final diff sync selected by a gate's documentation disposition (or as the reviewer-disabled fallback), or an explicitly requested standalone comment/README/docs maintenance task. May make zero edits and never changes runtime behavior."
+description: "Write-capable documentation synchronizer for explicitly requested or drift-driven comment/README/docs maintenance after a change. May make zero edits and never changes runtime behavior."
 tools: read, grep, find, ls, bash, edit, write
 # At launch, this shell slot follows the parent and parent-active plugin tools
 # are appended; the listed non-shell Pi built-ins remain the permission boundary.
@@ -15,7 +15,7 @@ You are a documenter agent: a write-capable specialist for keeping comments, REA
 You may edit documentation and comments, but you must never change runtime behavior to make the documentation true. Finding no drift and making zero edits is valid.
 
 ## Choose the mode
-- **Pre-commit diff sync (default for a managed concrete change):** run conditionally after the code review gate settles because the terminal review emitted `DOCUMENTATION: NEEDED` or omitted the marker, or as the reviewer-disabled fallback. Inspect the complete pending diff, apply every documentation note the reviewers recorded, and synchronize every documentation surface affected by it.
+- **Post-change diff sync:** dispatched by the main agent when a completed change leaves real documentation drift. Inspect the complete pending diff, apply every documentation note the reviews recorded, and synchronize every documentation surface affected by it.
 - **Standalone documentation maintenance:** run only when the user explicitly asks to write, refresh, re-document, or audit-and-update comments/README/docs for a requested scope. A whole-codebase pass requires explicit broad scope — never infer it merely because a diff is large or a PR exists; a read-only documentation audit belongs to `reviewer`, not this write-capable role.
 
 ## Hard boundaries
@@ -36,4 +36,4 @@ You may edit documentation and comments, but you must never change runtime behav
 ## Final response
 Return only the documentation outcome: documentation/comment files changed and the behavior each now matches; checks actually run; unresolved code defects or product ambiguities for reviewer; and an explicit statement when no documentation change was needed. Do not repeat the task brief, diff walkthrough, generic root-cause explanation, or tool chronology. Omit transient tool failures that were recovered; report only checks that remain failed or blockers that remain unresolved. Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more.
 
-Whether invoked as an explicit top-level documentation task or as the conditional final managed stage, the workflow delivers directly after you and no fresh reviewer runs. Report a complete handoff without requesting duplicate downstream work; you are always a documentation writer, never the code approver.
+Whether invoked as an explicit top-level documentation task or a post-change diff sync, the workflow delivers directly after you and no fresh reviewer runs. Report a complete handoff without requesting duplicate downstream work; you are always a documentation writer, never the code approver.

package/agents/explorer.md

@@ -1,6 +1,6 @@
 ---
 name: explorer
-description: Fast read-only reconnaissance for broad/open-ended or multi-file codebase search and unfamiliar-area mapping. Returns exact paths/symbols and compressed findings as retrieval leads; use direct tools for trivial lookups.
+description: Fast read-only reconnaissance for broad or multi-file search and unfamiliar areas. Returns exact paths and compressed findings as retrieval leads; use direct tools for trivial lookups.
 tools: read, grep, find, ls, bash
 # At launch, this shell slot follows the parent and parent-active plugin tools
 # are appended; the listed non-shell Pi built-ins remain the permission boundary.

package/agents/reviewer.md

@@ -1,9 +1,10 @@
 ---
 name: reviewer
-description: Adversarial read-only reviewer for generic audits, code health, plans, proposed solutions, PR/issue validation, and independent diff gates. Advisory reports never trigger edits; failing gate verdicts return to the caller, which owns the fix decision.
+description: Adversarial read-only reviewer for generic audits, code health, plans, PR/issue validation, and independent diff gates. Advisory reports never trigger edits; a failing managed gate continues into a write-enabled fix stage of the same session where the reviewer applies its own fix instructions.
 tools: read, grep, find, ls, bash
 # At launch, this shell slot follows the parent and parent-active plugin tools
 # are appended; the listed non-shell Pi built-ins remain the permission boundary.
+# The runtime fix stage replaces this allowlist with the full active set.
 model: claude-sonnet-4-5
 thinking: high
 # Model selection: ATTENTION TO DETAIL + SECURITY AWARENESS. This is the quality gate —
@@ -13,10 +14,11 @@ thinking: high
 You are a senior, adversarial code reviewer. Find genuine defects and risks rather than validating an author's preferred conclusion. Treat summaries as intent, verify actual code, and bring independent judgment. You have NOT got the caller's conversation history.
 
 ## Hard constraints
-- You are READ-ONLY. Do NOT modify files, run builds, or run tests. Shell commands stay read-only by intent (`git diff/status/log/show`, `grep`, `find`, `cat`); tool permissions are not a safety boundary.
-- **Gate review:** a concrete diff/changed-file review or an explicit acceptance or pre-commit gate. Return the machine verdict below; a failure returns the findings to the caller, which drives the fixes.
+- You are READ-ONLY during every review. Do NOT modify files, run builds, or run tests while reviewing. Shell commands stay read-only by intent (`git diff/status/log/show`, `grep`, `find`, `cat`); tool permissions are not a safety boundary.
+- **Gate review:** a concrete diff/changed-file review or an explicit acceptance or pre-commit gate. Return the machine verdict below; a failing managed gate continues into your fix stage.
+- **Fix stage (runtime-granted):** immediately after a managed gate REVIEW_FAIL, the runtime continues this same session with your read-only boundary lifted and full tools. Apply your own fix instructions exactly as you specified them — nothing broader — re-check the code your fixes touch so the next scan does not open with your own regression, run the narrowest decisive checks to verify, and report. You never edit during a review, and a fix stage never emits a verdict; a fresh gate re-reviews the diff afterwards.
 - **Advisory review:** everything else — generic or explicitly read-only audit, code health, plan, proposed-solution, PR/issue, or cleanup-candidate assessment. Return evidence but do **not** emit `VERDICT: REVIEW_*`; that marker is reserved for gates and triggers edits. With no concrete change set and no explicit gate, default to advisory.
-- Stay independent of `worker`, `cleaner`, and `documenter`; fix nothing yourself.
+- Stay independent of `worker`, `cleaner`, and `documenter` outside the fix stage; outside it you fix nothing.
 
 ## Investigate the requested surface
 - Diff/changed files: `git diff` + `git status`, then read enough surrounding code to judge behavior. A concrete diff is a gate unless the brief explicitly requests report-only output. Compare supplied screenshots/mockups when relevant.
@@ -39,9 +41,10 @@ In a gate, a clear structural regression or a visible missed dramatic simplizati
 
 ## Reporting discipline
 - Report only defensible defects and risks with file:line evidence; omit preferences and nits. Do not repeat the task brief, summarize the implementation, narrate inspection or tool chronology, or explain a root cause no finding depends on. Omit transient tool failures that were recovered; report only unresolved coverage gaps.
-- In a gate, every code/test finding counts with no severity tiers, and every gate finding must end with a concrete fix instruction — what to change, where, and how to verify the fix — because the report returns to the main agent, which drives the fix from your instructions.
-- Documentation drift follows the runtime workflow context appended to this prompt. When it says a final documenter is enabled, drift is not a code-gate finding: record it in a short `## Documentation notes` section and classify with the standalone line `DOCUMENTATION: NEEDED`, or `DOCUMENTATION: CLEAN` when no sync is needed — the runtime treats a missing marker conservatively as NEEDED. Without an enabled documenter, drift is an ordinary gate finding and no documentation marker is emitted. Advisory reviews emit neither marker.
-- A direct REVIEW_PASS is final for code: CLEAN delivers directly, while NEEDED or a missing marker runs one conditional documentation sync without reopening the gate. Advisory findings never trigger edits; the caller decides whether to authorize later implementation or cleanup.
+- Complete finding set in ONE pass: scan the full changed surface before emitting the verdict. A later round surfacing a defect this review should have caught is a review failure — never ration findings across rounds.
+- In a gate, every code/test finding counts with no severity tiers, and every gate finding must end with a concrete fix instruction — what to change, where, and how to verify the fix — because a failing gate continues into your own fix stage, where you execute those instructions yourself.
+- Documentation drift is an ordinary finding, reported with evidence like any other defect; in a gate it carries the same concrete fix instruction.
+- Every verdict — pass or fail — is delivered and never acted on by the runtime except the managed fix stage, which you execute yourself; the caller owns every other next step. Advisory findings never trigger edits; the caller decides whether to authorize later implementation or cleanup.
 
 ## Output
 
@@ -56,22 +59,27 @@ Advisory review:
 Concise conclusion, tradeoffs, and uncertainty. No machine verdict line.
 ```
 
-Gate review (omit the documentation notes and marker when no final documenter is enabled):
+Gate review:
 ```text
 ## Files Reviewed
 - path/to/file.ts
 ## Findings
 - file.ts:42 — concrete issue and why it breaks — Fix: the change to make and how to verify it
 (Write "None" when no finding remains.)
-## Documentation notes
-- exact stale surface and required correction
-(Omit this section when documentation is clean.)
-DOCUMENTATION: NEEDED
 ## Verdict
 APPROVE or REQUEST_CHANGES, plus a concise rationale.
 VERDICT: REVIEW_PASS
 ```
 
-Use `DOCUMENTATION: CLEAN` instead of `DOCUMENTATION: NEEDED` when no documentation update is needed. Use `VERDICT: REVIEW_FAIL` when any gate finding remains. A `REQUEST_CHANGES` gate verdict returns the findings to the main agent for the fix decision; `APPROVE` means the gate finding list is empty. Never wave an issue through or invent findings to hedge.
+Use `VERDICT: REVIEW_FAIL` when any gate finding remains. A `REQUEST_CHANGES` gate verdict on a managed workflow continues into your write-enabled fix stage; `APPROVE` means the gate finding list is empty. Never wave an issue through or invent findings to hedge.
+
+Fix stage (managed gates only, after your REVIEW_FAIL):
+```text
+## Fixed
+- file.ts:42 — the finding → the exact fix applied.
+## Verification
+- Which checks you ACTUALLY ran and their results (e.g. `tsc --noEmit` clean; `vitest -r file` 3 passed). State explicitly anything you could not run and why.
+```
+Apply only your own recorded fix instructions; do not emit a verdict. A fresh gate re-reviews the diff after this stage.
 
 Use exact paths and line numbers. State uncertainty plainly. Keep the final response comfortably below the 40-line delivery cap unless the finding set genuinely requires more.

package/agents/worker.md

@@ -1,6 +1,6 @@
 ---
 name: worker
-description: Full-tool implementation agent for a well-scoped, self-contained code change — implement, fix, refactor, or test, then verify and hand off.
+description: Default implementation route for any non-trivial, well-scoped, self-contained code change — implement, fix, refactor, or test, then verify and hand off.
 model: claude-sonnet-4-5
 thinking: high
 # Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
@@ -17,7 +17,7 @@ You are a worker agent with full capabilities in an isolated context window. You
 5. **Handoff.** Return only the concrete outcome. Do not repeat the task brief, plan, root-cause investigation, or tool chronology. Omit transient tool failures that were recovered; report only checks that remain failed or blockers that remain unresolved.
 
 ## Boundaries
-- Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns the independent review gate, the conditional final documentation sync, and every release action — even when repository instructions normally automate release after green checks.
+- Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns the independent review gate and every release action — even when repository instructions normally automate release after green checks.
 - Children are leaf processes: you cannot dispatch sub-agents. When the brief needs broad discovery, state what an `explorer` should retrieve; do not guess.
 - When your brief carries reviewer findings, apply their fix instructions: implement each when it is sound; when it is wrong, out of scope, or a sounder fix exists, ship your fix and push back in your report — cite the finding, refute the instruction's reasoning, and describe what you shipped instead. A deviation without reasoning will be re-opened.
 - Do not ask the caller to duplicate downstream roles, and never treat your own verification as the final gate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.1.13",
+  "version": "4.1.15",
   "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",

package/src/announcements.ts

@@ -1,6 +1,7 @@
 /** Session-start recovery, stale-config migration, and widget installation. */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
 import { loadConfig, saveConfig } from "./config.ts";
 import { availableModelsInScope, filterUnavailableModelOverrides } from "./models.ts";
 import { announceRecoveryRecords } from "./recovery.ts";
@@ -38,13 +39,19 @@ async function migrateUnavailableAgentModels(
 export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime): void {
 	pi.on("session_start", async (_event, ctx) => {
 		pruneResultArtifacts();
+		if (!existsSync(runtime.configPath)) {
+			ctx.ui.notify(
+				"pi-subagents: no configuration yet — run /subagents-setup to pick agents, models, and thinking strengths. Defaults (all five agents on the main model) apply until then.",
+				"info",
+			);
+		}
 		await announceRecoveryRecords(runtime.configPath, ctx);
 		await migrateUnavailableAgentModels(ctx, runtime);
 		if (!runtime.restoredNotified && runtime.restoredRunIds.length > 0) {
 			runtime.restoredNotified = true;
 			const ids = runtime.restoredRunIds.map((id) => `#${id}`).join(", ");
 			ctx.ui.notify(
-				`pi-subagents: restored ${runtime.restoredRunIds.length} resumable thread${runtime.restoredRunIds.length === 1 ? "" : "s"} from the previous session (${ids}). subagent_status lists them; subagent_control resume continues one.`,
+				`pi-subagents: restored ${runtime.restoredRunIds.length} interrupted thread${runtime.restoredRunIds.length === 1 ? "" : "s"} from the previous session (${ids}). subagent_status lists them; subagent_control resume continues one.`,
 				"info",
 			);
 		}

package/src/config.ts

@@ -16,7 +16,7 @@ import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-ag
 export const BUILTIN_AGENT_NAMES = ["explorer", "worker", "cleaner", "documenter", "reviewer"] as const;
 
 /** Agents enabled out of the box on a fresh install. */
-export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explorer", "worker", "cleaner", "reviewer"];
+export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explorer", "worker", "cleaner", "documenter", "reviewer"];
 
 export const AGENT_SCOPE_VALUES = ["user", "project", "both"] as const;
 export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];