pi-codex-marketplace 0.1.9 → 0.2.0

package/README.md

@@ -2,25 +2,28 @@
 
 Bridge Package for Codex Marketplace compatibility in Pi (`Pi 0.84.2`).
 
-> **One-line:** `pi install npm:pi-codex-marketplace` → `/codex-marketplace` opens a responsive Bridge Ledger with simultaneous Global / Project authority rails, guarded lifecycle transactions, and three-orthogonal Receipt reporting.
+> **One-line:** `pi install npm:pi-codex-marketplace` → `/codex-marketplace` opens a responsive Bridge Ledger with Global authority, guarded lifecycle transactions, and three-orthogonal Receipt reporting.
 
 ## Install
 
 ```bash
-pi install npm:pi-codex-marketplace                    # Global Scope (writes to ~/.pi/agent/settings.json)
-pi install npm:pi-codex-marketplace -l                 # Project Scope (.pi/settings.json)
+pi install npm:pi-codex-marketplace                    # Global package (writes to ~/.pi/agent/settings.json)
+pi install npm:pi-codex-marketplace -l                 # Project package location (.pi/settings.json; Pi host package setting only)
 pi install ./path/to/pi-codex-marketplace              # Local path (try without publishing)
-pi install ./path/to/pi-codex-marketplace -l           # Local path, Project Scope
+pi install ./path/to/pi-codex-marketplace -l           # Local path, Project package location
 pi -e npm:pi-codex-marketplace                         # Ephemeral try without installing (temporary)
 pi update npm:pi-codex-marketplace                     # Update one package
 pi update --all                                        # Update pi + all packages
 pi remove npm:pi-codex-marketplace                     # Remove package
 pi list                                                # List installed packages
-pi config                                              # Enable/disable resources (Tab switches scope)
+pi config                                              # Enable/disable resources
 ```
 
 Source types follow `docs/packages.md`: `npm:` for registry, `git:`/`https://` for git, and absolute/relative paths for local. Ephemeral runs use `pi -e <source>` (not `pi install -e`). This package declares a single `pi` extension entry (`extensions/pi/index.ts`) loaded via `jiti` and requires no build step.
 
+> [!NOTE]
+> `pi install -l` controls where Pi loads this Bridge Package extension from (`.pi/settings.json` vs `~/.pi/agent/settings.json` on the Pi host). Regardless of how Pi installs the package, the Bridge State managed by `pi-codex-marketplace` is always recorded in the single Global Scope (`~/.pi/agent/codex-marketplace/state.json`).
+
 Requirements: **Pi 0.84.2**, **Node >=22.19.0**, **macOS / Linux** (Windows not supported).
 
 ## Usage — `/codex-marketplace` (聚合指令)
@@ -31,39 +34,37 @@ Single aggregated command in Pi TUI, faithful to `prototype/tui-management-flow@
 /codex-marketplace
 ```
 
-TUI mode opens a persistent **Bridge Ledger** instead of a flat action list. Global and Project remain visible as separate authority rails with their State Revisions, counts, Project Trust, health, and the persistent Global Pending Barrier. Navigation is grouped into **Observe**, **Sources**, **Plugins**, **Scope & inheritance**, and **Recovery & receipts**; every action is attached to a canonical scope/object identity rather than dispatched from its translated label.
+TUI mode opens a persistent **Bridge Ledger** instead of a flat action list. The workspace presents the Global authority with its State Revision, counts, and health. Navigation is grouped into **Observe**, **Sources**, **Plugins**, and **Recovery & receipts**; every action is attached to a canonical object identity rather than dispatched from its translated label.
 
-At 120/80 columns the Ledger uses navigation and detail panes; below 64 columns it switches to a single-column drill-down. Use arrows or `j/k` to move, `Enter` to open/activate, `Esc` to go back or cancel, `q`/Ctrl-C to exit, `?` for help, and `g`/`p` to change browsing focus only. Browsing focus never grants mutation authority. On Validation sheets, `d` expands or collapses the full ordered disclosure after the initial verdict and finding counts.
+At 120/80 columns the Ledger uses navigation and detail panes; below 64 columns it switches to a single-column drill-down. Use arrows or `j/k` to move, `Enter` to open/activate, `Esc` to go back or cancel, `q`/Ctrl-C to exit, and `?` for help. On Validation sheets, `d` expands or collapses the full ordered disclosure after the initial verdict and finding counts.
 
-Every mutation uses the shared transaction sequence **`Intent → Validation → Consent → Plan → Commit → Receipt`**. The target authority, State Revision, Validation Snapshot, separate Default-No confirmations, atomic commit boundary, and final Durable / Findings / Runtime outcomes remain visible across the flow. After every completed, declined, blocked, stale, or cancelled action, the workspace re-reads both authoritative state documents, receipts, trust, and barrier inputs before rendering again. Existing `list` / `inspect` and non-TUI summary paths remain non-interactive.
+Every mutation uses the shared transaction sequence **`Intent → Validation → Consent → Plan → Commit → Receipt`**. The target authority, State Revision, Validation Snapshot, separate Default-No confirmations, atomic commit boundary, and final Durable / Findings / Runtime outcomes remain visible across the flow. After every completed, declined, blocked, stale, or cancelled action, the workspace re-reads the authoritative state document and receipts before rendering again. Existing `list` / `inspect` and non-TUI summary paths remain non-interactive.
 
 The Ledger exposes these existing capabilities without changing their lifecycle semantics:
 
-- **檢視 Global / Project 分區** — partitioned list of `Global Scope` (`{getAgentDir()}/codex-marketplace/state.json`, baseline) and `Project Scope` (`{cwd}/.pi/codex-marketplace/state.json`, overlay + sparse overrides). Shows `schemaVersion`, `stateRevision`, partitioned registrations/installations/overrides, empty-state guidance, and provenance notes.
-- **註冊本地 / Git Marketplace…** — local or Git Marketplace Source Registration. Local uses canonical real path; Git uses Canonical Git Locator (credential-free) + Normalized Git Selector (`default` / `branch refs/heads/*` / `tag refs/tags/*` / `commit` lower 40/64 hex) → Resolved Revision. Validation Disclosure shows source, scope, Marketplace name, State Revision, Validation Snapshot fingerprint, entry outcomes, findings summary. **Registration Confirmation** is snapshot+revision bound, Default No. Blocking Findings (Contained Path / Contained Symlink / Budget / duplicate Source Key / locator/selector trust) block the attempt; concurrent same-scope attempt is blocked by Attempt Fence (`FENCE-01`); changed State Revision or snapshot yields `Rejected as Stale` (`STALE-01/02`).
-- **安裝 Compatible Plugin…** — the Plugins ledger is keyed directly by stable **Marketplace Entry ID** (`/plugins/<序號>`), classification, skills, Invocation Policies, and resources; each compatible row exposes `Install Disabled` and `Install and Enable` without reopening a display-label Entry selector. Unavailable rows remain visible with their exact reason (unsupported source kind / parse failure / Invalid / Incompatible / Plugin ID collision). Compatibility Profile v1 classifies every Plugin atomically as Compatible / Incompatible / Invalid; collision never changes classification. `Install Disabled` persists provenance without Activation Confirmation; `Install and Enable` discloses exact Plugin, skill list, Skill Resources, Invocation Policies, `Pi → Project → Global` precedence and findings, then requires a separate **Default No** Activation Confirmation (bound to same snapshot+revision). Re-enabling a disabled Installation repeats validation and confirmation; disabling preserves its Installation ID.
+- **檢視 Global 分區** — single `Global Scope` (`{getAgentDir()}/codex-marketplace/state.json`) workspace. Shows `schemaVersion` (v2), `stateRevision`, registrations/installations, empty-state guidance, and provenance notes.
+- **註冊本地 / Git Marketplace…** — local or Git Marketplace Source Registration. Local uses canonical real path; Git uses Canonical Git Locator (credential-free) + Normalized Git Selector (`default` / `branch refs/heads/*` / `tag refs/tags/*` / `commit` lower 40/64 hex) → Resolved Revision. Validation Disclosure shows source, Marketplace name, State Revision, Validation Snapshot fingerprint, entry outcomes, findings summary. **Registration Confirmation** is snapshot+revision bound, Default No. Blocking Findings (Contained Path / Contained Symlink / Budget / duplicate Source Key / locator/selector trust) block the attempt; concurrent attempt is blocked by Attempt Fence (`FENCE-01`); changed State Revision or snapshot yields `Rejected as Stale` (`STALE-01/02`).
+- **安裝 Compatible Plugin…** — the Plugins ledger is keyed directly by stable **Marketplace Entry ID** (`/plugins/<序號>`), classification, skills, Invocation Policies, and resources; each compatible row exposes `Install Disabled` and `Install and Enable` without reopening a display-label Entry selector. Unavailable rows remain visible with their exact reason (unsupported source kind / parse failure / Invalid / Incompatible / Plugin ID collision). Compatibility Profile v1 classifies every Plugin atomically as Compatible / Incompatible / Invalid; collision never changes classification. `Install Disabled` persists provenance without Activation Confirmation; `Install and Enable` discloses exact Plugin, skill list, Skill Resources, Invocation Policies, `Pi → Global` precedence and findings, then requires a separate **Default No** Activation Confirmation (bound to same snapshot+revision). Re-enabling a disabled Installation repeats validation and confirmation; disabling preserves its Installation ID.
 - **管理已安裝 Plugin（Enable / Disable）…** — toggle Installation State; disabling preserves provenance, enabling re-validates under current profile/ruleset/budget.
-- **建立 / 移除 Scope Override…** — fine-grained Project Scope suppression of inherited Global records (Registration override suppresses marketplace subtree, Installation override suppresses single Plugin). Removing an override reveals the inherited record immediately without mutating the global document. Effective State view marks every record's participation and suppression reason.
-- **檢視 Effective State 與 Projected Skills…** — read-time derived Effective State (`global-baseline + project-additions – overrides`, only `enabled` installations, `project-over-global` Plugin ID precedence) and Projected Skills with Runtime Skill Collision resolution (`Pi → Project Scope → Global Scope` exact name layering, same-scope Bridge colliders all unavailable, only surviving higher-layer skill reserves the name, lower layer survives when no higher contender). Whole-Plugin Blocking Findings block the Plugin; collision affects only that skill; `Available` is established only by independent host evidence (`AVAIL-01`).
-- **Refresh / 更新 Registration… (Marketplace Refresh → Update Candidate → Update Plan Checklist → Apply Update)** — Refresh is non-mutating and produces an Update Candidate when the validated source state differs (Plugin version alone does not; full-commit Git selector ref movement alone does not). Update Plan Checklist requires fresh **Registration Confirmation** + one explicit outcome per Installation (`update` / `disable` / `remove`, with `update` only when a Compatible candidate exists) + **Activation Confirmation** per enabled installation that remains enabled. Commit is a single scope-atomic Lifecycle Operation replacing the Registration's Validation Snapshot and applying every disclosed same-scope consequence without mixing revisions.
-- **Rebind Registration…** — explicitly replace a Registration's locator/selector with fresh validation, Registration Confirmation and a complete Update Plan for every existing Installation; prior activation consent never carries over.
-- **移除 Registration / Installation…** — Registration Removal discloses that all same-scope Installations will be atomically removed; Installation Removal discloses which inherited Installation will become effective afterward.
-- **檢視 Receipt Journal…** — bounded immutable Receipt Journal (redacted, non-authoritative, with active recovery chain preservation across restarts); degraded journal surfaces `JOURNAL-01/02` without changing Persistence Failed outcome, and Repair State can atomically reconstruct validated lines while preserving parsed active chains. An exact active Pending Application chain exposes an Attempt Fence-held Retry Application transaction bound to its scope, State Revision, and Validation Snapshot; missing snapshots remain visible but Retry is disabled in favor of a fresh validated intent, interaction-time drift fails closed without reload, reload failure remains Pending Application, and the chain resolves only after exact post-reload verification.
-- **執行 State Repair…** — explicit, fence-guarded verification for an unreadable state or an exact Persistence Indeterminate recovery chain; it stays visibly disabled for Pending Application, Persistence Failed, and healthy scopes because those require a different Recovery Action. It is never auto-retried.
+- **檢視 Effective State 與 Projected Skills…** — read-time derived Effective State (Global Scope enabled installations) and Projected Skills with Runtime Skill Collision resolution (`Pi → Global Scope` exact name layering: pre-existing Pi skills reserve their names; non-colliding Bridge skills are projected; colliding Bridge skills within the same layer are unavailable). Whole-Plugin Blocking Findings block the Plugin; collision affects only that skill; `Available` is established only by independent host evidence (`AVAIL-01`).
+- **Refresh / 更新 Registration… (Marketplace Refresh → Update Candidate → Update Plan Checklist → Apply Update)** — Refresh is non-mutating and produces an Update Candidate when the validated source state differs (Plugin version alone does not; full-commit Git selector ref movement alone does not). Update Plan Checklist requires fresh **Registration Confirmation** + one explicit outcome per Installation (`update` / `disable` / `remove`, with `update` only when a Compatible candidate exists) + **Activation Confirmation** per enabled installation that remains enabled. Commit is a single atomic Lifecycle Operation replacing the Registration's Validation Snapshot and applying every disclosed consequence without mixing revisions.
+- **Rebind Registration…** — explicitly replace a Registration's locator/selector with fresh validation, Registration Confirmation, and a complete Update Plan for every existing Installation; prior activation consent never carries over.
+- **移除 Registration / Installation…** — Registration Removal discloses that all associated Installations will be atomically removed; Installation Removal removes the selected Installation.
+- **檢視 Receipt Journal…** — bounded immutable Receipt Journal (redacted, non-authoritative, with active recovery chain preservation across restarts); degraded journal surfaces `JOURNAL-01/02` without changing Persistence Failed outcome, and Repair State can atomically reconstruct validated lines while preserving parsed active chains. An exact active Pending Application chain exposes an Attempt Fence-held Retry Application transaction bound to State Revision and Validation Snapshot; missing snapshots remain visible but Retry is disabled in favor of a fresh validated intent, interaction-time drift fails closed without reload, reload failure remains Pending Application, and the chain resolves only after exact post-reload verification.
+- **執行 State Repair…** — explicit, fence-guarded verification for an unreadable state or an exact Persistence Indeterminate recovery chain; it stays visibly disabled for Pending Application, Persistence Failed, and healthy states because those require a different Recovery Action. It is never auto-retried.
 
-Diagnostics throughout are shown with **synchronized ordering** `class → phase → target → pointer → rule` and **closed rule codes** (`CONT-01`, `COMP-02`, `BARRIER-01`, etc.), grouped by severity (`Blocking` / `Validation Warning` / `Operational Notice`). Closed **Recovery Actions** (`Retry` / `Revalidate` / `Refresh` / `Rebind` / `Retry Application` / `Disable` / `Remove` / `Repair State` / `Inspect`) list only the currently safe next step under the exact current State Revision. Every committed operation reports a **three-orthogonal Attempt Summary** (`Completed` / `Completed with diagnostics` / `Declined` / `Blocked` / `Rejected as Stale` / `Persistence Failed` / `Persistence Indeterminate` / `Pending Application`) with separate persistence, findings, and runtime (`Applied` / `Pending Application` / `none`) diagnostics. A post-commit `reload` is attempted immediately; if not host-verifiable at the expected revision it is reported as `Pending Application` and no inspection or Refresh supersedes it. A held Global Scope Attempt Fence, `Persistence Indeterminate`, or Receipt Journal degradation triggers the **Global Pending Barrier** that blocks every Project Scope mutation/application (but leaves inspection/Refresh available) until global recovery (`global-first`). Pending state is reconciled at startup by producing a new reconciling receipt without implicit retry or rollback.
+Diagnostics throughout are shown with **synchronized ordering** `class → phase → target → pointer → rule` and **closed rule codes** (`CONT-01`, `COMP-02`, `FENCE-01`, `MIGRATE-01`, etc.), grouped by severity (`Blocking` / `Validation Warning` / `Operational Notice`). Closed **Recovery Actions** (`Retry` / `Revalidate` / `Refresh` / `Rebind` / `Retry Application` / `Disable` / `Remove` / `Repair State` / `Inspect`) list only the currently safe next step under the exact current State Revision. Every committed operation reports a **three-orthogonal Attempt Summary** (`Completed` / `Completed with diagnostics` / `Declined` / `Blocked` / `Rejected as Stale` / `Persistence Failed` / `Persistence Indeterminate` / `Pending Application`) with separate persistence, findings, and runtime (`Applied` / `Pending Application` / `none`) diagnostics. A post-commit `reload` is attempted immediately; if not host-verifiable at the expected revision it is reported as `Pending Application` and no inspection or Refresh supersedes it. Pending state is carried by active recovery chains (Retry Application and other Recovery Actions) and is reconciled at startup by producing a new reconciling receipt without implicit retry or rollback.
 
 ## Bridge State storage & migration
 
-Bridge State is the sole authority, stored as **two scope-local documents**:
+Bridge State is the sole authority, stored in a **single Global Scope document** at `{getAgentDir()}/codex-marketplace/state.json` (`~/.pi/agent/codex-marketplace/state.json`):
 
 ```jsonc
 {
-  "schemaVersion": 1,
-  "stateRevision": "1", // opaque monotonic per scope (string "0" -> "1" -> "2" ...)
+  "schemaVersion": 2,
+  "stateRevision": "1", // opaque monotonic (string "0" -> "1" -> "2" ...)
   "registrations": [],  // immutable Registration ID = UUIDv4 allocated before preflight
-  "installations": [], // Installed Plugins (enabled/disabled), each bound to a Validation Snapshot
-  "scopeOverrides": [] // Project-only: sparse suppression of Global records
+  "installations": []   // Installed Plugins (enabled/disabled), each bound to a Validation Snapshot
 }
 ```
 
@@ -72,15 +73,11 @@ Only authoritative fields are persisted. `Effective State`, catalogs, compatibil
 - `State Revision` increments monotonically under file lock; commit is CAS-guarded by `expectedStateRevision` when supplied.
 - Writes are **atomic**: `write-to-temp → fsync → rename` + `fsync` parent dir + **file lock** (`.lock` sibling) + **WAL** (`state.json.wal`) + **read-after-verify**.
 - Cross-process concurrency is safe: lock serializes RMW; rename prevents torn reads; per-fingerprint `flock` guards Source Cache fetches with `p50 <200ms` on cache hit.
-- **WAL migration** (`src/bridge-state/migrate.ts`): supported forward migrations are applied atomically via WAL (`state.json.wal` fsynced before commit, replayed on the next read after a crash, cleaned after commit success). Migrations are **non-waivable, opt-in per version**, require no implicit activation, and preserve the active recovery chain. Unknown/older-without-path and newer (`schemaVersion > CURRENT_SCHEMA_VERSION`) versions are treated as **incompatible** — fail-closed, no auto-migration, no rollback. **Downgrade never writes back** (`isDowngradeAttempt` guard): a newer durable file is never overwritten by an older Bridge Package; the operator must update the package first.
+- **WAL migration** (`src/bridge-state/migrate.ts`): supported forward migrations are applied atomically via WAL (`state.json.wal` fsynced before commit, replayed on the next read after a crash, cleaned after commit success). Migrations are **non-waivable, opt-in per version**, require no implicit activation, and preserve the active recovery chain. Schema v1 → v2 migration strips legacy `scopeOverrides` (non-empty overrides generate a non-blocking `MIGRATE-01` diagnostic finding without fail-closed) and normalizes Installation IDs (stripping legacy `global/` prefix). Unknown/older-without-path and newer (`schemaVersion > CURRENT_SCHEMA_VERSION`) versions are treated as **incompatible** — fail-closed, no auto-migration, no rollback. **Downgrade never writes back** (`isDowngradeAttempt` guard): a newer durable file is never overwritten by an older Bridge Package; the operator must update the package first.
 - Corrupted / unknown `schemaVersion` → classified as **corrupted / incompatible (Persistence Indeterminate)**, **never auto-rollback** — fail-closed. `validateSchema` and `migrateForward` enforce the closed set `CORRUPTED_JSON` / `INVALID_SCHEMA` / `INCOMPATIBLE_SCHEMA_VERSION` / `UNKNOWN_OLD_VERSION` / `MIGRATION_FAILED`.
 
 See `src/bridge-state/` for `store.ts`, `atomic.ts`, `schema.ts`, `migrate.ts`, `paths.ts`.
 
-## Project Trust
-
-Project Scope mutations and Effective-State participation require Pi's `Project Trust` (host-owned, never granted/persisted by this package). Without trust, project records remain stored but excluded from Effective State and no Project Scope Lifecycle Operation may mutate them.
-
 ## Support matrix
 
 | Dimension | Supported | Notes |
@@ -109,12 +106,12 @@ Every row is a **release blocker**: `v*` may not publish unless the full matrix
 | unit | **synthetic** | macOS + Linux | 22.19.0 | — | selector/locator normalization, Contained Path/Symlink, budget, compatibility atomic classification, precedence, collision, fence/sync ordering |
 | unit | **pinned** `SamWang32191/codex-plugins@98e78ca` | macOS + Linux | 22.19.0 | — | catalog parsing + validation against a real pinned marketplace snapshot (fingerprint-stable) |
 | unit | **adversarial** | macOS + Linux | 22.19.0 | — | malformed manifests, path-escapes, symlink loops, budget overflows, ID collisions, parser depth |
-| integration | synthetic | macOS + Linux | 22.19.0 | 0.84.2 | Bridge State atomic WAL + file lock + read-after-verify, Cache pinning/LRU/flock, Receipt Journal rebuild & prune (active chain), Global Barrier |
+| integration | synthetic | macOS + Linux | 22.19.0 | 0.84.2 | Bridge State atomic WAL + file lock + read-after-verify, Cache pinning/LRU/flock, Receipt Journal rebuild & prune (active chain) |
 | integration | pinned | macOS + Linux | 22.19.0 | 0.84.2 | Git acquisition (non-executing), Snapshot fingerprinting, Installation dual-path, Effective State, projection/collision, Refresh/Rebind/Removal WAL commit |
-| integration | adversarial | macOS + Linux | 22.19.0 | 0.84.2 | Source Drift (Blocking), Stale Snapshot rejection, Persistence Indeterminate fail-closed, Fence/Barrier admission, Cache stale-snapshot never promotes |
-| E2E (highest seam — **TUI**) | synthetic | macOS + Linux | 22.19.0 | **0.84.2** | `/codex-marketplace` → Bridge Ledger custom component → structured scope/object intent → transaction sheet → commit → authoritative reload → three-orthogonal Receipt |
-| E2E (highest seam — **TUI**) | pinned | macOS + Linux | 22.19.0 | **0.84.2** | full lifecycle (Register → Install Disabled / Install and Enable → Disable/Enable → Refresh → Update Plan Checklist → Apply Update / Rebind → Removal → Override → Barrier) with fence/cache/external observability |
-| E2E (highest seam — **TUI**) | adversarial | macOS + Linux | 22.19.0 | **0.84.2** | collision (`Pi → Project → Global`), barrier (`Global Pending` blocks project, Refresh/inspect still allowed), cache (`offline exact fingerprint hit` vs `stale never success`) |
+| integration | adversarial | macOS + Linux | 22.19.0 | 0.84.2 | Source Drift (Blocking), Stale Snapshot rejection, Persistence Indeterminate fail-closed, Fence admission, Cache stale-snapshot never promotes |
+| E2E (highest seam — **TUI**) | synthetic | macOS + Linux | 22.19.0 | **0.84.2** | `/codex-marketplace` → Bridge Ledger custom component → structured object intent → transaction sheet → commit → authoritative reload → three-orthogonal Receipt |
+| E2E (highest seam — **TUI**) | pinned | macOS + Linux | 22.19.0 | **0.84.2** | full lifecycle (Register → Install Disabled / Install and Enable → Disable/Enable → Refresh → Update Plan Checklist → Apply Update / Rebind → Removal) with fence/cache/external observability |
+| E2E (highest seam — **TUI**) | adversarial | macOS + Linux | 22.19.0 | **0.84.2** | collision (`Pi → Global`), cache (`offline exact fingerprint hit` vs `stale never success`) |
 
 Fixtures: `tests/fixtures/synthetic/`, `tests/fixtures/pinned/` (captured `SamWang32191/codex-plugins@98e78ca` snapshot + fingerprint manifest), `tests/fixtures/adversarial/` (path-escape / symlink-loop / budget-overflow / malformed frontmatter corpora). See `tests/acceptance/` for the matrix runner that enforces per-row gating (any row failure blocks publish).