pi-codex-marketplace 0.6.2 → 0.7.0

package/README.md

@@ -53,6 +53,28 @@ Nine subcommands, no arguments = 總覽：
 - 安裝成功後由指令層主動要求 reload；reload 失敗不影響已記錄狀態，下次 session start 或 `/reload` 仍生效。
 - `--no-skills` 啟動 Pi 不影響 Bridge 投影。
 
+### Autocomplete（Pi 原生，TUI 限定）
+
+互動（TUI）模式下，`/codex-marketplace` 以 **Pi 原生 autocomplete** 提供兩層、狀態感知的候選。**純文字指令表面維持權威不變**：九個子命令、指令參數、輸出與語意完全不受 autocomplete 影響；RPC／JSON／print 模式根本不註冊 terminal-only provider。
+
+**第一層——九個根層子命令。** 輸入完整的 `/codex-marketplace` 後按 Tab，候選清單顯示全部九個子命令（`add`／`list`／`install`／`update`／`disable`／`enable`／`remove`／`forget`／`help`）與各自說明，支援不分大小寫的模糊搜尋。選取需要參數的子命令（`add`／`list`／`install`／`disable`／`enable`／`remove`／`forget`）會自動補上一個尾隨空格，可直接繼續輸入；`update` 與 `help` 不加。
+
+**第二層——再按一次 Tab 開啟狀態感知候選。** 需要參數的子命令套用後，**再按一次 Tab** 依當下 Bridge State 只列出當下可執行的選項（空集合不給假候選）；**不承諾自動重開 selector**（Pi 0.84.2 在套用候選後不會自動再開一層補完選單，鍵盤流程固定是「輸入 command → Tab 選子命令 → 需要參數時再按一次 Tab」）：
+
+| 子命令 | 候選範圍 | 歧義處理 |
+|--------|----------|----------|
+| `install` | 可安裝／可重裝的 plugin（**不含 Unavailable Entry**） | 名稱在完整 enumeration 唯一＝插入名稱；同名（含 unavailable sibling）＝插入 enumeration 編號（`#N`），描述顯示 `[marketplace]` 與狀態 |
+| `enable` | 僅**已停用**的 Installation | 名稱無法唯一解析的記錄不給候選 |
+| `disable` | 僅**已啟用**的 Installation | 同上 |
+| `remove` | 全部已安裝 plugin（不分啟用／停用） | 同上 |
+| `list` | Marketplace Registrations | 名稱無法唯一解析＝依序改插唯一可解析的 alias、其次 Registration id |
+| `forget` | Marketplace Registrations | 同上 |
+| `add` | **不提供 Bridge 候選**：Tab 委派 Pi 原生路徑 completion，Git locator 維持自由輸入 | — |
+
+補完只提議當下可執行的動作，候選反映最新 Bridge State，且**被動讀取**——按 Tab 絕不會重置或重寫損壞的 state 文件。其餘輸入（其他 slash 指令、一般文字、檔案／路徑補完）一律原樣委派 Pi 既有 provider；安裝本套件不影響任何其他指令的 autocomplete。
+
+> 沒有 custom TUI、沒有自動第二層 selector：所有操作也都可以照舊以純文字輸入完成，autocomplete 只是 discoverability 與輸入效率層。
+
 ### 私有 Git repo：Credentialed Acquisition（核准式取得）
 
 對私有 HTTPS repo，`add`／`update` **開箱即用**：預設會自動偵測本機已存在的憑證來源並逐次核准（**固定白名單**，不讀本機 gitconfig 的任意 helper；偵測結果只限該次呼叫、永不持久化）：

package/extensions/pi/autocomplete.ts

@@ -0,0 +1,90 @@
+/**
+ * Narrow Bridge autocomplete provider — thin Pi adapter (TUI session only) (#119, #121–#124).
+ *
+ * Pi 0.84.2's built-in combined provider completes the slash-command name and inserts a
+ * trailing space without exposing empty-prefix argument completion (root subcommands) when
+ * the editor holds exactly `/codex-marketplace`. This wrapper intercepts that exact editor
+ * content and presents the nine root candidates. It also owns the second-level argument
+ * contexts (`install` #122, the Installation lifecycle `enable` / `disable` / `remove` #123,
+ * and the Marketplace Registration `list` / `forget` #124) on forced (Tab) requests, which
+ * Pi 0.84.2 routes to file completion instead of slash-command argument completion (its
+ * argument path only runs when `force` is false) — the wrapper returns the state-aware
+ * candidates there. `add` stays free-form (#124): its forced Tab keeps Pi's native
+ * filesystem completion, and a typed Git locator or path is never constrained by Bridge
+ * candidates. Everything else — other slash commands, text, file/path completion, suggestion
+ * generation and completion application — delegates unchanged to the host's current provider.
+ *
+ * The wrapper is installed from a `session_start` handler via `ctx.ui.addAutocompleteProvider`,
+ * which interactive (TUI) mode wires into the editor and RPC/JSON/print modes no-op, so a
+ * terminal-only provider is never registered outside a TUI session.
+ */
+
+import type { AutocompleteProvider } from '@earendil-works/pi-tui';
+
+import { completeArguments, type CompletionReadOptions } from '../../src/bridge/completion.js';
+
+/** The exact editor content this provider owns. */
+export const EXACT_COMMAND = '/codex-marketplace';
+
+/**
+ * The Bridge-owned second-level argument contexts on forced requests: `install` plus the
+ * installation lifecycle actions plus the Marketplace Registration commands — each followed
+ * by the trailing space root candidates insert. `add` is deliberately absent (#124): its
+ * argument is an arbitrary path or Git locator that stays under Pi's native completion.
+ */
+export const SECOND_LEVEL_ARGUMENT_RE = /^\/codex-marketplace (?:install|list|forget|enable|disable|remove) /;
+
+/**
+ * Wrap the host's current autocomplete provider. Suggestion generation intercepts only the
+ * Bridge-owned editor contexts (the exact `/codex-marketplace` line and the forced `install `
+ * argument context); completion application and file-trigger decisions delegate to the
+ * current provider's semantics, so selection behavior stays Pi-native.
+ */
+export function createBridgeAutocompleteProvider(
+  current: AutocompleteProvider,
+  readOptions: CompletionReadOptions = {},
+): AutocompleteProvider {
+  return {
+    async getSuggestions(lines, cursorLine, cursorCol, options) {
+      const line = lines[cursorLine] ?? '';
+      // Root-level interception (#121): only when the editor content is exactly the complete
+      // command text — a mid-command cursor or trailing text after the command is not
+      // "editor 內容恰為 /codex-marketplace" and must fall through to the host provider.
+      if (line === EXACT_COMMAND && cursorCol === EXACT_COMMAND.length) {
+        const items = completeArguments('', readOptions);
+        if (items && items.length > 0) {
+          // The intercepted prefix is the whole line before the cursor (prefix ''), so the
+          // insertion value must carry the separator space the editor content lacks.
+          return {
+            items: items.map((item) => ({ ...item, value: ` ${item.value}` })),
+            prefix: '',
+          };
+        }
+      }
+      // Second-level argument interception (#122, #123, #124): forced (Tab) requests inside a
+      // Bridge-owned argument context (`install ` / `enable ` / `disable ` / `remove ` /
+      // `list ` / `forget `) are Bridge-owned — the host's combined provider would route them
+      // to file completion. Natural typing (force=false) is delegated and reaches the same
+      // candidates through the command's getArgumentCompletions. Like the root branch, the
+      // cursor must be at the end of the line: a mid-line cursor with trailing text would
+      // otherwise produce a malformed line after applying a candidate. The prefix returned is
+      // the text after the command name (`install <query>` etc.), matching the host's
+      // argument-text semantics. `add ` is not Bridge-owned (#124), so a forced Tab there
+      // falls through to the host provider's filesystem completion unchanged.
+      if (options.force && cursorCol === line.length && SECOND_LEVEL_ARGUMENT_RE.test(line)) {
+        const argumentText = line.slice(EXACT_COMMAND.length + 1, cursorCol);
+        const items = completeArguments(argumentText, readOptions);
+        if (items) {
+          return { items, prefix: argumentText };
+        }
+      }
+      return current.getSuggestions(lines, cursorLine, cursorCol, options);
+    },
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}

package/extensions/pi/index.ts

@@ -14,8 +14,22 @@ import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-c
 
 import { runCommand } from '../../src/bridge/command.js';
 import { discoverProjectedSkillPaths } from '../../src/projection/exposure.js';
+import { completeArguments } from '../../src/bridge/completion.js';
+import { createBridgeAutocompleteProvider } from './autocomplete.js';
 
 export default function (pi: ExtensionAPI) {
+  // Root-level autocomplete (#121) + second-level autocomplete (#122–#124): stack a narrow
+  // provider for the exact `/codex-marketplace` editor text and the forced `install `,
+  // Installation lifecycle (`enable ` / `disable ` / `remove `), and Marketplace Registration
+  // (`list ` / `forget `) argument contexts (Pi otherwise completes just the command name
+  // plus a space, and routes forced argument Tabs to file completion). `add ` stays free-form
+  // (#124): forced Tabs keep Pi's native filesystem completion and typed Git locators are
+  // never constrained. session_start supplies the full TUI ui context;
+  // RPC/JSON/print modes no-op ctx.ui.addAutocompleteProvider, so a terminal-only provider is
+  // never registered outside a TUI session and command execution is unchanged.
+  pi.on('session_start', (_event, ctx) => {
+    ctx.ui.addAutocompleteProvider((current) => createBridgeAutocompleteProvider(current));
+  });
   // Runtime Skill Exposure (ADR 0001): contribute Projected Skills through Pi's
   // resource-discovery seam at every startup and reload. Passive existence inspection over the
   // current Effective State only — no fingerprint validation and no Bridge State mutation.
@@ -33,6 +47,11 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerCommand('codex-marketplace', {
     description: 'codex / claude marketplace 管理（add/list/install/update/disable/enable/remove/forget/help）',
+    // Standard argument completion (#121–#124): typed subcommand and `install <query>` /
+    // lifecycle `<query>` / Registration (`list` / `forget`) `<query>` prefixes go through
+    // Pi's normal autocomplete; unowned syntax (including `add`'s free-form argument) returns
+    // null so Pi falls through to its own behavior.
+    getArgumentCompletions: (argumentPrefix: string) => completeArguments(argumentPrefix),
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const rawArgs = (args ?? '').trim();
       const argv = rawArgs.length > 0 ? rawArgs.split(/\s+/) : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codex-marketplace",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Bridge Package for Codex and Claude Marketplace compatibility in Pi — 極簡 /codex-marketplace 純文字指令（add/list/install/update/disable/enable/remove/forget）、單一 Global Bridge State、當下最新安裝與即時投影",
   "type": "module",
   "keywords": [

package/src/bridge/command.ts

@@ -16,19 +16,22 @@ import {
   readMinimalBridgeState,
   writeMinimalBridgeState,
   type MinimalBridgeState,
-  type MarketplaceFormat,
 } from './state.js';
-import { BUDGET } from '../registration/budget.js';
 import { localSourceKey } from '../registration/source-key.js';
 import {
-  catalogContractFor,
   detectMarketplaceFormat,
   CODEX_MARKETPLACE_CATALOG_RELPATH,
   CLAUDE_MARKETPLACE_CATALOG_RELPATH,
 } from '../registration/format.js';
 import { resolveContained } from '../registration/contained.js';
-import { findEntryByManifestName, GIT_FAMILY_UNAVAILABLE_REASON, type Catalog, type MarketplaceEntry } from '../registration/catalog.js';
-import type { ValidationFinding } from '../registration/findings.js';
+import { findEntryByManifestName } from '../registration/catalog.js';
+import {
+  queryMarketplacePlugins,
+  readMarketplaceCatalog,
+  resolveMarketplaceRoot,
+  type MarketplaceCatalogReadResult,
+  type MarketplacePluginCandidate,
+} from './plugin-query.js';
 import { normalizeGitLocator } from '../registration/git-locator.js';
 import { acquireGitSource, cleanupAcquisition, type GitExecutor } from '../registration/git-acquisition.js';
 import {
@@ -39,7 +42,6 @@ import {
 import { gitSourceKey } from '../registration/source-key.js';
 import { buildGitSnapshot } from '../registration/snapshot.js';
 import { SourceCache } from '../cache/source-cache.js';
-import { getCacheDir, getCacheEntriesDir } from '../cache/paths.js';
 
 export interface CommandOptions {
   statePath?: string;
@@ -61,7 +63,9 @@ export interface CommandResult {
 
 const USAGE_LINE = '用法：/codex-marketplace <add|list|install|update|disable|enable|remove|forget|help>';
 
-const HELP_TEXT = [
+// Exported so the Bridge completion seam can be verified against the same description
+// vocabulary it mirrors (#121) — alignment is pinned by tests, not by manual syncing.
+export const HELP_TEXT = [
   '用法：/codex-marketplace <子命令> [參數]',
   '',
   '子命令：',
@@ -94,29 +98,6 @@ function expandOwnerRepo(input: string): string {
   return `https://github.com/${input.trim()}`;
 }
 
-function catalogRootForReg(
-  reg: MinimalBridgeState['registrations'][number],
-  opts: CommandOptions,
-): string | undefined {
-  if (reg.sourceKind === 'git') {
-    const snap = (reg as unknown as { snapshot?: string }).snapshot;
-    if (!snap || !/^[0-9a-f]{64}$/.test(snap)) return undefined;
-    const entriesDir = getCacheEntriesDir(getCacheDir(opts.agentDir));
-    const p = join(entriesDir, snap);
-    if (!existsSync(p)) return undefined;
-    return p;
-  }
-  return reg.source;
-}
-
-function sourceRootForReg(
-  reg: MinimalBridgeState['registrations'][number],
-  opts: CommandOptions,
-): string | undefined {
-  if (reg.sourceKind === 'git') return catalogRootForReg(reg, opts);
-  return reg.source;
-}
-
 function padRight(str: string, length: number): string {
   return str.length >= length ? str : str + ' '.repeat(length - str.length);
 }
@@ -173,138 +154,18 @@ function formatCatalogError(findings: { code?: string; outcome?: string; rule?:
   return detail;
 }
 
-// ---- Plugin enumeration helpers (#90, #91) ----
-
-interface EnumeratedPlugin {
-  number: number;
-  reg: MinimalBridgeState['registrations'][number];
-  entry: MarketplaceEntry;
-  pluginName: string;
-  status: '可安裝' | '已裝啟用' | '已裝停用' | 'unavailable';
-  unavailableReason?: string;
-}
-
-/**
- * Whether an entry can supply a locally installable plugin on the command surface. Git-family
- * and unsupported source kinds are Unavailable Entries (#91): disclosed with a reason, never
- * silently skipped and never installable.
- */
-function entryLocallyInstallable(entry: MarketplaceEntry): boolean {
-  return (
-    entry.type === 'local' && entry.available === true && typeof entry.path === 'string' && entry.path.length > 0
-  );
-}
-
-function entryUnavailableReason(entry: MarketplaceEntry): string {
-  if (entry.type === 'git' && entry.available !== false) return GIT_FAMILY_UNAVAILABLE_REASON;
-  return entry.unavailableReason ?? 'unsupported source kind';
-}
-
-interface CatalogReadResult {
-  /** Parsed catalog on success (name + entries); also present for some parse failures. */
-  catalog?: Catalog;
-  /** Structural findings from the format-bound parser (present for parse failures too). */
-  findings: ValidationFinding[];
-  /** Disclosed read failure (catalog 缺失／超上限／malformed); never silently skipped. */
-  error?: string;
-}
-
-/**
- * The single catalog reader for the command surface: budget-bounded read + format-bound parse.
- * Read failures produce a disclosed `error` instead of silently skipping (#91).
- */
-function readCatalogForReg(root: string, format: MarketplaceFormat): CatalogReadResult {
-  const contract = catalogContractFor(format);
-  const catalogPath = join(root, ...contract.relPath.split('/'));
-  let raw: string;
-  try {
-    if (!existsSync(catalogPath)) {
-      return { findings: [], error: `catalog 缺失（${contract.relPath}）` };
-    }
-    const size = statSync(catalogPath).size;
-    if (size > BUDGET.maxCatalogBytes) {
-      return {
-        findings: [],
-        error: `catalog 檔案過大（${size} bytes > ${BUDGET.maxCatalogBytes}）— 超過 Validation Budget 上限，catalog 無法解析`,
-      };
-    }
-    raw = readFileSync(catalogPath, 'utf-8');
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    return { findings: [], error: `catalog 無法讀取：${msg}` };
-  }
-  if (!raw.trim()) {
-    return { findings: [], error: `catalog 解析失敗：檔案為空 — catalog malformed` };
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    return { findings: [], error: `catalog 解析失敗：${msg} — catalog malformed` };
-  }
-  const res = contract.parse(parsed);
-  if (!res.ok) {
-    const codes = res.findings.map((f) => f.code).join(', ');
-    return {
-      catalog: res.catalog,
-      findings: res.findings,
-      error: `catalog 解析失敗${codes ? ` (${codes})` : ''} — catalog malformed`,
-    };
-  }
-  return { catalog: res.catalog, findings: res.findings };
-}
-
-interface Enumeration {
-  plugins: EnumeratedPlugin[];
-  catalogErrors: Array<{ marketplace: string; error: string }>;
-}
+// ---- Plugin enumeration presentation (#90, #91, #120) ----
 
-function enumeratePlugins(state: MinimalBridgeState, opts: CommandOptions = {}): Enumeration {
-  const result: EnumeratedPlugin[] = [];
-  const catalogErrors: Enumeration['catalogErrors'] = [];
-  let counter = 1;
-  for (const reg of state.registrations) {
-    const catalogRoot = catalogRootForReg(reg, opts);
-    if (!catalogRoot) {
-      const isGit = reg.sourceKind === 'git';
-      const snap = (reg as unknown as { snapshot?: string }).snapshot;
-      const reason = isGit
-        ? (!snap ? 'git marketplace 缺少 cache 指紋' : `cache 快照缺失（${snap.slice(0, 12)}…）`)
-        : 'catalog 根路徑無法解析';
-      catalogErrors.push({ marketplace: reg.marketplaceName || reg.alias || reg.id, error: reason });
-      continue;
-    }
-    const read = readCatalogForReg(catalogRoot, reg.format ?? 'codex');
-    if (read.error) {
-      // Disclosed read failure (#91): the error line is shown and the marketplace contributes
-      // no entries — a broken catalog never yields installable plugins.
-      catalogErrors.push({ marketplace: reg.marketplaceName || reg.alias || reg.id, error: read.error });
-      continue;
-    }
-    for (const entry of read.catalog?.entries ?? []) {
-      const pluginName = entry.name ?? (entry.path ? basename(entry.path) : `plugin-${entry.ordinal}`);
-      const inst = state.installations.find(
-        (i) => i.registrationId === reg.id && (i.manifestName === pluginName || i.pluginId === pluginName),
-      );
-      let status: EnumeratedPlugin['status'];
-      let unavailableReason: string | undefined;
-      if (!entryLocallyInstallable(entry)) {
-        status = 'unavailable';
-        unavailableReason = entryUnavailableReason(entry);
-      } else if (!inst) status = '可安裝';
-      else if (isInstallationEnabled(inst as any)) status = '已裝啟用';
-      else status = '已裝停用';
-      result.push({ number: counter, reg, entry, pluginName, status, unavailableReason });
-      counter++;
-    }
-  }
-  return { plugins: result, catalogErrors };
+function pluginStatus(plugin: MarketplacePluginCandidate): '可安裝' | '已裝啟用' | '已裝停用' | 'unavailable' {
+  if (!plugin.structurallyInstallable) return 'unavailable';
+  if (plugin.installationState === 'enabled') return '已裝啟用';
+  if (plugin.installationState === 'disabled') return '已裝停用';
+  return '可安裝';
 }
 
 function formatPluginListLines(state: MinimalBridgeState, filter?: string, opts: CommandOptions = {}): string[] {
-  const { plugins: enumeration, catalogErrors } = enumeratePlugins(state, opts);
-  const errorLines = catalogErrors.map((e) => `⚠ marketplace [${e.marketplace}] ${e.error}`);
+  const { plugins: enumeration, diagnostics } = queryMarketplacePlugins(state, opts);
+  const errorLines = diagnostics.map((diagnostic) => `⚠ marketplace [${diagnostic.marketplace}] ${diagnostic.error}`);
   if (enumeration.length === 0) {
     // No plugins at all (e.g., empty catalog, no registrations, or unreadable catalogs):
     // read failures are disclosed, never silently skipped (#91).
@@ -313,7 +174,9 @@ function formatPluginListLines(state: MinimalBridgeState, filter?: string, opts:
   let filtered = enumeration;
   if (filter) {
     filtered = enumeration.filter(
-      (e) => e.reg.marketplaceName === filter || e.reg.alias === filter || e.reg.id === filter,
+      (plugin) => plugin.registration.marketplaceName === filter
+        || plugin.registration.alias === filter
+        || plugin.registration.id === filter,
     );
     if (filtered.length === 0) {
       return [
@@ -324,11 +187,14 @@ function formatPluginListLines(state: MinimalBridgeState, filter?: string, opts:
   }
   const lines: string[] = ['Plugins（編號／所屬 marketplace／狀態）'];
   const show = filter ? filtered : enumeration;
-  for (const e of show) {
-    const num = padRight(` ${e.number}`, 4);
-    const name = padRight(e.pluginName, 18);
-    const mkt = padRight(`[${e.reg.marketplaceName || e.reg.alias || e.reg.id}]`, 20);
-    const status = e.status === 'unavailable' ? `unavailable（${e.unavailableReason ?? 'unavailable'}）` : e.status;
+  for (const plugin of show) {
+    const num = padRight(` ${plugin.number}`, 4);
+    const name = padRight(plugin.candidateName, 18);
+    const mkt = padRight(`[${plugin.marketplaceName}]`, 20);
+    const stateLabel = pluginStatus(plugin);
+    const status = stateLabel === 'unavailable'
+      ? `unavailable（${plugin.unavailableReason ?? 'unavailable'}）`
+      : stateLabel;
     lines.push(`${num}${name}${mkt}${status}`);
   }
   lines.push(...errorLines);
@@ -367,21 +233,20 @@ function findRegistrationIndex(state: MinimalBridgeState, name: string): number
 }
 
 /**
- * Best-effort reread for enable: mirrors install Step1-3 (sourceRoot -> catalogRoot -> readCatalog -> entry -> resolveContained -> collectSkillNames).
+ * Best-effort reread for enable: mirrors install Step1-3 (Marketplace Root -> readCatalog -> entry -> resolveContained -> collectSkillNames).
  * Returns undefined on any missing cache/catalog/entry/path — caller falls back to stored skills.
- * Pure-logic branches (find/entry.path/resolveContained outcome) do not throw; only I/O (readCatalogForReg/collectSkillNames) is try/catch guarded.
+ * Pure-logic branches (find/entry.path/resolveContained outcome) do not throw; only I/O (readMarketplaceCatalog/collectSkillNames) is try/catch guarded.
  */
 function tryRereadSkills(
   reg: MinimalBridgeState['registrations'][number],
   inst: MinimalBridgeState['installations'][number],
   opts: CommandOptions,
 ): string[] | undefined {
-  const sourceRoot = sourceRootForReg(reg, opts);
-  const catalogRoot = catalogRootForReg(reg, opts);
-  if (!sourceRoot || !catalogRoot) return undefined;
-  let read: CatalogReadResult | undefined;
+  const marketplaceRoot = resolveMarketplaceRoot(reg, opts);
+  if (!marketplaceRoot) return undefined;
+  let read: MarketplaceCatalogReadResult | undefined;
   try {
-    read = readCatalogForReg(catalogRoot, reg.format ?? 'codex');
+    read = readMarketplaceCatalog(marketplaceRoot, reg.format ?? 'codex');
   } catch {
     // best-effort: catalog 讀取/解析失敗（cache 缺失或損毀）則沿用舊 skills
     return undefined;
@@ -389,7 +254,7 @@ function tryRereadSkills(
   if (read.error || !read.catalog) return undefined;
   const entry = findEntryByManifestName(read.catalog, inst.manifestName);
   if (!entry?.path) return undefined;
-  const contained = resolveContained(sourceRoot, entry.path, 'directory');
+  const contained = resolveContained(marketplaceRoot, entry.path, 'directory');
   if (contained.outcome.kind !== 'ok') return undefined;
   try {
     return collectSkillNames(contained.outcome.canonicalPath, (reg.format ?? 'codex') as 'codex' | 'claude');
@@ -426,7 +291,7 @@ interface PluginRereadOutcome {
 /**
  * 重裝＝更新（#94）：對已安裝 plugin 在最新材料root（本機 live 路徑或 git 新 cache entry）重讀
  * catalog → 重解析 manifest＋skills，回傳刷新結果由呼叫端套用。純邏輯分支不拋；
- * 僅 I/O（readCatalogForReg／readManifestName／collectSkillNames）由各函式內部 try/catch 守護。
+ * 僅 I/O（readMarketplaceCatalog／readManifestName／collectSkillNames）由各函式內部 try/catch 守護。
  */
 function rereadInstalledPlugin(
   root: string,
@@ -434,7 +299,7 @@ function rereadInstalledPlugin(
   inst: MinimalBridgeState['installations'][number],
   installations: MinimalBridgeState['installations'],
 ): PluginRereadOutcome {
-  const read = readCatalogForReg(root, format);
+  const read = readMarketplaceCatalog(root, format);
   if (read.error || !read.catalog) {
     return {
       ok: false,
@@ -725,7 +590,7 @@ export async function runCommand(
               break;
             }
 
-            const catalogResult = readCatalogForReg(acquiredPath, detectedFormat);
+            const catalogResult = readMarketplaceCatalog(acquiredPath, detectedFormat);
             if (catalogResult.error || !catalogResult.catalog) {
               messages.push(`錯誤：${catalogResult.error ?? 'catalog 解析失敗'}`);
               if (catalogResult.findings.length > 0) {
@@ -821,7 +686,7 @@ export async function runCommand(
               break;
             }
 
-            const catalogResult = readCatalogForReg(canonicalPath, detectedFormat);
+            const catalogResult = readMarketplaceCatalog(canonicalPath, detectedFormat);
             if (catalogResult.error || !catalogResult.catalog) {
               messages.push(`錯誤：${catalogResult.error ?? 'catalog 解析失敗'}`);
               if (catalogResult.findings.length > 0) {
@@ -910,9 +775,11 @@ export async function runCommand(
             messages.push('錯誤：尚未註冊任何 marketplace，請先使用 `/codex-marketplace add <路徑>` 註冊');
             break;
           }
-          const { plugins: enumeration, catalogErrors } = enumeratePlugins(state, opts);
+          const { plugins: enumeration, diagnostics } = queryMarketplacePlugins(state, opts);
           const pushCatalogErrors = (): void => {
-            for (const e of catalogErrors) messages.push(`⚠ marketplace [${e.marketplace}] ${e.error}`);
+            for (const diagnostic of diagnostics) {
+              messages.push(`⚠ marketplace [${diagnostic.marketplace}] ${diagnostic.error}`);
+            }
           };
           if (enumeration.length === 0) {
             messages.push('錯誤：目前沒有可安裝的 plugin（marketplace 內無可用 entry）');
@@ -920,7 +787,7 @@ export async function runCommand(
             break;
           }
 
-          let target: EnumeratedPlugin | undefined;
+          let target: MarketplacePluginCandidate | undefined;
           const num = Number(arg);
           const isNumeric = !isNaN(num) && String(num) === arg && Number.isInteger(num) && num >= 1;
           if (isNumeric) {
@@ -931,8 +798,8 @@ export async function runCommand(
               break;
             }
           } else {
-            // treat as name: match pluginName exactly
-            const candidates = enumeration.filter((e) => e.pluginName === arg);
+            // treat as name: match the query's Plugin candidate name exactly
+            const candidates = enumeration.filter((plugin) => plugin.candidateName === arg);
             if (candidates.length === 0) {
               // Also try to match manifestName of already installed? But enumeration already covers all catalog entries.
               messages.push(`錯誤：找不到名稱 "${arg}" 對應的 plugin`);
@@ -941,32 +808,26 @@ export async function runCommand(
             }
             if (candidates.length > 1) {
               // Ambiguous: list candidates
-              const list = candidates.map((c) => `${c.number}:${c.pluginName}[${c.reg.marketplaceName}]`).join('、');
+              const list = candidates
+                .map((candidate) => `${candidate.number}:${candidate.candidateName}[${candidate.registration.marketplaceName}]`)
+                .join('、');
               messages.push(`錯誤：名稱 "${arg}" 對應多個 plugin（${list}），請改用編號安裝`);
               break;
             }
             target = candidates[0];
           }
 
-          const targetReg = target.reg;
+          const targetReg = target.registration;
           const targetEntry = target.entry;
 
           // ---- Step 1: Unavailable Entry refusal (#91) + contained path check ----
-          if (!entryLocallyInstallable(targetEntry)) {
+          if (!target.structurallyInstallable) {
             messages.push(
-              `錯誤：plugin "${target.pluginName}" unavailable，無法安裝：${entryUnavailableReason(targetEntry)}`,
+              `錯誤：plugin "${target.candidateName}" unavailable，無法安裝：${target.unavailableReason}`,
             );
             break;
           }
-          const sourceRoot = sourceRootForReg(targetReg, opts);
-          if (!sourceRoot) {
-            const snap = (targetReg as unknown as { snapshot?: string }).snapshot;
-            const reason = targetReg.sourceKind === 'git'
-              ? (!snap ? 'git cache 指紋缺失' : `cache 快照缺失（${snap.slice(0, 12)}…）請先重新 add`)
-              : 'marketplace 根路徑無法解析';
-            messages.push(`錯誤：無法解析 marketplace 根 — ${reason}`);
-            break;
-          }
+          const sourceRoot = target.marketplaceRoot;
           const contained = resolveContained(sourceRoot, targetEntry.path!, 'directory');
           if (contained.outcome.kind === 'blocking') {
             messages.push(`錯誤：plugin 路徑檢查失敗（Contained Path 違規）— ${contained.outcome.reason}`);
@@ -1176,7 +1037,7 @@ export async function runCommand(
             gitAdvanced = true;
 
             // 重裝＝更新：從最新 cache 材料重裝全部已安裝 plugin（投影直讀新位址）
-            const cacheRoot = catalogRootForReg(reg, opts);
+            const cacheRoot = resolveMarketplaceRoot(reg, opts);
             if (cacheRoot) {
               for (const inst of insts) {
                 const outcome = rereadInstalledPlugin(cacheRoot, format, inst, state.installations);
@@ -1212,7 +1073,7 @@ export async function runCommand(
               continue;
             }
             // 先 probe catalog：不可讀時不能聲稱「無變化」，必須明示（不靜默略過）
-            const probe = readCatalogForReg(reg.source, format);
+            const probe = readMarketplaceCatalog(reg.source, format);
             if (probe.error) {
               updateLines.push(`⚠ marketplace [${display}] ${probe.error}`);
               continue;

package/src/bridge/completion.ts

@@ -0,0 +1,521 @@
+/**
+ * Bridge completion seam (#121, #122, #123, #124).
+ *
+ * Pure autocomplete for `/codex-marketplace`: root-level subcommands (#121), state-aware
+ * second-level `install` candidates (#122), Installation lifecycle `enable` / `disable` /
+ * `remove` candidates (#123), and Marketplace Registration candidates for `list` / `forget`
+ * (#124). This module owns no terminal, TUI, rendering, or Pi host types: its input is the
+ * complete argument prefix plus replaceable read-only options, and its output is only the
+ * insertion value, display label, and optional description that Pi autocomplete needs — or
+ * `null` when the argument prefix is not Bridge-owned syntax.
+ *
+ * Not owned: the `add` argument (arbitrary path or Git locator — free-form by design #124),
+ * arbitrary text, file and path completion. When the module does not own the syntax, callers
+ * fall through to Pi's normal behavior unchanged.
+ */
+
+import { queryMarketplacePlugins, type MarketplacePluginInstallationState } from './plugin-query.js';
+import {
+  isInstallationEnabled,
+  readMinimalBridgeStatePassive,
+  type MinimalBridgeState,
+  type MinimalInstallation,
+} from './state.js';
+
+export interface CompletionItem {
+  /** Insertion value. Argument-taking subcommands carry a trailing space (#121). */
+  value: string;
+  /** Display label shown in Pi's candidate list. */
+  label: string;
+  /** Optional short description, matching the command surface's HELP_TEXT vocabulary. */
+  description?: string;
+}
+
+/**
+ * Replaceable read-only options for composing candidates (Bridge State read seam).
+ *
+ * Root-level (#121) candidates never read Bridge State; state-aware `install` candidates
+ * (#122) read it passively through `readMinimalBridgeStatePassive`, so a damaged document is
+ * never written, reset, or repaired (#119 stories 22–23). The adapter passes them through
+ * from registrable sources only.
+ */
+export interface CompletionReadOptions {
+  statePath?: string;
+  agentDir?: string;
+}
+
+interface RootCommandCandidate {
+  label: string;
+  description: string;
+  /** Whether applying the subcommand expects an argument (inserts a trailing space). */
+  takesArgument: boolean;
+}
+
+/** The nine root subcommands, descriptions aligned with the command surface's HELP_TEXT vocabulary. */
+const ROOT_CANDIDATES: RootCommandCandidate[] = [
+  { label: 'add', description: '註冊 marketplace', takesArgument: true },
+  { label: 'list', description: '列出 plugins', takesArgument: true },
+  { label: 'install', description: '安裝最新版本並立即啟用', takesArgument: true },
+  { label: 'update', description: '全部更新', takesArgument: false },
+  { label: 'disable', description: '停用 plugin（不再投影）', takesArgument: true },
+  { label: 'enable', description: '啟用 plugin（恢復投影）', takesArgument: true },
+  { label: 'remove', description: '移除 plugin', takesArgument: true },
+  { label: 'forget', description: '移除 marketplace（含其全部安裝）', takesArgument: true },
+  { label: 'help', description: '這份說明清單', takesArgument: false },
+];
+
+function toItem(candidate: RootCommandCandidate): CompletionItem {
+  return {
+    value: candidate.takesArgument ? `${candidate.label} ` : candidate.label,
+    label: candidate.label,
+    description: candidate.description,
+  };
+}
+
+/** Scoring: earlier first-match wins, then a tighter char span within the label. */
+const FIRST_MATCH_WEIGHT = 1000;
+
+/**
+ * Case-insensitive non-contiguous fuzzy match: every query character must appear in order
+ * within the label. The score prefers earlier first-match position then a tighter span.
+ */
+function fuzzyScore(query: string, label: string): number | null {
+  const q = query.toLowerCase();
+  const target = label.toLowerCase();
+  let queryIndex = 0;
+  let firstMatch = -1;
+  let lastMatch = -1;
+  for (let i = 0; i < target.length && queryIndex < q.length; i += 1) {
+    if (target[i] === q[queryIndex]) {
+      if (firstMatch === -1) firstMatch = i;
+      lastMatch = i;
+      queryIndex += 1;
+    }
+  }
+  if (queryIndex < q.length) return null;
+  return firstMatch * FIRST_MATCH_WEIGHT + (lastMatch - firstMatch);
+}
+
+/**
+ * The owned second-level syntax: `install` followed by whitespace and a single-token query
+ * (plugin names are lowercase kebab-case; a second token is not Bridge-owned and falls
+ * through). `install` without a trailing space stays at the root level so the trailing-space
+ * root candidate can be applied first.
+ */
+const INSTALL_SECOND_LEVEL_RE = /^install\s+(\S*)$/;
+
+/**
+ * The owned Installation lifecycle second-level syntax (#123): `enable` / `disable` /
+ * `remove` followed by whitespace and a single-token query. Like `install`, each command
+ * without a trailing space stays at the root level; a second token is not Bridge-owned.
+ */
+const LIFECYCLE_SECOND_LEVEL_RE = /^(enable|disable|remove)\s+(\S*)$/;
+
+/**
+ * The owned Registration second-level syntax (#124): `list` / `forget` followed by
+ * whitespace and a single-token query. Both commands resolve their argument against the same
+ * Registration identity fields (marketplaceName OR alias OR id). Each command without a
+ * trailing space stays at the root level; a second token is not Bridge-owned. `add` is
+ * deliberately absent: its argument is free-form input (path or Git locator) and stays
+ * Pi-native.
+ */
+const REGISTRATION_SECOND_LEVEL_RE = /^(list|forget)\s+(\S*)$/;
+
+export type LifecycleAction = 'enable' | 'disable' | 'remove';
+
+/** Status vocabulary aligned with the `list` command surface (#90). */
+function installStatusLabel(state: MarketplacePluginInstallationState): string {
+  if (state === 'enabled') return '已裝啟用';
+  if (state === 'disabled') return '已裝停用';
+  return '可安裝';
+}
+
+/**
+ * Positive canonical integer without leading zeros — the exact argument shape `install`
+ * parses as an enumeration number (`String(Number(arg)) === arg && Number.isInteger && >= 1`),
+ * so a unique plugin name with this shape can never be resolved by name.
+ */
+const CANONICAL_INTEGER_RE = /^[1-9]\d*$/;
+
+/**
+ * Whether a name-typed `install <name>` invocation would actually resolve this candidate
+ * name: it must be unique in the full enumeration, contain no whitespace (the command splits
+ * arguments on whitespace), and not look like a canonical integer (the command parses those
+ * as enumeration numbers). Otherwise the insertion must be the enumeration number instead.
+ */
+function nameInsertionUsable(unique: boolean, name: string): boolean {
+  return unique && !/\s/.test(name) && !CANONICAL_INTEGER_RE.test(name);
+}
+
+interface InstallCandidate {
+  /** Plugin candidate name (entry name → path basename → ordinal fallback). */
+  name: string;
+  /** Marketplace provenance shown in the candidate description. */
+  marketplaceName: string;
+  /** 可安裝 / 已裝啟用 / 已裝停用 — install and reinstall are both selectable. */
+  status: string;
+  /** Case-insensitive fuzzy search target: plugin name + marketplace provenance. */
+  searchText: string;
+  /** Insertion token: the name when usable, else the enumeration number. */
+  insertion: string;
+}
+
+/**
+ * Compose install candidates from the shared Marketplace Plugin enumeration, restricted to
+ * structurally installable entries. Unavailable Entries (unsupported source, unresolvable
+ * source, invalid plugin, identity collision) never become candidates.
+ *
+ * Name insertion is allowed only when a name-typed `install <名稱>` would actually resolve
+ * the plugin: the candidate name must be unique against the *full* enumeration (the same
+ * domain `install <名稱>` resolves against — a same-named sibling, even an unavailable one,
+ * forces the number insertion because the name would be rejected as ambiguous), contain no
+ * whitespace, and not parse as a canonical enumeration number. The inserted number is the
+ * plugin's number in that full enumeration, matching `list` and `install <編號>` exactly.
+ */
+function composeInstallCandidates(state: MinimalBridgeState, options: CompletionReadOptions): InstallCandidate[] {
+  const { plugins } = queryMarketplacePlugins(state, { agentDir: options.agentDir });
+  const nameCounts = new Map<string, number>();
+  for (const plugin of plugins) {
+    nameCounts.set(plugin.candidateName, (nameCounts.get(plugin.candidateName) ?? 0) + 1);
+  }
+
+  const candidates: InstallCandidate[] = [];
+  for (const plugin of plugins) {
+    if (!plugin.structurallyInstallable) continue;
+    candidates.push({
+      name: plugin.candidateName,
+      marketplaceName: plugin.marketplaceName,
+      status: installStatusLabel(plugin.installationState),
+      searchText: `${plugin.candidateName} ${plugin.marketplaceName}`,
+      insertion: nameInsertionUsable((nameCounts.get(plugin.candidateName) ?? 0) === 1, plugin.candidateName)
+        ? plugin.candidateName
+        : String(plugin.number),
+    });
+  }
+  return candidates;
+}
+
+/**
+ * Compose the candidate label. A name insertion shows the name itself; a number insertion
+ * keeps the enumeration number visible but labels the plugin so the user can tell which
+ * same-named entry each candidate selects (the description carries provenance + status).
+ */
+function installLabel(candidate: InstallCandidate): string {
+  return candidate.insertion === candidate.name
+    ? candidate.name
+    : `${candidate.name} (#${candidate.insertion})`;
+}
+
+function toInstallItem(candidate: InstallCandidate): CompletionItem {
+  return {
+    value: `install ${candidate.insertion}`,
+    label: installLabel(candidate),
+    description: `[${candidate.marketplaceName}] ${candidate.status}`,
+  };
+}
+
+/**
+ * Second-level `install` candidates for `/codex-marketplace install <query>`.
+ *
+ * - Empty query → every currently installable or reinstallable plugin in enumeration order.
+ * - A query → case-insensitive fuzzy match over the plugin name and Marketplace provenance;
+ *   `[]` when nothing matches (the syntax is still Bridge-owned, there are simply no
+ *   candidates).
+ *
+ * The Bridge State read is passive: empty, damaged, unreadable, or incompatible state or
+ * marketplace material contributes no candidates and is never written, reset, or repaired.
+ */
+function completeInstallArguments(query: string, options: CompletionReadOptions): CompletionItem[] {
+  const state = readMinimalBridgeStatePassive({ statePath: options.statePath, agentDir: options.agentDir });
+  const candidates = composeInstallCandidates(state, options);
+  if (query.length === 0) {
+    return candidates.map(toInstallItem);
+  }
+  const scored: { item: CompletionItem; score: number }[] = [];
+  for (const candidate of candidates) {
+    const score = fuzzyScore(query, candidate.searchText);
+    if (score !== null) {
+      scored.push({ item: toInstallItem(candidate), score });
+    }
+  }
+  scored.sort((a, b) => a.score - b.score || a.item.label.localeCompare(b.item.label));
+  return scored.map((entry) => entry.item);
+}
+
+interface LifecycleCandidate {
+  /** The Installation name the command surface resolves on (manifestName → pluginId → id). */
+  name: string;
+  /** Marketplace provenance shown in the candidate description. */
+  marketplaceName: string;
+  /** 已裝啟用 / 已裝停用 — the Installation lifecycle status (#123). */
+  status: string;
+  /** Case-insensitive fuzzy search target: plugin name + marketplace provenance. */
+  searchText: string;
+  /** Durable Installation state — consumed by the action filter, not rendered. */
+  enabled: boolean;
+}
+
+function lifecycleStatusLabel(enabled: boolean): string {
+  return enabled ? '已裝啟用' : '已裝停用';
+}
+
+function installationName(inst: MinimalInstallation): string {
+  return inst.manifestName || inst.pluginId || inst.id;
+}
+
+/**
+ * Whether a name-typed `enable|disable|remove <name>` invocation would resolve exactly this
+ * Installation: the command matches `manifestName` OR `pluginId` OR `id` over every
+ * Installation (#93), so the token must be unique across all records, and must survive the
+ * command's whitespace token split.
+ */
+function lifecycleNameUsable(state: MinimalBridgeState, name: string): boolean {
+  if (name.length === 0 || /\s/.test(name)) return false;
+  let matches = 0;
+  for (const other of state.installations) {
+    if (other.manifestName === name || other.pluginId === name || other.id === name) matches += 1;
+  }
+  return matches === 1;
+}
+
+/**
+ * Compose Installation lifecycle candidates directly from Bridge State (#123). Lifecycle
+ * commands resolve on Installation records — not on catalog entries — so a record stays
+ * selectable even when its registration or marketplace material has become unreadable; only
+ * the provenance display degrades to the registration id.
+ *
+ * Ambiguity uses the full command resolution predicate over every Installation: a token that
+ * could resolve more than one record (cross-Marketplace same name, or a pluginId/id
+ * collision) is never offered, because the typed command would be rejected as ambiguous.
+ */
+function composeLifecycleCandidates(state: MinimalBridgeState): LifecycleCandidate[] {
+  const regNames = new Map(state.registrations.map((reg) => [reg.id, reg.marketplaceName || reg.alias || reg.id]));
+  const candidates: LifecycleCandidate[] = [];
+  for (const inst of state.installations) {
+    const name = installationName(inst);
+    if (!lifecycleNameUsable(state, name)) continue;
+    const marketplaceName = regNames.get(inst.registrationId) ?? inst.registrationId;
+    const enabled = isInstallationEnabled(inst);
+    candidates.push({
+      name,
+      marketplaceName,
+      status: lifecycleStatusLabel(enabled),
+      searchText: `${name} ${marketplaceName}`,
+      enabled,
+    });
+  }
+  return candidates;
+}
+
+function lifecycleCandidateIncluded(action: LifecycleAction, enabled: boolean): boolean {
+  if (action === 'enable') return !enabled;
+  if (action === 'disable') return enabled;
+  return true; // remove: every Installed Plugin, regardless of state
+}
+
+function toLifecycleItem(action: LifecycleAction, candidate: LifecycleCandidate): CompletionItem {
+  return {
+    value: `${action} ${candidate.name}`,
+    label: candidate.name,
+    description: `[${candidate.marketplaceName}] ${candidate.status}`,
+  };
+}
+
+interface RegistrationCandidate {
+  /** Registration display name — marketplaceName, else alias, else id (command surface display). */
+  name: string;
+  /** Unique resolvable token the command executes on: the name, else its alias, else its id. */
+  insertion: string;
+  /** Marketplace format ('codex' | 'claude') shown as provenance. */
+  format: string;
+  /** 本地 / git source-kind vocabulary matching the `list` overview surface (#90). */
+  sourceKindLabel: string;
+  /** Raw source (local path or Git URL) shown as provenance. */
+  source: string;
+  /** Case-insensitive fuzzy search target: name + alias + format + source provenance. */
+  searchText: string;
+}
+
+/**
+ * Whether a name-typed `list|forget <token>` invocation would resolve exactly this
+ * Registration: the command matches marketplaceName OR alias OR id over every Registration
+ * (the same predicate as `matchesRegistration` in the command surface), so the token must be
+ * unique across all identity fields and survive the command's whitespace token split.
+ */
+function registrationTokenUsable(registrations: MinimalBridgeState['registrations'], token: string): boolean {
+  if (token.length === 0 || /\s/.test(token)) return false;
+  let matches = 0;
+  for (const reg of registrations) {
+    if (reg.marketplaceName === token || reg.alias === token || reg.id === token) matches += 1;
+  }
+  return matches === 1;
+}
+
+/**
+ * Compose Registration candidates directly from Bridge State (#124). `list` and `forget`
+ * both resolve their argument on Registration records, so a candidate is offered only when
+ * some token uniquely names that record — the readable name first, then its alias, then its
+ * Registration id — mirroring the exact predicate the commands execute with. Ambiguity uses
+ * the full predicate over every Registration identity field; a Registration with no uniquely
+ * resolvable token contributes no candidate, because the typed command could never select it.
+ */
+function composeRegistrationCandidates(state: MinimalBridgeState): RegistrationCandidate[] {
+  const candidates: RegistrationCandidate[] = [];
+  for (const reg of state.registrations) {
+    const name = reg.marketplaceName || reg.alias || reg.id;
+    const insertion =
+      (registrationTokenUsable(state.registrations, name) && name) ||
+      (reg.alias && reg.alias !== name && registrationTokenUsable(state.registrations, reg.alias) && reg.alias) ||
+      (registrationTokenUsable(state.registrations, reg.id) && reg.id);
+    if (!insertion) continue;
+    const format = reg.format ?? 'codex';
+    const sourceKindLabel = reg.sourceKind === 'local' ? '本地' : 'git';
+    candidates.push({
+      name,
+      insertion,
+      format,
+      sourceKindLabel,
+      source: reg.source,
+      searchText: [name, reg.alias, format, sourceKindLabel, reg.source].filter(Boolean).join(' '),
+    });
+  }
+  return candidates;
+}
+
+/**
+ * Compose the candidate label: the readable Registration name; when the insertion is not the
+ * name (ambiguous name, alias, or id), it stays visible so the user sees which token the
+ * candidate inserts.
+ */
+function registrationLabel(candidate: RegistrationCandidate): string {
+  return candidate.insertion === candidate.name
+    ? candidate.name
+    : `${candidate.name} (${candidate.insertion})`;
+}
+
+function toRegistrationItem(action: 'list' | 'forget', candidate: RegistrationCandidate): CompletionItem {
+  return {
+    value: `${action} ${candidate.insertion}`,
+    label: registrationLabel(candidate),
+    description: `[${candidate.format}] ${candidate.sourceKindLabel} ${candidate.source}`,
+  };
+}
+
+/**
+ * Second-level `list` / `forget` candidates for `/codex-marketplace <action> <query>` (#124).
+ *
+ * - Empty query → every Registration with a uniquely resolvable token, in state order.
+ * - A query → case-insensitive fuzzy match over the name, alias, and source/format
+ *   provenance; `[]` when nothing matches.
+ *
+ * The Bridge State read is passive: empty, damaged, unreadable, or incompatible state or
+ * marketplace material contributes no candidates and is never written, reset, or repaired
+ * (#119 stories 22–23). `add` is not owned here by design.
+ */
+function completeRegistrationArguments(
+  action: 'list' | 'forget',
+  query: string,
+  options: CompletionReadOptions,
+): CompletionItem[] {
+  const state = readMinimalBridgeStatePassive({ statePath: options.statePath, agentDir: options.agentDir });
+  const candidates = composeRegistrationCandidates(state);
+  if (query.length === 0) {
+    return candidates.map((candidate) => toRegistrationItem(action, candidate));
+  }
+  const scored: { item: CompletionItem; score: number }[] = [];
+  for (const candidate of candidates) {
+    const score = fuzzyScore(query, candidate.searchText);
+    if (score !== null) {
+      scored.push({ item: toRegistrationItem(action, candidate), score });
+    }
+  }
+  scored.sort((a, b) => a.score - b.score || a.item.label.localeCompare(b.item.label));
+  return scored.map((entry) => entry.item);
+}
+
+/**
+ * Second-level `enable` / `disable` / `remove` candidates for `/codex-marketplace <action> <query>`.
+ *
+ * - `enable <query>` → disabled Installations only.
+ * - `disable <query>` → enabled Installations only.
+ * - `remove <query>` → every Installed Plugin, whatever its state.
+ * - Empty query → every actionable Installation in state order; a query → case-insensitive
+ *   fuzzy match over the name and Marketplace provenance; `[]` when nothing matches.
+ *
+ * The Bridge State read is passive: empty, damaged, unreadable, or incompatible state
+ * contributes no candidates and is never written, reset, or repaired (#119 stories 22–23).
+ */
+function completeLifecycleArguments(
+  action: LifecycleAction,
+  query: string,
+  options: CompletionReadOptions,
+): CompletionItem[] {
+  const state = readMinimalBridgeStatePassive({ statePath: options.statePath, agentDir: options.agentDir });
+  const candidates = composeLifecycleCandidates(state).filter((candidate) =>
+    lifecycleCandidateIncluded(action, candidate.enabled),
+  );
+  if (query.length === 0) {
+    return candidates.map((candidate) => toLifecycleItem(action, candidate));
+  }
+  const scored: { item: CompletionItem; score: number }[] = [];
+  for (const candidate of candidates) {
+    const score = fuzzyScore(query, candidate.searchText);
+    if (score !== null) {
+      scored.push({ item: toLifecycleItem(action, candidate), score });
+    }
+  }
+  scored.sort((a, b) => a.score - b.score || a.item.label.localeCompare(b.item.label));
+  return scored.map((entry) => entry.item);
+}
+
+/**
+ * Compose completion candidates for `/codex-marketplace <argumentPrefix>`.
+ *
+ * - `install ` / `install <query>` → state-aware second-level install candidates (#122).
+ * - `enable|disable|remove <query>` → Installation lifecycle candidates (#123).
+ * - `list|forget <query>` → Registration candidates (#124); `add` is never owned.
+ * - Empty prefix → all nine root candidates (Pi's exact-command interception surface).
+ * - A single token → case-insensitive fuzzy-filtered subcommands; `[]` when nothing matches.
+ * - Any other whitespace-containing prefix (unowned second-level syntax) → `null`, so callers
+ *   fall through to Pi's own completion unchanged.
+ *
+ * The module never writes Bridge State; root candidates are derived without reading it at all,
+ * and state-aware candidates read it passively.
+ */
+export function completeArguments(
+  argumentPrefix: string,
+  options: CompletionReadOptions = {},
+): CompletionItem[] | null {
+  const installMatch = INSTALL_SECOND_LEVEL_RE.exec(argumentPrefix);
+  if (installMatch) {
+    return completeInstallArguments(installMatch[1], options);
+  }
+  const lifecycleMatch = LIFECYCLE_SECOND_LEVEL_RE.exec(argumentPrefix);
+  if (lifecycleMatch) {
+    return completeLifecycleArguments(lifecycleMatch[1] as LifecycleAction, lifecycleMatch[2], options);
+  }
+  const registrationMatch = REGISTRATION_SECOND_LEVEL_RE.exec(argumentPrefix);
+  if (registrationMatch) {
+    return completeRegistrationArguments(
+      registrationMatch[1] as 'list' | 'forget',
+      registrationMatch[2],
+      options,
+    );
+  }
+  if (/\s/.test(argumentPrefix)) return null;
+
+  const query = argumentPrefix.trim();
+  if (query.length === 0) {
+    return ROOT_CANDIDATES.map(toItem);
+  }
+
+  const scored: { item: CompletionItem; score: number }[] = [];
+  for (const candidate of ROOT_CANDIDATES) {
+    const score = fuzzyScore(query, candidate.label);
+    if (score !== null) {
+      scored.push({ item: toItem(candidate), score });
+    }
+  }
+  scored.sort((a, b) => a.score - b.score || a.item.label.localeCompare(b.item.label));
+  return scored.map((entry) => entry.item);
+}

package/src/bridge/plugin-query.ts

@@ -0,0 +1,233 @@
+/**
+ * Read-only Marketplace Plugin enumeration query.
+ *
+ * This is the shared read model for command surfaces that need to select or display catalog
+ * entries. It owns registration material resolution, format-bound bounded catalog reads,
+ * global numbering, candidate naming, structural installability, Installation matching/state,
+ * Unavailable reasons, and disclosed diagnostics. It never mutates Bridge State or source data.
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { getCacheDir, getCacheEntriesDir } from '../cache/paths.js';
+import { BUDGET } from '../registration/budget.js';
+import {
+  GIT_FAMILY_UNAVAILABLE_REASON,
+  type Catalog,
+  type MarketplaceEntry,
+} from '../registration/catalog.js';
+import type { ValidationFinding } from '../registration/findings.js';
+import { catalogContractFor } from '../registration/format.js';
+import {
+  isInstallationEnabled,
+  type MarketplaceFormat,
+  type MinimalBridgeState,
+  type MinimalInstallation,
+  type MinimalRegistration,
+} from './state.js';
+
+export interface MarketplacePluginQueryOptions {
+  agentDir?: string;
+}
+
+export interface MarketplaceCatalogReadResult {
+  /** Parsed catalog on success; also present for structural parser failures that retain entries. */
+  catalog?: Catalog;
+  /** Structural findings from the registration's fixed Marketplace Format parser. */
+  findings: ValidationFinding[];
+  /** Existing command-surface diagnostic wording for a denied catalog read. */
+  error?: string;
+}
+
+export type MarketplacePluginInstallationState = 'not-installed' | 'enabled' | 'disabled';
+
+export interface MarketplacePluginCandidate {
+  /** Global 1-based number across registrations and entries in their original order. */
+  number: number;
+  registration: MinimalRegistration;
+  entry: MarketplaceEntry;
+  /** Entry-declared name, then local path basename, then ordinal fallback. */
+  candidateName: string;
+  marketplaceName: string;
+  marketplaceSource: string;
+  /** Live local Marketplace Root or the registration's pinned Git Source Cache material. */
+  marketplaceRoot: string;
+  structurallyInstallable: boolean;
+  installation?: MinimalInstallation;
+  installationState: MarketplacePluginInstallationState;
+  unavailableReason?: string;
+}
+
+export interface MarketplacePluginDiagnostic {
+  registration: MinimalRegistration;
+  marketplace: string;
+  marketplaceSource: string;
+  marketplaceRoot?: string;
+  findings: ValidationFinding[];
+  error: string;
+}
+
+export interface MarketplacePluginQueryResult {
+  plugins: MarketplacePluginCandidate[];
+  diagnostics: MarketplacePluginDiagnostic[];
+}
+
+/**
+ * Budget-bounded, format-bound Marketplace Catalog read used by the query and existing lifecycle
+ * rereads. Error literals intentionally retain the command grammar established by #91.
+ */
+export function readMarketplaceCatalog(
+  root: string,
+  format: MarketplaceFormat,
+): MarketplaceCatalogReadResult {
+  const contract = catalogContractFor(format);
+  const catalogPath = join(root, ...contract.relPath.split('/'));
+  let raw: string;
+  try {
+    if (!existsSync(catalogPath)) {
+      return { findings: [], error: `catalog 缺失（${contract.relPath}）` };
+    }
+    // Preserve the established command behavior exactly: the stat supplies the Validation Budget
+    // diagnostic, while readFileSync retains native diagnostics for directories/special files.
+    const size = statSync(catalogPath).size;
+    if (size > BUDGET.maxCatalogBytes) {
+      return {
+        findings: [],
+        error: `catalog 檔案過大（${size} bytes > ${BUDGET.maxCatalogBytes}）— 超過 Validation Budget 上限，catalog 無法解析`,
+      };
+    }
+    raw = readFileSync(catalogPath, 'utf-8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { findings: [], error: `catalog 無法讀取：${message}` };
+  }
+
+  if (!raw.trim()) {
+    return { findings: [], error: 'catalog 解析失敗：檔案為空 — catalog malformed' };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { findings: [], error: `catalog 解析失敗：${message} — catalog malformed` };
+  }
+
+  const result = contract.parse(parsed);
+  if (!result.ok) {
+    const codes = result.findings.map((finding) => finding.code).join(', ');
+    return {
+      catalog: result.catalog,
+      findings: result.findings,
+      error: `catalog 解析失敗${codes ? ` (${codes})` : ''} — catalog malformed`,
+    };
+  }
+  return { catalog: result.catalog, findings: result.findings };
+}
+
+function marketplaceName(registration: MinimalRegistration): string {
+  return registration.marketplaceName || registration.alias || registration.id;
+}
+
+export function resolveMarketplaceRoot(
+  registration: MinimalRegistration,
+  options: MarketplacePluginQueryOptions = {},
+): string | undefined {
+  if (registration.sourceKind !== 'git') return registration.source;
+  const snapshot = registration.snapshot;
+  if (!snapshot || !/^[0-9a-f]{64}$/.test(snapshot)) return undefined;
+  const root = join(getCacheEntriesDir(getCacheDir(options.agentDir)), snapshot);
+  return existsSync(root) ? root : undefined;
+}
+
+function materialUnavailableReason(registration: MinimalRegistration): string {
+  if (registration.sourceKind !== 'git') return 'catalog 根路徑無法解析';
+  const snapshot = registration.snapshot;
+  return !snapshot
+    ? 'git marketplace 缺少 cache 指紋'
+    : `cache 快照缺失（${snapshot.slice(0, 12)}…）`;
+}
+
+export function isMarketplaceEntryStructurallyInstallable(entry: MarketplaceEntry): boolean {
+  return entry.type === 'local'
+    && entry.available === true
+    && typeof entry.path === 'string'
+    && entry.path.length > 0;
+}
+
+export function marketplaceEntryUnavailableReason(entry: MarketplaceEntry): string {
+  if (entry.type === 'git' && entry.available !== false) return GIT_FAMILY_UNAVAILABLE_REASON;
+  return entry.unavailableReason ?? 'unsupported source kind';
+}
+
+/** Enumerate every readable Marketplace Catalog without mutating Bridge State or material. */
+export function queryMarketplacePlugins(
+  state: MinimalBridgeState,
+  options: MarketplacePluginQueryOptions = {},
+): MarketplacePluginQueryResult {
+  const plugins: MarketplacePluginCandidate[] = [];
+  const diagnostics: MarketplacePluginDiagnostic[] = [];
+  let number = 1;
+
+  for (const registration of state.registrations) {
+    const name = marketplaceName(registration);
+    const root = resolveMarketplaceRoot(registration, options);
+    if (!root) {
+      diagnostics.push({
+        registration,
+        marketplace: name,
+        marketplaceSource: registration.source,
+        marketplaceRoot: undefined,
+        findings: [],
+        error: materialUnavailableReason(registration),
+      });
+      continue;
+    }
+
+    const read = readMarketplaceCatalog(root, registration.format ?? 'codex');
+    if (read.error) {
+      diagnostics.push({
+        registration,
+        marketplace: name,
+        marketplaceSource: registration.source,
+        marketplaceRoot: root,
+        findings: read.findings,
+        error: read.error,
+      });
+      continue;
+    }
+
+    for (const entry of read.catalog?.entries ?? []) {
+      const candidateName = entry.name ?? (entry.path ? basename(entry.path) : `plugin-${entry.ordinal}`);
+      const installation = state.installations.find(
+        (candidate) => candidate.registrationId === registration.id
+          && (candidate.manifestName === candidateName || candidate.pluginId === candidateName),
+      );
+      const structurallyInstallable = isMarketplaceEntryStructurallyInstallable(entry);
+      const installationState: MarketplacePluginInstallationState = !installation
+        ? 'not-installed'
+        : isInstallationEnabled(installation)
+          ? 'enabled'
+          : 'disabled';
+
+      plugins.push({
+        number,
+        registration,
+        entry,
+        candidateName,
+        marketplaceName: name,
+        marketplaceSource: registration.source,
+        marketplaceRoot: root,
+        structurallyInstallable,
+        installation,
+        installationState,
+        unavailableReason: structurallyInstallable ? undefined : marketplaceEntryUnavailableReason(entry),
+      });
+      number += 1;
+    }
+  }
+
+  return { plugins, diagnostics };
+}