pi-codex-marketplace 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,134 @@
+# pi-codex-marketplace
+
+Bridge Package for Codex Marketplace compatibility in Pi (`Pi 0.84.2`).
+
+> **One-line:** `pi install pi-codex-marketplace` → `/codex-marketplace` shows Global / Project partitioned Bridge State and lifecycle controls with Validation Disclosure, dual Confirmation, and three-orthogonal Receipt reporting.
+
+## Install
+
+```bash
+pi install pi-codex-marketplace            # Global Scope (writes to ~/.pi/agent/settings.json)
+pi install -l pi-codex-marketplace         # Project Scope (.pi/settings.json)
+pi install -e ./path/to/pi-codex-marketplace  # External link (try without publishing)
+pi update pi-codex-marketplace             # Update to latest compatible Bridge Package
+pi remove pi-codex-marketplace             # Remove Registration + Installations atomically
+pi -e ./path/to/repo                       # Ephemeral run without installing
+```
+
+All `pi install / -e / -l / update / remove` semantics are handled by the Pi host; this package declares a single `pi` extension entry (`extensions/pi/index.ts`) loaded via `jiti` and requires no build step.
+
+Requirements: **Pi 0.84.2**, **Node >=22.19.0**, **macOS / Linux** (Windows not supported).
+
+## Usage — `/codex-marketplace` (聚合指令)
+
+Single aggregated command in Pi TUI, faithful to `prototype/tui-management-flow@c9107d2`:
+
+```
+/codex-marketplace
+```
+
+混合發現/導向 (hybrid discovery/guided) flow — every mutation forces **explicit scope choice → Validation Disclosure → State Revision + Validation Snapshot bound confirmation (Default No, never remembered/batched) → scope-atomic commit → immediate reload → three-orthogonal Receipt report**:
+
+- **檢視 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…** — browse registered Marketplace Entries by **Marketplace Entry ID** (`/plugins/<序號>`) with explicit Unavailable 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.
+- **管理已安裝 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.
+- **執行 State Repair…** — explicit, fence-guarded verification and recovery of a degraded Bridge State; 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.
+
+## Bridge State storage & migration
+
+Bridge State is the sole authority, stored as **two scope-local documents**:
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "stateRevision": "1", // opaque monotonic per scope (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
+}
+```
+
+Only authoritative fields are persisted. `Effective State`, catalogs, compatibility results, diagnostics are **derived at read time**.
+
+- `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.
+- 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 |
+|-----------|-----------|-------|
+| OS | **macOS**, **Linux** | Windows not supported (path containment, symlink, `flock` semantics are POSIX-only) |
+| Node | **>=22.19.0** | `engines.node` enforced; `npm-shrinkwrap.json` pins Pi 0.84.2 host |
+| Pi host | **0.84.2** | `peerDependencies` exact `0.84.2`; expected compatible range `^0.84.2` (devDeps). `pi-ai`/`pi-tui` peers `*` per Pi extension docs. |
+| Semantics | `pi install` / `pi install -e` / `pi install -l` / `pi update` / `pi remove` | Single `pi` extension package; `files` ships `extensions/`, `src/`, `README.md`, `LICENSE` only |
+
+Peer declaration (dual): **精確 `0.84.2`** in `peerDependencies` (exact host that this version was validated against) + **預期 `^0.84.2`** in `devDependencies` (range expected to remain compatible). `pi-ai` and `pi-tui` remain `*` because they are bundled by Pi.
+
+## Versioning & release flow
+
+- **Package**: `pi-codex-marketplace` published to **npm** as primary, **Git tag** `v*` as mirror.
+- **SemVer**: starts at `0.1.0`; `0.y` maintenance window until `1.0.0` signals a stable Bridge State contract.
+- **schemaVersion is bound to the package version**: bumping `schemaVersion` requires a package version bump and a WAL migration entry in `src/bridge-state/migrate.ts`; unknown `schemaVersion` is incompatible and never silently accepted.
+- **Publishing**: `v*` tag → CI **full matrix green** (below) is a **release gate** → `npm publish --provenance` (OIDC). `latest` tracks stable tags (`v0.*` stable line and later `v1.*`); `next` tracks pre-release tags. Provenance is required (`--provenance`) and verified post-publish by the publish workflow. See `.github/workflows/ci.yml` and `.github/workflows/publish.yml`.
+- **Maintenance windows**: `0.y` (current) may include additive schema migrations with WAL forward paths; `1.0` will freeze the `schemaVersion` contract and only accept forward-compatible additive changes via new `schemaVersion`s.
+
+## Verification matrix (發版阻擋 gate)
+
+Every row is a **release blocker**: `v*` may not publish unless the full matrix is green.
+
+| Layer | Fixture | OS | Node | Pi host | What is covered |
+|-------|---------|----|------|---------|-----------------|
+| 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 | 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` → scope choice → disclosure → confirmation → commit → reload → receipt (three-orthogonal) → partitioned list → skill-granular `Available` |
+| 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`) |
+
+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).
+
+Run locally:
+
+```bash
+npm run typecheck
+npm test                          # full matrix (unit + integration + E2E)
+npm run test:acceptance           # acceptance matrix only (three-tier × three-fixture)
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run test:acceptance
+```
+
+## Domain vocabulary
+
+Canonical terms are defined in [`CONTEXT.md`](./CONTEXT.md) — use them verbatim (Bridge Package vs Bridge Extension, Bridge State vs Effective State, State Revision, Registration ID, Source Key, etc.).
+
+## Changelog & Releases
+
+See [`CHANGELOG.md`](./CHANGELOG.md) and [GitHub Releases](../../releases). Version `0.1.0` is the first SemVer release; Git tags mirror npm versions (`v0.1.0` → `0.1.0`).

package/extensions/pi/git-registration.ts

@@ -0,0 +1,138 @@
+/**
+ * Git Marketplace Registration — interactive TUI flow (Issue #18).
+ * Mirrors local registration contract: explicit scope → Git locator + Git Selector
+ * → normalization (Canonical Locator + selector canonical) + Acquisition Trust Base + snapshot
+ * → Validation Disclosure → Registration Confirmation (Snapshot+Revision bound, Default No) → atomic commit → Attempt Receipt.
+ */
+
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import type { ExtensionCommandContext, ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth } from '@earendil-works/pi-tui';
+
+import {
+  preflightGitRegistration,
+  confirmGitRegistration,
+  disclosureSummaryGit,
+} from '../../src/registration/git-flow.js';
+import type { GitSelectorInput } from '../../src/registration/git-selector.js';
+import type { GitRegistrationOutcome as RegistrationOutcome } from '../../src/registration/git-flow.js';
+import { formatFindings, reportOutcome } from './registration.js';
+
+class DisclosureComponent {
+  private lines: string[];
+  private theme: Theme;
+  private onClose: () => void;
+
+  constructor(lines: string[], theme: Theme, onClose: () => void) {
+    this.lines = lines;
+    this.theme = theme;
+    this.onClose = onClose;
+  }
+
+  handleInput(data: string): void {
+    if (data) this.onClose();
+  }
+
+  render(width: number): string[] {
+    const th = this.theme;
+    const out: string[] = [];
+    out.push('');
+    out.push(truncateToWidth(th.fg('accent', th.bold(' Validation Disclosure (Git) ')) + th.fg('borderMuted', '─'.repeat(Math.max(0, width - 26))), width));
+    for (const ln of this.lines) {
+      out.push(truncateToWidth(`  ${ln}`, width));
+    }
+    out.push('');
+    out.push(truncateToWidth(`  ${th.fg('dim', 'Any key: continue to Registration Confirmation (Default No) · Confirm is snapshot + State Revision bound')}`, width));
+    out.push(truncateToWidth(`  ${th.fg('dim', 'Canonical Locator 與 Git Selector 正規化結果已於上方披露；Acquisition 採 clone --no-checkout 且未執行 hooks/filters/submodules')}`, width));
+    out.push('');
+    return out;
+  }
+
+  invalidate(): void {}
+}
+
+export async function runGitRegistrationFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const ui: ExtensionUIContext = ctx.ui;
+  const scopeChoice = await ui.select('Marketplace Registration (Git) — 選擇 Scope', [
+    'Global Scope',
+    'Project Scope',
+  ]);
+  if (!scopeChoice) {
+    ui.notify('已取消 Git Registration', 'info');
+    return;
+  }
+  const scope: 'global' | 'project' = scopeChoice.startsWith('Global') ? 'global' : 'project';
+
+  const locator = await ui.input('Git Marketplace Locator（https:// 或 ssh:// 或 scp-like user@host:path，無憑證、無 query/fragment）', 'https://github.com/owner/repo.git');
+  if (!locator) {
+    ui.notify('已取消 Git Registration', 'info');
+    return;
+  }
+
+  const selectorKindChoice = await ui.select('Git Selector — 選擇型別', [
+    'default (跟隨遠端預設分支 HEAD)',
+    'branch (→ refs/heads/*)',
+    'tag (→ refs/tags/*)',
+    'commit (小寫完整 40/64 hex)',
+  ]);
+  if (!selectorKindChoice) {
+    ui.notify('已取消 Git Registration', 'info');
+    return;
+  }
+  let selectorInput: GitSelectorInput;
+  if (selectorKindChoice.startsWith('default')) {
+    selectorInput = { kind: 'default' };
+  } else if (selectorKindChoice.startsWith('branch')) {
+    const branch = await ui.input('Branch 名稱（例：main / feature/foo，將正規化為 refs/heads/<name>）', 'main');
+    if (!branch) {
+      ui.notify('已取消 Git Registration', 'info');
+      return;
+    }
+    selectorInput = { kind: 'branch', value: branch };
+  } else if (selectorKindChoice.startsWith('tag')) {
+    const tag = await ui.input('Tag 名稱（例：v1.2.3，將正規化為 refs/tags/<name>）', 'v1.0.0');
+    if (!tag) {
+      ui.notify('已取消 Git Registration', 'info');
+      return;
+    }
+    selectorInput = { kind: 'tag', value: tag };
+  } else {
+    const commit = await ui.input('Commit（完整 40 或 64 hex，將轉為小寫）', 'abc123def456abc123def456abc123def456abcd12');
+    if (!commit) {
+      ui.notify('已取消 Git Registration', 'info');
+      return;
+    }
+    selectorInput = { kind: 'commit', value: commit };
+  }
+
+  const opts = { cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() };
+  const res = await preflightGitRegistration(scope, locator, selectorInput, opts);
+  if (!res.ok) {
+    reportOutcome(ctx, res.outcome);
+    return;
+  }
+
+  const pf = res.preflight;
+  const lines = [
+    ...disclosureSummaryGit(pf).split('\n'),
+    '',
+    ...formatFindings(pf.findings),
+  ];
+
+  if (ctx.mode !== 'tui') {
+    ui.notify('Git Registration 需要 TUI 模式; disclosure:\n' + lines.join('\n'), 'info');
+  } else {
+    await ui.custom<void>(
+      (_tui, theme, _kb, done) =>
+        new DisclosureComponent(lines, theme, () => done(undefined)),
+    );
+  }
+
+  const yes = await ui.confirm(
+    'Registration Confirmation — 預設 No（綁定 State Revision + Validation Snapshot，不可記憶、不可批次）',
+    `確認註冊 ${pf.locator.canonicalUrl}#${pf.selector.canonical} (${pf.resolvedRevision.slice(0, 8)}…) 至 ${scope}？\n${lines.slice(0, 10).join('\n')}`,
+  );
+
+  const outcome = await confirmGitRegistration(pf, yes, opts);
+  reportOutcome(ctx, outcome);
+}

package/extensions/pi/index.ts

@@ -0,0 +1,293 @@
+/**
+ * Bridge Extension — Pi runtime entry for pi-codex-marketplace
+ * Single extension "pi" package, Pi 0.84.2 compatible.
+ *
+ * Provides:
+ * - /codex-marketplace command: partitioned Global Scope / Project Scope empty state
+ * - Bridge State reading via dual-document store (global + project)
+ * - Startup Reconciliation on session_start
+ * - Receipt Journal inspection & State Repair flows
+ *
+ * Domain vocabulary follows CONTEXT.md (Bridge Package, Bridge Extension, Bridge State, State Revision, etc.)
+ */
+
+import type { ExtensionAPI, Theme } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth } from '@earendil-works/pi-tui';
+
+import { readBridgeStateSync } from '../../src/bridge-state/store.js';
+import type { BridgeState, ReadResult } from '../../src/bridge-state/types.js';
+import { runStartupReconciliation } from '../../src/reconciliation/startup.js';
+import { formatThreeOrthogonalReport } from '../../src/registration/receipt.js';
+import { checkGlobalPendingBarrier } from '../../src/barrier/global-barrier.js';
+import { runLocalRegistrationFlow } from './registration.js';
+import { runGitRegistrationFlow } from './git-registration.js';
+import { runPluginInstallationFlow, runPluginStateFlow } from './installation.js';
+import { runRefreshFlow, runRebindFlow, runRemovalFlow } from './lifecycle.js';
+import {
+  runEffectiveStateView,
+  runRemoveScopeOverrideFlow,
+  runScopeOverrideFlow,
+} from './scope-overrides.js';
+import { runReceiptJournalView, runRepairStateFlow } from './journal.js';
+
+// Closed helper to format state summary for disclosure
+function formatStateSummary(result: ReadResult, scopeLabel: string): string {
+  if (result.status === 'missing') {
+    const s = result.state!;
+    return `${scopeLabel}: empty · schema v${s.schemaVersion} · revision ${s.stateRevision} · 0 registrations · 0 installations`;
+  }
+  if (result.status === 'ok') {
+    const s = result.state!;
+    const regCount = s.registrations.length;
+    const instEnabled = s.installations.filter((i) => i.installationState === 'enabled').length;
+    const instDisabled = s.installations.filter((i) => i.installationState === 'disabled').length;
+    const ov = s.scopeOverrides.length;
+    const ovPart = scopeLabel === 'Project Scope' ? ` · ${ov} overrides` : '';
+    return `${scopeLabel}: revision ${s.stateRevision} · ${regCount} registrations · ${instEnabled} enabled / ${instDisabled} disabled${ovPart}`;
+  }
+  if (result.status === 'incompatible') {
+    return `${scopeLabel}: incompatible — ${result.error} (requires newer Bridge Package)`;
+  }
+  return `${scopeLabel}: corrupted — ${result.error} (Persistence Indeterminate, no auto-rollback)`;
+}
+
+class MarketplaceComponent {
+  private theme: Theme;
+  private onClose: () => void;
+  private global: ReadResult;
+  private project: ReadResult;
+  private cwd: string;
+  private width?: number;
+  private cached?: string[];
+
+  constructor(
+    global: ReadResult,
+    project: ReadResult,
+    cwd: string,
+    theme: Theme,
+    onClose: () => void,
+  ) {
+    this.global = global;
+    this.project = project;
+    this.cwd = cwd;
+    this.theme = theme;
+    this.onClose = onClose;
+  }
+
+  handleInput(data: string): void {
+    if (data === '\x1b' || data === 'q' || data === '\x03') {
+      this.onClose();
+    }
+  }
+
+  render(width: number): string[] {
+    if (this.cached && this.width === width) return this.cached;
+    const th = this.theme;
+    const lines: string[] = [];
+    const hr = th.fg('borderMuted', '─'.repeat(Math.max(0, width - 2)));
+
+    lines.push('');
+    lines.push(truncateToWidth(th.fg('accent', th.bold(' Codex Marketplace ')) + th.fg('borderMuted', '─'.repeat(Math.max(0, width - 22))), width));
+    lines.push(truncateToWidth(`  ${th.fg('dim', 'Bridge State · partitioned by Global Scope / Project Scope · State Revision per scope · Effective State derived at read time')}`, width));
+    lines.push('');
+
+    // Global Section
+    lines.push(truncateToWidth(`  ${th.fg('accent', '▸ Global Scope')}  ${th.fg('dim', formatStateSummary(this.global, 'Global Scope'))}`, width));
+    lines.push(truncateToWidth(`    ${th.fg('dim', 'Global document: {getAgentDir()}/codex-marketplace/state.json — authoritative fields only: schemaVersion / stateRevision / registrations / installations / scopeOverrides')}`, width));
+    if (this.global.status === 'ok' || this.global.status === 'missing') {
+      const s: BridgeState = this.global.state!;
+      if (s.registrations.length === 0 && s.installations.length === 0) {
+        lines.push(truncateToWidth(`    ${th.fg('muted', '— No marketplace registrations —')}`, width));
+        lines.push(truncateToWidth(`    ${th.fg('dim', 'Empty registration list — use the Registration flow (「註冊本地 Marketplace…」menu) to add a local Marketplace Source. Each Registration gets an immutable Registration ID (UUIDv4) before preflight.')}`, width));
+        lines.push(truncateToWidth(`    ${th.fg('dim', 'Projected Plugins will appear here once installations are created. Collision is per-skill; whole-Plugin classification is atomic.')}`, width));
+      } else {
+        for (const r of s.registrations) {
+          lines.push(truncateToWidth(`    ${th.fg('text', `• ${r.alias ?? r.marketplaceName ?? r.id.slice(0, 8)}`)} ${th.fg('dim', `(${r.sourceKind ?? 'unknown'} · ${r.id.slice(0, 8)}…)`)}`, width));
+        }
+        for (const inst of s.installations) {
+          const badge = inst.installationState === 'enabled' ? th.fg('success', 'enabled') : th.fg('dim', 'disabled');
+          lines.push(truncateToWidth(`      ${th.fg('muted', inst.pluginId)} — ${badge}`, width));
+        }
+      }
+    } else {
+      lines.push(truncateToWidth(`    ${th.fg('error', this.global.status === 'incompatible' ? 'Incompatible schema — update Bridge Package' : 'Persistence Indeterminate — file corrupted, no auto-rollback')}`, width));
+      if (this.global.error) lines.push(truncateToWidth(`    ${th.fg('dim', this.global.error)}`, width));
+    }
+    lines.push('');
+
+    // Project Section
+    lines.push(truncateToWidth(`  ${th.fg('accent', '▸ Project Scope')}  ${th.fg('dim', formatStateSummary(this.project, 'Project Scope'))}`, width));
+    lines.push(truncateToWidth(`    ${th.fg('dim', `Project document: ${this.cwd}/.pi/codex-marketplace/state.json — Project Trust gates mutation/effective participation; overrides suppress Global without mutating it`)}`, width));
+    if (this.project.status === 'ok' || this.project.status === 'missing') {
+      const s: BridgeState = this.project.state!;
+      if (s.registrations.length === 0 && s.installations.length === 0 && s.scopeOverrides.length === 0) {
+        lines.push(truncateToWidth(`    ${th.fg('muted', '— No project registrations —')}`, width));
+        lines.push(truncateToWidth(`    ${th.fg('dim', 'Project Scope inherits Global registrations via Effective State; add project-local registrations or Scope Overrides to diverge.')}`, width));
+        lines.push(truncateToWidth(`    ${th.fg('dim', 'Overrides are sparse, keyed by Registration ID / Installation ID; removing an override reveals the inherited Global record.')}`, width));
+      } else {
+        for (const r of s.registrations) {
+          lines.push(truncateToWidth(`    ${th.fg('text', `• ${r.alias ?? r.marketplaceName ?? r.id.slice(0, 8)}`)} ${th.fg('dim', `(${r.sourceKind ?? 'unknown'} · ${r.id.slice(0, 8)}…)`)}`, width));
+        }
+        for (const inst of s.installations) {
+          const badge = inst.installationState === 'enabled' ? th.fg('success', 'enabled') : th.fg('dim', 'disabled');
+          lines.push(truncateToWidth(`      ${th.fg('muted', inst.pluginId)} — ${badge}`, width));
+        }
+        for (const ov of s.scopeOverrides) {
+          lines.push(truncateToWidth(`    ${th.fg('warning', `⊘ override ${ov.kind} ${ov.targetId.slice(0, 8)}…`)}`, width));
+        }
+      }
+    } else {
+      lines.push(truncateToWidth(`    ${th.fg('error', this.project.status === 'incompatible' ? 'Incompatible schema — update Bridge Package' : 'Persistence Indeterminate — file corrupted, no auto-rollback')}`, width));
+      if (this.project.error) lines.push(truncateToWidth(`    ${th.fg('dim', this.project.error)}`, width));
+    }
+
+    lines.push('');
+    lines.push(truncateToWidth(hr, width));
+    lines.push(truncateToWidth(`  ${th.fg('dim', 'Bridge State holds only registrations / installations (with Installation State) / scopeOverrides / schemaVersion / stateRevision. Effective State, catalogs, compatibility, diagnostics are recomputed.')}`, width));
+    lines.push(truncateToWidth(`  ${th.fg('dim', 'State Revision is opaque monotonic per scope; writes are atomic (temp→fsync→rename) under file lock with read-after-verify. Corrupted/unknown schema ⇒ Indeterminate/incompatible, never auto-rollback.')}`, width));
+    lines.push(truncateToWidth(`  ${th.fg('dim', 'Scope Override / Effective State / Runtime Skill Collision flows are available: 建立或移除 Override、檢視投影與碰撞診斷。Available 僅由宿主獨立證據確立。')}`, width));
+    lines.push('');
+    lines.push(truncateToWidth(`  ${th.fg('dim', 'Press Esc / q to close · 選擇相應選單以執行完整驗證、Attempt Summary 與 Recovery Action 的操作流程。')}`, width));
+    lines.push('');
+
+    this.width = width;
+    this.cached = lines;
+    return lines;
+  }
+
+  invalidate(): void {
+    this.cached = undefined;
+    this.width = undefined;
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on('session_start', async (_event, ctx) => {
+    // Startup reconciliation: Global-first pass
+    try {
+      const recon = await runStartupReconciliation({
+        cwd: ctx.cwd,
+        projectTrusted: ctx.isProjectTrusted(),
+      });
+      if (recon.globalReconciled && recon.globalReceipt) {
+        ctx.ui.notify(formatThreeOrthogonalReport(recon.globalReceipt), recon.globalReceipt.summary === 'Completed' ? 'info' : 'warning');
+      }
+      if (recon.projectReconciled && recon.projectReceipt) {
+        ctx.ui.notify(formatThreeOrthogonalReport(recon.projectReceipt), recon.projectReceipt.summary === 'Completed' ? 'info' : 'warning');
+      }
+    } catch {
+      // Non-blocking in extension bootstrap
+    }
+  });
+
+  pi.registerCommand('codex-marketplace', {
+    description: 'Manage Codex Marketplaces — partitioned Global / Project Bridge State + lifecycle controls (prototype tui-management-flow@c9107d2)',
+    handler: async (args, ctx) => {
+      const cwd = ctx.cwd;
+
+      // Hybrid discovery/guided: support /codex-marketplace list|inspect <args> for non-TUI quick paths
+      const rawArgs = (args ?? '').trim();
+      if (rawArgs.length > 0 && (rawArgs.startsWith('list') || rawArgs.startsWith('inspect') || rawArgs === '--help' || rawArgs === '-h')) {
+        const global = readBridgeStateSync('global', { cwd });
+        const project = readBridgeStateSync('project', { cwd });
+        const g = formatStateSummary(global, 'Global Scope');
+        const p = formatStateSummary(project, 'Project Scope');
+        const barrier = await checkGlobalPendingBarrier({ cwd });
+        const banner = barrier.active ? `\n⚠ Global Pending Barrier 活躍：${barrier.reason}（專案變異已阻擋，僅檢查/Refresh 可用）` : '';
+        ctx.ui.notify(`${g}\n${p}${banner}\n(完整導向流請於 TUI 內執行 /codex-marketplace)` , barrier.active ? 'warning' : 'info');
+        return;
+      }
+
+      // Non-TUI fallback: notify with summary + barrier hint
+      if (ctx.mode !== 'tui' || !ctx.hasUI) {
+        const global = readBridgeStateSync('global', { cwd });
+        const project = readBridgeStateSync('project', { cwd });
+        const g = formatStateSummary(global, 'Global Scope');
+        const p = formatStateSummary(project, 'Project Scope');
+        const barrier = await checkGlobalPendingBarrier({ cwd });
+        const banner = barrier.active ? `\n⚠ Global Pending Barrier：${barrier.reason}` : '';
+        ctx.ui.notify(`${g}\n${p}${banner}\n互動流程需 TUI 模式（/codex-marketplace 於 TUI 內）`, barrier.active ? 'warning' : 'info');
+        return;
+      }
+
+      // TUI mode: surface Pending/Global Barrier hint before menu (closed, per prototype Variant C banner)
+      const barrier = await checkGlobalPendingBarrier({ cwd });
+      if (barrier.active) {
+        ctx.ui.notify(`⚠ Global Pending Barrier 已阻擋所有 Project Scope 變異/套用（Reserve Global-first 復原）：${barrier.reason}。仍可執行 檢查 / Refresh。`, 'warning');
+      }
+
+      const choice = await ctx.ui.select('Codex Marketplace — Bridge State', [
+        '檢視 Global / Project 分區',
+        '註冊本地 Marketplace…',
+        '註冊 Git Marketplace…',
+        '安裝 Compatible Plugin…',
+        '管理已安裝 Plugin（Enable / Disable）…',
+        '建立 Scope Override（抑制繼承全域紀錄）…',
+        '移除 Scope Override（還原繼承）…',
+        '檢視 Effective State 與 Projected Skills…',
+        'Refresh / 更新 Registration…',
+        'Rebind Registration（更換來源）…',
+        '移除 Registration / Installation…',
+        '檢視 Receipt Journal（Active Chains 與歷史）…',
+        '執行 State Repair（修復與驗證 Bridge State）…',
+      ]);
+      if (!choice) return;
+
+      if (choice === '註冊本地 Marketplace…') {
+        await runLocalRegistrationFlow(ctx);
+        return;
+      }
+      if (choice === '註冊 Git Marketplace…') {
+        await runGitRegistrationFlow(ctx);
+        return;
+      }
+      if (choice === '安裝 Compatible Plugin…') {
+        await runPluginInstallationFlow(ctx);
+        return;
+      }
+      if (choice === '管理已安裝 Plugin（Enable / Disable）…') {
+        await runPluginStateFlow(ctx);
+        return;
+      }
+      if (choice === '建立 Scope Override（抑制繼承全域紀錄）…') {
+        await runScopeOverrideFlow(ctx);
+        return;
+      }
+      if (choice === '移除 Scope Override（還原繼承）…') {
+        await runRemoveScopeOverrideFlow(ctx);
+        return;
+      }
+      if (choice === '檢視 Effective State 與 Projected Skills…') {
+        await runEffectiveStateView(ctx);
+        return;
+      }
+      if (choice === 'Refresh / 更新 Registration…') {
+        await runRefreshFlow(ctx);
+        return;
+      }
+      if (choice === 'Rebind Registration（更換來源）…') {
+        await runRebindFlow(ctx);
+        return;
+      }
+      if (choice === '移除 Registration / Installation…') {
+        await runRemovalFlow(ctx);
+        return;
+      }
+      if (choice === '檢視 Receipt Journal（Active Chains 與歷史）…') {
+        await runReceiptJournalView(ctx);
+        return;
+      }
+      if (choice === '執行 State Repair（修復與驗證 Bridge State）…') {
+        await runRepairStateFlow(ctx);
+        return;
+      }
+
+      const global = readBridgeStateSync('global', { cwd });
+      const project = readBridgeStateSync('project', { cwd });
+
+      await ctx.ui.custom<void>((_tui, theme, _kb, done) => {
+        return new MarketplaceComponent(global, project, cwd, theme, () => done());
+      });
+    },
+  });
+}