superpowers-manager 0.1.6 → 0.2.0

package/README.md

@@ -41,15 +41,19 @@ It never removes the legacy provider automatically.
 
 Superpowers Manager requires Node 24+, `git`, Python 3, and a POSIX `sh`.
 Codex CLI is required for `probe`, `install`, `update`, and `uninstall`;
-`prepare` does not require it.
+`prepare`, `pin`, `track-latest`, and `unpin` do not require it. Codex is the
+only supported integration today.
 
 macOS and Linux are tested. WSL2 is supported. The native Windows path is
 untested; the launcher looks for Git Bash, `git`, and `python3`, but path
 handling between MSYS and Codex remains a known risk area.
 
-Prepare, install, probe, and update resolve the requested upstream ref over the
-network. Updates are user-triggered and need upstream network access; the
-manager does not run automatic or background updates.
+Network needs depend on the saved policy. `pin` verifies its target;
+`track-latest` and invocation overrides resolve from upstream when applied; and
+`prepare`, `install`, and `update` fetch or verify the effective source. A probe
+of a saved exact pin can reuse its recorded identity without upstream access.
+Updates remain user-triggered; the manager does not run automatic or background
+updates.
 
 ## What it does
 
@@ -76,7 +80,8 @@ compatibility evidence.
 
 ## Runtime architecture
 
-- `scripts/core/` owns the shared lifecycle, status, and protocol validation.
+- `scripts/core/` owns the shared lifecycle, status, and protocol validation;
+  see the [version-1 adapter response protocol](https://github.com/j7an/superpowers-manager/blob/main/docs/adapter-protocol.md).
 - `scripts/adapters/codex/` owns build, inspection, reconciliation, and Codex
   mutation.
 - Codex is the only supported adapter today; no public harness selector ships
@@ -121,6 +126,9 @@ manager will not remove it for you.
 
 | Command | Codex side effects | Purpose |
 |---|---|---|
+| `npx superpowers-manager pin REF` | None | Resolve and save an exact upstream release tag or full commit |
+| `npx superpowers-manager track-latest` | None | Save a policy that resolves the latest stable release when applied |
+| `npx superpowers-manager unpin` | None | Remove saved selection and return to the packaged fallback policy |
 | `npx superpowers-manager prepare` | None | Resolve upstream, build a staged plugin tree, validate it, and replace the generated tree only on success |
 | `npx superpowers-manager probe` | None | Report requested and resolved refs, desired/generated/installed commits, identity state, and status |
 | `npx superpowers-manager install` | Marketplace and plugin state | Prepare and validate, register the marketplace, install the plugin, and verify installed state |
@@ -136,29 +144,75 @@ when resulting manager state cannot be verified.
 
 ## Choosing the upstream version
 
-`SUPERPOWERS_REF` selects a stable release tag, full commit SHA, branch, or
-other resolvable upstream ref for that invocation. The stateless npx package
-records the requested ref, resolved ref, and exact commit, but does not persist
-the selection for a later invocation that omits `SUPERPOWERS_REF`.
+Save a tag pin, commit pin, or explicit latest-stable policy for future
+invocations:
 
-Without `SUPERPOWERS_REF`, the manager reads `config/upstream-ref`, which ships
-as `latest-release`. Accepted values include:
+```sh
+npx superpowers-manager pin v6.1.1
+npx superpowers-manager pin 0123456789abcdef0123456789abcdef01234567  # replace with a real upstream commit
+npx superpowers-manager track-latest
+npx superpowers-manager unpin
+```
+
+The selection commands save intent only; they do not prepare generated content
+or change Codex state. Run `npx superpowers-manager install` for a first
+installation or `npx superpowers-manager update` to apply the saved policy to
+an existing installation. There is no background updater: selection changes
+take effect only through a user-triggered `prepare`, `install`, or `update`.
+
+`pin` accepts only an exact `vMAJOR.MINOR.PATCH` tag (optionally with a SemVer
+prerelease suffix) or a full 40-character commit. It resolves and verifies the
+target before saving both the exact commit identity and its source. The saved
+identity is the contract, not the contents of a clone cache: clearing or moving
+`SUPERPOWERS_CACHE_DIR` does not change the selection. `track-latest` saves the
+source and resolves the highest stable `vX.Y.Z` tag each time the policy is
+applied. `unpin` removes only the saved selection and restores the packaged
+`config/upstream-ref` fallback, currently `latest-release`.
+
+The user-wide selection file is `selection.json` under the first configured
+location:
+
+1. `$SUPERPOWERS_CONFIG_DIR`
+2. `$XDG_CONFIG_HOME/superpowers-manager`
+3. `$HOME/.config/superpowers-manager`
+
+Each location must be absolute. The ref and source precedence chains are
+independent:
+
+- Ref: `SUPERPOWERS_REF`, then saved selection, then `config/upstream-ref`.
+- Source: `SUPERPOWERS_UPSTREAM_URL`, then saved source, then the official
+  `https://github.com/obra/superpowers` source.
 
-- `latest-release` — highest stable `vX.Y.Z` tag (prereleases are excluded).
-- A specific tag, e.g. `v6.0.3`.
-- A full 40-character commit SHA.
-- Any other ref upstream resolves (e.g. a branch name).
+`SUPERPOWERS_REF` is an invocation-only override and is not persisted. Unlike
+an exact saved pin, it accepts stable tags, full commit SHAs, branches, and
+other resolvable upstream refs for that invocation:
 
 ```sh
-SUPERPOWERS_REF=v6.0.3 npx superpowers-manager prepare
-SUPERPOWERS_REF=main npx superpowers-manager probe
-SUPERPOWERS_REF=feature/foo npx superpowers-manager install
-SUPERPOWERS_REF=latest-release npx superpowers-manager update
+SUPERPOWERS_REF=feature/foo npx superpowers-manager probe
 ```
 
-`SUPERPOWERS_CACHE_DIR` may point to a persistent upstream clone cache to avoid
-re-cloning between package materializations. It caches Git objects; it does not
-persist ref selection or trigger updates.
+`pin` and `track-latest` bind the current `SUPERPOWERS_UPSTREAM_URL`, or the
+official source when that variable is unset, to the saved intent. An invocation
+may override only the ref or only the source; `probe` exposes
+`selection_origin`, `selection_mode`, `upstream_source_origin`,
+`effective_source`, the saved-selection fields, and a mixed-origin warning in
+human output so that combination remains visible.
+
+A saved exact pin lets `probe` determine the desired upstream identity without
+contacting Git, even when the saved source is temporarily unavailable. This is
+not a general offline installation promise: `pin` verifies the requested
+target, `track-latest` must resolve when applied, and `prepare`/`install`/`update`
+must fetch or verify content from the effective source. Codex inspection is
+still required for lifecycle status.
+
+HTTP(S) upstream URLs containing userinfo are now rejected, including
+token-only userinfo. This is an intentional compatibility break: use a Git
+credential helper for HTTP(S) authentication or an SSH source instead of
+embedding credentials in the URL.
+
+Saved selection does not claim or transfer provider ownership. The manager
+continues to mutate only `superpowers@superpowers-manager` and never removes or
+updates the official provider or any other provider automatically.
 
 ## How versioning works
 
@@ -236,8 +290,9 @@ plugins/superpowers/
   .superpowers-upstream.json               # generated provenance         (gitignored)
 scripts/
   adapters/codex/                          # Codex adapter entrypoint + validator helpers
-  core/                                    # shared lifecycle/provenance/status modules
-  prepare probe install update uninstall   # user-facing shell entrypoints
+  core/                                    # shared lifecycle, selection, provenance, and status modules
+  pin track-latest unpin                   # persistent-selection entrypoints
+  prepare probe install update uninstall   # lifecycle entrypoints
 tests/                                     # hermetic suite + manual Codex probe
 .cache/upstream/                           # upstream clone cache         (gitignored)
 ```

package/bin/superpowers-manager.js

@@ -6,7 +6,7 @@ import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 /**
- * @typedef {'prepare' | 'probe' | 'install' | 'update' | 'uninstall'} Subcommand
+ * @typedef {'pin' | 'track-latest' | 'unpin' | 'prepare' | 'probe' | 'install' | 'update' | 'uninstall'} Subcommand
  */
 
 /**
@@ -27,8 +27,22 @@ import { spawnSync } from 'node:child_process';
  * @typedef {{ file: string, argv: string[] }} SpawnDescriptor
  */
 
-const SUBCOMMANDS = ['prepare', 'probe', 'install', 'update', 'uninstall'];
-const CODEX_SUBCOMMANDS = ['probe', 'install', 'update', 'uninstall'];
+const SUBCOMMANDS = [
+  'pin', 'track-latest', 'unpin', 'prepare', 'probe', 'install', 'update', 'uninstall',
+];
+const PIN_TAG_RE = /^v(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-(?:(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?$/;
+const PIN_COMMIT_RE = /^[0-9A-Fa-f]{40}$/;
+/** @type {Record<Subcommand, string[]>} */
+const COMMAND_REQUIREMENTS = {
+  pin: ['git', 'python3'],
+  'track-latest': ['python3'],
+  unpin: [],
+  prepare: ['git', 'python3'],
+  probe: ['git', 'python3', 'codex'],
+  install: ['git', 'python3', 'codex'],
+  update: ['git', 'python3', 'codex'],
+  uninstall: ['python3', 'codex'],
+};
 // Mirrors upstream Superpowers' hooks/run-hook.cmd discovery order.
 const GIT_BASH_CANDIDATES = [
   'C:\\Program Files\\Git\\bin\\bash.exe',
@@ -78,7 +92,20 @@ function parseArgs(argv) {
   if (first === '--help' || first === '-h') return { kind: 'help' };
   if (first === '--version') return { kind: 'version' };
   if (first && SUBCOMMANDS.includes(first)) {
-    return { kind: 'run', cmd: /** @type {Subcommand} */ (first), args: argv.slice(1) };
+    const args = argv.slice(1);
+    if (first === 'pin' && args.length !== 1) {
+      return { kind: 'usage-error', message: 'usage: superpowers-manager pin REF' };
+    }
+    if (first === 'pin' && !PIN_TAG_RE.test(args[0]) && !PIN_COMMIT_RE.test(args[0])) {
+      return {
+        kind: 'usage-error',
+        message: 'pin REF must be an exact v-prefixed SemVer tag or full 40-hex commit',
+      };
+    }
+    if ((first === 'track-latest' || first === 'unpin') && args.length !== 0) {
+      return { kind: 'usage-error', message: `usage: superpowers-manager ${first}` };
+    }
+    return { kind: 'run', cmd: /** @type {Subcommand} */ (first), args };
   }
   return { kind: 'usage-error', message: `unknown subcommand: ${first}` };
 }
@@ -127,8 +154,15 @@ function discoverShell(env, platform) {
   return findTool('bash', env, platform);
 }
 
-// Tool preflight; never touches Codex state. codex is required only for the
-// subcommands that mutate or read Codex.
+/**
+ * @returns {Record<Subcommand, string[]>}
+ */
+function commandRequirements() {
+  return COMMAND_REQUIREMENTS;
+}
+
+// Tool preflight; never touches Codex state. Requirements are specific to the
+// selected command, while a POSIX shell remains mandatory for every command.
 /**
  * @param {Subcommand} cmd
  * @param {NodeJS.ProcessEnv} env
@@ -137,8 +171,17 @@ function discoverShell(env, platform) {
  */
 function preflight(cmd, env, platform) {
   const errors = [];
-  for (const tool of ['git', 'python3']) {
-    if (!findTool(tool, env, platform)) {
+  for (const tool of COMMAND_REQUIREMENTS[cmd]) {
+    if (tool === 'codex') {
+      const codexBin = env.SUPERPOWERS_CODEX || 'codex';
+      // An explicit override may be a path rather than a PATH-resolvable name.
+      const found = codexBin.includes(path.sep)
+        ? fs.existsSync(codexBin)
+        : Boolean(findTool(codexBin, env, platform));
+      if (!found) {
+        errors.push(`required command not found: ${codexBin} — install the Codex CLI or set SUPERPOWERS_CODEX`);
+      }
+    } else if (!findTool(tool, env, platform)) {
       errors.push(`required command not found: ${tool} — install ${tool} and re-run`);
     }
   }
@@ -148,16 +191,6 @@ function preflight(cmd, env, platform) {
       ? 'no POSIX shell found — install Git for Windows (provides bash) or use WSL2'
       : 'required command not found: sh');
   }
-  if (CODEX_SUBCOMMANDS.includes(cmd)) {
-    const codexBin = env.SUPERPOWERS_CODEX || 'codex';
-    // An explicit override may be a path rather than a PATH-resolvable name.
-    const found = codexBin.includes(path.sep)
-      ? fs.existsSync(codexBin)
-      : Boolean(findTool(codexBin, env, platform));
-    if (!found) {
-      errors.push(`required command not found: ${codexBin} — install the Codex CLI or set SUPERPOWERS_CODEX`);
-    }
-  }
   if (errors.length) return { ok: false, errors };
   return { ok: true, shell: /** @type {string} */ (shell) };
 }
@@ -183,8 +216,14 @@ function buildSpawn(cmd, args, root, shell, platform) {
 
 function usage() {
   return [
-    'usage: superpowers-manager [prepare|probe|install|update|uninstall] [args...]',
+    'usage: superpowers-manager [command] [args...]',
+    '',
+    'Selection commands (save intent only; they do not prepare or install it):',
+    '  pin REF       save an exact upstream release tag or commit',
+    '  track-latest  save selection of the latest stable upstream release',
+    '  unpin         remove the saved selection and return to the packaged fallback',
     '',
+    'Apply and lifecycle commands:',
     '  prepare    fetch the pinned upstream ref and generate the plugin tree',
     '  probe      report upstream/generated/installed status (accepts --porcelain)',
     '  install    register this package root as a Codex marketplace and install the plugin',
@@ -193,9 +232,13 @@ function usage() {
     '',
     'Environment overrides (passed through to the scripts): SUPERPOWERS_REF,',
     'SUPERPOWERS_UPSTREAM_URL, SUPERPOWERS_CODEX, SUPERPOWERS_CACHE_DIR,',
+    'SUPERPOWERS_CONFIG_DIR, XDG_CONFIG_HOME,',
     'SUPERPOWERS_PLUGIN_ROOT, SUPERPOWERS_MANIFEST_TEMPLATE,',
     'SUPERPOWERS_VALIDATOR,',
     'SUPERPOWERS_INSTALLED_SEARCH_ROOT, SUPERPOWERS_INSTALL_REFRESH_MODE',
+    '',
+    'Selection state uses SUPERPOWERS_CONFIG_DIR when set; otherwise it uses',
+    '$XDG_CONFIG_HOME/superpowers-manager, then $HOME/.config/superpowers-manager.',
   ].join('\n');
 }
 
@@ -239,6 +282,9 @@ function main() {
   process.exit(res.status === null ? 1 : res.status);
 }
 
-export { resolvePackageRoot, isMain, parseArgs, findTool, discoverShell, preflight, buildSpawn, usage };
+export {
+  resolvePackageRoot, isMain, parseArgs, findTool, discoverShell,
+  commandRequirements, preflight, buildSpawn, usage,
+};
 
 if (isMain(import.meta.filename, process.argv[1])) main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-manager",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Install and update the latest stable obra/superpowers release directly from upstream, without waiting for agent marketplaces to catch up. Codex supported today.",
   "keywords": [
     "superpowers",

package/scripts/adapters/codex/adapter

@@ -203,24 +203,15 @@ spw_codex_build() {
   [ -f "$validator" ] || spw_codex_failure build "build-failed" "missing built-in plugin validator: $validator" "" ""
 
   tmp_parent="${TMPDIR:-/tmp}"
-  if ! scratch=$(mktemp -d "$tmp_parent/superpowers-manager.adapter-build.XXXXXX"); then
+  if ! scratch=$(spw_make_workspace "$tmp_parent" "superpowers-manager.adapter-build"); then
     spw_codex_failure build "build-failed" "cannot create adapter build workspace under $tmp_parent" "" ""
   fi
+  spw_install_workspace_trap "$scratch"
   stdout_file="$scratch/stdout"
   stderr_file="$scratch/stderr"
   messages_file="$scratch/messages"
   candidate_manifest="$candidate_root/.codex-plugin/plugin.json"
   provenance_path="$candidate_root/.superpowers-upstream.json"
-  cleanup() {
-    status=$?
-    trap - 0 HUP INT TERM
-    rm -rf "$scratch" || :
-    exit "$status"
-  }
-  trap cleanup 0
-  trap 'exit 129' HUP
-  trap 'exit 130' INT
-  trap 'exit 143' TERM
 
   mkdir -p "$candidate_root/.codex-plugin"
   : > "$messages_file"
@@ -250,7 +241,7 @@ spw_codex_build() {
 
   if python3 -S "$validator" \
     --plugin-root "$candidate_root" \
-    --source "$upstream_source" \
+    --source="$upstream_source" \
     --requested-ref "$requested_ref" \
     --resolved-ref "$resolved_ref" \
     --commit "$commit" \
@@ -302,23 +293,14 @@ spw_codex_install() {
   esac
 
   tmp_parent="${TMPDIR:-/tmp}"
-  if ! scratch=$(mktemp -d "$tmp_parent/superpowers-manager.adapter-install.XXXXXX"); then
+  if ! scratch=$(spw_make_workspace "$tmp_parent" "superpowers-manager.adapter-install"); then
     spw_codex_failure install "install-failed" "cannot create adapter install workspace under $tmp_parent" "" ""
   fi
+  spw_install_workspace_trap "$scratch"
   stdout_file="$scratch/stdout"
   stderr_file="$scratch/stderr"
   messages_file="$scratch/messages"
   hints_file="$scratch/hints"
-  cleanup() {
-    status=$?
-    trap - 0 HUP INT TERM
-    rm -rf "$scratch" || :
-    exit "$status"
-  }
-  trap cleanup 0
-  trap 'exit 129' HUP
-  trap 'exit 130' INT
-  trap 'exit 143' TERM
 
   : > "$messages_file"
   : > "$hints_file"
@@ -426,22 +408,13 @@ spw_codex_uninstall() {
   spw_codex_require_command uninstall "$codex_bin"
 
   tmp_parent="${TMPDIR:-/tmp}"
-  if ! scratch=$(mktemp -d "$tmp_parent/superpowers-manager.adapter-uninstall.XXXXXX"); then
+  if ! scratch=$(spw_make_workspace "$tmp_parent" "superpowers-manager.adapter-uninstall"); then
     spw_codex_failure uninstall "uninstall-failed" "cannot create adapter uninstall workspace under $tmp_parent" "" ""
   fi
+  spw_install_workspace_trap "$scratch"
   stdout_file="$scratch/stdout"
   stderr_file="$scratch/stderr"
   messages_file="$scratch/messages"
-  cleanup() {
-    status=$?
-    trap - 0 HUP INT TERM
-    rm -rf "$scratch" || :
-    exit "$status"
-  }
-  trap cleanup 0
-  trap 'exit 129' HUP
-  trap 'exit 130' INT
-  trap 'exit 143' TERM
 
   : > "$messages_file"
 
@@ -491,12 +464,53 @@ spw_codex_inspect() {
 
   case "$view" in
     fingerprint)
-      fingerprint=$(spw_installed_commit_or_empty || true)
-      if [ -n "$fingerprint" ]; then
-        spw_codex_success inspect "{\"view\":\"fingerprint\",\"fingerprint\":\"$fingerprint\"}" ""
-      else
-        spw_codex_success inspect '{"view":"fingerprint","fingerprint":null}' ""
+      codex_bin="${SUPERPOWERS_CODEX:-codex}"
+      spw_require_command python3
+      spw_codex_require_command inspect "$codex_bin"
+
+      tmp_parent="${TMPDIR:-/tmp}"
+      if ! scratch=$(spw_make_workspace "$tmp_parent" "superpowers-manager.adapter-fingerprint"); then
+        spw_codex_failure inspect "inspect-failed" "cannot create adapter fingerprint workspace under $tmp_parent" "" ""
+      fi
+      spw_install_workspace_trap "$scratch"
+      stderr_file="$scratch/stderr"
+      messages_file="$scratch/messages"
+
+      : > "$messages_file"
+      : > "$stderr_file"
+      if ! plugin_listing=$("$codex_bin" plugin list --json 2>"$stderr_file"); then
+        spw_codex_append_messages "$messages_file" stderr "$stderr_file"
+        spw_codex_failure inspect "inspect-failed" "cannot list Codex plugins via '$codex_bin plugin list --json'" "" "$messages_file"
+      fi
+      spw_codex_append_messages "$messages_file" stderr "$stderr_file"
+      if ! active_version=$(spw_active_plugin_version_from_json \
+        "$plugin_listing" "$SPW_PLUGIN_ID"); then
+        spw_codex_failure inspect "inspect-failed" "cannot parse output of '$codex_bin plugin list --json'" "" "$messages_file"
+      fi
+      if [ -z "$active_version" ]; then
+        spw_codex_success inspect \
+          '{"view":"fingerprint","fingerprint":null}' "$messages_file"
+        return 0
       fi
+
+      search_root="${SUPERPOWERS_INSTALLED_SEARCH_ROOT:-$HOME/.codex}"
+      active_root=$(spw_installed_root_for_version \
+        "$search_root" "$SPW_MARKETPLACE_NAME" "superpowers" "$active_version")
+      fingerprint=$(spw_installed_commit_from_root_or_empty "$active_root")
+      if [ -z "$fingerprint" ]; then
+        spw_codex_failure inspect "inspect-failed" \
+          "cannot inspect active Codex plugin fingerprint under $active_root" "" "$messages_file"
+      fi
+      spw_codex_success inspect \
+        "{\"view\":\"fingerprint\",\"fingerprint\":\"$fingerprint\"}" \
+        "$messages_file"
+      ;;
+    update-control)
+      # Capability declaration for the fixed Codex local-package topology,
+      # backed by Layer-4 A/B evidence; revisit if topology or observed update
+      # behavior changes.
+      spw_codex_success inspect \
+        '{"view":"update-control","update_control":"managed"}' ""
       ;;
     ownership)
       codex_bin="${SUPERPOWERS_CODEX:-codex}"
@@ -504,21 +518,12 @@ spw_codex_inspect() {
       spw_codex_require_command inspect "$codex_bin"
 
       tmp_parent="${TMPDIR:-/tmp}"
-      if ! scratch=$(mktemp -d "$tmp_parent/superpowers-manager.adapter-inspect.XXXXXX"); then
+      if ! scratch=$(spw_make_workspace "$tmp_parent" "superpowers-manager.adapter-inspect"); then
         spw_codex_failure inspect "inspect-failed" "cannot create adapter inspect workspace under $tmp_parent" "" ""
       fi
+      spw_install_workspace_trap "$scratch"
       stderr_file="$scratch/stderr"
       messages_file="$scratch/messages"
-      cleanup() {
-        status=$?
-        trap - 0 HUP INT TERM
-        rm -rf "$scratch" || :
-        exit "$status"
-      }
-      trap cleanup 0
-      trap 'exit 129' HUP
-      trap 'exit 130' INT
-      trap 'exit 143' TERM
 
       : > "$messages_file"
 

package/scripts/adapters/codex/lib.sh

@@ -99,20 +99,77 @@ print("same" if na == nb else "different")
 PY
 }
 
-spw_find_installed_metadata() {
-  search_root="${SUPERPOWERS_INSTALLED_SEARCH_ROOT:-$HOME/.codex}"
-  find "$search_root" \
-    \( -path "*/$SPW_MARKETPLACE_NAME/superpowers/.superpowers-upstream.json" \
-       -o -path "*/$SPW_MARKETPLACE_NAME/superpowers/*/.superpowers-upstream.json" \) \
-    -type f 2>/dev/null | head -n 1
+spw_active_plugin_version_from_json() {
+  json="$1"
+  plugin_id="$2"
+  python3 - "$json" "$plugin_id" <<'PY'
+import json
+import sys
+
+raw, plugin_id = sys.argv[1:]
+
+def reject_constant(value):
+    raise ValueError(f"non-standard JSON constant: {value}")
+
+def has_terminal_control(value):
+    return any(
+        ord(character) < 0x20
+        or 0x7F <= ord(character) <= 0x9F
+        or 0xD800 <= ord(character) <= 0xDFFF
+        for character in value
+    )
+
+try:
+    data = json.loads(raw, parse_constant=reject_constant)
+except (json.JSONDecodeError, RecursionError, ValueError):
+    sys.exit(2)
+
+if not isinstance(data, dict):
+    sys.exit(2)
+items = data.get("installed")
+if not isinstance(items, list):
+    sys.exit(2)
+
+matches = []
+for item in items:
+    if not isinstance(item, dict):
+        sys.exit(2)
+    item_plugin_id = item.get("pluginId")
+    if not isinstance(item_plugin_id, str) or not item_plugin_id:
+        sys.exit(2)
+    if item_plugin_id == plugin_id:
+        matches.append(item)
+
+if len(matches) > 1:
+    sys.exit(2)
+if not matches:
+    sys.exit(0)
+
+version = matches[0].get("version")
+if (
+    not isinstance(version, str)
+    or not version
+    or version in {".", ".."}
+    or "/" in version
+    or "\\" in version
+    or has_terminal_control(version)
+):
+    sys.exit(2)
+print(version)
+PY
 }
 
-spw_find_installed_manifest() {
-  search_root="${SUPERPOWERS_INSTALLED_SEARCH_ROOT:-$HOME/.codex}"
-  find "$search_root" \
-    \( -path "*/$SPW_MARKETPLACE_NAME/superpowers/.codex-plugin/plugin.json" \
-       -o -path "*/$SPW_MARKETPLACE_NAME/superpowers/*/.codex-plugin/plugin.json" \) \
-    -type f 2>/dev/null | head -n 1
+spw_installed_root_for_version() {
+  search_root="$1"
+  marketplace="$2"
+  plugin="$3"
+  version="$4"
+  case "$search_root" in
+    /) search_root= ;;
+    */) search_root=${search_root%/} ;;
+  esac
+  printf '%s/plugins/cache/%s/%s/%s\n' \
+    "$search_root" "$marketplace" "$plugin" "$version"
 }
 
 spw_codex_json_get_or_empty() {
@@ -265,14 +322,15 @@ spw_manifest_short_sha_or_empty() {
   esac
 }
 
-spw_installed_commit_or_empty() {
-  installed_metadata=$(spw_find_installed_metadata || true)
-  installed_manifest=$(spw_find_installed_manifest || true)
+spw_installed_commit_from_root_or_empty() {
+  active_root="$1"
+  installed_metadata="$active_root/.superpowers-upstream.json"
+  installed_manifest="$active_root/.codex-plugin/plugin.json"
   installed_commit=""
-  if [ -n "$installed_metadata" ]; then
+  if [ -f "$installed_metadata" ]; then
     installed_commit=$(spw_codex_metadata_commit_or_empty "$installed_metadata" || true)
   fi
-  if [ -z "$installed_commit" ] && [ -n "$installed_manifest" ]; then
+  if [ -z "$installed_commit" ] && [ -f "$installed_manifest" ]; then
     installed_commit=$(spw_manifest_short_sha_or_empty "$installed_manifest" || true)
   fi
   printf '%s\n' "$installed_commit"

package/scripts/core/adapter.sh

@@ -24,6 +24,7 @@ spw_invoke_adapter() {
   shift
 
   response_file="${result_file}.response"
+  rm -f "$result_file"
   adapter_exit=0
   "$SPW_ADAPTER" "$operation" "$@" > "$response_file" || adapter_exit=$?
 
@@ -31,15 +32,20 @@ spw_invoke_adapter() {
   if [ -n "$inspect_view" ]; then
     args="$inspect_view"
   fi
+  validator_exit=0
   if [ -n "$args" ]; then
     python3 -S "$SPW_ADAPTER_RESPONSE_VALIDATOR" \
       --operation "$operation" --adapter-exit "$adapter_exit" \
       --response "$response_file" --result "$result_file" \
-      --inspect-view "$inspect_view"
+      --inspect-view "$inspect_view" || validator_exit=$?
   else
     python3 -S "$SPW_ADAPTER_RESPONSE_VALIDATOR" \
       --operation "$operation" --adapter-exit "$adapter_exit" \
-      --response "$response_file" --result "$result_file"
+      --response "$response_file" --result "$result_file" || validator_exit=$?
+  fi
+  if [ "$validator_exit" -ne 0 ]; then
+    rm -f "$result_file"
+    return 1
   fi
 }
 
@@ -76,6 +82,11 @@ spw_inspect_ownership() {
   spw_invoke_adapter inspect "$result_file" ownership -- --view ownership
 }
 
+spw_inspect_update_control() {
+  result_file="$1"
+  spw_invoke_adapter inspect "$result_file" update-control -- --view update-control
+}
+
 spw_adapter_install() {
   result_file="$1"
   package_root="$2"

package/scripts/core/common.sh

@@ -6,6 +6,11 @@ spw_die() {
   exit 1
 }
 
+spw_usage_error() {
+  echo "error: $*" >&2
+  exit 2
+}
+
 spw_require_command() {
   command_name="$1"
   if ! command -v "$command_name" >/dev/null 2>&1; then
@@ -13,6 +18,25 @@ spw_require_command() {
   fi
 }
 
+spw_make_workspace() {
+  mktemp -d "$1/$2.XXXXXX"
+}
+
+spw_cleanup_workspace_trap() {
+  _spw_workspace_trap_status=$?
+  trap - 0 HUP INT TERM
+  rm -rf "$_spw_workspace_trap_path" || :
+  exit "$_spw_workspace_trap_status"
+}
+
+spw_install_workspace_trap() {
+  _spw_workspace_trap_path="$1"
+  trap spw_cleanup_workspace_trap 0
+  trap 'exit 129' HUP
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
+}
+
 spw_root() {
   CDPATH= cd -- "$(dirname "$0")/.." && pwd
 }