fix(tools/git): pr-review.sh _belongs case-insensitive repo-slug compare

#866 hardened the comment-persistence read-back into a full-path _belongs() check that pins scheme+host+port origin plus the full path, to block look-alike-host and same-host decoy-prefix attacks. That check compared the path case-sensitively: EXPECTED_REPO_SLUG is taken verbatim from GITEA_API_BASE and can be mixed-case (e.g. "USC/uconnect"), while Gitea canonicalizes the returned pull_request_url's owner/repo segment to lowercase. A successful 201 write on a mixed-case-slug repo therefore false-negatived ("did not land on a pull request") even though the comment genuinely landed — fail-closed on a real success, not a false success, but broken for legitimate mixed-case-slug repos. Lowercase both sides of the path comparison inside _belongs (path and expected_path) while leaving the origin tuple comparison, _origin_and_path's scheme+host lowercasing, and the full (non-suffix) path match untouched — the look-alike-host and decoy-prefix protections from #866 are unchanged; only the repo-slug segment's case sensitivity is relaxed, which is safe because Gitea repo slugs are case-insensitive and the remainder of the path is numeric. Adds a red-first regression case (comment-mixed-case-slug) modeling a mixed-case EXPECTED_REPO_SLUG against a Gitea-canonicalized lowercase pull_request_url, which fails against pre-fix code and passes after. Closes #875
2026-07-23 12:34:34 -05:00
21 changed files with 18 additions and 2455 deletions
--- a/packages/mosaic/framework/install.sh
+++ b/packages/mosaic/framework/install.sh
@@ -18,33 +18,12 @@ set -Eeuo pipefail
 #   MOSAIC_INSTALL_MODE      — prompt|keep|overwrite (default: prompt)
 #   MOSAIC_ALLOW_MISSING_SEQUENTIAL_THINKING — 1 to bypass MCP check
 #   MOSAIC_SKIP_SKILLS_SYNC  — 1 to skip skill sync
 #
 # Flags (CLI args, NOT environment variables — see #869 Point-1 C2):
 #   --allow-inactive-enforcement  Explicit, per-invocation opt-out that lets the
 #                                 lease-enforcement hooks (mutator-gate.py,
 #                                 receipt-observer-client.py) be wired into
 #                                 ~/.claude/settings.json even when this host
 #                                 cannot confirm it can ACTIVATE them. Loud on
 #                                 use (see mosaic-link-runtime-assets). Default
 #                                 (flag absent) is fail-loud: the enforcement
 #                                 hooks are NOT wired and the framework's
 #                                 runtime-asset-link step reports a failure.
 # ──────────────────────────────────────────────────────────────────────────────
 SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 # Deliberately parsed from "$@" (a real, explicit, per-invocation argument) —
 # never an environment variable — so this opt-out can never sit silently
 # inherited in a shell profile. See #869 Point-1 C2.
 ALLOW_INACTIVE_ENFORCEMENT=0
 for _arg in "$@"; do
  case "$_arg" in
    --allow-inactive-enforcement) ALLOW_INACTIVE_ENFORCEMENT=1 ;;
  esac
 done
 # Shared framework path-ownership manifest reader (#791). Parity with
 # packages/mosaic/src/framework/manifest.ts — both consume framework-manifest.txt.
 # Sourcing does not run its CLI dispatch (guarded by BASH_SOURCE==$0).
@@ -660,10 +639,6 @@ reconcile_framework_files
 # Ensure tool scripts are executable
 find "$TARGET_DIR/tools" -name "*.sh" -exec chmod +x {} + 2>/dev/null || true
 find "$TARGET_DIR/tools/_scripts" -type f -exec chmod +x {} + 2>/dev/null || true
 # git-credential-mosaic (per-agent Gitea identity helper) ships without a .sh
 # suffix — git resolves credential helpers by exact name/path, not extension —
 # so the *.sh glob above does not cover it; chmod it explicitly.
 [[ -f "$TARGET_DIR/tools/git/git-credential-mosaic" ]] && chmod +x "$TARGET_DIR/tools/git/git-credential-mosaic" 2>/dev/null || true
 ok "Framework synced to $TARGET_DIR"
@@ -691,15 +666,10 @@ step "Post-install tasks"
 SCRIPTS="$TARGET_DIR/tools/_scripts"
 if [[ -x "$SCRIPTS/mosaic-link-runtime-assets" ]]; then
-  link_args=()
+  if "$SCRIPTS/mosaic-link-runtime-assets" >/dev/null 2>&1; then
  [[ "$ALLOW_INACTIVE_ENFORCEMENT" == "1" ]] && link_args+=(--allow-inactive-enforcement)
  # stdout is suppressed as before, but stderr is left connected: the
  # install-ordering guard's FAIL LOUD message (#869 Point-1 C2) must reach
  # the operator, not be swallowed silently.
  if "$SCRIPTS/mosaic-link-runtime-assets" "${link_args[@]}" >/dev/null; then
    ok "Runtime assets linked"
  else
-    warn "Runtime asset linking failed (non-fatal) — see message above for details."
+    warn "Runtime asset linking failed (non-fatal)"
  fi
 fi
--- a/packages/mosaic/framework/tools/_scripts/mosaic-link-runtime-assets
+++ b/packages/mosaic/framework/tools/_scripts/mosaic-link-runtime-assets
@@ -4,22 +4,6 @@ set -euo pipefail
 MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 backup_stamp="$(date +%Y%m%d%H%M%S)"
 # ─── Install-ordering guard opt-out (#869 Point-1 C2) ───────────────────────
 # Explicit, per-invocation CLI flag ONLY — deliberately NOT read from an
 # environment variable, so it can never sit as a silently-inherited default in
 # a shell profile or CI env. Absent (the default) => hard fail-loud path.
 allow_inactive_enforcement=0
 for arg in "$@"; do
  case "$arg" in
    --allow-inactive-enforcement) allow_inactive_enforcement=1 ;;
  esac
 done
 # Tracks whether the Claude settings install-ordering guard (below) reported a
 # degraded (enforcement-not-wired) outcome, so this script's own exit status
 # reflects it even though the rest of the runtime-asset sync must still run.
 guard_degraded=0
 copy_file_managed() {
  local src="$1"
  local dst="$2"
@@ -40,103 +24,6 @@ copy_file_managed() {
  cp "$src" "$dst"
 }
 # ─── Install-ordering guard for settings.json (#869 Point-1 C2) ─────────────
 #
 # settings.json is where #828's enforcement hooks (PreToolUse mutator-gate.py,
 # Stop receipt-observer-client.py) get wired unconditionally. Before copying
 # it, delegate to `mosaic __link-claude-settings` (packages/mosaic/src/commands/
 # install-ordering-guard.ts) so the wiring decision is made by importing the
 # C1 activation probe (`leaseEnforcementActivatable()`) directly, rather than
 # re-implementing the capability/supervisor checks in shell. That subcommand:
 #   - activatable            -> writes settings.json with hooks intact, exits 0
 #   - NOT activatable        -> writes settings.json with hooks STRIPPED,
 #                                prints an actionable message, exits 1
 #   - NOT activatable + opt-out -> writes settings.json with hooks intact,
 #                                   prints a loud warning, exits 0
 # The `mosaic` CLI is expected on PATH at this point ("No executables are
 # placed on PATH — the mosaic npm CLI is the only binary", per install.sh).
 # If it is not resolvable at all, that is itself strong evidence the
 # activation half is absent, so the same fail-loud default applies via a
 # minimal python3 fallback (this repo already depends on python3 for the
 # lease broker itself).
 copy_claude_settings_guarded() {
  local src="$1"
  local dst="$2"
  local guard_args=(__link-claude-settings "$src" "$dst")
  if [[ "$allow_inactive_enforcement" == "1" ]]; then
    guard_args+=(--allow-inactive-enforcement)
  fi
  if command -v mosaic >/dev/null 2>&1; then
    if mosaic "${guard_args[@]}"; then
      return 0
    fi
    echo "[mosaic-link] Enforcement hooks were NOT wired into $dst (see message above)." >&2
    guard_degraded=1
    return 0
  fi
  echo "[mosaic-link] ERROR: 'mosaic' CLI not found on PATH — cannot confirm lease-enforcement" >&2
  echo "[mosaic-link] activation capability. enforcement requested but activation half absent —" >&2
  echo "[mosaic-link] needs a published CLI carrying launch-runtime activation + a broker" >&2
  echo "[mosaic-link] supervisor; refusing to wire a dead gate (see #869)." >&2
  if [[ "$allow_inactive_enforcement" == "1" ]]; then
    echo "[mosaic-link] WARNING: --allow-inactive-enforcement set — wiring $dst AS-IS (with" >&2
    echo "[mosaic-link] enforcement hooks) despite being unable to confirm activation." >&2
    copy_file_managed "$src" "$dst"
    return 0
  fi
  mkdir -p "$(dirname "$dst")"
  if command -v python3 >/dev/null 2>&1; then
    python3 - "$src" "$dst" <<'PYEOF'
 import json, sys
 src, dest = sys.argv[1], sys.argv[2]
 with open(src) as f:
    data = json.load(f)
 hooks = data.get("hooks", {})
 pre = hooks.get("PreToolUse", [])
 hooks["PreToolUse"] = [
    t for t in pre
    if not any("mutator-gate.py" in h.get("command", "") for h in t.get("hooks", []))
 ]
 if not hooks["PreToolUse"]:
    del hooks["PreToolUse"]
 stop = hooks.get("Stop", [])
 new_stop = []
 for t in stop:
    kept = [h for h in t.get("hooks", []) if "receipt-observer-client.py" not in h.get("command", "")]
    if kept:
        t = dict(t)
        t["hooks"] = kept
        new_stop.append(t)
 if new_stop:
    hooks["Stop"] = new_stop
 elif "Stop" in hooks:
    del hooks["Stop"]
 if hooks:
    data["hooks"] = hooks
 else:
    data.pop("hooks", None)
 with open(dest, "w") as f:
    json.dump(data, f, indent=2)
    f.write("\n")
 PYEOF
  else
    cp "$src" "$dst"
  fi
  guard_degraded=1
  return 0
 }
 remove_legacy_path() {
  local p="$1"
@@ -223,13 +110,6 @@ for runtime_file in \
  fi
  src="$MOSAIC_HOME/runtime/claude/$runtime_file"
  [[ -f "$src" ]] || continue
  if [[ "$runtime_file" == "settings.json" ]]; then
    # Install-ordering guard (#869 Point-1 C2): gate enforcement-hook wiring
    # on confirmed activation instead of the plain copy_file_managed used for
    # every other runtime file. See copy_claude_settings_guarded() above.
    copy_claude_settings_guarded "$src" "$HOME/.claude/$runtime_file"
    continue
  fi
  copy_file_managed "$src" "$HOME/.claude/$runtime_file"
 done
@@ -287,12 +167,3 @@ fi
 echo "[mosaic-link] Runtime assets synced (non-symlink mode)"
 echo "[mosaic-link] Canonical source: $MOSAIC_HOME"
 # Propagate the install-ordering guard's outcome (#869 Point-1 C2): every
 # other runtime asset above is best-effort/non-fatal, but a degraded
 # (enforcement-not-wired) settings.json must make THIS script's own exit
 # status non-zero so callers (framework/install.sh, finalize.ts) can surface
 # it — never silently.
 if [[ "$guard_degraded" == "1" ]]; then
  exit 1
 fi
--- a/packages/mosaic/framework/tools/_scripts/test-install-ordering-guard.sh
+++ b/packages/mosaic/framework/tools/_scripts/test-install-ordering-guard.sh
@@ -1,180 +0,0 @@
 #!/usr/bin/env bash
 # Regression harness for issue #869 Point-1 C2 — the install-ordering guard
 # wired into mosaic-link-runtime-assets.
 #
 # Root cause under test: mosaic-link-runtime-assets copies
 # runtime/claude/settings.json (which embeds the PreToolUse mutator-gate.py
 # hook and the Stop receipt-observer-client.py hook) straight into
 # ~/.claude/settings.json, unconditionally. If the lease-broker activation
 # half cannot be confirmed on this host, wiring those hooks bricks it with a
 # fail-closed gate that can never be satisfied.
 #
 # This harness never invokes a real `mosaic` CLI build — it stubs the
 # `__link-claude-settings` contract with a fake `mosaic` on PATH so the shell
 # WIRING (does mosaic-link-runtime-assets call out correctly? does it
 # propagate a degraded outcome? does it still copy every other runtime file?
 # does --allow-inactive-enforcement forward through?) is exercised
 # independently of the TS guard's own logic (already covered by
 # install-ordering-guard.spec.ts). It also exercises the no-mosaic-on-PATH
 # python3 fallback directly.
 #
 # Scenarios:
 #   1. probe=true (fake mosaic exits 0)  -> settings.json copied, script exits 0.
 #   2. probe=false (fake mosaic exits 1) -> script exits 1 (guard_degraded
 #      propagated), but every OTHER runtime file is still copied.
 #   3. probe=false + --allow-inactive-enforcement -> the flag is forwarded to
 #      the fake mosaic stub.
 #   4. No `mosaic` on PATH at all (activation unconfirmable) -> the python3
 #      fallback strips the enforcement hooks itself and the script exits 1.
 #   5. No `mosaic` on PATH + --allow-inactive-enforcement -> the python3
 #      fallback wires the hooks AS-IS and the script exits 0.
 set -uo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 LINK_SCRIPT="$SCRIPT_DIR/mosaic-link-runtime-assets"
 TMP_ROOT=$(mktemp -d)
 trap 'rm -rf "$TMP_ROOT"' EXIT
 fail=0
 fail_msg() {
    echo "FAIL: $*" >&2
    fail=1
 }
 FIXTURE_SETTINGS='{
  "model": "opus",
  "hooks": {
    "PreToolUse": [
      { "matcher": ".*", "hooks": [ { "type": "command", "command": "python3 ~/.config/mosaic/tools/lease-broker/mutator-gate.py --runtime claude" } ] },
      { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "~/.config/mosaic/tools/qa/prevent-memory-write.sh" } ] }
    ],
    "Stop": [
      { "hooks": [
        { "type": "command", "command": "python3 ~/.config/mosaic/tools/lease-broker/receipt-observer-client.py --runtime claude" },
        { "type": "command", "command": "~/.config/mosaic/tools/qa/reflect-stop-hook.sh" }
      ] }
    ]
  }
 }'
 # Sets up a fresh $MOSAIC_HOME/runtime/claude/{settings.json,CLAUDE.md,
 # hooks-config.json,context7-integration.md} + fresh $HOME, echoes both paths
 # space-separated for the caller to `read`.
 new_scenario_dirs() {
    local scenario="$1"
    local base="$TMP_ROOT/$scenario"
    local mosaic_home="$base/mosaic-home"
    local home="$base/home"
    mkdir -p "$mosaic_home/runtime/claude" "$home"
    printf '%s' "$FIXTURE_SETTINGS" > "$mosaic_home/runtime/claude/settings.json"
    echo "claude.md fixture" > "$mosaic_home/runtime/claude/CLAUDE.md"
    echo '{"hooks":{}}' > "$mosaic_home/runtime/claude/hooks-config.json"
    echo "context7 fixture" > "$mosaic_home/runtime/claude/context7-integration.md"
    echo "$mosaic_home" "$home"
 }
 settings_has_marker() {
    local file="$1" marker="$2"
    [[ -f "$file" ]] && grep -q "$marker" "$file"
 }
 # A fake `mosaic` binary implementing only the __link-claude-settings contract
 # this harness needs: writes dest verbatim (fixture is unmodified either way —
 # this stub only exercises the CALL CONTRACT, not the TS strip logic, which
 # has its own vitest coverage) and exits with the code the scenario wants.
 # Records the args it was called with so the harness can assert forwarding.
 make_fake_mosaic() {
    local bin_dir="$1" exit_code="$2"
    mkdir -p "$bin_dir"
    cat > "$bin_dir/mosaic" <<EOF
 #!/usr/bin/env bash
 set -euo pipefail
 echo "\$@" > "$bin_dir/mosaic.args"
 if [[ "\$1" == "__link-claude-settings" ]]; then
  cp "\$2" "\$3"
  exit $exit_code
 fi
 exit 0
 EOF
    chmod +x "$bin_dir/mosaic"
 }
 # --- Scenario 1: probe=true (fake mosaic exits 0) ---------------------------
 read -r MOSAIC_HOME_1 HOME_1 < <(new_scenario_dirs scenario1)
 BIN_1="$TMP_ROOT/scenario1/bin"
 make_fake_mosaic "$BIN_1" 0
 OUTPUT=$(MOSAIC_HOME="$MOSAIC_HOME_1" HOME="$HOME_1" PATH="$BIN_1:$PATH" "$LINK_SCRIPT" 2>&1)
 STATUS=$?
 [[ "$STATUS" -eq 0 ]] || fail_msg "scenario1 (probe=true): expected exit 0, got $STATUS. Output: $OUTPUT"
 [[ -f "$HOME_1/.claude/settings.json" ]] || fail_msg "scenario1: settings.json was not copied"
 # --- Scenario 2: probe=false (fake mosaic exits 1) --------------------------
 read -r MOSAIC_HOME_2 HOME_2 < <(new_scenario_dirs scenario2)
 BIN_2="$TMP_ROOT/scenario2/bin"
 make_fake_mosaic "$BIN_2" 1
 OUTPUT=$(MOSAIC_HOME="$MOSAIC_HOME_2" HOME="$HOME_2" PATH="$BIN_2:$PATH" "$LINK_SCRIPT" 2>&1)
 STATUS=$?
 [[ "$STATUS" -ne 0 ]] || fail_msg "scenario2 (probe=false, default): expected non-zero exit, got 0. Output: $OUTPUT"
 [[ -f "$HOME_2/.claude/CLAUDE.md" ]] || fail_msg "scenario2: CLAUDE.md was NOT copied even though it is independent of the settings.json guard"
 [[ -f "$HOME_2/.claude/hooks-config.json" ]] || fail_msg "scenario2: hooks-config.json was NOT copied"
 [[ -f "$HOME_2/.claude/context7-integration.md" ]] || fail_msg "scenario2: context7-integration.md was NOT copied"
 case "$OUTPUT" in
    *"NOT be wired"*|*"NOT wired"*) ;;
    *) fail_msg "scenario2: expected an actionable degraded-wiring message in output, got: $OUTPUT" ;;
 esac
 # --- Scenario 3: probe=false + --allow-inactive-enforcement forwards the flag
 read -r MOSAIC_HOME_3 HOME_3 < <(new_scenario_dirs scenario3)
 BIN_3="$TMP_ROOT/scenario3/bin"
 make_fake_mosaic "$BIN_3" 0
 MOSAIC_HOME="$MOSAIC_HOME_3" HOME="$HOME_3" PATH="$BIN_3:$PATH" "$LINK_SCRIPT" --allow-inactive-enforcement >/dev/null 2>&1
 RECORDED_ARGS="$(cat "$BIN_3/mosaic.args" 2>/dev/null || true)"
 case "$RECORDED_ARGS" in
    *"--allow-inactive-enforcement"*) ;;
    *) fail_msg "scenario3: --allow-inactive-enforcement was not forwarded to the mosaic CLI invocation (got: '$RECORDED_ARGS')" ;;
 esac
 # --- Scenario 4: no `mosaic` on PATH at all -> python3 fallback strips hooks
 read -r MOSAIC_HOME_4 HOME_4 < <(new_scenario_dirs scenario4)
 EMPTY_BIN="$TMP_ROOT/scenario4/empty-bin"
 mkdir -p "$EMPTY_BIN"
 # A PATH containing only python3 (for the fallback) + core utils, no mosaic.
 FALLBACK_PATH="$EMPTY_BIN:/usr/bin:/bin"
 OUTPUT=$(MOSAIC_HOME="$MOSAIC_HOME_4" HOME="$HOME_4" PATH="$FALLBACK_PATH" "$LINK_SCRIPT" 2>&1)
 STATUS=$?
 [[ "$STATUS" -ne 0 ]] || fail_msg "scenario4 (no mosaic on PATH, default): expected non-zero exit, got 0. Output: $OUTPUT"
 if settings_has_marker "$HOME_4/.claude/settings.json" "mutator-gate.py"; then
    fail_msg "scenario4: mutator-gate.py hook was wired even though mosaic could not be resolved (activation unconfirmable)"
 fi
 if settings_has_marker "$HOME_4/.claude/settings.json" "receipt-observer-client.py"; then
    fail_msg "scenario4: receipt-observer-client.py hook was wired even though mosaic could not be resolved"
 fi
 if ! settings_has_marker "$HOME_4/.claude/settings.json" "prevent-memory-write.sh"; then
    fail_msg "scenario4: the unrelated prevent-memory-write.sh hook was incorrectly dropped too"
 fi
 # --- Scenario 5: no `mosaic` on PATH + --allow-inactive-enforcement --------
 read -r MOSAIC_HOME_5 HOME_5 < <(new_scenario_dirs scenario5)
 OUTPUT=$(MOSAIC_HOME="$MOSAIC_HOME_5" HOME="$HOME_5" PATH="$FALLBACK_PATH" "$LINK_SCRIPT" --allow-inactive-enforcement 2>&1)
 STATUS=$?
 [[ "$STATUS" -eq 0 ]] || fail_msg "scenario5 (no mosaic, opt-out): expected exit 0, got $STATUS. Output: $OUTPUT"
 if ! settings_has_marker "$HOME_5/.claude/settings.json" "mutator-gate.py"; then
    fail_msg "scenario5: mutator-gate.py hook should have been wired (explicit opt-out set)"
 fi
 case "$OUTPUT" in
    *"WARNING"*"--allow-inactive-enforcement"*) ;;
    *) fail_msg "scenario5: expected a loud WARNING mentioning --allow-inactive-enforcement, got: $OUTPUT" ;;
 esac
 if [[ "$fail" -eq 0 ]]; then
    echo "install-ordering-guard regression passed (5/5 scenarios)"
 fi
 exit "$fail"
--- a/packages/mosaic/framework/tools/git/README.md
+++ b/packages/mosaic/framework/tools/git/README.md
@@ -33,64 +33,3 @@ The Gitea API token is **never passed on a curl command line.** An `Authorizatio
 Both `pr-review.sh` and `issue-comment.sh` accept an optional `--login <name>` flag that overrides the automatically detected Gitea login for that single invocation. The override selects **which credential the REST write, the `/user` identity lookup, and the read-back all use** — its token is resolved from the tea config for that login name (`get_gitea_token_for_login`), falling back to the repo host's credential when no login is named. The resolved login is **host- and port-bound**: the login's configured URL host **and effective port** (the scheme's default port — 80 for `http`, 443 for `https` — applies when a port is omitted, symmetrically on both sides) must match the repo remote's, so a login name shared across hosts (or an override configured for a different Gitea, including one on a different port of the same host) can never send one host's credential to another — a host or port mismatch fails closed rather than leaking a cross-host token. Resolving the acting identity and the read-back from the _same_ login that performs the write is essential: a write performed under an overridden login must be verified against that login's identity, not the host default's. Callers who need a different login than the host default should pass `--login <reviewer-login>`.
 As a durable successor to this mechanism, consider giving each reviewer/approver slot its own dedicated Gitea login credential, so that author≠reviewer holds at the credential level rather than relying on wrapper-level `--login` bookkeeping. This is a recommendation for future hardening, not something implemented by this flag.
 ## Per-agent Gitea identity (Gate-16 author≠reviewer)
 By default, git push/fetch (via `git-credential-mosaic`) and the API wrappers above (via
 `detect-platform.sh`'s `get_gitea_token`) all authenticate as the single shared Gitea
 account/token configured through `tools/_lib/credentials.sh`. That means every agent in a
 fleet commits, pushes, and opens PRs under one identity — with no cryptographic
 separation between an author and a reviewer.
 Both `git-credential-mosaic` and `get_gitea_token()` resolve an optional **per-agent
 identity** before falling back to the shared account:
 1. `MOSAIC_GIT_IDENTITY` environment variable, or
 2. `git config --get mosaic.gitIdentity` (set per-worktree; persists on disk across
   non-persistent shells — `git config mosaic.gitIdentity <agent-id>`), or
 3. (git-credential-mosaic only) the username git itself supplies for the credential
   request.
 If the resolved identity has a token file at
 `~/.config/mosaic/secrets/gitea-tokens/gitea-{usc,mosaicstack}-<agent-id>.token`, that
 identity + token is used. **Nothing configured → nothing changes**: with no per-slot
 token file present, both tools fall through to the existing shared-account path
 unchanged, so this feature is a no-op on any host that hasn't provisioned per-slot
 tokens.
 ### Enabling it for a clone
 The framework installer syncs `git-credential-mosaic` to
 `~/.config/mosaic/tools/git/git-credential-mosaic` (executable) on every install/update,
 but does **not** register it as git's credential helper automatically. Registration is a
 one-time, explicit step:
 ```bash
 # Per-repo (recommended — scopes the helper to this clone only):
 git config credential.helper "$HOME/.config/mosaic/tools/git/git-credential-mosaic"
 # Per-worktree identity pin (Gate-16 separation):
 git config mosaic.gitIdentity <agent-id>
 ```
 This is deliberately **not** auto-registered on install/update: `credential.helper` is
 global, order-sensitive git config (`~/.gitconfig`) that can already hold an
 operator-chosen credential manager (keychain, `store`, `manager-core`, …) for
 repositories unrelated to Mosaic. Silently inserting an entry on every framework
 install/upgrade risks reordering or shadowing that operator-owned surface across the
 whole host — the same operator-owned config the installer's manifest system is
 otherwise careful never to touch. Because identity is already resolved per-worktree
 (`mosaic.gitIdentity`), the correct granularity for registering the helper is per-clone
 too, so a documented manual step is the right shape here, not a global auto-write.
 ### PowerShell parity
 `detect-platform.ps1`'s Gitea wrappers authenticate through `tea` CLI logins
 (`Get-GiteaLoginForHost`), not a raw-token `get_gitea_token`-equivalent function — there
 is nothing to prepend the identity-resolution block to on the PowerShell side. A native
 PowerShell git-credential helper is also unnecessary: `git-credential-mosaic` is invoked
 by git's credential-helper protocol (stdin/stdout), which works identically under Git for
 Windows' bundled `bash`/`sh` when configured via `credential.helper`, without a `.ps1`
 counterpart. A `tea`-login-based per-agent identity for the PowerShell wrappers is a
 separate, larger design (mapping identities to `tea login` profiles) and is out of scope
 here.
--- a/packages/mosaic/framework/tools/git/detect-platform.sh
+++ b/packages/mosaic/framework/tools/git/detect-platform.sh
@@ -505,28 +505,6 @@ get_gitea_token() {
    script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
    local cred_loader="$script_dir/../_lib/credentials.sh"
    # 0. Per-agent identity (Gate-16 author≠reviewer). If MOSAIC_GIT_IDENTITY, or the
    #    per-worktree `git config mosaic.gitIdentity`, resolves to an agent that has a
    #    stored per-slot token for this host, act AS that agent so API tooling
    #    (pr-create, issue-create, …) authors under the right identity — matching the
    #    git credential helper. Backward-compatible: nothing resolvable → shared logic below.
    local _ident="${MOSAIC_GIT_IDENTITY:-}"
    [[ -z "$_ident" ]] && _ident="$(git config --get mosaic.gitIdentity 2>/dev/null || true)"
    if [[ -n "$_ident" ]]; then
        local _idpfx=""
        case "$host" in
            git.uscllc.com)      _idpfx=gitea-usc ;;
            git.mosaicstack.dev) _idpfx=gitea-mosaicstack ;;
        esac
        if [[ -n "$_idpfx" ]]; then
            local _idtok="$HOME/.config/mosaic/secrets/gitea-tokens/${_idpfx}-${_ident}.token"
            if [[ -r "$_idtok" ]]; then
                cat "$_idtok"
                return 0
            fi
        fi
    fi
    # 1. Mosaic credential loader (host → service mapping, run in subshell to avoid polluting env)
    if [[ -f "$cred_loader" ]]; then
        local token
--- a/packages/mosaic/framework/tools/git/git-credential-mosaic
+++ b/packages/mosaic/framework/tools/git/git-credential-mosaic
@@ -1,69 +0,0 @@
 #!/bin/bash
 # git-credential-mosaic — git credential helper — resolves Gitea tokens from
 # the Mosaic credential store at runtime so remote URLs never embed secrets.
 #
 # Install (one-time, per clone or globally):
 #   git config credential.helper "$HOME/.config/mosaic/tools/git/git-credential-mosaic"
 #   # or, fleet-wide: git config --global credential.helper "$HOME/.config/mosaic/tools/git/git-credential-mosaic"
 #
 # Per-agent Gate-16 identity (author != reviewer separation):
 #   git config mosaic.gitIdentity <agent-id>   # per-worktree, persists on disk
 #   # or: export MOSAIC_GIT_IDENTITY=<agent-id>
 #
 # Resolution priority: MOSAIC_GIT_IDENTITY env > git config mosaic.gitIdentity
 # (per-worktree, survives across non-persistent shells) > git-supplied username
 # (credential.username / URL). When the resolved identity has a matching
 # per-agent token file, use it instead of the shared account. Backward
 # compatible: nothing resolvable -> shared token (unchanged behavior).
 [ "$1" = "get" ] || exit 0
 host=""; username_in=""
 while IFS= read -r line; do
  [ -z "$line" ] && break
  case "$line" in
    host=*)     host=${line#host=};;
    username=*) username_in=${line#username=};;
  esac
 done
 # Per-agent identity resolution (Gate-16 author≠reviewer separation).
 # Priority: MOSAIC_GIT_IDENTITY env  >  git config mosaic.gitIdentity (per-worktree,
 # survives across non-persistent shells)  >  git-supplied username (credential.username
 # / URL). When the resolved identity has a matching per-agent token, use it instead of
 # the shared account. Backward-compatible: nothing resolvable → shared token.
 ident="$MOSAIC_GIT_IDENTITY"
 [ -z "$ident" ] && ident=$(git config --get mosaic.gitIdentity 2>/dev/null)
 [ -z "$ident" ] && ident="$username_in"
 if [ -n "$ident" ]; then
  case "$host" in
    git.uscllc.com)      idpfx=gitea-usc;;
    git.mosaicstack.dev) idpfx=gitea-mosaicstack;;
    *) idpfx="";;
  esac
  if [ -n "$idpfx" ]; then
    idtok="$HOME/.config/mosaic/secrets/gitea-tokens/${idpfx}-${ident}.token"
    if [ -r "$idtok" ]; then
      echo "username=${ident}"
      echo "password=$(cat "$idtok")"
      exit 0
    fi
  fi
 fi
 case "$host" in
  git.uscllc.com)      svc=gitea-usc;;
  git.mosaicstack.dev) svc=gitea-mosaicstack;;
  *) exit 0;;
 esac
 # Script-relative (not $HOME-absolute) so this resolves correctly regardless
 # of where the framework installer places tools/ under $HOME — mirrors
 # detect-platform.sh's own cred_loader resolution in this same directory.
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=../_lib/credentials.sh
 source "$script_dir/../_lib/credentials.sh"
 load_credentials "$svc" >/dev/null 2>&1 || exit 0
 # GITEA_USER is not populated by load_credentials (it only exports
 # GITEA_URL/GITEA_TOKEN for gitea-*), so this fallback is normally taken. Gitea's
 # git-over-HTTP auth authenticates from the token itself (the password field),
 # not from the username string, so any non-empty placeholder works here — this
 # is deliberately NOT a real account name (framework files must stay
 # operator-agnostic; see tools/quality/scripts/verify-sanitized.sh).
 echo "username=${GITEA_USER:-git}"
 echo "password=$GITEA_TOKEN"
--- a/packages/mosaic/framework/tools/git/test-git-credential-mosaic.sh
+++ b/packages/mosaic/framework/tools/git/test-git-credential-mosaic.sh
@@ -1,161 +0,0 @@
 #!/usr/bin/env bash
 # Regression harness for `git-credential-mosaic` — per-agent Gitea identity
 # resolution (Gate-16 author≠reviewer separation).
 #
 # Covers:
 #   1. Identity resolution priority: MOSAIC_GIT_IDENTITY env > git config
 #      mosaic.gitIdentity (per-worktree) > git-supplied username.
 #   2. Correct per-slot token file path chosen per host
 #      (gitea-usc-<id>.token vs gitea-mosaicstack-<id>.token).
 #   3. Per-slot token present -> emits that identity + token.
 #   4. Per-slot token absent -> falls back to the shared account
 #      (backward-compat / no-op for hosts without per-slot tokens).
 #   5. Unknown/unrelated host -> exits 0 with no output (passthrough).
 #
 # Uses stubbed token files under a fake HOME + a real (throwaway) git repo.
 # NEVER reads real secrets or touches the real ~/.config/mosaic/secrets.
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/git-credential-mosaic}"
 FAKE_HOME="$WORK_DIR/home"
 REPO_DIR="$WORK_DIR/repo"
 # Mirror the real deployed layout (~/.config/mosaic/tools/{git,_lib}/) under the
 # fake HOME: git-credential-mosaic resolves its credentials.sh sibling via a
 # script-relative path (BASH_SOURCE), so the copy must live next to a stubbed
 # _lib/credentials.sh, not the real one, to keep this test hermetic.
 HELPER="$FAKE_HOME/.config/mosaic/tools/git/git-credential-mosaic"
 rm -rf "$WORK_DIR"
 mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" \
         "$FAKE_HOME/.config/mosaic/tools/git" \
         "$FAKE_HOME/.config/mosaic/tools/_lib" \
         "$REPO_DIR"
 cp "$SCRIPT_DIR/git-credential-mosaic" "$HELPER"
 chmod +x "$HELPER"
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" config user.email "test@example.invalid"
 git -C "$REPO_DIR" config user.name "Test"
 # Fake shared-account credential loader — stands in for
 # tools/_lib/credentials.sh's load_credentials(), scoped to this test only.
 cat > "$FAKE_HOME/.config/mosaic/tools/_lib/credentials.sh" <<'SH'
 load_credentials() {
  case "$1" in
    gitea-mosaicstack) GITEA_URL="https://git.mosaicstack.dev"; GITEA_TOKEN="shared-mosaicstack-token"; export GITEA_URL GITEA_TOKEN; return 0 ;;
    gitea-usc)         GITEA_URL="https://git.uscllc.com"; GITEA_TOKEN="shared-usc-token"; export GITEA_URL GITEA_TOKEN; return 0 ;;
    *) return 1 ;;
  esac
 }
 SH
 fail=0
 assert_eq() {
  local desc="$1" expected="$2" actual="$3"
  if [[ "$expected" != "$actual" ]]; then
    echo "FAIL: $desc — expected '$expected', got '$actual'" >&2
    fail=1
  fi
 }
 # Feed "host=<h>\nusername=<u>\n\n" on stdin (mirrors git's credential protocol)
 # and run the helper with the fake HOME, inside REPO_DIR (so `git config
 # mosaic.gitIdentity` resolves per-worktree), plus any extra env passed in $@.
 run_helper() {
  local host="$1" username_in="$2"; shift 2
  (
    cd "$REPO_DIR"
    env -i HOME="$FAKE_HOME" PATH="$PATH" "$@" bash "$HELPER" get <<EOF
 host=$host
 username=$username_in
 EOF
  )
 }
 # ---------------------------------------------------------------------------
 # 1. No identity resolvable anywhere, no per-slot token -> shared fallback
 #    (backward-compat: unchanged behavior when nothing is configured).
 # ---------------------------------------------------------------------------
 git -C "$REPO_DIR" config --unset mosaic.gitIdentity 2>/dev/null || true
 out=$(run_helper "git.mosaicstack.dev" "")
 assert_eq "shared fallback: username" "username=git" "$(echo "$out" | grep '^username=')"
 assert_eq "shared fallback: password" "password=shared-mosaicstack-token" "$(echo "$out" | grep '^password=')"
 # ---------------------------------------------------------------------------
 # 2. git-supplied username resolves to an identity WITH a per-slot token ->
 #    that identity + token wins over the shared account.
 # ---------------------------------------------------------------------------
 echo -n "agentA-mosaicstack-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentA.token"
 out=$(run_helper "git.mosaicstack.dev" "agentA")
 assert_eq "username-resolved identity: username" "username=agentA" "$(echo "$out" | grep '^username=')"
 assert_eq "username-resolved identity: password" "password=agentA-mosaicstack-token" "$(echo "$out" | grep '^password=')"
 # ---------------------------------------------------------------------------
 # 3. git config mosaic.gitIdentity (per-worktree) beats git-supplied username.
 # ---------------------------------------------------------------------------
 echo -n "agentB-mosaicstack-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentB.token"
 git -C "$REPO_DIR" config mosaic.gitIdentity agentB
 out=$(run_helper "git.mosaicstack.dev" "agentA")
 assert_eq "git-config beats username: username" "username=agentB" "$(echo "$out" | grep '^username=')"
 assert_eq "git-config beats username: password" "password=agentB-mosaicstack-token" "$(echo "$out" | grep '^password=')"
 # ---------------------------------------------------------------------------
 # 4. MOSAIC_GIT_IDENTITY env beats git config mosaic.gitIdentity.
 # ---------------------------------------------------------------------------
 echo -n "agentC-mosaicstack-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentC.token"
 out=$(run_helper "git.mosaicstack.dev" "agentA" MOSAIC_GIT_IDENTITY=agentC)
 assert_eq "env beats git-config: username" "username=agentC" "$(echo "$out" | grep '^username=')"
 assert_eq "env beats git-config: password" "password=agentC-mosaicstack-token" "$(echo "$out" | grep '^password=')"
 git -C "$REPO_DIR" config --unset mosaic.gitIdentity
 # ---------------------------------------------------------------------------
 # 5. Identity resolves, but no matching per-slot token file -> falls back to
 #    the shared account (per-agent identity is opt-in, not a hard requirement).
 # ---------------------------------------------------------------------------
 out=$(run_helper "git.mosaicstack.dev" "no-such-agent")
 assert_eq "no per-slot token: username" "username=git" "$(echo "$out" | grep '^username=')"
 assert_eq "no per-slot token: password" "password=shared-mosaicstack-token" "$(echo "$out" | grep '^password=')"
 # ---------------------------------------------------------------------------
 # 6. Correct per-slot token PATH is chosen per host: same agent id, different
 #    host prefix (gitea-usc- vs gitea-mosaicstack-).
 # ---------------------------------------------------------------------------
 echo -n "agentD-usc-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-usc-agentD.token"
 out=$(run_helper "git.uscllc.com" "agentD")
 assert_eq "host-scoped token path (usc): username" "username=agentD" "$(echo "$out" | grep '^username=')"
 assert_eq "host-scoped token path (usc): password" "password=agentD-usc-token" "$(echo "$out" | grep '^password=')"
 # agentD has NO mosaicstack token -> must fall back to shared mosaicstack, not
 # leak the usc token across hosts.
 out=$(run_helper "git.mosaicstack.dev" "agentD")
 assert_eq "host-scoped token path (cross-host must not leak): username" "username=git" "$(echo "$out" | grep '^username=')"
 assert_eq "host-scoped token path (cross-host must not leak): password" "password=shared-mosaicstack-token" "$(echo "$out" | grep '^password=')"
 # ---------------------------------------------------------------------------
 # 7. Unrelated/unknown host -> exit 0, no output (passthrough for non-Gitea
 #    remotes, e.g. github.com via a different credential helper).
 # ---------------------------------------------------------------------------
 out=$(run_helper "github.com" "agentA")
 assert_eq "unknown host: no output" "" "$out"
 # ---------------------------------------------------------------------------
 # 8. Non-"get" verb (store/erase) -> exit 0, no output (git-credential
 #    protocol: this helper only implements get).
 # ---------------------------------------------------------------------------
 store_out=$(cd "$REPO_DIR" && env -i HOME="$FAKE_HOME" PATH="$PATH" bash "$HELPER" store <<EOF
 host=git.mosaicstack.dev
 username=agentA
 password=whatever
 EOF
 )
 assert_eq "store verb: no output" "" "$store_out"
 if [[ "$fail" -eq 0 ]]; then
  echo "git-credential-mosaic identity resolution regression passed"
 fi
 exit "$fail"
--- a/packages/mosaic/framework/tools/git/test-gitea-token-identity.sh
+++ b/packages/mosaic/framework/tools/git/test-gitea-token-identity.sh
@@ -1,122 +0,0 @@
 #!/usr/bin/env bash
 # Regression harness for detect-platform.sh's get_gitea_token() per-agent
 # identity resolution (Gate-16 author≠reviewer separation) — the API-tooling
 # counterpart to git-credential-mosaic, so pr-create.sh/issue-create.sh/etc.
 # open records under the resolved agent identity, not the shared account.
 #
 # Covers:
 #   1. Identity resolution priority: MOSAIC_GIT_IDENTITY env > git config
 #      mosaic.gitIdentity (per-worktree).
 #   2. Correct per-slot token file path chosen per host
 #      (gitea-usc-<id>.token vs gitea-mosaicstack-<id>.token).
 #   3. Per-slot token present -> that token is returned (agent-authored calls).
 #   4. Per-slot token absent -> falls back to the shared credential-loader
 #      token (backward-compat / no-op for hosts without per-slot tokens).
 #   5. Unrelated host with no shared credentials configured -> failure
 #      (unchanged, existing behavior).
 #
 # Uses a stubbed credentials.json + stubbed per-slot token files under a fake
 # HOME. NEVER reads real secrets or touches the real ~/.config/mosaic/secrets.
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/gitea-token-identity}"
 FAKE_HOME="$WORK_DIR/home"
 REPO_DIR="$WORK_DIR/repo"
 CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
 rm -rf "$WORK_DIR"
 mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$REPO_DIR"
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
 cat > "$CREDENTIALS_FILE" <<'JSON'
 {
  "gitea": {
    "mosaicstack": {
      "url": "https://git.mosaicstack.dev",
      "token": "shared-mosaicstack-token"
    },
    "usc": {
      "url": "https://git.uscllc.com",
      "token": "shared-usc-token"
    }
  }
 }
 JSON
 fail=0
 assert_eq() {
  local desc="$1" expected="$2" actual="$3"
  if [[ "$expected" != "$actual" ]]; then
    echo "FAIL: $desc — expected '$expected', got '$actual'" >&2
    fail=1
  fi
 }
 # Runs get_gitea_token for $1=host inside REPO_DIR (per-worktree git config
 # resolves there) with a fake HOME + the stub credentials.json, plus any
 # extra env passed in $@.
 call_get_gitea_token() {
  local host="$1"; shift
  (
    cd "$REPO_DIR"
    # shellcheck disable=SC2016 # deliberately deferred: $DETECT_PLATFORM_SH is
    # expanded by the INNER bash -c (via the exported env var below), not here.
    env -i HOME="$FAKE_HOME" PATH="$PATH" MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
      DETECT_PLATFORM_SH="$SCRIPT_DIR/detect-platform.sh" "$@" \
      bash -c 'source "$DETECT_PLATFORM_SH"; get_gitea_token "$1"' _ "$host"
  )
 }
 # ---------------------------------------------------------------------------
 # 1. No identity resolvable -> shared credential-loader token (unchanged).
 # ---------------------------------------------------------------------------
 git -C "$REPO_DIR" config --unset mosaic.gitIdentity 2>/dev/null || true
 out=$(call_get_gitea_token "git.mosaicstack.dev")
 assert_eq "shared fallback (no identity)" "shared-mosaicstack-token" "$out"
 # ---------------------------------------------------------------------------
 # 2. git config mosaic.gitIdentity resolves to an agent WITH a per-slot
 #    token -> that token wins over the shared account.
 # ---------------------------------------------------------------------------
 echo -n "agentA-mosaicstack-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentA.token"
 git -C "$REPO_DIR" config mosaic.gitIdentity agentA
 out=$(call_get_gitea_token "git.mosaicstack.dev")
 assert_eq "git-config identity token" "agentA-mosaicstack-token" "$out"
 # ---------------------------------------------------------------------------
 # 3. MOSAIC_GIT_IDENTITY env beats git config mosaic.gitIdentity.
 # ---------------------------------------------------------------------------
 echo -n "agentB-mosaicstack-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentB.token"
 out=$(call_get_gitea_token "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentB)
 assert_eq "env beats git-config identity token" "agentB-mosaicstack-token" "$out"
 # ---------------------------------------------------------------------------
 # 4. Identity resolves but has no per-slot token for THIS host -> falls back
 #    to the shared token (per-agent identity is opt-in per host).
 # ---------------------------------------------------------------------------
 git -C "$REPO_DIR" config mosaic.gitIdentity no-such-agent
 out=$(call_get_gitea_token "git.mosaicstack.dev")
 assert_eq "no per-slot token falls back to shared" "shared-mosaicstack-token" "$out"
 # ---------------------------------------------------------------------------
 # 5. Correct per-slot token PATH per host: same agent id, only a usc token
 #    exists -> usc host returns it, mosaicstack host must NOT leak it and
 #    instead falls back to the shared mosaicstack token.
 # ---------------------------------------------------------------------------
 echo -n "agentD-usc-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-usc-agentD.token"
 git -C "$REPO_DIR" config mosaic.gitIdentity agentD
 out=$(call_get_gitea_token "git.uscllc.com")
 assert_eq "host-scoped token path (usc)" "agentD-usc-token" "$out"
 out=$(call_get_gitea_token "git.mosaicstack.dev")
 assert_eq "host-scoped token path (no cross-host leak)" "shared-mosaicstack-token" "$out"
 git -C "$REPO_DIR" config --unset mosaic.gitIdentity
 if [[ "$fail" -eq 0 ]]; then
  echo "get_gitea_token identity resolution regression passed"
 fi
 exit "$fail"
--- a/packages/mosaic/framework/tools/lease-broker/activation_version_gate.py
+++ b/packages/mosaic/framework/tools/lease-broker/activation_version_gate.py
@@ -1,180 +0,0 @@
 #!/usr/bin/env python3
 """Enforcement-side version-coupling gate (issue #869, Point-1 card C4).
 Root cause this exists to guard against (#828 version skew, restated from
 the C1 activation probe in ``lease-activation-probe.ts``): the lease
 broker's ENFORCEMENT half (this toolkit — ``launch-runtime.py``,
 ``mutator-gate.py``, ``revoke-lease.py``) and its ACTIVATION half
 (``execLeaseGatedRuntime()`` in ``launch.ts``, which chains the gated
 runtime through ``launch-runtime.py`` and injects ``MOSAIC_LEASE_*``) ship
 on different channels — an npm package and a framework/CLI reseed. C1 gave
 the activation half a versioned, machine-checkable identity
 (``LEASE_ACTIVATION_CAPABILITY``, printed by the CLI's hidden
 ``mosaic __lease-capability`` subcommand). That identity is inert on its
 own: nothing yet asserted that ENFORCEMENT actually requires the version
 ACTIVATION advertises. This module is that assertion, owned by the
 enforcement side.
 ``EXPECTED_ACTIVATION_CAPABILITY`` below is this toolkit's own contract
 declaration — bump it only when this toolkit's launch/gate seam starts
 requiring a different activation contract (new env vars it depends on,
 changed chaining behavior, etc.), independent of any package semver, for
 the same reason C1's constant is: #828 happened precisely because a
 version number that should have moved did not.
 This module never talks to a real broker or a real installed CLI in its
 own tests — both the probe's command resolution and its ``run`` transport
 are injectable so tests can drive every branch with fakes/stubs (see
 ``version_coupling_unittest.py``).
 """
 from __future__ import annotations
 import json
 import os
 import shlex
 import shutil
 import subprocess
 from collections.abc import Callable, Mapping
 from typing import Final, TypedDict
 class ActivationCapability(TypedDict):
    name: str
    version: int
 # ENFORCEMENT-side expected activation contract. OWNED by this toolkit (the
 # enforcement half). Mirrors — but is deliberately a SEPARATE constant from
 # — `LEASE_ACTIVATION_CAPABILITY` in
 # `packages/mosaic/src/commands/lease-activation-probe.ts` (the activation
 # half's own declaration of what it implements). The two are compared at
 # runtime by `assert_activation_capability_matches()`; drift between them is
 # exactly the version-skew failure mode #828/#869 exist to catch, and must
 # FAIL LOUD, never a silent pass and never a dead (always-true) gate.
 EXPECTED_ACTIVATION_CAPABILITY: Final[ActivationCapability] = {
    "name": "lease-runtime-activation",
    "version": 1,
 }
 # Matches `LEASE_CAPABILITY_PROBE_COMMAND` in lease-activation-probe.ts —
 # the hidden CLI subcommand that prints the activation half's advertised
 # capability as compact JSON.
 LEASE_CAPABILITY_PROBE_COMMAND: Final = "__lease-capability"
 PROBE_TIMEOUT_SECONDS: Final = 2.0
 # Override hook: a full shell-style command line (parsed with `shlex.split`)
 # to run INSTEAD of resolving `mosaic` on PATH and appending the probe
 # subcommand. Real deployments should never need this — `mosaic` is on PATH
 # whenever a runtime was launched via `mosaic <cmd>` in the first place, the
 # only real caller of this seam. It exists for integration tests that spawn
 # `launch-runtime.py` directly (never through the real CLI) to supply a
 # fake/stub CLI probe, matching the existing convention of those tests
 # supplying a fake broker and a fake runtime binary rather than depending on
 # host state.
 MOSAIC_COMMAND_OVERRIDE_VAR: Final = "MOSAIC_LEASE_VERSION_PROBE_COMMAND"
 class VersionCouplingError(Exception):
    """Raised when the activation capability is absent, unreadable, or does
    not match what enforcement expects. Callers MUST fail loud on this
    (non-zero exit, clear actionable stderr) — never swallow it into a
    silent pass, and never let its absence be treated as compatible."""
 def _resolve_probe_command(environ: Mapping[str, str]) -> list[str] | None:
    override = environ.get(MOSAIC_COMMAND_OVERRIDE_VAR)
    if override:
        parsed = shlex.split(override)
        return parsed or None
    resolved = shutil.which("mosaic")
    if resolved is None:
        return None
    return [resolved, LEASE_CAPABILITY_PROBE_COMMAND]
 def default_probe_activation_capability(
    environ: Mapping[str, str] | None = None,
    *,
    run: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
 ) -> ActivationCapability | None:
    """Real capability lookup: resolves and executes the CLI's hidden
    ``__lease-capability`` probe subcommand out-of-process (the same
    mechanism `defaultCapabilityProbe()` in lease-activation-probe.ts uses
    from the activation side) and parses its JSON stdout. Any failure to
    resolve a command, spawn it, have it exit zero, or produce a well-shaped
    ``{name, version}`` JSON object is treated as NO capability (``None``)
    — fail-closed, never a fabricated/guessed capability.
    """
    source_environment = os.environ if environ is None else environ
    command = _resolve_probe_command(source_environment)
    if command is None:
        return None
    try:
        completed = run(
            command,
            capture_output=True,
            text=True,
            timeout=PROBE_TIMEOUT_SECONDS,
            check=False,
        )
    except (OSError, subprocess.TimeoutExpired, ValueError):
        return None
    if completed.returncode != 0:
        return None
    try:
        parsed = json.loads(completed.stdout)
    except json.JSONDecodeError:
        return None
    if (
        not isinstance(parsed, dict)
        or not isinstance(parsed.get("name"), str)
        or not isinstance(parsed.get("version"), int)
        or isinstance(parsed.get("version"), bool)
    ):
        return None
    return {"name": parsed["name"], "version": parsed["version"]}
 def format_mismatch_message(
    activation: ActivationCapability | None,
    expected: ActivationCapability,
 ) -> str:
    """Actionable, non-silent remediation message for either failure shape:
    absent/unreadable capability, or a present-but-incompatible one."""
    if activation is None:
        return (
            "Mosaic lease activation capability unreadable: enforcement "
            f"expects '{expected['name']}' v{expected['version']} but the "
            f"CLI's `mosaic {LEASE_CAPABILITY_PROBE_COMMAND}` probe produced "
            "no usable result (mosaic not on PATH, non-zero exit, or "
            "malformed output) — framework/CLI version skew; upgrade both "
            "as one unit; see #869."
        )
    if activation["name"] != expected["name"]:
        return (
            f"activation capability name '{activation['name']}' != "
            f"enforcement expects '{expected['name']}' — framework/CLI "
            "version skew; upgrade both as one unit; see #869"
        )
    return (
        f"activation capability v{activation['version']} != enforcement "
        f"expects v{expected['version']} — framework/CLI version skew; "
        "upgrade both as one unit; see #869"
    )
 def assert_activation_capability_matches(
    activation: ActivationCapability | None,
    expected: ActivationCapability = EXPECTED_ACTIVATION_CAPABILITY,
 ) -> None:
    """Raise `VersionCouplingError` unless `activation` is present AND its
    `name`/`version` exactly match `expected`. Absence is treated the same
    as a mismatch — never a silent pass."""
    if (
        activation is None
        or activation.get("name") != expected["name"]
        or activation.get("version") != expected["version"]
    ):
        raise VersionCouplingError(format_mismatch_message(activation, expected))
--- a/packages/mosaic/framework/tools/lease-broker/launch-runtime.py
+++ b/packages/mosaic/framework/tools/lease-broker/launch-runtime.py
@@ -12,24 +12,11 @@ from collections.abc import Callable, Mapping, Sequence
 from pathlib import Path
 from typing import Final
 from activation_version_gate import (
    EXPECTED_ACTIVATION_CAPABILITY,
    ActivationCapability,
    VersionCouplingError,
    assert_activation_capability_matches,
    default_probe_activation_capability,
 )
 from lease_generation import initialize_runtime_generation
 MAX_FRAME: Final = 64 * 1024
 BROKER_TIMEOUT_SECONDS: Final = 1.5
 CLAUDE_DANGEROUS_FLAG: Final = "--dangerously-skip-permissions"
 # Distinct, non-overlapping exit code for the C4 version-coupling gate (see
 # `activation_version_gate.py`) — deliberately different from the `1`
 # (broker registration failed closed) and `64` (usage error) codes already
 # owned by this script, so a version-skew denial is unambiguous in caller
 # logs/tests and is never confused with a broker-availability failure.
 EXIT_VERSION_SKEW: Final = 65
 def broker_request(socket_path: Path, request: dict[str, object]) -> dict[str, object]:
@@ -60,10 +47,6 @@ def main(
    request: Callable[[Path, dict[str, object]], dict[str, object]] = broker_request,
    execute: Callable[[str, list[str], dict[str, str]], object] = os.execvpe,
    initialize_generation: Callable[[Path, int], None] = initialize_runtime_generation,
    probe_activation_capability: Callable[
        [Mapping[str, str]], ActivationCapability | None
    ] = default_probe_activation_capability,
    expected_activation_capability: ActivationCapability = EXPECTED_ACTIVATION_CAPABILITY,
 ) -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--runtime", required=True, choices=("claude", "pi"))
@@ -83,25 +66,6 @@ def main(
        command = [command[0], CLAUDE_DANGEROUS_FLAG, *command[1:]]
    source_environment = os.environ if environ is None else environ
    # C4 version-coupling gate (#869 Point-1): before this ENFORCEMENT half
    # chains into anything, assert that the ACTIVATION contract it is about
    # to rely on (MOSAIC_LEASE_* injection, broker chaining) matches what
    # this enforcement build expects. This is a build/deploy-defect check,
    # not a broker-availability question, so it runs before — and
    # independently of — broker registration below, and it FAILS LOUD: a
    # clear stderr message plus a dedicated non-zero exit code, never a
    # silent pass and never folded into the generic registration-failure
    # branch.
    try:
        assert_activation_capability_matches(
            probe_activation_capability(source_environment),
            expected_activation_capability,
        )
    except VersionCouplingError as version_error:
        print(str(version_error), file=sys.stderr)
        return EXIT_VERSION_SKEW
    try:
        socket_path = Path(source_environment["MOSAIC_LEASE_BROKER_SOCKET"])
        generation = int(source_environment.get("MOSAIC_RUNTIME_GENERATION", "1"))
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -25,7 +25,7 @@
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
    "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh"
+    "test:framework-shell": "python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
--- a/packages/mosaic/src/cli.ts
+++ b/packages/mosaic/src/cli.ts
@@ -22,7 +22,6 @@ import { registerSkillCommand } from './commands/skill.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
 import { registerLeaseCapabilityProbe } from './commands/lease-activation-probe.js';
 import { registerInstallOrderingGuardCommand } from './commands/install-ordering-guard.js';
 import { registerAuthCommand } from './commands/auth.js';
 import { registerFederationCommand } from './commands/federation.js';
 import { registerGatewayCommand } from './commands/gateway.js';
@@ -84,10 +83,6 @@ registerLaunchCommands(program);
 registerLeaseCapabilityProbe(program);
 // ─── install-ordering guard (hidden; #869 Point-1 C2) ───────────────────
 registerInstallOrderingGuardCommand(program);
 // ─── login ──────────────────────────────────────────────────────────────
 program
--- a/packages/mosaic/src/commands/install-ordering-guard.spec.ts
+++ b/packages/mosaic/src/commands/install-ordering-guard.spec.ts
@@ -1,301 +0,0 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { leaseEnforcementActivatable } from './lease-activation-probe.js';
 import {
  ENFORCEMENT_HOOK_MARKERS,
  FAIL_LOUD_MESSAGE,
  guardClaudeSettingsWiring,
  loudOptOutMessage,
  runInstallOrderingGuard,
  settingsHasEnforcementHooks,
  stripEnforcementHooks,
 } from './install-ordering-guard.js';
 /**
 * Red-first tests for issue #869 Point-1 C2 — the install-ordering guard.
 *
 * Root cause under test: `mosaic-link-runtime-assets` copies
 * `runtime/claude/settings.json` (which embeds the PreToolUse
 * `mutator-gate.py` hook and the Stop `receipt-observer-client.py` hook)
 * straight into `~/.claude/settings.json`, unconditionally. If the
 * activation half (C1: `leaseEnforcementActivatable()`) cannot be confirmed,
 * wiring those hooks bricks the host with a fail-closed gate that can never
 * be satisfied. This guard must refuse to wire in that case by default, and
 * only wire anyway on an explicit, loud opt-out.
 *
 * All fixtures use temp directories — this suite never reads or writes the
 * real `~/.claude/settings.json`.
 */
 const FIXTURE_SETTINGS = {
  model: 'opus',
  hooks: {
    PreCompact: [
      {
        matcher: '.*',
        hooks: [{ type: 'command', command: 'python3 revoke-lease.py --reason pre-compact' }],
      },
    ],
    PreToolUse: [
      {
        matcher: '.*',
        hooks: [
          {
            type: 'command',
            command: 'python3 ~/.config/mosaic/tools/lease-broker/mutator-gate.py --runtime claude',
            timeout: 3,
          },
        ],
      },
      {
        matcher: 'Write|Edit|MultiEdit',
        hooks: [{ type: 'command', command: '~/.config/mosaic/tools/qa/prevent-memory-write.sh' }],
      },
    ],
    PostToolUse: [
      {
        matcher: 'Edit|MultiEdit|Write',
        hooks: [{ type: 'command', command: '~/.config/mosaic/tools/qa/qa-hook-stdin.sh' }],
      },
    ],
    Stop: [
      {
        hooks: [
          {
            type: 'command',
            command:
              'python3 ~/.config/mosaic/tools/lease-broker/receipt-observer-client.py --runtime claude',
            timeout: 3,
          },
          { type: 'command', command: '~/.config/mosaic/tools/qa/reflect-stop-hook.sh' },
        ],
      },
    ],
  },
  enabledPlugins: { 'feature-dev@claude-plugins-official': true },
 };
 function fixtureJson(): string {
  return JSON.stringify(FIXTURE_SETTINGS, null, 2) + '\n';
 }
 describe('stripEnforcementHooks', () => {
  it('removes the PreToolUse mutator-gate trigger entirely', () => {
    const { settings } = stripEnforcementHooks(FIXTURE_SETTINGS);
    const hooks = settings['hooks'] as Record<string, unknown[]>;
    const preToolUse = hooks['PreToolUse'] as Array<{ hooks: Array<{ command: string }> }>;
    expect(preToolUse.some((t) => t.hooks.some((h) => h.command.includes('mutator-gate.py')))).toBe(
      false,
    );
  });
  it('preserves the sibling prevent-memory-write.sh PreToolUse trigger', () => {
    const { settings } = stripEnforcementHooks(FIXTURE_SETTINGS);
    const hooks = settings['hooks'] as Record<string, unknown[]>;
    const preToolUse = hooks['PreToolUse'] as Array<{ hooks: Array<{ command: string }> }>;
    expect(
      preToolUse.some((t) => t.hooks.some((h) => h.command.includes('prevent-memory-write.sh'))),
    ).toBe(true);
  });
  it('removes only the receipt-observer-client.py hook from Stop, keeping reflect-stop-hook.sh', () => {
    const { settings } = stripEnforcementHooks(FIXTURE_SETTINGS);
    const hooks = settings['hooks'] as Record<string, unknown[]>;
    const stop = hooks['Stop'] as Array<{ hooks: Array<{ command: string }> }>;
    const commands = stop.flatMap((t) => t.hooks.map((h) => h.command));
    expect(commands.some((c) => c.includes('receipt-observer-client.py'))).toBe(false);
    expect(commands.some((c) => c.includes('reflect-stop-hook.sh'))).toBe(true);
  });
  it('leaves PreCompact/PostToolUse hooks byte-identical', () => {
    const { settings } = stripEnforcementHooks(FIXTURE_SETTINGS);
    const hooks = settings['hooks'] as Record<string, unknown>;
    expect(hooks['PreCompact']).toEqual(FIXTURE_SETTINGS.hooks.PreCompact);
    expect(hooks['PostToolUse']).toEqual(FIXTURE_SETTINGS.hooks.PostToolUse);
  });
  it('reports what it removed', () => {
    const { removed } = stripEnforcementHooks(FIXTURE_SETTINGS);
    expect(removed).toContain(`PreToolUse:${ENFORCEMENT_HOOK_MARKERS.preToolUse}`);
    expect(removed).toContain(`Stop:${ENFORCEMENT_HOOK_MARKERS.stop}`);
  });
 });
 describe('settingsHasEnforcementHooks', () => {
  it('is true for the unmodified fixture', () => {
    expect(settingsHasEnforcementHooks(FIXTURE_SETTINGS)).toBe(true);
  });
  it('is false after stripping', () => {
    const { settings } = stripEnforcementHooks(FIXTURE_SETTINGS);
    expect(settingsHasEnforcementHooks(settings)).toBe(false);
  });
  it('is false for settings with no hooks key at all', () => {
    expect(settingsHasEnforcementHooks({ model: 'opus' })).toBe(false);
  });
 });
 describe('guardClaudeSettingsWiring', () => {
  it('probe=false (default, no opt-out): strips enforcement hooks and reports non-zero with a loud, actionable message', () => {
    const outcome = guardClaudeSettingsWiring(fixtureJson(), {}, { activatable: () => false });
    expect(outcome.exitCode).toBe(1);
    expect(outcome.wired).toBe(false);
    expect(settingsHasEnforcementHooks(JSON.parse(outcome.json) as Record<string, unknown>)).toBe(
      false,
    );
    expect(outcome.logs).toHaveLength(1);
    expect(outcome.logs[0]?.level).toBe('error');
    expect(outcome.logs[0]?.message).toBe(FAIL_LOUD_MESSAGE);
    expect(outcome.logs[0]?.message).toMatch(/refusing to wire a dead gate/i);
    expect(outcome.logs[0]?.message).toMatch(/#869/);
    expect(outcome.logs[0]?.message).toMatch(/--allow-inactive-enforcement/);
  });
  it('probe=false + explicit opt-out flag: wires hooks as-is and emits a loud warning', () => {
    const outcome = guardClaudeSettingsWiring(
      fixtureJson(),
      { allowInactiveEnforcement: true },
      { activatable: () => false },
    );
    expect(outcome.exitCode).toBe(0);
    expect(outcome.wired).toBe(true);
    expect(settingsHasEnforcementHooks(JSON.parse(outcome.json) as Record<string, unknown>)).toBe(
      true,
    );
    expect(outcome.logs).toHaveLength(1);
    expect(outcome.logs[0]?.level).toBe('warn');
    expect(outcome.logs[0]?.message).toBe(loudOptOutMessage());
    expect(outcome.logs[0]?.message).toMatch(/WITHOUT confirmed activation/);
  });
  it('probe=true: wires hooks normally with no logs, regardless of opt-out', () => {
    const outcome = guardClaudeSettingsWiring(fixtureJson(), {}, { activatable: () => true });
    expect(outcome.exitCode).toBe(0);
    expect(outcome.wired).toBe(true);
    expect(outcome.logs).toHaveLength(0);
    expect(JSON.parse(outcome.json)).toEqual(FIXTURE_SETTINGS);
  });
  it('probe=true + opt-out flag set anyway: still wires normally, no spurious warning', () => {
    const outcome = guardClaudeSettingsWiring(
      fixtureJson(),
      { allowInactiveEnforcement: true },
      { activatable: () => true },
    );
    expect(outcome.exitCode).toBe(0);
    expect(outcome.wired).toBe(true);
    expect(outcome.logs).toHaveLength(0);
  });
  it('defaults to the real leaseEnforcementActivatable() when no activatable dep is injected', () => {
    // Deliberately does not assume a fixed true/false value for the real
    // probe (whether dist/cli.js happens to be built varies by environment —
    // asserting a hardcoded expectation here would make the test flaky, not
    // red-first). Instead it proves the wiring is genuinely delegated: the
    // no-deps call must agree with an explicit call to the same real
    // predicate, not some other hardcoded value.
    const reallyActivatable = leaseEnforcementActivatable();
    const outcome = guardClaudeSettingsWiring(fixtureJson());
    if (reallyActivatable) {
      expect(outcome.exitCode).toBe(0);
      expect(outcome.wired).toBe(true);
    } else {
      expect(outcome.exitCode).toBe(1);
      expect(outcome.wired).toBe(false);
    }
  });
 });
 describe('runInstallOrderingGuard (file-level, temp dirs only)', () => {
  let dir: string;
  afterEach(() => {
    if (dir) rmSync(dir, { recursive: true, force: true });
  });
  function makeSrc(): string {
    dir = mkdtempSync(join(tmpdir(), 'mosaic-install-ordering-guard-'));
    const src = join(dir, 'settings.json');
    writeFileSync(src, fixtureJson());
    return src;
  }
  it('probe=false: writes a dest settings.json with hooks stripped and returns exitCode 1', () => {
    const src = makeSrc();
    const dest = join(dir, 'claude-settings.json');
    const result = runInstallOrderingGuard(src, dest, {}, { activatable: () => false });
    expect(result.exitCode).toBe(1);
    expect(result.destWritten).toBe(true);
    expect(existsSync(dest)).toBe(true);
    const written = JSON.parse(readFileSync(dest, 'utf-8')) as Record<string, unknown>;
    expect(settingsHasEnforcementHooks(written)).toBe(false);
  });
  it('probe=false + opt-out: writes dest with hooks intact and returns exitCode 0', () => {
    const src = makeSrc();
    const dest = join(dir, 'claude-settings.json');
    const result = runInstallOrderingGuard(
      src,
      dest,
      { allowInactiveEnforcement: true },
      { activatable: () => false },
    );
    expect(result.exitCode).toBe(0);
    const written = JSON.parse(readFileSync(dest, 'utf-8')) as Record<string, unknown>;
    expect(settingsHasEnforcementHooks(written)).toBe(true);
  });
  it('probe=true: writes dest with hooks intact and returns exitCode 0', () => {
    const src = makeSrc();
    const dest = join(dir, 'claude-settings.json');
    const result = runInstallOrderingGuard(src, dest, {}, { activatable: () => true });
    expect(result.exitCode).toBe(0);
    const written = JSON.parse(readFileSync(dest, 'utf-8')) as Record<string, unknown>;
    expect(settingsHasEnforcementHooks(written)).toBe(true);
  });
  it('backs up a pre-existing divergent dest before overwriting (copy_file_managed parity)', () => {
    const src = makeSrc();
    const dest = join(dir, 'claude-settings.json');
    writeFileSync(dest, JSON.stringify({ preexisting: true }));
    const result = runInstallOrderingGuard(src, dest, {}, { activatable: () => true });
    expect(result.destWritten).toBe(true);
    expect(result.backupPath).toBeDefined();
    expect(existsSync(result.backupPath!)).toBe(true);
    expect(JSON.parse(readFileSync(result.backupPath!, 'utf-8'))).toEqual({ preexisting: true });
  });
  it('is a no-op write when dest already matches the guarded content (idempotent)', () => {
    const src = makeSrc();
    const dest = join(dir, 'claude-settings.json');
    const first = runInstallOrderingGuard(src, dest, {}, { activatable: () => true });
    expect(first.destWritten).toBe(true);
    const second = runInstallOrderingGuard(src, dest, {}, { activatable: () => true });
    expect(second.destWritten).toBe(false);
    expect(second.backupPath).toBeUndefined();
  });
  it('never touches the real home directory settings path used by this test file', () => {
    // Sanity guard for the suite itself: every dest path used above lives
    // under the mkdtemp() scratch dir, never under homedir()/.claude.
    expect(dir).toContain('mosaic-install-ordering-guard-');
  });
 });
--- a/packages/mosaic/src/commands/install-ordering-guard.ts
+++ b/packages/mosaic/src/commands/install-ordering-guard.ts
@@ -1,327 +0,0 @@
 /**
 * Install-ordering guard (issue #869, Point-1 card C2).
 *
 * Root cause this exists to guard against (#828 version skew, restated): the
 * framework reseed / install path (`framework/install.sh` →
 * `mosaic-link-runtime-assets` → copies `runtime/claude/settings.json` to
 * `~/.claude/settings.json`) wires the ENFORCEMENT half of the lease broker —
 * the `PreToolUse` `mutator-gate.py` hook and the `Stop`
 * `receipt-observer-client.py` hook — unconditionally. If the ACTIVATION half
 * (a CLI build advertising launch-runtime activation + a running broker
 * supervisor — see `lease-activation-probe.ts`, C1) is absent, the fail-closed
 * gate then denies every tool call with GATE_UNAVAILABLE: a bricked host.
 *
 * This module is the WIRING gate, not the enforcement gate: it decides
 * whether the enforcement hook entries are written into the settings.json
 * that ships to `~/.claude/`. It never touches `mutator-gate.py`'s own
 * fail-closed-on-absent-identity runtime behavior (test-locked in
 * `runtime_tools_unittest.py` / `fail-closed-regression.spec.ts`).
 *
 * Default (no opt-out): NOT activatable → strip the enforcement hook entries
 * from the written settings.json and report a non-zero outcome with a loud,
 * actionable message (see FAIL_LOUD_MESSAGE below).
 *
 * Opt-out: `--allow-inactive-enforcement` (an explicit, per-invocation CLI
 * flag — deliberately NOT an environment variable, so it can never sit as a
 * silently-inherited default in a shell profile). When set on a NOT
 * activatable host, the hooks ARE wired but a loud warning is emitted saying
 * so, and the outcome is reported ok (this is a conscious, informed choice).
 */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import type { Command } from 'commander';
 import { leaseEnforcementActivatable } from './lease-activation-probe.js';
 // ─── Enforcement hook identification ────────────────────────────────────────
 /** Substrings that identify the two enforcement hook commands #828 wired
 * unconditionally. Matches the marker strings documented in
 * `lease-activation-probe.ts`. */
 export const ENFORCEMENT_HOOK_MARKERS = {
  preToolUse: 'mutator-gate.py',
  stop: 'receipt-observer-client.py',
 } as const;
 interface HookEntry {
  command?: string;
  [key: string]: unknown;
 }
 interface HookTrigger {
  matcher?: string;
  hooks?: HookEntry[];
  [key: string]: unknown;
 }
 type HooksMap = Record<string, HookTrigger[]>;
 function cloneJson<T>(value: T): T {
  return JSON.parse(JSON.stringify(value)) as T;
 }
 function commandIncludes(hook: HookEntry, marker: string): boolean {
  return String(hook.command ?? '').includes(marker);
 }
 /**
 * Return a deep clone of `settings` with the enforcement hook entries removed:
 *  - Any `PreToolUse` trigger group containing a `mutator-gate.py` command is
 *    dropped in full (that trigger exists solely to run the gate).
 *  - Within `Stop` trigger groups, only the individual `receipt-observer-client.py`
 *    hook entry is dropped; sibling hooks in the same trigger (e.g.
 *    `reflect-stop-hook.sh`) are preserved.
 * Every other hook (PreCompact/SessionStart revoke-lease, the
 * `prevent-memory-write.sh` PreToolUse trigger, PostToolUse qa/typecheck
 * hooks) is left byte-identical — this function only ever removes the two
 * markers above.
 */
 export function stripEnforcementHooks(settings: Record<string, unknown>): {
  settings: Record<string, unknown>;
  removed: string[];
 } {
  const cloned = cloneJson(settings);
  const removed: string[] = [];
  const hooks = cloned['hooks'] as HooksMap | undefined;
  if (!hooks || typeof hooks !== 'object') {
    return { settings: cloned, removed };
  }
  const preToolUse = hooks['PreToolUse'];
  if (Array.isArray(preToolUse)) {
    const kept = preToolUse.filter((trigger) => {
      const hasGate = (trigger.hooks ?? []).some((h) =>
        commandIncludes(h, ENFORCEMENT_HOOK_MARKERS.preToolUse),
      );
      if (hasGate) removed.push('PreToolUse:mutator-gate.py');
      return !hasGate;
    });
    if (kept.length > 0) hooks['PreToolUse'] = kept;
    else delete hooks['PreToolUse'];
  }
  const stop = hooks['Stop'];
  if (Array.isArray(stop)) {
    const rebuilt: HookTrigger[] = [];
    for (const trigger of stop) {
      const innerHooks = trigger.hooks ?? [];
      const keptHooks = innerHooks.filter((h) => {
        const isReceiptObserver = commandIncludes(h, ENFORCEMENT_HOOK_MARKERS.stop);
        if (isReceiptObserver) removed.push('Stop:receipt-observer-client.py');
        return !isReceiptObserver;
      });
      if (keptHooks.length > 0) {
        rebuilt.push({ ...trigger, hooks: keptHooks });
      }
    }
    if (rebuilt.length > 0) hooks['Stop'] = rebuilt;
    else delete hooks['Stop'];
  }
  if (Object.keys(hooks).length === 0) {
    delete cloned['hooks'];
  } else {
    cloned['hooks'] = hooks;
  }
  return { settings: cloned, removed };
 }
 /** True iff `settings` currently wires either enforcement hook. */
 export function settingsHasEnforcementHooks(settings: Record<string, unknown>): boolean {
  const hooks = settings['hooks'] as HooksMap | undefined;
  if (!hooks || typeof hooks !== 'object') return false;
  const preToolUse = hooks['PreToolUse'] ?? [];
  const preHit = preToolUse.some((trigger) =>
    (trigger.hooks ?? []).some((h) => commandIncludes(h, ENFORCEMENT_HOOK_MARKERS.preToolUse)),
  );
  if (preHit) return true;
  const stop = hooks['Stop'] ?? [];
  return stop.some((trigger) =>
    (trigger.hooks ?? []).some((h) => commandIncludes(h, ENFORCEMENT_HOOK_MARKERS.stop)),
  );
 }
 // ─── Guard predicate ────────────────────────────────────────────────────────
 export const FAIL_LOUD_MESSAGE =
  '[mosaic] ERROR: enforcement requested but activation half absent — needs a published CLI ' +
  'carrying launch-runtime activation + a broker supervisor; refusing to wire a dead gate (see #869). ' +
  'The PreToolUse mutator-gate.py hook and Stop receipt-observer-client.py hook were NOT written to ' +
  'settings.json. Fix by installing/updating the CLI and broker, then re-run the framework reseed. ' +
  'To wire anyway (NOT recommended — the fail-closed gate will deny every tool call with ' +
  'GATE_UNAVAILABLE until activation is restored), re-run with --allow-inactive-enforcement.';
 export function loudOptOutMessage(): string {
  return (
    '[mosaic] WARNING: wiring lease-enforcement hooks (mutator-gate.py / receipt-observer-client.py) ' +
    'WITHOUT confirmed activation — --allow-inactive-enforcement was set explicitly. The fail-closed ' +
    'gate will deny every tool call (GATE_UNAVAILABLE) until the activation half (launch-runtime ' +
    'activation capability + a running broker supervisor) is present on this host (see #869).'
  );
 }
 export type GuardLogLevel = 'error' | 'warn';
 export interface GuardLogLine {
  level: GuardLogLevel;
  message: string;
 }
 export interface InstallOrderingGuardOptions {
  /** Explicit, per-invocation opt-out. Never source this from an environment
   * variable — see module doc. */
  allowInactiveEnforcement?: boolean;
 }
 export interface InstallOrderingGuardDeps {
  /** Defaults to {@link leaseEnforcementActivatable}. Injectable for tests. */
  activatable?: () => boolean;
 }
 export interface InstallOrderingGuardOutcome {
  /** The settings.json content to write (pretty-printed, trailing newline). */
  json: string;
  /** Whether the enforcement hooks are present in `json`. */
  wired: boolean;
  /** 0 = proceed normally; 1 = enforcement was refused (fail-loud default path). */
  exitCode: 0 | 1;
  logs: GuardLogLine[];
 }
 /**
 * The install-ordering guard: decide whether the enforcement hooks embedded
 * in the Claude settings.json template may be wired into the settings.json
 * actually shipped to `~/.claude/`.
 *
 *   - activatable            → wire as-is. exitCode 0, no logs.
 *   - NOT activatable, no opt-out → strip enforcement hooks. exitCode 1,
 *     one 'error' log with the actionable FAIL_LOUD_MESSAGE.
 *   - NOT activatable, opt-out set → wire as-is anyway. exitCode 0, one
 *     'warn' log making the risk explicit and loud.
 *
 * Pure function: takes the raw settings.json text, returns the text to write
 * plus metadata. No filesystem access — callers (the hidden CLI subcommand
 * below, or a test) own reading/writing so this stays trivially testable with
 * fakes/temp files and never risks touching a real `~/.claude/settings.json`.
 */
 export function guardClaudeSettingsWiring(
  rawSettingsJson: string,
  options: InstallOrderingGuardOptions = {},
  deps: InstallOrderingGuardDeps = {},
 ): InstallOrderingGuardOutcome {
  const parsed = JSON.parse(rawSettingsJson) as Record<string, unknown>;
  const activatable = deps.activatable ?? leaseEnforcementActivatable;
  const isActivatable = activatable();
  const serialize = (settings: Record<string, unknown>): string =>
    JSON.stringify(settings, null, 2) + '\n';
  if (isActivatable) {
    return {
      json: serialize(parsed),
      wired: settingsHasEnforcementHooks(parsed),
      exitCode: 0,
      logs: [],
    };
  }
  if (options.allowInactiveEnforcement === true) {
    return {
      json: serialize(parsed),
      wired: settingsHasEnforcementHooks(parsed),
      exitCode: 0,
      logs: [{ level: 'warn', message: loudOptOutMessage() }],
    };
  }
  const { settings: stripped } = stripEnforcementHooks(parsed);
  return {
    json: serialize(stripped),
    wired: settingsHasEnforcementHooks(stripped),
    exitCode: 1,
    logs: [{ level: 'error', message: FAIL_LOUD_MESSAGE }],
  };
 }
 // ─── File-level runner (shared by the CLI action + tests) ──────────────────
 export interface RunInstallOrderingGuardResult extends InstallOrderingGuardOutcome {
  destWritten: boolean;
  backupPath?: string;
 }
 /**
 * Read `src`, guard it, and write the result to `dest` — mirroring
 * `copy_file_managed`'s backup-on-change semantics from
 * `mosaic-link-runtime-assets` (skip the write if content is unchanged;
 * back up an existing divergent file once, timestamped). Exported standalone
 * (not only reachable via the CLI action closure) so tests can exercise real
 * file I/O against temp directories without ever touching `~/.claude/`.
 */
 export function runInstallOrderingGuard(
  src: string,
  dest: string,
  options: InstallOrderingGuardOptions = {},
  deps: InstallOrderingGuardDeps = {},
 ): RunInstallOrderingGuardResult {
  const raw = readFileSync(src, 'utf-8');
  const outcome = guardClaudeSettingsWiring(raw, options, deps);
  mkdirSync(dirname(dest), { recursive: true });
  const existing = existsSync(dest) ? readFileSync(dest, 'utf-8') : null;
  let destWritten = false;
  let backupPath: string | undefined;
  if (existing !== outcome.json) {
    if (existing !== null) {
      const stamp = new Date()
        .toISOString()
        .replace(/[-:]/g, '')
        .replace(/\..+$/, '')
        .replace('T', '');
      backupPath = `${dest}.mosaic-bak-${stamp}`;
      writeFileSync(backupPath, existing);
    }
    writeFileSync(dest, outcome.json);
    destWritten = true;
  }
  return { ...outcome, destWritten, backupPath };
 }
 // ─── Hidden CLI bridge (bash → TS) ──────────────────────────────────────────
 /** Hidden CLI subcommand name. `mosaic-link-runtime-assets` (bash) invokes
 * this instead of its generic `copy_file_managed` for the settings.json
 * runtime file specifically, so the guard's decision is made by importing
 * `leaseEnforcementActivatable()` directly rather than re-implementing the
 * capability/supervisor probes in shell. Deliberately undocumented (hidden
 * from `--help`) — internal wiring, not a user-facing command. */
 export const INSTALL_ORDERING_GUARD_COMMAND = '__link-claude-settings';
 export function registerInstallOrderingGuardCommand(program: Command): void {
  program
    .command(`${INSTALL_ORDERING_GUARD_COMMAND} <src> <dest>`, { hidden: true })
    .description(
      'Internal: copy the Claude settings.json template, gating enforcement-hook ' +
        'wiring on lease-activation capability (#869 Point-1 C2)',
    )
    .option(
      '--allow-inactive-enforcement',
      'Wire enforcement hooks even when activation cannot be confirmed on this host ' +
        '(explicit, loud, non-default opt-out — see #869)',
    )
    .action((src: string, dest: string, opts: { allowInactiveEnforcement?: boolean }) => {
      const result = runInstallOrderingGuard(src, dest, {
        allowInactiveEnforcement: opts.allowInactiveEnforcement === true,
      });
      for (const line of result.logs) {
        (line.level === 'error' ? console.error : console.warn)(line.message);
      }
      process.exit(result.exitCode);
    });
 }
--- a/packages/mosaic/src/commands/launch.ts
+++ b/packages/mosaic/src/commands/launch.ts
@@ -28,7 +28,6 @@ import { readRegularFileSecure } from '../fleet/secure-file.js';
 import { readPersonaContractBlock } from '../fleet/persona-contract.js';
 import { canonicalizeRoleClass } from './fleet-personas.js';
 import { launchClaudex, type ClaudexHarnessAdapter } from './claudex.js';
 import { runLeaseEnforcementDoctorCheck } from './lease-doctor-check.js';
 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 const MAX_INSTALLED_TOOLS_BYTES = 256 * 1024;
@@ -1238,6 +1237,7 @@ export function registerLaunchCommands(program: Command): void {
  // Direct framework script delegates
  const directCommands: Record<string, { desc: string; script: string }> = {
    init: { desc: 'Generate SOUL.md (agent identity contract)', script: 'mosaic-init' },
    doctor: { desc: 'Health audit — detect drift and missing files', script: 'mosaic-doctor' },
    sync: { desc: 'Sync skills from canonical source', script: 'mosaic-sync-skills' },
    bootstrap: {
      desc: 'Bootstrap a repo with Mosaic standards',
@@ -1256,67 +1256,4 @@ export function registerLaunchCommands(program: Command): void {
        delegateToScript(fwScript(script), cmd.args);
      });
  }
  // `doctor` — the framework drift audit (bash script) PLUS the #869
  // Point-1 C5 lease-enforcement activation check (TS, reusing C1's
  // `leaseEnforcementActivatable()` and C3's `checkBrokerSupervisorHealth()`).
  // Kept out of the generic `directCommands` loop above because this check
  // must run and report BEFORE the bash script's own exit, and must be able
  // to force a non-zero exit on its own — a silent pass on "enforcement
  // hooks wired but activation absent" would leave a bricked host
  // undiagnosed (see lease-doctor-check.ts docstring).
  program
    .command('doctor')
    .description('Health audit — detect drift, missing files, and #869 lease-activation gaps')
    .allowUnknownOption(true)
    .allowExcessArguments(true)
    .action(async (_opts: unknown, cmd: Command) => {
      checkMosaicHome();
      const leaseCheck = await runLeaseEnforcementDoctorCheck();
      const leaseCheckFailed = printLeaseDoctorCheck(leaseCheck);
      runDoctorScriptAndExit(fwScript('mosaic-doctor'), cmd.args, leaseCheckFailed);
    });
 }
 /**
 * Print the #869 C5 lease-enforcement doctor result using the same
 * `[mosaic-doctor]` prefix the bash audit script uses, but with a distinct
 * `[ERROR]` severity token (louder than the script's own `[WARN]`) — this is
 * a hard, actionable brick warning, not a soft drift warning, and must never
 * read as just one more line among the script's routine warnings. Silent on
 * an `ok` result, matching this file's other pre-flight checks
 * (`checkMosaicHome`, `checkFile`, `checkRuntime`) which only print on
 * failure. Returns whether the check failed, so the caller can force a
 * non-zero exit regardless of the bash script's own exit code.
 */
 function printLeaseDoctorCheck(
  result: Awaited<ReturnType<typeof runLeaseEnforcementDoctorCheck>>,
 ): boolean {
  if (result.status === 'error') {
    console.error(`[mosaic-doctor] [ERROR] ${result.message}`);
    return true;
  }
  return false;
 }
 /**
 * Run the bash `mosaic-doctor` audit script (inheriting stdio, same as
 * {@link delegateToScript}) and exit with a non-zero code if EITHER the
 * script itself reported failure OR the lease-enforcement check above did —
 * so `--fail-on-warn` and other script-level exit semantics are preserved,
 * but the lease-enforcement ERROR can never be masked by an otherwise-green
 * script run.
 */
 function runDoctorScriptAndExit(scriptPath: string, args: string[], forceFailure: boolean): never {
  if (!existsSync(scriptPath)) {
    console.error(`[mosaic] Script not found: ${scriptPath}`);
    process.exit(1);
  }
  let scriptExitCode = 0;
  try {
    execFileSync('bash', [scriptPath, ...args], { stdio: 'inherit', env: process.env });
  } catch (err) {
    scriptExitCode = (err as { status?: number }).status ?? 1;
  }
  process.exit(forceFailure ? 1 : scriptExitCode);
 }
--- a/packages/mosaic/src/commands/lease-doctor-check.spec.ts
+++ b/packages/mosaic/src/commands/lease-doctor-check.spec.ts
@@ -1,196 +0,0 @@
 import { describe, expect, it } from 'vitest';
 import {
  detectEnforcementHooksWired,
  runLeaseEnforcementDoctorCheck,
 } from './lease-doctor-check.js';
 /**
 * Red-first tests for issue #869 Point-1 C5 — the `mosaic doctor`
 * lease-enforcement surfacing check.
 *
 * Root cause under test: enforcement hooks (`mutator-gate.py`,
 * `receipt-observer-client.py`) can be wired into `~/.claude/settings.json`
 * on a host where C1's `leaseEnforcementActivatable()` is false and/or C3's
 * `checkBrokerSupervisorHealth()` reports unhealthy. That combination fails
 * closed correctly, but must be surfaced LOUDLY by `mosaic doctor` rather
 * than silently passing — this test suite exercises the three primary
 * branches (wired+not-activatable, wired+healthy, not-wired) plus the
 * broker-unhealthy variant.
 *
 * Every dependency is injected — no real `~/.claude/settings.json` and no
 * real broker are ever touched.
 */
 const WIRED_SETTINGS_JSON = JSON.stringify({
  hooks: {
    PreToolUse: [
      {
        matcher: '.*',
        hooks: [
          {
            type: 'command',
            command: 'python3 ~/.config/mosaic/tools/lease-broker/mutator-gate.py --runtime claude',
          },
        ],
      },
    ],
    Stop: [
      {
        hooks: [
          {
            type: 'command',
            command:
              'python3 ~/.config/mosaic/tools/lease-broker/receipt-observer-client.py --runtime claude --latest-entry',
          },
        ],
      },
    ],
  },
 });
 const UNWIRED_SETTINGS_JSON = JSON.stringify({
  hooks: {
    PostToolUse: [
      {
        matcher: 'Edit|MultiEdit|Write',
        hooks: [{ type: 'command', command: '~/.config/mosaic/tools/qa/qa-hook-stdin.sh' }],
      },
    ],
  },
 });
 describe('detectEnforcementHooksWired', () => {
  it('detects the mutator-gate + receipt-observer markers when wired', () => {
    const result = detectEnforcementHooksWired(JSON.parse(WIRED_SETTINGS_JSON));
    expect(result.wired).toBe(true);
    expect(result.matchedMarkers).toEqual(
      expect.arrayContaining(['mutator-gate.py', 'receipt-observer-client.py']),
    );
  });
  it('reports not wired when no enforcement markers are present', () => {
    const result = detectEnforcementHooksWired(JSON.parse(UNWIRED_SETTINGS_JSON));
    expect(result.wired).toBe(false);
    expect(result.matchedMarkers).toEqual([]);
  });
  it('reports not wired for an empty settings object', () => {
    expect(detectEnforcementHooksWired({}).wired).toBe(false);
  });
  it('detects wiring from just ONE marker (partial wiring is still dangerous)', () => {
    const onlyMutatorGate = JSON.stringify({
      hooks: {
        PreToolUse: [
          {
            hooks: [{ type: 'command', command: 'python3 .../mutator-gate.py --runtime claude' }],
          },
        ],
      },
    });
    const result = detectEnforcementHooksWired(JSON.parse(onlyMutatorGate));
    expect(result.wired).toBe(true);
    expect(result.matchedMarkers).toEqual(['mutator-gate.py']);
  });
 });
 describe('runLeaseEnforcementDoctorCheck', () => {
  it('RED: wired + not-activatable ⇒ LOUD error (not a silent pass)', async () => {
    const result = await runLeaseEnforcementDoctorCheck({
      readSettingsRaw: () => WIRED_SETTINGS_JSON,
      isActivatable: () => false,
      isBrokerHealthy: async () => true,
    });
    expect(result.status).toBe('error');
    expect(result.wired).toBe(true);
    expect(result.activatable).toBe(false);
    expect(result.message).toMatch(/activation absent/);
    expect(result.message).toMatch(/#869/);
    expect(result.message.toLowerCase()).toMatch(/brick/);
  });
  it('wired + activatable + broker-unhealthy ⇒ LOUD error', async () => {
    const result = await runLeaseEnforcementDoctorCheck({
      readSettingsRaw: () => WIRED_SETTINGS_JSON,
      isActivatable: () => true,
      isBrokerHealthy: async () => false,
    });
    expect(result.status).toBe('error');
    expect(result.wired).toBe(true);
    expect(result.brokerHealthy).toBe(false);
    expect(result.message).toMatch(/broker not healthy/);
  });
  it('wired + not-activatable + broker-unhealthy ⇒ LOUD error citing both reasons', async () => {
    const result = await runLeaseEnforcementDoctorCheck({
      readSettingsRaw: () => WIRED_SETTINGS_JSON,
      isActivatable: () => false,
      isBrokerHealthy: async () => false,
    });
    expect(result.status).toBe('error');
    expect(result.message).toMatch(/activation absent/);
    expect(result.message).toMatch(/broker not healthy/);
  });
  it('GREEN: wired + activatable + broker-healthy ⇒ ok', async () => {
    const result = await runLeaseEnforcementDoctorCheck({
      readSettingsRaw: () => WIRED_SETTINGS_JSON,
      isActivatable: () => true,
      isBrokerHealthy: async () => true,
    });
    expect(result.status).toBe('ok');
    expect(result.wired).toBe(true);
    expect(result.activatable).toBe(true);
    expect(result.brokerHealthy).toBe(true);
  });
  it('GREEN: not-wired ⇒ ok, no false alarm (activation/broker never probed)', async () => {
    let activatableCalled = false;
    let brokerCalled = false;
    const result = await runLeaseEnforcementDoctorCheck({
      readSettingsRaw: () => UNWIRED_SETTINGS_JSON,
      isActivatable: () => {
        activatableCalled = true;
        return false;
      },
      isBrokerHealthy: async () => {
        brokerCalled = true;
        return false;
      },
    });
    expect(result.status).toBe('ok');
    expect(result.wired).toBe(false);
    expect(result.activatable).toBeNull();
    expect(result.brokerHealthy).toBeNull();
    // Not wired must short-circuit — never even consult activation/broker.
    expect(activatableCalled).toBe(false);
    expect(brokerCalled).toBe(false);
  });
  it('GREEN: settings.json absent ⇒ ok (never touches a real file — readSettingsRaw is injected)', async () => {
    const result = await runLeaseEnforcementDoctorCheck({
      readSettingsRaw: () => null,
      isActivatable: () => false,
      isBrokerHealthy: async () => false,
    });
    expect(result.status).toBe('ok');
    expect(result.wired).toBe(false);
  });
  it('GREEN: malformed settings.json ⇒ ok (parse errors are not this card’s failure class)', async () => {
    const result = await runLeaseEnforcementDoctorCheck({
      readSettingsRaw: () => '{ not valid json',
      isActivatable: () => false,
      isBrokerHealthy: async () => false,
    });
    expect(result.status).toBe('ok');
  });
 });
--- a/packages/mosaic/src/commands/lease-doctor-check.ts
+++ b/packages/mosaic/src/commands/lease-doctor-check.ts
@@ -1,210 +0,0 @@
 /**
 * Lease-enforcement doctor check (issue #869, Point-1 card C5).
 *
 * Root cause this guards against (#828 version skew, the same one C1/C3
 * exist for): the Claude Code enforcement hooks (`mutator-gate.py` gating
 * PreToolUse, `receipt-observer-client.py` observing Stop) can be WIRED into
 * `~/.claude/settings.json` on a host where the ACTIVATION half is absent —
 * no compatible CLI build (C1's `leaseEnforcementActivatable()`), or no
 * healthy broker supervisor (C3's `checkBrokerSupervisorHealth()`). That
 * combination is a silent brick: every gated tool call denies with
 * GATE_UNAVAILABLE, and the fail-closed behavior is *correct* — but nothing
 * surfaces it to an operator running `mosaic doctor` on an already-bricked
 * host.
 *
 * This module answers one question — "if I ran right now, would I be
 * bricked?" — by combining:
 *
 *   1. wiring detection: does `~/.claude/settings.json` reference either
 *      enforcement-hook marker (`mutator-gate.py` / `receipt-observer-client.py`)?
 *   2. C1's `leaseEnforcementActivatable()` — could activation satisfy
 *      enforcement if it were exercised right now?
 *   3. C3's `checkBrokerSupervisorHealth()` — is the broker supervisor
 *      actually healthy?
 *
 * Not wired ⇒ ok (nothing to activate, no false alarm). Wired AND activatable
 * AND broker-healthy ⇒ ok. Wired AND (NOT activatable OR broker unhealthy) ⇒
 * a LOUD, actionable error — this module never silently passes that state.
 *
 * Every dependency (settings read, activation probe, broker-health check) is
 * injectable so tests can drive every branch without ever touching a real
 * `~/.claude/settings.json` or a real broker.
 */
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { leaseEnforcementActivatable, type ActivationProbeDeps } from './lease-activation-probe.js';
 import {
  checkBrokerSupervisorHealth,
  resolveBrokerSupervisorPaths,
 } from '../lease-broker/broker-supervisor.js';
 import { DEFAULT_MOSAIC_HOME } from '../constants.js';
 /** Markers identifying the two enforcement-hook halves wired via the
 * framework reseed. Either marker's presence in `settings.json` means
 * enforcement is wired — a host can be bricked with just one half present. */
 const ENFORCEMENT_HOOK_MARKERS = ['mutator-gate.py', 'receipt-observer-client.py'] as const;
 export interface EnforcementHooksWiredResult {
  readonly wired: boolean;
  readonly matchedMarkers: readonly string[];
 }
 /**
 * Detect whether the Claude Code enforcement hooks (mutator-gate /
 * receipt-observer) are wired into an already-parsed `settings.json`.
 * Pure/testable — takes parsed JSON, never touches the filesystem itself.
 */
 export function detectEnforcementHooksWired(settings: unknown): EnforcementHooksWiredResult {
  const serialized = JSON.stringify(settings ?? {});
  const matchedMarkers = ENFORCEMENT_HOOK_MARKERS.filter((marker) => serialized.includes(marker));
  return { wired: matchedMarkers.length > 0, matchedMarkers };
 }
 export interface LeaseDoctorCheckDeps {
  /**
   * Read raw `settings.json` text; return `null` if the file is absent.
   * Defaults to reading the real `~/.claude/settings.json`. ALWAYS inject a
   * fake in tests — never point this at a real host's settings file.
   */
  readSettingsRaw?: () => string | null;
  /** Defaults to {@link leaseEnforcementActivatable} (C1). Inject for tests. */
  isActivatable?: (deps?: ActivationProbeDeps) => boolean;
  /**
   * Defaults to a real broker-supervisor health check (C3) rooted at
   * `mosaicHome`. Inject for tests — never point this at a real broker.
   */
  isBrokerHealthy?: () => Promise<boolean>;
  /** Mosaic home used to resolve default broker-supervisor paths. Defaults to
   * `$MOSAIC_HOME` or `~/.config/mosaic`. */
  mosaicHome?: string;
 }
 export type LeaseDoctorCheckStatus = 'ok' | 'error';
 export interface LeaseDoctorCheckResult {
  readonly status: LeaseDoctorCheckStatus;
  readonly wired: boolean;
  /** `null` when hooks are not wired (activation/broker were never probed). */
  readonly activatable: boolean | null;
  /** `null` when hooks are not wired (activation/broker were never probed). */
  readonly brokerHealthy: boolean | null;
  readonly message: string;
 }
 function defaultReadSettingsRaw(): string | null {
  const settingsPath = join(homedir(), '.claude', 'settings.json');
  try {
    return readFileSync(settingsPath, 'utf8');
  } catch (error) {
    if (isEnoent(error)) return null;
    throw error;
  }
 }
 function isEnoent(error: unknown): boolean {
  return (
    typeof error === 'object' &&
    error !== null &&
    'code' in error &&
    (error as NodeJS.ErrnoException).code === 'ENOENT'
  );
 }
 function defaultMosaicHome(): string {
  return process.env['MOSAIC_HOME'] ?? DEFAULT_MOSAIC_HOME;
 }
 async function defaultIsBrokerHealthy(mosaicHome: string): Promise<boolean> {
  // `frameworkRoot` only feeds SOURCE paths (unit/wrapper/daemon file
  // locations for `applyBrokerSupervisor`); the health check only reads
  // TARGET paths (`unitTargetPath`, `socketPath`), both derived from
  // `mosaicHome`/`homeDir`/`env` alone. Passing `mosaicHome` again here is
  // therefore safe and never resolves or touches a framework checkout.
  const paths = resolveBrokerSupervisorPaths({ mosaicHome, frameworkRoot: mosaicHome });
  return (await checkBrokerSupervisorHealth(paths)).healthy;
 }
 /**
 * Surface the #869 fail-closed brick scenario as a LOUD `mosaic doctor`
 * error. See module docstring for the full decision table.
 */
 export async function runLeaseEnforcementDoctorCheck(
  deps: LeaseDoctorCheckDeps = {},
 ): Promise<LeaseDoctorCheckResult> {
  const readSettingsRaw = deps.readSettingsRaw ?? defaultReadSettingsRaw;
  const mosaicHome = deps.mosaicHome ?? defaultMosaicHome();
  const isActivatable = deps.isActivatable ?? leaseEnforcementActivatable;
  const isBrokerHealthy = deps.isBrokerHealthy ?? (() => defaultIsBrokerHealthy(mosaicHome));
  const raw = readSettingsRaw();
  if (raw === null) {
    return {
      status: 'ok',
      wired: false,
      activatable: null,
      brokerHealthy: null,
      message: 'Claude Code settings.json not found — lease-enforcement hooks not wired.',
    };
  }
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    // Malformed settings.json is a different failure class than this card
    // owns (C2 guards install-time writes); report ok rather than
    // misattributing a parse error to the #869 activation gap.
    return {
      status: 'ok',
      wired: false,
      activatable: null,
      brokerHealthy: null,
      message:
        'Claude Code settings.json could not be parsed — skipping lease-enforcement wiring check.',
    };
  }
  const { wired, matchedMarkers } = detectEnforcementHooksWired(parsed);
  if (!wired) {
    return {
      status: 'ok',
      wired: false,
      activatable: null,
      brokerHealthy: null,
      message:
        'Lease-enforcement hooks not wired in ~/.claude/settings.json — nothing to activate.',
    };
  }
  const activatable = isActivatable();
  const brokerHealthy = await isBrokerHealthy();
  if (activatable && brokerHealthy) {
    return {
      status: 'ok',
      wired: true,
      activatable,
      brokerHealthy,
      message: `Lease-enforcement hooks wired (${matchedMarkers.join(', ')}) — activation capability present and broker healthy.`,
    };
  }
  const reasons: string[] = [];
  if (!activatable) reasons.push('activation absent (leaseEnforcementActivatable() is false)');
  if (!brokerHealthy) {
    reasons.push('broker not healthy (checkBrokerSupervisorHealth() reports unhealthy)');
  }
  return {
    status: 'error',
    wired: true,
    activatable,
    brokerHealthy,
    message:
      `Lease-enforcement hooks (${matchedMarkers.join(', ')}) are wired in ~/.claude/settings.json, but ${reasons.join(' and ')}. ` +
      'Every gated tool call will fail closed and BRICK this agent (see #869). ' +
      'Remediate by activating the lease-broker supervisor (systemd unit + socket) or by removing the enforcement hooks from ~/.claude/settings.json.',
  };
 }
--- a/packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts
+++ b/packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts
@@ -47,22 +47,6 @@ const piLifecyclePath = join(frameworkRoot, 'runtime/pi/lease-lifecycle.ts');
 const prdyInitPath = join(frameworkRoot, 'tools/prdy/prdy-init.sh');
 const prdyUpdatePath = join(frameworkRoot, 'tools/prdy/prdy-update.sh');
 const remediationHandlerPath = join(frameworkRoot, 'tools/qa/remediation-hook-handler.sh');
 // C4 (#869 Point-1): launch-runtime.py now asserts, before anything else,
 // that the CLI's advertised lease-activation capability (normally read via
 // the hidden `mosaic __lease-capability` subcommand) matches what
 // enforcement expects — see framework/tools/lease-broker/
 // activation_version_gate.py. This suite drives launch-runtime.py directly
 // as a subprocess (never through the real `mosaic` CLI), so — exactly like
 // the fake broker (daemon.py) and fake `claude` binaries already used
 // below — it must supply a fake activation-capability probe rather than
 // depend on a real `mosaic` binary being on PATH. `MOSAIC_LEASE_VERSION_PROBE_COMMAND`
 // is launch-runtime.py's injection point for that fake; this literal
 // {name, version} pair must be kept in sync with
 // `EXPECTED_ACTIVATION_CAPABILITY` (activation_version_gate.py) and
 // `LEASE_ACTIVATION_CAPABILITY` (lease-activation-probe.ts) — all three
 // currently agree on v1.
 const leaseCapabilityProbeStub = `python3 -c "import json; print(json.dumps({'name': 'lease-runtime-activation', 'version': 1}))"`;
 const children: ChildProcess[] = [];
 const temporaryRoots: string[] = [];
@@ -200,7 +184,6 @@ raise SystemExit(0 if len(session_id) == 64 and denied else 1)
      MOSAIC_PRDY_RUNTIME: 'claude',
      MOSAIC_LEASE_BROKER_SOCKET: socket,
      MOSAIC_RUNTIME_GENERATION: '1',
      MOSAIC_LEASE_VERSION_PROBE_COMMAND: leaseCapabilityProbeStub,
    },
  });
 }
@@ -760,7 +743,6 @@ describe('whole mutator-class lease gate', () => {
          ...process.env,
          MOSAIC_LEASE_BROKER_SOCKET: socket,
          MOSAIC_RUNTIME_GENERATION: '1',
          MOSAIC_LEASE_VERSION_PROBE_COMMAND: leaseCapabilityProbeStub,
        },
      },
    );
@@ -779,7 +761,6 @@ describe('whole mutator-class lease gate', () => {
          ...process.env,
          MOSAIC_LEASE_BROKER_SOCKET: join(tmpdir(), 'missing-mosaic-broker.sock'),
          MOSAIC_RUNTIME_GENERATION: '1',
          MOSAIC_LEASE_VERSION_PROBE_COMMAND: leaseCapabilityProbeStub,
        },
      },
    );
@@ -897,7 +878,6 @@ raise SystemExit(0 if len(session_id) == 64 and hook_present and observers_prese
          PATH: `${binDir}:${process.env.PATH ?? ''}`,
          MOSAIC_LEASE_BROKER_SOCKET: socket,
          MOSAIC_RUNTIME_GENERATION: '1',
          MOSAIC_LEASE_VERSION_PROBE_COMMAND: leaseCapabilityProbeStub,
        },
        proxyGate: () =>
          Promise.resolve({
--- a/packages/mosaic/src/mutator-gate/runtime_tools_unittest.py
+++ b/packages/mosaic/src/mutator-gate/runtime_tools_unittest.py
@@ -39,18 +39,6 @@ LAUNCHER = load_tool("lease_runtime_launcher", "launch-runtime.py")
 GATE = load_tool("lease_mutator_gate", "mutator-gate.py")
 def matching_activation_probe(*_args: object, **_kwargs: object) -> dict[str, object]:
    """Fake activation-capability probe matching what enforcement expects
    (C4, #869 Point-1). Injected into `LAUNCHER.main()` calls below that are
    exercising OTHER branches (registration, exec, generation init, ...) so
    the new version-coupling gate — which runs before those — never blocks
    on host state (no real `mosaic` CLI on PATH in a test sandbox). The
    version-coupling gate's OWN behavior (match/mismatch/absent) is covered
    by its dedicated red-first tests in `version_coupling_unittest.py`."""
    return dict(LAUNCHER.EXPECTED_ACTIVATION_CAPABILITY)
 class FakeSocket:
    def __init__(self, *chunks: bytes):
        self.chunks = list(chunks)
@@ -107,7 +95,6 @@ class LaunchRuntimeTest(unittest.TestCase):
            request=request,
            execute=execute,
            initialize_generation=initialize_generation,
            probe_activation_capability=matching_activation_probe,
        )
        self.assertEqual(result, 0)
@@ -140,7 +127,6 @@ class LaunchRuntimeTest(unittest.TestCase):
            request=lambda *_args: {"ok": True, "session_id": "e" * 64},
            execute=lambda *args: executed.append(args),
            initialize_generation=lambda *_args: None,
            probe_activation_capability=matching_activation_probe,
        )
        self.assertEqual(result, 0)
        self.assertEqual(
@@ -167,7 +153,6 @@ class LaunchRuntimeTest(unittest.TestCase):
            request=lambda *_args: {"ok": True, "session_id": "f" * 64},
            execute=lambda *args: executed.append(args),
            initialize_generation=lambda *_args: None,
            probe_activation_capability=matching_activation_probe,
        )
        self.assertEqual(result, 0)
        self.assertEqual(executed[0][0:2], ("pi", ["pi", "--print", "hello"]))
@@ -203,7 +188,6 @@ class LaunchRuntimeTest(unittest.TestCase):
                    environ=environment,
                    request=lambda *_args, value=reply: value,
                    execute=lambda *args: executed.append(args),
                    probe_activation_capability=matching_activation_probe,
                )
                self.assertEqual(result, 1)
                self.assertEqual(executed, [])
@@ -219,7 +203,6 @@ class LaunchRuntimeTest(unittest.TestCase):
                    initialize_generation=lambda *_args: (_ for _ in ()).throw(
                        OSError("unsafe state")
                    ),
                    probe_activation_capability=matching_activation_probe,
                ),
                1,
            )
@@ -237,7 +220,6 @@ class LaunchRuntimeTest(unittest.TestCase):
                        environ={"MOSAIC_LEASE_BROKER_SOCKET": "/x"},
                        request=request,
                        execute=lambda *_args: self.fail("must not execute"),
                        probe_activation_capability=matching_activation_probe,
                    ),
                    1,
                )
@@ -251,7 +233,6 @@ class LaunchRuntimeTest(unittest.TestCase):
                    request=lambda *_args: {"ok": True, "session_id": "c" * 64},
                    execute=lambda *_args: (_ for _ in ()).throw(OSError("missing")),
                    initialize_generation=lambda *_args: None,
                    probe_activation_capability=matching_activation_probe,
                ),
                1,
            )
--- a/packages/mosaic/src/mutator-gate/version_coupling_unittest.py
+++ b/packages/mosaic/src/mutator-gate/version_coupling_unittest.py
@@ -1,287 +0,0 @@
 #!/usr/bin/env python3
 """Red-first tests for issue #869 Point-1 C4 — the enforcement/activation
 version-coupling assertion at the `launch-runtime.py` seam.
 Root cause under test (#828 restated): the lease broker's ENFORCEMENT half
 (this toolkit) and its ACTIVATION half (`execLeaseGatedRuntime()` in
 `launch.ts`, chained through `launch-runtime.py`) shipped on different
 channels and drifted. C1 (`lease-activation-probe.ts`) gave the activation
 half a versioned, machine-checkable identity
 (`LEASE_ACTIVATION_CAPABILITY`, printed via the hidden CLI subcommand
 `mosaic __lease-capability`). C4 (this module + `activation_version_gate.py`)
 is the assertion that actually USES that identity: enforcement must refuse
 to proceed — loudly, with an actionable remediation message, never a
 silent pass — unless the activation capability it observes exactly matches
 what enforcement expects.
 Every case here drives the seam with injected fakes/stubs (a fake
 `probe_activation_capability` callable at the `launch-runtime.py` level, or
 a fake `run` transport at the `activation_version_gate` level) — never a
 real broker, a real installed CLI, or a real `mosaic` binary on PATH.
 """
 from __future__ import annotations
 import importlib.util
 import io
 import subprocess
 import sys
 import unittest
 from contextlib import redirect_stderr
 from pathlib import Path
 TOOLS_DIR = Path(__file__).parents[2] / "framework/tools/lease-broker"
 if str(TOOLS_DIR) not in sys.path:
    sys.path.insert(0, str(TOOLS_DIR))
 def load_tool(module_name: str, filename: str):
    spec = importlib.util.spec_from_file_location(module_name, TOOLS_DIR / filename)
    if spec is None or spec.loader is None:
        raise RuntimeError(f"unable to load {filename}")
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module
 # Loaded under distinct module names from runtime_tools_unittest.py's own
 # LAUNCHER/GATE loads — importlib.util.module_from_spec() gives each load a
 # fresh module object regardless of name collisions, but distinct names keep
 # tracebacks/debugging unambiguous when both files run in the same process.
 LAUNCHER = load_tool("lease_runtime_launcher_version_coupling", "launch-runtime.py")
 VERSION_GATE = load_tool("lease_activation_version_gate_test", "activation_version_gate.py")
 def matching_capability() -> dict[str, object]:
    return dict(VERSION_GATE.EXPECTED_ACTIVATION_CAPABILITY)
 class AssertActivationCapabilityMatchesTest(unittest.TestCase):
    """Unit-level coverage of `activation_version_gate.py`'s own assertion,
    isolated from the launch-runtime.py seam it is wired into below."""
    def test_matching_capability_passes_silently(self) -> None:
        VERSION_GATE.assert_activation_capability_matches(matching_capability())
        # No exception is the assertion; nothing further to check.
    def test_absent_capability_fails_closed_not_silent_pass(self) -> None:
        with self.assertRaises(VERSION_GATE.VersionCouplingError) as raised:
            VERSION_GATE.assert_activation_capability_matches(None)
        message = str(raised.exception)
        self.assertIn("#869", message)
        self.assertIn("upgrade", message.lower())
    def test_version_mismatch_message_is_actionable(self) -> None:
        expected = {"name": "lease-runtime-activation", "version": 1}
        mismatched = {"name": "lease-runtime-activation", "version": 2}
        with self.assertRaises(VERSION_GATE.VersionCouplingError) as raised:
            VERSION_GATE.assert_activation_capability_matches(mismatched, expected)
        message = str(raised.exception)
        self.assertIn("v2", message)
        self.assertIn("v1", message)
        self.assertIn("#869", message)
        self.assertIn("upgrade", message.lower())
        self.assertIn("version skew", message.lower())
    def test_name_mismatch_fails_loud(self) -> None:
        expected = {"name": "lease-runtime-activation", "version": 1}
        mismatched = {"name": "some-other-capability", "version": 1}
        with self.assertRaises(VERSION_GATE.VersionCouplingError) as raised:
            VERSION_GATE.assert_activation_capability_matches(mismatched, expected)
        message = str(raised.exception)
        self.assertIn("some-other-capability", message)
        self.assertIn("lease-runtime-activation", message)
        self.assertIn("#869", message)
    def test_reversed_drift_newer_activation_than_enforcement_expects_also_fails(self) -> None:
        # A build/deploy where ACTIVATION shipped ahead of ENFORCEMENT is
        # exactly as much version skew as the reverse (#828's actual shape
        # was enforcement ahead of activation) — the assertion must not special
        # case direction.
        expected = {"name": "lease-runtime-activation", "version": 1}
        newer_activation = {"name": "lease-runtime-activation", "version": 2}
        with self.assertRaises(VERSION_GATE.VersionCouplingError):
            VERSION_GATE.assert_activation_capability_matches(newer_activation, expected)
 class ProbeActivationCapabilityTest(unittest.TestCase):
    """Coverage of the probe's command resolution and fail-closed transport
    handling — never spawns a real `mosaic` process."""
    def test_returns_none_when_mosaic_is_not_resolvable_on_path(self) -> None:
        result = VERSION_GATE.default_probe_activation_capability(
            {"PATH": "/nonexistent-bin-dir-for-869-c4-test"}
        )
        self.assertIsNone(result)
    def test_override_command_is_parsed_and_the_probe_subcommand_is_not_double_appended(
        self,
    ) -> None:
        captured: list[list[str]] = []
        class FakeCompleted:
            returncode = 0
            stdout = '{"name": "lease-runtime-activation", "version": 1}'
        def fake_run(argv: list[str], **_kwargs: object) -> FakeCompleted:
            captured.append(argv)
            return FakeCompleted()
        result = VERSION_GATE.default_probe_activation_capability(
            {VERSION_GATE.MOSAIC_COMMAND_OVERRIDE_VAR: "/fake/mosaic __lease-capability"},
            run=fake_run,
        )
        self.assertEqual(result, {"name": "lease-runtime-activation", "version": 1})
        self.assertEqual(captured, [["/fake/mosaic", "__lease-capability"]])
    def test_fails_closed_on_nonzero_exit_malformed_json_and_missing_fields(self) -> None:
        class NonZeroExit:
            returncode = 1
            stdout = '{"name": "lease-runtime-activation", "version": 1}'
        class MalformedOutput:
            returncode = 0
            stdout = "not-json"
        class MissingVersion:
            returncode = 0
            stdout = '{"name": "lease-runtime-activation"}'
        class WrongShapeVersion:
            returncode = 0
            stdout = '{"name": "lease-runtime-activation", "version": "1"}'
        class BooleanVersion:
            # bool is a subclass of int in Python; must not be accepted as
            # a version number.
            returncode = 0
            stdout = '{"name": "lease-runtime-activation", "version": true}'
        for fake in (
            NonZeroExit(),
            MalformedOutput(),
            MissingVersion(),
            WrongShapeVersion(),
            BooleanVersion(),
        ):
            with self.subTest(stdout=fake.stdout, returncode=fake.returncode):
                result = VERSION_GATE.default_probe_activation_capability(
                    {VERSION_GATE.MOSAIC_COMMAND_OVERRIDE_VAR: "/fake/mosaic"},
                    run=lambda *_a, fake=fake, **_kw: fake,
                )
                self.assertIsNone(result)
    def test_fails_closed_on_timeout_and_transport_error(self) -> None:
        def timeout_run(*_args: object, **_kwargs: object) -> None:
            raise subprocess.TimeoutExpired(cmd="mosaic", timeout=2.0)
        def oserror_run(*_args: object, **_kwargs: object) -> None:
            raise OSError("no such file or directory")
        for run_fake in (timeout_run, oserror_run):
            with self.subTest(run=run_fake.__name__):
                result = VERSION_GATE.default_probe_activation_capability(
                    {VERSION_GATE.MOSAIC_COMMAND_OVERRIDE_VAR: "/fake/mosaic"},
                    run=run_fake,
                )
                self.assertIsNone(result)
 class LaunchRuntimeVersionCouplingSeamTest(unittest.TestCase):
    """End-to-end (still fully faked) coverage of the seam as wired into
    `launch-runtime.py`'s `main()` — the strongest natural enforcement point
    per the C4 card, run before any broker registration."""
    def _run(self, *, probe):
        calls: dict[str, object] = {}
        def request(_path: Path, payload: dict[str, object]) -> dict[str, object]:
            calls["registered"] = True
            calls["request"] = payload
            return {"ok": True, "session_id": "a" * 64}
        def execute(command: str, argv: list[str], environment: dict[str, str]) -> None:
            calls["executed"] = (command, argv, environment)
        def initialize_generation(_path: Path, _generation: int) -> None:
            calls["generation_initialized"] = True
        stderr = io.StringIO()
        with redirect_stderr(stderr):
            result = LAUNCHER.main(
                ["--runtime", "claude", "--", "claude", "--print", "hello"],
                environ={"MOSAIC_LEASE_BROKER_SOCKET": "/run/test/broker.sock"},
                request=request,
                execute=execute,
                initialize_generation=initialize_generation,
                probe_activation_capability=probe,
            )
        return result, stderr.getvalue(), calls
    def test_matching_activation_version_passes_and_the_gate_proceeds(self) -> None:
        result, stderr_text, calls = self._run(probe=lambda *_a, **_kw: matching_capability())
        self.assertEqual(result, 0)
        self.assertEqual(stderr_text, "")
        self.assertTrue(calls.get("registered"))
        self.assertIn("executed", calls)
    def test_version_mismatch_fails_loud_denies_and_never_registers_or_execs(self) -> None:
        expected = LAUNCHER.EXPECTED_ACTIVATION_CAPABILITY
        mismatched = {"name": expected["name"], "version": expected["version"] + 1}
        result, stderr_text, calls = self._run(probe=lambda *_a, **_kw: mismatched)
        self.assertEqual(result, LAUNCHER.EXIT_VERSION_SKEW)
        self.assertNotEqual(result, 0)
        self.assertIn("#869", stderr_text)
        self.assertIn(f"v{mismatched['version']}", stderr_text)
        self.assertIn(f"v{expected['version']}", stderr_text)
        self.assertIn("upgrade", stderr_text.lower())
        # Never reaches broker registration or exec — the version gate is a
        # hard stop, not advisory.
        self.assertNotIn("registered", calls)
        self.assertNotIn("executed", calls)
    def test_name_mismatch_fails_loud(self) -> None:
        expected = LAUNCHER.EXPECTED_ACTIVATION_CAPABILITY
        mismatched = {"name": "some-other-capability", "version": expected["version"]}
        result, stderr_text, calls = self._run(probe=lambda *_a, **_kw: mismatched)
        self.assertEqual(result, LAUNCHER.EXIT_VERSION_SKEW)
        self.assertIn("#869", stderr_text)
        self.assertIn("some-other-capability", stderr_text)
        self.assertNotIn("registered", calls)
        self.assertNotIn("executed", calls)
    def test_absent_activation_capability_fails_closed_not_a_silent_pass(self) -> None:
        result, stderr_text, calls = self._run(probe=lambda *_a, **_kw: None)
        self.assertEqual(result, LAUNCHER.EXIT_VERSION_SKEW)
        self.assertNotEqual(result, 0)
        self.assertIn("#869", stderr_text)
        self.assertNotIn("registered", calls)
        self.assertNotIn("executed", calls)
    def test_version_gate_runs_before_and_independently_of_broker_registration(self) -> None:
        def request_must_not_be_called(*_args: object, **_kwargs: object) -> dict[str, object]:
            self.fail("broker must not be contacted when activation version is mismatched")
        stderr = io.StringIO()
        with redirect_stderr(stderr):
            result = LAUNCHER.main(
                ["--runtime", "claude", "--", "claude"],
                environ={"MOSAIC_LEASE_BROKER_SOCKET": "/run/test/broker.sock"},
                request=request_must_not_be_called,
                probe_activation_capability=lambda *_a, **_kw: None,
            )
        self.assertEqual(result, LAUNCHER.EXIT_VERSION_SKEW)
    def test_dedicated_exit_code_never_collides_with_usage_or_registration_codes(self) -> None:
        # Distinctness guard: a version-skew denial must never be mistaken
        # for the pre-existing usage error (64) or registration/exec
        # fail-closed code (1) this script already owns.
        self.assertNotIn(LAUNCHER.EXIT_VERSION_SKEW, (0, 1, 64))
 if __name__ == "__main__":
    unittest.main()
--- a/packages/mosaic/src/stages/finalize.ts
+++ b/packages/mosaic/src/stages/finalize.ts
@@ -13,37 +13,22 @@ import {
  type SkillSyncResult as ClaudeSkillSyncResult,
 } from '../commands/skill.js';
-/**
+function linkRuntimeAssets(mosaicHome: string, skipClaudeHooks: boolean): void {
 * Link runtime assets. Returns a warning string when the install-ordering
 * guard (#869 Point-1 C2) reported a degraded outcome — i.e. the
 * lease-enforcement hooks were NOT wired into ~/.claude/settings.json because
 * this host could not confirm it can activate them — so the caller can
 * surface it via `p.warn(...)` instead of it being swallowed by `stdio:
 * 'pipe'`. Non-fatal either way: the wizard always continues.
 */
 function linkRuntimeAssets(mosaicHome: string, skipClaudeHooks: boolean): string | undefined {
  const script = join(mosaicHome, 'bin', 'mosaic-link-runtime-assets');
-  if (!existsSync(script)) return undefined;
+  if (existsSync(script)) {
-  try {
+    try {
-    const result = spawnSync('bash', [script], {
+      spawnSync('bash', [script], {
-      timeout: 30000,
+        timeout: 30000,
-      stdio: 'pipe',
+        stdio: 'pipe',
-      encoding: 'utf-8',
+        env: {
-      env: {
+          ...process.env,
-        ...process.env,
+          ...(skipClaudeHooks ? { MOSAIC_SKIP_CLAUDE_HOOKS: '1' } : {}),
-        ...(skipClaudeHooks ? { MOSAIC_SKIP_CLAUDE_HOOKS: '1' } : {}),
+        },
-      },
+      });
-    });
+    } catch {
-    if (result.status !== 0) {
+      // Non-fatal: wizard continues
      const stderr = (result.stderr ?? '').trim();
      return (
        stderr || 'Runtime asset linking reported a non-zero exit (see mosaic doctor for details).'
      );
    }
  } catch {
    // Non-fatal: wizard continues
  }
  return undefined;
 }
 interface SyncSkillsResult {
@@ -216,7 +201,7 @@ export async function finalizeStage(
  // copied into ~/.claude/ while still linking the other runtime files.
  spin.update('Linking runtime assets...');
  const skipClaudeHooks = state.hooks?.accepted === false;
-  const linkWarning = linkRuntimeAssets(state.mosaicHome, skipClaudeHooks);
+  linkRuntimeAssets(state.mosaicHome, skipClaudeHooks);
  // 4. Sync skills (only installs the user-selected subset)
  let skillsResult: SyncSkillsResult = { success: true, installedCount: 0 };
@@ -251,10 +236,6 @@ export async function finalizeStage(
  spin.stop('Installation complete');
  // Surface the install-ordering guard's outcome (#869 Point-1 C2) — never
  // silent, even though the wizard continues either way.
  if (linkWarning) p.warn(linkWarning);
  // Report skill install failure clearly (non-fatal but user should know)
  if (!skillsResult.success && skillsResult.failureReason) {
    p.warn(skillsResult.failureReason);