@oai404iao/pi-subagent 0.3.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ The design independently adapts the
 [DeepSeek Harness subagent seam](https://github.com/deepseek-ai/deepseek-harness/tree/4d03472cd098dc48a630e526ca620f4f37f18a0e/docs/subsystems)
 to Pi's extension and SDK APIs.
 
-Compatibility: Pi 0.84.2 or newer; tested against 0.84.2.
+Peer floor: Pi 0.85.1; tested against 0.85.1.
 
 > npm identity: `@oai404iao/pi-subagent`. Once the selected version is
 > available on npm, install it from npm; use a local checkout before its
@@ -15,21 +15,31 @@ Compatibility: Pi 0.84.2 or newer; tested against 0.84.2.
 
 - **Named providers**
   - `spawn`: fresh child with no parent conversation
-  - `fork`: one-shot child seeded through the parent's latest completed turn
-- **Two lifecycles**
-  - foreground one-shot runs return the child's final answer
-  - background continuable runs return a durable agent id immediately
-- **Foreground-only policy** that removes background scheduling and lifecycle controls
+  - `fork`: child seeded through the parent's latest completed turn
+- **Readable task paths** such as `/root/review/auth`, with relative addressing
+- **Explicit context inheritance**: `fresh`, `all_completed`, or
+  `last_n_completed`
+- **One scheduling mode per session** (`runtimeMode`)
+  - `foreground`: one-shot runs return the child's final answer
+  - `background`: continuable runs return a readable path and stable agent id
+    at prompt acceptance
+- **Foreground-only policy** that removes background scheduling and lifecycle
+  controls when `runtimeMode` is `foreground`
 - **Independent context and session** for every child
-- **Bundled presets without filesystem writes by default**, with opt-in
-  materialization, backup, and replacement
+- **User-owned agent catalog** with bundled templates used only for
+  first-install and package-version initialization
 - **Durable descriptors and lineage** stored in child JSONL sessions
-- **Cold resume** through `send_message`
+- **Durable mailbox protocol**: enqueue-only `send_message` plus explicit
+  `followup_task` turn starts
+- **Quiet durable completion updates** with event-driven `wait_agent`
 - **Control plane** with listing and interruption
-- **Child-to-parent `report` channel** for continuable children
+- **Child-to-parent `report` channel** for continuable children (quiet: it never
+  starts a parent turn)
 - **Nested delegation** with an absolute persisted depth limit
 - **Dynamic agent-name enums** generated from the effective user/project catalog
 - **Parallel-safe delegation**: multiple `subagent` calls in one assistant message may overlap
+- **Bounded background execution** with per-agent cold-resume serialization
+- **Optional idle runtime LRU** with transparent cold resume
 - **Composable tool ceilings** that preserve model/extension tool decisions
 - **Usage accounting, streaming progress, output caps, and custom TUI rendering**
 
@@ -57,18 +67,20 @@ For a temporary test:
 pi -e /absolute/path/to/pi-extensions/pi-subagent
 ```
 
-This implementation targets Pi `0.84.2`.
+Development and the supported compatibility floor are pinned to Pi `0.85.1`.
 
 ## Model-facing tools
 
 | Tool | Behavior |
 | --- | --- |
-| `subagent` | Starts a fresh child. Background continuable mode is the default unless configured otherwise; foreground-only mode always waits for the answer. |
-| `subagent_fork` | Starts a foreground one-shot child with the parent's completed-turn history. The in-flight tool turn is excluded. |
-| `send_message` | Sends the next FIFO turn to a direct continuable child; cold-resumes a persisted child when background execution is enabled. |
-| `interrupt_agent` | Requests cancellation of a live descendant's current turn without deleting its session. Active only when background execution is enabled. |
-| `list_agents` | Lists direct children or all descendants as `running`, `idle`, or `ready`. Active only when background execution is enabled. |
-| `report` | Child-only return channel. Installed automatically in continuable children. |
+| `subagent` | Starts a named child with selectable context inheritance. In `background` mode it is continuable and returns at prompt acceptance; in `foreground` mode it waits for the final answer. |
+| `subagent_fork` | Starts a child with all completed parent turns and uses the same session scheduling mode. |
+| `send_message` | Durably appends a message to a direct child's FIFO mailbox. It never starts or resumes the child. |
+| `followup_task` | Targets a direct child by path or id, atomically claims the pending FIFO batch, and starts one scheduled turn. |
+| `wait_agent` | Waits event-driven for unread direct-child completions without starting a model turn or consuming a scheduler slot. |
+| `interrupt_agent` | Requests cancellation of a live descendant by path or id without deleting its session. Active only in `background` mode. |
+| `list_agents` | Lists readable descendant paths as `running`, `idle`, or `ready`, including separate `pending=N` task and `updates=N` completion counts. Active only in `background` mode. |
+| `report` | Child-only return channel. Installed automatically in continuable children; the entry is recorded in the parent session without waking it. |
 
 The `/subagents` command shows the effective scheduling mode, available agent definitions,
 and the current descendant catalog.
@@ -92,52 +104,140 @@ Use subagent_fork with planner to plan the change using our completed discussion
 List my subagents, then send the scout a follow-up asking for exact call sites.
 ```
 
+In the default background mode, enqueue first and start explicitly:
+
+```text
+Send the scout two mailbox messages, then call followup_task once so it handles
+the current FIFO batch in one turn. Call wait_agent when the next action needs
+its quiet completion update.
+```
+
 Pi executes sibling tool calls in parallel, so this package deliberately accepts one delegation per `subagent` call instead of embedding a separate `tasks` array.
 
-## Agent definitions
+Every child follows the session's `runtimeMode`; there is no per-call background
+flag. Independent foreground calls still execute in parallel within one
+assistant message.
 
-The package includes `scout`, `planner`, `reviewer`, and `worker`. By default,
-these bundled definitions are read directly from the package. Startup does
-**not** create, replace, remove, or back up files in the Pi agent directory.
-`/subagents` reports those defaults as `(bundled)`.
+### Task paths and context
+
+Every new child has an immutable path rooted at `/root`:
+
+```text
+/root
+├─ review
+│  └─ auth
+└─ tests
+```
 
-User and project definitions can override the same names without modifying
-package files. Runtime locations and precedence are:
+Set `task_name` to choose the final path segment. Names use 1–64 lowercase
+ASCII letters, digits, hyphens, or underscores. If omitted, the extension
+slugs `description` and appends `-2`, `-3`, and so on to avoid sibling
+collisions. Explicit duplicate sibling names fail before child creation.
 
-1. bundled package definitions
-2. `<Pi agent dir>/agents/*.md`
-3. nearest trusted `.pi/agents/*.md`
+Control tools retain their existing parameter names for compatibility, but
+accept any of:
+
+- a durable UUIDv7 agent id;
+- an absolute path such as `/root/review/auth`;
+- a path relative to the caller, such as `auth`, `./auth`, or `../tests`.
+
+References cannot escape `/root`. Path lookup is resolved to the durable agent
+id before per-agent serialization; mailbox ownership, events, and durable
+lineage remain UUID-based. Direct-child restrictions still apply to
+`send_message` and `followup_task`, while `interrupt_agent` still requires a
+descendant. Paths do not bypass those checks.
+
+`subagent` accepts an optional context object:
+
+```json
+{
+  "task_name": "review",
+  "context": {
+    "mode": "last_n_completed",
+    "completed_turns": 2
+  }
+}
+```
 
-Project definitions replace user and bundled definitions with the same name
-when project scope is enabled. Project agents are disabled by the default
-`agentScope: "user"`. Setting the scope to `project` explicitly selects only
-project definitions; `both` loads bundled definitions, user overrides, then
-project overrides.
+Context modes are:
 
-When upgrading from a version that synchronized presets by default, unchanged
-previously managed files are recognized read-only and do not shadow newer
-package defaults. Edited managed files remain user overrides. The default
-never deletes or rewrites those existing files.
+| Mode | Initial child context |
+| --- | --- |
+| `fresh` | No parent conversation. This is the compatible `subagent` default. |
+| `all_completed` | The parent's compaction-aware context through its latest completed assistant turn. |
+| `last_n_completed` | The last `completed_turns` complete parent turns, bounded to 1–100. |
+
+The active assistant/tool-call suffix is always excluded. A compaction summary
+is retained when it is the only safe representation of completed history; if
+it prevents exact turn counting, `last_n_completed` keeps that summary only
+when fewer than the requested number of explicit completed turns remain.
+Context is copied once into a new child session. Descriptor, lineage, mailbox,
+completion, and other plain extension-state entries are not copied.
+
+`subagent_fork` is the compatibility shortcut for `all_completed` and follows
+the session's `runtimeMode` exactly like `subagent`: in `background` mode the
+fork is continuable and uses the same mailbox lifecycle as a fresh child.
+
+Every child persists descriptor version 4 with its task path, context policy,
+and `runtimeMode`. Descriptors written by earlier releases use retired
+scheduling switches and a background-protocol snapshot; they are **not**
+readable any more. Such sessions stay on disk but appear as a corrupt
+diagnostic in `list_agents` and cannot be addressed by path or id.
 
-### Opt-in managed preset synchronization
+## Agent definitions
 
-Set `syncBundledAgents: true` only if you explicitly want the package to
-materialize its bundled definitions into:
+The package ships `scout`, `planner`, `reviewer`, and `worker` as initialization
+templates. On the first extension startup after installation, and whenever the
+detected package version changes, those templates are materialized into:
 
 ```text
 <Pi agent dir>/agents/*.md
 ```
 
-With that opt-in, runtime discovery uses the managed user files rather than
-reading package copies directly, and `/subagents` reports built-ins as
-`(user)`. Synchronization behavior is then:
+The package copies are **never runtime agent definitions or fallbacks**.
+Runtime discovery reads only:
+
+1. `<Pi agent dir>/agents/*.md`
+2. nearest trusted `.pi/agents/*.md`
+
+Project definitions replace user definitions with the same name when project
+scope is enabled. Project agents are disabled by the default
+`agentScope: "user"`. Setting the scope to `project` selects only project
+definitions; `both` loads user definitions followed by project overrides.
+
+After the current package version has been initialized, the user directory is
+authoritative. Same-version startups do not restore missing files or refresh
+changed templates. If the user deletes every agent definition, the effective
+catalog is empty and delegation tools are inactive after restart or `/reload`.
+
+### Deleting a bundled preset
+
+Deleting a managed preset file is a durable decision, not a transient one:
+
+- every startup compares the manifest with the user agent directory; a managed
+  preset that is missing is recorded in `agents-manifest.json` as `retired`;
+- later package-version changes install **new** bundled presets but never
+  restore a preset you deleted;
+- presets that were never previously managed are still installed, and a preset
+  the user deleted before this version was first run is detected on the next
+  startup;
+- recreating the file (for example by copying a backup) makes it a managed
+  preset again; from then on an ordinary package-version change refreshes it
+  with a backup like any other existing preset;
+- deleting every preset leaves delegation tools inactive after restart or
+  `/reload`; run `/subagents` to see the effective catalog.
+
+Retirement is reported at startup (`deleted by you (not restored): ...`) and a
+name is dropped from the retirement list once it is no longer bundled.
+
+Initialization behavior:
 
 1. **First startup:** missing presets are installed. A different pre-existing same-name file
    is backed up before the bundled version replaces it.
 2. **Ordinary restart of the same release:** user edits are preserved.
 3. **Plugin update:** differing user presets are backed up, then replaced with the new
-   bundled versions. A bundled prompt hash change also triggers this refresh even if the
-   package version was not bumped.
+   bundled versions. Presets deleted by the user stay deleted. A bundled prompt
+   change without a package-version change does not trigger a refresh.
 4. **Retired preset:** a formerly bundled name is backed up and removed so an obsolete
    prompt does not remain silently active.
 5. Files whose names were never managed bundled presets are left untouched.
@@ -146,8 +246,10 @@ Synchronization holds a cross-process lock, then preflights and stages the whole
 before changing agent files. If a commit fails, it rolls back already-applied changes and
 fails extension startup rather than falling back to package prompts. Same-name symbolic
 links are preserved as symbolic links inside the backup directory before the user path is
-replaced. An invalid synchronization manifest is copied to a timestamped `.corrupt-*` file
-and startup fails closed until the manifest is repaired or deliberately removed.
+replaced. An invalid synchronization manifest is copied to a content-addressed
+`.corrupt-*` file and skips template initialization; user and project agent discovery
+continues with a warning. Repair the manifest, or deliberately remove it to request a new
+first-install initialization pass.
 
 Synchronization state and backups live at:
 
@@ -236,11 +338,10 @@ See [`config.example.json`](config.example.json) and [`config.schema.json`](conf
 {
   "$schema": "/path/to/pi-subagent/config.schema.json",
   "agentScope": "user",
-  "syncBundledAgents": false,
   "maxDepth": 3,
-  "enableRunInBackground": true,
-  "defaultBackground": true,
-  "reportDelivery": "wakeup",
+  "runtimeMode": "background",
+  "maxConcurrentBackgroundRuns": 4,
+  "maxIdleRuntimes": 0,
   "inheritExtensions": false,
   "openAIIdentity": false,
   "maxOutputBytes": 51200
@@ -250,17 +351,37 @@ See [`config.example.json`](config.example.json) and [`config.schema.json`](conf
 | Setting | Default | Meaning |
 | --- | --- | --- |
 | `agentScope` | `user` | Select user definitions, project definitions, or user definitions followed by project overrides. |
-| `syncBundledAgents` | `false` | **User-level config only.** Opt in to writing managed bundled presets into `<Pi agent dir>/agents`. `true` may install, replace, retire, and back up those files. |
 | `maxDepth` | `3` | Absolute delegation depth; a top-level Pi session is depth 0. |
-| `enableRunInBackground` | `true` | Enable continuable background children and their model-facing lifecycle controls. Set `false` for strict foreground-only mode. |
-| `defaultBackground` | `true` | Default scheduling for fresh `subagent` calls when background execution is enabled. |
-| `reportDelivery` | `wakeup` | `wakeup` starts/queues a parent turn; `quiet` waits for the parent's next turn. |
+| `runtimeMode` | `background` | The single scheduling switch. `background` starts continuable children and exposes their lifecycle tools; `foreground` waits for every child's final answer and removes those tools. |
+| `maxConcurrentBackgroundRuns` | `4` | Maximum continuable subagent turns executing at once in one extension runtime. Additional top-level runs wait in FIFO order; nested work fails at capacity instead of deadlocking its parent turn. |
+| `maxIdleRuntimes` | `0` | Process-wide LRU capacity for settled continuable runtimes. `0` preserves immediate unload; a positive value keeps the most recently used idle runtimes and transparently cold-resumes evicted paths. |
 | `inheritExtensions` | `false` | Load other Pi extensions in child runtimes. This package filters itself out; explicit agent tool ceilings still apply. |
 | `openAIIdentity` | `false` | For OpenAI Responses child models, inject only the named `pi-codex-minimal-tools` identity lifecycle inline. Codex Session/Thread/Turn/Window ids remain owned and serialized by that package. |
-| `maxOutputBytes` | `51200` | Cap for parent-visible foreground output, reports, and settlement notices. Full output remains in the child session. |
+| `maxOutputBytes` | `51200` | Cap for parent-visible foreground output, reports, and completion updates. Full output remains in the child session. |
 
 Invalid configuration and unknown child tool names fail loud before the child's first model request.
 
+### Migrating an existing configuration
+
+Earlier releases configured two booleans (`enableRunInBackground`,
+`defaultBackground`) plus a `backgroundProtocol` selector, and 0.2/0.3 added a
+`syncBundledAgents` switch. Every one of them is retired and is now rejected as
+an unknown setting, and the extension never rewrites a configuration file:
+
+| Retired key | Replace with |
+| --- | --- |
+| `enableRunInBackground: false` | `runtimeMode: "foreground"` |
+| `enableRunInBackground: true` (or absent) | `runtimeMode: "background"` |
+| `defaultBackground` | nothing; background children are always continuable |
+| `backgroundProtocol` | nothing; the durable mailbox is the only background protocol |
+| `syncBundledAgents` | nothing; template initialization is automatic |
+| `reportDelivery` | nothing; `report` never starts a parent turn |
+
+`reportDelivery` was removed together with the parent-wakeup path. A child
+`report` is appended to the parent session (so the parent model sees it on its
+next turn) and displayed in the TUI, but it never starts or queues a parent
+turn. Durable completion updates are read with `wait_agent`.
+
 `openAIIdentity` and `inheritExtensions` are independent. The former adds only
 the lightweight Codex identity lifecycle even when normal extension inheritance
 is disabled. Enable `inheritExtensions` as well when the child should receive
@@ -275,24 +396,23 @@ with an actionable missing-adapter error.
 
 ```json
 {
-  "enableRunInBackground": false
+  "runtimeMode": "foreground"
 }
 ```
 
 In this mode:
 
-- `subagent` always waits for the child's final answer, even when `defaultBackground` is `true`;
-- `run_in_background` is removed from the model-facing schema at session startup;
-- a forced `run_in_background: true` call is rejected before a child is created;
-- nested subagents inherit the foreground-only policy through the durable runtime snapshot;
-- `send_message`, `interrupt_agent`, and `list_agents` are removed from the active
+- `subagent` and `subagent_fork` always wait for the child's final answer;
+- no per-call background flag exists, so a child can never be created continuable;
+- nested subagents inherit the mode through the durable runtime snapshot;
+- `send_message`, `followup_task`, `wait_agent`, `interrupt_agent`, and `list_agents` are removed from the active
   model tool set, including inside nested children;
 - sibling foreground calls may still execute in parallel in one assistant message.
 
-`subagent_fork` is already foreground-only and is unchanged. The `/subagents` command
-remains available for human inspection of historical children, but persisted continuable
-children cannot be resumed until background execution is re-enabled. Run `/reload` or
-restart Pi after changing this setting so the active tool set and displayed schema are
+The `/subagents` command remains available for human inspection of historical
+children, but persisted continuable children cannot be resumed until
+`runtimeMode` is set back to `background`. Run `/reload` or restart Pi after
+changing this setting so the active tool set and displayed schema are
 refreshed.
 
 ## Lifecycle
@@ -313,42 +433,128 @@ The caller waits for one isolated child run. Only the child's last non-empty ass
 
 ### Continuable
 
-The start tool resolves at prompt preflight acceptance and returns the child's durable
-agent id (UUIDv7). Agent ids are independent of Pi session (file) ids: they are
+The start tool resolves at prompt preflight acceptance and returns the child's
+readable task path plus stable agent id (UUIDv7). Agent ids are independent of
+Pi session (file) ids: they are
 generated once per subagent, recorded in the child's session as `pi-subagent/agent`,
 and chained through `parentAgentId` in the descriptor, so children stay addressable
 even when a parent session is forked or re-created. When an activation settles:
 
-1. the runtime sends the parent a settlement notice with the stop reason and closing message;
-2. the child runtime is disposed once its owned descendants are done;
-3. its persistent session becomes `ready`;
-4. `send_message` can cold-resume that same session for another FIFO turn.
-
-A child can explicitly call `report` before settlement. Reports and settlement notices are separate by design.
-
-### Fork boundary
-
-The parent is executing a tool when `subagent_fork` starts, so its current assistant/tool-result sequence is incomplete. The provider copies only through the latest assistant message whose stop reason is not `toolUse`. This avoids seeding an invalid unbalanced tool turn.
+1. the child appends a quiet completion update to the direct parent's session;
+2. once owned descendants are done, the child runtime is either disposed or
+   retained in the optional idle LRU;
+3. an unloaded persistent session is `ready`; a retained settled runtime is
+   `idle`;
+4. `send_message` plus `followup_task` can cold-resume that same session for
+   another turn.
+
+A child can explicitly call `report` before settlement. A report is recorded in
+the parent session and never starts or queues a parent turn; it is a content
+channel that is separate from the quiet completion update.
+
+Continuable turns share a bounded scheduler. Calls targeting the same durable
+agent are serialized so concurrent messages cannot create multiple cold
+runtimes for one child session. Every scheduler-admitted run has a stable
+`turnId` in delegation details and the paired `pi-subagent:turn-start` /
+`pi-subagent:turn-end` events. FIFO follow-ups accepted while that
+`AgentSession` is already running remain part of the same admitted run.
+Existing `pi-subagent:start` / `pi-subagent:end` events continue to describe
+the wider activation lifecycle and now include `taskPath`.
+
+With `maxIdleRuntimes: 0`, disposal behavior is unchanged. A positive value
+retains only settled continuable runtimes with no active run, owned descendant,
+or pending mailbox claim. LRU accounting is serialized across concurrent
+settlements. Eviction disposes only the runtime; the descriptor, path, context,
+session history, task mailbox, and completion mailbox remain durable, so the
+next accepted turn cold-resumes normally.
+
+#### Mailbox protocol
+
+The mailbox separates delivery from execution:
+
+1. `send_message` appends a bounded message record to the direct child's JSONL
+   session and returns its stable message id. It does not create a runtime,
+   acquire a scheduler permit, create a `turnId`, or emit turn events.
+2. `followup_task` snapshots the current pending FIFO prefix, waits for the
+   normal background scheduler, and starts one turn containing that batch.
+   Messages arriving after the snapshot remain pending for a later turn.
+3. A claim is committed only after Pi prompt preflight succeeds. The durable
+   user-turn marker makes a claim without its corresponding prompt recoverable
+   after a crash. Once the user turn is durable, the batch is consumed even if
+   that model turn later fails or is interrupted.
+4. Scheduler rejection, cancellation while queued, and shutdown before prompt
+   acceptance leave the batch pending. Concurrent sends and starts for one
+   agent are serialized within the extension process.
+5. A completed turn appends a stable completion record to the direct parent's
+   separate notification mailbox before the child unloads. This custom entry
+   does not enter model context and does not wake or start the parent.
+6. `wait_agent` returns existing unread updates immediately or subscribes to
+   in-process mailbox activity and rechecks durable state after wakeup. Its
+   optional timeout defaults to 30 seconds and is capped at 120 seconds.
+7. A returned update becomes read only after Pi durably appends the successful
+   `wait_agent` tool result. An interrupted/failed delivery is released at the
+   end of the parent turn; a process restart also makes an orphan reservation
+   available again. Delivery output is bounded to a 256 KiB FIFO prefix.
+8. If the parent completion append fails, the child records an undelivered
+   fallback in its own session and emits `pi-subagent:completion-error` before
+   normal residency cleanup; no false completion is exposed to `wait_agent`.
+
+Each message is limited to 131,072 characters; a mailbox is limited to 256 pending
+messages and 256 KiB of pending UTF-8 content. `list_agents` exposes task
+`pending` and completion `updates` independently from lifecycle and scheduler
+state.
+
+FIFO follows durable append order after target resolution, not the invocation
+order of concurrent `send_message` calls. Each returned `pendingMessages` count
+describes that append. If one message must precede another, await the first send
+before starting the next.
+
+The durable mailbox is the only background protocol: `send_message` always
+enqueues and `followup_task` is always required to start the queued batch.
+
+`wait_agent` observes only completions written by the current agent's direct
+children. Nested parents consume their own child updates; a root wait does not
+steal grandchild updates. Nothing in this extension wakes a parent turn: work
+continues until the parent reads its mailbox.
+
+### Inherited-context boundary
+
+The parent is executing a tool when an inherited-context child starts, so its
+current assistant/tool-result sequence is incomplete. The provider projects
+Pi's active compaction-aware context only through a safe completed boundary,
+then copies model-facing entries into a new child session. This avoids seeding
+an invalid unbalanced tool turn and prevents parent control-log records from
+becoming child descriptors or mailbox ownership.
 
 ## Security
 
 - Extensions and subagents run with the user's OS permissions.
-- Opt-in `syncBundledAgents: true` synchronizes bundled presets into the user
-  agent directory and may create backups under
-  `<Pi agent dir>/.pi-subagent/backups`. The default does not write these
-  paths.
+- First-install and package-version initialization writes bundled templates
+  into the user agent directory and may create backups under
+  `<Pi agent dir>/.pi-subagent/backups`.
 - Project-local agents are repository-controlled prompts. They are loaded only when the project is trusted and configuration enables project scope.
 - `inheritExtensions` is disabled by default because loading an extension in a child executes its code and may duplicate external side effects.
 - Explicit agent tool lists are enforced as registry ceilings, but this controls model visibility and execution composition rather than providing an OS sandbox.
-- A child may send content only to its recorded direct parent through `report`; `send_message` likewise requires direct-parent identity.
+- A child may send content only to its recorded direct parent through `report`;
+  path resolution is only an address lookup, and `send_message` /
+  `followup_task` still require direct-parent identity.
 
 ## Current limitations
 
-- Activations and ownership are process-local; there is no cross-process lease or durable mailbox.
-- Pi does not expose stable inbox message ids, so control acknowledgements return the child id rather than a delivery id.
-- A process crash can lose a prompt accepted just before Pi writes it to the child JSONL; there is no durable mailbox for accepted-but-unlogged work.
+- Activations, scheduling ownership, and mailbox serialization are process-local;
+  two Pi processes must not concurrently control the same child session.
+- Readable-path reservation and idle-LRU accounting are process-local. Durable
+  UUID identity remains authoritative when multiple processes are involved,
+  which is still unsupported.
+- Resident parents still retain `ownedChildren` until descendants settle;
+  actor-graph residency, orphan handling, and background GC are not implemented.
+- Pi lazily creates a new child JSONL file on its first assistant entry. The
+  initial background agent id therefore has a crash window after prompt
+  acceptance; `send_message` waits for that first durable checkpoint before
+  acknowledging an enqueue.
+- A foreground child that is still being created has no mailbox; only
+  `runtimeMode: "background"` children accept durable messages.
 - `interrupt_agent` is fire-and-return and relies on Pi's current `AgentSession.abort()` queue behavior.
-- The fork provider is intentionally one-shot.
 - Structured-output delegation is not implemented yet.
 - Continuable starts require a persisted parent session; ephemeral (`--no-session`) parents can use foreground one-shot delegation only.
 - `subagent_fork` needs a persisted parent to copy completed history; before the first completed turn its safe prefix is empty and it behaves like a fresh child.
@@ -368,6 +574,5 @@ The test suite includes provider-boundary, descriptor, configuration, discovery,
 MIT © 2026 oai404iao. See [LICENSE](LICENSE) and
 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
-Managed global-preset synchronization is opt-in through
-`syncBundledAgents: true`; the default reads bundled definitions without
-writing user files.
+Bundled presets are initialization templates only. Runtime agent discovery is
+limited to user and trusted project configuration.

package/agents/worker.md

@@ -1,7 +1,7 @@
 ---
 name: worker
 description: General-purpose implementation agent with coding tools
-tools: read, grep, find, ls, bash, $mutation, subagent, subagent_fork, send_message, interrupt_agent, list_agents
+tools: read, grep, find, ls, bash, $mutation, subagent, subagent_fork, send_message, followup_task, wait_agent, interrupt_agent, list_agents
 thinking: high
 ---
 

package/config.example.json

@@ -1,11 +1,10 @@
 {
   "$schema": "./config.schema.json",
   "agentScope": "user",
-  "syncBundledAgents": false,
   "maxDepth": 3,
-  "enableRunInBackground": true,
-  "defaultBackground": true,
-  "reportDelivery": "wakeup",
+  "runtimeMode": "background",
+  "maxConcurrentBackgroundRuns": 4,
+  "maxIdleRuntimes": 0,
   "inheritExtensions": false,
   "openAIIdentity": false,
   "maxOutputBytes": 51200

package/config.schema.json

@@ -13,15 +13,14 @@
     },
     "agentScope": {
       "type": "string",
-      "enum": ["user", "project", "both"],
+      "enum": [
+        "user",
+        "project",
+        "both"
+      ],
       "description": "Select user definitions, project definitions, or user definitions followed by project overrides.",
       "default": "user"
     },
-    "syncBundledAgents": {
-      "type": "boolean",
-      "description": "User-level configuration only. Opt in to materializing bundled presets under the Pi agent directory. When true, startup may install, replace, retire, and back up managed agent files; when false, bundled definitions are read directly without writing user files.",
-      "default": false
-    },
     "maxDepth": {
       "type": "integer",
       "minimum": 0,
@@ -29,21 +28,28 @@
       "description": "Absolute delegation depth. A top-level Pi session has depth 0.",
       "default": 3
     },
-    "enableRunInBackground": {
-      "type": "boolean",
-      "description": "Enable continuable background children and their model-facing lifecycle controls. Set false for strict foreground-only mode.",
-      "default": true
+    "runtimeMode": {
+      "type": "string",
+      "enum": [
+        "foreground",
+        "background"
+      ],
+      "description": "Single execution mode. foreground waits for every child's final answer and exposes no lifecycle tools; background starts continuable mailbox-v2 children that return a readable path plus durable id.",
+      "default": "background"
     },
-    "defaultBackground": {
-      "type": "boolean",
-      "description": "Default run mode for the fresh spawn provider when background execution is enabled. Ignored in foreground-only mode.",
-      "default": true
+    "maxConcurrentBackgroundRuns": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "Maximum number of continuable subagent turns that may execute concurrently within one extension runtime.",
+      "default": 4
     },
-    "reportDelivery": {
-      "type": "string",
-      "enum": ["wakeup", "quiet"],
-      "description": "Whether child reports trigger a parent turn or wait for the parent's next turn.",
-      "default": "wakeup"
+    "maxIdleRuntimes": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Maximum settled continuable child runtimes retained in the process-wide idle LRU. Zero unloads immediately.",
+      "default": 0
     },
     "inheritExtensions": {
       "type": "boolean",
@@ -59,7 +65,7 @@
       "type": "integer",
       "minimum": 1024,
       "maximum": 1048576,
-      "description": "Maximum child output inserted into a parent tool result, report, or settlement notice.",
+      "description": "Maximum child output inserted into a parent tool result, report, or completion update.",
       "default": 51200
     }
   }

package/index.ts

@@ -0,0 +1,2 @@
+export { default } from "./src/index.js";
+export * from "./src/index.js";