@ferris1225/pi-subagents 4.2.13 → 4.3.1

package/CHANGELOG.md

@@ -4,6 +4,40 @@ Published versions of `@ferris1225/pi-subagents`. Unpublished numbers
 (`4.2.3`, `4.2.6`, `4.2.9`–`4.2.11`) never shipped on npm; their changes
 landed in the next published release.
 
+## 4.3.1
+
+- Make phase ownership explicit and reject an exact active duplicate by normalized
+  task plus resolved working directory, regardless of agent name.
+- Route each result exactly once: `wait: true` owns in-turn delivery, background
+  completions use follow-up wakeups, and immediate failures flush earlier successes.
+- Move worktree preparation under the bounded queue, release child-process slots
+  before Git finalization, and report repository-lane versus process-slot waits
+  accurately.
+- Keep missing restored worktrees failed, retained, and non-resumable; compute RPC
+  usage from generation-safe session-stat deltas.
+- Store the worktree recovery manifest under `ferris-pi-subagents/`, relocating
+  an existing agent-root manifest without losing retained artifact pointers.
+- Enforce a strict read-only scout tool set and strict declared-tool intersection.
+  Unknown custom tools remain conservatively write-capable for isolation.
+- Honor `enabledAgents`, including `[]`, without auto-enabling roles. Remove the
+  completed role/config migration bridge and shorten role prompts, tool metadata,
+  launch receipts, and handoffs.
+
+## 4.3.0
+
+- Built-in team is `scout`, `artisan`, and `steward`. All three stay enabled.
+- `explorer` / `executor` configs rename in place (models and thinking
+  overrides follow). `steward` is adopted. That migration is deleted in the
+  next major.
+- Artisan owns implement / fix / refactor / test. Steward owns cleanup, docs
+  sync, and merge — dispatched only when that work exists.
+- Thinking is a role default (scout low, artisan high, steward medium) that
+  `/subagents-setup` can override. Per-call `thinking` and agent-file
+  `thinking` are gone. There is no Auto row.
+- First session and first-run setup explain each role and ask for a model.
+- Unit tests cover catalog migration, role prompts, dispatch routing, and
+  honest footer / truncation notes.
+
 ## 4.2.13
 
 - README: table of contents, a What's new lead-in, and a pointer at this

package/README.md

@@ -6,20 +6,17 @@
 ![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
 ![pi](https://img.shields.io/badge/pi-extension-orange)
 
-A managed engineering team for [pi](https://github.com/earendil-works/pi): two
+A managed engineering team for [pi](https://github.com/earendil-works/pi): three
 focused sub-agents, durable threads, and Git worktree
 isolation. You install it once and your main agent delegates on its own.
 
 ## What's new
 
-**4.2.13** — this page now leads with current changes and keeps the 4.2 line
-in [CHANGELOG.md](./CHANGELOG.md).
-
-**4.2.12**
-
-- The executor confirms a named defect on current code before it edits.
-- Footer settled counts stay honest, and only while a sibling is still live.
-- Merging to `main` publishes npm and opens a matching GitHub Release.
+**4.3.1** — phase ownership prevents duplicate paid work, completion delivery
+is exactly once, worktree setup obeys the bounded queue, and final integration
+releases its child-process slot. Scout now has a strict read-only tool boundary;
+`enabledAgents` is authoritative, including `[]`. Role prompts and launch receipts
+are shorter and cost-aware. See [CHANGELOG.md](./CHANGELOG.md).
 
 ## Contents
 
@@ -45,17 +42,19 @@ at "spawn a child with a prompt" and leave the hard parts — when to delegate,
 wide to fan out, what happens when a model dies, how results come
 back — with you. This extension owns them:
 
-- The main model delegates without being asked, because a delegation directive is
-  always in its system prompt.
-- Dispatching never blocks or ends the main turn, so it can start several runs and
-  keep working while they execute.
-- Results deliver themselves. There is no status tool to poll and no lookup step.
-- Parallel writers get their own Git worktrees, so concurrent edits do not collide
-  and your index is never touched.
-- Threads keep their context across resume, stop, reload, and crash; a dead model
-  hands its session to the current main model instead of losing progress.
-- Crashes, partial starts, and integration failures come back as results with
-  recovery records — never as silent hangs.
+- The main model gets a cost-aware routing contract and delegates only when a leaf
+  context saves more work than its handoff costs.
+- One active normalized task and working directory owns its phase, so an exact
+  duplicate dispatch is rejected instead of paying twice.
+- Background completions wake the main model; `wait: true` returns the same result
+  in-turn instead. A run uses exactly one route.
+- Parallel writers use detached Git worktrees without touching your index.
+  Worktree setup obeys the bounded queue; final integration releases its process
+  slot.
+- Interrupted threads retain their session for resume after reload or crash; a
+  configured child-model failure continues the same session on the main model.
+- Start, restore, and integration failures surface with retained recovery paths
+  instead of becoming silent hangs.
 
 ## Install
 
@@ -65,10 +64,10 @@ Requires **pi >= 0.84.4** and **Node.js >= 22.19.0**.
 pi install npm:@ferris1225/pi-subagents
 ```
 
-Open pi and run `/subagents-setup` to choose agents, models, and thinking
-strengths. A fresh install enables every agent on the current main model, and each
-session start points you at the wizard until a config file exists. Then just ask
-for work:
+Open pi and run `/subagents-setup`. Choose the enabled roles, then pick a model
+and optional thinking override for each. Fresh installs select all three, but
+you can disable any role or use `[]` to disable delegation. Then just ask for
+work:
 
 ```text
 Map how authentication works, fix the refresh race, run the tests, and review the diff.
@@ -79,10 +78,11 @@ directly when you want exact control.
 
 ## The team
 
-| Agent         | Access    | Best for                                                                                                                                                                                                   |
-| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `explorer`    | Read-only | Broad search, unfamiliar-area mapping, symbol and dependency tracing. Returns a retrieval index — never proof. A single artifact the main agent must fully absorb (one issue, one spec) stays an inline read. |
-| `executor`    | Full      | A self-contained unit that changes the repository or condenses inputs: implementation, fixes, refactors, tests, evidence-first cleanup, docs/comment sync, or merging a fan-out's results into one brief — carried through verification and a result-only handoff. |
+| Agent     | Access    | Owns |
+| --------- | --------- | ---- |
+| `scout`   | Read-only | Broad or unfamiliar reconnaissance with compact findings and decisive citations. Its output is a retrieval lead, not proof. |
+| `artisan` | Full      | A substantial self-contained implementation, including affected tests, docs, comments, targeted checks, and local cleanup. |
+| `steward` | Full      | One pre-commit cleanup or cross-cutting docs/comments pass after a broad or multi-writer change is complete. |
 
 Custom roles join them with a Markdown file (see [Custom agents](#custom-agents)).
 
@@ -90,33 +90,21 @@ Every child is an isolated leaf pi process with its own context window and no
 memory of your conversation, so the brief is its only input. A good brief carries
 the goal, exact paths, constraints, and expected output — which is what the
 injected delegation guidance produces when the main agent dispatches for you.
-A named defect is not yet a change: confirm it on current code before fixing
-or briefing a fix. The executor re-reads before it edits.
-
-```text
-You
- └─ pi main agent
-     ├─ explorer ─── parallel recon, retrieval leads only
-     └─ executor ─── one deliverable per child: implement, fix, clean up,
-                     sync docs, or merge fan-out results → verify → deliver
-```
 
 ## Dispatching work
 
 ```ts
 // One task
 subagent({
-  agent: "executor",
+  agent: "artisan",
   task: "Fix the cache invalidation bug in src/cache, add regression tests, run the checks.",
 });
 
-// Parallel: as many genuinely independent units as the work has
+// Parallel only when each scope independently justifies a child
 subagent({
   tasks: [
-    { agent: "explorer", task: "Trace model fallback from dispatch to completion." },
-    { agent: "executor", task: "Add edge-case tests for config migration." },
-    // Optional per-call reasoning strength for a task that needs less of it
-    { agent: "executor", task: "Run the suite and report failures.", thinking: "low" },
+    { agent: "scout", task: "Map model fallback across src/rpc-run.ts and src/spawn.ts." },
+    { agent: "artisan", task: "Fix config validation in src/config.ts and its tests." },
   ],
 });
 ```
@@ -127,21 +115,25 @@ paces execution instead, running a pool of child processes that scales with the
 machine (half its cores, bounded to 4–16) and starting queued runs automatically
 as slots free.
 
+An active run leases its normalized task and resolved working directory across
+agent names. Dispatching the same pair again is rejected and names the existing
+run id; it does not use fuzzy matching, and resuming that thread remains allowed.
+
 Because queueing is pacing rather than refusal, it is always reported as such.
 Dispatch confirmations name each waiting run's real reason — waiting for a free
 process slot, serialized behind the shared-checkout write lane, or already
 starting its child — alongside the slot capacity. A run that waits for the write
 lane releases its slot first, so serialized writers never starve new dispatches.
 
-One child owns one coherent deliverable and its files. Dependent work starts only
-after its prerequisite delivers. Verification belongs to whoever did the work:
-every child runs the checks it can and reports exactly which ones ran, and the
-main agent inspects the actual changes before calling anything done.
+One child owns one coherent phase. Dependent work starts only after its
+prerequisite delivers. Artisan owns the affected tests, docs, comments, targeted
+checks, and local cleanup for its implementation. Scout stays read-only. Main
+inspects the integrated diff and runs the final gate.
 
 ## Parallel edits
 
-- Single tasks use your checkout. Every parallel write-capable agent (`executor`
-  and custom writers) defaults to a detached Git worktree, so
+- Single tasks use your checkout. Every parallel write-capable agent (`artisan`,
+  `steward`, and custom writers) defaults to a detached Git worktree, so
   parallel writers run at the same time. Worktree mode needs a committed `HEAD`,
   and read-only agents reject it.
 - A role file can pin its own default with `isolation: worktree` or
@@ -158,7 +150,7 @@ main agent inspects the actual changes before calling anything done.
   one repository lane, so two of them never race. A run waiting there is reported
   as a lane wait, not as slot queueing, and its process slot is already released.
 - Setup and integration failures keep the useful patch and worktree, and record
-  where they are in `~/.pi/agent/pi-subagents-recovery.json`. Every later session
+  where they are in `~/.pi/agent/ferris-pi-subagents/pi-subagents-recovery.json`.
   start repeats that notice until you remove the artifacts. When the changes had
   already been applied and only the cleanup failed, the next session start
   removes the retained copy itself and clears the notice.
@@ -176,25 +168,27 @@ Every dispatch returns a stable `#id`, which is the handle for the thread tools:
 subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
 ```
 
-There is deliberately no status, polling, or wait tool. Every result delivers
-itself as a completion that wakes the main model, so a turn never blocks on a
-running subagent — keep working or end the turn, and the completion continues
-it. The one in-turn block is `wait: true` on a dispatch, which holds that call
-until the runs it started settle: the escape hatch for one-shot `pi -p`
-parents, which exit at end of turn and would otherwise never see them. That
-wait runs on no timer and no timeout the model picks: it resolves the instant
-its run settles, a parked run answers immediately with its resume handle, and
-aborting the turn is the escape hatch. Control operations are all bounded, so
-they never hang on a generation that is still settling.
+There is no status, polling, or separate wait tool. A background dispatch returns
+a launch receipt, then its completion is delivered as a follow-up that wakes the
+main model. `wait: true` instead holds that tool call until its new runs settle,
+which is useful for one-shot `pi -p` sessions. It claims the delivery route before
+launch, so the same result cannot also arrive as a background completion; if the
+parent turn is aborted, delivery falls back to the completion path.
+
+The wait has no timer chosen by the model: it resolves when its run settles, and
+a parked run returns its resume handle. Control operations are bounded so they do
+not hang on a generation that is still settling.
 
 A thread stays durable while its work is unfinished. Parked sessions, worktree
-checkpoints, and result excerpts are recorded in a manifest beside your config, so
-a pi reload, restart, or crash interrupts a run into a resumable checkpoint
-instead of losing it, and an isolated thread resumes in the worktree it was
-already working in. Restore happens at load, and everything that answers for a run
-waits for it — `subagent_control`, `subagent_stop`, and a new dispatch before it
-takes an id — so the first call after a reload can never report parked work as
-missing or hand its id to something else.
+checkpoints, and result excerpts are recorded under the per-project storage root,
+so reload, restart, or crash produces a resumable checkpoint. An isolated thread
+continues in its original worktree.
+
+Restore runs at session start. `subagent_control`, `subagent_stop`, prompt
+injection, and new dispatches wait for it, so a parked id cannot be reported
+missing or reused. If a recorded worktree is gone, the run is surfaced as failed
+and non-resumable while its retained session and recovery record remain available
+for inspection or destructive stop.
 
 Only interrupted work needs a record, so a thread that completes or fails cleanly
 drops its own. That also means a reload keeps interrupted threads resumable, while
@@ -213,12 +207,12 @@ two lines: what it is — agent, task, token flow, cost, provider/model, elapsed
 and, dim under the label column, what it is doing right now:
 
 ```text
-● #12 executor  src/cache.ts · worktree:a91f3c · ↑5.2k ↓41.0k R210.0k W6.1k $1.9400 · 12m06s
+● #12 artisan  src/cache.ts · worktree:a91f3c · ↑5.2k ↓41.0k R210.0k W6.1k $1.9400 · 12m06s
   ↳ edit src/auth.ts
-● #15 explorer  src/models.ts · ↑1.2k ↓8.4k R31.0k W1.1k $0.0900 · openai/gpt-5-mini · 3m07s
+● #15 scout    src/models.ts · ↑1.2k ↓8.4k R31.0k W1.1k $0.0900 · openai/gpt-5-mini · 3m07s
                 ↳ grep fallback
-○ #23 executor  src/config.ts · repo lane
-○ #24 executor ↻  tests/config.test.ts · queued · 5m02s
+○ #23 artisan  src/config.ts · repo lane
+○ #24 artisan ↻  tests/config.test.ts · queued · 5m02s
 ```
 
 Telemetry drops leftmost-first when a row runs out of width (badge, wait
@@ -270,43 +264,37 @@ is missing, rate-limited, or fails at the provider level, the **same retained
 session** continues on the main model, so finished searches, reads, and edits
 survive. Ordinary task failures do not trigger a handoff.
 
-Thinking defaults to **Auto**: the role's own preference, clamped to what the
-effective model supports. `/subagents-setup` → _Configure an agent_ also offers a
-manual strength, listing only the levels that model supports. A dispatch can also
-ask for a strength per call with `thinking`, so a quick check and a deep refactor
-do not have to share one static level. Precedence: your manual
-`/subagents-setup` choice > the per-call `thinking` > the role's frontmatter >
-the default, and the winner is still clamped to the effective model. There is no separate
-vision mode — assign a multimodal model and name the image paths in the task.
-
-Every dispatch, resume, retry, and fallback snapshots the parent's
-currently active tools. A role with no explicit list inherits the full set. An
-explicit list keeps its pi built-in boundary and gains active extension tools,
-while its shell slot follows the parent: a role file naming `bash` runs
-`powershell` when that is the shell you enabled. When you run both, the child gets
-the one that fits the host — PowerShell on Windows, Bash elsewhere — rather than
-two terminals to choose between. A child never receives a shell you disabled,
-since pi's `--tools` allowlist overrides its own `defaultTools`. Read-only roles
-never gain `edit` or `write`, and all `subagent*` tools are stripped so children
-stay leaves. An empty snapshot starts the child with `--no-tools`.
-
-Shell guidance in the shipped roles is portable for the same reason: they reach
-for pi's own `read`/`grep`/`find`/`ls` tools, which behave identically everywhere,
-and keep shell examples to `git` queries instead of POSIX binaries a PowerShell
-child cannot run.
+Thinking is a **role default** — scout `low`, artisan `high`, steward
+`medium` — clamped to what the effective model supports. `/subagents-setup` →
+_Configure an agent_ lists only the levels that model supports, with the role
+default marked. There is no Auto choice, no per-dispatch `thinking` flag, and
+no `thinking` field in agent Markdown. Precedence: your setup override > the
+role default, then the model clamp. There is no separate vision mode — assign
+a multimodal model and name the image paths in the task.
+
+Every dispatch, resume, retry, and fallback snapshots the parent's active tools,
+and all `subagent*` tools are removed so children remain leaves. A role without
+an explicit list inherits that snapshot; an explicit list is a strict
+intersection, so active extension tools are available only when named. A declared
+shell slot follows the parent's active shell on non-scout roles.
+
+`scout` is a hard read-only boundary even when a project override omits or
+overstates its tool list. The shipped scout uses only `read`, `grep`, `find`, and
+`ls`; it receives no shell or unknown custom tool. Unknown tools declared by other
+roles are conservatively treated as write-capable when isolation is chosen. An
+empty resolved snapshot starts the child with `--no-tools`.
 
 ## Configuration
 
-`/subagents-setup` stays one level deep: enabled agents, plus a model and thinking
-strength per agent. Everything else is config-file only, stored at
+`/subagents-setup` enables or disables roles and configures a model plus optional
+thinking override for each enabled role. The same settings live in
 `~/.pi/agent/pi-subagents.json` (following `PI_CODING_AGENT_DIR`):
 
 ```json
 {
-  "enabledAgents": ["explorer", "executor"],
-  "knownAgents": ["explorer", "executor"],
-  "agentModels": { "explorer": "anthropic/claude-haiku-4-5" },
-  "agentThinkingLevels": { "executor": "high" },
+  "enabledAgents": ["scout", "artisan", "steward"],
+  "agentModels": { "scout": "anthropic/claude-haiku-4-5" },
+  "agentThinkingLevels": { "artisan": "high" },
   "maxResultLines": 40,
   "agentScope": "user",
   "idleTimeoutSec": 90
@@ -316,31 +304,20 @@ strength per agent. Everything else is config-file only, stored at
 | Field                 | Meaning                                                                           |
 | --------------------- | --------------------------------------------------------------------------------- |
 | `enabledAgents`       | Agents available for discovery and delegation. `[]` disables all.                 |
-| `knownAgents`         | Built-ins this config has seen; automatic bookkeeping — never edit it.            |
 | `agentModels`         | Optional `provider/model-id` per agent; missing = current main model.             |
-| `agentThinkingLevels` | Optional manual level per agent; missing = Auto.                                  |
+| `agentThinkingLevels` | Optional setup override per agent; missing = the role default.                    |
 | `maxResultLines`      | Lines kept in a completion message before the artifact takes over. Default `40`.  |
 | `agentScope`          | Discover `user`, `project`, or `both` agent directories. Default `user`.          |
 | `idleTimeoutSec`      | Seconds without child RPC output before termination; `0` disables. Default `90`.  |
 
-The delegation directive is always injected; there is no toggle. Invalid values
-fall back safely, and stale keys — including the former `proactiveInjection`,
-`maxConcurrency`, `maxFixRounds`, and `notifyOnReviewPass` knobs — are dropped
-automatically. Built-in roles a newer package no longer ships (such as the
-retired `worker`/`cleaner`/`documenter`/`synthesizer`/`reviewer` set) are pruned
-from `enabledAgents`, `knownAgents`, and the model/thinking tables at first
-load, so the setup wizard never mixes old and new roles; custom agents are
-untouched. At session
-start, model overrides pi no longer reports are removed with a one-time notice. If
-pi's own session compaction fails mid-thread, a notice surfaces the error and the
-automatic retry instead of failing quietly.
-
-Agents shipped by a newer package version turn themselves on at the next
-session: a built-in the config has never seen is adopted into `enabledAgents`
-and follows explorer's configured model and thinking level — the fast lane
-these light roles need — while an agent you disabled stays disabled
-(`knownAgents` is what tells the two cases apart). Enabling a role in
-`/subagents-setup` adopts the same explorer route.
+When at least one role is enabled, the cost-aware delegation directive is injected
+automatically. `enabledAgents` is authoritative: the extension neither re-enables
+a disabled role nor adopts or renames roles. Invalid known fields fall back safely,
+and unknown fields are dropped when the canonical config is persisted.
+
+At session start, model overrides that pi no longer reports are removed with a
+one-time notice. If pi's own session compaction fails mid-thread, a notice surfaces
+the error and automatic retry instead of failing quietly.
 
 ## Custom agents
 
@@ -352,21 +329,20 @@ Built-ins ship with the package. Add or replace them with Markdown files:
 
 ```yaml
 ---
-name: explorer
+name: scout
 description: Fast read-only codebase reconnaissance
-thinking: low
 isolation: shared
-tools: read, bash
+tools: read, grep, find, ls
 ---
 …additional system prompt…
 ```
 
-`description` is the routing line the main model reads, and `thinking` is the
-role's Auto preference, which a wizard choice overrides. `isolation` pins the
+`description` is the routing line the main model reads. `isolation` pins the
 role's default boundary as described under [Parallel edits](#parallel-edits).
 Models come only from `/subagents-setup`; an agent file cannot pin one. An
-explicit `tools` list is the capability boundary, and omitting it inherits the
-parent's complete active set.
+explicit `tools` list is intersected with the parent's active set; omitting it
+inherits the active set. A role named `scout` is always reduced to the fixed
+read-only tool set described above.
 
 ## Storage and cleanup
 
@@ -377,15 +353,15 @@ that removes it, so this directory does not grow without bound:
 | Path                                       | Holds                                                | Removed                                                          |
 | ------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------- |
 | `pi-subagents.json`                        | Your configuration                                   | Never — it is yours                                              |
-| `pi-subagents-recovery.json`               | Worktree integration and cleanup failures            | When the retained patch or worktree it points at is gone         |
+| `ferris-pi-subagents/pi-subagents-recovery.json` | Worktree integration and cleanup failures | When the retained patch or worktree it points at is gone |
 | `ferris-pi-subagents/<project>/pi-subagents-threads.json` | One record per interrupted thread     | When the thread settles, or after 30 days                        |
-| `ferris-pi-subagents/<project>/sessions/`  | Retained child sessions that a resume continues from | When the pi session that produced it ends, or its owner is gone  |
-| `ferris-pi-subagents/<project>/worktrees/` | Isolated checkouts for parallel writers              | On integration, or when its owning process is gone               |
+| `ferris-pi-subagents/<project>/sessions/`  | Retained child sessions that a resume continues from | When the thread settles or its retained record is removed        |
+| `ferris-pi-subagents/<project>/worktrees/` | Isolated checkouts for parallel writers              | On integration, or when no retained record claims them           |
 | `ferris-pi-subagents/<project>/results/`   | Full text of truncated results                       | After 7 days, or beyond 50 per project                           |
 | `ferris-pi-subagents/<project>/tmp/`       | Child prompt copies and the no-retry policy shim     | When its owning process exits                                    |
 | `ferris-pi-subagents/<project>/`           | All of the above for one checkout                     | When the whole directory has been idle for 3 days                |
 
-Cleanup runs at extension load and is deliberately conservative. A directory goes
+Cleanup runs at session start and is deliberately conservative. A directory goes
 away only when the process that created it is gone and no manifest record still
 claims it, so a live sibling pi instance never loses state and parked work
 outlives its own process by design — a reference from the threads manifest always
@@ -398,30 +374,18 @@ npm install
 npm run check
 ```
 
-There are no bundled runtime dependencies; pi and TypeBox are peers. The source is
+`npm run check` is `tsc --noEmit` plus the unit tests (`npm test`). There are
+no bundled runtime dependencies; pi and TypeBox are peers. The source is
 split by responsibility: dispatch policy, thread lifecycle, RPC
 transport, worktree integration, completion delivery, tools, and TUI status.
 
 ## Changelog
 
-The 4.2 line lives in [CHANGELOG.md](./CHANGELOG.md). Latest published
-version is **4.2.13**.
-
-| Version | What changed |
-| ------- | ------------ |
-| 4.2.13  | README navigation, What's new, and this changelog. |
-| 4.2.12  | Confirm-before-fix; honest footer counts; `main` publishes npm + GitHub Release. |
-| 4.2.8   | Footer roll-up; wait-path token usage; hold completions across compaction. |
-| 4.2.7   | Sharper executor routing; per-dispatch `thinking`. |
-| 4.2.5   | Per-project threads manifest. |
-| 4.2.4   | One-line explorer findings; recovery cleanup retry. |
-| 4.2.2   | Single-artifact reads stay inline. |
-| 4.2.1   | Prune retired roles from upgraded configs. |
-| 4.2.0   | Team is `explorer` + `executor`; two-line live widget. |
+See [CHANGELOG.md](./CHANGELOG.md) for published release notes.
 
 ## Release
 
-Merging to `main` publishes `@ferris1225/pi-subagents` when `package.json`
+Pushing to `main` publishes `@ferris1225/pi-subagents` when `package.json`
 carries a version npm does not have yet, then opens a matching GitHub Release.
 Do not `npm publish` from a laptop. The workflow is
 `.github/workflows/publish.yml` (npm trusted publisher or `NPM_TOKEN`).

package/agents/artisan.md

@@ -0,0 +1,19 @@
+---
+name: artisan
+description: Owns a substantial implementation scope, including directly affected tests, docs, comments, and verification.
+---
+
+You own one implementation phase. The task brief is your only context.
+
+## Rules
+
+- Inspect current code and confirm the defect before editing; a disproved issue means zero edits.
+- Make the smallest coherent root-cause change. Preserve unrelated work and existing conventions; avoid speculative abstractions and unrelated cleanup.
+- Own code refactors, directly affected tests, README/docs, comments, and local diff hygiene. Remove debug output, dead code, stale comments, and other debris introduced in your scope.
+- Leave standalone docs and cross-cutting pre-commit cleanup for a completed broad or multi-writer change to `steward`.
+- Run the smallest targeted check, then relevant project gates. Report unrun or pre-existing failures exactly; never imply a check passed when it did not run.
+- You are a leaf: do not dispatch agents, bump versions, commit, push, publish, tag, or release.
+
+## Output
+
+Return only the outcome, changed paths, checks run, and material blockers. No task restatement, plan, investigation narrative, or tool chronology.

package/agents/scout.md

@@ -0,0 +1,18 @@
+---
+name: scout
+description: Read-only reconnaissance for broad or unfamiliar code; returns compact, decisive citations.
+tools: read, grep, find, ls
+---
+
+You own one broad reconnaissance phase. Atomic lookups and known locations stay with main. The task brief is your only context.
+
+## Rules
+
+- Stay read-only: never create, edit, delete, install, build, or run commands. Use `read`/`grep`/`find`/`ls` only.
+- Findings are retrieval leads, not proof for deletion, security, compatibility, or persistence decisions. Cite decisive lines so main can plan without repeating the search; a later actor rechecks only source needed for its own decision or edit.
+- Search broadly once, then read key sections and follow relevant imports, callers, tests, and types. Cluster related questions instead of running a series of small searches.
+- Read requested images when relevant. State real gaps instead of guessing.
+
+## Output
+
+Return at most 15 evidence bullets as ``- `path:line-range` — fact``. Add `Start here:` or `Gaps:` only when useful. No preamble, task restatement, file inventory, chronology, or nonessential code excerpts.

package/agents/steward.md

@@ -0,0 +1,19 @@
+---
+name: steward
+description: Pre-commit cleanup and cross-cutting docs/comment sync for a completed broad or multi-writer change.
+---
+
+You own one final hygiene phase after primary writing has finished. The task brief is your only context.
+
+## Rules
+
+- Require a named completed scope such as an uncommitted diff, Git range, or directory. Stop if primary writing is still active.
+- Start from that diff; never repeat implementation or reconnaissance. For a deletion candidate, read only load-bearing lines and search consumers before removing it. Keep uncertain dynamic behavior, public APIs, persisted formats, and compatibility outside the brief.
+- Remove dead code, duplication, debug residue, stale comments, and needless complexity without changing product behavior.
+- Synchronize cross-cutting comments, README, examples, and user docs. Code-local comments and directly affected docs belong to the artisan; do not rewrite them merely for style.
+- Report behavior changes, fixes, refactors, or missing tests for an artisan instead of performing them.
+- Run relevant checks and report failures exactly. You are a leaf: do not dispatch agents, bump versions, commit, push, publish, tag, or release.
+
+## Output
+
+Return only cleaned or synchronized paths, checks run, kept candidates needing a decision, and material blockers. No task restatement, investigation narrative, or tool chronology.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.2.13",
-  "description": "A managed sub-agent team for pi: explorer and executor roles, durable threads, model fallback, and Git worktree isolation.",
+  "version": "4.3.1",
+  "description": "A managed sub-agent team for pi: scout, artisan, and steward roles, durable threads, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,8 @@
     ]
   },
   "scripts": {
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && npm test",
+    "test": "node --experimental-transform-types --test test/*.test.ts",
     "prepack": "npm run check"
   },
   "peerDependencies": {