fix(install): fail-closed marketplace ownership, shared-purge refusal, unconditional receipt inventory

Address codex review on #452:
- install claims a Claude/Codex marketplace only when it was absent before
  the install (or a prior receipt already claimed it); pre-existing or
  unreadable marketplaces are never recorded as owned
- uninstall scans live host inventory plus every stored receipt for
  marketplace dependents and retains the marketplace when any exist or
  the inventory is unknown; Claude --purge-data refuses (AB7008) when the
  same plugin is installed at another scope or dependents are unknown
- Claude project/local receipts are keyed by project root so parallel
  projects no longer overwrite each other's receipt
- doctor inventories store receipts even when the host probe is unavailable
- uninstall --plan for Cursor local simulates the prune precisely;
  --keep-data reruns on a remnant are a not-installed no-op
- Cursor marketplace imported detection uses the receipt commit even after
  the staged repo is gone

Author: ScriptedAlchemy

.changeset/101-managed-lifecycle.md

@@ -1,5 +1,5 @@
 ---
-"agent-bundle": minor
+"agent-bundle": patch
 ---
 
 Add `agent-bundle uninstall <host> [--from <bundle-dir>] [--scope <scope>] [--mode local|marketplace] [--keep-data | --purge-data --confirm-purge] [--force] [--plan] [--json]`, the package-relative installer bin's `uninstall <host>`, and the emitted standalone `install.mjs --uninstall`: the receipt-owned reverse of `install`. Uninstall removes exactly the receipt's files and installer-created directories (Cursor local, including the `~/.cursor/plugins[/local]` directories the install created), the staged marketplace repository after its `HEAD` matches the recorded commit (Cursor `--mode marketplace`), or the recorded host registrations (`claude plugin uninstall --keep-data` + `claude plugin marketplace remove`, `codex plugin remove` + `codex plugin marketplace remove`, the marketplace retained while another installed plugin uses it) — and nothing else. Durable runtime state (`state/`) is kept unless `--purge-data --confirm-purge` (`AB7008` without confirmation) with a typed per-host `data.outcome` (`kept`/`purged`/`absent`, Claude `retained-by-host`, Codex `removed-by-host`/`unavailable`); a missing receipt is `AB7006` and an owned-content, version, or `HEAD` mismatch is `AB7007` unless `--force`; foreign directories are refused regardless; `--plan` prints the exact paths and host verbs without changing anything; a rerun is a `not-installed` no-op. Install receipts move to format `agent-bundle-install-receipt/2` as the single lifecycle source of truth (mode, scope, registrations, created host directories, `updatedAt`), Claude/Codex/Cursor-marketplace installs write store receipts under `<host root>/agent-bundle/receipts/`, and format 1 receipts are read with synthesized fields and diagnosed (`AB7327`), never rejected. `agent-bundle doctor --from` reports the lifecycle stage per host (placed → registered → enabled → active, unobservable stages typed `unavailable`; `AB7325`), inventories store receipts and flags orphaned ones (`AB7326`), and explains a Cursor directory holding only preserved runtime state as `missing` (`AB7307`) instead of foreign. Host capability tables gain dated `lifecycle` rows and every adapter revision advances (#452)

docs/diagnostics.md

@@ -734,7 +734,16 @@ committed tree, so theirs live in an Agent Bundle-owned store,
 `<host root>/agent-bundle/receipts/<plugin>.<scope|marketplace>.json`
 (`~/.claude` or `$CLAUDE_CONFIG_DIR`, `~/.codex` or `$CODEX_HOME`,
 `~/.cursor`), with `files: []` — they own no files, only the registrations and
-the content hash. A format 1 receipt (written by #420) is read with those
+the content hash. A Claude `project` / `local` scope registration belongs to
+the working directory the host verbs ran in (the bundle root), so those
+receipts are keyed `<plugin>.<scope>.<12-hex digest of projectRoot>.json` and
+record `projectRoot`: two projects installing the same plugin at the same scope
+are two receipts. The `<host>-marketplace` registration is recorded only when
+the install actually created it — `plugin marketplace list --json` did not list
+the marketplace beforehand (or the receipted install it replaces recorded it);
+a marketplace that already existed, or one whose state could not be read,
+is not claimed, and `uninstall` then retains it and says why. A format 1
+receipt (written by #420) is read with those
 fields synthesized (`mode: local`, `scope: user`, one `cursor-local-plugin`
 registration, no host directories) and reported as migrated (`AB7327`); an
 identical rerun of the installer rewrites it as format 2. A current-format
@@ -822,10 +831,13 @@ open issue). Every mutation is opt-in and bounded by the receipt:
   `claude plugin uninstall <id> --scope <scope> --keep-data` /
   `codex plugin remove <id>`, then `plugin marketplace remove <marketplace>`
   and removes the store receipt. Because `plugin marketplace remove` applies
-  to every scope, the marketplace is `retained` when another installed plugin
-  still names it, when the same plugin is installed at another Claude scope,
-  or when the dependency re-read of `plugin list --json` fails (a failed read
-  is not proof that nothing depends on it). A registration the host no longer holds is
+  to every scope, the marketplace is `retained` when the receipt does not
+  record Agent Bundle registering it (it pre-existed the install, or there is
+  no receipt), when another installed plugin still names it, when another
+  store receipt (another project's scoped install) records it, when the same
+  plugin is installed at another Claude scope, or when `plugin marketplace
+  list --json` / the dependency re-read of `plugin list --json` cannot be read
+  (a failed read is not proof that nothing depends on it). A registration the host no longer holds is
   `already-absent`, so a receipt orphaned behind Agent Bundle's back is
   consumed without running any host verb.
 
@@ -839,14 +851,20 @@ for its ~14-day grace period; a purge additionally removes `state/` and
 tree on `plugin remove`), and `unavailable` (Codex has no keep-data option; a
 staged Cursor marketplace holds no runtime state). `--plan` computes the same
 report — exact absolute paths, registrations, data decision — without opening a
-writer, and a second run after a successful uninstall is a `not-installed`
-no-op.
+writer; planned directories are exactly the ones the run would prune (purged
+`state/` first, then every owned directory that would be left empty), never a
+directory kept alive by retained state or unowned entries. A second run after a
+successful uninstall is a `not-installed` no-op. When `--keep-data` left
+`state/` behind under a Cursor local root, the remnant receipt written there
+stays in place (`receipt.status: 'remnant'`) and a rerun without
+`--purge-data` is the same `not-installed` no-op; only `--purge-data
+--confirm-purge` removes the preserved state and prunes the root.
 
 | Code | Severity | Trigger | Recovery |
 | --- | --- | --- | --- |
 | `AB7006` | error | `uninstall` found the install but no receipt proving Agent Bundle owns it: a Cursor local copy in the pre-receipt legacy layout, a staged marketplace repository without its store receipt, or a host-registered Claude/Codex copy without its store receipt. | Re-run with `--force` (a legacy Cursor copy is removed by its inventory, `state/` kept; a host-CLI install is removed through the host verbs), or reinstall with `--replace` first to record a receipt. |
 | `AB7007` | error | `uninstall` refused a mismatch or a foreign target: the owned files hash differently from the receipt, the cached host copy differs from the receipt in version or content, the staged repository's `HEAD` is not the recorded commit, the receipt names another plugin, the directory is not this plugin's install at all, or a destination / `state/` entry is a symlink or special file. | `--force` overrides content and `HEAD` mismatches (the receipt-owned set is still the only thing removed); a receipt or manifest naming another plugin, and symlinked entries, are refused regardless — inspect and remove them manually. |
-| `AB7008` | error | `--purge-data` without `--confirm-purge`, or `--purge-data` together with `--keep-data`. | Pass `--purge-data --confirm-purge` to delete durable state, or neither flag to keep it. |
+| `AB7008` | error | `--purge-data` without `--confirm-purge`, `--purge-data` together with `--keep-data`, or (Claude) `--purge-data` while the same plugin is installed at another scope — the cached copy and `plugins/data/<id>/` are scope-less and still in use — or while `claude plugin list --json` cannot be re-read to prove there is no other scope. | Pass `--purge-data --confirm-purge` to delete durable state, or neither flag to keep it; for a shared Claude scope, uninstall without `--purge-data` and purge after the last scope is removed. |
 
 The Cursor and portable host-install proofs (`tests/host-install-proof.test.ts`,
 `tests/packed-host-install-proof.test.ts`) snapshot the isolated home before

packages/agent-bundle/src/install/doctor.ts

@@ -38,6 +38,7 @@ import {
   installReceiptFile,
   installReceiptFormat,
   installReceiptStoreDirectory,
+  isPreservedRuntimeRoot,
   isRemnantReceipt,
   isRuntimeStateRemnant,
   readInstallReceipt,
@@ -815,15 +816,26 @@ const cursorInventory = async (
       } catch {
         remnantReceipt = undefined;
       }
-      const remnant = (remnantReceipt !== undefined && isRemnantReceipt(remnantReceipt)) || await isRuntimeStateRemnant(path);
+      const stateOnly = await isRuntimeStateRemnant(path);
+      const remnant = stateOnly || (remnantReceipt !== undefined && isRemnantReceipt(remnantReceipt));
       if (remnant) {
         const durableState = await inspectDurableState(path, 'cursor');
         if (durableState !== undefined) diagnostics.push(...durableState.diagnostics);
+        // A remnant receipt may also guard unowned entries the uninstall retained: say so instead of
+        // calling the directory state-only.
+        const entries = stateOnly ? [] : (await readdir(path)).filter((name) => name !== installReceiptFile);
+        const extras = entries.filter((name) => !isPreservedRuntimeRoot(name)).sort((left, right) => left.localeCompare(right));
         diagnostics.push(diagnostic(
           'AB7307',
-          `Cursor plugin entry ${JSON.stringify(path)} holds only preserved runtime state (state/) from an earlier ` +
-            '`uninstall --keep-data`; no plugin is installed there.',
-          'Reinstall the plugin to use the preserved state, or run `agent-bundle uninstall cursor --purge-data --confirm-purge` to remove it.',
+          extras.length === 0
+            ? `Cursor plugin entry ${JSON.stringify(path)} holds only preserved runtime state (state/) from an earlier ` +
+              '`uninstall --keep-data`; no plugin is installed there.'
+            : `Cursor plugin entry ${JSON.stringify(path)} holds no plugin: an earlier \`uninstall\` retained the unowned ` +
+              `${extras.length === 1 ? 'entry' : 'entries'} ${extras.map((name) => JSON.stringify(name)).join(', ')}` +
+              `${entries.some(isPreservedRuntimeRoot) ? ' beside preserved runtime state (state/)' : ''}.`,
+          extras.length === 0
+            ? 'Reinstall the plugin to use the preserved state, or run `agent-bundle uninstall cursor --purge-data --confirm-purge` to remove it.'
+            : 'Reinstall the plugin, or move the retained entries out and remove the directory by hand; `uninstall` never removes unowned entries.',
           'info',
           'cursor',
         ));

packages/agent-bundle/src/install/install.ts

@@ -16,6 +16,7 @@ import {
   createInstallReceipt,
   describeContentComparison,
   installReceiptFile,
+  installReceiptScopeKey,
   installReceiptStorePath,
   isRemnantReceipt,
   isRuntimeStateRemnant,
@@ -440,14 +441,61 @@ export const publicHostRegistrations = (
     Object.freeze({ id, kind: 'codex-plugin' as const }),
   ]);
 
-/** Where the store receipt for a host-CLI install lives (`<host root>/agent-bundle/receipts/<plugin>.<scope>.json`). */
+/**
+ * Where the store receipt for a host-CLI install lives:
+ * `<host root>/agent-bundle/receipts/<plugin>.<scope>[.<project digest>].json`.
+ * Claude `project` / `local` registrations belong to the working directory the
+ * host verbs ran in (the bundle root), so each project keeps its own receipt.
+ */
 export const publicHostReceiptPath = (
   host: Exclude<InstallHost, 'cursor'>,
   plugin: string,
   scope: InstallScope,
   environment: Readonly<NodeJS.ProcessEnv>,
   home: string,
-): string => installReceiptStorePath(publicHostRoot(host, environment, home), plugin, scope);
+  projectRoot?: string,
+): string => installReceiptStorePath(
+  publicHostRoot(host, environment, home),
+  plugin,
+  installReceiptScopeKey(scope, projectRoot),
+);
+
+/** The project root a Claude `project` / `local` registration belongs to: the cwd the host verbs run in. */
+export const publicHostProjectRoot = (
+  host: Exclude<InstallHost, 'cursor'>,
+  scope: InstallScope,
+  identity: PluginIdentity,
+): string | undefined => host === 'claude' && scope !== 'user' ? identity.bundleRoot : undefined;
+
+/** `<host> plugin marketplace list --json`: whether a marketplace of this name is configured; `unknown` when unusable. */
+export const readPublicHostMarketplaceState = async (
+  runner: InstallCommandRunner,
+  identity: PluginIdentity,
+  host: Exclude<InstallHost, 'cursor'>,
+  marketplace: string,
+): Promise<'absent' | 'present' | 'unknown'> => {
+  let stdout: string;
+  try {
+    const result = await runner.run(host, ['plugin', 'marketplace', 'list', '--json'], { cwd: identity.bundleRoot });
+    if (result.code !== 0) return 'unknown';
+    stdout = result.stdout;
+  } catch {
+    return 'unknown';
+  }
+  let document: unknown;
+  try {
+    document = JSON.parse(stdout) as unknown;
+  } catch {
+    return 'unknown';
+  }
+  const rows = host === 'claude'
+    ? document
+    : typeof document === 'object' && document !== null ? (document as { readonly marketplaces?: unknown }).marketplaces : undefined;
+  if (!Array.isArray(rows)) return 'unknown';
+  return rows.some((row) => typeof row === 'object' && row !== null && (row as { readonly name?: unknown }).name === marketplace)
+    ? 'present'
+    : 'absent';
+};
 
 /** Where the store receipt for a Cursor marketplace-mode install lives. */
 export const cursorMarketplaceReceiptPath = (cursorRoot: string, plugin: string): string =>
@@ -479,7 +527,8 @@ const installPublicCli = async (
       host,
     );
   }
-  const receiptPath = publicHostReceiptPath(host, identity.plugin, scope, environment, home);
+  const projectRoot = publicHostProjectRoot(host, scope, identity);
+  const receiptPath = publicHostReceiptPath(host, identity.plugin, scope, environment, home, projectRoot);
   const previousReceipt = await readInstallReceiptFile(receiptPath);
   const base = {
     bundleRoot: identity.bundleRoot,
@@ -500,14 +549,25 @@ const installPublicCli = async (
   // replacement, and refreshed when an identical copy is found without one (pre-#101 installs). It owns
   // no files — the host owns its cache copy — so only the content hash rides along, never an inventory.
   const storeInventory: TreeInventory = Object.freeze({ files: Object.freeze([]), hash: artifact.hash });
-  const receiptIdentity: InstallReceiptIdentity = {
-    host,
-    ...(previousReceipt === undefined ? {} : { installedAt: previousReceipt.installedAt }),
-    mode: 'host-cli',
-    plugin: identity.plugin,
-    registrations: publicHostRegistrations(host, id, marketplace, scope),
-    scope,
-    version: identity.version,
+  // The marketplace registration is recorded — and therefore reversed by `uninstall` — only when this
+  // install (or the receipted install it replaces) created it. A marketplace that was already configured
+  // belongs to whoever configured it; when `plugin marketplace list --json` cannot say, the registration
+  // is not claimed either (fail-closed: `uninstall` then retains it and says why).
+  const receiptIdentity = async (): Promise<InstallReceiptIdentity> => {
+    const ownsMarketplace = previousReceipt !== undefined
+      ? previousReceipt.registrations.some((registration) => registration.kind === `${host}-marketplace`)
+      : await readPublicHostMarketplaceState(runner, identity, host, marketplace) === 'absent';
+    return {
+      host,
+      ...(previousReceipt === undefined ? {} : { installedAt: previousReceipt.installedAt }),
+      mode: 'host-cli',
+      plugin: identity.plugin,
+      ...(projectRoot === undefined ? {} : { projectRoot }),
+      registrations: publicHostRegistrations(host, id, marketplace, scope)
+        .filter((registration) => ownsMarketplace || registration.kind !== `${host}-marketplace`),
+      scope,
+      version: identity.version,
+    };
   };
   if (entry !== undefined) {
     destination = join(dirname(entry.installPath), identity.version);
@@ -529,7 +589,7 @@ const installPublicCli = async (
     const sameVersion = entry.version === identity.version;
     if (installed !== undefined && sameVersion && installed.hash === artifact.hash) {
       if (previousReceipt === undefined || previousReceipt.contentHash !== artifact.hash) {
-        await writeStoredInstallReceipt(receiptPath, createInstallReceipt({ ...receiptIdentity, inventory: storeInventory }));
+        await writeStoredInstallReceipt(receiptPath, createInstallReceipt({ ...(await receiptIdentity()), inventory: storeInventory }));
       }
       return { ...base, destination: entry.installPath, state: 'already-installed' };
     }
@@ -550,12 +610,16 @@ const installPublicCli = async (
     }
     const contentDrift = installed !== undefined && sameVersion && installed.hash !== artifact.hash;
     if (options.replace === true || contentDrift) {
-      await runHostCommand(runner, identity, host, publicHostUninstallArguments(host, id, scope), 'removal');
       replaced = true;
       // The receipt remembers what the superseded copy hashed when the copy itself cannot be read.
       previousContentHash = installed?.hash ?? previousReceipt?.contentHash;
     }
   }
+  // Decided before any host verb runs, so the marketplace ownership check sees the pre-install state.
+  const recorded = await receiptIdentity();
+  if (replaced) {
+    await runHostCommand(runner, identity, host, publicHostUninstallArguments(host, id, scope), 'removal');
+  }
   await runHostCommand(runner, identity, host, [
     'plugin',
     'marketplace',
@@ -566,7 +630,7 @@ const installPublicCli = async (
     ? ['plugin', 'install', id, '--scope', scope]
     : ['plugin', 'add', id]);
   await writeStoredInstallReceipt(receiptPath, createInstallReceipt({
-    ...receiptIdentity,
+    ...recorded,
     inventory: storeInventory,
     updatedAt: new Date().toISOString(),
   }));