superpowers-manager 0.1.6 → 0.2.0

package/scripts/core/upstream.sh

@@ -22,6 +22,139 @@ spw_is_semver_base() {
   printf '%s' "$version" | grep -Eq '^(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-]*))*))?$'
 }
 
+spw_is_pinnable_tag() {
+  ref="$1"
+  case "$ref" in
+    *'
+'*|*"$(printf '\r')"*) return 1 ;;
+    v*) spw_is_semver_base "${ref#v}" ;;
+    *) return 1 ;;
+  esac
+}
+
+spw_is_full_commit() {
+  ref="$1"
+  [ "${#ref}" -eq 40 ] || return 1
+  case "$ref" in
+    *[!0-9A-Fa-f]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+spw_git_safe_source() {
+  source="$1"
+  case "$source" in
+    /*|*://*|*:*|~*) printf '%s\n' "$source" ;;
+    *) printf '%s/%s\n' "$(pwd -P)" "$source" ;;
+  esac
+}
+
+spw_resolve_exact_tag() {
+  source="$1"
+  ref="$2"
+  source_display=$(spw_display_source "$source")
+  query_source=$(spw_git_safe_source "$source")
+  if ! output=$(git ls-remote --tags -- "$query_source" "refs/tags/$ref" "refs/tags/$ref^{}" 2>&1); then
+    spw_die "cannot query exact upstream tag $ref from $source_display: $output"
+  fi
+  commit=$(printf '%s\n' "$output" | awk -v direct="refs/tags/$ref" '
+    $2 == direct { direct_sha = $1 }
+    $2 == direct "^{}" { peeled_sha = $1 }
+    END { if (peeled_sha != "") print peeled_sha; else if (direct_sha != "") print direct_sha }
+  ')
+  [ -n "$commit" ] || spw_die "upstream tag not found: $ref"
+  printf '%s\n' "$commit"
+}
+
+spw_verify_raw_commit() (
+  source="$1"
+  commit=$(printf '%s' "$2" | tr '[:upper:]' '[:lower:]')
+  workspace="$3"
+  source_display=$(spw_display_source "$source")
+  fetch_source=$(spw_git_safe_source "$source")
+
+  if ! verify_workspace=$(spw_make_workspace "$workspace" "superpowers-manager.commit"); then
+    spw_die "cannot create raw-commit verification workspace under $workspace"
+  fi
+  spw_install_workspace_trap "$verify_workspace"
+
+  if ! init_output=$(git init "$verify_workspace" 2>&1); then
+    spw_die "cannot initialize raw-commit verification workspace: $init_output"
+  fi
+  if fetch_output=$(git -C "$verify_workspace" fetch --no-tags -- "$fetch_source" "$commit" 2>&1); then
+    :
+  else
+    case "$fetch_output" in
+      *'not our ref'*|*'unadvertised object'*|*"couldn't find remote ref"*)
+        spw_die "source cannot supply requested commit: $commit"
+        ;;
+      *)
+        spw_die "cannot fetch requested commit from $source_display"
+        ;;
+    esac
+  fi
+  if ! object_type=$(git -C "$verify_workspace" cat-file -t "$commit" 2>/dev/null); then
+    spw_die "requested object is not a commit: $commit"
+  fi
+  if [ "$object_type" != commit ]; then
+    spw_die "requested object is not a commit: $commit"
+  fi
+  printf '%s\n' "$commit"
+)
+
+spw_fetch_exact_commit() (
+  source="$1"
+  commit="$2"
+  repository="$3"
+  workspace="$4"
+  source_display=$(spw_display_source "$source")
+  fetch_source=$(spw_git_safe_source "$source")
+
+  if ! fetch_workspace=$(spw_make_workspace "$workspace" "superpowers-manager.fetch"); then
+    spw_die "cannot create exact-commit fetch workspace under $workspace"
+  fi
+  spw_install_workspace_trap "$fetch_workspace"
+
+  if ! init_output=$(git init "$fetch_workspace" 2>&1); then
+    spw_die "cannot initialize exact-commit fetch workspace: $init_output"
+  fi
+  if fetch_output=$(git -C "$fetch_workspace" fetch --no-tags -- "$fetch_source" "$commit" 2>&1); then
+    :
+  else
+    case "$fetch_output" in
+      *'not our ref'*|*'unadvertised object'*|*"couldn't find remote ref"*)
+        spw_die "source cannot supply requested commit: $commit"
+        ;;
+      *)
+        spw_die "cannot fetch requested commit from $source_display"
+        ;;
+    esac
+  fi
+  if ! object_type=$(git -C "$fetch_workspace" cat-file -t "$commit" 2>/dev/null); then
+    spw_die "requested object is not a commit: $commit"
+  fi
+  if [ "$object_type" != commit ]; then
+    spw_die "requested object is not a commit: $commit"
+  fi
+
+  if [ ! -d "$repository/.git" ]; then
+    if ! init_output=$(git init "$repository" 2>&1); then
+      spw_die "cannot initialize upstream cache repository: $init_output"
+    fi
+  fi
+  if ! transfer_output=$(
+    git -C "$repository" fetch --no-tags -- "$fetch_workspace" "$commit" 2>&1
+  ); then
+    spw_die "cannot transfer requested commit into upstream cache: $transfer_output"
+  fi
+  if ! object_type=$(git -C "$repository" cat-file -t "$commit" 2>/dev/null); then
+    spw_die "cannot verify requested commit in upstream cache: $commit"
+  fi
+  if [ "$object_type" != commit ]; then
+    spw_die "cannot verify requested commit in upstream cache: $commit"
+  fi
+)
+
 spw_sanitize_ref_for_version() {
   ref="$1"
   sanitized=$(printf '%s' "$ref" | sed 's/[^0-9A-Za-z-][^0-9A-Za-z-]*/-/g; s/^-*//; s/-*$//')
@@ -102,9 +235,10 @@ spw_resolve_ref() {
   upstream_url="$1"
   requested_ref="$2"
   spw_require_command git
+  query_source=$(spw_git_safe_source "$upstream_url")
 
   if [ "$requested_ref" = "latest-release" ]; then
-    if ! output=$(git ls-remote --tags "$upstream_url" 'refs/tags/v*' 2>&1); then
+    if ! output=$(git ls-remote --tags -- "$query_source" 'refs/tags/v*' 2>&1); then
       spw_die "cannot query upstream tags from $upstream_url: $output"
     fi
     if ! selected=$(printf '%s\n' "$output" | spw_select_latest_release_from_ls_remote); then
@@ -119,7 +253,7 @@ spw_resolve_ref() {
     return
   fi
 
-  if ! tag_output=$(git ls-remote --tags "$upstream_url" "refs/tags/$requested_ref" "refs/tags/$requested_ref^{}" 2>&1); then
+  if ! tag_output=$(git ls-remote --tags -- "$query_source" "refs/tags/$requested_ref" "refs/tags/$requested_ref^{}" 2>&1); then
     spw_die "cannot query upstream tag $requested_ref from $upstream_url: $tag_output"
   fi
   resolved=$(printf '%s\n' "$tag_output" | awk -v tag_ref="refs/tags/$requested_ref" '
@@ -133,7 +267,7 @@ spw_resolve_ref() {
     return
   fi
 
-  if ! ref_output=$(git ls-remote "$upstream_url" "$requested_ref" 2>&1); then
+  if ! ref_output=$(git ls-remote -- "$query_source" "$requested_ref" 2>&1); then
     spw_die "cannot query upstream ref $requested_ref from $upstream_url: $ref_output"
   fi
   resolved=$(printf '%s\n' "$ref_output" | awk 'NF >= 2 { print $1; exit }')

package/scripts/core/validate-adapter-response.py

@@ -15,6 +15,7 @@ VERIFICATION_HINT_KEYS = {"mismatch", "missing"}
 OPERATIONS = {"build", "inspect", "install", "uninstall"}
 FINGERPRINT_RE = re.compile(r"(?:[0-9a-fA-F]{7}|[0-9a-fA-F]{40})\Z")
 MAX_NESTING = 64
+MAX_RESPONSE_BYTES = 1_048_576
 
 
 class ProtocolError(ValueError):
@@ -25,6 +26,17 @@ def reject_constant(value: str) -> None:
     raise ProtocolError(f"non-standard JSON constant: {value}")
 
 
+def reject_duplicate_keys(
+    pairs: list[tuple[str, object]],
+) -> dict[str, object]:
+    obj: dict[str, object] = {}
+    for key, value in pairs:
+        if key in obj:
+            raise ProtocolError("duplicate object key")
+        obj[key] = value
+    return obj
+
+
 def nesting_exceeds_limit(value: object) -> bool:
     stack = [(value, 0)]
     while stack:
@@ -160,7 +172,23 @@ def validate_result(
                 "legacy_resources": legacy_resources,
                 "identity_state": identity_state,
             }
-        raise ProtocolError("inspect view must be fingerprint or ownership")
+        if inspect_view == "update-control":
+            require_exact_keys(
+                result,
+                {"view", "update_control"},
+                "update-control inspect result",
+            )
+            if result.get("view") != "update-control":
+                raise ProtocolError("inspect result view must be update-control")
+            value = result.get("update_control")
+            if value not in {"managed", "unsupported"}:
+                raise ProtocolError(
+                    "update-control value must be managed or unsupported"
+                )
+            return {"view": "update-control", "update_control": value}
+        raise ProtocolError(
+            "inspect view must be fingerprint or ownership, or update-control"
+        )
     if operation == "install":
         require_exact_keys(result, {"verification_hints"}, "install result")
         hints = require_object(result.get("verification_hints"), "verification_hints")
@@ -216,11 +244,22 @@ def main() -> int:
     parser.add_argument("--adapter-exit", type=int, required=True)
     parser.add_argument("--response", type=Path, required=True)
     parser.add_argument("--result", type=Path, required=True)
-    parser.add_argument("--inspect-view", choices=("fingerprint", "ownership"))
+    parser.add_argument(
+        "--inspect-view", choices=("fingerprint", "ownership", "update-control")
+    )
     args = parser.parse_args()
     try:
+        response_size = args.response.stat().st_size
+        if response_size > MAX_RESPONSE_BYTES:
+            raise ProtocolError(
+                f"response exceeds {MAX_RESPONSE_BYTES}-byte limit"
+            )
         with args.response.open(encoding="utf-8") as handle:
-            raw = json.load(handle, parse_constant=reject_constant)
+            raw = json.load(
+                handle,
+                parse_constant=reject_constant,
+                object_pairs_hook=reject_duplicate_keys,
+            )
         if nesting_exceeds_limit(raw):
             raise ProtocolError("response JSON nesting exceeds limit")
         messages, result, error = validate_envelope(

package/scripts/install

@@ -16,10 +16,10 @@ echo "Note: remove or disable conflicting Superpowers providers yourself before
 # missing or stale — including validation — entirely before any Codex
 # marketplace or plugin mutation. A failed prepare leaves Codex untouched.
 probe_output=$(sh "$root/scripts/probe" --porcelain)
-identity_state=$(printf '%s\n' "$probe_output" | awk -F= '$1 == "identity_state" { print $2 }')
+identity_state=$(spw_probe_field "$probe_output" identity_state)
 [ -n "$identity_state" ] || spw_die "probe did not report adapter identity state"
 spw_require_no_legacy_state "$identity_state"
-status=$(printf '%s\n' "$probe_output" | awk -F= '$1 == "status" { print $2 }')
+status=$(spw_probe_field "$probe_output" status)
 case "$status" in
   needs\ prepare)
     sh "$root/scripts/prepare"
@@ -36,24 +36,23 @@ desired_commit=$(spw_metadata_commit_or_empty "$root/plugins/superpowers/.superp
 [ -n "$desired_commit" ] || spw_die "generated metadata missing desired commit after prepare"
 
 tmp_parent="${TMPDIR:-/tmp}"
-if ! install_workspace=$(mktemp -d "$tmp_parent/superpowers-manager.install.XXXXXX"); then
+if ! install_workspace=$(spw_make_workspace "$tmp_parent" "superpowers-manager.install"); then
   spw_die "cannot create install workspace under $tmp_parent"
 fi
-cleanup_install_workspace() {
-  status=$?
-  trap - 0 HUP INT TERM
-  rm -rf "$install_workspace" || :
-  exit "$status"
-}
-trap cleanup_install_workspace 0
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
+spw_install_workspace_trap "$install_workspace"
 
 TMPDIR="$install_workspace"
 export TMPDIR
 install_result="$install_workspace/install.json"
 inspect_result="$install_workspace/inspect.json"
+ownership_result="$install_workspace/ownership.json"
+update_control_result="$install_workspace/update-control.json"
+spw_inspect_ownership "$ownership_result"
+spw_inspect_update_control "$update_control_result"
+identity_state=$(spw_adapter_result_get "$ownership_result" "identity_state")
+update_control=$(spw_adapter_result_get "$update_control_result" "update_control")
+spw_require_no_legacy_state "$identity_state"
+spw_require_managed_update_control "$update_control"
 spw_adapter_install "$install_result" "$root"
 if ! spw_verify_installed_fingerprint "$desired_commit" "$install_result" "$inspect_result"; then
   exit 1

package/scripts/pin

@@ -0,0 +1,51 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+. "$root/scripts/core/common.sh"
+. "$root/scripts/core/upstream.sh"
+. "$root/scripts/core/selection.sh"
+
+[ "$#" -eq 1 ] || spw_usage_error 'usage: superpowers-manager pin REF'
+requested_ref="$1"
+
+if spw_is_pinnable_tag "$requested_ref"; then
+  requested_kind=tag
+elif spw_is_full_commit "$requested_ref"; then
+  requested_kind=raw-commit
+else
+  spw_usage_error 'pin REF must be an exact v-prefixed SemVer tag or full 40-hex commit'
+fi
+
+spw_require_command python3
+state_path=$(spw_selection_state_path)
+tmp_parent="${TMPDIR:-/tmp}"
+if ! pin_workspace=$(spw_make_workspace "$tmp_parent" "superpowers-manager.pin"); then
+  spw_die "cannot create pin workspace under $tmp_parent"
+fi
+spw_install_workspace_trap "$pin_workspace"
+
+normalized="$pin_workspace/selection.json"
+spw_selection_state "$root" read \
+  --path="$state_path" --output="$normalized"
+
+source="${SUPERPOWERS_UPSTREAM_URL:-$SPW_UPSTREAM_URL_DEFAULT}"
+spw_selection_state "$root" \
+  validate-source --source="$source"
+
+if [ "$requested_kind" = tag ]; then
+  spw_require_command git
+  commit=$(spw_resolve_exact_tag "$source" "$requested_ref")
+  resolved_ref="$requested_ref"
+else
+  spw_require_command git
+  requested_ref=$(printf '%s' "$requested_ref" | tr '[:upper:]' '[:lower:]')
+  resolved_ref="$requested_ref"
+  commit=$(spw_verify_raw_commit "$source" "$requested_ref" "$pin_workspace")
+fi
+
+spw_selection_state "$root" write-pinned \
+  --path="$state_path" --source="$source" --requested-ref="$requested_ref" \
+  --resolved-ref="$resolved_ref" --commit="$commit"
+
+printf 'pinned upstream selection to %s at %s\n' "$requested_ref" "$commit"

package/scripts/prepare

@@ -4,11 +4,11 @@ set -eu
 root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
 . "$root/scripts/core/common.sh"
 . "$root/scripts/core/upstream.sh"
+. "$root/scripts/core/selection.sh"
 . "$root/scripts/core/provenance.sh"
 . "$root/scripts/core/lifecycle.sh"
 . "$root/scripts/core/adapter.sh"
 
-upstream_url="${SUPERPOWERS_UPSTREAM_URL:-$SPW_UPSTREAM_URL_DEFAULT}"
 cache_parent="${SUPERPOWERS_CACHE_DIR:-$root/.cache/upstream}"
 plugin_root="${SUPERPOWERS_PLUGIN_ROOT:-$root/plugins/superpowers}"
 manifest_template="${SUPERPOWERS_MANIFEST_TEMPLATE:-$root/plugins/superpowers/.codex-plugin/plugin.template.json}"
@@ -25,51 +25,40 @@ esac
 cache="$cache_parent/superpowers"
 tmp_parent=$(dirname "$plugin_root")
 mkdir -p "$tmp_parent"
-if ! prepare_workspace=$(mktemp -d "$tmp_parent/.superpowers.prepare.XXXXXX"); then
+if ! prepare_workspace=$(spw_make_workspace "$tmp_parent" ".superpowers.prepare"); then
   spw_die "cannot create prepare workspace under $tmp_parent"
 fi
+spw_install_workspace_trap "$prepare_workspace"
 tmp_plugin="$prepare_workspace/superpowers"
 adapter_result="$prepare_workspace/adapter-build.json"
 
-cleanup_tmp_plugin() {
-  status=$?
-  trap - 0 HUP INT TERM
-  rm -rf "$prepare_workspace" || :
-  exit "$status"
-}
-
-trap cleanup_tmp_plugin 0
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
-
 TMPDIR="$prepare_workspace"
 export TMPDIR
 
-requested_ref=$(spw_config_ref "$root")
-
-spw_require_command git
 spw_require_command python3
+spw_compute_effective_selection "$root" "$prepare_workspace"
+spw_require_command git
 spw_require_command "$SPW_ADAPTER"
 [ -f "$manifest_template" ] || spw_die "missing fallback manifest template: $manifest_template"
 
-resolved_record=$(spw_resolve_ref "$upstream_url" "$requested_ref")
-resolution_kind=$(printf '%s\n' "$resolved_record" | awk '{ print $1 }')
-resolved_ref=$(printf '%s\n' "$resolved_record" | awk '{ print $2 }')
-commit=$(printf '%s\n' "$resolved_record" | awk '{ print $3 }')
-
 mkdir -p "$cache_parent" "$tmp_parent"
-if [ -d "$cache/.git" ]; then
-  if ! git -C "$cache" fetch --tags --prune "$upstream_url"; then
-    spw_die "cannot fetch upstream repo: $upstream_url"
-  fi
+if [ "$SPW_SELECTION_MODE" = "pinned" ]; then
+  spw_fetch_exact_commit \
+    "$SPW_EFFECTIVE_SOURCE" "$SPW_DESIRED_COMMIT" "$cache" "$prepare_workspace"
 else
-  if ! git clone "$upstream_url" "$cache"; then
-    spw_die "cannot clone upstream repo: $upstream_url"
+  git_source=$(spw_git_safe_source "$SPW_EFFECTIVE_SOURCE")
+  if [ -d "$cache/.git" ]; then
+    if ! git -C "$cache" fetch --tags --prune -- "$git_source"; then
+      spw_die "cannot fetch upstream repo: $SPW_EFFECTIVE_SOURCE"
+    fi
+  else
+    if ! git clone -- "$git_source" "$cache"; then
+      spw_die "cannot clone upstream repo: $SPW_EFFECTIVE_SOURCE"
+    fi
   fi
 fi
-if ! git -C "$cache" checkout --detach "$commit" >/dev/null; then
-  spw_die "cannot check out upstream commit: $commit"
+if ! git -C "$cache" checkout --detach "$SPW_DESIRED_COMMIT" >/dev/null; then
+  spw_die "cannot check out upstream commit: $SPW_DESIRED_COMMIT"
 fi
 
 spw_require_upstream_path "$cache/skills" "skills/"
@@ -94,21 +83,23 @@ fi
 
 spw_write_metadata_json \
   "$tmp_plugin/.superpowers-upstream.json" \
-  "$upstream_url" \
-  "$requested_ref" \
-  "$resolved_ref" \
-  "$commit" \
+  "$SPW_EFFECTIVE_SOURCE" \
+  "$SPW_REQUESTED_REF" \
+  "$SPW_RESOLVED_REF" \
+  "$SPW_DESIRED_COMMIT" \
   "$upstream_manifest_version"
 
 manager_version=$(
-  spw_manifest_version_for_ref "$requested_ref" "$resolution_kind" "$resolved_ref" "$commit"
+  spw_manifest_version_for_ref \
+    "$SPW_REQUESTED_REF" "$SPW_RESOLUTION_KIND" \
+    "$SPW_RESOLVED_REF" "$SPW_DESIRED_COMMIT"
 )
 spw_invoke_adapter build "$adapter_result" "" -- \
   --upstream-root "$cache" \
   --candidate-root "$tmp_plugin" \
-  --requested-ref "$requested_ref" \
-  --resolved-ref "$resolved_ref" \
-  --commit "$commit" \
+  --requested-ref "$SPW_REQUESTED_REF" \
+  --resolved-ref "$SPW_RESOLVED_REF" \
+  --commit "$SPW_DESIRED_COMMIT" \
   --manager-version "$manager_version" \
   --upstream-manifest-version "$upstream_manifest_version" \
   --fallback-manifest "$manifest_template"
@@ -123,4 +114,4 @@ fi
 
 spw_replace_generated_tree "$tmp_plugin" "$plugin_root"
 
-echo "prepared $resolved_ref at $commit"
+echo "prepared $SPW_RESOLVED_REF at $SPW_DESIRED_COMMIT"

package/scripts/probe

@@ -4,58 +4,79 @@ set -eu
 root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
 . "$root/scripts/core/common.sh"
 . "$root/scripts/core/upstream.sh"
+. "$root/scripts/core/selection.sh"
 . "$root/scripts/core/provenance.sh"
 . "$root/scripts/core/status.sh"
 . "$root/scripts/core/lifecycle.sh"
 . "$root/scripts/core/adapter.sh"
 
-upstream_url="${SUPERPOWERS_UPSTREAM_URL:-$SPW_UPSTREAM_URL_DEFAULT}"
-requested_ref=$(spw_config_ref "$root")
-resolved_record=$(spw_resolve_ref "$upstream_url" "$requested_ref")
-resolved_ref=$(printf '%s\n' "$resolved_record" | awk '{ print $2 }')
-desired_commit=$(printf '%s\n' "$resolved_record" | awk '{ print $3 }')
-
-generated_commit=$(spw_generated_commit_or_empty "$root")
 tmp_parent="${TMPDIR:-/tmp}"
-if ! probe_workspace=$(mktemp -d "$tmp_parent/superpowers-manager.probe.XXXXXX"); then
+if ! probe_workspace=$(spw_make_workspace "$tmp_parent" "superpowers-manager.probe"); then
   spw_die "cannot create probe workspace under $tmp_parent"
 fi
+spw_install_workspace_trap "$probe_workspace"
 fingerprint_result="$probe_workspace/fingerprint.json"
 ownership_result="$probe_workspace/ownership.json"
-cleanup() {
-  status=$?
-  trap - 0 HUP INT TERM
-  rm -rf "$probe_workspace" || :
-  exit "$status"
-}
-trap cleanup 0
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
+update_control_result="$probe_workspace/update-control.json"
 
 TMPDIR="$probe_workspace"
 export TMPDIR
+spw_compute_effective_selection "$root" "$probe_workspace"
+effective_source=$(spw_display_source "$SPW_EFFECTIVE_SOURCE")
+if [ -n "$SPW_SAVED_SOURCE" ]; then
+  saved_source=$(spw_display_source "$SPW_SAVED_SOURCE")
+else
+  saved_source=""
+fi
+
+generated_commit=$(spw_generated_commit_or_empty "$root")
 spw_inspect_fingerprint "$fingerprint_result"
 installed_commit=$(spw_adapter_result_get "$fingerprint_result" "fingerprint")
 spw_inspect_ownership "$ownership_result"
 identity_state=$(spw_adapter_result_get "$ownership_result" "identity_state")
+spw_inspect_update_control "$update_control_result"
+update_control=$(spw_adapter_result_get "$update_control_result" "update_control")
 
-status=$(spw_status_for_commits "$desired_commit" "$generated_commit" "$installed_commit")
+status=$(spw_status_for_commits "$SPW_DESIRED_COMMIT" "$generated_commit" "$installed_commit")
 
 if [ "${1:-}" = "--porcelain" ]; then
-  printf 'requested_ref=%s\n' "$requested_ref"
-  printf 'resolved_ref=%s\n' "$resolved_ref"
-  printf 'desired_commit=%s\n' "$desired_commit"
+  printf 'requested_ref=%s\n' "$SPW_REQUESTED_REF"
+  printf 'resolved_ref=%s\n' "$SPW_RESOLVED_REF"
+  printf 'desired_commit=%s\n' "$SPW_DESIRED_COMMIT"
   printf 'generated_commit=%s\n' "$generated_commit"
   printf 'installed_commit=%s\n' "$installed_commit"
   printf 'identity_state=%s\n' "$identity_state"
   printf 'status=%s\n' "$status"
+  printf 'selection_origin=%s\n' "$SPW_SELECTION_ORIGIN"
+  printf 'selection_mode=%s\n' "$SPW_SELECTION_MODE"
+  printf 'upstream_source_origin=%s\n' "$SPW_UPSTREAM_SOURCE_ORIGIN"
+  printf 'effective_source=%s\n' "$effective_source"
+  printf 'saved_mode=%s\n' "$SPW_SAVED_MODE"
+  printf 'saved_source=%s\n' "$saved_source"
+  printf 'saved_requested_ref=%s\n' "$SPW_SAVED_REQUESTED_REF"
+  printf 'saved_resolved_ref=%s\n' "$SPW_SAVED_RESOLVED_REF"
+  printf 'saved_commit=%s\n' "$SPW_SAVED_COMMIT"
+  printf 'update_control=%s\n' "$update_control"
 else
-  printf 'requested ref: %s\n' "$requested_ref"
-  printf 'resolved ref: %s\n' "$resolved_ref"
-  printf 'desired commit: %s\n' "$desired_commit"
+  printf 'requested ref: %s\n' "$SPW_REQUESTED_REF"
+  printf 'resolved ref: %s\n' "$SPW_RESOLVED_REF"
+  printf 'desired commit: %s\n' "$SPW_DESIRED_COMMIT"
   printf 'generated plugin commit: %s\n' "${generated_commit:-not present}"
   printf 'installed manager commit or fingerprint: %s\n' "${installed_commit:-not detected}"
   printf 'Codex identity state: %s\n' "$identity_state"
   printf 'status: %s\n' "$status"
+  printf 'selection origin: %s\n' "$SPW_SELECTION_ORIGIN"
+  printf 'selection mode: %s\n' "$SPW_SELECTION_MODE"
+  printf 'upstream source origin: %s\n' "$SPW_UPSTREAM_SOURCE_ORIGIN"
+  printf 'effective source: %s\n' "$effective_source"
+  printf 'saved mode: %s\n' "$SPW_SAVED_MODE"
+  printf 'saved source: %s\n' "$saved_source"
+  printf 'saved requested ref: %s\n' "$SPW_SAVED_REQUESTED_REF"
+  printf 'saved resolved ref: %s\n' "$SPW_SAVED_RESOLVED_REF"
+  printf 'saved commit: %s\n' "$SPW_SAVED_COMMIT"
+  printf 'update control: %s\n' "$update_control"
+  if [ "$SPW_SELECTION_ORIGIN" != "$SPW_UPSTREAM_SOURCE_ORIGIN" ]; then
+    printf 'warning: effective ref and source have mixed origins (ref: %s, source: %s)\n' \
+      "$SPW_SELECTION_ORIGIN" "$SPW_UPSTREAM_SOURCE_ORIGIN"
+  fi
 fi

package/scripts/track-latest

@@ -0,0 +1,30 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+. "$root/scripts/core/common.sh"
+. "$root/scripts/core/upstream.sh"
+. "$root/scripts/core/selection.sh"
+
+[ "$#" -eq 0 ] || spw_usage_error 'usage: superpowers-manager track-latest'
+
+spw_require_command python3
+state_path=$(spw_selection_state_path)
+tmp_parent="${TMPDIR:-/tmp}"
+if ! track_workspace=$(spw_make_workspace "$tmp_parent" "superpowers-manager.track-latest"); then
+  spw_die "cannot create track-latest workspace under $tmp_parent"
+fi
+spw_install_workspace_trap "$track_workspace"
+
+normalized="$track_workspace/selection.json"
+spw_selection_state "$root" read \
+  --path="$state_path" --output="$normalized"
+
+source="${SUPERPOWERS_UPSTREAM_URL:-$SPW_UPSTREAM_URL_DEFAULT}"
+spw_selection_state "$root" \
+  validate-source --source="$source"
+
+spw_selection_state "$root" write-track-latest \
+  --path="$state_path" --source="$source"
+
+printf '%s\n' 'saved upstream selection: latest stable release'

package/scripts/uninstall

@@ -10,21 +10,12 @@ root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
 spw_require_command python3
 
 tmp_parent="${TMPDIR:-/tmp}"
-if ! uninstall_workspace=$(mktemp -d "$tmp_parent/superpowers-manager.uninstall.XXXXXX"); then
+if ! uninstall_workspace=$(spw_make_workspace "$tmp_parent" "superpowers-manager.uninstall"); then
   spw_die "cannot create uninstall workspace under $tmp_parent"
 fi
+spw_install_workspace_trap "$uninstall_workspace"
 inspect_result="$uninstall_workspace/inspect.json"
 uninstall_result="$uninstall_workspace/uninstall.json"
-cleanup() {
-  status=$?
-  trap - 0 HUP INT TERM
-  rm -rf "$uninstall_workspace" || :
-  exit "$status"
-}
-trap cleanup 0
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
 
 TMPDIR="$uninstall_workspace"
 export TMPDIR

package/scripts/unpin

@@ -0,0 +1,41 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+. "$root/scripts/core/common.sh"
+. "$root/scripts/core/upstream.sh"
+. "$root/scripts/core/selection.sh"
+
+[ "$#" -eq 0 ] || spw_usage_error 'usage: superpowers-manager unpin'
+
+state_path=$(spw_selection_state_path)
+fallback=$(SUPERPOWERS_REF= spw_config_ref "$root")
+removed=false
+
+if [ -L "$state_path" ]; then
+  spw_die "selection state path is not a regular file; remove it manually after inspecting: $state_path"
+elif [ -e "$state_path" ]; then
+  if [ ! -f "$state_path" ]; then
+    spw_die "selection state path is not a regular file; remove it manually after inspecting: $state_path"
+  fi
+  if ! rm -f "$state_path"; then
+    spw_die "cannot remove selection state: $state_path"
+  fi
+  removed=true
+fi
+
+if [ -e "$state_path" ] || [ -L "$state_path" ]; then
+  spw_die "selection state remains after removal attempt: $state_path"
+fi
+
+if [ "$removed" = true ]; then
+  printf 'removed saved upstream selection; packaged fallback is %s\n' "$fallback"
+else
+  printf 'no saved upstream selection; packaged fallback is %s\n' "$fallback"
+fi
+if [ -n "${SUPERPOWERS_REF:-}" ]; then
+  printf '%s\n' 'note: active SUPERPOWERS_REF override remains effective'
+fi
+if [ -n "${SUPERPOWERS_UPSTREAM_URL:-}" ]; then
+  printf '%s\n' 'note: active SUPERPOWERS_UPSTREAM_URL override remains effective'
+fi