@zihanw/pi-forge 0.5.3 → 0.5.5

package/docs/design/pi-forge-system-update-design-notes.md

@@ -0,0 +1,157 @@
+# Capabilities — accepted 0.5.5 design
+
+[Documentation](../README.md) · [Lean architecture](architecture-0.5.md) · [Roadmap](../development/roadmap.md)
+
+**Status:** implementation authorized, 2026-09-20; accepted 9/21 amendment incorporated. Functional source is delivered across all planned lanes: foundation codecs, human CLI core (`/capability`), plain metadata anchor projection, Web Session capabilities activity panel, live Preset bindings (`capabilities`) in dedicated peer Capability bindings tab with finite overrides and opt-in `modelCallable: true`, restricted model-callable Agent control (`forge_capability`), Web Capabilities surface CRUD with SDK-grouped tool picker and `sourceRevision` stale-save protection, custom default tools policy (`tools.initial`), guarded human Web activation picker (`GET /api/capability-state/available`, `POST /api/capability-state/enable`), and Pi 0.87 transcript/projection migration. Parent safeguards enforce raw source/revision coherence, external new-bindings stale-save protection, and lifecycle/re-entry fences (`disposed`, `lifecycleRevision`, `sameContext`). [Current reference](../reference/capabilities.md) states operational boundaries. Capabilities support `add`/`remove` only; candidate `only`/allowlist is not implemented. Parent build and full verification passed on Pi 0.87.0 (773 Node / 37 browser); development package version remains 0.5.4; release version bump decision pending between 0.5.5 or 0.6; repo dev SDK is pinned to `0.87.0` with peer range `>=0.87.0 <0.88.0` (no dual 0.86 support claim).
+
+This supersedes the [September 12 upstream-blocked proposal](archive/2026-09-12-system-update-design.md). Historical spike notes below reflect dated 0.86 exploration; current production architecture builds directly on Pi 0.87 APIs.
+
+## Ownership and bounded scope
+
+**Definitions are reusable; authorization belongs to Presets; active state belongs to Sessions.** Capabilities contain continuing collaboration/output guidance and optional tool selection changes. Skills remain the place for procedures, scripts and reference material.
+
+- Forge owns semantic events, activation snapshots, derived delivery anchors and request-only capability projection.
+- Pi owns ordinary transcript storage/branching, message protocols, provider encoding and actual tool execution. No fork or private `AgentSession` patches.
+- `ForgeWorkspace` remains the single resource-state owner. Existing codecs/repositories/catalogs are reused. The capability reducer is a pure view, not a second mutable workspace.
+- `tool-policy-runtime` remains the only Forge owner of executable tool selection. Text saying a tool is disabled is not enforcement.
+- CLI, restricted Agent tool and Web UI share one application service. No dynamic control-tool schema, new registry/framework/package entry point, arbitrary JSON Patch, inheritance chain, capability dependencies, automatic resource bundling, or general undo/redo.
+
+## Evidence behind the architecture
+
+An isolated Pi 0.86 `AgentSession`/extension-runner spike used fake models/tools and intercepted adapter payload assembly; no provider HTTP was sent by that harness. Nineteen assertions and a separate smoke passed, including assertions that intentionally reproduce integration failures. They are not nineteen production features passing.
+
+1. Keeping and mutating `before_agent_start.systemPromptOptions.sections` across a tool loop did not reliably synchronize later changes: the expected text sequence off/on/off became off/on/on while tools restored correctly. The command options getter was not a live-run setter.
+2. Returning Forge's current full `systemPrompt` invokes Pi's forced request projection after context hooks; it suppresses later native system updates. `customPrompt` is not an exact replacement because the cwd contribution remains.
+3. A Forge-owned marker/context projector worked in the sampled repeated toggle, native/user/native switch, branch/JSON reconstruction and manual-compaction scenarios. Those samples do not establish production crash recovery, automatic compaction, concurrency, old-Preset compatibility or tool-baseline recovery.
+4. `systemPromptOptions.sections` is a prompt-building input; `SystemMessage.sections` is still useful as a native request representation. Failure of the tested thin bridge does not prove every upstream integration impossible.
+5. `sendMessage` steering with explicit `triggerTurn:false` did not enter the next request in the tested live loop. Omitting it worked while streaming and did not start inference in the tested idle command. Context-hook exceptions alone are swallowed; explicit abort behavior must be accounted for.
+
+The implemented request-base bridge preserves compiled replacement strings while retaining foreign named sections and tool declarations. Built-in base text and selected-tool macros refresh when the executable set changes.
+
+**Production architecture:** management completely avoids transcript `sendMessage` and `custom_message` carriers, preventing dialogue contamination and spurious model turns. Under Pi 0.87, standard `context` hooks intentionally exclude System messages; Forge moves the entire compiler, base prompt replacement, and capability projection pipeline to `context_with_system` without an internal two-phase split. Delivery is anchored using plain `custom` session entries under the same delivery type (`pi-forge-capability-delivery`) carrying strictly cursor-only metadata (`{ schemaVersion: 1, throughEventId: string }`).
+
+- **Anchor persistence points:**
+  - **Idle:** persisted immediately upon `/capability` execution or synchronization.
+  - **Running session:** safely deferred while a tool loop is busy; anchors are never inserted between an in-flight tool call and its matching result.
+  - **On `agent_end`:** uncommitted pending anchors are committed after the assistant's final response when no Forge context failure or incomplete batch remains, before the next user turn.
+  - **Cycle reset on `agent_settled`:** while `agent_end` commits anchors, compile cycles and the busy fence reset only on `agent_settled`. This ensures `agent_before_settle` continuations preserve compiled Preset inputs and active capabilities across low-level runs.
+- **Context assembly via canonical projection:**
+  - Runtime, Preview, and anchor helpers build against Pi 0.87's `buildSessionProjection` (handling `context_edit` omissions, replacements, and `sourceEntry`). Raw session history on disk is never modified.
+  - `prepareCapabilityMessages` materializes before Preset compilation plain metadata anchors into ephemeral in-memory markers at their exact ordinal positions, verifying a unique ordered alignment against the canonical session projection.
+  - Incoming SDK leading System prompts always remain first; Forge's own prefix plain metadata anchors are inserted after it.
+  - `projectCapabilityMessages` then projects active capability deltas into native request-only `SystemMessage.sections` or fallback attributed timeline user messages.
+- **Decoupled UI notification:** UI status notifications (`ctx.ui.setStatus` and Web activity panel) are completely independent and never enqueue turns to the model.
+
+Preceding extension message rewrites (modifying messages in context hooks) are a legal and valid Pi SDK capability. However, Forge's anchor materialization requires a unique ordered alignment with canonical session entries. Content/protocol rewrites, inserted messages, non-custom omissions and ambiguous custom-message omissions fail closed. Prior full-System context extensions must move to `context_with_system`; `before_agent_start` forced System prompt injection continues to execute later in Pi's lifecycle; and final request arbitrary preceding rewrites still fail closed. Users may adjust conflicting extension order or extension behavior, but this is an operational suggestion only; Forge does not guarantee post-extension rewrite safety, nor can it guarantee generic plugin compatibility, prompt cache retention, warming, or automatic overflow handling. Upstream Pi metadata chunking and semantic-cut defects are NOT patched and remain unfixed upstream; legacy session carriers remain untouched, and Oh My Pi (OMP) is not supported or promised.
+
+The SDK queue exception is explicit: persisted custom messages can be absent from the current tool follow-up and have different live/persisted envelope timestamps. Compare full content/protocol fields, ignore only the regenerated custom timestamp, and permit custom-message omissions only when earliest/latest ordered alignments agree. Identical ambiguous omissions fail closed. Never rebuild/overwrite incoming context or reinsert omitted peer messages.
+
+## Resource and binding contract
+
+Discovered directories:
+
+- `.pi/forge/capabilities/*.json`
+- `~/.pi/forge/capabilities/*.json`
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "pi-forge.capability",
+  "id": "review",
+  "name": "Review",
+  "description": "Report findings and evidence before editing.",
+  "content": "List findings, evidence and risks. Do not directly edit files.",
+  "tools": {
+    "add": ["grep", "find", "ls"],
+    "remove": ["bash", "powershell", "write", "edit"]
+  }
+}
+```
+
+The definition has no Agent authorization. Content is literal text, not an executable template or file path. `name`/`description` are optional; omitted tool arrays normalize to empty arrays. At least non-whitespace text or one tool effect is required. Content is bounded to 100,000 characters, name to 1,000, each tool array to 256 names and each exact tool name to 128 characters. Tool names cannot contain whitespace, controls, `*` or `?`. Capabilities support `add` and `remove` only; candidate `only` or capability-level allowlists are not implemented. Unknown and malformed fields fail closed.
+
+Preset binding field:
+
+```json
+{
+  "capabilities": [{
+    "ref": "global:review",
+    "id": "review",
+    "modelCallable": true,
+    "overrides": {
+      "appendContent": "Also inspect backwards compatibility.",
+      "tools": { "add": ["grep", "find"] }
+    }
+  }]
+}
+```
+
+The `capabilities` field is live in the Preset schema and validated by codecs and editors.
+
+### Accepted 9/21 amendment: Tool selection and UX refinements
+
+- **Preset initial tools (`tools.initial?: string[]`):** Configures initial active tools for a preset using concrete valid tool names (no wildcards allowed). When omitted, legacy behavior is preserved (selective allow selects matching registered tools; unrestricted/deny retains or filters the session baseline). When set to `[]`, zero tools are active initially. The `allow`/`deny` ceiling remains authoritative and exclusive; tools blocked by policy produce validation errors. Extensions and mods register allowed inactive tools: if `initial` is set, dynamically registered tools remain inactive unless listed or added by an active capability. Configured defaults serve as the active base throughout preset activation (not a one-time reset per turn): disabling a capability or calling disable/reset restores these defaults plus remaining capabilities; disabling the preset restores the reconciled session baseline (including preserved external changes).
+- **Capability grouped picker:** The tool picker organizes tools using SDK `sourceInfo` (Pi built-in tools, packages, or top-level entry points). It saves exact concrete tool names: no package references are persisted, no packages are auto-installed, and newly added package tools are not auto-added. Inactive registered tools are visible in the picker; unloaded tools are unavailable in the session, but manual saved references are preserved.
+- **Preset bindings tab:** Preset bindings are relocated from Preset metadata to a dedicated peer **Capability bindings** tab (`bindings`). Overrides (content, tools add/remove) and source-effective preview are collapsed under an advanced toggle (`showAdvanced` / `hideAdvanced`).
+- **Default tools editor:** An opt-in, searchable, collapsible grouped picker in the Policy tab allows choosing default tools, while retaining advanced literal and wildcard allow/deny policy.
+- **Save execution behavior:** Saving a Capability in the Capabilities surface updates its library definition only and never activates it. Saving an inactive Preset updates disk bytes without selecting or activating it. Crucially, saving the currently active Preset reloads and syncs its live tool and capability authorization policy immediately in the session without replacing frozen active capability snapshots (UI docs accurately reflect this; never promise that all saves leave execution untouched).
+- **Compatibility and versioning:** Stacks using `tools.initial` require new Forge (older Forge ignores `initial`, not downgrade-compatible). Development remains in the 0.5.4 tree with release version bump pending (0.5.5 or maybe 0.6); host requirement remains Pi `>=0.87.0 <0.88.0` unchanged.
+- **Prompt caching:** On compatible Codex transports, first-time additions can preserve request prefixes if retained history contains no removals/redeclarations; this is not a cache-hit guarantee. Removals/re-additions use the full-current-tool fallback. No permission bypass or caching guarantees.
+
+- Direct library selection of a bare ID uses project-over-global. Invalid or duplicate local definitions do not fall back to global.
+- A bare Preset reference resolves in its owner's scope. A project Preset must explicitly write `global:<id>` to use a global capability; a global Preset cannot use project capabilities.
+- UI writes qualified references. Binding ID defaults to the referenced ID; duplicate effective binding IDs are rejected, including same-name cross-scope references unless explicitly disambiguated. At most 256 bindings per Preset.
+- Only `modelCallable: true` grants eligibility for the Agent control path; omission defaults to `false`. Current tool policy and registration still apply on every call.
+- Overrides allow `content` (replace) **or** `appendContent` (paragraph append with two newlines), never both. Each specified `tools.add`/`tools.remove` array replaces that entire field; the other field is preserved. Identity, name, authorization, and arbitrary fields cannot be overridden.
+- Base resources must validate before applying overrides; an override cannot repair an invalid source silently. Effective results are defensive snapshots.
+
+## Semantic events and snapshots
+
+The internal schema is persisted through existing `session-adapter`/Pi custom entries, not a new persistence backend. Semantic entries carry validated snapshots; delivery messages carry only a versioned event cursor. Baseline records belong to the existing tool-policy owner.
+
+Common event fields: `schemaVersion: 1`, `eventId`, `op`, `actor`, `createdAt` (finite nonnegative milliseconds). Branch order, not timestamps, determines reduction. Opaque event/activation IDs are at most 128 characters. Resource/Preset/binding IDs keep the existing grammar.
+
+- **activate:** actor `user` or `agent`, with an immutable `snapshot` containing `activationId`, `source`, optional name, content, normalized tool patch, and content fingerprint.
+- **deactivate:** targets an `activationId`; actor `user`, `agent` or `lifecycle`.
+- **reset:** user only. Clears current activity, not historical events.
+- Source is `{ kind: "manual" }` or `{ kind: "capability", key: { scope, id }, binding?: { preset: { scope, id }, id } }`.
+- Agent activation requires an authorized bound capability (`modelCallable: true`). Agent deactivation cannot close user-owned activations. Lifecycle deactivation is restricted to bound capabilities; it cannot clear manual or unbound user rules.
+- Unknown/repeated off is a no-op. Activation IDs cannot be reused within one branch even after reset/off. Repeated identical event IDs are no-ops without moving the latest event marker backwards; conflicting reuse fails closed.
+- Repeated `enable` is deduplicated and idempotent; it never performs an automatic owner takeover between user and agent. Takeover requires explicit deactivation and reactivation.
+- Malformed owned event data fails reduction with an index/error, never a partially restored active set. Unrelated Pi entries are filtered by the adapter, not fed as fake capability events.
+- Fingerprints use Forge's canonical `sha256:v1` algorithm. The payload is domain-tagged effective source/name/content/tools, excluding activation ID. It represents content identity, not a cryptographic signature.
+
+Snapshot content never drifts with source edits. Switching Presets appends deactivations for old bound activations while retaining manual and unbound user rules; reloading the same Preset retains immutable active snapshots. Revoked authorization does not retroactively erase active snapshots; human recovery via CLI or Web disable/reset is the recovery path.
+
+## Delivery, recovery, tools, and parent safeguards
+
+Derived plain `custom` metadata entries anchor delivery; they do not independently own active state, duplicate authoritative snapshot payloads, or pollute conversation dialogue. One semantic history supports both presentations:
+
+- Native: request-only `SystemMessage.sections` keyed by activation identity; off uses a null patch and Pi's existing removal wording, without an extra duplicate user notice.
+- Unsupported models: an attributed timeline user update/stop notice. Do not silently fold Forge capability updates into the leading prompt. Genuine user/tool content is never promoted to system authority.
+- Transform only clearly owned Forge rule content, never an entire mixed system message. Preserve unrelated content/sections and `toolsAdded`/`toolsRemoved` for Pi's adapters.
+- Compaction requires an owned current-state checkpoint derived from semantic events; suppress pre-checkpoint anchors, including retained-tail copies, then replay later deltas. Request-only sections are not automatically saved by Pi's raw transcript checkpoint. Checkpoint placement remains unchanged (precedes summary, follows leading system prompt); the upstream Pi metadata chunking bug is an independent issue and remains unfixed.
+- Compaction input characterization: in real SDK compaction, summarizers receive no metadata anchors and no Forge rule bodies (projection is request-only), while user, assistant, and peer dialogue are preserved. Simulated responses in test harnesses characterize request plumbing and harness shape, not remote LLM semantic compaction fidelity or summarizer compliance.
+- **Breaking pre-release rename boundary:** no legacy aliases or readers are provided for the former instruction-mode schema, directories, or capability state. Existing development configuration must be converted and continuing old sessions are unsupported; Forge does not rewrite old JSONL or historical summaries, so converted configurations require a new session.
+- Immediate tool synchronization vs. next-request prompt projection: admission validates text/reference/authorization/tool effects before commit. Executable tool policy synchronizes *immediately* (`sync()` / `setActiveTools()`), whereas prompt text and native sections or user updates take effect at the *next model request* boundary. Running tool batches are not interrupted.
+- Tool policy calculation: tools are computed from a recoverable baseline plus all remaining additions minus all remaining removals, subject to top-level Preset deny policy; removal wins globally across active capabilities. Additions must be registered and permitted by the active Preset.
+- Read-only resource discovery and Preview: inspecting capabilities, calling `GET /api/capability-state/available`, or inspecting the Preview dock never mutates tool policies, commits session events, or marks pending capabilities prepared.
+- Parent safeguards:
+  - Raw source and revision coherence: GET operations couple editable data and `sourceRevision` from the same raw file bytes.
+  - External new bindings stale save detection: Preset saves enforce `sourceRevision` checks whenever bindings are present or modified, rejecting stale overwrites (409 Conflict) if the file changed on disk (including externally added bindings).
+  - Lifecycle and re-entry fences: explicit `disposed` flag, `lifecycleRevision` increment, and `sameContext` verification prevent cross-session pollution or operations after session disposal.
+- Provider-managed cache warning: prompt caching, tool transport, and KV cache hits are downstream provider-managed. Stable prefixes may help caching, but schema changes, removals, fallback, base recompilation, model switches, and compaction alter cache boundaries; pi-forge provides no guarantees of zero KV invalidation or exact cache hits.
+- Human recovery: human CLI (`/capability disable`, `/capability reset`) and Web panel controls remain available; an Agent-owned capability cannot disable its own control path without a safe recovery policy.
+
+## Staged implementation and release gates
+
+1. **Foundation (verified):** JSON codec, finite overrides, scoped resolution, immutable snapshots, and strict event reduction.
+2. **Human CLI core and metadata anchor projection (implemented):** Pi 0.87 dependency upgrade, `context_with_system` full pipeline, `buildSessionProjection` canonical alignment, request-base bridge, scoped discovery, session event persistence, plain `custom` cursor-only metadata anchors (replacing transcript carriers), ordinal materialization, compaction checkpoints, and executable tool-policy coordination. Real SDK tests cover same-run toggles, native/fallback switches, fake tool execution, disk reopens, branches, crash-window baseline recovery, and legitimate preceding extension rewrite fail-closed safety.
+3. **Session activity UI and compaction characterization (implemented):** read/control view derived from the existing runtime, never a second state owner. Human disable/reset carries an exact session/leaf/revision guard with runtime-instance fencing; Web requires trust, pure reads never synchronize or infer, and stale pages cannot retry writes automatically. Real-SDK compaction-input characterization confirms Forge metadata and request-only rules are absent from summarizer history while user, assistant, and peer dialogue remain intact; fake test responses are plumbing characterization, not remote semantic validation.
+4. **Preset authorization and restricted Agent control (implemented):** live Preset binding schema (`capabilities`), opt-in `modelCallable: true`, and restricted fixed-schema `forge_capability` (list, status, enable, disable, ID ≤ 128 chars). Per-call trust, binding identity, authorization, and tool policy checks prevent privilege escalation. CLI additions `/capability bindings` and `/capability enable-bound <id>` provide human parity. Management operations do not initiate paid inference.
+5. **Capabilities library CRUD, binding editor, and guarded human Web activation picker (delivered in functional source):** dedicated **Capabilities** surface for project/global capability CRUD with `sourceRevision` stale-save guards; Preset metadata bindings editor with finite overrides and live source-effective preview; guarded human Web activation picker (`GET /api/capability-state/available`, `POST /api/capability-state/enable`) with pre-activation preview and session/leaf/revision plus content fingerprint validation. Parent safeguards enforce raw source/revision coherence, external new bindings stale-save detection, and lifecycle/re-entry fences.
+6. **Release closeout (pending release review and user authorization):** Pi 0.87 migration and accepted tool-selection/UX amendment passed parent build and full verification (773 Node / 37 browser). Development package version remains 0.5.4; release version bump decision pending between 0.5.5 or 0.6; repo dev SDK is pinned to `0.87.0` with peer range `>=0.87.0 <0.88.0` (no dual 0.86 support claim); release, git push, and host reload (`/reload`) are separate user-authorized actions.
+
+Acceptance includes old Presets, regex/history filtering, repeated same-run toggles, native/user/native transitions, request abort/retry/concurrency, explicit and automatic compaction, disk resume/branches/crash boundaries, baseline recovery, real tool-call rejection, external tool changes, warming, and payload/usage association.
+
+No universal native support, obedience, zero-KV-invalidation, or guaranteed cache-hit claims. No automatic legacy migration, no old summary rewrites, and no Pi split patch. Publishing, host upgrades, reloads, and deployment remain separate user-authorized actions.

package/docs/development/release.md

@@ -2,36 +2,36 @@
 
 [Documentation](../README.md)
 
-## Before release
-
-1. Confirm the changelog and user documentation describe the intended version and experimental surfaces accurately.
-2. Publish and smoke-test any required `@zihanw/pi-subagent-runtime` version first.
-3. Install dependencies from the lockfile and run `npm run verify`; require the
-   Ubuntu, macOS, and Windows GitHub Actions jobs to pass for the release commit.
-4. Test a packed installation against the documented minimum and current Pi versions.
-5. Exercise ordinary stack/profile use independently of delegation.
-6. Exercise both configured foreground backends and confirm unsupported host capabilities fail closed before provider transport.
-7. Inspect `npm pack --dry-run` for package size and unexpected or missing files.
-
-The macOS and Windows jobs run the same complete verification surface as Linux,
-including the real-browser editor suite against the hosted runner's system
-Chrome. Compatibility-version and scheduled latest-Pi probes remain Linux-only;
-they test dependency drift rather than operating-system behavior.
+## Independent packages
+
+The main `@zihanw/pi-forge` package has **no** dependency on `@zihanw/pi-forge-subagents` or `@zihanw/pi-subagent-runtime`. It can release independently; unfinished optional features do not block ordinary Forge use or a main-package release.
+
+The optional package is tested against the released Forge host before its own publication. Any required runtime version must be published and smoke-tested before publishing the optional package that depends on it. Backend, continuation, background-task, and nested-usage producer acceptance belong to that companion release, not to the main package.
+
+## Before main-package release
+
+1. Confirm the intended version in the manifest, lockfile, changelog, and current user documentation. Preserve historical release records and document breaking configuration/session boundaries.
+2. Install dependencies from the lockfile with `npm ci`, build, and run the complete `npm run verify` chain: Node tests, browser tests, types, generated client, docs, distribution, package contents, and packed installation.
+3. Require the Ubuntu, macOS, Windows, and configured Pi compatibility GitHub Actions jobs to pass for the **exact release commit**, not an earlier source revision.
+4. Test a packed main-package installation against both the documented minimum and current tested Pi versions; exercise ordinary Preset/Profile/Capability behavior independently of optional delegation.
+5. Inspect `npm pack --dry-run` for package size and unexpected or missing files. Publish the verified artifact, not an unreviewed working tree.
+
+The macOS and Windows jobs run the same complete verification surface as Linux, including the real-browser editor suite. Compatibility-version and scheduled latest-Pi probes remain Linux-only; they test dependency drift rather than operating-system behavior.
 
 ## Dependency policy
 
-Published manifests use wildcard peer dependencies for Pi-host-provided SDK packages. Exact versions belong in development dependencies and the lockfile so tests are reproducible without restricting compatible host releases.
+The four Pi SDK packages remain host-provided optional peers, never private runtime dependencies. Forge 0.5.5 requires Pi `>=0.87.0 <0.88.0`, with development fixtures pinned to `0.87.0`; `typebox` remains a wildcard optional peer. Pi 0.86 and future minor versions are not implicitly supported. Exact tested versions belong in development dependencies and the lockfile, not exact host-version requirements.
 
-`pi-subagent-runtime` remains a normal exact dependency until its compatibility policy says otherwise. Its own host-facing Pi dependencies must follow the same host-provided peer model.
+Published `@zihanw/pi-forge-subagents` 0.5.3 does not understand `tools.initial`. The upcoming optional package needs the matching fix and a Forge dependency floor of `^0.5.5` for the new command-contribution entry. This is a companion compatibility gate, not a requirement to publish the packages simultaneously. See the [host-port compatibility note](../reference/subagent-host-port.md#tool-selection-compatibility).
 
 ## Package contents
 
-The tarball must include compiled `dist/`, examples, the English and Chinese landing pages, changelog, license, and user/reference documentation. It must not include physical `src/` files. Both the default extension entry and experimental subagent entry must resolve to compiled output.
+The tarball must include compiled `dist/`, examples, the English and Chinese landing pages, changelog, license, and user/reference documentation. It must not include physical `src/` files. The root, `/subagent`, `/ui-contribution`, and `/command-contribution` entries must resolve to compiled output.
 
 The root `PUBLIC_API.md` and `SUBAGENT_ADAPTER_CONTRACT.md` files are compatibility pointers; authoritative content lives under `docs/reference/`.
 
 ## Publish and verify
 
-Publish the intended version/tag, then install it through Pi in a clean project. Verify `/preset`, `/profile`, `/preset ui`, and—when deliberately enabled—delegation. Restart Pi after installation to avoid testing a stale extension instance.
+With release authorization, publish the intended version using the intended tag (`latest` for a stable main-package release). Verify registry version, tag, and tarball integrity, then install the published package through Pi in a clean project and smoke-test the main commands and resource workflow without model inference.
 
-For a stable release, ensure npm `latest` points to the new version and any prerelease channel no longer leaves users on an incompatible older build.
+Do not silently move unrelated legacy or prerelease tags. Publishing is not a host upgrade: restart or reload a user's existing host only with that user's authorization, and start a new session when the release's migration notes require it. Keep release evidence separate from static documentation; a version bump or changelog entry alone is not proof of successful publication.

package/docs/development/roadmap.md

@@ -4,7 +4,22 @@
 
 This file contains forward-looking product work only. Completed capability belongs in the [feature inventory](../reference/features.md), release history in the root [changelog](../../CHANGELOG.md), and completed investigation in the [design archive](../design/README.md).
 
-## 0.5.0 breaking cleanup (lean)
+## Active 0.5.5: session capabilities
+
+Implementation is authorized under the [accepted capability design](../design/pi-forge-system-update-design-notes.md) and [lean-plan amendment](../design/architecture-0.5.md#accepted-055-amendment-session-capabilities). Pi 0.86 is released; the old upstream-blocked thin-sections proposal is superseded.
+
+One active lane at a time:
+
+1. **Foundation (verified):** strict capability/override codec, scoped binding resolution, immutable snapshots, and branch event reducer.
+2. **Human CLI core & metadata anchor projection (implemented):** Pi 0.87 dependency upgrade, request-base replacement, `context_with_system` full pipeline, `buildSessionProjection` canonical alignment, native/user projection, semantic events and plain `custom` cursor-only metadata anchors, durable tool baselines, repositories/ForgeWorkspace discovery, and `/capability` add/list/bindings/enable/enable-bound/disable/status/reset. See [current reference](../reference/capabilities.md).
+3. **Session observability & activity panel (implemented):** derived multi-capability state, actual selected tools, delivery status (`none`, `pending`, `prepared`), presentation indicators, and guarded human disable/reset; real SDK summarizer-input characterization.
+4. **Preset authorization & restricted Agent control (implemented):** live Preset binding schema (`capabilities`), opt-in `modelCallable: true`, and model-callable `forge_capability` tool with fixed list/status/enable/disable schema; per-call trust, binding identity, authorization, and tool policy checks; strict user-vs-agent ownership.
+5. **Capabilities library CRUD, Preset binding editor, and guarded human Web activation picker (delivered in functional source):** dedicated **Capabilities** surface for project/global capability CRUD with `sourceRevision` stale-save guards; dedicated peer Capability bindings editor with finite overrides and live source-effective preview; guarded human Web activation picker (`GET /api/capability-state/available`, `POST /api/capability-state/enable`) with pre-activation preview and session guard plus content fingerprint validation. Parent safeguards enforce raw source/revision coherence, external new bindings stale-save detection, and lifecycle/re-entry fences (`disposed`, `lifecycleRevision`, `sameContext`).
+6. **Main-package 0.5.5 release closeout:** The accepted UI and local full verification closed out on 2026-09-24 (`89c6ba2`); bilingual README B and reviewed continuous media are adopted. UI scope is frozen except for regressions/release blockers. The main package is versioned 0.5.5; publication requires the exact-commit CI and packed-install gates in the [release process](release.md). No paid provider matrix is implied. The optional package and runtime have independent unfinished release work and are not a main-package gate. Repo dev SDK remains pinned to 0.87.0 with peer `>=0.87.0 <0.88.0` (no dual 0.86 support claim).
+
+Existing README and optional Pet active-state changes are preserved. No host upgrade, reload or publication follows implicitly from local feature development. Foundation tests are not proof of live 0.5.5 behavior.
+
+## 0.5.0 breaking cleanup (lean history)
 
 0.5.0 is a deliberately breaking cleanup release plus the minimum foundation for 0.5.x. Net-new feature work is frozen.
 
@@ -78,7 +93,7 @@ Candidate history controls need concrete use cases and dangling tool-pair tests.
 - Skill filtering is model-visible prompt filtering, not an invocation or security boundary.
 - Delegation remains opt-in, foreground, clean-context, and fail-closed on missing capabilities, and lives in the optional package.
 - Do not report shared-user read-only policy as an OS sandbox.
-- New editor product workflows are frozen; migration changes retain real-browser coverage.
+- New editor workflows remain frozen except the explicitly accepted capability surfaces above; migration and new workflows retain real-browser coverage.
 - Run the full verification and package checks before release.
 
 The detailed completed 0.4 plan is retained in the [historical roadmap](../design/roadmap-0.4-archive.md).

package/docs/development/scoped-global-profiles-stacks.md

@@ -158,7 +158,7 @@ For compatibility:
 
 - Read legacy branch entries containing only `activeStackId` using effective lookup.
 - Write new entries with a scoped active-stack reference.
-- Preserve the explicit `none`/`off` selection as a scope-independent opt-out.
+- Preserve the explicit `none`/`disable` selection as a scope-independent opt-out.
 - Profile provenance should add the profile scope/key while continuing to accept older provenance that has only `profileId` and `sourcePath`.
 - Drift snapshots should store the resolved scoped stack reference so status can distinguish definition changes from a scope change.
 

package/docs/development/setup.md

@@ -55,7 +55,7 @@ Set `CHROME_PATH` when Chrome/Chromium is outside a standard location. CI runs t
 
 ## Pi compatibility
 
-Published pi-forge treats Pi-owned SDK packages (`pi-agent-core`, `pi-ai`, `pi-coding-agent`, `pi-tui`, and `typebox`) as host-provided wildcard peers. The running Pi host supplies one coherent SDK instance, avoiding duplicate packages and avoiding an install-time lock to Pi's frequent release cadence.
+Pi-forge treats Pi-owned SDK packages (`pi-agent-core`, `pi-ai`, `pi-coding-agent`, `pi-tui`, and `typebox`) as host-provided optional peers, not private runtime dependencies. The repository dev SDK is pinned to `0.87.0` and the peer requirement is `>=0.87.0 <0.88.0` for the four Pi SDK peers; `typebox` remains `*`. There is no claim of dual 0.86 runtime support. The running host supplies one coherent SDK instance, avoiding duplicate packages and exact-version locks while expressing the actual API requirement.
 
 The repository keeps exact SDK versions as development/test fixtures for reproducibility. Exact fixtures do not constrain which Pi version may load the published extension.
 

package/docs/getting-started.md

@@ -25,7 +25,7 @@ mkdir -p .pi/forge/prompt-stacks
 cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
 ```
 
-When installed from npm, open `/preset ui` and create a stack; new stacks start from the same mirror layout.
+Open `/forge ui` to create a preset without copying a file. In Forge 0.5.5, you can choose the default Pi mirror layout, an empty preset (where Pi retains its base prompt and history), or a minimal worker template (`bash` and `edit` only).
 
 Reload and activate it:
 

package/docs/guides/delegation.md

@@ -4,7 +4,10 @@
 
 > **Experimental:** This API and its backends may change independently of stable prompt-stack and profile behavior.
 
-The optional `@zihanw/pi-forge-subagents` package executes an explicitly authorized agent profile as a separate, clean, one-shot Pi process. It runs in the foreground and returns a bounded report to the parent conversation.
+The optional `@zihanw/pi-forge-subagents` package executes an explicitly authorized agent profile through a selected backend. The default read-only backends use a separate, clean, one-shot Pi process; write-capable backends have different boundaries described below. The documented flow runs in the foreground and returns a bounded report to the parent conversation.
+
+> **Default-tool compatibility:** Forge 0.5.5 provides `tools.initial`; the independently published optional subagents 0.5.3 is not compatible with this field. Until the optional package raises its Forge floor to `^0.5.5` and ships its separate fix, use matching local checkouts; see [tool-selection compatibility](../reference/subagent-host-port.md#tool-selection-compatibility). This optional compatibility work is not a main-package release gate.
+
 
 ## Enable a profile
 
@@ -43,7 +46,7 @@ Humans use:
 
 `plan` resolves the profile and stack, compiles and validates the exact immutable provider-bound plan, displays it, and discards it without provider transport.
 
-Profile selectors accept the same grammar everywhere: `reviewer` (project first), `project:reviewer`, or `global:reviewer`. When both scopes expose the same ID, the project profile keeps the concise selector and the global profile remains callable as `global:<id>`.
+Profile selectors use the same grammar everywhere: `reviewer`, `project:reviewer`, or `global:reviewer`. For delegation, a bare ID selects `project:<id>`; use an explicit `global:<id>` selector for a global profile. Same-ID profiles remain separate and do not inherit delegation policy from one another.
 
 The parent model uses `forge_subagent_profiles` to discover enabled profiles and `forge_subagent` to invoke one. A restrictive parent stack must allow both tool names. Discovery is local/no-egress and reports metadata, resolution readiness, effective backend/timeout, approval mode, and whether parent tool policy permits invocation.
 
@@ -51,18 +54,20 @@ Projects with only a few frequently used profiles can set `summaryInToolDescript
 
 ## Parallel invocation
 
-`forge_subagent` is a parallel-execution tool: the parent model may issue several calls in one turn, and they prepare and run concurrently. Interactive approval dialogs are serialized one at a time because Pi's selector/editor UI is a single slot—a second concurrent dialog would clear the first and leave it unresolved—so each call waits its turn for the dialog and then executes immediately, letting approved runs overlap. Unattended invocation needs no dialog and is fully concurrent. Each run is an independent `pi` subprocess and provider request; a burst of parallel calls multiplies provider cost and process load, so keep the parent tool policy conservative until a configurable concurrency cap lands.
+`forge_subagent` is a parallel-execution tool: the parent model may issue several calls in one turn, and they prepare and run concurrently. Interactive approval dialogs are serialized one at a time because Pi's selector/editor UI is a single slot—a second concurrent dialog would clear the first and leave it unresolved—so each call waits its turn for the dialog and then executes immediately, letting approved runs overlap. Unattended invocation needs no dialog and is fully concurrent. Fresh-process backends create an independent child process and provider request; `pi-inprocess` instead runs in the host runtime. A burst of parallel calls multiplies provider cost and process load, so keep the parent tool policy conservative until a configurable concurrency cap lands.
 
 ## Backends and precedence
 
-Two fresh-process backends are registered:
+Matching development versions of the optional subagents package and runtime expose four backend IDs. These notes describe unfinished optional-package source, not a finalized companion release; the main Forge 0.5.5 package does not require them.
 
-- `pi-subprocess-readonly` is the default and uses `pi --mode text --print`.
-- `pi-rpc-readonly` uses `pi --mode rpc`.
+- `pi-subprocess-readonly` is the default and uses `pi --mode text --print`. It exposes the `read`/`grep`/`find`/`ls` allowlist and is shared-user: the allowlist is not an OS sandbox.
+- `pi-rpc-readonly` uses `pi --mode rpc` with the same shared-user read-only policy; only the process protocol differs.
+- `pi-inprocess` runs in the host model runtime with the invoking user's full privileges. It is a workspace-write backend and can expose `read`/`grep`/`find`/`ls`/`edit`/`write`/`bash` when the sealed access level and stack policy allow them; it has no OS sandbox. It is the backend for extension-registered providers that cannot be used in fresh children.
+- `pi-bwrap-write` is an opt-in Linux Bubblewrap backend. It provides an isolated `workspace-write` mount for the selected workspace and can expose `read`/`grep`/`find`/`ls`/`edit`/`write`/`bash` when allowed. Writes go directly to that workspace; they are not staged for a separate approval/apply step. Bubblewrap and, by default, a git workspace are required.
 
-Both execute the same sealed prompt and shared-user read-only policy; only their process protocol differs. There is no fallback if the selected backend is unavailable.
+There is no fallback if the selected backend is unavailable. Fresh-process backends reject extension-registered providers as non-portable; use `pi-inprocess` for those providers. Do not read the development matrix or the `tools.initial` compatibility fix as a claim that the paired companion release is already published.
 
-Interactive backend precedence is: per-run override, project profile override, project default, user default, built-in default. Unattended model invocation is pinned to the effective configured backend and rejects a per-call override. Timeout follows profile, project, user, then the 60-second built-in default; valid values are 1,000–3,600,000 ms. Host timeout is best effort.
+For human runs, backend precedence is: explicit per-run `--backend`, matching profile override, trusted project default, global default, then the built-in `pi-subprocess-readonly`. An interactive model invocation may also supply a per-call backend override; an unattended model invocation is pinned to the effective profile/configured backend and rejects that override. Timeout follows matching profile override, trusted project default, global default, then the 60-second built-in default; valid values are 1,000–3,600,000 ms. Host timeout is best effort.
 
 ## Approval and unattended invocation
 
@@ -76,28 +81,25 @@ To authorize the parent model without per-run approval:
 }
 ```
 
-This affects only `forge_subagent`; `/forge-agent run` remains interactive. It is ignored in untrusted projects and malformed values fail closed. Treat this project `subagents.json` as an authorization file: do not enable or commit it unless every parent agent allowed to call `forge_subagent` may send the compiled prompt and readable file contents to the selected provider without asking again.
+This affects only `forge_subagent`; `/forge-agent run` remains interactive. The flag may come from global defaults or a trusted project file, with the project value taking precedence. With the unreleased companion fix, an absent flag inherits; an explicitly non-boolean value sets that layer to `false` and emits a warning. A valid boolean in a higher-priority layer still overrides normally. If an entire config file is unreadable, malformed, or not a JSON object, that file is ignored with a warning and an earlier valid layer may remain effective. An untrusted project's project settings are ignored, and the execution trust gate blocks delegation runs from that project. Treat `subagents.json` as an authorization file: do not enable or commit unattended invocation unless every permitted parent agent may send the compiled prompt and readable file contents to the selected provider without asking again.
 
 ## Child context and output
 
-The child receives a clean conversation, the exact profile model/thinking/stack, and the delegated task as a protected final user message. It does not automatically receive parent history.
+An ordinary new child starts with a clean conversation, the exact profile model/thinking/stack, and the delegated task as a protected final user message. It does not automatically receive parent history. Explicit retained-child continuation and background execution are separate development features documented in the [companion package](https://github.com/MacroSony/pi-forge-subagents).
 
-Candidate tools are `read`, `grep`, `find`, and `ls`, further restricted by stack tool policy. The child loads no write/edit/shell tools, skills, prompt templates, project context files, or third-party extensions.
+For `pi-subprocess-readonly` and `pi-rpc-readonly`, candidate tools are `read`, `grep`, `find`, and `ls`, further restricted by stack tool policy; these children load no write/edit/shell tools, skills, prompt templates, project context files, or third-party extensions. `pi-inprocess` and `pi-bwrap-write` can receive the write-capable tool surface described above only when their access level and stack policy allow it.
 
 The model-visible result is bounded. Expandable human details retain normalized status, a text transcript, tool events, diagnostics, usage, approval receipt, and execution report. Retained strings are bounded, base64-like text is redacted, and the transcript keeps a 512 KiB rolling tail. Inline image bytes are replaced by MIME/encoded-size metadata before retention in the parent session.
 
 ## Security boundary
 
-The current backends are **shared-user, not operating-system sandboxes**.
+The security boundary is backend-specific:
 
-- “Read-only” is a model-tool policy. The process retains the invoking user's OS permissions.
-- Absolute paths readable by that user may be read and sent to the selected provider.
-- Text may be retained in parent tool-result details and Pi's on-disk session JSONL.
-- Timeout and cancellation are best effort.
-- `/tree` changes the active conversation branch; abandoned entries can remain on disk.
-- `/tree` cannot undo provider requests, billing, or external effects.
-- Removing sensitive retained text requires deleting the relevant Pi session data.
+- The subprocess and RPC read-only backends are **shared-user, not OS sandboxes**. “Read-only” is a model-tool policy; the child retains the invoking user's OS permissions. Absolute paths readable by that user may be read and sent to the selected provider.
+- `pi-inprocess` is also shared-user and runs in the host process with full user privileges. Its allowlist can permit write/edit/`bash`, but it provides no OS isolation.
+- `pi-bwrap-write` is the isolated Linux exception: Bubblewrap exposes the selected workspace as the writable project mount, alongside read-only runtime mounts and temporary sandbox storage. It is not a staged patch/apply workflow, and it does not provide network isolation.
+- Across backends, timeout and cancellation are best effort. Text may be retained in parent tool-result details and Pi's on-disk session JSONL; `/tree` cannot undo provider requests, billing, or external effects, and abandoned entries can remain on disk. Removing sensitive retained text requires deleting the relevant Pi session data.
 
-The default tools intentionally provide no mutation path. Do not add write, edit, or shell access to this shared-user design. OS isolation and separately approved staged writes remain future work.
+Choose a read-only backend when no mutation path is intended. Treat write-capable backends as explicit authorization to modify the selected workspace, not as a promise of separately approved staged changes.
 
 For integration authors, see the [subagent host port contract](../reference/subagent-host-port.md).

package/docs/guides/migrating-to-0.5.md

@@ -101,6 +101,35 @@ Subagent execution moved out of the main package into the optional `@zihanw/pi-f
 | `@zihanw/pi-forge/src/*` aliases | removed; no replacement (internals) |
 | root loader/profile/catalog/engine re-exports | removed; no replacement (internals) |
 
+## Upstream Pi 0.87 migration
+
+Forge 0.5.5 requires upstream Pi `>=0.87.0 <0.88.0`. Dual 0.86 runtime support is not provided (repo dev SDK is pinned to `0.87.0`, peer range `>=0.87.0 <0.88.0`). Main and optional packages release independently.
+
+**Restart Pi after upgrading:** Updating the global installation does not replace the core in already-running processes. If the session predates the upgrade, exit and start Pi again before resuming it; extension-only `/reload` does not upgrade the running core. Use the new `/preset ui` URL; old server tokens are not retained.
+
+### Context hook migration (`context_with_system`)
+
+- **Standard `context` excludes System:** In Pi 0.87, standard `context` lifecycle hooks intentionally exclude System messages. Any prior extension or custom integration that inspected, modified, or relied upon full System context must move to the full `context_with_system` hook.
+- **Unified Forge pipeline:** Forge moves its entire compiler, base prompt replacement, and capability projection pipeline together to `context_with_system`, operating cleanly at the full-transcript boundary without an internal two-phase split.
+- **`before_agent_start` timing:** Any forced System prompt injection via `before_agent_start` continues to execute later in Pi's lifecycle than `context_with_system`.
+
+### Canonical projection and session history
+
+- **`buildSessionProjection` integration:** Runtime execution, the Preview dock, and anchor locator helpers now use Pi 0.87's `buildSessionProjection`. Turn-level `context_edit` omissions, replacements, and `sourceEntry` references are reflected in ephemeral model requests while raw session JSONL history on disk remains untouched.
+- **Leading System message ordering:** The SDK's incoming leading System message always remains first in the request transcript; Forge's own prefix plain metadata anchors are inserted immediately after it, never displacing the request head or user fallback.
+- **Arbitrary preceding rewrites fail closed:** Third-party extensions performing arbitrary message rewrites prior to Forge must maintain unique ordered alignment with the canonical session projection. Ambiguous or destructive preceding rewrites still fail closed.
+
+### Continuations and settlement lifecycle
+
+- **`agent_end` vs. `agent_settled`:** `agent_end` offers an anchor boundary after a low-level run, provided no Forge context failure or incomplete tool batch remains. However, the compile cycle and busy fence reset only on `agent_settled`. This guarantees that `agent_before_settle` continuations preserve compiled Preset inputs and active capabilities across low-level runs without dropping prompt context.
+
+### Guardrails and semantics unchanged
+
+- **Project trust:** Activations and Agent control require an explicitly trusted project (`isProjectTrusted()`); human CLI disable/reset recovery remains available.
+- **`sourceRevision` stale-save guard:** Existing capability updates/deletes and binding-bearing Preset updates must match the loaded source revision; capability creation must not overwrite an existing file. Stale saves fail with `409 Conflict`.
+- **Save ≠ Enable:** Saving a capability library definition updates its file only and does not enable it in the session; saving an active Preset refreshes that Preset's policy immediately (updating live tool and capability authorization policy), without replacing frozen active capability snapshots.
+- **Upstream defect status:** Upstream Pi metadata chunking and semantic-cut defects are NOT patched; compaction checkpoint placement is unchanged. Existing legacy session carriers remain untouched without automatic migration, and Oh My Pi (OMP) is not supported or promised.
+
 ## Compatibility notes
 
 - The wire shape of the host port is additive across `FORGE_HOST_PORT_VERSION = 1`; unknown operations are rejected with a plain `{ ok: false, error }` result (`"Unknown Forge host operation: …"`), not a thrown error, and optional packages must treat any operation failure as terminal for that request.

package/docs/guides/use-cases.md

@@ -36,7 +36,7 @@ Keep independent project files:
   translator.json
 ```
 
-Switch with `/preset use coder`, `/preset use writer`, or `/preset use translator`. Capture a profile when a mode also needs a specific model and thinking level.
+Switch with `/preset use coder`, `/preset use writer`, or `/preset use translator`. Capture a profile when a capability also needs a specific model and thinking level.
 
 ## Read-only scout
 
@@ -44,13 +44,17 @@ Allow only `read`, `grep`, `find`, and `ls`, omit editing tools, and cap chat hi
 
 Tool policy constrains model tool calls but is not an operating-system sandbox. A normal Pi agent may still have other non-tool ways to interact with its host; do not describe a prompt stack alone as process isolation.
 
+## Read first, enable command/edit tools on demand
+
+The [Read-first Worker pair](../reference/capabilities.md#read-first-worker) keeps the minimal-worker shape: one role block and chat history. Defaults are `read` and `ls` plus `forge_capability`; one explicitly authorized binding adds `bash` and `edit`. Follow the paired-file setup and ownership/sandbox caveats before trying it.
+
 ## Surgical patcher
 
 Keep the Pi mirror, require the tools needed for the workflow, strip prior assistant thinking from inserted history, and move project context near the current user turn. This reduces distracting prompt material without removing relevant repository instructions.
 
 ## Payload lab
 
-Include `active-model` and `date-cwd`, then add compiled regex rules for deterministic redaction or formatting. Pair the stack with `/payload next` or the web editor's capture view to audit exactly what changed.
+Include `active-model` and `date-cwd`, then add compiled regex rules for deterministic redaction or formatting. Pair the stack with `/forge payload next` (or bare `/payload`) or the web editor's capture view to audit exactly what changed. Use `save="path with spaces.json"` when saving a capture; existing files require `--overwrite`.
 
 Redaction is limited to the declared patterns and supported text targets. It is useful for known shapes but is not an exhaustive credential scanner or security boundary.