@ferris1225/pi-subagents 4.3.4 → 4.3.6

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.6
+
+- Add `subagent_control steer` for nonblank, parent-mediated guidance to the current active
+  RPC attempt without replacing its logical objective. Stable control serialization orders
+  steering against stop and AbortSignal shutdown; bounded ACKs keep stop responsive.
+- Refine the lean delegation directive: main owns architecture; for one high-stakes
+  uncertainty at most two read-only scouts may examine distinct hypotheses, without
+  capping unrelated disjoint scout scopes; main reconciles cited evidence, writers
+  and briefs never overlap, and new evidence steers the existing phase instead of
+  duplicating or restarting it.
+- Steer background completions and stop results into the next parent model boundary
+  instead of queuing them until the whole parent run settles, preventing stale notifications
+  from arriving after the main agent has already finished.
+- Validate durable session, worktree, repository, and recovery paths against their canonical
+  project-scoped layout before restore or cleanup. Forged and junction-escaping records are
+  dropped without deleting external targets.
+- Keep worktree and patch artifacts referenced by recovery records through durable sweeps and
+  stale project-root retention until their recovery notice can be delivered.
+- Clarify that worktree isolation protects Git changes rather than sandboxing child privileges
+  or third-party Pi packages.
+
+## 4.3.5
+
+- Restore `/subagents-setup`'s nested menu flow, fuzzy model picker, and disabled
+  custom-role discovery.
+- Retire the built-in `sentinel` role and mandatory pre-commit review workflow.
+  Config normalization, loading, and saving now remove its enabled/known entries
+  and model/thinking overrides while preserving every other custom role.
+- Keep role prompts self-contained: direct diagnosis, test, and cleanup rules remain,
+  while external loading directives are removed.
+- Delegate substantial independent phases more proactively while capping the child-process
+  pool at six and retaining phase leases, duplicate-dispatch rejection, and single-route delivery.
+- Move the extension assembly to package-root `index.ts`, group `src/` by responsibility,
+  and split thread restoration, shared lifecycle coordination, RPC control, and Git command
+  execution out of the largest modules. Pi now shows the package name without a `:src` suffix.
+
 ## 4.3.4
 
 - Keep artisan, steward, and sentinel fully usable when Ferris skills are absent.

package/README.md

@@ -6,15 +6,16 @@
 ![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): four
+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.3.4** — makes Ferris skills optional enhancements instead of runtime
-requirements. Artisan, steward, and sentinel remain fully operational from their
-standalone role prompts when users have no Ferris skills installed.
+**4.3.6** — adds live parent-mediated steering for running children, delivers background
+completions and stop results at the next safe parent boundary, and hardens durable
+recovery paths without treating Git worktrees as a security sandbox.
+
 See [CHANGELOG.md](./CHANGELOG.md).
 
 ## Contents
@@ -24,7 +25,7 @@ See [CHANGELOG.md](./CHANGELOG.md).
 - [The team](#the-team)
 - [Dispatching work](#dispatching-work)
 - [Parallel edits](#parallel-edits)
-- [Threads: resume, stop](#threads-resume-stop)
+- [Threads: steer, resume, stop](#threads-steer-resume-stop)
 - [Live status and results](#live-status-and-results)
 - [Models, thinking, and tools](#models-thinking-and-tools)
 - [Configuration](#configuration)
@@ -41,12 +42,13 @@ 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 gets a cost-aware routing contract and delegates only when a leaf
-  context saves more work than its handoff costs.
+- The main model gets a cost-aware routing contract and proactively delegates
+  substantial self-contained phases when a fresh 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.
+- Background completions and stop results arrive at the next parent model boundary;
+  `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.
@@ -63,11 +65,14 @@ Requires **pi >= 0.84.4** and **Node.js >= 22.19.0**.
 pi install npm:@ferris1225/pi-subagents
 ```
 
-Open pi and run `/subagents-setup`. One overlay shows every role's enabled state,
-model, and effective thinking level. Move through the grid, search models in place,
-then choose **Save & Exit** to write everything once; **Cancel** or `Esc` discards
-the draft. Fresh installs select all four, and an upgrade surfaces a new built-in
-once without re-enabling it after you deliberately turn it off. Then ask for work:
+Pi's extension list shows `@ferris1225/pi-subagents` without an internal source-path suffix.
+
+Open pi and run `/subagents-setup`. The original menu flow lets you enable or
+disable roles, configure one role's model and thinking level, or run the full setup
+again. Each screen uses the usual arrow-key/Enter/Esc navigation, and model lists
+remain searchable. Fresh installs select all three. A newly shipped built-in is
+surfaced once without being re-enabled after you deliberately turn it off. Then ask
+for work:
 
 ```text
 Map how authentication works, fix the refresh race, run the tests, and review the diff.
@@ -78,18 +83,14 @@ directly when you want exact control.
 
 ## The team
 
-| Agent      | Access      | Owns |
-| ---------- | ----------- | ---- |
-| `scout`    | Read-only   | Broad or unfamiliar code reconnaissance and external research. Returns compact file citations or source URLs as leads, not proof. |
-| `artisan`  | Full        | One substantial primary change—implementation, fix, refactor, test, or docs—through root cause, affected verification, and local hygiene. |
-| `steward`  | Full        | One final cleanup and cross-cutting docs/comment sync pass after a broad or multi-writer change. |
-| `sentinel` | Review-only | A post-cleanup adversarial review using standalone evidence gates plus any matching Ferris skills; reports only evidence-backed defects and concrete test gaps. |
+| Agent     | Access    | Owns |
+| --------- | --------- | ---- |
+| `scout`   | Read-only | Broad or unfamiliar code reconnaissance and external research. Returns compact file citations or source URLs as leads, not proof. |
+| `artisan` | Full      | One substantial primary change—implementation, fix, refactor, test, or docs—through root cause, affected verification, and local hygiene. |
+| `steward` | Full      | One final cleanup and cross-cutting docs/comment sync pass after a broad or multi-writer change. |
 
-Role prompts are standalone: they embed root-cause-first diagnosis, meaningful test
-evidence, bounded cleanup, and evidence-only review. Optional Ferris skills remain
-the canonical source of deeper language, platform, debugging, testing, and audit
-guidance. Artisan and sentinel load matching skills when available; steward uses
-`ferris-audit`; a missing skill never blocks a role or changes its ownership contract.
+Role prompts are self-contained and directly embed root-cause-first diagnosis,
+meaningful test evidence, and bounded cleanup.
 
 Custom roles join them with a Markdown file (see [Custom agents](#custom-agents)).
 
@@ -116,11 +117,10 @@ subagent({
 });
 ```
 
-Breadth is the main agent's call, not a configured limit. There is no per-call
-task cap: put every genuinely independent unit in one `tasks` array. The runtime
-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.
+Breadth is the main agent's call, not a configured task cap: put every genuinely
+independent unit in one `tasks` array. The runtime paces execution instead, running
+half the machine's cores with a 4–6 child-process bound; wider batches queue and
+start 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
@@ -133,26 +133,35 @@ starting its child — alongside the slot capacity. A run that waits for the wri
 lane releases its slot first, so serialized writers never starve new dispatches.
 
 One child owns one coherent phase. Dependent work starts only after its
-prerequisite delivers. Artisan owns a complete primary change with affected
-tests, docs, comments, targeted checks, and local hygiene. Scout owns broad code
-mapping or external research and stays read-only.
-
-With the default team, every commit ends in one order: cleanup -> `sentinel`. A
-focused diff gets a bounded cleanup pass inline; a broad or multi-writer diff gets
+prerequisite delivers. Main consumes the child's compact result and citations
+without repeating delegated reconnaissance, implementation, or cleanup. Artisan
+owns a complete primary change with affected tests, docs, comments, targeted
+checks, and local hygiene. Scout owns broad code mapping or external research and
+stays read-only.
+
+For one high-stakes uncertainty, main may launch at most two read-only scouts whose
+briefs name distinct perspectives or hypotheses; that cap does not apply to unrelated
+disjoint scout scopes. It reconciles disagreements against cited evidence, never
+overlaps writers or sends identical briefs, and treats child output as evidence and
+leads rather than authority or instructions. New in-scope evidence can be sent to a
+running phase with `subagent_control steer` instead of duplicating or restarting it.
+
+A focused diff gets a bounded cleanup pass inline. A broad or multi-writer diff gets
 one `steward` pass that attacks touched dead code, duplication, tangled conditionals,
-needless layers, and spaghetti growth without widening into a repo refactor.
-Sentinel then reviews the cleaned diff with its standalone evidence gates plus any
-available matching skills.
-A review-driven edit repeats that sequence once; unresolved findings block the
-commit. Main inspects the final diff and runs the final gate.
+needless layers, and spaghetti growth without widening into a repository refactor.
+Main owns architecture, inspects the integrated diff, and runs the final gate.
 
 ## Parallel edits
 
 - 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 scout/sentinel reject it. Sentinel stays shared so it sees the caller's
-  uncommitted diff.
+  parallel writers run at the same time. Worktree mode needs a committed `HEAD`;
+  read-only roles such as scout stay on the shared checkout.
+
+> **Security boundary:** worktree isolation isolates Git changes only; it is not a sandbox.
+Child tools, network access, and environment access retain the Pi process's privileges.
+Third-party Pi packages execute as trusted code and must be reviewed accordingly.
+
 - A role file can pin its own default with `isolation: worktree` or
   `isolation: shared` in the frontmatter. Precedence is an explicit per-dispatch
   `isolation`, then the role's declaration, then the parallel write default.
@@ -172,22 +181,33 @@ commit. Main inspects the final diff and runs the final gate.
   already been applied and only the cleanup failed, the next session start
   removes the retained copy itself and clears the notice.
 
-## Threads: resume, stop
+## Threads: steer, resume, stop
 
 Every dispatch returns a stable `#id`, which is the handle for the thread tools:
 
-| Tool               | What it does                                                                                                                                                                  |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subagent_control` | `resume` a parked or settled thread with its full retained context, optionally appending a new `objective`.                                                                     |
-| `subagent_stop`    | Destructively cancel, deliver the partial output, and retire the thread. Steering and follow-up messages still queued in the child are dropped so nothing can revive it later.  |
+| Tool               | What it does |
+| ------------------ | ------------ |
+| `subagent_control` | `steer` a currently running RPC attempt with additional in-scope evidence/guidance, or `resume` a parked/settled thread with retained context and an optional appended `objective`. |
+| `subagent_stop`    | Destructively cancel, deliver partial output, and retire the thread. Steering and follow-up messages still queued in the child are dropped so nothing can revive it later. |
 
 ```ts
+subagent_control({ action: "steer", id: 7, objective: "The failing request used an expired token; account for that evidence." });
 subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
 ```
 
+`steer` requires a nonblank `objective` and accepts only the active running RPC
+attempt for that stable id. It adds guidance to the current phase; it does not replace
+the thread's original task. Parked, settled, queued, starting, retrying, interrupting,
+stopped, retired, and missing threads are rejected without changing them. Steering ACKs
+are bounded, and steering/stop are serialized so stop can clear queued child messages
+and abort without a stale steer landing afterward.
+
 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,
+a launch receipt, then its completion is steered at the next safe parent boundary—after
+the current tool calls and before the next model call. This wakes the main model without
+waiting for its whole run to end.
+
+`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.
@@ -210,6 +230,11 @@ 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.
 
+Persisted sessions and worktrees are resumed or removed only when their canonical paths
+match the current project's managed storage layout and repository. Invalid records are
+dropped without following or deleting their targets. Recovery-owned worktrees and patches
+remain protected from startup sweeps and project-root retention until recovery is announced.
+
 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
 threads that had already finished keep only their delivered result.
@@ -279,17 +304,15 @@ rather than a fabricated number.
 ## Models, thinking, and tools
 
 Each agent runs on the current main model or one picked in `/subagents-setup`,
-which labels vision and text-only models. Without its own override, `sentinel`
-uses `artisan`'s configured model; if artisan also follows main, sentinel does
-too. If a selected model is missing, rate-limited, or fails at the provider level,
-the **same retained
+which labels vision and text-only models. If a selected model 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 is a **role default** — scout `low`, artisan `high`, steward `medium`,
-sentinel `max` — clamped to what the effective model supports. The unified setup
-grid shows the effective level; changing the thinking cell cycles only supported
-levels, and returning to the role default clears the stored override. There is no
+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 and marks the role
+default; selecting it clears the stored override. 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
@@ -314,25 +337,19 @@ For external research scout prefers official documentation, specifications, rele
 notes, and first-party repositories; it fetches decisive pages rather than citing
 search snippets, records material dates/versions, and marks uncertainty.
 
-`sentinel` has an explicit retrieval/documentation list plus a portable shell
-slot for Git inspection and the smallest proving check. It is pinned to `shared`
-so it sees the current uncommitted diff. Its concise prompt uses matching available
-Ferris skills, preserves their owners, and forbids mutation; missing skills do not
-block review. This is a review contract,
-not a hard shell sandbox.
-
 ## Configuration
 
-`/subagents-setup` opens one transactional overlay for every built-in and already
-configured custom role. Its grid edits enabled state, model, and thinking before
-**Save & Exit** persists the complete draft; **Cancel**/`Esc` writes nothing. Model
-selection remains inside the overlay and supports fuzzy search. Other settings live in
+`/subagents-setup` opens the original settings menu: enable or disable roles,
+configure one enabled role's model and thinking level, or walk through a full
+re-setup. `Esc` moves back through the menu stack, and model lists support fuzzy
+search. Built-in and previously configured custom roles remain available in the
+enable menu. Other settings live in
 `~/.pi/agent/pi-subagents.json` (following `PI_CODING_AGENT_DIR`):
 
 ```json
 {
-  "enabledAgents": ["scout", "artisan", "steward", "sentinel"],
-  "knownAgents": ["scout", "artisan", "steward", "sentinel"],
+  "enabledAgents": ["scout", "artisan", "steward"],
+  "knownAgents": ["scout", "artisan", "steward"],
   "agentModels": { "scout": "anthropic/claude-haiku-4-5" },
   "agentThinkingLevels": { "artisan": "high" },
   "maxResultLines": 40,
@@ -345,7 +362,7 @@ selection remains inside the overlay and supports fuzzy search. Other settings l
 | --------------------- | ------- |
 | `enabledAgents`       | Agents available for discovery and delegation. `[]` disables all. |
 | `knownAgents`         | Roles already surfaced by setup; retains disabled custom roles and tracks built-in adoption. |
-| `agentModels`         | Optional model per agent; missing means main, except sentinel inherits artisan's override. |
+| `agentModels`         | Optional model per agent; missing means the current main model. |
 | `agentThinkingLevels` | Optional setup override per agent; missing means 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`. |
@@ -354,8 +371,10 @@ selection remains inside the overlay and supports fuzzy search. Other settings l
 When at least one role is enabled, the cost-aware delegation directive is injected
 automatically. `enabledAgents` is authoritative after catalog adoption: a newly
 shipped built-in is appended once, then `knownAgents` records that it was surfaced
-so a deliberate later disable remains disabled. Invalid known fields fall back
-safely, and unknown fields are dropped when canonical config is persisted.
+so a deliberate later disable remains disabled. On upgrade, the retired `sentinel`
+entry is removed from enabled and known agents plus model and thinking overrides;
+all other custom roles and known-agent entries remain intact. Invalid known fields
+fall back safely, and unknown fields are dropped when 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
@@ -398,16 +417,16 @@ that removes it, so this directory does not grow without bound:
 | `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 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>/worktrees/` | Isolated checkouts for parallel writers              | On integration, or when no thread/recovery 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                |
+| `ferris-pi-subagents/<project>/`           | All of the above for one checkout                     | After 3 idle days unless a thread/recovery record claims it      |
 
 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
-beats an age rule.
+away only when the process that created it is gone and no valid manifest record still
+claims it, so a live sibling pi instance never loses state and parked or recovery-owned
+work outlives its own process by design. Thread and recovery references always beat an
+age rule.
 
 ## Development
 
@@ -418,8 +437,9 @@ npm run check
 
 `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.
+grouped by responsibility under `src/`: configuration, delegation, execution, isolation,
+lifecycle, and presentation. Thread restoration, shared lifecycle coordination, RPC control,
+and Git command execution live in focused modules rather than oversized catch-all files.
 
 ## Changelog
 

package/agents/artisan.md

@@ -7,7 +7,6 @@ You own one primary change phase: implementation, fix, refactor, test, or substa
 
 ## Rules
 
-- Use matching ferris skills when available: `ferris-debug` for unexplained failures, `ferris-tests` for test changes, and the relevant language or platform skill. Missing skills are not a blocker; the rules below are the fallback contract.
 - For a reported defect or failure, inspect current behavior, confirm the defect before editing, and establish its root cause; 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 the complete primary change plus directly affected tests, README/docs, comments, and local diff hygiene. Remove debug output, dead code, stale comments, and other debris introduced in your scope.

package/agents/steward.md

@@ -3,11 +3,10 @@ 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 and before sentinel review. The task brief is your only context.
+You own one final hygiene phase after primary writing has finished. The task brief is your only context.
 
 ## Rules
 
-- Use `ferris-audit` when available and apply its automatic pre-commit tier. Missing skills are not a blocker; the rules below are the fallback contract and must not widen into repo-wide cleanup.
 - Require a named completed scope such as an uncommitted diff or Git range. Start there; never repeat implementation or reconnaissance, and stop if primary writing is still active.
 - Hunt hard inside the touched scope: dead or unreachable code, unused imports/exports, duplicated facts or branches, debug residue, stale comments, one-off flags, tangled conditionals, pass-through wrappers, cast/optional fallback sprawl, feature logic in shared paths, and growth toward 1000-line files.
 - Prefer deleting branches, state, and layers; otherwise reuse the canonical helper. Never merely move spaghetti. Prove every cut has no live consumer, and keep uncertain dynamic behavior, public APIs, persisted formats, and compatibility.

package/{src/index.ts → index.ts}

@@ -3,12 +3,12 @@
  *
  * Assembly point: builds the shared runtime and registers everything.
  * The heavy lifting lives in focused modules:
- *   - dispatch.ts         — tool contract, managed role policy, internal steps
- *   - thread-lifecycle.ts — stable generations, controls, final integration/delivery
- *   - tools.ts            — subagent_control / subagent_stop
- *   - announcements.ts — session-start recovery, notices, and widget install
- *   - widget.ts        — active-only TUI run status
- *   - runtime.ts       — shared per-session state
+ *   - delegation/    — role discovery, routing prompts, and tool contract
+ *   - configuration/ — persisted settings, model routes, and setup UI
+ *   - execution/     — process queue, RPC transport/control, and model handoff
+ *   - lifecycle/     — durable threads, restoration, controls, and delivery
+ *   - isolation/     — Git worktrees, recovery, and temporary-state hygiene
+ *   - presentation/  — announcements, formatting, monitor, status, and widget
  *
  * Also registers the `/subagents-setup` command and a `before_agent_start` hook
  * that injects a delegation directive into the parent system prompt so the main
@@ -20,19 +20,19 @@
 
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { discoverAgents } from "./agents.ts";
-import { registerAnnouncements } from "./announcements.ts";
-import { getConfigPath, loadConfig } from "./config.ts";
-import { registerSubagentTool } from "./dispatch.ts";
-import { matchRunIds } from "./format.ts";
-import { buildDelegationDirective } from "./prompt.ts";
-import { createRuntime } from "./runtime.ts";
-import { runSetup } from "./setup.ts";
-import { currentSubagentDepth } from "./spawn.ts";
-import { clearActiveRunsStatus } from "./status.ts";
-import { bootstrapDurableState } from "./thread-lifecycle.ts";
-import { registerLookupTools } from "./tools.ts";
-import { clearActiveRunsWidget } from "./widget.ts";
+import { getConfigPath, loadConfig } from "./src/configuration/config.ts";
+import { runSetup } from "./src/configuration/setup.ts";
+import { discoverAgents } from "./src/delegation/agents.ts";
+import { registerSubagentTool } from "./src/delegation/dispatch.ts";
+import { buildDelegationDirective } from "./src/delegation/prompt.ts";
+import { currentSubagentDepth } from "./src/execution/spawn.ts";
+import { createRuntime } from "./src/lifecycle/runtime.ts";
+import { bootstrapDurableState } from "./src/lifecycle/thread-restore.ts";
+import { registerLookupTools } from "./src/lifecycle/tools.ts";
+import { registerAnnouncements } from "./src/presentation/announcements.ts";
+import { matchRunIds } from "./src/presentation/format.ts";
+import { clearActiveRunsStatus } from "./src/presentation/status.ts";
+import { clearActiveRunsWidget } from "./src/presentation/widget.ts";
 
 export { matchRunIds };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.3.4",
-  "description": "A managed sub-agent team for pi: scout, artisan, steward, and sentinel roles, durable threads, model fallback, and Git worktree isolation.",
+  "version": "4.3.6",
+  "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": {
@@ -25,6 +25,7 @@
     "dead-code"
   ],
   "files": [
+    "index.ts",
     "src",
     "agents",
     "README.md",
@@ -33,7 +34,7 @@
   ],
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./index.ts"
     ]
   },
   "scripts": {

package/src/{config.ts → configuration/config.ts}

@@ -13,11 +13,14 @@ import { dirname, join } from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
-export const BUILTIN_AGENT_NAMES = ["scout", "artisan", "steward", "sentinel"] as const;
+export const BUILTIN_AGENT_NAMES = ["scout", "artisan", "steward"] as const;
 
-// Historical catalog for configs written before the marker existed. Keep this
-// frozen so future built-ins are still recognized as new.
-const PRE_SENTINEL_AGENT_NAMES = ["scout", "artisan", "steward"] as const;
+// Historical catalog for configs written before built-in adoption tracking.
+// Keep this frozen so future built-ins are still recognized as new.
+const INITIAL_AGENT_NAMES = ["scout", "artisan", "steward"] as const;
+
+/** Names that used to be built in and must not survive as custom roles. */
+const RETIRED_AGENT_NAMES = new Set(["sentinel"]);
 
 /** Agents enabled out of the box on a fresh install. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = [...BUILTIN_AGENT_NAMES];
@@ -38,8 +41,6 @@ export function roleThinkingLevel(agentName: string): ThinkingLevel {
 			return "low";
 		case "artisan":
 			return "high";
-		case "sentinel":
-			return "max";
 		case "steward":
 			return "medium";
 		default:
@@ -47,14 +48,6 @@ export function roleThinkingLevel(agentName: string): ThinkingLevel {
 	}
 }
 
-/** Sentinel shares artisan's configured model unless it has its own override. */
-export function configuredModelForAgent(
-	agentModels: Readonly<Record<string, string>>,
-	agentName: string,
-): string | undefined {
-	return agentModels[agentName] ?? (agentName === "sentinel" ? agentModels.artisan : undefined);
-}
-
 /** Short responsibility line shown next to each built-in in setup lists. */
 export interface AgentProfile {
 	/** A few words for picker rows. */
@@ -76,10 +69,6 @@ export const AGENT_PROFILES: Record<(typeof BUILTIN_AGENT_NAMES)[number], AgentP
 		summary: "pre-commit finish",
 		remark: "Cleans a completed broad or multi-writer diff and synchronizes cross-cutting docs/comments without changing behavior.",
 	},
-	sentinel: {
-		summary: "adversarial review",
-		remark: "Challenges every cleaned pre-commit diff with standalone evidence gates plus available matching skills; follows artisan's model with max thinking by default.",
-	},
 };
 
 export function agentProfile(name: string): AgentProfile | undefined {
@@ -143,8 +132,7 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 
 export const FIRST_RUN_SETUP_HINT =
 	"Run /subagents-setup to choose enabled roles, models, and thinking levels. " +
-	"Sentinel follows artisan's model by default and requests max thinking; scout and steward can use efficient models. " +
-	"Scout maps code or researches external sources, artisan owns the primary change, steward cleans broad final diffs, and sentinel reviews after cleanup before every commit.";
+	"Scout maps code or researches external sources, artisan owns the primary change, and steward cleans broad final diffs.";
 
 export function getConfigPath(agentDir: string = getAgentDir()): string {
 	return join(agentDir, CONFIG_FILE_NAME);
@@ -181,15 +169,21 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 
 	if (Array.isArray(raw.enabledAgents)) {
 		const names = raw.enabledAgents.filter(
-			(name): name is string => typeof name === "string" && name.trim().length > 0,
+			(name): name is string =>
+				typeof name === "string" &&
+				name.trim().length > 0 &&
+				!RETIRED_AGENT_NAMES.has(name.trim()),
 		);
 		// An explicitly empty array is honored; duplicates collapse.
 		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
 	}
 
-	const rawKnownAgents = Array.isArray(raw.knownAgents) ? raw.knownAgents : PRE_SENTINEL_AGENT_NAMES;
+	const rawKnownAgents = Array.isArray(raw.knownAgents) ? raw.knownAgents : INITIAL_AGENT_NAMES;
 	config.knownAgents = [...new Set(rawKnownAgents.filter(
-		(name): name is string => typeof name === "string" && name.trim().length > 0,
+		(name): name is string =>
+			typeof name === "string" &&
+			name.trim().length > 0 &&
+			!RETIRED_AGENT_NAMES.has(name.trim()),
 	).map((name) => name.trim()))];
 	for (const name of config.enabledAgents) {
 		if (!config.knownAgents.includes(name)) config.knownAgents.push(name);
@@ -198,7 +192,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 	if (isRecord(raw.agentModels)) {
 		for (const [rawKey, value] of Object.entries(raw.agentModels)) {
 			const key = rawKey.trim();
-			if (key !== "" && isModelReference(value)) {
+			if (key !== "" && !RETIRED_AGENT_NAMES.has(key) && isModelReference(value)) {
 				config.agentModels[key] = value.trim();
 			}
 		}
@@ -209,6 +203,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 			const key = rawKey.trim();
 			if (
 				key !== "" &&
+				!RETIRED_AGENT_NAMES.has(key) &&
 				typeof value === "string" &&
 				(THINKING_LEVEL_VALUES as readonly string[]).includes(value)
 			) {