@tranhoangnguyen0310/pi-flow-external 2.9.0-external.0 → 3.0.0-external.0

package/AGENTS.md

@@ -4,15 +4,16 @@
 
 This fork changes the original pi-flow contract: `Agent` is not a generic Pi subagent launcher. It delegates only to external Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode harnesses, plus named Pi harness configurations (below) — in-process, per-model configs registered by the user, not a spawned CLI.
 
-- Ordinary driver tools: `Agent`, read-only `external_help`, `external_runs`, and optional `workflow`. `pi_flow_role_create` is active only inside `/external role create`. `pi_flow_harness_create` is active only inside `/external config harness create`.
-- User operations use `/external`. Harness-centric configuration lives under `/external config`: `edit`, `convert`, `harnesses`, `harness create`, `enable <harness>`, `disable <harness>`, and `default <harness>`. Role authoring stays under `/external role`. Former `/external settings …`, `/external harnesses`, and `/external harness create` routes are removed, not aliases. `/external profiles`, `/external profile create`, and `/pi-flow-profile create` are removed, including registrations, completions, and interview routing. They are not aliases or redirect handlers. Unknown-command help lists the current commands. `subagent_type` on `Agent` and `workflow` remains the exact-identity API.
-- The only execution-configuration file is `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json` (settings v4): concurrency, timeout, permission and budget defaults, retention, `defaultHarness`, named `pi-*` harness entries (`model` / `thinking` / `preset`), `disabledProfiles`, and `disabledHarnesses`. Reads do not write the file. Shared roles live in `pi-flow-external/roles/<role>.md` (one file, any harness; `description` only). Exact overrides live in `pi-flow-external/overrides/<harness>-<role>.md` and keep the execution profile schema as a complete replacement. `permission` and `capabilitySet` are obsolete metadata on both and are rejected, not used as authority. Both directories are created only when a file is saved. The extension does not write Pi's native `subagents/` directory. Settings mutations use one validated read-modify-write helper (private staged file, same-directory replacement, unrelated fields preserved, malformed or future-version files refused). Replacement prevents a torn write. There is no inter-process lock: concurrent writers from separate sessions are last-writer-wins and may drop one update. That limitation stays accepted. A trusted project may override `defaultHarness` via `.pi/pi-flow-external/settings.json` (that key only, read-only to the extension); explicit call harness > project default > global default > built-in default. `defaultHarness` may name a registered `pi-*` harness. The project file cannot inject roles or harnesses.
-- Every `Agent` call requires `description`, `prompt`, and either `role` with optional `harness` (`agy`, `claude`, `codex`, `grok`, `muse`, `opencode`, or a registered `pi-*` harness name) or the legacy exact `subagent_type`. The selectors cannot be combined. Without `harness`, use the effective default harness. A default that names a `pi-*` harness that is no longer registered fails with an actionable error and does not fall back to `agy`. `disabledProfiles` blocks individual identities; `disabledHarnesses` blocks whole CLI or named Pi harnesses for both `role` and exact `subagent_type` selection, including resumed calls and new workflow replay attempts. Disabled harnesses are hidden from executable discovery; config lists their state and doctor skips readiness probes. Definitions and overrides are preserved. Guided commands refuse disabling the effective/global default or selecting a disabled default. Manual inconsistencies fail selection. Active children and frozen workflows keep their snapshot. Unknown disabled names are preserved with diagnostics. There is no harness substitution.
-- One catalog snapshot serves `Agent`, workflows, coordinator guidance, `external_help`, `/external roles`, and doctor. Precedence is exact override, then shared role, then built-in. An invalid higher-priority entry blocks that selection. Unrelated invalid entries are diagnostics and do not block other roles. Invalid settings JSON or an unsupported settings version blocks delegation; `/external config` and `/external config convert` stay available. Stable identities are `<harness>-<role>` plus exact legacy names. The next invocation reads settings, roles, and overrides from disk. A workflow freezes one snapshot for the whole run. A `maxConcurrentSubagents` change waits until no subagent is active and none are queued.
-- The six built-in roles (explorer, planner, implementer, reviewer, qa, worker) are in memory for all six CLI harnesses and every registered named Pi harness. Session start writes zero role files and zero seed markers. A shared file named `reviewer.md` replaces that built-in on every harness. Roles outside the six are authored once with `/external role create` (offline validation and write; a role is not an authenticated connection). `/external role override <role> <harness>` materializes one full override. `/external config harness create` registers a named Pi harness with a real runtime smoke test and no role interview. A harness smoke test does not judge role quality. Deleted seeded identities survive conversion as `disabledProfiles` and are not recreated.
-- Native Pi subagent files stay native. This extension does not modify them. A `backend: pi` file under native `subagents/` is outside the external catalog. A Pi exact override is delegation-eligible only when its `harness` names an entry in the live settings `harnesses` map.
+- `/external` and bare `/external config` open one guided modal in TUI mode, native dialogs in RPC, and retain text without UI. The modal reuses lifecycle validation/previews, never probes or sends requests on open, defaults terminal confirmations to Cancel, and offers explicitly confirmed Pi tests. Terminal Esc cancels pending listings/tests; RPC uses client dialogs and has no busy-operation cancel control. Runtime tuning and legacy state stay under Advanced. Ordinary tools remain Agent, external_help, external_runs and workflow. Configuration commands are symmetric under `/external config harness` and `/external config role`: list, inspect, create, edit, set, reset, enable, disable, delete; harness also default/test/assist and role assist. Assisted finalizers activate only under assist. Prior config harnesses/enable/disable/default and external roles/role routes are removed; help and release notes provide mappings.
+- settings v5 is the only execution settings source. `harnesses` accepts CLI defaults and named Pi registrations; sparse `harnesses.<name>.roles.<role>` owns per-binding scalars/gates; root `roles` owns role-wide gates. Markdown under roles/<role>.md and overrides/<harness>/<role>.md holds description/instructions only. Empty replacement body is explicit empty; absence inherits. Converted nonstandard selectors remain explicit exact compatibility records.
+- Canonical identities use harness/role and explicit fields, not ambiguous hyphen splitting. Legacy exact pair names work only when unambiguous. One catalog feeds selection, discovery, inspection, and workflows. Invalid higher-priority entries block; unrelated invalid instructions do not block valid bindings. Invalid global settings block delegation. No harness fallback.
+- Scalars resolve binding > harness > backend defaults. Fresh CLI effort defaults native; parent explicitly snapshots root effort; off is not reset. Pi model/effort are defaults permitting validated binding exceptions; preset remains harness-owned. Permission is only call > global default. Native unresolved defaults cannot prove replay equivalence. Agent/workflow share effective resolution; replay hashes effective effort/budget.
+- Enablement is harness AND role AND binding AND valid configuration. Enable clears only its named gate and reports remaining blocks. Reset preserves gates. Built-ins cannot be deleted. Destructive previews fingerprint owned files/settings and revalidate; deletion persists a disable gate before multi-file cleanup, leaving failures blocked. Never delete native settings, credentials, or receipts. Role reset removes instruction files before scalars; unlink failure preserves scalar settings, and any later settings-write failure reports the partial removals. Catalog reads reject linked configuration/instruction roots rather than traversing them. Active children and workflows retain frozen snapshots.
+- Reads create no settings/default role files. Six built-in roles remain in memory. Settings writes use private atomic replacement, preserving unrelated fields; concurrent sessions remain last-writer-wins, not lock-protected. Trusted projects may override defaultHarness only. Deterministic authoring does not need a model. Pi readiness tests explicitly use readonly curated tools, not an OS sandbox; CLI readiness distinguishes status from model requests.
+- v4 runtime delegation requires explicit conversion through `/external config convert` or the guided recovery preview. Pre-v4 installs first convert to v4, then separately preview/confirm v5. The first step preserves legacy files; the v5 step installs immutable `settings.v4.backup.json` and instruction copies under `overrides/<harness>/<role>.md` before activation, revalidating sources and collisions. Nonstandard/ambiguous selectors retain explicit `exact` records. Matching interrupted copies may be reused; differing copies block. Legacy CLI tools metadata was never enforced and is omitted with a source-specific preview note; Pi tools remain. Unsupported effort blocks with its source and repair guidance, never silent remapping. The shared writer refuses editor version changes; only verified converter activation may change v4 to v5. No automatic repeated-pin consolidation or copied-body deletion. Purge is separate and optional; never modify real user configuration without separate authorization.
+- Native Pi subagent files stay native. This extension does not modify them. A `backend: pi` file under native `subagents/` is outside the external catalog. A Pi exact compatibility record is delegation-eligible only when its `harness` names an entry in the live settings `harnesses` map.
 - A registered `pi-*` harness is selected with the same `Agent` and `workflow` `role` plus optional `harness` path as `agy`, `claude`, `codex`, `grok`, `muse`, and `opencode`. Do not tell callers to route Pi-backed work to Pi's native subagent tool.
-- **Named Pi harness configuration:** a `pi-<label>` entry in settings v4 `harnesses`, pinning a `provider/model` id (resolved through Pi's own model registry), a thinking level (`off|minimal|low|medium|high|xhigh`, always persisted explicitly), and a resource preset (`minimal` or `skills`). New writes persist the preset. A legacy registration that omits it is `minimal`. The six CLI harnesses are built in and need no entries. It runs in-process via Pi's own SDK, not as a spawned CLI. `minimal` leaves skills unloaded (`noSkills: true`). `skills` loads installed skills through `DefaultResourceLoader` (`noSkills: false`); project-scope skills load only when the caller's project is trusted. Extensions, prompt templates, and themes stay unloaded in both presets. The catalog, the workflow's frozen descriptor, the replay fingerprint, and spawn all use that registration value. The tool surface stays the SDK builtins (`read`/`bash`/`edit`/`write`, plus `grep`/`find`/`ls` where a tier's allow-list adds them), curated but never claimed to be an OS sandbox: `danger` tier `bash` is exactly as exposed as on any external CLI. Retry is disabled per child (in-memory, call-scoped, never touching the user's real settings) to honor this extension's no-auto-retry contract, since the underlying SDK otherwise retries transient provider errors on its own. Pi children cannot resume (no persisted session) and have no enforced budget cap — both are deliberate v1 limitations, not oversights. Shared roles apply to every harness from one file. Backend-specific model, tools, budget, or instruction changes belong in one exact override; `tools` is enforceable only on Pi, and a Pi override's `model`/`thinking` must match the harness entry. Follow-up capability expansion (trusted extensions/MCP, resumable sessions, real budget controls) stays tracked in issue #43. `pi-web-access` was not wired: the pinned SDK docs do not verify that extension integration, and it is left for a separate investigation. Pre-v4 installs convert once through `/external config convert`. `/external config` points there when conversion is ready. Originals stay on disk. Custom profiles are copied as overrides with obsolete `permission` and `capabilitySet` removed. A legacy `subagents/pi-<role>.md` file with `harness: "pi-*"` becomes an ordinary cross-harness `roles/<role>.md`. Those copies install before v4 activation, and after activation old paths are ignored. `piCapabilitySets` is not copied. `/external [danger]purge-old-files` lists the legacy inventory, including customized copies, and deletes only the paths you select and then confirm. Ordinary delegation does not require it. Downgrade after purge needs the user's own backup. The literal `[danger]` is part of the purge spelling. There is no dual-write and no `/external migrate` command.
+- **Named Pi harness configuration:** a `pi-<label>` entry in settings v5 `harnesses`, defaulting to a `provider/model` id (resolved through Pi's own model registry), a thinking policy (`off|minimal|low|medium|high|xhigh|parent`, persisted explicitly by creation), and a resource preset (`minimal` or `skills`). New writes persist the preset. A legacy registration that omits it is `minimal`. The six CLI harnesses are built in and need no entries. It runs in-process via Pi's own SDK, not as a spawned CLI. `minimal` leaves skills unloaded (`noSkills: true`). `skills` loads installed skills through `DefaultResourceLoader` (`noSkills: false`); project-scope skills load only when the caller's project is trusted. Extensions, prompt templates, and themes stay unloaded in both presets. The catalog, the workflow's frozen descriptor, the replay fingerprint, and spawn all use that registration value. The tool surface stays the SDK builtins (`read`/`bash`/`edit`/`write`, plus `grep`/`find`/`ls` where a tier's allow-list adds them), curated but never claimed to be an OS sandbox: `danger` tier `bash` is exactly as exposed as on any external CLI. Retry is disabled per child (in-memory, call-scoped, never touching the user's real settings) to honor this extension's no-auto-retry contract, since the underlying SDK otherwise retries transient provider errors on its own. Pi children cannot resume (no persisted session) and have no enforced budget cap — both are deliberate v1 limitations, not oversights. Shared roles apply to every harness from one file. Backend-specific model, effort, tools and budget settings belong in sparse JSON binding settings; instruction replacements stay Markdown. Tools are enforceable only on Pi. Pi binding model/effort exceptions are validated rather than required to equal defaults. Follow-up capability expansion (trusted extensions/MCP, resumable sessions, real budget controls) stays tracked in issue #43. `pi-web-access` was not wired: the pinned SDK docs do not verify that extension integration, and it is left for a separate investigation. Guided and direct Pi creation validate and save offline; no test request is sent. `/external config harness assist` is a separate model-assisted interview whose finalizer confirms and smoke-tests the registration with rollback on failure. Explicit readiness tests require their own confirmation, use an empty temporary workspace and readonly curated tools, and do not create a normal run receipt. Conversion follows the staged contract above; obsolete `permission`, `capabilitySet`, and `piCapabilitySets` are not execution authority. `/external [danger]purge-old-files` lists the legacy inventory, including customized copies, and deletes only the paths you select and then confirm. Ordinary delegation does not require it. Downgrade after purge needs the user's own backup. The literal `[danger]` is part of the purge spelling. There is no dual-write and no `/external migrate` command.
 - Permission is the call's explicit `permission`, otherwise settings `defaultPermission` (`danger` unless changed). A role describes intent and does not grant or limit authority. There is no profile floor and no role-name escalation. Each backend maps a tier it supports and rejects a restriction it cannot enforce. Disclosure and receipts show that resolved tier.
 - External CLI backends use their own tools and permission mechanisms. Codex tiers map to its `--sandbox` axis. Grok tiers also map to its `--sandbox` axis (`read-only`/`workspace`/`off`), always paired with `--permission-mode bypassPermissions`; bypass only skips the interactive prompt, and the kernel sandbox remains the enforced boundary at every tier. Grok's readonly network-blocking guarantee is Linux-only (a no-op on macOS), and sandbox startup can fail closed rather than silently downgrading on some macOS hosts (for example when `/var/run/docker.sock` resolves to a symlink). Claude falls back to `--permission-mode auto` when its effective UID is 0 because Claude refuses bypass mode under root. Claude `edit` uses `acceptEdits` and denies Bash headlessly; a role name does not raise that tier. Antigravity (`agy`) accepts only unsandboxed `--dangerously-skip-permissions`. A `readonly` or `edit` request is rejected rather than broadened. Run agy only in trusted repositories. Muse (`muse exec`) has approval and its own sandbox ON by default; every supported tier passes `--disable-approval` so headless runs never hang on an interactive prompt. `readonly` additionally passes `--disable-write --disable-shell`; `edit` leaves the sandbox enabled with only approval bypassed; `danger` uses `--yolo`, which disables approval and the sandbox and additionally trusts the workspace for this run (loads its skills/rules). Pi curated tool lists are not an OS sandbox.
 - Grok supports `resume` via its own `--resume <sessionId>` flag and reports native cost (`total_cost_usd`) rather than an estimate. It has no budget-enforcement mechanism, so `max_budget_usd` is recorded but unenforceable, and — like codex — it is never automatically retried (agy's one infra-failure retry exception does not apply to Grok).
@@ -31,7 +32,7 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 
 ## Delegation transparency invariants
 
-- Treat each `description` as a concise user-facing task label. Role and override descriptions are also user-visible as the declared reason for selection. The resolved execution object is still an internal profile; receipts keep the stable `<harness>-<role>` identity or the exact `subagent_type` name.
+- Treat each `description` as a concise user-facing task label. Role and override descriptions are also user-visible as the declared reason for selection. The resolved execution object is still an internal profile; receipts keep the canonical `<harness>/<role>` identity or the exact `subagent_type` name.
 - `unsandboxed external CLI` and `external host access` disclose the real execution boundary for CLI backends; a pi harness delegation discloses `Pi SDK child · host access · curated tools` instead — never call an in-process pi child an "external CLI". Never present a read-only prompt as permission enforcement. Antigravity accepts only danger and rejects narrower tiers. On pi, the curated tool table bounds which tool *names* exist and is not an OS sandbox; `bash` at `danger` stays host access.
 - Keep direct intent visible during execution. Workflow access belongs once at the workflow level, not on every child row.
 - Parent guidance stays split. The always-on coordinator prompt is a short operating guide. `external_help` topic `usage` is the worked playbook. README is the user model. This file holds contributor invariants. Do not copy the playbook into the coordinator prompt, and do not rank harnesses by intelligence.
@@ -53,7 +54,7 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 
 ## Workflow contract
 
-`workflow` remains trusted JavaScript orchestration over the same external-only role roster, including all six CLI harnesses and registered named Pi harnesses. Its first statement declares `meta.apiVersion: 1`; missing/unsupported versions fail before child launch. Every workflow `agent()` child uses the same `role`/optional `harness` resolution as `Agent`, with legacy exact `subagent_type` available as an escape hatch. A workflow run freezes one catalog snapshot up front — built-in roles, shared roles, exact overrides, and the harness model, thinking, and resource preset — so a later edit to `settings.json`, `roles/`, or `overrides/` cannot desync what the replay fingerprint recorded from what that run executed. Replay reuses a prefix only when the effective descriptor is identical; changed instructions invalidate reuse. Successful calls return their value; failed, cancelled, and timed-out calls throw structured catchable child errors. Explicitly handled errors permit siblings to finish; escaping errors fail the workflow and drain active siblings.
+`workflow` remains trusted JavaScript orchestration over the same external-only role roster, including all six CLI harnesses and registered named Pi harnesses. Its first statement declares `meta.apiVersion: 1`; missing/unsupported versions fail before child launch. Every workflow `agent()` child uses the same `role`/optional `harness` resolution as `Agent`, with legacy exact `subagent_type` available as an escape hatch. A workflow run freezes one catalog snapshot up front — built-in roles, shared/scoped instructions, gates, compatibility records, and resolved execution settings, including model, effort, tools, budget, and resource preset — so a later edit to `settings.json`, `roles/`, or `overrides/` cannot desync what the replay fingerprint recorded from what that run executed. Replay reuses a prefix only when the effective descriptor is identical; changed instructions invalidate reuse. Successful calls return their value; failed, cancelled, and timed-out calls throw structured catchable child errors. Explicitly handled errors permit siblings to finish; escaping errors fail the workflow and drain active siblings.
 
 Replay is explicit through a persisted `scriptPath` plus `resumeFromRunId`. Reuse only the longest unchanged successful prefix; changed or unsuccessful calls and their suffix execute again. Never describe script recomposition as making child reruns free or side-effect-free. There is no live steering or automatic repaired-script retry.
 
@@ -71,5 +72,5 @@ Use workflows for requested fan-out or multi-agent orchestration across agy, Cla
 
 - Run `npm run check`, `npm pack --dry-run --json`, and `npm audit --omit=dev --audit-level=high` before release.
 - Follow `docs/field-testing.md` for real-backend checks and `docs/releasing.md` for the automated release flow, versioning, trusted publishing, and registry verification.
-- Releases are automated: merging a PR that bumps the version (labelled `release:patch|minor|major|prerelease`, or `release:none` to skip) tags the commit, publishes to npm via OIDC trusted publishing, and creates the GitHub release. `release:none` PRs must not change shipped files without a bump; CI enforces the label/version/CHANGELOG contract. The v4 redesign shipped as `2.6.0-external.0` with `release:minor`. Subsequent command removals still require explicit old→new mappings in the CHANGELOG section that becomes the GitHub release notes. Existing v4 settings require no new conversion for harness toggles. Pre-v4 conversion preserves originals; purge deletes only selected legacy copies, and downgrade after purge needs the user's backup. Do not hide command breaks in a patch note.
+- Releases are automated: merging a PR that bumps the version (labelled `release:patch|minor|major|prerelease`, or `release:none` to skip) tags the commit, publishes to npm via OIDC trusted publishing, and creates the GitHub release. `release:none` PRs must not change shipped files without a bump; CI enforces the label/version/CHANGELOG contract. The v4 redesign shipped as `2.6.0-external.0` with `release:minor`. Subsequent command removals still require explicit old→new mappings in the CHANGELOG section that becomes the GitHub release notes. Existing v4 settings require explicit v5 conversion. Pre-v4 conversion preserves originals; purge deletes only selected legacy copies, and downgrade after purge needs the user's backup. Do not hide command breaks in a patch note.
 - Never republish an existing npm version or force-push release history.

package/CHANGELOG.md

@@ -2,9 +2,49 @@
 
 All notable changes to pi-flow external are documented here.
 
-## Unreleased
+## [3.0.0-external.0] - 2026-10-01
+
+### Breaking: configuration v5 (issue #73)
+- Require explicit v4→v5 conversion before delegation. `/external config convert` (or **Preview format update…** on the guided recovery screen) previews changes, preserves `settings.v4.backup.json` and original files, and installs instruction copies before activation. Pre-v4 installations first convert to v4, then v5. No automatic consolidation of repeated pins or deletion of copied instructions.
+- Replace `/external config harnesses` → `/external config harness list`; `/external config enable|disable|default NAME` → `/external config harness enable|disable|default NAME`.
+- Replace the `/external config harness create` interview → `/external config harness create pi-NAME --model provider/model [--effort LEVEL] [--preset minimal|skills]`, which saves offline and sends no request, or `/external config harness assist` for the model-assisted interview, which smoke-tests before saving.
+- Replace `/external roles` → `/external config role list`; `/external role create` → `/external config role create NAME` (or `/external config role assist`); `/external role inspect ROLE HARNESS` → `/external config role inspect ROLE --harness HARNESS`; `/external role override ROLE HARNESS` → `/external config role edit ROLE --harness HARNESS` for instructions, or `/external config role set ROLE --harness HARNESS` for model, effort, budget, or tools. Removed routes are not aliases.
+- Bare `/external` and `/external config` now open the guided window in the terminal and in RPC instead of printing text. Scripts that read their output should use `/external config text`, which prints the configuration in any mode. Without UI, both commands still print text.
+- Canonical binding identities use `harness/role`; unambiguous legacy exact selectors remain accepted. Separate path segments prevent hyphenated identity collisions.
+
+### Added
+- Name-based model selection from backend catalogs/aliases and Pi registry, current-value markers, searchable menus, readable access settings, timeout presets and role customization summaries. Model lists come from Codex's local catalog, Claude aliases, or the Antigravity/Grok/OpenCode `models` command when a picker opens; Muse has no listing. Listing sends no prompt but a CLI may contact its service. A listed model or configured account does not imply account eligibility; manual IDs remain a fallback. The window offers Antigravity and Grok only the reasoning levels their adapters forward unchanged.
+- Guided modal configuration through `/external` and `/external config`: agent-first settings, role customization, registry-backed Pi creation, contextual checks, recovery, and Advanced. Existing explicit commands remain available; RPC uses standard dialogs and headless mode retains text output. Opening the window never probes or sends a model request.
+- Role customization distinguishes **Same as <agent>** (remove the role's own value and inherit) from **Use <agent> settings** (an explicit native CLI default, even over an agent pin).
+- Guided Pi creation (**Add a Pi agent…**) picks a provider and model from Pi's registry, then a name, and saves offline only on **Create agent**. **Send a test message…** is a separately confirmed, potentially paid readonly request from an empty temporary directory, limited to 60 seconds, and writes no run record. Esc cancels it and model listing in the terminal window; RPC dialogs cannot cancel them.
+- `/external config text` prints effective configuration, sources, and the settings path in any mode.
+- Instruction editing supports an external editor (`$VISUAL`/`$EDITOR`) and keeps the draft if it fails. The window returns to the recovery screen if settings become invalid while it is open.
+- CLI harness-wide model/effort defaults, sparse role-on-harness exceptions, role-wide enablement, deterministic create/edit/set/reset/delete operations, impact previews and effective configuration origins.
+- Named Pi model/effort exceptions use the same inheritance rules as CLI settings. JSON owns scalars; Markdown owns authored instructions. Fresh CLI defaults are native; converted installations preserve explicit parent effort policy.
+
+### Fixed
+- Keep exact-selector exclusions independent from structured binding gates, and fail closed on symlinked configuration/instruction roots.
+- Prevent settings-editor version changes from bypassing explicit conversion or downgrade safeguards.
+- Preserve enforceable Pi tools during migration, disclose omitted unenforced CLI tools and frozen exact Pi pins, and report unsupported legacy effort with source-specific repair guidance. Include retained-exclusion warnings in conversion previews.
+- Preserve scalar settings when role-reset instruction removal fails; report partial file removal if a later settings write fails. Show Pi parent effort policies accurately in text inspection.
+- Restrict harness smoke tests explicitly to readonly curated tools; no implicit danger fallback.
+- Fingerprint effective inherited effort/budget, conservatively reject replay of unresolved native defaults, and record OpenCode's actual variant/default rather than ignored parent effort.
+- Reject malformed settings and unsupported effort instead of silently dropping them; align blocked discovery with selection and validate destructive preview ownership before applying.
+
+## [2.10.0-external.0] - 2026-09-25
+
+### Added
+- Add paged Launch inspection through `external_runs` and `/external runs` for queued, active, and historical assignments, including recorded prompts, context, and execution configuration.
+- Record requested settings and applied Pi SDK tools/thinking/context, and preserve workflow source and arguments in redacted launch evidence.
+- Document the delegation experience north star and visual guidelines.
+
+### Changed
+- Make background Agent and workflow cards explicit launch receipts, with inspection routes and clearer workflow purpose, workspace, and access disclosure.
+- Improve card legibility with consistent label/value contrast, bounded source paths and run references, and expanded-only usage accounting.
+- Add run-detail refresh and recover from stale inspection pages without closing navigation.
 
 ## [2.9.0-external.0] - 2026-09-25
+
 ### Added
 
 - OpenCode (`opencode`) as a sixth CLI backend, with JSONL progress, verified-final-step completion, session resume, native root-step usage, cancellation, and durable receipts. Targets OpenCode 2 only (verified against `@opencode/cli` 2.0.16); OpenCode 1.x is not supported. Every run uses `--standalone`, a private server the run owns, and never touches the shared background service. Success is verified from the persisted session export: a new user turn for this prompt, a `succeeded` idle outcome, and a clean final assistant message whose text is the result. It never relies on the zero exit code or streamed narration alone. Restricted tiers use native deny-by-default tool rules, not an OS sandbox, and select their agent with `--agent` on every run, including resumes. Unsafe resumes (a restricted resume of a session with its own permission rules, or a danger resume of a restricted session) are refused. A pinned thinking level is passed as the pinned model's `#variant`, which OpenCode validates. Structured schemas are rejected. Nested-subagent total cost is unknown, and budgets are unenforceable.

package/CONTEXT.md

@@ -4,14 +4,14 @@ This package is a fork of pi-flow whose `Agent` and `workflow` tools are reserve
 
 ## Domain language
 
-- **Settings:** The only execution-configuration file, `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json` version 4. It holds the default harness, concurrency, timeouts, permission and budget defaults, retention, named `pi-*` harness entries, `disabledProfiles`, and `disabledHarnesses`. The six CLI harnesses (`agy`, `claude`, `codex`, `grok`, `muse`, `opencode`) are built in.
+- **Settings:** The only execution-configuration file, `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json` version 5. It holds the default harness, concurrency, timeouts, permission and budget defaults, retention, `harnesses` (CLI defaults and named Pi registrations with sparse `roles` binding settings), root `roles` enablement gates, and `exact` compatibility records. Legacy `disabledProfiles` and `disabledHarnesses` exclusions remain independent gates where retained. The six CLI harnesses (`agy`, `claude`, `codex`, `grok`, `muse`, `opencode`) are built in.
 - **Harness:** Where and how a role executes. One of the six CLI harnesses, or a registered `pi-<label>` entry in settings. Discovery and readiness are separate: a listed harness may still be uninstalled or unauthenticated.
 - **Role:** The work instructions and description. A role does not grant authority. Six built-ins (explorer, planner, implementer, reviewer, qa, worker) exist in memory for every CLI harness and every registered named Pi harness. A user-authored shared role is one file, `pi-flow-external/roles/<role>.md`, with `description` only, and it applies to every harness. `roles/reviewer.md` replaces that built-in everywhere.
-- **Exact override:** `pi-flow-external/overrides/<harness>-<role>.md`, a complete replacement of one execution identity, using the existing profile schema. `tools` is enforced only on a named Pi harness. Nonstandard legacy names stay selectable through exact `subagent_type`.
-- **Resolved profile:** The internal execution object produced by binding a role definition to a harness. It is not a user-facing command and it is not a file under Pi's native `subagents/` directory. Precedence is exact override, then shared role, then built-in.
+- **Scoped customization:** JSON harness defaults and sparse role-on-harness scalar settings; Markdown `overrides/<harness>/<role>.md` replaces instructions only. Named Pi model/effort are overridable defaults. Compatibility exact selectors are explicit, not name-parsed.
+- **Resolved profile:** The internal execution object produced by binding a role definition to a harness. It is not a user-facing command and it is not a file under Pi's native `subagents/` directory. Instruction precedence is scoped replacement, then shared role, then built-in; scalars resolve binding > harness > backend defaults.
 - **Native Pi subagent:** A subagent file owned by Pi's native subagent system. This extension does not load or modify those files. They are not entries in the external catalog.
 - **Agent call:** A direct external delegation selected by `role` and optional `harness` (`agy`, `claude`, `codex`, `grok`, `muse`, `opencode`, or a registered named Pi harness), or by legacy exact `subagent_type`.
-- **Named Pi harness configuration:** A `pi-<label>` entry in settings v4 `harnesses`, pinning a `provider/model` id and a thinking level, run in-process via Pi's own SDK rather than as a spawned CLI. `harness` selects *which* configuration; `backend` (always the literal `"pi"` for these) selects the execution mechanism. The six built-in roles are available on it immediately from the same canonical source as the six CLI harnesses, with zero generated files.
+- **Named Pi harness configuration:** A `pi-<label>` entry in settings v5 `harnesses`, defaulting to a `provider/model` id and a thinking policy, run in-process via Pi's own SDK rather than as a spawned CLI. `harness` selects *which* configuration; `backend` (always the literal `"pi"` for these) selects the execution mechanism. The six built-in roles are available on it immediately from the same canonical source as the six CLI harnesses, with zero generated files.
 - **Parent context:** An opt-in frozen text snapshot: `none` (default), `recent` with last N user turns including the current turn, or `full` available post-compaction conversation. It is background for a new external conversation, not a native session clone, system-prompt inheritance, or guaranteed cache reuse. Sharing excludes thinking and pending calls and cannot be combined with child `resume`. Workflow children share one invocation-time snapshot; prior child outputs remain explicit inputs.
 - **Workflow call:** Trusted JavaScript orchestration beginning with `meta.apiVersion: 1` that may fan out several explicit external `agent()` calls. Each child returns a value or throws a catchable `ChildRunError`; escaping child errors fail the workflow and drain siblings.
 - **Background run:** A validated, registered `Agent` or `workflow` invocation that returns a stable handle while work remains owned by the originating session. It is not a daemon or cross-session job.
@@ -29,19 +29,21 @@ This package is a fork of pi-flow whose `Agent` and `workflow` tools are reserve
 
 Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, OpenCode, and registered named Pi harnesses are selected through this extension's `Agent` or `workflow`. A role is the work. A harness is the execution environment. Pi's native subagent files stay outside the catalog and are not modified.
 
-The ordinary driver sees `Agent`, optional `workflow`, and read-only `external_help`. `pi_flow_role_create` is activated only by `/external role create`. `pi_flow_harness_create` is activated only by `/external config harness create`. External children start in the requested working directory, but backend-native nested helpers may create or use a separate workspace; prompts that request further nesting should include explicit absolute paths and all required context. Named Pi harness children are the one exception to "backend-native nested helpers may use a different workspace": a pi child runs in-process with no extensions, prompt templates, or themes loaded. The registration preset chooses skills: `minimal` leaves them unloaded, and `skills` loads installed skills, including project skills only when the project is trusted. Extensions stay unloaded, so the child still cannot launch a further nested agent through an extension.
+The ordinary driver sees `Agent`, optional `workflow`, and read-only `external_help`. `pi_flow_role_create` is activated only by `/external config role assist`. `pi_flow_harness_create` is activated only by `/external config harness assist`. External children start in the requested working directory, but backend-native nested helpers may create or use a separate workspace; prompts that request further nesting should include explicit absolute paths and all required context. Named Pi harness children are the one exception to "backend-native nested helpers may use a different workspace": a pi child runs in-process with no extensions, prompt templates, or themes loaded. The registration preset chooses skills: `minimal` leaves them unloaded, and `skills` loads installed skills, including project skills only when the project is trusted. Extensions stay unloaded, so the child still cannot launch a further nested agent through an extension.
 
 ## User control surface
 
-User operations are namespaced under `/external`: overview, doctor, `config` (harness-centric settings and defaults), `config edit`, `config convert` (the one-time pre-v4 preview and apply), `config harnesses`, `config harness create`, `config enable`, `config disable`, `config default`, roles, `role create`, `role inspect`, `role override`, the literal `[danger]purge-old-files` maintenance command, workflows, interactive run navigation, durable run summary/pruning, and help. The next invocation reads the live configuration. A concurrency-cap change waits until active and queued work drains. A workflow already running keeps its frozen snapshot. `/external profiles`, `/external profile create`, and `/pi-flow-profile create` are removed and are not aliases. `/external runs` uses the same registry/readers as `external_runs`, including every cursor-paged workflow child and output/diagnostic page. Settings v4 is the only execution-configuration file, including named Pi harness registrations. Shared roles and exact overrides are the extension-owned markdown. A trusted project may override only `defaultHarness`, which may itself name a registered `pi-*` harness. After version 4 is active, old `subagents/` profiles, seed markers, and `harnesses.json` are ignored. Purge is optional, destructive, and separate from conversion.
+Start with `/external` or `/external config`: a single guided overlay in TUI, standard client dialogs in RPC, or text without UI. Agent rows show effective model/reasoning and scoped customizations; terminal lists support `/` search, current markers, and Esc back. Model catalogs load only on picker entry and never send prompts; listed models/credentials are not access guarantees. Pi creation saves offline; setup checks and explicitly confirmed paid tests are separate. Only the terminal offers Esc cancellation of pending listings/tests. Advanced holds runtime tuning, raw settings, and compatibility maintenance; `/external config text` always emits text details.
 
-> Next agent: full implementation map is `docs/ARCHITECTURE_SNAPSHOT.md` (configuration contract 2026-09-23; execution-adapter notes last verified 2026-09-21). Keep this file and `AGENTS.md` as the persistent breadcrumbs. Files under `docs/plans/` are dated records. They are not rewritten, and they are not a second runtime contract. Where a plan disagrees with `AGENTS.md`, this file, `README.md`, or the architecture snapshot, those current docs win.
+The secondary command interface is symmetric under `/external config harness` and `/external config role`: list, inspect, create, edit, set, reset, enable, disable, delete. Harness adds default/test/assist; role adds assist. Settings edits and conversion remain under config. Runtime requires v5; v4 conversion is explicit and preserves originals. CLI defaults are native on fresh installations, parent effort is an explicit policy preserved by migration. Enablement is the conjunction of harness/role/binding gates. Reset never enables. Destructive previews revalidate owned files/settings and partial deletion remains blocked. Existing runs, workflows, doctor and optional legacy purge remain. Real user settings are never automatically migrated.
+
+> Next agent: full implementation map is `docs/ARCHITECTURE_SNAPSHOT.md` (current v5 configuration and runtime map). Keep this file and `AGENTS.md` as the persistent breadcrumbs. Files under `docs/plans/` are dated records. They are not rewritten, and they are not a second runtime contract. Where a plan disagrees with `AGENTS.md`, this file, `README.md`, or the architecture snapshot, those current docs win.
 
 ## Design stance
 
-Guardrails exist to keep lanes from bleeding into each other (a reviewer that edits, a worker that fixes), not to constrain how a model works. Role bodies stay short: define the job, state the boundary, then get out of the way and trust the model's judgment on approach, depth, and method. The generic `worker` role covers non-coding tasks with no method constraints at all. The shipped roster is five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus `worker`, in memory for `agy`, `claude`, `codex`, `grok`, `muse`, `opencode`, and every registered named Pi harness. Other roles are user-created once through `/external role create`. Authority is the call's `permission`, or `defaultPermission` when the call omits it. The default remains `danger`. A role file cannot raise or lower that tier.
+Guardrails exist to keep lanes from bleeding into each other (a reviewer that edits, a worker that fixes), not to constrain how a model works. Role bodies stay short: define the job, state the boundary, then get out of the way and trust the model's judgment on approach, depth, and method. The generic `worker` role covers non-coding tasks with no method constraints at all. The shipped roster is five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus `worker`, in memory for `agy`, `claude`, `codex`, `grok`, `muse`, `opencode`, and every registered named Pi harness. Other roles are user-created offline through `Roles…` or `/external config role create NAME`; `/external config role assist` is the optional model-assisted interview. Authority is the call's `permission`, or `defaultPermission` when the call omits it. The default remains `danger`. A role file cannot raise or lower that tier.
 
-Role resolution is mechanical, not model-routed. The identity is `<harness>-<role>` (`agy-reviewer` is role `reviewer` on harness `agy`). Precedence is exact override, then shared role, then built-in. The selected role and harness must resolve to that exact identity; unavailable roles report their supported harnesses and do not fall back. Harnesses listed in `disabledHarnesses` are absent from executable discovery and blocked for both `role` and exact `subagent_type`; configuration and overrides remain intact. `disabledProfiles` independently blocks individual identities. Toggles affect new invocations, not active children or frozen workflows. No disabled default silently falls back to another harness. Nonstandard names remain available only through legacy exact `subagent_type`. The resolved profile stays authoritative for its instructions and model. Permission is not stored on the role.
+Role resolution is mechanical, not model-routed. The identity is `<harness>/<role>` (`agy/reviewer` is role `reviewer` on harness `agy`). Legacy exact names are accepted only when unambiguous. Scoped instructions replace shared/built-in instructions; scalar exceptions inherit independently. Explicit compatibility records are selected only through their exact selector. The selected role and harness must resolve to that exact identity; unavailable roles report their supported harnesses and do not fall back. Harness, role, and binding gates combine; enabling one scope does not enable the others. Retained legacy exclusions also block their own targets. Disabled entries remain configured but unavailable to execution. Reset never enables. Toggles affect new invocations, not active children or frozen workflows. No disabled default silently falls back to another harness. Nonstandard names remain available only through legacy exact `subagent_type`. The resolved profile stays authoritative for its instructions and model. Permission is not stored on the role.
 
 The always-visible parent guidance is a compact role catalog and a short operating guide. `external_help` topic `usage` is the worked playbook. Topics `roles`, `permissions`, and `workflow` are the references, returned only when requested. Catalog availability reflects the resolved roster, not CLI installation or authentication.
 
@@ -59,8 +61,8 @@ OpenCode (OpenCode 2 only) runs `run --standalone --format json`, a private per-
 
 ## Known inelegance
 
-<!-- ponytail: shared roles removed the role x harness file product; keep backend-specific prompts in exact overrides. Do not grow a second inheritance language. -->
-Shared roles are one file for every harness. Backend-specific model, tools, budget, or instruction changes are a separate exact override, which replaces that one identity completely. Permission is the call or the global default, not a field on the role. Claude `edit` still denies Bash headlessly, and a pi `edit` child still has no `bash` tool. Ask for `danger` on the call when the task needs a shell. Named Pi harnesses still have no resume and no enforced budget cap. Extensions and MCP stay out. `tools` remains enforceable only on Pi.
+<!-- ponytail: shared roles removed the role x harness file product; scoped Markdown replaces instructions only. Do not grow a second inheritance language. -->
+Shared roles are one file for every harness; execution defaults and sparse exceptions no longer copy bodies. Permission remains call > global default. Native CLI defaults are unresolved by the extension and cannot prove replay equivalence. Pi children still have no resume or enforced budget cap; curated tools are not an OS sandbox. Concurrent settings writers remain last-writer-wins.
 
 ## Evidence boundary