feat: bridge Codex v0.5–v0.6 installer/uninstaller fail-closed hardening (2a/2)

Adopt the portable installer-safety improvements from Codex-Game-Studios v0.5–v0.6 (upstream commit 259cff8) into the OpenCode-native port, Phase 2a.

- coexistence.sh: add ccgs_state_validate (exists/schema==2/valid JSON/no path-traversal/no symlink) and ccgs_state_owned_paths helpers.
- uninstall.sh: fail-closed — remove the source-manifest fallback so missing, stale, malformed, path-traversing, or symlinked install-state aborts without removing files; drop the redundant emptiness-based AGENTS.md re-check (the Python helper already does proven-marker-only deletion); limit pruning to .opencode/ (never shared content roots).
- install.sh: --replace-modified opt-in + Python preflight that aborts before any mutation on unowned collisions (always) and locally-modified package-owned files (unless --replace-modified), naming the exact paths. Preflight runs only for cross-target deploys; self-install (source==target) is untouched.
- audit.sh: run_install_safety validator (5 static guards) wired into all and exposed as audit.sh install-safety.
- README.md / UPGRADING.md: document --replace-modified and fail-closed uninstall.

Verified: bash -n on all four scripts; audit.sh install-safety 5/5; audit.sh all 0 errors; scratch matrix 10/10 (fresh install, unowned-collision abort, modified-file abort, --replace-modified backup+replace, missing-state uninstall abort, valid-state uninstall clean removal). Phase 2b (transaction + rollback) is deferred to the next commit.

Author: Cipher-85

.opencode/audit.sh

@@ -606,6 +606,51 @@ run_release() {
   fi
 }
 
+run_install_safety() {
+  printf '\n── Installer Safety ────────────────────────────────────────\n'
+  local coex="$root/.opencode/lib/coexistence.sh"
+  local inst="$root/.opencode/install.sh"
+  local uninst="$root/.opencode/uninstall.sh"
+  local problems=0
+
+  if grep -q 'ccgs_state_validate()' "$coex" 2>/dev/null; then
+    pass "coexistence.sh defines ccgs_state_validate"
+  else
+    fail "coexistence.sh missing ccgs_state_validate (uninstall cannot fail closed)"
+    problems=1
+  fi
+
+  if grep -q 'ccgs_state_validate' "$uninst" 2>/dev/null; then
+    pass "uninstall.sh validates state (fail-closed)"
+  else
+    fail "uninstall.sh does not call ccgs_state_validate"
+    problems=1
+  fi
+
+  if grep -q 'installed-files.json' "$uninst" 2>/dev/null; then
+    fail "uninstall.sh references installed-files.json (ownership-by-manifest regression)"
+    problems=1
+  else
+    pass "uninstall.sh does not infer ownership from source manifest"
+  fi
+
+  if grep -q -- '--replace-modified' "$inst" 2>/dev/null; then
+    pass "install.sh supports --replace-modified"
+  else
+    fail "install.sh missing --replace-modified opt-in"
+    problems=1
+  fi
+
+  if grep -q 'Preflight' "$inst" 2>/dev/null; then
+    pass "install.sh runs a preflight pass"
+  else
+    fail "install.sh missing preflight conflict detection"
+    problems=1
+  fi
+
+  return $problems
+}
+
 case "$command" in
   all)
     run_agents
@@ -618,6 +663,7 @@ case "$command" in
     run_resume_contract
     run_runtime
     run_config
+    run_install_safety
     run_hooks
     run_smoke
     ;;
@@ -631,10 +677,11 @@ case "$command" in
   resume-contract) run_resume_contract ;;
   runtime)  run_runtime ;;
   config)   run_config ;;
+  install-safety) run_install_safety ;;
   hooks)    run_hooks ;;
   smoke)    run_smoke ;;
   release)  run_release ;;
-    *) printf 'Unknown command: %s\nAvailable: all, agents, skills, closeout, checkpoint, playtest, bug-lifecycle, handoff-review, resume-contract, runtime, config, hooks, smoke, release\n' "$command" >&2; exit 2 ;;
+    *) printf 'Unknown command: %s\nAvailable: all, agents, skills, closeout, checkpoint, playtest, bug-lifecycle, handoff-review, resume-contract, runtime, config, install-safety, hooks, smoke, release\n' "$command" >&2; exit 2 ;;
 esac
 
 printf '\n── Result: %d error(s) ──\n' "$errors"

.opencode/install.sh

@@ -16,6 +16,7 @@ source "$script_dir/lib/coexistence.sh"
 
 # ── Parse arguments ──────────────────────────────────────────────
 dry_run=0
+replace_modified=0
 target_arg=""
 opus_model=""
 sonnet_model=""
@@ -28,6 +29,7 @@ haiku_variant=""
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --dry-run) dry_run=1; shift ;;
+    --replace-modified) replace_modified=1; shift ;;
     --tier-opus)         opus_model="${2:-}";   shift 2 ;;
     --tier-sonnet)       sonnet_model="${2:-}"; shift 2 ;;
     --tier-haiku)        haiku_model="${2:-}";  shift 2 ;;
@@ -203,6 +205,7 @@ manifest_path = '$manifest'
 preserved_path = '$preserved_file'
 created_path = '$created_file'
 dry_run = 0
+replace_modified = $replace_modified
 
 marker_start = '$ccgs_marker_start'
 marker_end = '$ccgs_marker_end'
@@ -243,6 +246,81 @@ def is_coexist_mode(m):
 with open(manifest_path) as f:
     data = json.load(f)
 
+# ── Preflight: classify paths and detect conflicts before any mutation ──
+# A path is package-owned when prior install-state records it. On a fresh
+# target (no valid state) every existing manifest path that is not a
+# coexist-preserved shared file counts as an unowned collision. We never
+# infer ownership from file contents.
+_state_path = os.path.join(target, '.opencode', 'install-state.json')
+owned_hashes = {}
+if os.path.isfile(_state_path) and not os.path.islink(_state_path):
+    try:
+        with open(_state_path) as _sf:
+            _state = json.load(_sf)
+        if _state.get('schema_version') == 2:
+            owned_hashes = _state.get('installed_file_hashes', {}) or {}
+    except Exception:
+        owned_hashes = {}
+has_state = bool(owned_hashes)
+
+def _sha256_of(p):
+    h = hashlib.sha256()
+    with open(p, 'rb') as fh:
+        for _chunk in iter(lambda: fh.read(65536), b''):
+            h.update(_chunk)
+    return h.hexdigest()
+
+_collisions = []   # existing paths not proven package-owned
+_modified = []     # package-owned paths changed locally
+for entry in data.get('files', []):
+    rel = entry['path']
+    mode_flag = entry.get('mode', 'copy')
+    src = os.path.join(source, rel)
+    dst = os.path.join(target, rel)
+    if not os.path.exists(src):
+        continue
+    if is_foreign(rel):
+        continue            # execution refuses; not a deploy conflict
+    if mode_flag == 'marker':
+        continue            # marker splice, not a wholesale conflict
+    if rel == 'opencode.json':
+        continue            # only-if-absent; preserved when present
+    if is_coexist_mode(mode) and os.path.exists(dst) and not rel.startswith('.opencode/'):
+        continue            # preserved shared content
+    if not os.path.exists(dst):
+        continue            # create — no conflict
+    # dst exists and the standard-copy branch would overwrite it — classify
+    if has_state and rel in owned_hashes:
+        recorded = owned_hashes.get(rel)
+        try:
+            _dst_hash = _sha256_of(dst)
+        except OSError:
+            continue
+        if _dst_hash == recorded:
+            continue        # unchanged since we installed it — normal refresh
+        _src_hash = _sha256_of(src)
+        if _dst_hash == _src_hash:
+            continue        # already current
+        _modified.append(rel)
+    else:
+        _collisions.append(rel)
+
+if _collisions or (_modified and not replace_modified):
+    print('\n-- Preflight conflict: no files were changed --', file=sys.stderr)
+    if _collisions:
+        print('Unowned collisions (existing files not proven package-owned):', file=sys.stderr)
+        for _c in sorted(set(_collisions)):
+            print(f'  - {_c}', file=sys.stderr)
+        print('Resolve by removing/renaming these files, or install into a clean target.', file=sys.stderr)
+    if _modified and not replace_modified:
+        print('Locally-modified package-owned files (would be overwritten):', file=sys.stderr)
+        for _m in sorted(set(_modified)):
+            print(f'  - {_m}', file=sys.stderr)
+        print('Review with --dry-run, then re-run with --replace-modified to back up and replace', file=sys.stderr)
+        print('only state-proven package paths. --replace-modified never overwrites an unowned shared file.', file=sys.stderr)
+    sys.exit(1)
+# end preflight
+
 import filecmp
 
 copied = 0

.opencode/lib/coexistence.sh

@@ -370,6 +370,59 @@ ccgs_install_state_file() {
   printf '%s/%s\n' "${target_root:-$PWD}" "$ccgs_install_state_rel"
 }
 
+ccgs_state_validate() {
+  # Validate install-state.json. Returns: 0 valid, 1 invalid, 2 missing.
+  # Prints a reason to stderr when invalid. Args: target_root (optional)
+  local root="${1:-${target_root:-$PWD}}"
+  local state_file="$root/$ccgs_install_state_rel"
+  if [ ! -f "$state_file" ]; then
+    printf 'install-state missing: %s\n' "$state_file" >&2
+    return 2
+  fi
+  if [ -L "$state_file" ]; then
+    printf 'install-state is a symlink (unsafe): %s\n' "$state_file" >&2
+    return 1
+  fi
+  python3 - "$state_file" <<'PY'
+import json, sys
+from pathlib import Path
+p = Path(sys.argv[1])
+try:
+    data = json.loads(p.read_text(encoding="utf-8"))
+except Exception as e:
+    print(f"malformed install-state JSON: {e}", file=sys.stderr); sys.exit(1)
+if data.get("schema_version") != 2:
+    print(f"unsupported schema_version: {data.get('schema_version')}", file=sys.stderr); sys.exit(1)
+for key in ("installed_file_hashes", "shared_paths_created", "shared_paths_preserved"):
+    val = data.get(key, {})
+    items = val.keys() if isinstance(val, dict) else val
+    for rel in items:
+        s = str(rel)
+        if s.startswith("/") or ".." in s.split("/"):
+            print(f"unsafe path in {key}: {s}", file=sys.stderr); sys.exit(1)
+sys.exit(0)
+PY
+}
+
+ccgs_state_owned_paths() {
+  # Emit package-owned paths from install-state, one per line.
+  # Caller MUST validate state first. Args: target_root (optional)
+  local root="${1:-${target_root:-$PWD}}"
+  local state_file="$root/$ccgs_install_state_rel"
+  python3 - "$state_file" <<'PY'
+import json, sys
+from pathlib import Path
+try:
+    data = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+except Exception:
+    sys.exit(1)
+items = data.get("installed_file_hashes", {})
+paths = items.keys() if isinstance(items, dict) else items
+for rel in sorted(paths):
+    print(rel)
+PY
+}
+
 ccgs_write_install_state() {
   # Args: target_root source_root mode patch_mode opus_model sonnet_model haiku_model primary_model
   #       opus_variant sonnet_variant haiku_variant preserved_file created_file

.opencode/uninstall.sh

@@ -37,45 +37,32 @@ install_mode="$(ccgs_detect_mode)"
 printf '── OpenCode Game Studios Uninstall ──\n\n'
 ccgs_print_mode_summary "$install_mode"
 
-# ── Read install state for file list ─────────────────────────────
+# ── Read install state for file list (fail-closed) ───────────────
 state_file="$target_root/.opencode/install-state.json"
-manifest="$source_root/.opencode/manifest/installed-files.json"
 
-# Get paths we created (from install state or manifest fallback)
 paths_file="$(mktemp "${TMPDIR:-/tmp}/ccgs-uninstall-paths.XXXXXX")"
 trap 'rm -f "$paths_file"' EXIT
 
-if [ -f "$state_file" ]; then
-  # Read file hashes from install-state (exact list of what we deployed)
-  python3 -c "
-import json, sys
-with open('$state_file') as f:
-    state = json.load(f)
-for path in sorted(state.get('installed_file_hashes', {}).keys()):
-    print(path)
-" > "$paths_file" 2>/dev/null
-elif [ -f "$manifest" ]; then
-  # Fallback: use manifest
-  python3 -c "
-import json
-with open('$manifest') as f:
-    data = json.load(f)
-for entry in data.get('files', []):
-    print(entry['path'])
-" > "$paths_file" 2>/dev/null
+# Fail-closed: uninstall requires valid install-state ownership data.
+# Missing, stale, malformed, path-traversing, or symlinked state aborts
+# without removing project files. Never infer ownership from the source
+# manifest or from file contents.
+if ccgs_state_validate "$target_root"; then
+  ccgs_state_owned_paths "$target_root" > "$paths_file"
+else
+  rc=$?
+  reason="invalid"
+  [ "$rc" -eq 2 ] && reason="missing"
+  printf '\nERROR: cannot uninstall safely — install-state is %s.\n' "$reason" >&2
+  printf 'Uninstall requires valid .opencode/install-state.json ownership data.\n' >&2
+  printf 'Restore it from .opencode/backups/ or resolve ownership manually.\n' >&2
+  printf 'No files were changed.\n' >&2
+  exit 1
 fi
 
 if [ ! -s "$paths_file" ]; then
-  printf 'No install state or manifest found — stripping models only.\n'
-  # Still strip models + remove generated files
-  if [ "$dry_run" -eq 0 ]; then
-    ccgs_strip_all_agents "$target_root"
-    ccgs_remove_primary_model "$target_root"
-    for f in .opencode/models.json .opencode/install-state.json; do
-      [ -f "$target_root/$f" ] && rm "$target_root/$f"
-    done
-  fi
-  printf 'Done (models stripped, no file list to remove).\n'
+  printf 'install-state valid but records no owned files — nothing to remove.\n'
+  printf 'No files were changed.\n'
   exit 0
 fi
 
@@ -150,13 +137,11 @@ while IFS= read -r path; do
 
   case "$path" in
     AGENTS.md|*/AGENTS.md)
-      # Remove marker block, preserve rest of file
+      # Remove our marker block only. ccgs_remove_marker_block deletes the
+      # file solely when its pre-strip content was nothing but the marker
+      # block; it keeps any user-authored content and never uses emptiness
+      # or file contents as ownership proof.
       ccgs_remove_marker_block "$target_file" 2>/dev/null || true
-      # If file is now empty or just a stub, remove it
-      if [ -f "$target_file" ]; then
-        local_content="$(tr -d '\n\r\t ' < "$target_file" 2>/dev/null || true)"
-        [ -z "$local_content" ] && rm -f "$target_file"
-      fi
       ;;
     opencode.json)
       # Don't remove opencode.json (user may have other config)
@@ -187,15 +172,12 @@ done
 ccgs_remove_gitignore_allowlist "$target_root" 2>/dev/null || true
 
 # ── Prune empty OpenCode-owned directories ───────────────────────
-if is_coexist; then
-  # Only prune .opencode/ in coexistence mode (leave shared dirs alone)
+# Pruning is limited to the OpenCode runtime directory (.opencode/).
+# Shared content roots (design/, docs/, production/, src/, assets/, tests/,
+# tools/, "CCGS Skill Testing Framework/") are never deleted even when empty
+# — emptiness is not ownership proof and they may be user scaffolds.
+if [ -d "$target_root/.opencode" ]; then
   find "$target_root/.opencode" -depth -type d -empty -delete 2>/dev/null || true
-else
-  # Full prune of all framework dirs
-  for dir in .opencode "CCGS Skill Testing Framework" assets design docs production prototypes src tests tools; do
-    [ -d "$target_root/$dir" ] || continue
-    find "$target_root/$dir" -depth -type d -empty -delete 2>/dev/null || true
-  done
 fi
 
 printf '\nDone. OpenCode Game Studios removed.\n'

README.md

@@ -267,6 +267,19 @@ The installer deploys all framework files alongside existing content. It detects
 prior installs, foreign runtimes (Claude Code, Codex), and preserves shared
 project files. See [Coexistence](#coexistence) below.
 
+The installer preflights the target before mutating anything: an **unowned
+collision** (an existing file at a package path not proven ours) or a
+**locally-modified package-owned file** aborts the deploy with the exact paths
+and changes nothing. To back up and replace state-proven package paths you
+intentionally edited, re-run with `--replace-modified`:
+
+```bash
+bash .opencode/install.sh --dry-run --replace-modified /path/to/existing-game-project
+bash .opencode/install.sh --replace-modified /path/to/existing-game-project
+```
+
+`--replace-modified` never overwrites an unowned shared file.
+
 ### What the installer modifies
 
 1. **`.opencode/agents/*.md`** — injects `model:` and `variant:` into each
@@ -301,6 +314,13 @@ In coexistence mode, the uninstaller preserves shared paths it didn't create,
 removes only OpenCode-owned files, and extracts the marker block from
 `AGENTS.md` without deleting user content.
 
+Uninstall is **fail-closed**: it requires valid `.opencode/install-state.json`
+ownership data. Missing, stale, malformed, path-traversing, or symlinked state
+aborts without removing project files — restore the state from
+`.opencode/backups/` or resolve ownership manually. `AGENTS.md` is deleted only
+when its entire content was the CCGS marker block; any user-authored content is
+kept.
+
 ## Coexistence
 
 OpenCode Game Studios is intentionally additive. The installer detects the

UPGRADING.md

@@ -133,6 +133,21 @@ live. After any upgrade, trust the target project and start a **new
 `opencode` session** before verifying hooks, rules, permission profile, and
 agents. Keep the exact failing command and output if verification is blocked.
 
+Upgrades are fail-closed. A cross-target deploy aborts before mutating when it
+finds an unowned collision (an existing file at a package path not proven ours)
+or a locally-modified package-owned file. Review the abort with `--dry-run`,
+then opt into backup-first replacement for state-proven package paths only:
+
+```bash
+bash .opencode/install.sh --dry-run --replace-modified /path/to/project
+bash .opencode/install.sh --replace-modified /path/to/project
+```
+
+`--replace-modified` never adopts an unowned shared path; merge those manually.
+Uninstall is also fail-closed: it requires valid `.opencode/install-state.json`
+ownership data and aborts without removing files when state is missing, stale,
+malformed, path-traversing, or symlinked.
+
 ---
 
 ## v0.4.1