feat(869-c4): enforcement/activation version-coupling assertion

Part of #869 (Point-1 C4). Locks the lease broker's ENFORCEMENT half
(launch-runtime.py) and ACTIVATION half (execLeaseGatedRuntime, C1's
LEASE_ACTIVATION_CAPABILITY) as one versioned unit, closing the #828
version-skew gap C1 only made observable.

- New packages/mosaic/framework/tools/lease-broker/activation_version_gate.py:
  EXPECTED_ACTIVATION_CAPABILITY (enforcement-owned, mirrors but is
  independent from C1's LEASE_ACTIVATION_CAPABILITY), a fail-closed
  subprocess probe of the CLI's hidden `mosaic __lease-capability`
  command, and an assertion that FAILS LOUD (VersionCouplingError with
  an actionable #869 remediation message) on mismatch OR absence —
  never a silent pass, never a dead gate.
- launch-runtime.py now runs this assertion first, before any broker
  registration, and denies with a dedicated exit code (65) distinct
  from its existing usage (64) and registration-failure (1) codes.
- Red-first tests: src/mutator-gate/version_coupling_unittest.py
  (module-level match/mismatch/name-mismatch/absent-capability cases,
  and seam-level LAUNCHER.main() cases proving the gate runs before
  broker registration and never silently passes).
- Existing fail-closed-on-absent-identity lock
  (runtime_tools_unittest.py) stays green: matching-capability fakes
  were injected into its pre-existing LAUNCHER.main() calls so the new
  gate runs alongside, not in place of, identity enforcement.
- mutator-gate.acceptance.spec.ts updated to supply a fake CLI-capability
  probe (matching the existing fake-broker/fake-runtime-binary test
  doubles already in that suite) everywhere it drives launch-runtime.py
  as a real subprocess.

launch.ts and lease-activation-probe.ts are untouched (C2/C5 avoidance,
C1 read-only).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/mosaic/framework/install.sh

@@ -18,12 +18,33 @@ 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).
@@ -639,6 +660,10 @@ 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"
 
@@ -666,10 +691,15 @@ step "Post-install tasks"
 SCRIPTS="$TARGET_DIR/tools/_scripts"
 
 if [[ -x "$SCRIPTS/mosaic-link-runtime-assets" ]]; then
-  if "$SCRIPTS/mosaic-link-runtime-assets" >/dev/null 2>&1; then
+  link_args=()
+  [[ "$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)"
+    warn "Runtime asset linking failed (non-fatal) — see message above for details."
   fi
 fi
 

packages/mosaic/framework/systemd/user/mosaic-lease-broker.service

@@ -0,0 +1,22 @@
+[Unit]
+Description=Mosaic lease broker daemon (framework tools/lease-broker/daemon.py)
+Documentation=https://git.mosaicstack.dev/mosaicstack/stack
+After=default.target
+
+[Service]
+Type=simple
+# The broker socket lives under the runtime directory so it disappears with
+# the user session instead of surviving as stale state across logins.
+# daemon.py's secure_parent() fails closed unless this directory is exactly
+# 0700, so RuntimeDirectoryMode is not cosmetic.
+RuntimeDirectory=mosaic-lease
+RuntimeDirectoryMode=0700
+# Remove loader and noninteractive-shell controls before ExecStart loads env,
+# matching the tmux fleet units in this same directory.
+UnsetEnvironment=LD_PRELOAD BASH_ENV ENV
+ExecStart=/usr/bin/env -i HOME=%h PATH=/usr/bin:/bin XDG_RUNTIME_DIR=%t /bin/bash --noprofile --norc %h/.config/mosaic/tools/lease-broker/start-lease-broker.sh
+Restart=on-failure
+RestartSec=1
+
+[Install]
+WantedBy=default.target

packages/mosaic/framework/tools/_scripts/mosaic-link-runtime-assets

@@ -4,6 +4,22 @@ 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"
@@ -24,6 +40,103 @@ 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"
 
@@ -110,6 +223,13 @@ 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
 
@@ -167,3 +287,12 @@ 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

packages/mosaic/framework/tools/_scripts/test-install-ordering-guard.sh

@@ -0,0 +1,180 @@
+#!/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"

packages/mosaic/framework/tools/git/README.md

@@ -33,3 +33,64 @@ 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.

packages/mosaic/framework/tools/git/ci-queue-wait.ps1

@@ -185,6 +185,16 @@ switch ($platform) {
             $headSha = ($branchPayload.commit.id | Out-String).Trim()
         }
         catch {
+            # A not-yet-pushed feature branch has no in-flight pipeline, so the
+            # pre-push queue guard must treat 404 as "queue clear", not crash.
+            $statusCode = $null
+            if ($_.Exception.Response) {
+                $statusCode = [int]$_.Exception.Response.StatusCode
+            }
+            if ($statusCode -eq 404) {
+                Write-Host "[ci-queue-wait] branch $Branch not yet on remote — no in-flight pipeline; queue clear."
+                exit 0
+            }
             Write-Error "Could not resolve $Branch head SHA from Gitea API."
             exit 1
         }

packages/mosaic/framework/tools/git/ci-queue-wait.sh

@@ -137,7 +137,21 @@ gitea_get_branch_head_sha() {
     local branch="$3"
     local token="$4"
     local url="https://${host}/api/v1/repos/${repo}/branches/${branch}"
-    curl -fsSL -H "User-Agent: curl/8" -H "Authorization: token ${token}" "$url" | python3 -c '
+    # Capture HTTP status so an absent branch (404) is distinguished from an API
+    # error. A not-yet-pushed feature branch has no in-flight pipeline, so the
+    # pre-push queue guard must treat 404 as "queue clear", not crash.
+    local resp code body
+    resp=$(curl -sS -H "User-Agent: curl/8" -H "Authorization: token ${token}" -w $'\n%{http_code}' "$url")
+    code="${resp##*$'\n'}"
+    body="${resp%$'\n'*}"
+    if [[ "$code" == "404" ]]; then
+        echo "__BRANCH_ABSENT__"
+        return 0
+    fi
+    if [[ "$code" != "200" ]]; then
+        return 1
+    fi
+    printf '%s' "$body" | python3 -c '
 import json, sys
 data = json.load(sys.stdin)
 commit = data.get("commit") or {}
@@ -219,6 +233,10 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
         exit 1
     }
     HEAD_SHA=$(gitea_get_branch_head_sha "$HOST" "$OWNER/$REPO" "$BRANCH" "$TOKEN")
+    if [[ "$HEAD_SHA" == "__BRANCH_ABSENT__" ]]; then
+        echo "[ci-queue-wait] branch ${BRANCH} not yet on remote — no in-flight pipeline; queue clear."
+        exit 0
+    fi
     if [[ -z "$HEAD_SHA" ]]; then
         echo "Error: Could not resolve ${BRANCH} head SHA." >&2
         exit 1

packages/mosaic/framework/tools/git/detect-platform.sh

@@ -505,6 +505,28 @@ 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

packages/mosaic/framework/tools/git/git-credential-mosaic

@@ -0,0 +1,69 @@
+#!/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"

packages/mosaic/framework/tools/git/pr-review.sh

@@ -203,7 +203,15 @@ try:
         if not url:
             return False
         origin, path = _origin_and_path(url)
-        return origin == base_origin and path == expected_path
+        # Repo owner/repo slugs are case-insensitive (Gitea canonicalizes the
+        # pull_request_url slug to lowercase on return), while EXPECTED_REPO_SLUG
+        # is taken verbatim from GITEA_API_BASE and may be mixed-case. The
+        # remainder of the path (".../pulls/<number>") is numeric, so lowercasing
+        # the whole path for this comparison only relaxes case, not identity: the
+        # origin tuple (scheme+host+port) above still pins the provider host, and
+        # the path is still compared in FULL (no endswith/suffix match), so the
+        # look-alike-host and same-host decoy-prefix protections are unchanged.
+        return origin == base_origin and path.lower() == expected_path.lower()
 
     if comment.get("id") != expected_id:
         raise ValueError("read-back id does not match the created id")

packages/mosaic/framework/tools/git/test-ci-queue-wait-branch-absent.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Regression harness for ci-queue-wait.sh's 404-branch-absent handling.
+#
+# gitea_get_branch_head_sha() resolves a branch's head SHA before the
+# pre-push queue guard runs. A branch that has never been pushed doesn't
+# exist on the remote yet, so Gitea's branches/<branch> endpoint 404s.
+# Before the fix, `curl -fsSL` failed on the 404, its empty stdout was piped
+# into `python3 -c 'json.load(sys.stdin)'`, and the resulting
+# JSONDecodeError crashed the guard -- blocking every new feature branch's
+# first push. The fix must treat 404 as "no in-flight pipeline" (queue
+# clear) while still failing closed on a genuine API error.
+#
+# Covers:
+#   (a) 404 branch-absent          -> exit 0, "queue clear" message.
+#   (b) 200 existing branch + a terminal CI state -> unchanged behavior.
+#   (c) genuine API error (500)    -> still fail-closed (nonzero exit).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/ci-queue-wait-branch-absent}"
+REPO_DIR="$WORK_DIR/repo"
+STUB_DIR="$WORK_DIR/stubs"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$REPO_DIR" "$STUB_DIR"
+
+git -C "$REPO_DIR" init -q
+git -C "$REPO_DIR" remote add origin https://git.example.test/acme/widgets.git
+
+# Minimal curl stub. Selects a canned response by inspecting which Gitea
+# endpoint is being hit (branches/<branch> vs commits/<sha>/status) and
+# whether -w '%{http_code}' was requested. Only the patched branch-lookup
+# call passes -w; the unpatched call and the (unchanged) status call both
+# use plain `curl -fsSL` semantics -- exit nonzero and print nothing on a
+# non-2xx response. This lets the same stub exercise both the pre-fix and
+# post-fix branch-lookup code paths faithfully.
+cat > "$STUB_DIR/curl" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+has_w=0
+url=""
+for arg in "$@"; do
+    case "$arg" in
+        -w) has_w=1 ;;
+        http://*|https://*) url="$arg" ;;
+    esac
+done
+
+case "$url" in
+    */branches/*) mode="${MOSAIC_STUB_BRANCH_MODE:?MOSAIC_STUB_BRANCH_MODE not set}" ;;
+    */status)     mode="${MOSAIC_STUB_STATUS_MODE:-terminal-success}" ;;
+    *)
+        echo "curl stub: unrecognized URL: $url" >&2
+        exit 2
+        ;;
+esac
+
+case "$mode" in
+    404)  code=404; body="" ;;
+    200)  code=200; body='{"commit":{"id":"deadbeefcafef00d0123456789abcdef01234567"}}' ;;
+    500)  code=500; body='{"message":"internal server error"}' ;;
+    no-status)         code=200; body='{}' ;;
+    terminal-success)  code=200; body='{"state":"success"}' ;;
+    *)
+        echo "curl stub: unknown mode=$mode" >&2
+        exit 2
+        ;;
+esac
+
+if [[ "$has_w" == 1 ]]; then
+    printf '%s\n%s' "$body" "$code"
+    exit 0
+fi
+
+# Unpatched branch-lookup call / status-endpoint call: real curl -fsSL
+# exits nonzero and emits nothing on stdout for a non-2xx response.
+if [[ "$code" != "200" ]]; then
+    exit 22
+fi
+printf '%s' "$body"
+SH
+chmod +x "$STUB_DIR/curl"
+
+run_ci_queue_wait() {
+    local branch="$1"
+    (
+        cd "$REPO_DIR"
+        export PATH="$STUB_DIR:$PATH"
+        export MOSAIC_CREDENTIALS_FILE="$WORK_DIR/no-credentials.json"
+        export GITEA_TOKEN="stub-token"
+        export GITEA_URL="https://git.example.test"
+        "$SCRIPT_DIR/ci-queue-wait.sh" -B "$branch" --purpose push -t 5 -i 1
+    )
+}
+
+fail=0
+
+# (a) 404 branch-absent -> queue clear, exit 0.
+set +e
+out_a=$(MOSAIC_STUB_BRANCH_MODE=404 run_ci_queue_wait "feat/not-pushed-yet" 2>&1)
+status_a=$?
+set -e
+if [[ "$status_a" -ne 0 ]]; then
+    echo "FAIL(a): expected exit 0 for 404 branch-absent, got $status_a" >&2
+    echo "$out_a" >&2
+    fail=1
+elif [[ "$out_a" != *"queue clear"* ]]; then
+    echo "FAIL(a): expected a queue-clear message, got:" >&2
+    echo "$out_a" >&2
+    fail=1
+fi
+
+# (b) 200 existing branch + terminal CI state -> unchanged behavior, exit 0.
+set +e
+out_b=$(MOSAIC_STUB_BRANCH_MODE=200 MOSAIC_STUB_STATUS_MODE=terminal-success run_ci_queue_wait "main" 2>&1)
+status_b=$?
+set -e
+if [[ "$status_b" -ne 0 ]]; then
+    echo "FAIL(b): expected exit 0 for existing branch with terminal status, got $status_b" >&2
+    echo "$out_b" >&2
+    fail=1
+elif [[ "$out_b" != *"sha=deadbeefcafef00d0123456789abcdef01234567"* ]]; then
+    echo "FAIL(b): expected the resolved HEAD SHA to be logged, got:" >&2
+    echo "$out_b" >&2
+    fail=1
+elif [[ "$out_b" == *"queue clear"* ]]; then
+    echo "FAIL(b): an existing branch must not take the branch-absent path" >&2
+    echo "$out_b" >&2
+    fail=1
+fi
+
+# (c) genuine API error (500) -> still fail-closed, exit nonzero.
+set +e
+out_c=$(MOSAIC_STUB_BRANCH_MODE=500 run_ci_queue_wait "feat/some-branch" 2>&1)
+status_c=$?
+set -e
+if [[ "$status_c" -eq 0 ]]; then
+    echo "FAIL(c): expected a nonzero exit for a genuine 500 API error, got 0" >&2
+    echo "$out_c" >&2
+    fail=1
+elif [[ "$out_c" == *"queue clear"* ]]; then
+    echo "FAIL(c): a genuine API error must not be reported as queue-clear" >&2
+    echo "$out_c" >&2
+    fail=1
+fi
+
+if [[ "$fail" -eq 0 ]]; then
+    echo "ci-queue-wait branch-absent regression passed (3/3 cases)"
+fi
+
+exit "$fail"

packages/mosaic/framework/tools/git/test-git-credential-mosaic.sh

@@ -0,0 +1,161 @@
+#!/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"

packages/mosaic/framework/tools/git/test-gitea-token-identity.sh

@@ -0,0 +1,122 @@
+#!/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"

packages/mosaic/framework/tools/git/test-pr-review-gitea-comment.sh

@@ -406,6 +406,13 @@ elif mode == "comment-url-wrong-repo":
 elif mode == "comment-url-suffix-injection":
     # Prefix-injected: a bare endswith("/<slug>/pulls/123") test would ACCEPT it.
     pr_url = f"{_origin}/deceptive{_slug}/pulls/123"
+elif mode == "comment-mixed-case-slug":
+    # #875: EXPECTED_REPO_SLUG is taken verbatim from GITEA_API_BASE and can be
+    # mixed-case (e.g. "USC/uconnect"), but Gitea canonicalizes the returned
+    # pull_request_url's owner/repo segment to LOWERCASE. Model that here by
+    # lowercasing only the slug path, independent of the (possibly mixed-case)
+    # web_base the wrapper was configured with.
+    pr_url = f"{_origin}{_slug.lower()}/pulls/123"
 record = {
     "id": 456,
     "body": body,
@@ -868,6 +875,19 @@ for bad_mode in comment-url-wrong-host comment-url-wrong-owner comment-url-wrong
     assert_no_temp_leak "$bad_mode"
 done
 
+# Case 15b (#875): a MIXED-CASE repo slug (as embedded verbatim in
+# GITEA_API_BASE, e.g. "USC/uconnect") must still verify when Gitea returns the
+# comment's pull_request_url with its owner/repo segment canonicalized to
+# LOWERCASE ("usc/uconnect"). This is a legitimate, unforged provider response —
+# not a spoof — so `_belongs` must accept it (case-insensitive slug compare)
+# while still requiring the origin (scheme+host+port) and the rest of the path
+# to match in full. Pre-#875-fix this fails closed on a real success
+# (false-negative); post-fix it verifies.
+run_review comment-mixed-case-slug comment durable-body https://git.mosaicstack.dev \
+    https://git.mosaicstack.dev/USC/uconnect.git USC/uconnect
+grep -q 'Added and verified comment on Gitea PR #123' "$OUTPUT_FILE"
+assert_no_temp_leak "comment-mixed-case-slug"
+
 # Case 16 (#865 ITEM 1, current-head TOCTOU): the PR head advances between the
 # pre-submit head read (which pins the review) and the post-verify re-read. The
 # review is genuinely created and verified as pinned to the OLD head, but the

packages/mosaic/framework/tools/lease-broker/activation_version_gate.py

@@ -0,0 +1,180 @@
+#!/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))

packages/mosaic/framework/tools/lease-broker/launch-runtime.py

@@ -12,11 +12,24 @@ 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]:
@@ -47,6 +60,10 @@ 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"))
@@ -66,6 +83,25 @@ 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"))

packages/mosaic/framework/tools/lease-broker/start-lease-broker.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Supervisor entry point for the Mosaic lease broker daemon (issue #869, C3).
+#
+# Resolves the broker socket path with the SAME precedence as
+# `defaultLeaseBrokerSocket` in `packages/mosaic/src/commands/launch.ts`, so a
+# gated runtime launched through that client always finds the socket this
+# supervisor creates:
+#   1. an explicit MOSAIC_LEASE_BROKER_SOCKET
+#   2. "$XDG_RUNTIME_DIR/mosaic-lease/broker.sock"
+#   3. "/run/user/<uid>/mosaic-lease/broker.sock"
+#
+# The state file is colocated next to the socket (same directory,
+# "state.json"), mirroring how the broker already colocates its per-session
+# generation files beside the socket.
+#
+# This script never installs, enables, or starts the systemd unit that calls
+# it; it is only ever invoked BY that unit (or by a human/test harness that
+# passes its own HOME/XDG_RUNTIME_DIR).
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
+
+if [ -n "${MOSAIC_LEASE_BROKER_SOCKET:-}" ]; then
+  SOCKET="$MOSAIC_LEASE_BROKER_SOCKET"
+else
+  RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+  SOCKET="$RUNTIME_DIR/mosaic-lease/broker.sock"
+fi
+STATE="$(dirname -- "$SOCKET")/state.json"
+
+exec python3 "$SCRIPT_DIR/daemon.py" --socket "$SOCKET" --state "$STATE"

packages/mosaic/framework/tools/orchestrator/README.md

@@ -0,0 +1,92 @@
+# orchestrator/ tools
+
+Helper scripts for r0 coordinator / orchestrator sessions — mission lifecycle,
+session health, continuation, and board maintenance. See
+`framework/guides/ORCHESTRATOR-PROTOCOL.md` for the surrounding process.
+
+| Script               | Purpose                                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------------------- |
+| `mission-init.sh`    | Initialize a new orchestration mission (manifest, scratchpad, TASKS.md).                        |
+| `mission-status.sh`  | Show the mission progress dashboard.                                                            |
+| `session-run.sh`     | Generate continuation context and launch the target runtime.                                    |
+| `session-resume.sh`  | Crash recovery for dead orchestrator sessions.                                                  |
+| `session-status.sh`  | Check agent session health.                                                                     |
+| `continue-prompt.sh` | Generate the continuation prompt for the next session.                                          |
+| `board-roll.sh`      | Keep a LIVE orchestration board under its byte cap by rolling the oldest entries to its LEDGER. |
+| `smoke-test.sh`      | Behavior smoke checks for the coord continue/run workflows.                                     |
+| `test-board-roll.sh` | Regression harness for `board-roll.sh`.                                                         |
+| `_lib.sh`            | Shared functions sourced by the above (state files, TASKS.md parsing, locks).                   |
+
+## board-roll.sh
+
+Coordinator boards (`MOS-ORCHESTRATION-BOARD-LIVE.md`, `MS-LEAD-BOARD-LIVE.md`)
+follow a **"< 8 KB LIVE"** discipline: the LIVE board is the only file loaded on
+resume, so it must stay small, and history lives in an append-only LEDGER. When a
+board write would push LIVE over its cap, coordinators otherwise hand-trim and
+retry every time — an observed 38 ABORT-OVER-CAP cycles in one 24 h window.
+`board-roll.sh` automates that trim mechanically and reversibly: the audit trail
+is moved to the LEDGER instead of being hand-deleted.
+
+### Contract (conservative — it never guesses what is safe to move)
+
+The LIVE board opts in by wrapping its aging archival ticks in an explicit roll
+zone. Everything **outside** the markers (title, protocol blockquote, curated
+always-current `##` sections) is pinned and never touched:
+
+```markdown
+# MOS ORCHESTRATION BOARD — LIVE state
+
+> protocol blockquote … (pinned)
+
+## 🟦 Curated always-current section (pinned)
+
+…
+
+<!-- BOARD-ROLL:START -->
+
+### 2026-07-22 (mid²²) — newest tick, stays longest
+
+…
+
+### 2026-07-20 (dawn) — oldest tick, rolled first
+
+…
+
+<!-- BOARD-ROLL:END -->
+```
+
+Inside the zone, entries are delimited by a heading marker (default `### `) and
+are assumed **newest-first (top) → oldest-last (bottom)**. `board-roll.sh` moves
+whole oldest (bottom-most) entry blocks out of the zone and appends them verbatim
+to the LEDGER, one at a time, until LIVE is back under the cap or the zone is
+empty. If the board has no markers, it exits `3` and changes nothing — adding the
+markers is a deliberate opt-in by the board owner.
+
+### Usage
+
+```bash
+board-roll.sh --live <LIVE.md> --ledger <LEDGER.md> [options]
+
+  --live   <path>    LIVE board file (required)
+  --ledger <path>    append-only LEDGER file (required; created if absent)
+  --cap    <bytes>   size ceiling for LIVE (default 8192)
+  --marker <prefix>  entry-heading prefix inside the roll zone (default "### ")
+  --dry-run          report what would move; change nothing
+  -h, --help         show help and exit 0
+```
+
+Only **one** roll zone is supported. If a board carries more than one
+`BOARD-ROLL:START`/`END` pair, `board-roll.sh` refuses (exit `3`, zero changes)
+rather than span first-START..last-END and relocate the curated content between
+the zones — consolidate the ticks into a single zone instead.
+
+Exit codes: `0` LIVE under cap (already, or after rolling) — on `--dry-run`, a
+plan exists or nothing to do · `2` usage / argument / IO error · `3` cannot meet
+the cap (no markers, **more than one marker pair**, or the pinned sections alone
+exceed the cap and need a manual trim).
+
+Writes are atomic (temp file + `mv`, LEDGER first) so a failure never leaves a
+board half-written; line endings are normalized to LF on rewrite. `--dry-run`
+first is recommended when wiring it into a board update protocol.
+
+Run the regression suite with `bash test-board-roll.sh`.

packages/mosaic/framework/tools/orchestrator/board-roll.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+#
+# board-roll.sh — keep a LIVE orchestration board under its byte cap by rolling
+#                 the oldest archival entries out to its append-only LEDGER.
+#
+# WHY: coordinator boards (MOS-ORCHESTRATION-BOARD-LIVE.md, MS-LEAD-BOARD-LIVE.md)
+# enforce a "< 8 KB LIVE" discipline via a self-guard that ABORTs the board write
+# when the file exceeds the cap. In practice the LIVE board keeps bumping the cap,
+# so coordinators hand-trim + retry every time (observed: 38 ABORT-OVER-CAP cycles
+# in a 24h window on one coordinator). This automates that trim, mechanically and
+# reversibly, so the audit trail is preserved in the LEDGER instead of hand-deleted.
+#
+# CONTRACT (conservative by design — it NEVER guesses what is safe to move):
+#   The LIVE board must declare an explicit ROLL ZONE with HTML-comment markers:
+#
+#       <!-- BOARD-ROLL:START -->
+#       ### 2026-07-22 (newest tick — stays longest)
+#       ...
+#       ### 2026-07-19 (oldest tick — rolled first)
+#       ...
+#       <!-- BOARD-ROLL:END -->
+#
+#   Everything OUTSIDE the markers (title, protocol blockquote, curated always-current
+#   `##` sections) is PINNED and never touched. Inside the zone, entries are delimited
+#   by a heading marker (default `### `) and are assumed newest-first (top) → oldest-last
+#   (bottom), matching board convention. board-roll moves whole oldest (bottom-most)
+#   entry blocks out of the zone and APPENDS them verbatim to the LEDGER, one block at a
+#   time, until the LIVE file is back under the cap or the zone is empty.
+#
+#   If no markers are present, it exits 3 without changing anything (safe default —
+#   adding the markers is a deliberate opt-in by the board owner).
+#
+# USAGE:
+#   board-roll.sh --live <LIVE.md> --ledger <LEDGER.md> [options]
+#
+# OPTIONS:
+#   --live   <path>   LIVE board file (required)
+#   --ledger <path>   append-only LEDGER file (required; created if absent)
+#   --cap    <bytes>  size ceiling for LIVE (default 8192)
+#   --marker <prefix> entry-heading prefix inside the roll zone (default "### ")
+#   --dry-run         report what would move + resulting size; change nothing
+#   -h, --help        print usage and exit 0
+#
+# EXIT CODES:
+#   0  LIVE is under cap (already, or after rolling); on --dry-run, 0 = a plan exists
+#      (or nothing to do)
+#   2  usage / argument / IO error (bad flag, missing file, unwritable target)
+#   3  cannot satisfy the cap: no roll markers present, MORE THAN ONE marker pair
+#      (multiple zones are refused, not guessed), OR the zone was emptied and LIVE
+#      is still over cap (curated pinned sections need a manual trim)
+#
+# NOTE: line endings are normalized to LF on rewrite (boards are LF markdown); a
+# trailing newline is always ensured. Writes are atomic (temp file + mv) so a
+# failure never leaves LIVE or LEDGER half-written.
+
+set -euo pipefail
+
+START_MARK='<!-- BOARD-ROLL:START -->'
+END_MARK='<!-- BOARD-ROLL:END -->'
+
+usage() {
+    cat <<'EOF'
+Usage: board-roll.sh --live <LIVE.md> --ledger <LEDGER.md> [options]
+
+Roll the oldest entries out of a LIVE orchestration board into its LEDGER
+until the LIVE file is under a byte cap. Conservative: only content inside
+explicit <!-- BOARD-ROLL:START -->/<!-- BOARD-ROLL:END --> markers is moved.
+
+Options:
+  --live   <path>    LIVE board file (required)
+  --ledger <path>    append-only LEDGER file (required; created if absent)
+  --cap    <bytes>   size ceiling for LIVE (default 8192)
+  --marker <prefix>  entry-heading prefix inside the roll zone (default "### ")
+  --dry-run          report what would move; change nothing
+  -h, --help         show this help and exit 0
+
+Exit: 0 under cap (or dry-run plan) · 2 usage/IO error · 3 cannot meet cap
+      (no markers, or pinned sections alone exceed the cap).
+EOF
+}
+
+die() { echo "board-roll: $*" >&2; exit 2; }
+
+LIVE=""; LEDGER=""; CAP=8192; MARKER='### '; DRYRUN=0
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --live)    LIVE="${2:-}"; shift 2 || die "--live needs a value" ;;
+        --ledger)  LEDGER="${2:-}"; shift 2 || die "--ledger needs a value" ;;
+        --cap)     CAP="${2:-}"; shift 2 || die "--cap needs a value" ;;
+        --marker)  MARKER="${2:-}"; shift 2 || die "--marker needs a value" ;;
+        --dry-run) DRYRUN=1; shift ;;
+        -h|--help) usage; exit 0 ;;
+        *) usage >&2; die "unknown option: $1" ;;
+    esac
+done
+
+[[ -n "$LIVE"   ]] || { usage >&2; die "--live is required"; }
+[[ -n "$LEDGER" ]] || { usage >&2; die "--ledger is required"; }
+[[ -f "$LIVE"   ]] || die "LIVE file not found: $LIVE"
+[[ "$CAP" =~ ^[0-9]+$ ]] || die "--cap must be a non-negative integer, got: $CAP"
+
+# --- read LIVE into a line array (newlines stripped; re-added on write) ---------
+mapfile -t LINES < "$LIVE"
+
+# byte size of an array rendered as LF-terminated text
+render_size() {
+    if [[ $# -eq 0 ]]; then printf 0; return; fi
+    printf '%s\n' "$@" | wc -c
+}
+
+orig_size=$(render_size "${LINES[@]}")
+
+# --- already under cap → nothing to do -----------------------------------------
+if (( orig_size < CAP )); then
+    echo "board-roll: LIVE is ${orig_size}B (< cap ${CAP}B) — nothing to roll."
+    exit 0
+fi
+
+# --- locate the roll-zone markers ----------------------------------------------
+# Exactly ONE marker pair is supported. If a board carries more than one START or
+# END marker we REFUSE (exit 3, zero changes) rather than guess: a naive
+# first-START..last-END span would swallow the curated content and the intermediate
+# markers sitting between two intended zones and silently relocate that pinned text
+# to the LEDGER — the exact data-loss this tool exists to prevent. Refusing matches
+# the "no markers = exit 3" conservative posture.
+start_idx=-1; end_idx=-1; start_count=0; end_count=0
+for i in "${!LINES[@]}"; do
+    if [[ "${LINES[$i]}" == "$START_MARK" ]]; then
+        if (( start_count == 0 )); then start_idx=$i; fi
+        start_count=$(( start_count + 1 ))
+    fi
+    if [[ "${LINES[$i]}" == "$END_MARK" ]]; then
+        end_idx=$i
+        end_count=$(( end_count + 1 ))
+    fi
+done
+if (( start_count > 1 || end_count > 1 )); then
+    echo "board-roll: LIVE is ${orig_size}B (>= cap ${CAP}B) but has ${start_count} START / ${end_count} END" >&2
+    echo "  markers — only a SINGLE '$START_MARK' … '$END_MARK' roll zone is supported." >&2
+    echo "  Multiple zones are refused (not guessed) so content between zones is never relocated." >&2
+    echo "  Consolidate the archival ticks into one zone, or trim manually." >&2
+    exit 3
+fi
+if (( start_idx < 0 || end_idx < 0 || end_idx <= start_idx )); then
+    echo "board-roll: LIVE is ${orig_size}B (>= cap ${CAP}B) but no usable roll zone" >&2
+    echo "  (need '$START_MARK' then '$END_MARK'). Add the markers around the" >&2
+    echo "  archival tick section to opt this board into automatic rolling." >&2
+    exit 3
+fi
+
+# preamble = lines [0 .. start_idx]   (inclusive of START marker)
+# zone     = lines (start_idx .. end_idx)  (exclusive of both markers)
+# footer   = lines [end_idx .. end]   (inclusive of END marker)
+preamble=(); zone=(); footer=()
+for i in "${!LINES[@]}"; do
+    if   (( i <= start_idx )); then preamble+=("${LINES[$i]}")
+    elif (( i <  end_idx  )); then zone+=("${LINES[$i]}")
+    else footer+=("${LINES[$i]}")
+    fi
+done
+
+# --- split the zone into a fixed head + entry blocks ----------------------------
+# zone_head = any zone lines before the first entry marker (kept, never rolled).
+# blocks[k] = newline-joined text of entry k (marker line .. line before next marker).
+zone_head=(); declare -a block_start=()
+first_block=-1
+for i in "${!zone[@]}"; do
+    if [[ "${zone[$i]}" == "$MARKER"* ]]; then
+        [[ $first_block -eq -1 ]] && first_block=$i
+        block_start+=("$i")
+    fi
+done
+if (( first_block == -1 )); then
+    echo "board-roll: LIVE is ${orig_size}B (>= cap ${CAP}B) but the roll zone has no" >&2
+    echo "  '${MARKER}' entries to move. Trim the pinned sections manually." >&2
+    exit 3
+fi
+for (( i=0; i<first_block; i++ )); do zone_head+=("${zone[$i]}"); done
+
+nblocks=${#block_start[@]}
+# block k spans zone[ block_start[k] .. (block_start[k+1]-1 or end-of-zone) ]
+block_text() {  # $1 = block index → prints the block's lines, LF-joined (no trailing)
+    local k=$1 s e
+    s=${block_start[$k]}
+    if (( k+1 < nblocks )); then e=$(( block_start[$((k+1))] - 1 )); else e=$(( ${#zone[@]} - 1 )); fi
+    local out=()
+    for (( j=s; j<=e; j++ )); do out+=("${zone[$j]}"); done
+    printf '%s\n' "${out[@]}"
+}
+
+# --- greedily roll oldest (bottom-most) blocks until under cap ------------------
+# keep = number of newest blocks retained; start with all, drop from the bottom.
+keep=$nblocks       # blocks [keep .. nblocks-1] are the oldest set that gets moved
+current_size=$orig_size
+build_live_size() {  # size of LIVE if we keep blocks [0 .. keep-1]
+    local acc=("${preamble[@]}" "${zone_head[@]}")
+    local k s e j
+    for (( k=0; k<keep; k++ )); do
+        s=${block_start[$k]}
+        if (( k+1 < nblocks )); then e=$(( block_start[$((k+1))] - 1 )); else e=$(( ${#zone[@]} - 1 )); fi
+        for (( j=s; j<=e; j++ )); do acc+=("${zone[$j]}"); done
+    done
+    acc+=("${footer[@]}")
+    render_size "${acc[@]}"
+}
+while (( current_size >= CAP && keep > 0 )); do
+    keep=$(( keep - 1 ))
+    current_size=$(build_live_size)
+done
+
+moved_count=$(( nblocks - keep ))
+if (( moved_count == 0 )); then
+    # zone had entries but none movable brought us under (shouldn't happen: keep hits 0)
+    echo "board-roll: could not reduce LIVE below cap (${current_size}B >= ${CAP}B)." >&2
+    exit 3
+fi
+
+# --- dry-run report -------------------------------------------------------------
+plan_headers() {
+    local k
+    for (( k=keep; k<nblocks; k++ )); do
+        # first line of each moved block
+        printf '    %s\n' "${zone[${block_start[$k]}]}"
+    done
+}
+if (( DRYRUN )); then
+    echo "board-roll: DRY RUN"
+    echo "  LIVE now:   ${orig_size}B (cap ${CAP}B) — over by $(( orig_size - CAP ))B"
+    echo "  would roll: ${moved_count} of ${nblocks} entr$([[ $moved_count -eq 1 ]] && echo y || echo ies) (oldest first):"
+    plan_headers
+    echo "  LIVE after: ${current_size}B"
+    if (( current_size >= CAP )); then
+        echo "  WARNING: still >= cap after emptying the zone; pinned sections need a manual trim." >&2
+        exit 3
+    fi
+    exit 0
+fi
+
+# --- commit the roll atomically -------------------------------------------------
+live_tmp="$(mktemp "${LIVE}.roll.XXXXXX")" || die "cannot create temp next to LIVE"
+ledger_tmp=""
+# shellcheck disable=SC2329  # invoked indirectly via `trap cleanup EXIT`
+cleanup() { rm -f "$live_tmp" "$ledger_tmp" 2>/dev/null || true; }
+trap cleanup EXIT
+
+# new LIVE = preamble + zone_head + kept blocks + footer
+{
+    printf '%s\n' "${preamble[@]}" "${zone_head[@]}"
+    for (( k=0; k<keep; k++ )); do block_text "$k"; done
+    printf '%s\n' "${footer[@]}"
+} > "$live_tmp"
+
+# LEDGER gets the moved blocks appended verbatim, in original top→bottom order,
+# under a provenance separator. LEDGER is append-only, so we only ever add at EOF.
+ledger_tmp="$(mktemp "${LEDGER}.roll.XXXXXX")" || die "cannot create temp next to LEDGER"
+if [[ -f "$LEDGER" ]]; then cat "$LEDGER" > "$ledger_tmp"; fi
+# ensure a trailing newline on existing content before appending
+if [[ -s "$ledger_tmp" && -n "$(tail -c1 "$ledger_tmp")" ]]; then printf '\n' >> "$ledger_tmp"; fi
+{
+    printf '\n<!-- board-roll: %d entr%s rolled from %s -->\n' \
+        "$moved_count" "$([[ $moved_count -eq 1 ]] && echo y || echo ies)" "$(basename "$LIVE")"
+    for (( k=keep; k<nblocks; k++ )); do block_text "$k"; done
+} >> "$ledger_tmp"
+
+# atomic swap (both, LEDGER first so a crash never drops content that left LIVE)
+mv "$ledger_tmp" "$LEDGER"; ledger_tmp=""
+mv "$live_tmp" "$LIVE"; live_tmp=""
+trap - EXIT
+
+# read the real on-disk size back (truthful, not the predicted value)
+final_size=$(wc -c < "$LIVE")
+echo "board-roll: rolled ${moved_count} entr$([[ $moved_count -eq 1 ]] && echo y || echo ies) to $(basename "$LEDGER"); LIVE ${orig_size}B → ${final_size}B (cap ${CAP}B)."
+if (( final_size >= CAP )); then
+    echo "board-roll: still >= cap after rolling all zone entries; pinned sections need a manual trim." >&2
+    exit 3
+fi
+exit 0

packages/mosaic/framework/tools/orchestrator/test-board-roll.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# Regression harness for board-roll.sh — rolling oldest LIVE-board entries to LEDGER.
+#
+# Asserts:
+#   1. Under cap → no-op, exit 0, files unchanged.
+#   2. Over cap, no roll markers → exit 3, LIVE unchanged (never guesses).
+#   3. Over cap, markers present → rolls the fewest oldest entries to get under cap,
+#      LIVE ends under cap, pinned preamble/footer + newest entries preserved.
+#   4. Rolled blocks land in the LEDGER verbatim, oldest set in original order.
+#   5. --dry-run changes nothing and reports a plan.
+#   6. Zone emptied but pinned sections alone exceed cap → exit 3.
+#   7. --help exits 0 and prints usage; an unknown flag exits nonzero (#701 discipline).
+#   8. More than one marker pair → exit 3, unchanged; curated content between the two
+#      zones is never relocated to the LEDGER (rev0 #868 regression).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SUT="$SCRIPT_DIR/board-roll.sh"
+
+fail=0
+note() { echo "FAIL: $*" >&2; fail=1; }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# builds a LIVE board: pinned preamble + roll zone with N dated entries (newest first),
+# each entry padded to be individually large so the cap math is predictable.
+make_board() {  # $1 file  $2 n_entries  $3 with_markers(1/0)  $4 pad_bytes
+    local f=$1 n=$2 markers=$3 pad=$4 i padtxt
+    padtxt=$(head -c "$pad" < /dev/zero | tr '\0' 'x')
+    {
+        echo "# BOARD — LIVE"
+        echo "> pinned protocol blockquote, never rolled."
+        echo
+        echo "## Curated always-current section (pinned)"
+        echo "- this stays no matter what"
+        echo
+        [[ "$markers" == 1 ]] && echo '<!-- BOARD-ROLL:START -->'
+        # newest first (i=n .. 1); oldest (i=1) ends at the bottom
+        for (( i=n; i>=1; i-- )); do
+            echo "### 2026-07-$(printf '%02d' $i) tick number $i"
+            echo "- detail $i $padtxt"
+            echo
+        done
+        [[ "$markers" == 1 ]] && echo '<!-- BOARD-ROLL:END -->'
+    } > "$f"
+    return 0
+}
+
+# ── 1. under cap → no-op ───────────────────────────────────────────────────────
+L="$WORK/live1.md"; G="$WORK/ledger1.md"; : > "$G"
+make_board "$L" 2 1 10
+before=$(cat "$L")
+if ! out=$(bash "$SUT" --live "$L" --ledger "$G" --cap 100000 2>&1); then
+    note "under-cap should exit 0 (got nonzero): $out"
+fi
+[[ "$(cat "$L")" == "$before" ]] || note "under-cap modified LIVE"
+[[ -s "$G" ]] && note "under-cap wrote to LEDGER"
+
+# ── 2. over cap, no markers → exit 3, unchanged ────────────────────────────────
+L="$WORK/live2.md"; G="$WORK/ledger2.md"; : > "$G"
+make_board "$L" 6 0 400
+before=$(cat "$L")
+set +e; bash "$SUT" --live "$L" --ledger "$G" --cap 800 >/dev/null 2>&1; rc=$?; set -e
+[[ "$rc" -eq 3 ]] || note "no-markers over-cap should exit 3 (got $rc)"
+[[ "$(cat "$L")" == "$before" ]] || note "no-markers run modified LIVE (must never guess)"
+
+# ── 3+4. over cap with markers → rolls oldest, LIVE under cap, LEDGER gets them ─
+L="$WORK/live3.md"; G="$WORK/ledger3.md"; echo "# LEDGER" > "$G"
+make_board "$L" 6 1 400          # 6 entries, each ~>400B
+big=$(wc -c < "$L")
+[[ "$big" -ge 2000 ]] || note "fixture too small to test rolling ($big B)"
+if ! out=$(bash "$SUT" --live "$L" --ledger "$G" --cap 2000 2>&1); then
+    note "marker roll should exit 0 when it can get under cap: $out"
+fi
+after=$(wc -c < "$L")
+[[ "$after" -lt 2000 ]] || note "LIVE still >= cap after roll ($after B)"
+# pinned content survives
+grep -q "Curated always-current section" "$L" || note "roll dropped pinned section"
+grep -q 'BOARD-ROLL:START' "$L" || note "roll dropped START marker"
+grep -q 'BOARD-ROLL:END' "$L"   || note "roll dropped END marker"
+# newest entry (07-06) stays; oldest (07-01) is the first to leave
+grep -q "### 2026-07-06 tick number 6" "$L" || note "roll dropped the newest entry"
+grep -q "### 2026-07-01 tick number 1" "$L" && note "oldest entry not rolled out of LIVE"
+# oldest went to LEDGER
+grep -q "### 2026-07-01 tick number 1" "$G" || note "oldest entry not appended to LEDGER"
+grep -q "board-roll:.*rolled from live3.md" "$G" || note "LEDGER missing provenance separator"
+# a rolled entry must not be duplicated (present in exactly one of LIVE/LEDGER)
+if grep -q "### 2026-07-01 tick number 1" "$L"; then note "rolled entry duplicated in LIVE"; fi
+# LEDGER original content preserved
+grep -q "^# LEDGER" "$G" || note "roll clobbered existing LEDGER content"
+
+# ── 5. --dry-run changes nothing ───────────────────────────────────────────────
+L="$WORK/live5.md"; G="$WORK/ledger5.md"; echo "# LEDGER" > "$G"
+make_board "$L" 6 1 400
+before_l=$(cat "$L"); before_g=$(cat "$G")
+out=$(bash "$SUT" --live "$L" --ledger "$G" --cap 2000 --dry-run 2>&1) || note "dry-run exited nonzero: $out"
+echo "$out" | grep -qi "dry run" || note "dry-run did not announce itself"
+echo "$out" | grep -q "would roll" || note "dry-run did not report a plan"
+[[ "$(cat "$L")" == "$before_l" ]] || note "dry-run modified LIVE"
+[[ "$(cat "$G")" == "$before_g" ]] || note "dry-run modified LEDGER"
+
+# ── 6. zone emptied, pinned alone over cap → exit 3 ────────────────────────────
+# cap 120 is below the pinned preamble+footer size (~180B), so even after rolling
+# every zone entry the LIVE file stays over cap → must report the unsatisfiable case.
+L="$WORK/live6.md"; G="$WORK/ledger6.md"; echo "# LEDGER" > "$G"
+make_board "$L" 3 1 50
+set +e; bash "$SUT" --live "$L" --ledger "$G" --cap 120 >/dev/null 2>&1; rc=$?; set -e
+[[ "$rc" -eq 3 ]] || note "unsatisfiable cap should exit 3 (got $rc)"
+
+# ── 7. help exits 0, unknown flag exits nonzero (#701) ─────────────────────────
+if ! out=$(bash "$SUT" --help 2>&1); then note "--help exited nonzero"; fi
+[[ "$out" == Usage:* ]] || note "--help did not print usage"
+bash "$SUT" -h >/dev/null 2>&1 || note "-h exited nonzero"
+if bash "$SUT" --not-a-real-flag >/dev/null 2>&1; then note "unknown flag was accepted"; fi
+if bash "$SUT" --live "$WORK/live3.md" >/dev/null 2>&1; then note "missing --ledger was accepted"; fi
+
+# ── 8. multiple marker pairs → exit 3, unchanged (no cross-zone relocation) ─────
+# Two separately-marked zones with a curated pinned section BETWEEN them. A naive
+# first-START..last-END span would sweep that curated section (and the intermediate
+# markers) into the LEDGER. board-roll must refuse (exit 3) and touch nothing.
+L="$WORK/live8.md"; G="$WORK/ledger8.md"; echo "# LEDGER" > "$G"
+pad8=$(head -c 300 < /dev/zero | tr '\0' 'x')
+{
+    echo "# BOARD — LIVE"
+    echo "> pinned protocol blockquote"
+    echo
+    echo '<!-- BOARD-ROLL:START -->'
+    echo "### 2026-07-10 zone-A newest"
+    echo "- detail A2 $pad8"
+    echo "### 2026-07-09 zone-A oldest"
+    echo "- detail A1 $pad8"
+    echo '<!-- BOARD-ROLL:END -->'
+    echo
+    echo "## Curated-between-zones (pinned — must never move)"
+    echo "- CANARY-BETWEEN keep me"
+    echo
+    echo '<!-- BOARD-ROLL:START -->'
+    echo "### 2026-07-08 zone-B newest"
+    echo "- detail B2 $pad8"
+    echo "### 2026-07-07 zone-B oldest"
+    echo "- detail B1 $pad8"
+    echo '<!-- BOARD-ROLL:END -->'
+} > "$L"
+before8=$(cat "$L")
+set +e; bash "$SUT" --live "$L" --ledger "$G" --cap 80 >/dev/null 2>&1; rc=$?; set -e
+[[ "$rc" -eq 3 ]] || note "multi-pair board should exit 3 (got $rc)"
+[[ "$(cat "$L")" == "$before8" ]] || note "multi-pair run modified LIVE (must never guess across zones)"
+grep -q "CANARY-BETWEEN keep me" "$L" || note "multi-pair run relocated curated between-zones content"
+grep -q "CANARY-BETWEEN" "$G" && note "curated between-zones content leaked into LEDGER"
+
+if [[ "$fail" -eq 0 ]]; then
+    echo "board-roll regression passed (8 groups)"
+fi
+exit "$fail"

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 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"
+    "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"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/cli.ts

@@ -21,6 +21,8 @@ import { registerRestoreCommand } from './commands/restore.js';
 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';
@@ -78,6 +80,14 @@ Command Groups:
 
 registerLaunchCommands(program);
 
+// ─── lease activation capability probe (hidden; #869 Point-1 C1) ────────
+
+registerLeaseCapabilityProbe(program);
+
+// ─── install-ordering guard (hidden; #869 Point-1 C2) ───────────────────
+
+registerInstallOrderingGuardCommand(program);
+
 // ─── login ──────────────────────────────────────────────────────────────
 
 program

packages/mosaic/src/commands/install-ordering-guard.spec.ts

@@ -0,0 +1,301 @@
+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-');
+  });
+});

packages/mosaic/src/commands/install-ordering-guard.ts

@@ -0,0 +1,327 @@
+/**
+ * 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);
+    });
+}

packages/mosaic/src/commands/launch.ts

@@ -28,6 +28,7 @@ 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;
@@ -806,7 +807,14 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
   process.exit(0); // Unreachable but satisfies never
 }
 
-function defaultLeaseBrokerSocket(env: NodeJS.ProcessEnv = process.env): string {
+/**
+ * Resolve the lease broker's control socket path. Exported (in addition to
+ * being used internally by execLeaseGatedRuntime) so the C1 activation probe
+ * (lease-activation-probe.ts) can perform the same resolution when checking
+ * whether the broker supervisor is reachable — detection only, this never
+ * connects to the socket itself.
+ */
+export function defaultLeaseBrokerSocket(env: NodeJS.ProcessEnv = process.env): string {
   if (env['MOSAIC_LEASE_BROKER_SOCKET']) return env['MOSAIC_LEASE_BROKER_SOCKET'];
   const runtimeDir = env['XDG_RUNTIME_DIR'];
   if (runtimeDir) return join(runtimeDir, 'mosaic-lease', 'broker.sock');
@@ -895,7 +903,12 @@ function delegateToScript(scriptPath: string, args: string[], env?: Record<strin
  * bundled in the @mosaicstack/mosaic npm package (always matches the installed
  * CLI version) over the deployed copy in ~/.config/mosaic/ (may be stale).
  */
-function resolveTool(...segments: string[]): string {
+/**
+ * Exported so the C1 activation probe (lease-activation-probe.ts) can resolve
+ * the same lease-broker launcher/daemon artifacts execLeaseGatedRuntime()
+ * uses, for detection-only supervisor presence checks.
+ */
+export function resolveTool(...segments: string[]): string {
   try {
     const req = createRequire(import.meta.url);
     const mosaicPkg = dirname(req.resolve('@mosaicstack/mosaic/package.json'));
@@ -1225,7 +1238,6 @@ 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',
@@ -1244,4 +1256,67 @@ 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);
 }

packages/mosaic/src/commands/lease-activation-probe.spec.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import {
+  LEASE_ACTIVATION_CAPABILITY,
+  LEASE_CAPABILITY_PROBE_COMMAND,
+  defaultCapabilityProbe,
+  defaultResolveCliEntry,
+  defaultSupervisorProbe,
+  leaseEnforcementActivatable,
+  registerLeaseCapabilityProbe,
+  type LeaseActivationCapability,
+  type SupervisorProbeResult,
+} from './lease-activation-probe.js';
+
+/**
+ * Red-first tests for issue #869 Point-1 C1 — leaseEnforcementActivatable().
+ *
+ * Root cause under test: #828 shipped the lease broker's ENFORCEMENT half
+ * (hooks) and ACTIVATION half (execLeaseGatedRuntime + a running daemon.py
+ * broker) on different channels, and they drifted — the published CLI
+ * tarball lacked the activation half even though it existed in source. The
+ * predicate here must say NO when either half of activation is unavailable,
+ * and only YES when both are genuinely present — never based on "does the
+ * source file exist", but on a real capability signal + real supervisor
+ * detection.
+ */
+
+const compatibleCapability: LeaseActivationCapability = { ...LEASE_ACTIVATION_CAPABILITY };
+const presentSupervisor: SupervisorProbeResult = {
+  supervisorPresent: true,
+  socketPath: '/run/user/1000/mosaic-lease/broker.sock',
+};
+
+describe('leaseEnforcementActivatable', () => {
+  it('is false when the activation capability is absent (null)', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => null,
+      probeSupervisor: () => presentSupervisor,
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when the activation capability name does not match', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => ({
+        name: 'some-other-capability',
+        version: LEASE_ACTIVATION_CAPABILITY.version,
+      }),
+      probeSupervisor: () => presentSupervisor,
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when the activation capability version is incompatible (stale/newer build)', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => ({
+        name: LEASE_ACTIVATION_CAPABILITY.name,
+        version: LEASE_ACTIVATION_CAPABILITY.version + 1,
+      }),
+      probeSupervisor: () => presentSupervisor,
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when the supervisor artifacts (launcher/daemon) are not present', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => compatibleCapability,
+      probeSupervisor: () => ({
+        supervisorPresent: false,
+        socketPath: presentSupervisor.socketPath,
+      }),
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when the supervisor socket path is not resolvable', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => compatibleCapability,
+      probeSupervisor: () => ({ supervisorPresent: true, socketPath: null }),
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when BOTH capability and supervisor are absent', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => null,
+      probeSupervisor: () => ({ supervisorPresent: false, socketPath: null }),
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is true when a compatible capability AND a resolvable supervisor are both present', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => compatibleCapability,
+      probeSupervisor: () => presentSupervisor,
+    });
+    expect(result).toBe(true);
+  });
+
+  it('uses the real default probes when no deps are injected (does not throw)', () => {
+    // No live broker / built CLI is guaranteed in a test environment, so this
+    // only asserts the predicate degrades to a safe boolean rather than
+    // throwing — the fail-closed behavior itself is covered by the injected
+    // cases above.
+    expect(() => leaseEnforcementActivatable()).not.toThrow();
+    expect(typeof leaseEnforcementActivatable()).toBe('boolean');
+  });
+});
+
+describe('defaultCapabilityProbe', () => {
+  it('returns null (fail-closed) when no built CLI artifact is resolvable', () => {
+    // Deterministic regardless of ambient host state (e.g. a host that has
+    // already run `pnpm build`, which would otherwise make this pass or fail
+    // depending on whether dist/cli.js happens to exist) — inject a resolver
+    // pointing at a path that cannot exist, rather than relying on this
+    // checkout being unbuilt. The probe must report "no capability" rather
+    // than fabricate one from source-tree presence — this is the exact
+    // distinction #828's version skew needed: source existing is not the
+    // same as the published artifact advertising the capability.
+    const result = defaultCapabilityProbe({
+      resolveCliEntry: () => '/nonexistent/mosaic-lease-activation-probe-test/cli.js',
+    });
+    expect(result).toBeNull();
+  });
+
+  describe('positive path — injected resolver, isolated scratch dir (never the real dist/)', () => {
+    // A prior version of this test staged the stub cli.js at the package's
+    // REAL resolved dist/ path and relied on afterEach to clean up "only
+    // what it created" — which meant a host with a real pre-built
+    // dist/cli.js (ordinary `pnpm build && pnpm test`) would have its real
+    // ~26KB compiled CLI silently overwritten by an 87-byte stub, with no
+    // restoration of the original content. That is exactly the kind of
+    // build-artifact corruption #869 exists to prevent. This version uses
+    // dependency injection exclusively: defaultCapabilityProbe() is never
+    // called with its default resolver here, so it can never touch the real
+    // package dist/ at all — proven below by asserting that path's
+    // existence is unchanged by the test.
+    it('returns the real {name, version} capability from a stub cli.js in a temp dir, and leaves the real dist/ untouched', () => {
+      const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+      const realDistDir = join(packageRoot, 'dist');
+      const realDistPreexisted = existsSync(realDistDir);
+
+      const scratchDir = mkdtempSync(join(tmpdir(), 'mosaic-lease-capability-probe-'));
+      try {
+        const scratchCliPath = join(scratchDir, 'cli.js');
+        // Minimal stand-in for the built CLI's hidden __lease-capability
+        // subcommand — prints exactly what registerLeaseCapabilityProbe()
+        // wires the real `mosaic __lease-capability` command to print.
+        writeFileSync(
+          scratchCliPath,
+          `process.stdout.write(JSON.stringify(${JSON.stringify(LEASE_ACTIVATION_CAPABILITY)}));\n`,
+        );
+
+        const result = defaultCapabilityProbe({ resolveCliEntry: () => scratchCliPath });
+        expect(result).toEqual(LEASE_ACTIVATION_CAPABILITY);
+
+        // The real package dist/ must be byte-for-byte untouched: this test
+        // never invokes the default resolver, so the path's mere existence
+        // (created or not) must be unchanged by having run this test.
+        expect(existsSync(realDistDir)).toBe(realDistPreexisted);
+      } finally {
+        rmSync(scratchDir, { recursive: true, force: true });
+      }
+    });
+  });
+});
+
+describe('defaultResolveCliEntry', () => {
+  it('resolves the bare "@mosaicstack/mosaic" specifier (the exported "." entry), never the non-exported "./package.json" subpath', () => {
+    // Fully isolated from the real filesystem/package state (no dependency
+    // on whether @mosaicstack/mosaic has been built on this host) via an
+    // injected fake resolver that mirrors Node's real behavior: the "."
+    // export resolves fine, but "./package.json" is NOT in package.json's
+    // `exports` map, so real `require.resolve` throws
+    // ERR_PACKAGE_PATH_NOT_EXPORTED for it. This is genuinely red-first
+    // against the reviewer-found bug: the old implementation resolved the
+    // "./package.json" subpath here, which this fake throws on — the new
+    // implementation must resolve only the bare specifier.
+    const requestedSpecifiers: string[] = [];
+    const fakeResolve = (specifier: string): string => {
+      requestedSpecifiers.push(specifier);
+      if (specifier === '@mosaicstack/mosaic') return '/fake/pkg/dist/index.js';
+      throw new Error(`ERR_PACKAGE_PATH_NOT_EXPORTED: ${specifier}`);
+    };
+
+    const result = defaultResolveCliEntry(fakeResolve);
+
+    expect(result).toBe(join('/fake/pkg/dist', 'cli.js'));
+    expect(requestedSpecifiers).toEqual(['@mosaicstack/mosaic']);
+  });
+});
+
+describe('defaultSupervisorProbe', () => {
+  it('returns a well-shaped result without starting or connecting to anything', () => {
+    const result = defaultSupervisorProbe({});
+    expect(typeof result.supervisorPresent).toBe('boolean');
+    expect(result.socketPath === null || typeof result.socketPath === 'string').toBe(true);
+  });
+
+  it('resolves a socket path from an explicit MOSAIC_LEASE_BROKER_SOCKET override', () => {
+    const result = defaultSupervisorProbe({ MOSAIC_LEASE_BROKER_SOCKET: '/tmp/explicit.sock' });
+    expect(result.socketPath).toBe('/tmp/explicit.sock');
+  });
+});
+
+describe('registerLeaseCapabilityProbe', () => {
+  it('registers a hidden subcommand named __lease-capability', () => {
+    const program = new Command();
+    program.exitOverride();
+    registerLeaseCapabilityProbe(program);
+
+    const registered = program.commands.find((c) => c.name() === LEASE_CAPABILITY_PROBE_COMMAND);
+    expect(registered).toBeDefined();
+    // Commander exposes "hidden" only as help-output suppression (no public
+    // getter) — assert the observable behavior instead of a private field.
+    expect(program.helpInformation()).not.toContain(LEASE_CAPABILITY_PROBE_COMMAND);
+  });
+
+  it('prints the capability constant as JSON when invoked', () => {
+    const program = new Command();
+    program.exitOverride();
+    registerLeaseCapabilityProbe(program);
+
+    let written = '';
+    const originalWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = ((chunk: string) => {
+      written += chunk;
+      return true;
+    }) as typeof process.stdout.write;
+
+    try {
+      program.parse(['node', 'mosaic', LEASE_CAPABILITY_PROBE_COMMAND]);
+    } finally {
+      process.stdout.write = originalWrite;
+    }
+
+    expect(JSON.parse(written)).toEqual(LEASE_ACTIVATION_CAPABILITY);
+  });
+});

packages/mosaic/src/commands/lease-activation-probe.ts

@@ -0,0 +1,232 @@
+/**
+ * Lease-enforcement activation probe (issue #869, Point-1 card C1).
+ *
+ * Root cause this exists to guard against (#828 version skew): the
+ * ENFORCEMENT half of the lease broker (PreToolUse/Stop hooks —
+ * `mutator-gate.py`, `receipt-observer-client.py` — wired via the framework
+ * reseed) and the ACTIVATION half (`execLeaseGatedRuntime()` in `launch.ts`,
+ * which chains the runtime through `launch-runtime.py`, injects
+ * `MOSAIC_LEASE_*`, and requires a running `daemon.py` broker) ship on
+ * different channels. When the published CLI tarball lags behind an
+ * enforcement reseed, the gate correctly fails CLOSED on absent identity —
+ * but every tool call then denies with GATE_UNAVAILABLE. That fail-closed
+ * behavior is intentional and must not change (see the C-REGRESS note in
+ * `runtime_tools_unittest.py`); this module exists so a downstream
+ * install-ordering guard (C2, out of scope here) can refuse to WIRE
+ * enforcement in the first place on a host that cannot ACTIVATE it.
+ *
+ * `leaseEnforcementActivatable()` answers one narrow question: "if
+ * enforcement were wired right now, could activation actually satisfy it?"
+ * It is a real capability probe — not a "does the source file exist" check
+ * — and both of its inputs are injectable so tests can drive every branch
+ * without a live broker or an installed CLI on PATH.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import type { Command } from 'commander';
+import { defaultLeaseBrokerSocket, resolveTool } from './launch.js';
+
+// ─── Capability signal (owned by the activation half) ──────────────────────
+
+/**
+ * Versioned identity for the activation contract `execLeaseGatedRuntime()`
+ * implements. OWNED by the activation half of the lease broker. Bump
+ * `version` only when the activation contract itself changes (env vars
+ * injected, chaining behavior, socket protocol, etc.) — deliberately
+ * independent of the package's npm semver, because #828 happened precisely
+ * because the npm version was NOT bumped even though the shipped artifact
+ * fell out of sync. A build that cannot advertise this exact
+ * `{ name, version }` pair does not implement the contract a caller is
+ * relying on, whatever its package.json claims.
+ */
+export interface LeaseActivationCapability {
+  readonly name: string;
+  readonly version: number;
+}
+
+export const LEASE_ACTIVATION_CAPABILITY: LeaseActivationCapability = {
+  name: 'lease-runtime-activation',
+  version: 1,
+};
+
+/** Hidden CLI probe subcommand name — wired via {@link registerLeaseCapabilityProbe}. */
+export const LEASE_CAPABILITY_PROBE_COMMAND = '__lease-capability';
+
+function capabilityMatches(candidate: LeaseActivationCapability | null): boolean {
+  return (
+    candidate !== null &&
+    candidate.name === LEASE_ACTIVATION_CAPABILITY.name &&
+    candidate.version === LEASE_ACTIVATION_CAPABILITY.version
+  );
+}
+
+/**
+ * Register the hidden `__lease-capability` probe subcommand. Prints the
+ * capability this BUILD advertises as compact JSON to stdout and exits 0.
+ * Deliberately undocumented (hidden from `--help`): it is an internal signal
+ * for {@link defaultCapabilityProbe}, not a user-facing command.
+ */
+export function registerLeaseCapabilityProbe(program: Command): void {
+  program
+    .command(LEASE_CAPABILITY_PROBE_COMMAND, { hidden: true })
+    .description('Internal: print the lease-activation capability this build advertises')
+    .action(() => {
+      process.stdout.write(JSON.stringify(LEASE_ACTIVATION_CAPABILITY));
+    });
+}
+
+/** Injectable Node module resolver — matches `require.resolve`'s signature
+ * narrowly (specifier in, absolute path out, or throws). Defaults to the
+ * real `createRequire(import.meta.url).resolve`. Injectable so tests can
+ * exercise WHICH specifier {@link defaultResolveCliEntry} resolves (the
+ * reviewer-found bug was resolving the wrong one) without depending on
+ * whether `@mosaicstack/mosaic` has actually been built on the test host —
+ * and without ever touching the real package's `dist/` to find out. */
+export type ModuleResolver = (specifier: string) => string;
+
+/**
+ * Resolve the CLI's built entrypoint (`dist/cli.js`). Resolves via the
+ * package's "." export (already present in package.json's `exports` map)
+ * rather than a "./package.json" subpath — the latter is NOT exported, so
+ * `require.resolve('@mosaicstack/mosaic/package.json')` throws
+ * ERR_PACKAGE_PATH_NOT_EXPORTED on every real install. The "." export
+ * resolves to `dist/index.js`; `cli.js` is its sibling in the same built
+ * `dist/` directory (see package.json's `bin.mosaic`).
+ *
+ * Exported standalone (and injectable via {@link CapabilityProbeDeps}) so
+ * tests can exercise this resolution logic in isolation, or point
+ * {@link defaultCapabilityProbe} at a scratch directory instead of ever
+ * touching the real installed package's `dist/` — a test corrupting a real
+ * build artifact is exactly the artifact-integrity failure class this card
+ * exists to prevent (#828).
+ */
+export function defaultResolveCliEntry(
+  resolve: ModuleResolver = createRequire(import.meta.url).resolve,
+): string {
+  const mainEntry = resolve('@mosaicstack/mosaic');
+  return join(dirname(mainEntry), 'cli.js');
+}
+
+/** Injectable inputs for {@link defaultCapabilityProbe}. */
+export interface CapabilityProbeDeps {
+  /** Resolve the CLI entrypoint (`cli.js`) to probe. Defaults to
+   * {@link defaultResolveCliEntry}. Inject to point at an isolated scratch
+   * location in tests — never at the real package's `dist/`. */
+  resolveCliEntry?: () => string;
+}
+
+/**
+ * Real capability lookup. Resolves the installed `@mosaicstack/mosaic`
+ * package's BUILT entrypoint (`dist/cli.js` — the published artifact a user
+ * actually runs, not this TypeScript source file) and executes its hidden
+ * `__lease-capability` probe subcommand out-of-process. A build that lacks
+ * the subcommand, fails to execute, or reports an incompatible
+ * `{ name, version }` is treated as having NO activation capability.
+ *
+ * This is the check that would have caught #828's version skew: the
+ * source-tree activation half existed, but the published tarball's `dist/`
+ * did not carry it, so this probe — reading the actually-resolvable built
+ * artifact rather than trusting source-tree presence — would report null.
+ */
+export function defaultCapabilityProbe(
+  deps: CapabilityProbeDeps = {},
+): LeaseActivationCapability | null {
+  try {
+    const resolveCliEntry = deps.resolveCliEntry ?? defaultResolveCliEntry;
+    const cliEntry = resolveCliEntry();
+    if (!existsSync(cliEntry)) return null;
+
+    const output = execFileSync(process.execPath, [cliEntry, LEASE_CAPABILITY_PROBE_COMMAND], {
+      encoding: 'utf-8',
+      timeout: 2000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+
+    const parsed: unknown = JSON.parse(output);
+    if (
+      typeof parsed !== 'object' ||
+      parsed === null ||
+      typeof (parsed as Record<string, unknown>)['name'] !== 'string' ||
+      typeof (parsed as Record<string, unknown>)['version'] !== 'number'
+    ) {
+      return null;
+    }
+    const candidate = parsed as { name: string; version: number };
+    return { name: candidate.name, version: candidate.version };
+  } catch {
+    return null;
+  }
+}
+
+// ─── Supervisor / socket resolution (detection only) ───────────────────────
+
+/** Detection-only supervisor/socket probe result. Never starts the broker
+ * and never connects to the socket — presence and path resolution only. */
+export interface SupervisorProbeResult {
+  /** The lease-broker supervisor artifacts (launcher + daemon) are present. */
+  readonly supervisorPresent: boolean;
+  /** Resolved broker socket path, or null if it could not be resolved. */
+  readonly socketPath: string | null;
+}
+
+/**
+ * Real supervisor/socket resolution: checks that the lease-broker's launcher
+ * (`launch-runtime.py`) and supervisor (`daemon.py`) artifacts resolve on
+ * disk via the same tool-resolution `execLeaseGatedRuntime()` uses, and that
+ * a broker socket path resolves via the same logic as
+ * `defaultLeaseBrokerSocket()`. Detection only — this never starts the
+ * daemon and never connects to the socket.
+ */
+export function defaultSupervisorProbe(
+  env: NodeJS.ProcessEnv = process.env,
+): SupervisorProbeResult {
+  const launcherPath = resolveTool('lease-broker', 'launch-runtime.py');
+  const daemonPath = resolveTool('lease-broker', 'daemon.py');
+  const supervisorPresent = existsSync(launcherPath) && existsSync(daemonPath);
+
+  let socketPath: string | null = null;
+  try {
+    const resolved = defaultLeaseBrokerSocket(env);
+    socketPath = resolved.trim().length > 0 ? resolved : null;
+  } catch {
+    socketPath = null;
+  }
+
+  return { supervisorPresent, socketPath };
+}
+
+// ─── Predicate ───────────────────────────────────────────────────────────
+
+/** Injectable inputs for {@link leaseEnforcementActivatable}, so tests (and
+ * downstream callers such as the C2 install-ordering guard) can drive every
+ * branch without a live broker or an installed CLI on PATH. */
+export interface ActivationProbeDeps {
+  getCapability?: () => LeaseActivationCapability | null;
+  probeSupervisor?: () => SupervisorProbeResult;
+}
+
+/**
+ * True IFF lease enforcement can actually be ACTIVATED on this host:
+ *
+ *   (a) the resolvable CLI advertises a {@link LeaseActivationCapability}
+ *       compatible with {@link LEASE_ACTIVATION_CAPABILITY}, AND
+ *   (b) the broker supervisor is resolvable — launcher + `daemon.py`
+ *       artifacts present AND a broker socket path resolves.
+ *
+ * Pure/testable: both probes default to the real, side-effect-free lookups
+ * above but can be injected, so this predicate never itself starts a broker
+ * or performs enforcement — it only reports whether activation *could*
+ * satisfy enforcement if wired.
+ */
+export function leaseEnforcementActivatable(deps: ActivationProbeDeps = {}): boolean {
+  const getCapability = deps.getCapability ?? defaultCapabilityProbe;
+  const probeSupervisor = deps.probeSupervisor ?? defaultSupervisorProbe;
+
+  if (!capabilityMatches(getCapability())) return false;
+
+  const supervisor = probeSupervisor();
+  return supervisor.supervisorPresent && supervisor.socketPath !== null;
+}

packages/mosaic/src/commands/lease-doctor-check.spec.ts

@@ -0,0 +1,196 @@
+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');
+  });
+});

packages/mosaic/src/commands/lease-doctor-check.ts

@@ -0,0 +1,210 @@
+/**
+ * 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.',
+  };
+}

packages/mosaic/src/lease-broker/broker-supervisor.spec.ts

@@ -0,0 +1,237 @@
+import { createServer, type Server } from 'node:net';
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  applyBrokerSupervisor,
+  checkBrokerSupervisorHealth,
+  isBrokerSupervisorHealthy,
+  resolveBrokerSupervisorPaths,
+  resolveLeaseBrokerSocketPath,
+  type BrokerSupervisorPaths,
+} from './broker-supervisor.js';
+
+const REAL_FRAMEWORK_ROOT = new URL('../../framework/', import.meta.url).pathname;
+
+const cleanupDirs: string[] = [];
+const cleanupServers: Server[] = [];
+
+async function tempDir(prefix: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), prefix));
+  cleanupDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  for (const server of cleanupServers.splice(0)) {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+  for (const dir of cleanupDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe('resolveLeaseBrokerSocketPath', () => {
+  it('honors an explicit MOSAIC_LEASE_BROKER_SOCKET override', () => {
+    expect(resolveLeaseBrokerSocketPath({ MOSAIC_LEASE_BROKER_SOCKET: '/tmp/explicit.sock' })).toBe(
+      '/tmp/explicit.sock',
+    );
+  });
+
+  it('falls back to $XDG_RUNTIME_DIR/mosaic-lease/broker.sock', () => {
+    expect(resolveLeaseBrokerSocketPath({ XDG_RUNTIME_DIR: '/run/user/1000' })).toBe(
+      join('/run/user/1000', 'mosaic-lease', 'broker.sock'),
+    );
+  });
+
+  it('falls back to /run/user/<uid>/mosaic-lease/broker.sock as a last resort', () => {
+    expect(resolveLeaseBrokerSocketPath({}, 4242)).toBe(
+      join('/run/user', '4242', 'mosaic-lease', 'broker.sock'),
+    );
+  });
+
+  it('prefers the explicit override over XDG_RUNTIME_DIR', () => {
+    expect(
+      resolveLeaseBrokerSocketPath({
+        MOSAIC_LEASE_BROKER_SOCKET: '/explicit.sock',
+        XDG_RUNTIME_DIR: '/run/user/1000',
+      }),
+    ).toBe('/explicit.sock');
+  });
+});
+
+describe('resolveBrokerSupervisorPaths', () => {
+  it('colocates the state file next to the resolved socket', () => {
+    const paths = resolveBrokerSupervisorPaths({
+      mosaicHome: '/home/x/.config/mosaic',
+      frameworkRoot: '/repo/framework',
+      env: { XDG_RUNTIME_DIR: '/run/user/1000' },
+    });
+    expect(paths.socketPath).toBe(join('/run/user/1000', 'mosaic-lease', 'broker.sock'));
+    expect(paths.statePath).toBe(join('/run/user/1000', 'mosaic-lease', 'state.json'));
+  });
+
+  it('targets the systemd --user dir under the given home, not mosaicHome', () => {
+    const paths = resolveBrokerSupervisorPaths({
+      mosaicHome: '/somewhere-else/.config/mosaic',
+      frameworkRoot: '/repo/framework',
+      homeDir: '/home/canary',
+      env: {},
+      uid: 0,
+    });
+    expect(paths.systemdUserDir).toBe(join('/home/canary', '.config', 'systemd', 'user'));
+    expect(paths.unitTargetPath).toBe(
+      join('/home/canary', '.config', 'systemd', 'user', 'mosaic-lease-broker.service'),
+    );
+  });
+
+  it('is a pure function: identical options resolve to identical paths', () => {
+    const options = {
+      mosaicHome: '/h/.config/mosaic',
+      frameworkRoot: '/repo/framework',
+      env: { XDG_RUNTIME_DIR: '/run/user/1000' },
+    };
+    expect(resolveBrokerSupervisorPaths(options)).toEqual(resolveBrokerSupervisorPaths(options));
+  });
+});
+
+describe('applyBrokerSupervisor', () => {
+  async function fakePaths(): Promise<BrokerSupervisorPaths> {
+    const home = await tempDir('mosaic-broker-supervisor-home-');
+    const mosaicHome = join(home, '.config', 'mosaic');
+    const runtimeDir = await tempDir('mosaic-broker-supervisor-runtime-');
+    return resolveBrokerSupervisorPaths({
+      mosaicHome,
+      frameworkRoot: REAL_FRAMEWORK_ROOT,
+      homeDir: home,
+      env: { XDG_RUNTIME_DIR: runtimeDir },
+    });
+  }
+
+  it('renders a unit that references the installed wrapper script and hardens the runtime dir', async () => {
+    const paths = await fakePaths();
+    const unitSource = await readFile(paths.unitSourcePath, 'utf8');
+    expect(unitSource).toContain('ExecStart=');
+    expect(unitSource).toContain('%h/.config/mosaic/tools/lease-broker/start-lease-broker.sh');
+    expect(unitSource).toContain('RuntimeDirectory=mosaic-lease');
+    expect(unitSource).toContain('RuntimeDirectoryMode=0700');
+    expect(unitSource).toContain('Restart=on-failure');
+    expect(unitSource).toContain('WantedBy=default.target');
+    // No ambient environment file preload, matching the other fleet units'
+    // strict-parsing convention.
+    expect(unitSource).not.toMatch(/^Environment(File)?=/m);
+  });
+
+  it('materializes the unit, wrapper script, and daemon sources on first apply', async () => {
+    const paths = await fakePaths();
+
+    const result = await applyBrokerSupervisor(paths);
+
+    expect(result.installedFiles).toContain(paths.unitTargetPath);
+    expect(result.installedFiles).toContain(paths.wrapperTargetPath);
+    for (const target of paths.daemonTargetPaths) {
+      expect(result.installedFiles).toContain(target);
+    }
+
+    const unitTargetContent = await readFile(paths.unitTargetPath, 'utf8');
+    const unitSourceContent = await readFile(paths.unitSourcePath, 'utf8');
+    expect(unitTargetContent).toBe(unitSourceContent);
+
+    const wrapperMode = (await stat(paths.wrapperTargetPath)).mode & 0o777;
+    expect(wrapperMode).toBe(0o755);
+
+    for (const target of paths.daemonTargetPaths) {
+      await expect(stat(target)).resolves.toBeDefined();
+    }
+  });
+
+  it('is idempotent: applying twice reproduces identical files with no error', async () => {
+    const paths = await fakePaths();
+
+    await applyBrokerSupervisor(paths);
+    const firstUnit = await readFile(paths.unitTargetPath, 'utf8');
+    const firstWrapper = await readFile(paths.wrapperTargetPath, 'utf8');
+    const firstWrapperMode = (await stat(paths.wrapperTargetPath)).mode & 0o777;
+
+    await expect(applyBrokerSupervisor(paths)).resolves.toBeDefined();
+
+    const secondUnit = await readFile(paths.unitTargetPath, 'utf8');
+    const secondWrapper = await readFile(paths.wrapperTargetPath, 'utf8');
+    const secondWrapperMode = (await stat(paths.wrapperTargetPath)).mode & 0o777;
+
+    expect(secondUnit).toBe(firstUnit);
+    expect(secondWrapper).toBe(firstWrapper);
+    expect(secondWrapperMode).toBe(firstWrapperMode);
+  });
+
+  it('never touches the real host: only writes under the supplied temp dirs', async () => {
+    const paths = await fakePaths();
+    await applyBrokerSupervisor(paths);
+    expect(paths.systemdUserDir.startsWith(tmpdir())).toBe(true);
+    expect(paths.mosaicHome.startsWith(tmpdir())).toBe(true);
+  });
+});
+
+describe('checkBrokerSupervisorHealth / isBrokerSupervisorHealthy', () => {
+  async function fakeHealthPaths(): Promise<
+    Pick<BrokerSupervisorPaths, 'unitTargetPath' | 'socketPath'>
+  > {
+    const runtimeDir = await tempDir('mosaic-broker-supervisor-health-');
+    await mkdir(join(runtimeDir, 'systemd-user'), { recursive: true });
+    return {
+      unitTargetPath: join(runtimeDir, 'systemd-user', 'mosaic-lease-broker.service'),
+      socketPath: join(runtimeDir, 'broker.sock'),
+    };
+  }
+
+  it('reports unhealthy when neither the unit nor the socket exist', async () => {
+    const paths = await fakeHealthPaths();
+
+    const health = await checkBrokerSupervisorHealth(paths);
+
+    expect(health).toEqual({ unitInstalled: false, socketPresent: false, healthy: false });
+    expect(await isBrokerSupervisorHealthy(paths)).toBe(false);
+  });
+
+  it('reports unhealthy when the unit is installed but no socket is listening', async () => {
+    const paths = await fakeHealthPaths();
+    await writeFile(paths.unitTargetPath, '[Unit]\n');
+
+    const health = await checkBrokerSupervisorHealth(paths);
+
+    expect(health.unitInstalled).toBe(true);
+    expect(health.socketPresent).toBe(false);
+    expect(health.healthy).toBe(false);
+  });
+
+  it('reports healthy=true once a real Unix socket exists at the resolved path, and false again once removed', async () => {
+    const paths = await fakeHealthPaths();
+
+    const server = createServer();
+    cleanupServers.push(server);
+    await new Promise<void>((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(paths.socketPath, resolve);
+    });
+
+    expect(await isBrokerSupervisorHealthy(paths)).toBe(true);
+    const health = await checkBrokerSupervisorHealth(paths);
+    expect(health.socketPresent).toBe(true);
+    expect(health.healthy).toBe(true);
+
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await rm(paths.socketPath, { force: true });
+
+    expect(await isBrokerSupervisorHealthy(paths)).toBe(false);
+  });
+
+  it('does not confuse a stale regular file at the socket path with a live socket', async () => {
+    const paths = await fakeHealthPaths();
+    await writeFile(paths.socketPath, 'not actually a socket');
+
+    expect(await isBrokerSupervisorHealthy(paths)).toBe(false);
+  });
+});

packages/mosaic/src/lease-broker/broker-supervisor.ts

@@ -0,0 +1,223 @@
+/**
+ * Activation-side supervisor for the Mosaic lease broker (issue #869, Point-1
+ * C3). #828 shipped fail-closed enforcement hooks (`mutator-gate.py`,
+ * `receipt-observer-client.py`) with nothing that guaranteed `daemon.py` was
+ * running or that its socket existed before a gated runtime started. This
+ * module:
+ *
+ *  - resolves the broker socket/state paths and the on-disk locations of the
+ *    supervisor artifacts, deterministically and consistently with
+ *    `defaultLeaseBrokerSocket` in `../commands/launch.ts`;
+ *  - idempotently applies (materializes) a systemd `--user` unit plus the
+ *    wrapper script and daemon sources it execs, mirroring the tmux fleet
+ *    unit convention in `framework/systemd/user/`;
+ *  - exposes a health predicate other cards (e.g. the C1 activation probe)
+ *    can call to learn whether a broker supervisor is present and healthy.
+ *
+ * `applyBrokerSupervisor` only writes files under the paths it is given. It
+ * never runs `systemctl`, never starts `daemon.py`, and never touches a real
+ * host's `~/.config` unless the caller explicitly resolves paths there.
+ * Enabling/starting the unit is a separate, later, out-of-scope step.
+ */
+import { chmod, copyFile, mkdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const UNIT_NAME = 'mosaic-lease-broker.service';
+const WRAPPER_SCRIPT_NAME = 'start-lease-broker.sh';
+
+/** Co-located modules `daemon.py` imports at runtime; kept alongside it. */
+const DAEMON_SOURCE_FILE_NAMES = [
+  'daemon.py',
+  'lease_generation.py',
+  'normative_fragments.py',
+  'receipt_challenge.py',
+  'receipt_observer.py',
+] as const;
+
+export interface ResolveBrokerSupervisorPathsOptions {
+  /** `~/.config/mosaic` (or an override) — where installed tool copies live. */
+  mosaicHome: string;
+  /** Root of the checked-out `framework/` directory (canonical file source). */
+  frameworkRoot: string;
+  /** Defaults to `process.env`; pass a fake for tests. */
+  env?: NodeJS.ProcessEnv;
+  /** Defaults to `os.homedir()`; pass a temp dir in tests. */
+  homeDir?: string;
+  /** Defaults to `process.getuid()` (or 0); pass a fake for tests. */
+  uid?: number;
+}
+
+export interface BrokerSupervisorPaths {
+  readonly mosaicHome: string;
+  readonly frameworkRoot: string;
+  readonly systemdUserDir: string;
+  readonly leaseBrokerToolsDir: string;
+  readonly unitSourcePath: string;
+  readonly unitTargetPath: string;
+  readonly wrapperSourcePath: string;
+  readonly wrapperTargetPath: string;
+  readonly daemonSourcePaths: readonly string[];
+  readonly daemonTargetPaths: readonly string[];
+  /**
+   * Resolved with the same precedence as `defaultLeaseBrokerSocket` in
+   * `../commands/launch.ts`: an explicit `MOSAIC_LEASE_BROKER_SOCKET`, else
+   * `$XDG_RUNTIME_DIR/mosaic-lease/broker.sock`, else
+   * `/run/user/<uid>/mosaic-lease/broker.sock`.
+   */
+  readonly socketPath: string;
+  /** Colocated next to the socket, matching the broker's own generation-file convention. */
+  readonly statePath: string;
+}
+
+/**
+ * Resolve the lease broker socket path alone, with the same precedence as
+ * `defaultLeaseBrokerSocket` in `../commands/launch.ts`. Exported so callers
+ * (and tests) can assert the two stay in agreement without importing the CLI
+ * command module.
+ */
+export function resolveLeaseBrokerSocketPath(
+  env: NodeJS.ProcessEnv = process.env,
+  uid: number = typeof process.getuid === 'function' ? process.getuid() : 0,
+): string {
+  const explicit = env['MOSAIC_LEASE_BROKER_SOCKET'];
+  if (explicit) return explicit;
+  const runtimeDir = env['XDG_RUNTIME_DIR'];
+  if (runtimeDir) return join(runtimeDir, 'mosaic-lease', 'broker.sock');
+  return join('/run/user', String(uid), 'mosaic-lease', 'broker.sock');
+}
+
+/** Resolve every path the supervisor apply/health functions need, deterministically. */
+export function resolveBrokerSupervisorPaths(
+  options: ResolveBrokerSupervisorPathsOptions,
+): BrokerSupervisorPaths {
+  const { mosaicHome, frameworkRoot } = options;
+  const env = options.env ?? process.env;
+  const homeDir = options.homeDir ?? homedir();
+  const systemdUserDir = join(homeDir, '.config', 'systemd', 'user');
+  const leaseBrokerToolsDir = join(mosaicHome, 'tools', 'lease-broker');
+  const frameworkLeaseBrokerDir = join(frameworkRoot, 'tools', 'lease-broker');
+  const socketPath = resolveLeaseBrokerSocketPath(env, options.uid);
+  const statePath = join(dirname(socketPath), 'state.json');
+
+  return {
+    mosaicHome,
+    frameworkRoot,
+    systemdUserDir,
+    leaseBrokerToolsDir,
+    unitSourcePath: join(frameworkRoot, 'systemd', 'user', UNIT_NAME),
+    unitTargetPath: join(systemdUserDir, UNIT_NAME),
+    wrapperSourcePath: join(frameworkLeaseBrokerDir, WRAPPER_SCRIPT_NAME),
+    wrapperTargetPath: join(leaseBrokerToolsDir, WRAPPER_SCRIPT_NAME),
+    daemonSourcePaths: DAEMON_SOURCE_FILE_NAMES.map((name) => join(frameworkLeaseBrokerDir, name)),
+    daemonTargetPaths: DAEMON_SOURCE_FILE_NAMES.map((name) => join(leaseBrokerToolsDir, name)),
+    socketPath,
+    statePath,
+  };
+}
+
+export interface ApplyBrokerSupervisorResult {
+  readonly installedFiles: readonly string[];
+}
+
+/**
+ * Idempotently materialize the supervisor unit, its wrapper script, and the
+ * daemon sources it execs. Safe to call on every reseed: every write is a
+ * deterministic overwrite of the same target path from the same source, so a
+ * second call reproduces identical bytes/modes and never errors.
+ *
+ * Never runs `systemctl`; the caller decides separately whether/when to
+ * `daemon-reload`/`enable`/`start` the installed unit.
+ */
+export async function applyBrokerSupervisor(
+  paths: BrokerSupervisorPaths,
+): Promise<ApplyBrokerSupervisorResult> {
+  await mkdir(paths.leaseBrokerToolsDir, { recursive: true });
+  await mkdir(paths.systemdUserDir, { recursive: true });
+
+  const installedFiles: string[] = [];
+
+  for (let index = 0; index < paths.daemonSourcePaths.length; index += 1) {
+    const source = paths.daemonSourcePaths[index];
+    const target = paths.daemonTargetPaths[index];
+    if (source === undefined || target === undefined) continue;
+    await copyFile(source, target);
+    await chmod(target, 0o644);
+    installedFiles.push(target);
+  }
+
+  await copyFile(paths.wrapperSourcePath, paths.wrapperTargetPath);
+  await chmod(paths.wrapperTargetPath, 0o755);
+  installedFiles.push(paths.wrapperTargetPath);
+
+  await copyFile(paths.unitSourcePath, paths.unitTargetPath);
+  await chmod(paths.unitTargetPath, 0o644);
+  installedFiles.push(paths.unitTargetPath);
+
+  return { installedFiles };
+}
+
+export interface BrokerSupervisorHealth {
+  /** Whether the systemd unit file has been materialized at its target path. */
+  readonly unitInstalled: boolean;
+  /** Whether a Unix domain socket currently exists at the resolved socket path. */
+  readonly socketPresent: boolean;
+  /**
+   * The signal other cards (e.g. C1's activation probe) should treat as
+   * "a broker supervisor is present and healthy". Presence of a live socket
+   * is the authoritative signal: a gated runtime can only ever succeed by
+   * connecting to it, so this is what fail-closed callers must check.
+   */
+  readonly healthy: boolean;
+}
+
+/**
+ * Report the supervisor's on-disk/health signals. Never throws for an
+ * absent unit or socket — both simply report `false`; unexpected filesystem
+ * errors (permission issues, etc.) still propagate.
+ */
+export async function checkBrokerSupervisorHealth(
+  paths: Pick<BrokerSupervisorPaths, 'unitTargetPath' | 'socketPath'>,
+): Promise<BrokerSupervisorHealth> {
+  const [unitInstalled, socketPresent] = await Promise.all([
+    pathExists(paths.unitTargetPath),
+    isUnixSocket(paths.socketPath),
+  ]);
+  return { unitInstalled, socketPresent, healthy: socketPresent };
+}
+
+/** Convenience boolean form of {@link checkBrokerSupervisorHealth} for simple call sites. */
+export async function isBrokerSupervisorHealthy(
+  paths: Pick<BrokerSupervisorPaths, 'unitTargetPath' | 'socketPath'>,
+): Promise<boolean> {
+  return (await checkBrokerSupervisorHealth(paths)).healthy;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isEnoent(error)) return false;
+    throw error;
+  }
+}
+
+async function isUnixSocket(path: string): Promise<boolean> {
+  try {
+    const info = await stat(path);
+    return info.isSocket();
+  } catch (error) {
+    if (isEnoent(error)) return false;
+    throw error;
+  }
+}
+
+function isEnoent(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error as NodeJS.ErrnoException).code === 'ENOENT'
+  );
+}

packages/mosaic/src/mutator-gate/fail-closed-regression.spec.ts

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+/**
+ * C-REGRESS (issue #869, Point-1) — proves the fail-closed gate is untouched
+ * by the C1 activation probe added alongside this test.
+ *
+ * `mutator-gate.py`'s fail-closed-on-absent-identity behavior is INTENTIONAL
+ * and TEST-LOCKED: #869 C1 gates the WIRING decision for enforcement (via
+ * `leaseEnforcementActivatable()`), it does not — and must not — touch the
+ * gate's own runtime denial behavior. This spec runs the two test-locked
+ * cases from `runtime_tools_unittest.py` directly (rather than merely
+ * re-asserting the same logic in TypeScript) so a regression in the actual
+ * Python gate is caught here too, not just documented in prose.
+ */
+
+const MUTATOR_GATE_DIR = new URL('.', import.meta.url).pathname;
+const UNITTEST_FILE = join(MUTATOR_GATE_DIR, 'runtime_tools_unittest.py');
+
+const LOCKED_TEST_CASES = [
+  'ExecutableEntrypointTest.test_gate_entrypoint_denies_when_identity_environment_is_absent',
+  'MutatorGateTest.test_environment_generation_and_request_failures_deny',
+] as const;
+
+describe('mutator-gate fail-closed behavior (C-REGRESS, unchanged by #869 C1)', () => {
+  it.each(LOCKED_TEST_CASES)('%s still passes', (testCase) => {
+    const result = spawnSync('python3', ['-m', 'unittest', `${moduleName()}.${testCase}`, '-v'], {
+      cwd: MUTATOR_GATE_DIR,
+      encoding: 'utf-8',
+    });
+
+    expect(result.status, `stderr:\n${result.stderr}`).toBe(0);
+  });
+});
+
+function moduleName(): string {
+  // runtime_tools_unittest.py, addressed as a bare module name for `python3 -m unittest`.
+  return UNITTEST_FILE.split('/').pop()!.replace(/\.py$/, '');
+}

packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts

@@ -47,6 +47,22 @@ 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[] = [];
 
@@ -184,6 +200,7 @@ 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,
     },
   });
 }
@@ -743,6 +760,7 @@ describe('whole mutator-class lease gate', () => {
           ...process.env,
           MOSAIC_LEASE_BROKER_SOCKET: socket,
           MOSAIC_RUNTIME_GENERATION: '1',
+          MOSAIC_LEASE_VERSION_PROBE_COMMAND: leaseCapabilityProbeStub,
         },
       },
     );
@@ -761,6 +779,7 @@ 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,
         },
       },
     );
@@ -878,6 +897,7 @@ 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({

packages/mosaic/src/mutator-gate/runtime_tools_unittest.py

@@ -39,6 +39,18 @@ 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)
@@ -95,6 +107,7 @@ class LaunchRuntimeTest(unittest.TestCase):
             request=request,
             execute=execute,
             initialize_generation=initialize_generation,
+            probe_activation_capability=matching_activation_probe,
         )
 
         self.assertEqual(result, 0)
@@ -127,6 +140,7 @@ 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(
@@ -153,6 +167,7 @@ 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"]))
@@ -188,6 +203,7 @@ 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, [])
@@ -203,6 +219,7 @@ class LaunchRuntimeTest(unittest.TestCase):
                     initialize_generation=lambda *_args: (_ for _ in ()).throw(
                         OSError("unsafe state")
                     ),
+                    probe_activation_capability=matching_activation_probe,
                 ),
                 1,
             )
@@ -220,6 +237,7 @@ 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,
                 )
@@ -233,6 +251,7 @@ 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,
             )

packages/mosaic/src/mutator-gate/version_coupling_unittest.py

@@ -0,0 +1,287 @@
+#!/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()

packages/mosaic/src/stages/finalize.ts

@@ -13,22 +13,37 @@ 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)) {
+  if (!existsSync(script)) return undefined;
-    try {
+  try {
-      spawnSync('bash', [script], {
+    const result = spawnSync('bash', [script], {
-        timeout: 30000,
+      timeout: 30000,
-        stdio: 'pipe',
+      stdio: 'pipe',
-        env: {
+      encoding: 'utf-8',
-          ...process.env,
+      env: {
-          ...(skipClaudeHooks ? { MOSAIC_SKIP_CLAUDE_HOOKS: '1' } : {}),
+        ...process.env,
-        },
+        ...(skipClaudeHooks ? { MOSAIC_SKIP_CLAUDE_HOOKS: '1' } : {}),
-      });
+      },
-    } catch {
+    });
-      // Non-fatal: wizard continues
+    if (result.status !== 0) {
+      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 {
@@ -201,7 +216,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;
-  linkRuntimeAssets(state.mosaicHome, skipClaudeHooks);
+  const linkWarning = linkRuntimeAssets(state.mosaicHome, skipClaudeHooks);
 
   // 4. Sync skills (only installs the user-selected subset)
   let skillsResult: SyncSkillsResult = { success: true, installedCount: 0 };
@@ -236,6 +251,10 @@ 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);