@howarewoo/pi-subagents 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [0.1.1]
+
+### Scoped npm package
+
+- Rename the npm package from `pi-extended-subagents` to `@howarewoo/pi-subagents`. The GitHub repository and production entrypoint are unchanged; the package rename does not change runtime behavior.
+- To prevent duplicate extension loading, run `pi remove npm:pi-extended-subagents`, then `pi install npm:@howarewoo/pi-subagents`, and restart Pi after active tasks finish.
+- Tested host remains Pi 1.5.2; requires Node 22.19 or newer. Shutdown or reload aborts and drains active children rather than migrating them.
+
+### Subagent terminology and command migration
+
+- Standardize current UI and documentation on Subagent Hub, Subagent Profiles and one-word subagent terminology.
+- Replace `/agent-hub`, `/task-profiles`, `/task-status`, `/task-steer` and `/task-stop` with `/subagent-hub`, `/subagent-profiles`, `/subagent-status`, `/subagent-steer` and `/subagent-stop`, respectively. Update saved instructions and command invocations; the old commands are not registered as aliases.
+- Delegation APIs, permissions, lifecycle and control behavior are unchanged.
+
+## [0.1.0]
+
+Initial versioned release.
+
+- Delegate single assignments and ordered batches through `delegate_task` and the native `subagent` interface.
+- Use explicit role, tool, skill, model and nesting grants, with parent-owned permission hooks.
+- Follow, steer and stop work in Agent Hub, with live transcripts and generation-pinned controls.
+- Validate structured results and retain per-generation transcripts and artifacts.
+- Serialize model-tool writers and abort/drain children when the parent shuts down or reloads.
+
+### Compatibility and lifecycle
+
+Tested against Pi 1.5.2; requires Node 22.19 or newer. Other Pi versions are not yet verified.
+Only one extension providing `subagent` should be loaded. Updating does not migrate active tasks:
+let them finish before updating, then restart Pi. Shutdown or reload aborts and drains children.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Woo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,329 @@
-# Temporary Holding Version
+# @howarewoo/pi-subagents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Delegate work to subagents in Pi, follow their progress, and steer or stop them from Subagent Hub. Subagents use your selected model by default, with their own assignments and explicit tool grants.
+
+![Terminal illustration of Subagent Hub with a four-task list on the left and the selected Reader alpha conversation on the right, including a native read-tool result containing synthetic input.](docs/images/subagent-hub.svg)
+
+_Subagent Hub: tasks and conversations side by side, with a full-width rule above the footer. Illustrated with synthetic demo data._
+
+## Installation
+
+Requires Node 22.19+; tested against Pi 1.5.2. Other Pi versions are not yet verified.
+
+Install from npm:
+
+```sh
+pi install npm:@howarewoo/pi-subagents
+```
+
+### Migrate from the old package
+
+If you installed `pi-extended-subagents`, remove it before installing the scoped package
+so Pi does not load the extension twice:
+
+```sh
+pi remove npm:pi-extended-subagents
+pi install npm:@howarewoo/pi-subagents
+```
+
+Use only one source. When switching from Git to npm, remove the Git registration first with
+`pi remove git:github.com/howarewoo/pi-extended-subagents`. The Git repository has not moved;
+`pi install git:github.com/howarewoo/pi-extended-subagents` remains an alternative.
+
+Restart Pi and run `/subagent-profiles` to check the installation. If you already installed a local checkout, remove that registration first with `pi remove /path/to/pi-extended-subagents` to avoid loading it twice.
+
+## Updates and rollback
+
+Let active subagents finish before updating, then restart Pi. Shutdown or `/reload` aborts
+and drains children; active tasks are not migrated to the new version. There is no extension-owned
+auto-updater.
+
+```sh
+# Update an unpinned npm installation
+pi update npm:@howarewoo/pi-subagents
+
+# Or update all installed extension packages
+pi update --extensions
+```
+
+Plain `pi update` updates Pi itself, not installed extension packages. For a Git installation,
+use `pi update git:github.com/howarewoo/pi-extended-subagents`; an unpinned Git source tracks
+the repository's default branch, including unreleased commits.
+
+For a reproducible npm installation or rollback, select an exact published version:
+
+```sh
+pi install npm:@howarewoo/pi-subagents@0.1.1
+```
+
+For Git, select a published tag, for example
+`pi install git:github.com/howarewoo/pi-extended-subagents@v0.1.1`.
+Exact npm versions and Git tags stay pinned; updating does not advance them to the next release.
+Install a different version explicitly to change the pin.
+
+[CHANGELOG.md](CHANGELOG.md) lists user-facing changes and migrations. Pi shows new package
+changelog entries on the next fresh launch after a version increase. See the
+[maintainer release guide](docs/releases.md) for publishing and recovery.
+
+## Feature comparison
+
+Compared with two community alternatives using their documentation, checked on 2026-11-11. This is a feature comparison, not a performance or reliability benchmark. UI cells name documented surfaces; they do not imply other features are absent.
+
+| Feature                  | @howarewoo/pi-subagents                                          | [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents) | [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents) |
+| ------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Background tasks         | Until parent exit or reload                                      | ✓ Supported                                                           | ✓ Supported                                                         |
+| Nested delegation        | Opt-in; foreground only                                          | Opt-in                                                                | Opt-in                                                              |
+| Task list / conversation | Subagent Hub: split panes; full-width thread on narrow terminals | Fleet inspector: roster and output pane                               | FleetView opens a separate conversation viewer                      |
+| Message / tool rendering | Native Pi message and tool components                            | Structured Markdown/tool transcripts                                  | Markdown + session-registered tool renderers                        |
+| Live follow / scrollback | ✓ Scroll up to pause; End to follow                              | ✓ Scroll away to pause; bottom resumes                                | ✓ Scroll up to pause; End to follow                                 |
+| In-UI task controls      | Hub: steer, inbox, stop, wait, park                              | Inspector: steer/follow-up and stop async runs                        | Viewer: steer, stop, foreground-to-background handoff               |
+| Tool / usage inspection  | Tools: sanitized arguments/results; Details: direct usage        | Expandable tool details + token counts                                | Expandable tool output + tokens; optional cost                      |
+| Schema-validated results | ✓ Supported                                                      | ✓ Supported                                                           | Workflow agents only                                                |
+| Managed Git worktrees    | — Not supported                                                  | ✓ Supported                                                           | ✓ Supported                                                         |
+| Workflow scripts         | — Not supported                                                  | ✓ Supported                                                           | ✓ Supported                                                         |
+| Scheduled runs           | — Not supported                                                  | ✓ Supported                                                           | Session-scoped agents only                                          |
+
+Sources: [our contract](docs/delegation-contract.md); nicobailon's [README](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/README.md), [agents](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/agents.md), [workflows](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/workflows.md) and [observability](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/observability.md); tintinweb's [README](https://github.com/tintinweb/pi-subagents/blob/8df7fa7d8e8130151a8fbfa991a1d3fa6b443739/README.md) and [workflows](https://github.com/tintinweb/pi-subagents/blob/8df7fa7d8e8130151a8fbfa991a1d3fa6b443739/docs/workflows.md).
+
+## Native orchestration
+
+Pi discovers the native `subagent` tool at startup through its tool description and coding-worker guidance; no enable call is needed. For replacement use, load only one extension providing `subagent`: Pi uses the first registration, not an automatic provider preference. Switching providers does not migrate or remove old runs.
+
+```json
+{
+  "agent": "worker",
+  "task": "Implement the approved change; follow the supplied repository guidelines and task references",
+  "cwd": "/absolute/path/to/task-worktree"
+}
+```
+
+`worker` uses the configured `implementation` profile. `scout`, `review` and `general` are also available. Calls are async by default and wake the parent after drain; set `async:false` to wait. Batches use `tasks:[{agent,task,cwd?}]`. Use the returned `id` with `action:"status"`, `"steer"`, `"stop"` or `"resume"`; steer/resume also need `message`.
+
+The coordinator supplies an existing workspace and the complete handoff, including accessible skill/reference paths. The extension does not create or manage worktrees. This is the [supported orchestration interface](docs/delegation-contract.md#native-orchestration-compatibility), not compatibility with every competing workflow script or custom agent definition.
+
+## Use delegation
+
+Choose a model through Pi's `/login` and `/model` setup. Delegation uses that provider and may incur charges; it does not automatically switch to a cheaper model.
+
+Ask Pi:
+
+> Use delegate_task with profile scout to locate the startup lifecycle code and report source locations. Run it in the foreground.
+
+The corresponding tool call is:
+
+```json
+{
+  "assignment": "Locate startup lifecycle code and report source locations",
+  "profile": "scout",
+  "background": false
+}
+```
+
+Or submit a batch:
+
+```json
+{
+  "tasks": [
+    { "assignment": "Locate startup code", "profile": "scout" },
+    { "assignment": "Review lifecycle tests", "profile": "review", "limits": { "requests": 20 } }
+  ],
+  "background": false
+}
+```
+
+The default is 16 concurrent tasks, a 32-item queue and up to 16 tasks per batch. Every item passes preflight before any starts. One failed task does not cancel its siblings.
+
+`scout` and `review` allow up to `read`, `grep`, `find` and `ls`. `general` and `implementation` also allow `write`, `edit` and `bash`. Each role receives only the builtins already callable in the parent. With Pi's default tools, scouts get `read` only. Tool calls retain the parent's permission hooks; incompatible tool overrides are rejected.
+
+`general` also inherits the parent's available skills, not its instructions or conversation history. Its existing role prompt and supplied assignment remain intact. Operator/trusted-project configuration can narrow inheritance with `tools` and `skills` (explicit `[]` removes grants). General can write when its inherited builtin set includes writing tools.
+
+Non-builtin inheritance is **restricted**: the operator may set `general.leafTools` to exact reviewed extension/MCP tool names in `delegation.json`. This is an assertion that the trusted implementation is a leaf: it never calls other Pi tools or changes the tool/model/session loadout. Unknown tools are denied, not automatically trusted from their descriptions or annotations. Declared reaching tools, codemode, tool search, owned delegation controls, hidden/model-only tools, and builtin replacements are never forwarded this way. Leaf tools are denied when child cwd differs from root cwd; only builtins have a workspace adapter. All admitted leaf tools conservatively require the global writer lease. See [restricted inheritance](docs/delegation-contract.md#restricted-general-inheritance) for the trust boundary and diagnostics.
+
+Foreground calls return the final results. Set `background:true` to return immediately and receive one ordered completion message after the batch drains. Use the returned task ID and generation for controls:
+
+```text
+/subagent-profiles
+/subagent-status
+/subagent-status <id> <generation>
+/subagent-steer <id> <generation> <text>
+/subagent-stop <id> <generation>
+/subagent-hub
+```
+
+## Subagent Profiles
+
+Run `/subagent-profiles` to inspect the resolved profiles for the current workspace: bundled definitions, operator `delegation.json`, then trusted-project narrowing. It opens a read-only list/details overlay, not an editor. Reopen it after configuration changes to refresh the snapshot.
+
+Use ↑/↓ to select a role; j/k, PgUp/PgDn and Home/End scroll details; Esc closes (configured selection bindings also apply). Narrow terminals stack the list above details; tiny terminals ask you to resize. Details show the description, prompt, builtin tool ceiling, exact skill paths, spawn/coordination ceilings and model/prewalk policy.
+
+**Ceilings are not callable tools.** Pi's command context has no callable-tool dispatcher, so the viewer reports effective tools as unknown rather than treating active declarations as executable grants. Admission performs the real intersection and remaining checks; inspect a task's `tools` in `/subagent-status` or Hub Details. RPC, JSON and print modes retain the structured `{toolPolicy, profiles}` message instead of opening an overlay. Invalid configuration or missing/invalid granted skills fails resolution, as at admission.
+
+![Native-renderer illustration of Subagent Profiles with a synthetic role list and selected general profile details.](docs/images/subagent-profiles.svg)
+
+_Synthetic native-component output; not a terminal screenshot or live-provider verification._
+
+## Subagent Hub
+
+Subagent Hub shows the subagent list beside the selected conversation, using Pi's native message and tool rendering. On narrow terminals, the conversation takes the full width. A border-colored horizontal rule separates the conversation and task list from the visible footer; it is omitted when the footer is hidden at tiny sizes. Details includes results, artifacts, grants and usage; Tools shows full sanitized arguments and result text.
+
+The thread follows new output until you scroll up. Press End to follow again. The pinned Subagents widget appears after the first task starts. Closing Subagent Hub does not stop the work.
+
+These illustrations use native renderer output with synthetic data modeled on the [offline fleet demo](examples/controlled-fleet.ts); they are not terminal screenshots.
+
+![Terminal illustration of the pinned Subagents widget showing four tasks: two running, one queued and one cancelled, with a live activity preview and model-tool writer warning.](docs/images/subagent-widget.svg)
+
+_Pinned Subagents widget: task counts and recent activity stay visible above the editor._
+
+| Key                   | Action                                            |
+| --------------------- | ------------------------------------------------- |
+| ↑ / ↓                 | Select a subagent or historical generation        |
+| j / k                 | Scroll down / up one line                         |
+| Ctrl+u/d or PgUp/PgDn | Scroll a page                                     |
+| Home / End            | Top / latest output                               |
+| Tab                   | Switch between thread, details and tools          |
+| /                     | Filter the subagent list                          |
+| s / m                 | Steer / send an inbox message                     |
+| x, then y             | Stop the selected subtree; Enter does not confirm |
+| w / p                 | Wait briefly for an outcome / park an idle task   |
+| Esc                   | Cancel input or close the Hub                     |
+
+Mouse-wheel scrolling works in fullscreen mode. In regular mode, use the keyboard controls because the terminal owns mouse scrollback. Actions stay pinned to the original task and generation; controls refuse to submit if the window cannot show the full target.
+
+## Messages and follow-up work
+
+Use `delegate_coordinate` to message a running subagent, wait for an outcome or assign follow-up work. Include it in any explicit tool allowlist alongside `delegate_task`.
+
+```json
+{"action":"message","target":{"id":"<task-id>","generation":1},"text":"Check the shutdown path too","mode":"steer"}
+{"action":"wait","target":{"id":"<task-id>","generation":1},"timeoutMs":30000}
+{"action":"followup","target":{"id":"<task-id>","generation":1},"assignment":"Now review the cancellation path"}
+```
+
+Each line is a separate call. An accepted or queued message is not a delivery confirmation; even a delivered receipt does not prove the model understood it. Follow-ups start a new generation without replaying the old conversation, so include the context it needs. Follow-up and revival are model-tool operations, unavailable directly in Subagent Hub. Child messaging is off until explicitly granted. See the [coordination reference](docs/delegation-contract.md#live-parent-messaging-waits-and-presence).
+
+### Task files and structured results
+
+Use `taskFile` instead of `assignment` to read instructions from a workspace-relative text file. Add `resultSchema` when you need a validated JSON value:
+
+```json
+{
+  "taskFile": "tasks/review.txt",
+  "profile": "review",
+  "resultSchema": {
+    "type": "object",
+    "properties": { "summary": { "type": "string" } },
+    "required": ["summary"],
+    "additionalProperties": false
+  }
+}
+```
+
+Task files must be regular UTF-8 files of 1 to 50000 bytes, outside hidden paths and `node_modules`. Reads use the parent's permission hooks. Schema-required children call `submit_result({value:...})`; missing or invalid results fail visibly. See [supported schemas](docs/delegation-contract.md#required-structured-results) and [task-file checks](docs/delegation-contract.md#checked-task-file-input).
+
+## Configuration
+
+No configuration is needed for the bundled roles. To change prompts or narrow tools, use `~/.pi/agent/delegation.json`:
+
+```json
+{
+  "review": {
+    "tools": ["read", "grep"],
+    "skills": ["/absolute/operator-reviewed/review/SKILL.md"],
+    "prompt": "Review this assignment and report concrete findings with source locations."
+  }
+}
+```
+
+All bundled profiles may delegate to `scout` and `review` by default, within a total depth of two (root 0, child 1, grandchild 2). Other nested targets and child messaging need explicit operator grants. Set `spawn: []` to revoke nesting. General inherits available parent skills; other roles need explicit skill grants. Trusted project configuration in `.pi/delegation.json` can narrow grants, never expand them. Children do not load ambient extension/MCP runtimes or context files; general can forward only the reviewed leaf tools described above.
+
+Each task defaults to a 10-minute deadline, 100 model requests and 100 tool calls. Cancellation waits for actual tool/provider drain, so a deadline cannot forcibly end unresponsive code. See [limits and nesting](docs/delegation-contract.md#capacity-and-bounded-execution), [Subagent Profiles](docs/delegation-contract.md#subagent-profiles-and-explicit-spawn-grants), and [exact model selection and prewalk](docs/advanced-policies.md).
+
+## Shared checkout and lifetime
+
+Subagents use your checkout by default, or an existing directory selected by `cwd`. File paths and shell commands are explicitly adapted through the original parent permission hooks; hooks still run in the parent context and may deny the selected paths. Writing tasks serialize through one global model-tool writer lease, even across worktrees. It does not coordinate manually entered `!`/`!!` commands, external editors, other terminals, other Pi sessions or arbitrary extension JavaScript. Avoid conflicting edits while a subagent is writing. A supplied worktree is not an OS sandbox; there is no automatic copy/apply or cleanup.
+
+Work belongs to the live parent runtime. Shutdown or reload aborts and drains children; there is no restart recovery or cross-parent revival. Saved transcripts and results can contain sensitive task, tool and model output. Treat them like your main Pi transcripts.
+
+### Why worktrees are managed externally
+
+The separation is intentional: the extension owns subagent execution, coordination and UI; an external coordinator or worktree tool owns worktree creation, branch and base selection, integration and cleanup.
+
+Worktrees are supported and useful for subagent orchestration. Create a worktree externally or select an existing workspace, then pass its path as `cwd` for the assigned subagent, as in the [native orchestration example](#native-orchestration). Separate worktrees do not bypass the global model-tool writer lease or provide an OS sandbox. The extension does not automatically commit, apply changes or clean up worktrees.
+
+### Why workflows and scheduling stay external
+
+This package is a focused delegation method, not a general-purpose automation framework. It provides explicit assignments and grants, bounded execution, coordination, and inspectable results in Subagent Hub. Ordered batches and live coordination are supported orchestration features, distinct from workflow scripts and scheduled runs.
+
+Workflow scripting and scheduling can live in separate packages that compose the public delegation tools and own when and how to delegate within the live parent runtime. They need not be built into this subagent integration. This separation implies neither a new built-in integration nor automatic inheritance of workflows, tools or context, and does not promise compatibility with existing third-party packages.
+
+## Documentation
+
+- [Delegation contract](docs/delegation-contract.md): tools, permissions, lifecycle and storage.
+- [Advanced policies](docs/advanced-policies.md): models, prewalk and unsupported capabilities.
+- [Verification](docs/verification.md): checks, terminal evidence and known limits.
+- [Parity inventory](docs/parity-inventory.md), [provenance](docs/provenance.md), [third-party notices](THIRD_PARTY_NOTICES.md).
+
+## Local development
+
+From a source checkout:
+
+```sh
+npm ci --ignore-scripts
+npm run lint
+npm run format:check
+npm run typecheck
+npm test
+npm run exercise
+npm pack --dry-run
+npm run test:package
+```
+
+`npm run check` runs lint, formatting, typecheck, tests and the controlled SDK exercise.
+`npm run test:package` packs and installs the tarball in a temporary directory, then checks
+that Pi loads the production entrypoint and registers its tools. It needs registry access
+for runtime dependencies, does not use model credentials and leaves your Pi settings unchanged.
+
+Oxlint checks correctness rules; warnings fail the lint command. Control-character regexes are allowed in terminal rendering code and tests because they match ANSI escape sequences. Run `npm run lint:fix` for safe lint fixes and `npm run format` to apply Oxfmt formatting. Formatting skips the generated lockfile and the managed Pullfrog workflow.
+
+Load the production entrypoint with `pi -e /absolute/path/to/src/pi-extended-subagents.ts`. Tests and examples use controlled providers without credentials or live inference.
+
+### Offline CLI walkthrough
+
+Run this from the checkout in a disposable workspace. The controlled example deliberately starts a long background child; normal print-parent exit aborts it.
+
+```sh
+repo="$PWD"
+root="$(mktemp -d)"
+node_bin="$(command -v node)"
+mkdir -p "$root/home" "$root/workspace"
+(
+  cd "$root/workspace"
+  env -i PATH="$PATH" HOME="$root/home" PI_CODING_AGENT_DIR="$root/agent" PI_OFFLINE=1 \
+    "$node_bin" "$repo/node_modules/@earendil-works/pi-coding-agent/dist/bundle/cli.js" \
+    --offline --no-extensions --no-mcp --no-skills --no-prompt-templates \
+    --no-themes --no-context-files --tools read,grep,find,ls,delegate_task \
+    --session-dir "$root/sessions" -e "$repo/src/pi-extended-subagents.ts" \
+    -e "$repo/examples/controlled-parent.ts" -p 'delegate example' </dev/null
+)
+# Inspect only these new files before removing the temporary walkthrough root:
+find "$root/sessions/delegation" -name '*.jsonl'
+rm -rf -- "$root"
+```
+
+The child's JSONL records `stopReason:aborted`. Do not install the controlled example as a production provider. This checks the SDK lifecycle, not live-provider reliability.
+
+For the UI exercise, create `input.txt` in a disposable cwd. Run the local CLI with `--offline --no-extensions --no-mcp --no-skills --no-prompt-templates --no-context-files`, `-e /absolute/path/src/pi-extended-subagents.ts -e /absolute/path/examples/controlled-fleet.ts`, and tools `read,grep,find,ls,write,edit,bash,delegate_task,delegate_coordinate`. Enter `fleet example`, then `/subagent-hub`. `/fleet-theme dark` and `/fleet-theme light` switch themes. `fleet coordinate <JSON>` calls the coordination tool. The example writes `fleet-output.txt`; it is not loaded by the package manifest.
+
+### Saved output
+
+New files live under the parent session directory:
+
+```text
+delegation/<parent-session-id>/<task-id>/
+  agent/                     # scoped child runtime cache location, no copied credentials
+  transcripts/<new-id>.jsonl # actual SDK messages/tool results
+  result.txt                 # complete last-assistant text after drain (when referenced)
+  structured.json            # accepted JSON value, if supplied (when referenced)
+```
+
+Completed generations keep their own immutable files. New generations use `<task-id>-g<generation>/`. Old `extended-subagents-proof` data is left untouched and is not loaded or migrated. SDK hosts must emit the public shutdown lifecycle before disposal; bare `session.dispose()` does not perform that cleanup.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,25 @@
+# Third-party notices
+
+The complete-resource-loader shape in `src/coordinator.ts` is adapted from Pi 1.5.2’s `examples/sdk/12-full-control.ts` (earendil-works/pi, commit b4afdddf44e059c67ccf5097e5317d913521b470).
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/advanced-policies.md

@@ -0,0 +1,76 @@
+# Advanced policy support and capability boundaries (Pi 1.5.2)
+
+This is a capability ledger for operators and integrators, not a full-parity or readiness claim. OMP revision `eda28eff97cf7a352fd3057a03581be1686dbc7a` is a behavioral reference only. No OMP implementation, prompts, private Pi runtime, or pi-subagents runtime is loaded. The native orchestration compatibility surface is defined in the [delegation contract](delegation-contract.md#native-orchestration-compatibility), not a full competitor API port.
+
+## Exact model and reasoning policy — implemented
+
+Ordinary tasks still use the captured physical parent model, effort and public authentication adapter. No automatic cheap model, alias, fallback, catalog refresh or extra inference is introduced. Virtual selections remain unsupported.
+
+Only operator `<agent-dir>/delegation.json` can grant exact alternative selections, per bundled role:
+
+```json
+{
+  "implementation": {
+    "models": [
+      { "provider": "your-provider", "id": "planning-model", "effort": "high" },
+      { "provider": "your-provider", "id": "implementation-model", "effort": "medium" }
+    ],
+    "model": { "provider": "your-provider", "id": "planning-model", "effort": "high" },
+    "prewalk": { "provider": "your-provider", "id": "implementation-model", "effort": "medium" }
+  }
+}
+```
+
+These identifiers are illustrative; use exact models already configured in the public parent registry. This configuration authorizes potentially billable dispatch when the operator runs real providers. It does not provision models or accounts. `models` has at most 64 selections; each includes a provider, model ID and explicit effort (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). The model must actually support that effort and declare known finite positive context/output limits. Parent scoped-model effort pins also apply. No suffix parsing or silent effort coercion occurs.
+
+- Absent `models`: only the inherited physical parent selection, no explicit override. Present `models` is an allowlist, including for the inherited default: list the default pair/effort if it should remain usable. `[]` denies dispatch for that role.
+- Optional `model` sets the role's default. It requires a matching exact `models` grant. Optional task-item `model` has the same object shape and selects only a granted entry. Optional task-item `models` narrows the admitted exact allowlist (including `[]`); it cannot add entries and its ceiling remains in effect for descendants and renewal. It does not mint a grant or alter the parent.
+- Trusted project configuration may only narrow the exact operator list or choose a default from it. It cannot introduce an alternative effort. Untrusted project configuration is ignored.
+- Default descendants inherit their immediate parent’s actual selection, not the root’s different model. Every descendant selection and armed prewalk target must fit ancestor admitted authority. An ancestor without alternative grants permits only its actual selection. Renewal intersects current and previously admitted/request-narrowed grants; explicit request selections remain pinned. Removed alternatives cannot be restored by renewal. Ordinary inherited defaults revalidate the current physical parent on renewal.
+- Whole-batch preflight checks every selection/armed target, provider, public availability, configured auth, parent scope and supported effort before inserting any identity or creating directories. Actual asynchronous auth resolution can still fail after admission and is reported as failure, not fallback. Each next turn rechecks current operator/project and ancestor policy; each dispatch rechecks live public registry/auth/scope/effort before counting and forwarding it. Revocation never authorizes an additional direct request.
+- Snapshots name the actual current physical model and effort, not an invented role alias. SDK transcripts record real selections/responses. Direct request/token/cost telemetry belongs to that generation once, including both prewalk phases; parent and descendants are not charged again in an aggregate here.
+
+## Prewalk — implemented bounded builtin subset
+
+Pinned OMP `task/prewalk.ts` resolves a definition's opt-in. `session/prewalk.ts` runs the planning model first, then hands the **same conversation** to a target after the first completed granted builtin `edit`/`write` at the assistant turn boundary. This is not repository scanning or a context-file preloader.
+
+An explicit task-item `model` is an exact assignment contract: it **suppresses inherited role prewalk**, as pinned OMP `task/executor.ts` and `executor-exact-model.test.ts` require. Its snapshot reports `prewalk.status:"suppressed-exact"` when a role prewalk was configured; neither the dormant role default nor target needs to be available. Exact selection/effort and suppression survive followup/revival, with current grant/auth/scope checks and no role fallback. A future explicit task `prewalk` field is not supported and is rejected, not silently discarded. Role `model` defaults may still prewalk. A target already identical to the effective source/effort reports `no-op` and adds no planning nudge, switch or extra dispatch.
+
+The implementation above enables that one-way switch through operator `prewalk`, with both source and target independently admitted. It uses the awaited public extension `turn_end` and public `AgentSession.setModel` / `setThinkingLevel`; no internal agent state is rewritten. Like the reference's direct builtin predicate, the completed call can have an error result: handoff means an implementation call occurred, not proof a file changed. Bash is not a handoff trigger. There is no injected todo/plan file or extra forced model call. Independently written planning guidance is added only for configured prewalk.
+
+Only existing effective tools and explicitly selected skills/assignment text are visible. Reads still traverse root permission hooks and consume the existing tool budget. No ambient context, credentials, environment, repository prescan, old history or additional resource discovery is added. Source and target use the same finite request/tool/deadline limits and public model context/output limits. Invalid later batch targets cause no earlier speculative launches. Cancellation/drain retains the writer/permit; a cancelled write does not switch or dispatch the target. A completed handoff survives fresh-generation renewal as the target selection, without rearming; renewal is still a fresh session with no warm history replay.
+
+Excluded reference behaviors: auto-prewalk classifier/smol routing, todo gating, deep-plan/continuation/checklist prompt machinery, hidden plan-nudge removal, plan-yolo approval transport, device/MCP mutation tiers, fallback/context promotion/cache affinity, automatic task-reset source restoration and warm parked transcript revival. These are not silently simulated. The supported public builtin/one-way contract was reconciled with the coordinator before implementation.
+
+## Advisor — excluded from current product scope
+
+Advisor is excluded from the current product scope. It is not awaiting an owner contract, an automatic follow-on implementation or a current release gate. Explicit ordinary `review` delegation remains supported; no advisor implementation or substitute is provided. The investigation below is retained as reference evidence, not an implementation plan.
+
+OMP `advisor/runtime.ts` and `session/session-advisors.ts` implement a **retained incremental observer**, not an ordinary one-shot review task. They capture primary transcript deltas at turn boundaries even when cadence holds dispatch; retain an append-only advisor conversation/cursor; gate review cadence and catch-up; route `advise` notes differently during primary continuation versus terminal unwind; avoid advice-triggered self-review; retain separate cost/transcript state; and drain pending reviews/cards. Per-agent enablement is off independently of parent enablement. This implementation does not expose an advisor option or imply a configured advisor is active.
+
+Public Pi sessions can retain their own conversation over multiple prompts; owned subscriptions, `steer`/`followUp`, custom tools, abort and `waitForIdle` are real building blocks. Missing a method named advisor is **not** evidence that extension-owned observers are impossible. However, this registry currently finalizes/disposes each prompt assignment, closes descendant presence, and holds ordinary permits for waiting ancestors. For reference, a faithful retained observer would need a retained-observer admission/lifetime contract covering delta/context grant and redaction boundary, finite cadence/backlog/input/output/request caps, read-only `advise` authority and terminal delivery, direct generation accounting, capacity/depth reservation and rejection when no permit is free, writer ancestry and drain across primary terminal/renewal/shutdown. Those boundaries explain the reference capability; they are not pending requirements for the current product.
+
+A boundary-only one-shot review changes the product meaning and already overlaps `review` delegation. Current product scope excludes both advisor implementation and an advisor substitute; ordinary explicit review tasks remain available on their own terms. No observer service, invisible side billing, extra calls, new queue or implicit overcommit was implemented.
+
+## Production isolation — deferred and unimplemented
+
+Filesystem isolation, automatic worktree management and copying/apply remain deferred. Existing caller-supplied workspaces are now supported through explicitly approved file-path and shell-cwd adaptation, preserving the original parent dispatcher and its hooks. Hooks see the actual transformed arguments, not a transparently rebound cwd. The public dispatcher still has no per-call cwd. This execution adapter and the global model-tool writer lease are not filesystem containment or an OS sandbox; see [the workspace contract](delegation-contract.md#explicit-working-directory).
+
+## Bounded investigations — not enabled
+
+| Capability                       | Public evidence and precise boundary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Disposition                                                                                                                                                                                                                                                                                                                                                   |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Completion probes                | OMP `task/completion-probe.ts` uses active-session `runEphemeralTurn`, same prompt/tools/history/cache, no transcript leaf change, bounded backoff and late cost capture. Pi 1.5.2 public `AgentSession` has no such method. Actual controlled busy-session `prompt()` rejects a second ordinary prompt without `steer`/`followUp`; those alternatives enter ordinary transcript/turn semantics. Public registry completion in a separate context is possible but does not establish ephemeral/cache/late-cost equivalence. | Unsupported as reference probes. No synthetic percentages, timer or extra inference.                                                                                                                                                                                                                                                                          |
+| Speculative launch               | OMP `task/speculative-launch.ts` requires host-authorized partial JSON object closure plus veto/approval/adoption/abort ownership. Pi provider/message streaming exposes deltas, but extension `tool_call` authorizes complete arguments, not an adopted speculative operation. The extension cannot infer future whole-batch approval from a closed prefix.                                                                                                                                                                | Parked: no authorized partial-argument seam proven. Existing atomic invalid-later batch behavior remains mandatory.                                                                                                                                                                                                                                           |
+| Worker/workpool                  | Public SDK can run in a Node worker/other host, but functions, public root dispatcher contexts and configured runtime/auth are not transferable automatically. OMP `task/workpool.ts` has persistent workers, item queues and incremental aggregate job yields; thread entrypoints additionally mirror host managers/resources. This package has finite in-process assignments, no admitted warm worker/workpool/backend/result contract.                                                                                   | Not implemented. Placement feasibility is not authorization to invent a worker pool, detached jobs or cloud backend.                                                                                                                                                                                                                                          |
+| Exact executable extension paths | Actual public `DefaultResourceLoader` with `noExtensions:true`, all other discovery disabled, in-memory settings and `additionalExtensionPaths:[exactSyntheticFile]` executes only that fixture module; hostile ambient project extension stays unloaded. Module code can write directly through Node before a model tool runs.                                                                                                                                                                                             | Public path loading supportable, **not a sandbox or inheritance grant**. Production still rejects `extensions`. A future exact canonical-file operator grant needs project/ancestor/revival intersection, exported registration/tool scope, lifecycle/shutdown and executable-code authority acceptance before enabling. No directory/package/glob discovery. |
+| MCP/resources                    | Public `createMcpExtension()` / `McpExtensionOptions.loadConfig` can select explicit server configs and an SDK resource loader can select skills/context files. Ordinary MCP startup otherwise discovers user/project configs and connects enabled servers. MCP tools/resources, executable transports, environment/auth interpolation, activation and shutdown have distinct authority contracts; extension path loading cannot grant them implicitly. No real server was connected or provisioned.                        | Production denies MCP/executable resources. Existing exact skills remain supported. No automatic environment/credentials copying. Exact server/resource grants and transport lifetime need owner reconciliation before implementation.                                                                                                                        |
+| Historical consultation          | Public `SessionManager.open`/branch/fork can read fresh synthetic transcripts (existing controlled SDK reopen tests); reopening is not read-only consultation or revival. OMP `task/seance-policy.ts` explicitly strips extensions/MCP/IRC/context/spawn/resources and separates historical evidence.                                                                                                                                                                                                                       | Historical source selection/access/redaction and consultation ownership unapproved. No retained sessions, old drafts or provider data scanned; no historical migration/mutation. Existing fresh-generation renewal intentionally reads no old history.                                                                                                        |
+
+Reference tests also include pinned `task/model-approval.test.ts`, `task/executor-prewalk.test.ts`, `task/parked-subagent-prewalk-revive.test.ts`, `subagent-advisor.test.ts`, `task/completion-probe-cost.test.ts`, `task/speculative-launch.test.ts`, `task/workpool.test.ts` and `task/seance-artifact-lifecycle.test.ts`; these are read-only reference evidence, not copied or executed upstream suites.
+
+The exact extension-path and busy-prompt counterexamples are in `test/advanced-capabilities.test.ts`; model/prewalk evidence is in `test/model-policy.test.ts`. These are controlled-provider actual SDK/runtime/filesystem observations, **not live provider inference, external billing/cache/auth reliability or OS isolation proof**. No test implies broader executable inheritance is authorized.
+
+## Joined fleet consumer
+
+The one registry still owns queued/setup/running/draining/terminal state, limits, identity/generation/history, artifacts and direct telemetry. The joined native fleet widget/cards/Hub display those alongside actual model/effort and prewalk armed/handed-off/suppressed-exact/no-op, immutable selected-generation history and separate presence. No inferred role fallback, subtree double billing, new provider call or advisor observer is added. Hub input/stop/message targets stay pinned to original UUID+generation. Native followup/revive remains model-issued only because Hub command context has no permission-preserving dispatcher. See the [supported surface table](delegation-contract.md#storage-and-fleet-observation). Explicit workspace path/shell adaptation is supported; production filesystem isolation/apply remains deferred and retained advisor is excluded from current product scope. Neither excluded advisor nor deferred filesystem isolation is a current release gate. Other unsupported/parked capabilities above remain explicit gaps, not implied support.