chore: prettier --write on tools/orchestrator/README.md (pre-existing drift)

Unrelated to the per-agent-identity feature in this branch. The repo's
format:check gate (which the pre-push hook runs across the whole tree) was
already failing against origin/main on this file before this branch existed;
fixing it here only because it otherwise blocks pushing this PR. No content
change — table alignment/spacing only.

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

packages/mosaic/framework/install.sh

@@ -639,6 +639,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"
 

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

@@ -1,22 +0,0 @@
-[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/git/README.md

@@ -7,3 +7,64 @@ These scripts provide host-aware GitHub and Gitea issue, pull-request, milestone
 A successful provider write command—or a wrapper message based only on that command's exit code—is **not** durable review provenance. Review comments count as durable provenance only after the wrapper reads the created provider record back and verifies that it belongs to the intended repository and pull request and contains the exact submitted body (or verifies the provider-returned record ID).
 
 `pr-review.sh` therefore fails closed when a Gitea comment cannot be written, its created comment ID cannot be identified, or provider read-back does not match. It reports comment success only after that read-back verification passes.
+
+## 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/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/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/lease-broker/start-lease-broker.sh

@@ -1,31 +0,0 @@
-#!/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/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 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-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

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

@@ -1,237 +0,0 @@
-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

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