fix(fleet): activate the lease broker at install/start, place units through symlinks safely, refuse doomed launches (#1292)

Wall 6: no documented path ever enabled or started the shipped
mosaic-lease-broker.service — every gated runtime died ~4s in at lease
registration while fleet start reported rc0, and a broker not in the
reconciler plan could not be reported as drifted.

Activation lands in the control plane, not the launcher:

- fleet install places ALL FOUR units through placeUnitFile — a placement
  helper that unlinks any by-path-enable symlink at the destination
  BEFORE copying (Node copyFile follows the link and overwrites the SEED
  template; measured on a throwaway systemd user instance 2026-08-17,
  with both cp and fs.copyFile), removes a stale wants-symlink pointing
  outside the active dir (readlink — readFile returns the target's
  content, not the link path), then copies and daemon-reloads. The same
  measurement showed systemctl enable <name> does NOT rewrite an existing
  by-path wants-symlink — reconciliation must be explicit. Idempotent:
  second install on by-path residue converges to the identical state.
  Until now the copy block named three units and omitted the broker, and
  the residue set / copy set were disjoint only by accident (fomo-lin
  survived copy-through because its one symlink was the one unit not
  copied); adding the broker made them intersect on first run. See the
  SET-INDEPENDENCE note on the helper before adding a fifth unit.
- enableFleetUnits enables the broker first, alongside the holder.
- fleet start / reconciler start the broker BEFORE any holder/agent
  lifecycle effect, then RE-CHECK the socket (not unit state) and exit
  nonzero with a named code if it did not appear. Re-probed on every
  invocation — a RemainAfterExit=yes dead-looking-active unit can never
  make retry look like repair (the sticky-retry check).
- The reconciler plan carries broker {unitInstalled, socketPresent} as a
  first-class member; the socket is the signal (enabled-but-dead units
  report socketPresent=false).
- start-agent-session.sh preflights the broker socket BEFORE any tmux
  effect (moved ahead of the ownership probe): absent -> exit 75
  (EX_TEMPFAIL), named refusal with socket path and remedy, no doomed
  pane. The agent@ unit is Type=oneshot with no Restart=, so the message
  survives instead of looping. The preflight detects and refuses; it
  never starts the broker.
- mosaic doctor's lease check names one convention-neutral remedy:
  'mosaic fleet install (it reconciles either enable convention)' —
  written from the measurement; teaching a manual systemctl line could
  leave a host with competing wants-symlinks.

Tests: fleet-place-unit.spec.ts (8: clean-host negative control,
by-path residue -> seed bytes AND mtime unchanged [the finding-2 check],
wants-residue cleared, idempotence single + double-install convergence);
fleet.spec.ts broker-first enable ordering, refused start emits no
holder/agent calls, second-start re-probe; reconciler broker plan member
(enabled-but-dead shape) + broker-before-agent ordering in both command
and apply paths; test-agent-session-broker-preflight.sh (CI-fit: fake
tmux, real unix socket at a short /tmp path — AF_UNIX caps at 108 bytes,
hermetic env; absent -> exit 75 + no tmux session, live socket passes,
explicit env wins, --stop not fenced). 1563/1563 vitest, lint, root
build 25/25, root typecheck 45/45.

Sabotage controls: placement unlink removed -> exactly the seed-integrity
test reddens (1/8); socket re-check disabled -> exactly the two preflight
specs redden; shell preflight removed -> the bash suite reddens (6 FAIL
assertions, rc=1). All restored byte-identically (sha256-verified), all
green again.

Test 6 (greenfield 1124, seat alive 2min + second fleet start) runs on
sandbox after daphne's baseline, coordinated with fred.

Note: the preflight uses exit 75 measured against the unit's Restart=
policy (oneshot, none) — no restart loop.

packages/mosaic/framework/tools/fleet/start-agent-session.sh

@@ -233,8 +233,36 @@ assert_owned_tmux_server() {
     fail "tmux server ownership or environment validation failed"
 }
 
-# Validate exact server ownership before querying, cleaning, or creating any
-# managed session. An unmanaged or contaminated named socket is never repaired.
+# Lease-broker socket preflight (#1292). The gated runtime (`mosaic yolo …` →
+# launch-runtime.py) registers with the broker or dies ~4 seconds in, with the
+# diagnostic invisible because tmux destroys the dead pane. This check runs
+# BEFORE any tmux effect — including the ownership probe below — so a host
+# without a broker produces a named, surviving refusal instead of a doomed
+# pane. Exit 75 (EX_TEMPFAIL), distinct from 64 (bad projection) and 69 (host
+# not ready for other reasons); the agent@ unit is Type=oneshot with no
+# Restart=, so the failed unit keeps its message instead of looping. Socket
+# resolution matches launch.ts's defaultLeaseBrokerSocket precedence exactly.
+# This preflight DETECTS and REFUSES — it never starts the broker (activation
+# belongs to the fleet control plane; a component that both detects and fixes
+# cannot be used to measure whether the fix worked).
+broker_socket_path() {
+  if [ -n "${MOSAIC_LEASE_BROKER_SOCKET:-}" ]; then
+    printf '%s\n' "$MOSAIC_LEASE_BROKER_SOCKET"
+    return 0
+  fi
+  local runtime_dir="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+  printf '%s\n' "${runtime_dir}/mosaic-lease/broker.sock"
+}
+
+if [ "$MODE" = "launch" ]; then
+  _broker_socket=$(broker_socket_path)
+  if [ ! -S "$_broker_socket" ]; then
+    echo "[fleet] FAIL_LAUNCH broker-absent: lease broker socket ${_broker_socket} missing; runtime launch denied (#1292)." >&2
+    echo "[fleet] remedy: systemctl --user enable --now mosaic-lease-broker.service  (or reinstall via: mosaic fleet install)" >&2
+    exit 75
+  fi
+fi
+
 assert_owned_tmux_server
 
 if [ "$MODE" = interaction ]; then

packages/mosaic/framework/tools/fleet/test-agent-session-broker-preflight.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+# CI-fit regression suite for the #1292 lease-broker socket preflight in
+# start-agent-session.sh.
+#
+# WHY THIS SUITE IS CI-FIT WHERE test-start-agent-session.sh IS NOT (#1017/#1270
+# context): that older suite's precondition is "the host does not have the pi
+# binary", which a CI image that ships pi violates — its guard correctly
+# refuses to report a pass there, so it is excluded from the chain. THIS suite
+# controls its own preconditions instead of inheriting them from the host: a
+# fake tmux on PATH, a fake mosaic on PATH, a real unix socket created in a
+# tmpdir, a hermetic env (env -i, fake HOME, GIT_CONFIG_GLOBAL severed). It
+# never depends on what the host has installed, so a green here means the same
+# thing on every host. Anyone adding cases: keep that property — no case may
+# depend on host state.
+#
+# The failure this suite is written down to catch (#1292): a seat launched on a
+# host with no lease broker dies ~4 seconds in at registration, with the
+# diagnostic invisible because tmux destroys the dead pane. The preflight runs
+# BEFORE any tmux effect and refuses with a NAMED code (exit 75, EX_TEMPFAIL)
+# so the message survives. The agent@ unit is Type=oneshot with no Restart=,
+# so a failed unit keeps its output instead of looping.
+#
+# Cases:
+#   1. absent socket -> exit 75, message names broker-absent + socket path +
+#      remedy, and NO tmux session was ever created (the doomed-pane half).
+#   2. present socket (real unix socket in tmpdir) -> proceeds PAST the
+#      preflight (the suite then stops at the next precondition, proving the
+#      preflight was not the refusal).
+#   3. explicit MOSAIC_LEASE_BROKER_SOCKET wins over XDG_RUNTIME_DIR default.
+#   4. --stop mode does NOT require the broker (teardown must not be fenced on
+#      a component whose absence is exactly what teardown may follow).
+#
+# Sabotage control, run by the developer (not in-suite): remove the preflight
+# block from start-agent-session.sh, re-run — case 1 fails (a tmux session is
+# created / exit is not 75), cases 2-4 still pass; restore byte-identically.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/agent-session-broker-preflight}"
+FAKE_HOME="$WORK_DIR/home"
+BIN_DIR="$WORK_DIR/bin"
+ENV_DIR="$WORK_DIR/env"
+SOCK_DIR="$WORK_DIR/sockets"
+LOG_FILE="$WORK_DIR/tmux-calls.log"
+
+rm -rf "$WORK_DIR"
+# The script asserts a managed directory tree under MOSAIC_HOME: mosaic/,
+# mosaic/fleet/, mosaic/fleet/agents/ — private (0700/0750-style) modes, no
+# symlinks — plus a per-agent env projection. Build the full tree the launcher
+# expects so the suite reaches the BROKER preflight rather than dying at
+# environment validation.
+mkdir -p "$FAKE_HOME/.config/mosaic/fleet/agents" "$BIN_DIR" "$SOCK_DIR"
+chmod 700 "$FAKE_HOME/.config/mosaic" "$FAKE_HOME/.config/mosaic/fleet/agents"
+chmod 750 "$FAKE_HOME/.config/mosaic/fleet"
+cat > "$FAKE_HOME/.config/mosaic/fleet/agents/preflight-test.env.generated" <<'ENVEOF'
+MOSAIC_AGENT_NAME=preflight-test
+MOSAIC_AGENT_CLASS=worker
+MOSAIC_AGENT_RUNTIME=pi
+MOSAIC_AGENT_MODEL=
+MOSAIC_AGENT_REASONING=
+MOSAIC_AGENT_TOOL_POLICY=code
+MOSAIC_AGENT_WORKDIR=/tmp
+MOSAIC_TMUX_SOCKET=mosaic-fleet
+ENVEOF
+chmod 600 "$FAKE_HOME/.config/mosaic/fleet/agents/preflight-test.env.generated"
+
+# ─── Fake tmux: records every invocation; new-session marks the marker. ────
+: > "$LOG_FILE"
+cat > "$BIN_DIR/tmux" <<SH
+#!/usr/bin/env bash
+printf 'tmux %s\n' "\$*" >> "$LOG_FILE"
+if [[ "\$*" == *new-session* ]]; then
+  echo "TMUX-NEW-SESSION-INVOKED" >> "$LOG_FILE"
+fi
+exit 0
+SH
+chmod +x "$BIN_DIR/tmux"
+
+# ─── Fake mosaic/pi binaries so the script proceeds past its own lookups. ───
+for bin in mosaic pi claude; do
+  printf '#!/usr/bin/env bash\nexit 0\n' > "$BIN_DIR/$bin"
+  chmod +x "$BIN_DIR/$bin"
+done
+
+# ─── Minimal launch environment the script expects. ────────────────────────
+# (Enough for the preflight to be reached; later stages will still fail in
+# case 2 — that is expected and asserted.)
+run_session_script() {
+  local mode="$1"; shift
+  (
+    cd "$WORK_DIR"
+    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:/usr/bin:/bin" \
+      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+      MOSAIC_HOME="$FAKE_HOME/.config/mosaic" \
+      AGENT_NAME=preflight-test \
+      "$@" \
+      bash "$SCRIPT_DIR/start-agent-session.sh" $mode preflight-test
+  )
+}
+
+fail=0
+assert() {
+  local desc="$1" expected="$2" actual="$3"
+  if [[ "$expected" != "$actual" ]]; then
+    echo "FAIL: $desc — expected '$expected', got '$actual'" >&2
+    fail=1
+  fi
+}
+assert_contains() {
+  local desc="$1" haystack="$2" needle="$3"
+  [[ "$haystack" == *"$needle"* ]] || { echo "FAIL: $desc — missing '$needle' in: $haystack" >&2; fail=1; }
+}
+assert_not_contains() {
+  local desc="$1" haystack="$2" needle="$3"
+  if [[ "$haystack" == *"$needle"* ]]; then
+    echo "FAIL: $desc — must not contain '$needle'" >&2
+    fail=1
+  fi
+  return 0
+}
+
+# ─── 1. Absent socket → named refusal, NO tmux session. ────────────────────
+: > "$LOG_FILE"
+stderr_file="$WORK_DIR/stderr-1.tmp"
+set +e
+out=$(run_session_script "" MOSAIC_LEASE_BROKER_SOCKET="$SOCK_DIR/absent.sock" 2>"$stderr_file")
+rc=$?
+set -e
+assert "absent socket exit code" "75" "$rc"
+err=$(cat "$stderr_file")
+assert_contains "absent socket names the failure" "$err" "FAIL_LAUNCH broker-absent"
+assert_contains "absent socket names the socket path" "$err" "$SOCK_DIR/absent.sock"
+assert_contains "absent socket names a remedy" "$err" "mosaic fleet install"
+log1=$(cat "$LOG_FILE")
+assert_not_contains "absent socket must not create a tmux session" "$log1" "TMUX-NEW-SESSION-INVOKED"
+
+# ─── 2. Present socket → passes the preflight. ─────────────────────────────
+# Expected: ownership/env checks AFTER the preflight may refuse (fixture is
+# minimal by design); the assertion is only that the refusal is NOT
+# broker-absent and the exit is NOT 75.
+# Create a REAL unix socket: a detached python holder binds it and stays alive
+# for the duration (bash cannot create sockets; a foreground python would
+# close the socket on exit and -S on a closed-but-unlinked path fails). Written
+# as a script file + setsid nohup so no job-control/heredoc interaction with
+# set -e can silently kill the suite.
+# AF_UNIX binds cap at 108 path bytes; the suite's workdir exceeds that, so
+# the live socket lives at a SHORT path under /tmp (unique per run, cleaned
+# with the suite). The preflight takes its socket path explicitly, so this
+# stays fully controlled.
+LIVE_SOCK=$(mktemp -u /tmp/mosaic-preflight-XXXXXX.sock)
+trap 'rm -f "$LIVE_SOCK"' EXIT
+rm -f "$SOCK_DIR/live.sock" "$LIVE_SOCK"
+cat > "$SOCK_DIR/holder.py" <<'PY'
+import socket, sys, time
+path = sys.argv[1]
+s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+s.bind(path)
+s.listen(1)
+time.sleep(120)
+PY
+python3 "$SOCK_DIR/holder.py" "$LIVE_SOCK" >/dev/null 2>"$SOCK_DIR/holder.err" &
+HOLDER_PID=$!
+# Wait for the socket object to exist (bind is near-instant, but do not race it).
+for _ in $(seq 1 50); do
+  [ -S "$LIVE_SOCK" ] && break
+  sleep 0.1
+done
+if [ ! -S "$LIVE_SOCK" ]; then
+  echo "FAIL: could not create live socket fixture (holder pid $HOLDER_PID)" >&2
+  ps -p "$HOLDER_PID" -o pid,stat,cmd --no-headers >&2 || echo "(holder exited)" >&2
+  cat "$SOCK_DIR/holder.err" >&2 || true
+  exit 1
+fi
+: > "$LOG_FILE"
+set +e
+out=$(run_session_script "" MOSAIC_LEASE_BROKER_SOCKET="$LIVE_SOCK" 2>"$WORK_DIR/stderr-2.tmp")
+rc=$?
+set -e
+# The preflight PASSED if the failure (whatever later stage refused) is NOT
+# the broker refusal, and tmux was reached or a later precondition named
+# something else.
+err2=$(cat "$WORK_DIR/stderr-2.tmp")
+assert_not_contains "live socket must not refuse broker-absent" "$err2" "broker-absent"
+if [[ "$rc" == "75" ]]; then
+  echo "FAIL: live socket — preflight still refused (exit 75) with a live socket" >&2
+  fail=1
+fi
+
+# ─── 3. Explicit socket env wins over XDG default. ─────────────────────────
+set +e
+out=$(run_session_script "" XDG_RUNTIME_DIR="$SOCK_DIR/no-runtime-here" MOSAIC_LEASE_BROKER_SOCKET="$SOCK_DIR/absent2.sock" 2>"$WORK_DIR/stderr-3.tmp")
+rc=$?
+set -e
+assert "explicit env wins (exit 75)" "75" "$rc"
+assert_contains "explicit env path named" "$(cat "$WORK_DIR/stderr-3.tmp")" "$SOCK_DIR/absent2.sock"
+
+# ─── 4. --stop is not fenced on the broker. ────────────────────────────────
+: > "$LOG_FILE"
+set +e
+out=$(run_session_script "--stop" MOSAIC_LEASE_BROKER_SOCKET="$SOCK_DIR/absent3.sock" 2>"$WORK_DIR/stderr-4.tmp")
+rc=$?
+set -e
+err4=$(cat "$WORK_DIR/stderr-4.tmp")
+assert_not_contains "--stop must not refuse broker-absent" "$err4" "broker-absent"
+if [[ "$rc" == "75" ]]; then
+  echo "FAIL: --stop — exit 75 means teardown was fenced on the broker" >&2
+  fail=1
+fi
+
+kill "$HOLDER_PID" 2>/dev/null || true
+
+if [[ "$fail" -eq 0 ]]; then
+  echo "start-agent-session lease-broker preflight regression passed"
+fi
+exit "$fail"

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

@@ -30,7 +30,7 @@ The Gitea API token is **never passed on a curl command line.** An `Authorizatio
 
 ### `--login` override
 
-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 (as of #1280, `pr-create.sh`, `pr-merge.sh` and `issue-create.sh` accept it too, and it wins over `MOSAIC_GIT_IDENTITY` everywhere). 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>`.
+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.
 
@@ -58,36 +58,6 @@ 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.
 
-### Identity-first principal resolution in the wrappers (#1280)
-
-`resolve_gitea_principal()` (detect-platform.sh) gives the write wrappers —
-`pr-create.sh`, `pr-merge.sh`, `pr-review.sh`, `issue-create.sh`, `issue-comment.sh` —
-ONE precedence for choosing the acting principal:
-
-1. an explicit `--login <name>` (now accepted by all five; operator intent beats
-   environment), then
-2. the per-agent identity above (`MOSAIC_GIT_IDENTITY` env / worktree
-   `mosaic.gitIdentity`) when a per-slot token exists — the wrapper then writes via the
-   REST API with that identity's token and never consults `tea`, so the tea login list
-   cannot shadow the requested principal, then
-3. the tea login list — the LAST resort, never the first, because it enumerates
-   whatever logins the host happens to hold and knows nothing about which seat is
-   calling.
-
-A requested identity whose per-slot token is absent, or a `--login` whose token cannot
-resolve host-bound, **fails loud** (nonzero, naming the identity/login and the expected
-slot) instead of silently writing under whatever account `tea` has configured — that
-silent fallthrough is defect #1280 (reviews, comments, merges, PRs and issues filed
-under the wrong account). `pr-merge.sh --dry-run` reports the principal the merge would
-act as, resolved exactly as the real merge resolves it. ⚠ A **workstation-global**
-`mosaic.gitIdentity` shadows every seat on that host (a fresh clone with no local value
-resolves the global one) — set it per-worktree, not with `--global`.
-
-The resolver is covered by `test-gitea-principal-resolution.sh`; the happy-path
-ordering (identity arm REACHED, not sitting behind a tea failure) by
-`test-pr-create-identity-first.sh`; merge credential binding by
-`test-pr-merge-principal-resolution.sh`.
-
 ### Enabling it for a clone
 
 The framework installer syncs `git-credential-mosaic` to

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

@@ -497,32 +497,6 @@ get_gitea_url_for_host() {
     return 1
 }
 
-# Map a Gitea host to the per-agent identity-token slot PREFIX ("gitea-usc" /
-# "gitea-mosaicstack") used by identity-first principal resolution
-# (MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity; #1280). Returns 1 for
-# hosts with no per-slot scheme — callers treat that as "identity does not
-# bind here" and fall through to existing behavior, never as an error. This is
-# the single source of truth for the slot layout: get_gitea_token and
-# resolve_gitea_principal both derive their slot paths from here, so the two
-# resolutions can never disagree about where an identity's credential lives.
-gitea_identity_slot_prefix() {
-    case "$1" in
-        git.uscllc.com)      echo "gitea-usc" ;;
-        git.mosaicstack.dev) echo "gitea-mosaicstack" ;;
-        *) return 1 ;;
-    esac
-}
-
-# Resolve the per-slot token FILE PATH for an identity on a host. Prints the
-# absolute path on success; returns 1 (no output) when the host has no per-slot
-# scheme. Prints a PATH only — never a token value.
-gitea_identity_token_slot() {
-    local identity="$1" host="$2" prefix
-    [[ -n "$identity" ]] || return 1
-    prefix=$(gitea_identity_slot_prefix "$host") || return 1
-    printf '%s\n' "$HOME/.config/mosaic/secrets/gitea-tokens/${prefix}-${identity}.token"
-}
-
 # Resolve a Gitea API token for the given host.
 # Priority: Mosaic credential loader → GITEA_TOKEN env → ~/.git-credentials
 get_gitea_token() {
@@ -543,8 +517,13 @@ get_gitea_token() {
         _ident_src="git config mosaic.gitIdentity"
     fi
     if [[ -n "$_ident" ]]; then
-        local _idtok=""
-        if _idtok="$(gitea_identity_token_slot "$_ident" "$host" 2>/dev/null)"; 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
@@ -1486,81 +1465,6 @@ raise SystemExit(1)
 PY
 }
 
-# resolve_gitea_principal — identity-first acting-principal resolution shared by
-# the git wrappers (#1280). The defect this fixes: wrappers resolved their
-# acting principal from tea's login list FIRST, and that list enumerates
-# whatever logins happen to be configured on the host — it knows nothing about
-# which seat is calling — so a wrapper invoked with MOSAIC_GIT_IDENTITY=fargo
-# still wrote under whichever account tea held (mos-dt-0), and the correct
-# identity-aware code sat behind arms that only ran when the tea path failed.
-# Precedence here is the contract:
-#   1. an explicit login override ($1, the wrapper's --login) — operator intent
-#      beats environment;
-#   2. MOSAIC_GIT_IDENTITY env, else per-worktree `git config mosaic.gitIdentity`
-#      (mirroring get_gitea_token exactly, so resolver and token resolution can
-#      never disagree) — binds only on hosts with a per-slot token scheme;
-#   3. the tea login list — LAST resort, never the first.
-#
-# Prints exactly one line, three tab-separated fields (machine-readable for
-# wrapper dispatch and tests):
-#   mode        "login" | "identity" | "default"
-#   principal   login name (login) | identity name (identity) | tea login or "" (default)
-#   source      "tea-login:<name>" | "identity-slot:<path>" | "tea-default" | "host-credential"
-#
-# Fails LOUD (nonzero, empty stdout, stderr diagnostic) when an explicit
-# override cannot be honored — a refusal is a good day; silently falling
-# through to whoever tea has configured is the exact defect this resolves:
-#   - login mode: no host-bound token for that tea login. The existence check
-#     runs the same tea-config lookup tea itself uses; the token VALUE is
-#     discarded (never printed, never used).
-#   - identity mode: no per-slot token file for that identity on a recognized
-#     host — the diagnostic names the identity, its source, and the expected
-#     slot path. An identity requested on a host with NO per-slot scheme does
-#     not bind (matching get_gitea_token's containment) and falls to default.
-#
-# NEVER prints a token value — principal names and slot paths only.
-# $1 = explicit login override ("" when absent), $2 = host (default: the
-# origin remote's host).
-resolve_gitea_principal() {
-    local login_override="${1:-}" host="${2:-}" ident ident_src slot login
-    [[ -n "$host" ]] || { host=$(get_remote_host) || return 1; }
-
-    if [[ -n "$login_override" ]]; then
-        get_gitea_token_for_login "$login_override" "$host" >/dev/null || {
-            echo "Error: --login '$login_override' has no host-matched token on host '$host' (tea config lookup); refusing to fall back to any other principal (#1280 identity-first resolution)." >&2
-            return 1
-        }
-        printf 'login\t%s\ttea-login:%s\n' "$login_override" "$login_override"
-        return 0
-    fi
-
-    ident="${MOSAIC_GIT_IDENTITY:-}"
-    ident_src="MOSAIC_GIT_IDENTITY"
-    if [[ -z "$ident" ]]; then
-        ident="$(git config --get mosaic.gitIdentity 2>/dev/null || true)"
-        ident_src="git config mosaic.gitIdentity"
-    fi
-    if [[ -n "$ident" ]] && slot="$(gitea_identity_token_slot "$ident" "$host" 2>/dev/null)"; then
-        if [[ -r "$slot" ]]; then
-            printf 'identity\t%s\tidentity-slot:%s\n' "$ident" "$slot"
-            return 0
-        fi
-        echo "Error: git identity '$ident' requested (via $ident_src) for host '$host', but no per-slot token at $slot (#1280 identity-first resolution)." >&2
-        echo "       Refusing to fall back to the tea login list or shared credentials. Provision the per-slot token, or unset the identity." >&2
-        return 1
-    fi
-
-    # No override requested: tea's login list is the LAST resort. Absence is
-    # not an error here — callers fall back to the host credential, exactly as
-    # they did before this resolver existed (preserved behavior).
-    if login=$(get_gitea_login_for_host "$host" 2>/dev/null); then
-        printf 'default\t%s\ttea-default\n' "$login"
-    else
-        printf 'default\t\thost-credential\n'
-    fi
-    return 0
-}
-
 # Resolve HTTPS basic auth credentials for a Gitea host from ~/.git-credentials.
 # Prints "username:password" for direct curl -u consumption. Callers must not log it.
 get_gitea_basic_auth() {

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -76,36 +76,27 @@ fi
 detect_platform >/dev/null
 
 # Resolve and cache the Gitea REST endpoint + token for the current remote,
-# bound to a SPECIFIC acting principal ($1) selected identity-first (#1280):
-# an explicit --login wins, else MOSAIC_GIT_IDENTITY / git config
-# mosaic.gitIdentity binds the per-slot credential, else the tea login list
-# (last resort). Populates GITEA_API_ROOT (…/api/v1), GITEA_API_BASE
-# (…/api/v1/repos/<slug>), and GITEA_API_TOKEN.
+# bound to a SPECIFIC login identity ($1). Populates GITEA_API_ROOT (…/api/v1),
+# GITEA_API_BASE (…/api/v1/repos/<slug>), and GITEA_API_TOKEN.
 #
-# The token is resolved for the EFFECTIVE principal so that the single
-# credential used for the write ALSO drives the /user identity read and the
-# read-back — write token and read-back token are the same identity by
-# construction (this is the credential-ordering fix: a --login override is no
-# longer written under one credential and verified under a different default
-# one). When $2 is "identity" the principal ($1) is a requested git identity:
-# the token MUST resolve from that identity's per-slot token (get_gitea_token's
-# identity arm), failing closed rather than borrowing the tea default login —
-# the tea login list must never shadow a requested identity (#1280). When $2
-# is "explicit" the principal came from a caller-supplied --login: that exact
-# login's token MUST resolve, and we FAIL CLOSED rather than silently
-# downgrading the write to the host default identity. Otherwise the best-effort
-# default path applies (per-login token, else the host-scoped credential).
-# Returns non-zero (clear stderr) on any resolution failure.
+# The token is resolved for the EFFECTIVE login (the --login override when
+# given, otherwise the detected default) so that the single credential used for
+# the write ALSO drives the /user identity read and the read-back — write token
+# and read-back token are the same identity by construction (this is the
+# credential-ordering fix: a --login override is no longer written under one
+# credential and verified under a different default one). Falls back to the
+# host-scoped credential ONLY when NO --login override was supplied (the
+# best-effort default path). When $2 is "explicit" the login came from a
+# caller-supplied --login: that exact login's token MUST resolve, and we FAIL
+# CLOSED rather than silently downgrading the write to the host default
+# identity — otherwise a caller relying on a dedicated per-role credential would
+# be told the write succeeded as requested while it was attributed to the shared
+# default. Returns non-zero (clear stderr) on any resolution failure.
 gitea_resolve_api_for_login() {
     local effective_login="$1" override_explicit="${2:-}" host configured_url repo
 
     host=$(get_remote_host)
-    if [[ "$override_explicit" == "identity" ]]; then
-        GITEA_API_TOKEN=$(get_gitea_token "$host") || {
-            echo "Error: could not resolve the per-slot token for requested git identity '$effective_login' on host '$host'; refusing to fall back to the tea login list or shared credentials (comment write/read-back, #1280)." >&2
-            return 1
-        }
-    elif [[ -n "$override_explicit" ]]; then
+    if [[ -n "$override_explicit" ]]; then
         GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login" "$host") || {
             echo "Error: could not resolve a host-matched Gitea token for --login '$effective_login' on host '$host'; refusing to fall back to the host default identity or a cross-host credential (comment write/read-back)" >&2
             return 1
@@ -327,31 +318,23 @@ if [[ "$PLATFORM" == "github" ]]; then
     gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
     echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    # Resolve the acting principal identity-first (#1280): an explicit --login
-    # wins; otherwise MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity
-    # selects the principal when a per-slot token exists (fail-loud when it
-    # does not); the tea login list is the LAST resort — it knows nothing about
-    # which seat is calling, so resolving from it first wrote under whichever
-    # account tea had configured (the #1280 family).
-    principal_host=$(get_remote_host)
-    if ! principal_resolved="$(resolve_gitea_principal "$LOGIN_OVERRIDE" "$principal_host")"; then
-        # resolve_gitea_principal already printed the fail-loud diagnostic.
-        exit 1
-    fi
-    PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-    PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
+    # Resolve the login this comment should be attributed to: the --login
+    # override when given, otherwise the detected default for this repo's host.
+    # A --login override always wins. Otherwise name this repo host's login only
+    # as a best effort: the login name merely selects a per-login token, and
+    # gitea_resolve_api_for_login falls back to the host credential
+    # (get_gitea_token) when no tea login is named, so the default credential
+    # still resolves even when the host tea has no matching login entry.
+    EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+    [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login 2>/dev/null || true)
 
-    # Bind the REST endpoint + token to the resolved principal, then derive the
+    # Bind the REST endpoint + token to the effective login, then derive the
     # acting identity from that SAME credential (GET /user). The write below and
     # its read-back both use this credential, so the write is verified against
-    # the identity that actually performed it.
-    if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
-        gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
-    elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
-        gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
-    else
-        gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
-    fi
+    # the identity that actually performed it. Passing "explicit" when --login
+    # was supplied forbids the host-default fallback: an unresolvable explicit
+    # override fails closed instead of writing under the default identity.
+    gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
     ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
 
     comment_id=$(gitea_create_comment_verified "$ISSUE_NUMBER" "$COMMENT" "$ACTING_LOGIN") || {

packages/mosaic/framework/tools/git/issue-create.sh

@@ -1,15 +1,6 @@
 #!/bin/bash
 # issue-create.sh - Create issues on Gitea or GitHub
-# Usage: issue-create.sh -t "Title" [-b "Body"] [-l "label1,label2"] [-m "milestone"] [--login <name>]
-#
-# Acting principal is resolved identity-first (#1280): an explicit --login
-# wins; otherwise MOSAIC_GIT_IDENTITY / per-worktree git config
-# mosaic.gitIdentity selects the principal when a per-slot token exists (and
-# the wrapper then creates the issue through the REST API with that identity's
-# token — tea is never invoked, so the tea login list cannot shadow the
-# requested principal); the tea login list is the LAST resort. A requested
-# identity with no per-slot token fails LOUD rather than writing under
-# whichever account tea happens to hold.
+# Usage: issue-create.sh -t "Title" [-b "Body"] [-l "label1,label2"] [-m "milestone"]
 
 set -e
 
@@ -25,14 +16,6 @@ INTERACTIVE=false
 
 # get_remote_host and get_gitea_token are provided by detect-platform.sh
 
-# Acting-principal mode set in the Gitea branch below (from
-# resolve_gitea_principal): "login" when --login was given, "identity" when a
-# git identity bound, "default" otherwise. PRINCIPAL_MODE=login makes the API
-# arm resolve the --login principal's token too, so an explicit --login keeps
-# winning even on the tea-FAILURE fallback arm.
-PRINCIPAL_MODE=""
-PRINCIPAL_NAME=""
-
 gitea_issue_create_api() {
     local host repo token url payload
     host=$(get_remote_host) || {
@@ -43,19 +26,10 @@ gitea_issue_create_api() {
         echo "Error: could not determine repo owner/name for API fallback" >&2
         return 1
     }
-    if [[ "$PRINCIPAL_MODE" == "login" ]]; then
-        token=$(get_gitea_token_for_login "$PRINCIPAL_NAME" "$host") || {
-            echo "Error: could not resolve a host-matched Gitea token for --login '$PRINCIPAL_NAME' on host '$host' (API path)" >&2
-            return 1
-        }
-    else
-        # Identity-first when MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity
-        # is set (per-slot token, fail-loud on absence); shared default otherwise.
-        token=$(get_gitea_token "$host") || {
-            echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
-            return 1
-        }
-    fi
+    token=$(get_gitea_token "$host") || {
+        echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
+        return 1
+    }
 
     if [[ -n "$LABELS" || -n "$MILESTONE" ]]; then
         echo "Warning: API fallback currently applies title/body only; labels/milestone require authenticated tea setup." >&2
@@ -93,7 +67,6 @@ Options:
     -b, --body BODY         Issue body/description
     -l, --labels LABELS     Comma-separated labels (e.g., "bug,feature")
     -m, --milestone NAME    Milestone name to assign
-        --login NAME        Act as this Gitea tea login (wins over MOSAIC_GIT_IDENTITY)
     -i, --interactive       Prompt for missing issue fields
     -h, --help              Show this help message
 
@@ -124,10 +97,6 @@ while [[ $# -gt 0 ]]; do
             MILESTONE="$2"
             shift 2
             ;;
-        --login)
-            LOGIN_OVERRIDE="$2"
-            shift 2
-            ;;
         -i|--interactive)
             INTERACTIVE=true
             shift
@@ -165,37 +134,13 @@ case "$PLATFORM" in
         "${CMD[@]}"
         ;;
     gitea)
-        # Resolve the acting principal identity-first (#1280). The tea login
-        # list is the LAST resort: it knows nothing about which seat is calling,
-        # and a login resolved from it first is what attributed issues to the
-        # wrong account even when MOSAIC_GIT_IDENTITY was set.
-        principal_host=$(get_remote_host 2>/dev/null || true)
-        if ! principal_resolved="$(resolve_gitea_principal "${LOGIN_OVERRIDE:-}" "$principal_host")"; then
-            # resolve_gitea_principal already printed the fail-loud diagnostic.
-            exit 1
-        fi
-        PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-        PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
-
-        if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
-            # HAPPY PATH for a requested identity: create through the REST API
-            # with the per-slot token and never invoke tea — the identity arm
-            # must be REACHED, not sit behind a tea failure (#1280).
-            gitea_issue_create_api
-            exit $?
-        fi
-
         if command -v tea >/dev/null 2>&1; then
             REPO_SLUG=$(get_repo_slug)
-            if [[ "$PRINCIPAL_MODE" == "login" ]]; then
-                GITEA_LOGIN_NAME="$PRINCIPAL_NAME"
-            else
-                GITEA_LOGIN_NAME=$(get_gitea_login) || {
-                    echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
-                    gitea_issue_create_api
-                    exit $?
-                }
-            fi
+            GITEA_LOGIN_NAME=$(get_gitea_login) || {
+                echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
+                gitea_issue_create_api
+                exit $?
+            }
             if ! get_gitea_authenticated_user "$GITEA_LOGIN_NAME" >/dev/null; then
                 echo "Warning: Tea authenticated-user validation failed (possible stale user/login); trying Gitea API fallback..." >&2
                 gitea_issue_create_api

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

@@ -1,15 +1,6 @@
 #!/bin/bash
 # pr-create.sh - Create pull requests on Gitea or GitHub
-# Usage: pr-create.sh -t "Title" [-b "Body"] [-B base] [-H head] [-l "labels"] [-m "milestone"] [--login <name>]
-#
-# Acting principal is resolved identity-first (#1280): an explicit --login
-# wins; otherwise MOSAIC_GIT_IDENTITY / per-worktree git config
-# mosaic.gitIdentity selects the principal when a per-slot token exists (and
-# the wrapper then creates the PR through the REST API with that identity's
-# token — tea is never invoked, so the tea login list cannot shadow the
-# requested principal); the tea login list is the LAST resort. A requested
-# identity with no per-slot token fails LOUD rather than writing under
-# whichever account tea happens to hold.
+# Usage: pr-create.sh -t "Title" [-b "Body"] [-B base] [-H head] [-l "labels"] [-m "milestone"]
 
 set -e
 
@@ -28,15 +19,6 @@ ISSUE=""
 
 # get_remote_host, get_gitea_token, get_repo_info, and get_gitea_repo_args are provided by detect-platform.sh
 
-# Acting-principal mode set in the Gitea branch below (from
-# resolve_gitea_principal): "login" when --login was given, "identity" when a
-# git identity bound, "default" otherwise. PRINCIPAL_MODE=login makes the API
-# arm resolve the --login principal's token too, so an explicit --login keeps
-# winning even on the tea-FAILURE fallback arm (otherwise the fallback would
-# silently re-resolve to the environment identity or shared credential).
-PRINCIPAL_MODE=""
-PRINCIPAL_NAME=""
-
 gitea_pr_create_api() {
     local host repo token url payload
     host=$(get_remote_host) || {
@@ -47,19 +29,10 @@ gitea_pr_create_api() {
         echo "Error: could not determine repo owner/name for API fallback" >&2
         return 1
     }
-    if [[ "$PRINCIPAL_MODE" == "login" ]]; then
-        token=$(get_gitea_token_for_login "$PRINCIPAL_NAME" "$host") || {
-            echo "Error: could not resolve a host-matched Gitea token for --login '$PRINCIPAL_NAME' on host '$host' (API path)" >&2
-            return 1
-        }
-    else
-        # Identity-first when MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity
-        # is set (per-slot token, fail-loud on absence); shared default otherwise.
-        token=$(get_gitea_token "$host") || {
-            echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
-            return 1
-        }
-    fi
+    token=$(get_gitea_token "$host") || {
+        echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
+        return 1
+    }
 
     if [[ -n "$LABELS" || -n "$MILESTONE" || "$DRAFT" == true ]]; then
         echo "Warning: API fallback applies title/body/head/base only; labels/milestone/draft require authenticated tea setup." >&2
@@ -103,7 +76,6 @@ Options:
     -H, --head BRANCH       Head branch with changes (default: current branch)
     -l, --labels LABELS     Comma-separated labels
     -m, --milestone NAME    Milestone name
-        --login NAME        Act as this Gitea tea login (wins over MOSAIC_GIT_IDENTITY)
     -i, --issue NUMBER      Link to issue (auto-generates title if not provided)
     -d, --draft             Create as draft PR
     -h, --help              Show this help message
@@ -144,10 +116,6 @@ while [[ $# -gt 0 ]]; do
             MILESTONE="$2"
             shift 2
             ;;
-        --login)
-            LOGIN_OVERRIDE="$2"
-            shift 2
-            ;;
         -i|--issue)
             ISSUE="$2"
             shift 2
@@ -206,41 +174,15 @@ case "$PLATFORM" in
         "${CMD[@]}"
         ;;
     gitea)
-        # Resolve the acting principal identity-first (#1280). The tea login
-        # list is the LAST resort: it knows nothing about which seat is calling,
-        # and a login resolved from it first is what attributed PRs to the wrong
-        # account even when MOSAIC_GIT_IDENTITY was set.
-        principal_host=$(get_remote_host 2>/dev/null || true)
-        if ! principal_resolved="$(resolve_gitea_principal "${LOGIN_OVERRIDE:-}" "$principal_host")"; then
-            # resolve_gitea_principal already printed the fail-loud diagnostic.
-            exit 1
-        fi
-        PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-        PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
-
-        if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
-            # HAPPY PATH for a requested identity: the per-slot token IS the
-            # credential, so create through the REST API directly and never
-            # invoke tea — the identity arm must be REACHED, not sit behind a
-            # tea failure (#1280). Fail-loud on a missing slot already happened
-            # in resolve_gitea_principal.
-            gitea_pr_create_api
-            exit $?
-        fi
-
         # tea pull create syntax. Always pass --repo because tea repo inference
         # is unreliable in Mosaic worktrees/profile shells. Use arrays instead
         # of eval so markdown backticks/body content are not shell-executed.
         REPO_SLUG=$(get_repo_slug)
-        if [[ "$PRINCIPAL_MODE" == "login" ]]; then
-            GITEA_LOGIN_NAME="$PRINCIPAL_NAME"
-        else
-            GITEA_LOGIN_NAME=$(get_gitea_login) || {
-                echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
-                gitea_pr_create_api
-                exit $?
-            }
-        fi
+        GITEA_LOGIN_NAME=$(get_gitea_login) || {
+            echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
+            gitea_pr_create_api
+            exit $?
+        }
         if ! get_gitea_authenticated_user "$GITEA_LOGIN_NAME" >/dev/null; then
             echo "Warning: Tea authenticated-user validation failed (possible stale user/login); trying Gitea API fallback..." >&2
             gitea_pr_create_api

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

@@ -1,13 +1,6 @@
 #!/bin/bash
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
-# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL] [--login <name>]
-#
-# Acting principal is resolved identity-first (#1280): an explicit --login
-# wins; otherwise MOSAIC_GIT_IDENTITY / per-worktree git config
-# mosaic.gitIdentity selects the credential (per-slot token, fail-loud when
-# absent); the shared host credential is the last resort. The merge is
-# performed with the resolved credential only — never a cross-principal
-# fallback (an HTTP 401 from the identity-bound token is a hard stop).
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL]
 
 set -euo pipefail
 
@@ -23,7 +16,6 @@ DRY_RUN=false
 EXPECT_HEAD=""
 CO_AUTHOR_TRAILERS=false
 ESCALATE_TO=""
-LOGIN_OVERRIDE=""
 
 usage() {
     cat <<EOF
@@ -39,7 +31,6 @@ Options:
         --expect-head SHA   Refuse unless the PR head matches this full commit SHA
         --co-author-trailers Build verified trailers from linked PR commit authors
         --escalate-to NAME  Named principal for an unresolved-author BLOCK
-        --login NAME        Act as this Gitea tea login (wins over MOSAIC_GIT_IDENTITY)
     -h, --help              Show this help message
 
 Examples:
@@ -48,7 +39,6 @@ Examples:
     $(basename "$0") -n 42 -d                 # Squash merge and delete branch
     $(basename "$0") -n 42 --expect-head 0123456789abcdef0123456789abcdef01234567
     $(basename "$0") -n 42 --co-author-trailers --escalate-to tl-mosaic
-    $(basename "$0") -n 42 --login fred-ms    # Merge under the fred-ms tea login
 EOF
     exit "${1:-1}"
 }
@@ -92,14 +82,6 @@ while [[ $# -gt 0 ]]; do
             ESCALATE_TO="$2"
             shift 2
             ;;
-        --login|-l)
-            if [[ $# -lt 2 ]]; then
-                echo "Error: --login requires one tea login name." >&2
-                exit 1
-            fi
-            LOGIN_OVERRIDE="$2"
-            shift 2
-            ;;
         -h|--help)
             usage 0
             ;;
@@ -590,22 +572,9 @@ PY
 merge_gitea_with_api() {
     local host="$1" token attempt_rc
 
-    # Identity-first principal resolution (#1280): an explicit --login wins
-    # over MOSAIC_GIT_IDENTITY (operator intent beats environment); otherwise
-    # get_gitea_token resolves the identity's per-slot token when an identity
-    # is requested (fail-loud when absent) and the shared host credential only
-    # when no identity is set. No cross-principal fallback: whatever resolves
-    # here is the ONLY credential the merge is attempted with.
-    if [[ -n "$LOGIN_OVERRIDE" ]]; then
-        if ! token=$(get_gitea_token_for_login "$LOGIN_OVERRIDE" "$host"); then
-            echo "Error: --login '$LOGIN_OVERRIDE' has no host-matched token on host '$host'; refusing to merge under any other principal (#1280 identity-first resolution)." >&2
-            return 1
-        fi
-    else
-        if ! token=$(get_gitea_token "$host"); then
-            echo "Error: Could not resolve the required Gitea token; refusing merge without changing principals." >&2
-            return 1
-        fi
+    if ! token=$(get_gitea_token "$host"); then
+        echo "Error: Could not resolve the required Gitea token; refusing merge without changing principals." >&2
+        return 1
     fi
     if [[ -z "$token" ]]; then
         echo "Error: Required Gitea token resolved empty; refusing merge without changing principals." >&2
@@ -633,25 +602,10 @@ if [[ "$DRY_RUN" == true ]]; then
             echo "Error: Cannot determine host from origin remote URL" >&2
             exit 1
         }
-        # Report the acting principal the merge WOULD use, resolved the same
-        # way the real merge resolves it (#1280) — a dry run that names a
-        # different principal than the merge would act as is a lie.
-        if ! principal_resolved="$(resolve_gitea_principal "$LOGIN_OVERRIDE" "$HOST")"; then
-            # Fail-loud diagnostic already printed (unresolvable --login or a
-            # requested identity with no per-slot token).
-            exit 1
-        fi
-        DRY_PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-        DRY_PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
-        case "$DRY_PRINCIPAL_MODE" in
-            login)    DRY_PRINCIPAL_DESC="tea login '$DRY_PRINCIPAL_NAME'" ;;
-            identity) DRY_PRINCIPAL_DESC="git identity '$DRY_PRINCIPAL_NAME' (per-slot credential)" ;;
-            *)        DRY_PRINCIPAL_DESC="default host credential" ;;
-        esac
         if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
-            echo "Dry run: would verify PR commit authors and merge PR #$PR_NUMBER on $HOST as $DRY_PRINCIPAL_DESC with authenticated Gitea API message fields (base=$BASE_BRANCH, method=squash)."
+            echo "Dry run: would verify PR commit authors and merge PR #$PR_NUMBER on $HOST with authenticated Gitea API message fields (base=$BASE_BRANCH, method=squash)."
         else
-            echo "Dry run: would merge PR #$PR_NUMBER on $HOST as $DRY_PRINCIPAL_DESC with the authenticated exact-head Gitea API path (base=$BASE_BRANCH, method=squash)."
+            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with the authenticated exact-head Gitea API path (base=$BASE_BRANCH, method=squash)."
         fi
     else
         echo "Dry run: would merge PR #$PR_NUMBER on $PLATFORM (base=$BASE_BRANCH, method=squash)."

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

@@ -76,7 +76,7 @@ while [[ $# -gt 0 ]]; do
             echo "  -n, --number   PR number (required)"
             echo "  -a, --action   Review action: approve, request-changes, comment (required)"
             echo "  -c, --comment  Review comment (required for request-changes)"
-            echo "  -l, --login    Override the detected Gitea tea login (all actions; wins over MOSAIC_GIT_IDENTITY)"
+            echo "  -l, --login    Override the detected Gitea tea login (approve/request-changes only)"
             echo "  -r, --repo     Explicit owner/repo slug (skips git-remote slug inference)"
             echo "  -H, --host     Explicit Gitea host (skips remote-host inference)"
             echo "  -h, --help     Show this help"
@@ -346,14 +346,7 @@ gitea_resolve_api_for_login() {
     else
         host=$(get_remote_host)
     fi
-    if [[ "$override_explicit" == "identity" ]]; then
-        # Requested git identity (#1280): the per-slot token MUST resolve via
-        # get_gitea_token's identity arm; never borrow the tea default login.
-        GITEA_API_TOKEN=$(get_gitea_token "$host") || {
-            echo "Error: could not resolve the per-slot token for requested git identity '$effective_login' on host '$host'; refusing to fall back to the tea login list or shared credentials (review write/read-back, #1280)." >&2
-            return 1
-        }
-    elif [[ -n "$override_explicit" ]]; then
+    if [[ -n "$override_explicit" ]]; then
         GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login" "$host") || {
             echo "Error: could not resolve a host-matched Gitea token for --login '$effective_login' on host '$host'; refusing to fall back to the host default identity or a cross-host credential (review write/read-back)" >&2
             return 1
@@ -683,32 +676,29 @@ if [[ "$PLATFORM" == "github" ]]; then
             ;;
     esac
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    # Resolve the acting principal ONCE for every action, identity-first
-    # (#1280): an explicit --login wins; otherwise MOSAIC_GIT_IDENTITY /
-    # per-worktree git config mosaic.gitIdentity selects the principal when a
-    # per-slot token exists (fail-loud when it does not); the tea login list is
-    # the LAST resort — it enumerates whatever logins this host happens to hold
-    # and knows nothing about which seat is calling, so resolving from it first
-    # wrote under whichever account tea had configured (the #1280 family).
-    principal_host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
-    if ! principal_resolved="$(resolve_gitea_principal "$LOGIN_OVERRIDE" "$principal_host")"; then
-        # resolve_gitea_principal already printed the fail-loud diagnostic.
-        exit 1
-    fi
-    PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-    PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
     case $ACTION in
         approve)
-            # Identity-first principal resolution (#1280): PRINCIPAL_MODE /
-            # PRINCIPAL_NAME were resolved once above from --login >
-            # MOSAIC_GIT_IDENTITY / git config > tea login list (last resort).
-            if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
-            elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
-            else
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
-            fi
+            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
+            # below re-derives the real host from HOST_OVERRIDE/remote independently and
+            # is authoritative). Prefer an explicit -H/--host; otherwise best-effort
+            # git-remote inference, tolerating its ABSENCE (a bare `get_remote_host` here
+            # under `set -e`, with no origin and no -H, previously killed the script
+            # SILENTLY — exit 1, zero output — even though -r/-H are exactly the flags
+            # that support running with no usable origin at all).
+            host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
+            # A --login override always wins. Otherwise name this host's login
+            # only as a best effort: the login name merely selects a per-login
+            # token, and gitea_resolve_api_for_login falls back to the host
+            # credential (get_gitea_token) when no tea login is named — so a host
+            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the default credential to resolve. The single resolved token is
+            # then used for the write, the /user identity, and the read-back.
+            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
+            # Bind the REST endpoint + token to the effective login, then derive
+            # the acting identity from that SAME credential so the review submit
+            # and its read-back verify against the identity that performed them.
+            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
             ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
             # The review body (if any) travels with the review itself in the REST
@@ -725,16 +715,24 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 echo "Error: Comment required for request-changes"
                 exit 1
             fi
-            # Identity-first principal resolution (#1280): PRINCIPAL_MODE /
-            # PRINCIPAL_NAME were resolved once above from --login >
-            # MOSAIC_GIT_IDENTITY / git config > tea login list (last resort).
-            if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
-            elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
-            else
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
-            fi
+            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
+            # below re-derives the real host from HOST_OVERRIDE/remote independently and
+            # is authoritative). Prefer an explicit -H/--host; otherwise best-effort
+            # git-remote inference, tolerating its ABSENCE (a bare `get_remote_host` here
+            # under `set -e`, with no origin and no -H, previously killed the script
+            # SILENTLY — exit 1, zero output — even though -r/-H are exactly the flags
+            # that support running with no usable origin at all).
+            host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
+            # A --login override always wins. Otherwise name this host's login
+            # only as a best effort: the login name merely selects a per-login
+            # token, and gitea_resolve_api_for_login falls back to the host
+            # credential (get_gitea_token) when no tea login is named — so a host
+            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the default credential to resolve. The single resolved token is
+            # then used for the write, the /user identity, and the read-back.
+            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
+            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
             ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
             review_id=$(gitea_submit_review_verified "$PR_NUMBER" "REQUEST_CHANGES" "$COMMENT" "$ACTING_LOGIN" "$head_sha") || {
@@ -748,16 +746,24 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 echo "Error: Comment required"
                 exit 1
             fi
-            # Identity-first principal resolution (#1280): PRINCIPAL_MODE /
-            # PRINCIPAL_NAME were resolved once above from --login >
-            # MOSAIC_GIT_IDENTITY / git config > tea login list (last resort).
-            if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
-            elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
-            else
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
-            fi
+            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
+            # below re-derives the real host from HOST_OVERRIDE/remote independently and
+            # is authoritative). Prefer an explicit -H/--host; otherwise best-effort
+            # git-remote inference, tolerating its ABSENCE (a bare `get_remote_host` here
+            # under `set -e`, with no origin and no -H, previously killed the script
+            # SILENTLY — exit 1, zero output — even though -r/-H are exactly the flags
+            # that support running with no usable origin at all).
+            host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
+            # A --login override always wins. Otherwise name this host's login
+            # only as a best effort: the login name merely selects a per-login
+            # token, and gitea_resolve_api_for_login falls back to the host
+            # credential (get_gitea_token) when no tea login is named — so a host
+            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the default credential to resolve. The single resolved token is
+            # then used for the write, the /user identity, and the read-back.
+            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
+            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
             ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             comment_id=$(gitea_create_comment_verified "$PR_NUMBER" "$COMMENT" "$ACTING_LOGIN") || {
                 echo "Error: could not create and verify a comment on Gitea PR #$PR_NUMBER via a provider-returned created id (#865)." >&2

packages/mosaic/framework/tools/git/test-gitea-principal-resolution.sh

@@ -1,255 +0,0 @@
-#!/usr/bin/env bash
-# Regression harness for detect-platform.sh's resolve_gitea_principal() — the
-# identity-first acting-principal resolution shared by the git wrappers
-# (mosaicstack/stack #1280).
-#
-# The contract under test (precedence: --login > MOSAIC_GIT_IDENTITY /
-# git config mosaic.gitIdentity > tea login list, which is the LAST resort):
-#   1. identity env + per-slot token present -> mode=identity, principal=
-#      identity name, source names the identity's slot PATH (never a token
-#      value).
-#   2. identity env + per-slot token ABSENT -> FAIL LOUD: nonzero, empty
-#      stdout, stderr naming the identity and the expected slot path.
-#   3. identity env + --login -> --login wins (login mode resolves even when
-#      the identity has no slot — operator intent beats environment).
-#   4. identity unset + no --login -> default mode: the tea login list
-#      resolves the principal exactly as before (preserved behavior).
-#   5. no identity + no host-matching tea login -> default/host-credential
-#      (preserved behavior; absence is not an error on the default path).
-#   6. identity on an UNRECOGNIZED host (no per-slot scheme) -> does not bind;
-#      default mode (containment, mirroring get_gitea_token).
-#   7. --login with no host-bound token for that login -> FAIL LOUD, stderr
-#      naming the login and the host.
-#   8. git config mosaic.gitIdentity is honored when the env var is unset.
-#   9. The resolver NEVER emits a token value — stdout/stderr of every
-#      successful resolution must not contain the slot file's contents.
-#
-# Uses a stubbed tea binary, stubbed tea config.yml, stubbed credentials.json
-# and stubbed per-slot token files under a fake HOME. NEVER reads real secrets.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/gitea-principal-resolution}"
-FAKE_HOME="$WORK_DIR/home"
-REPO_DIR="$WORK_DIR/repo"
-BIN_DIR="$WORK_DIR/bin"
-CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
-
-rm -rf "$WORK_DIR"
-mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$FAKE_HOME/.config/tea" "$REPO_DIR" "$BIN_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
-
-# tea's own config store: the source get_gitea_token_for_login reads. Logins
-# "alice" (mosaicstack) and "bob-usc" (usc) carry sentinel token values that
-# the assertions prove are NEVER emitted by the resolver.
-cat > "$FAKE_HOME/.config/tea/config.yml" <<'YAML'
-logins:
-- name: alice
-  url: https://git.mosaicstack.dev
-  token: SECRET-alice-tea-token
-- name: bob-usc
-  url: https://git.uscllc.com
-  token: SECRET-bob-usc-tea-token
-YAML
-
-# Stubbed tea: only what login resolution needs (`login list --output json`).
-cat > "$BIN_DIR/tea" <<'SH'
-#!/usr/bin/env bash
-set -euo pipefail
-if [[ "$*" == "login list --output json" ]]; then
-    cat <<'JSON'
-[
-  {"name":"alice","url":"https://git.mosaicstack.dev","default":true},
-  {"name":"bob-usc","url":"https://git.uscllc.com"}
-]
-JSON
-    exit 0
-fi
-exit 0
-SH
-chmod +x "$BIN_DIR/tea"
-
-# Per-slot identity token with a sentinel value the assertions prove is never
-# emitted (proving "token came from the identity's slot BY PATH, not by value").
-echo -n "SECRET-agentX-slot-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token"
-
-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
-}
-assert_contains() {
-  local desc="$1" haystack="$2" needle="$3"
-  if [[ "$haystack" != *"$needle"* ]]; then
-    echo "FAIL: $desc — missing '$needle' in: $haystack" >&2
-    fail=1
-  fi
-}
-assert_not_contains() {
-  local desc="$1" haystack="$2" needle="$3"
-  if [[ "$haystack" == *"$needle"* ]]; then
-    echo "FAIL: $desc — must not contain '$needle', got: $haystack" >&2
-    fail=1
-  fi
-}
-
-# Runs resolve_gitea_principal for $1=login_override $2=host inside REPO_DIR
-# (per-worktree git config resolves there) under a fake HOME, stubbed tea, and
-# stubbed credentials. Extra env (e.g. MOSAIC_GIT_IDENTITY) via $@.
-call_resolver() {
-  local login="$1" host="$2"; shift 2
-  (
-    cd "$REPO_DIR"
-    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
-      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
-      DETECT_PLATFORM_SH="$SCRIPT_DIR/detect-platform.sh" "$@" \
-      bash -c 'source "$DETECT_PLATFORM_SH"; resolve_gitea_principal "$1" "$2"' _ "$login" "$host"
-  )
-}
-
-field() { printf '%s' "$1" | cut -f"$2"; }
-
-# ---------------------------------------------------------------------------
-# 1. Identity env + slot present -> identity mode, slot named BY PATH, and no
-#    token value ever emitted.
-# ---------------------------------------------------------------------------
-git -C "$REPO_DIR" config --unset mosaic.gitIdentity 2>/dev/null || true
-out=$(call_resolver "" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentX)
-assert_eq "identity mode"            "identity" "$(field "$out" 1)"
-assert_eq "identity principal"       "agentX"   "$(field "$out" 2)"
-assert_eq "identity slot source" \
-  "identity-slot:$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token" \
-  "$(field "$out" 3)"
-assert_not_contains "identity stdout leaks token" "$out" "SECRET"
-
-# ---------------------------------------------------------------------------
-# 2. Identity env + slot ABSENT -> fail loud: nonzero, empty stdout, stderr
-#    naming the identity and the expected slot path.
-# ---------------------------------------------------------------------------
-stderr_file="$WORK_DIR/stderr.tmp"
-set +e
-out=$(call_resolver "" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentNoSlot 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: missing slot — expected nonzero return, got 0 (stdout='$out')" >&2
-  fail=1
-fi
-if [[ -n "$out" ]]; then
-  echo "FAIL: missing slot — expected empty stdout, got '$out'" >&2
-  fail=1
-fi
-err=$(cat "$stderr_file")
-assert_contains "missing slot names identity"  "$err" "agentNoSlot"
-assert_contains "missing slot names slot path" "$err" \
-  "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentNoSlot.token"
-assert_not_contains "missing-slot stderr leaks token" "$err" "SECRET"
-
-# ---------------------------------------------------------------------------
-# 3. Identity + --login -> --login wins. Also wins when the identity has NO
-#    slot (no identity check may veto an explicit login).
-# ---------------------------------------------------------------------------
-out=$(call_resolver "alice" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentX)
-assert_eq "login beats identity (mode)"      "login" "$(field "$out" 1)"
-assert_eq "login beats identity (principal)" "alice" "$(field "$out" 2)"
-assert_eq "login source" "tea-login:alice" "$(field "$out" 3)"
-out=$(call_resolver "alice" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentNoSlot)
-assert_eq "login beats slot-less identity" "login" "$(field "$out" 1)"
-
-# ---------------------------------------------------------------------------
-# 4. No identity, no --login -> default mode via the tea login list
-#    (preserved behavior).
-# ---------------------------------------------------------------------------
-out=$(call_resolver "" "git.mosaicstack.dev")
-assert_eq "default mode"          "default" "$(field "$out" 1)"
-assert_eq "default principal"     "alice"   "$(field "$out" 2)"
-assert_eq "default source"        "tea-default" "$(field "$out" 3)"
-
-# ---------------------------------------------------------------------------
-# 5. No identity, no --login, no host-matching tea login -> default with the
-#    host credential (absence is not an error on the default path).
-# ---------------------------------------------------------------------------
-out=$(call_resolver "" "git.unknown.test")
-assert_eq "no-match default mode"  "default" "$(field "$out" 1)"
-assert_eq "no-match default principal" "" "$(field "$out" 2)"
-assert_eq "no-match default source" "host-credential" "$(field "$out" 3)"
-
-# ---------------------------------------------------------------------------
-# 6. Identity on an UNRECOGNIZED host -> does not bind; default mode
-#    (containment, mirroring get_gitea_token's scope).
-# ---------------------------------------------------------------------------
-out=$(call_resolver "" "github.com" MOSAIC_GIT_IDENTITY=agentX)
-assert_eq "unrecognized host falls to default" "default" "$(field "$out" 1)"
-
-# ---------------------------------------------------------------------------
-# 7. --login with no host-bound token for that login -> fail loud, stderr
-#    naming the login and the host.
-# ---------------------------------------------------------------------------
-: > "$stderr_file"
-set +e
-out=$(call_resolver "ghost-login" "git.mosaicstack.dev" 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: unknown --login — expected nonzero return, got 0 (stdout='$out')" >&2
-  fail=1
-fi
-err=$(cat "$stderr_file")
-assert_contains "unknown login names login" "$err" "ghost-login"
-assert_contains "unknown login names host"  "$err" "git.mosaicstack.dev"
-# A cross-host login (exists, but for usc) must ALSO fail loud for mosaicstack.
-set +e
-out=$(call_resolver "bob-usc" "git.mosaicstack.dev" 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: cross-host --login — expected nonzero return, got 0" >&2
-  fail=1
-fi
-
-# ---------------------------------------------------------------------------
-# 8. git config mosaic.gitIdentity honored when env is unset.
-# ---------------------------------------------------------------------------
-git -C "$REPO_DIR" config mosaic.gitIdentity agentX
-out=$(call_resolver "" "git.mosaicstack.dev")
-assert_eq "git-config identity mode" "identity" "$(field "$out" 1)"
-assert_eq "git-config identity principal" "agentX" "$(field "$out" 2)"
-git -C "$REPO_DIR" config --unset mosaic.gitIdentity
-
-# ---------------------------------------------------------------------------
-# 9. Cross-host slot layout: the usc slot path is chosen for the usc host.
-# ---------------------------------------------------------------------------
-echo -n "SECRET-agentX-usc-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-usc-agentX.token"
-out=$(call_resolver "" "git.uscllc.com" MOSAIC_GIT_IDENTITY=agentX)
-assert_eq "usc identity mode" "identity" "$(field "$out" 1)"
-assert_eq "usc slot source" \
-  "identity-slot:$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-usc-agentX.token" \
-  "$(field "$out" 3)"
-
-if [[ "$fail" -eq 0 ]]; then
-  echo "resolve_gitea_principal identity-first resolution regression passed"
-fi
-
-exit "$fail"

packages/mosaic/framework/tools/git/test-issue-create-body-safety.sh

@@ -77,30 +77,12 @@ exit 0
 SH
 chmod +x "$BIN_DIR/tea"
 
-# TRIPWIRE provider stub: this harness tests argv construction, so ANY curl
-# call is a failure of that contract (and, before this stub existed, a LIVE
-# write — the #1282–#1287 incident: the seat's real HOME leaked a global
-# mosaic.gitIdentity, flipping the wrapper into identity mode whose real
-# per-slot token created real issues on the forge). Fail loudly instead.
-cat > "$BIN_DIR/curl" <<'SH'
-#!/usr/bin/env bash
-echo "FAIL: body-safety harness reached a provider request — this test must never curl" >&2
-exit 99
-SH
-chmod +x "$BIN_DIR/curl"
-
-# Hermetic invocation: fake HOME (no credentials, no tea config, no token
-# slots) and GIT_CONFIG_GLOBAL severed — `git config --get mosaic.gitIdentity`
-# otherwise resolves the WORKSTATION's global identity (mos-dt-0 on the seat
-# that wrote this) and reroutes the wrapper into identity mode (#1280 family).
 (
     cd "$REPO_DIR"
-    env -i HOME="$WORK_DIR/home" PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
-      MOSAIC_TEST_RECEIVED="$RECEIVED_FILE" \
-      "$SCRIPT_DIR/issue-create.sh" -t "Body safety test" -b "$BODY"
+    PATH="$BIN_DIR:$PATH" \
+    MOSAIC_TEST_RECEIVED="$RECEIVED_FILE" \
+    "$SCRIPT_DIR/issue-create.sh" -t "Body safety test" -b "$BODY"
 ) >/dev/null
-mkdir -p "$WORK_DIR/home"
 
 # 1. No command substitution executed anywhere in the pipeline.
 if [[ -e "$SENTINEL" ]]; then

packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh

@@ -47,31 +47,14 @@ SH
 chmod +x "$BIN_DIR/tea" "$BIN_DIR/curl"
 
 run_wrapper() {
-  # Hermetic: fake HOME (fixture credentials only, no token slots, no tea
-  # config) and GIT_CONFIG_GLOBAL severed — `git config --get
-  # mosaic.gitIdentity` otherwise resolves the WORKSTATION's global identity
-  # and reroutes the wrapper into identity mode before the tea paths this
-  # harness exercises (#1280 family; see test-issue-create-body-safety.sh).
-  # An `env …` prefix (used for MOSAIC_TEA_STALE_USER) is re-wrapped, not
-  # doubled: arguments beginning with "env" are shifted past.
-  local env_pairs=()
-  if [[ "${1:-}" == "env" ]]; then
-    shift
-    while [[ "$#" -gt 0 && "$1" == *=* ]]; do
-      env_pairs+=("$1")
-      shift
-    done
-  fi
   (
     cd "$REPO_DIR"
-    env -i HOME="$WORK_DIR/home" PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
-      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
-      MOSAIC_TEST_LOG="$LOG_FILE" "${env_pairs[@]}" \
-      "$@"
+    PATH="$BIN_DIR:$PATH" \
+    MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
+    MOSAIC_TEST_LOG="$LOG_FILE" \
+    "$@"
   )
 }
-mkdir -p "$WORK_DIR/home"
 
 : > "$LOG_FILE"
 printf 'Interactive title\nInteractive body\nlabel-a,label-b\nM1\n' | run_wrapper "$SCRIPT_DIR/issue-create.sh" -i >/dev/null

packages/mosaic/framework/tools/git/test-pr-create-identity-first.sh

@@ -1,244 +0,0 @@
-#!/usr/bin/env bash
-# Load-bearing regression harness for pr-create.sh identity-first principal
-# resolution (mosaicstack/stack #1280).
-#
-# The failure this harness is written down to catch: `MOSAIC_GIT_IDENTITY=fargo
-# pr-create.sh …` produces a PR attributed to `mos-dt-0` (whichever account the
-# tea login list happens to hold). Before #1280 the identity-aware code existed
-# but sat on the API arm that only ran when the tea path FAILED — tea succeeded,
-# so the identity arm never executed, and every test that did not check ORDERING
-# passed. This harness checks ordering directly:
-#
-#   1. identity set + slot present -> the PR is created via the REST API with
-#      the identity's per-slot token (asserted by sentinel value AT the fake
-#      provider), and tea's `pr create` is NEVER invoked.
-#   2. identity set + slot ABSENT -> nonzero, stderr naming the identity and
-#      the expected slot path; neither tea `pr create` nor any API request
-#      fires. No silent fallback to the tea login list.
-#   3. identity set + --login -> --login wins: tea runs WITH the explicit
-#      --login, no API request.
-#   4. nothing set -> preserved behavior: tea path with the tea-list login.
-#
-# Uses a stubbed tea, a stubbed curl provider, stubbed credentials.json and
-# per-slot token under a fake HOME. NEVER reads real secrets or hits a live
-# forge — all assertions are against the stubs' logs.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-create-identity-first}"
-FAKE_HOME="$WORK_DIR/home"
-REPO_DIR="$WORK_DIR/repo"
-TOOLS_DIR="$WORK_DIR/tools"
-BIN_DIR="$WORK_DIR/bin"
-LOG_FILE="$WORK_DIR/calls.log"
-CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
-
-rm -rf "$WORK_DIR"
-mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$FAKE_HOME/.config/tea" \
-  "$REPO_DIR" "$TOOLS_DIR/git" "$TOOLS_DIR/_lib" "$BIN_DIR"
-
-# Fixture: the real scripts under test, copied so sibling stubs (and the
-# ../_lib credential loader) resolve inside the fixture tree.
-cp "$SCRIPT_DIR/pr-create.sh" "$TOOLS_DIR/git/pr-create.sh"
-cp "$SCRIPT_DIR/detect-platform.sh" "$TOOLS_DIR/git/detect-platform.sh"
-cp "$SCRIPT_DIR/../_lib/credentials.sh" "$TOOLS_DIR/_lib/credentials.sh"
-chmod +x "$TOOLS_DIR/git/pr-create.sh"
-
-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"
-    }
-  }
-}
-JSON
-
-cat > "$FAKE_HOME/.config/tea/config.yml" <<'YAML'
-logins:
-- name: alice
-  url: https://git.mosaicstack.dev
-  token: SECRET-alice-tea-token
-YAML
-
-echo -n "SECRET-agentX-slot-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token"
-
-: > "$LOG_FILE"
-
-# Stubbed tea: records every invocation; `login list` feeds login resolution;
-# `api --login <n> /user` feeds get_gitea_authenticated_user; `pr create` marks
-# the marker file (its presence fails the identity-mode assertions).
-cat > "$BIN_DIR/tea" <<SH
-#!/usr/bin/env bash
-set -euo pipefail
-printf 'TEA: %s\n' "\$*" >> "$LOG_FILE"
-if [[ "\$*" == "login list --output json" ]]; then
-    cat <<'JSON'
-[
-  {"name":"alice","url":"https://git.mosaicstack.dev","default":true}
-]
-JSON
-    exit 0
-fi
-if [[ "\${1:-}" == "api" ]]; then
-    printf '%s\n' '{"login":"alice"}'
-    exit 0
-fi
-if [[ "\$*" == pr\ create* ]]; then
-    echo "TEA-PR-CREATE-INVOKED" >> "$LOG_FILE"
-    exit 0
-fi
-exit 0
-SH
-chmod +x "$BIN_DIR/tea"
-
-# Stubbed provider: records the URL and the Authorization header VALUE it
-# received, answers 201 with a created-PR object. The sentinel token values are
-# synthetic fixtures — asserting them at the provider proves WHICH slot's
-# credential carried the write.
-cat > "$BIN_DIR/curl" <<SH
-#!/usr/bin/env bash
-set -euo pipefail
-url=""
-auth=""
-while [[ \$# -gt 0 ]]; do
-    case "\$1" in
-        -H)
-            case "\$2" in
-                Authorization*) auth="\$2" ;;
-            esac
-            shift 2
-            ;;
-        *)  [[ -n "\$1" && "\$1" != -* ]] && url="\$1"
-            shift
-            ;;
-    esac
-done
-printf 'CURL-URL: %s\nCURL-AUTH: %s\n' "\$url" "\$auth" >> "$LOG_FILE"
-cat <<'JSON'
-{"number": 1299, "html_url": "https://git.mosaicstack.dev/mosaicstack/stack/pulls/1299"}
-JSON
-exit 0
-SH
-chmod +x "$BIN_DIR/curl"
-
-fail=0
-assert_contains() {
-  local desc="$1" needle="$2"
-  if ! grep -qF -- "$needle" "$LOG_FILE"; then
-    echo "FAIL: $desc — log does not contain '$needle':" >&2
-    cat "$LOG_FILE" >&2
-    fail=1
-  fi
-}
-assert_not_contains() {
-  local desc="$1" needle="$2"
-  if grep -qF -- "$needle" "$LOG_FILE"; then
-    echo "FAIL: $desc — log must not contain '$needle':" >&2
-    cat "$LOG_FILE" >&2
-    fail=1
-  fi
-}
-
-EXTRA_ARGS=""
-run_pr_create() {
-  # "$@" carries ONLY environment assignments (VAR=value); EXTRA_ARGS (if
-  # set) carries wrapper arguments, so `env` never mistakes a wrapper flag
-  # like --login for one of its own.
-  (
-    cd "$REPO_DIR"
-    # shellcheck disable=SC2086 # EXTRA_ARGS is deliberately word-split wrapper args
-    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
-      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" "$@" \
-      bash "$TOOLS_DIR/git/pr-create.sh" -t "Test PR" -B next -H fix/test $EXTRA_ARGS
-  )
-}
-
-# ---------------------------------------------------------------------------
-# 1. HAPPY PATH (the load-bearing ordering test): identity set + slot present
-#    -> REST API with the per-slot token; tea `pr create` NEVER invoked.
-# ---------------------------------------------------------------------------
-set +e
-out=$(run_pr_create MOSAIC_GIT_IDENTITY=agentX 2>"$WORK_DIR/stderr-1.tmp")
-rc=$?
-set -e
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: identity happy path — expected rc=0, got $rc" >&2
-  cat "$WORK_DIR/stderr-1.tmp" >&2
-  fail=1
-fi
-assert_contains "identity happy path reaches the API" "CURL-URL: https://git.mosaicstack.dev/api/v1/repos/mosaicstack/stack/pulls"
-assert_contains "identity happy path carries the slot token" "CURL-AUTH: Authorization: token SECRET-agentX-slot-token"
-assert_not_contains "identity happy path must NOT invoke tea pr create" "TEA-PR-CREATE-INVOKED"
-
-# ---------------------------------------------------------------------------
-# 2. Identity set + slot ABSENT -> fail loud BEFORE any write: nonzero, stderr
-#    naming identity + slot path, no tea pr create, no API request.
-# ---------------------------------------------------------------------------
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_create MOSAIC_GIT_IDENTITY=agentNoSlot 2>"$WORK_DIR/stderr-2.tmp")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: missing slot — expected nonzero return, got 0 (stdout='$out')" >&2
-  fail=1
-fi
-err=$(cat "$WORK_DIR/stderr-2.tmp")
-if [[ "$err" != *"agentNoSlot"* ]]; then
-  echo "FAIL: missing slot — stderr does not name the identity:" >&2
-  echo "$err" >&2
-  fail=1
-fi
-if [[ "$err" != *"$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentNoSlot.token"* ]]; then
-  echo "FAIL: missing slot — stderr does not name the expected slot path:" >&2
-  echo "$err" >&2
-  fail=1
-fi
-assert_not_contains "missing slot must not reach tea pr create" "TEA-PR-CREATE-INVOKED"
-assert_not_contains "missing slot must not reach the API" "CURL-URL"
-
-# ---------------------------------------------------------------------------
-# 3. Identity set + --login -> --login wins: tea runs WITH the explicit login.
-# ---------------------------------------------------------------------------
-: > "$LOG_FILE"
-EXTRA_ARGS="--login alice"
-set +e
-out=$(run_pr_create MOSAIC_GIT_IDENTITY=agentX 2>"$WORK_DIR/stderr-3.tmp")
-rc=$?
-set -e
-EXTRA_ARGS=""
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: login override — expected rc=0, got $rc" >&2
-  cat "$WORK_DIR/stderr-3.tmp" >&2
-  fail=1
-fi
-assert_contains "login override drives tea with the explicit login" "TEA: pr create --repo mosaicstack/stack --login alice"
-assert_not_contains "login override must not hit the API" "CURL-URL"
-
-# ---------------------------------------------------------------------------
-# 4. Nothing set -> preserved behavior: tea path with the tea-list login.
-# ---------------------------------------------------------------------------
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_create 2>"$WORK_DIR/stderr-4.tmp")
-rc=$?
-set -e
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: default path — expected rc=0, got $rc" >&2
-  cat "$WORK_DIR/stderr-4.tmp" >&2
-  fail=1
-fi
-assert_contains "default path still uses the tea-list login" "TEA: pr create --repo mosaicstack/stack --login alice"
-
-if [[ "$fail" -eq 0 ]]; then
-  echo "pr-create identity-first happy-path regression passed"
-fi
-
-exit "$fail"

packages/mosaic/framework/tools/git/test-pr-merge-principal-resolution.sh

@@ -1,247 +0,0 @@
-#!/usr/bin/env bash
-# Regression harness for pr-merge.sh identity-first principal resolution
-# (mosaicstack/stack #1280).
-#
-# Covers:
-#   1. --dry-run reports the acting principal the merge WOULD use, resolved the
-#      same way the real merge resolves it: --login > MOSAIC_GIT_IDENTITY /
-#      git config mosaic.gitIdentity > shared host credential. (The pre-#1280
-#      deployed copy reported a tea login that the merge would not act as.)
-#   2. --dry-run fails closed when the requested principal has no credential:
-#      unknown --login, or an identity with no per-slot token (stderr names
-#      the login / the identity and its slot path).
-#   3. The real merge POST carries the resolved principal's credential and no
-#      other: --login merges with that login's tea-config token; an identity
-#      merges with the per-slot token; an unresolvable --login never reaches
-#      the provider.
-#
-# Fixture pattern from test-pr-merge-head-pin.sh: the scripts under test are
-# copied into a fixture tree with stubbed pr-metadata.sh / ci-queue-wait.sh
-# siblings; the provider is a stubbed curl that records the credential it
-# received. NEVER reads real secrets or hits a live forge.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-principal-resolution}"
-FAKE_HOME="$WORK_DIR/home"
-REPO_DIR="$WORK_DIR/repo"
-TOOLS_DIR="$WORK_DIR/tools"
-BIN_DIR="$WORK_DIR/bin"
-LOG_FILE="$WORK_DIR/calls.log"
-CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
-SHA=0123456789abcdef0123456789abcdef01234567
-
-rm -rf "$WORK_DIR"
-mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$FAKE_HOME/.config/tea" \
-  "$REPO_DIR" "$TOOLS_DIR/git" "$TOOLS_DIR/_lib" "$BIN_DIR"
-
-cp "$SCRIPT_DIR/pr-merge.sh" "$TOOLS_DIR/git/pr-merge.sh"
-cp "$SCRIPT_DIR/detect-platform.sh" "$TOOLS_DIR/git/detect-platform.sh"
-cp "$SCRIPT_DIR/../_lib/credentials.sh" "$TOOLS_DIR/_lib/credentials.sh"
-chmod +x "$TOOLS_DIR/git/pr-merge.sh"
-
-git -C "$REPO_DIR" init -q
-git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
-
-# Stubbed siblings pr-merge.sh resolves relative to its own SCRIPT_DIR.
-cat > "$TOOLS_DIR/git/pr-metadata.sh" <<SH
-#!/usr/bin/env bash
-printf '%s\n' '{"baseRefName":"next","headRefName":"fix/pinned","headRefOid":"$SHA","headRepository":"mosaicstack/stack","title":"Test PR","author":{"login":"contributor"}}'
-SH
-cat > "$TOOLS_DIR/git/ci-queue-wait.sh" <<'SH'
-#!/usr/bin/env bash
-exit 0
-SH
-chmod +x "$TOOLS_DIR/git/pr-metadata.sh" "$TOOLS_DIR/git/ci-queue-wait.sh"
-
-cat > "$CREDENTIALS_FILE" <<'JSON'
-{
-  "gitea": {
-    "mosaicstack": {
-      "url": "https://git.mosaicstack.dev",
-      "token": "shared-mosaicstack-token"
-    }
-  }
-}
-JSON
-
-cat > "$FAKE_HOME/.config/tea/config.yml" <<'YAML'
-logins:
-- name: fred-ms
-  url: https://git.mosaicstack.dev
-  token: SECRET-fred-ms-tea-token
-YAML
-
-echo -n "SECRET-agentX-slot-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token"
-
-: > "$LOG_FILE"
-
-# Stubbed tea for login-list resolution only.
-cat > "$BIN_DIR/tea" <<'SH'
-#!/usr/bin/env bash
-set -euo pipefail
-if [[ "$*" == "login list --output json" ]]; then
-    cat <<'JSON'
-[
-  {"name":"fred-ms","url":"https://git.mosaicstack.dev","default":true}
-]
-JSON
-    exit 0
-fi
-exit 0
-SH
-chmod +x "$BIN_DIR/tea"
-
-# Stubbed provider. pr-merge passes curl config on STDIN with -K -; the stub
-# reads stdin, records the Authorization header it received, answers 200.
-cat > "$BIN_DIR/curl" <<SH
-#!/usr/bin/env bash
-set -euo pipefail
-url=""
-out_file=""
-stdin_config=""
-if [[ ! -t 0 ]]; then
-    stdin_config="\$(cat || true)"
-fi
-while [[ \$# -gt 0 ]]; do
-    case "\$1" in
-        -o) out_file="\$2"; shift 2 ;;
-        -K|-w|--max-filesize|--max-time|--connect-timeout|-sS) shift 2 ;;
-        *)  [[ -n "\$1" && "\$1" != -* && -z "\$url" ]] && url="\$1"
-            shift
-            ;;
-    esac
-done
-auth="\$(printf '%s' "\$stdin_config" | grep -o 'Authorization: token [^"]*' || true)"
-printf 'CURL-URL: %s\nCURL-AUTH: %s\n' "\$url" "\$auth" >> "$LOG_FILE"
-[[ -n "\$out_file" ]] && printf '{}' > "\$out_file"
-printf '200\n'
-exit 0
-SH
-chmod +x "$BIN_DIR/curl"
-
-fail=0
-assert_contains_log() {
-  local desc="$1" needle="$2"
-  if ! grep -qF -- "$needle" "$LOG_FILE"; then
-    echo "FAIL: $desc — log does not contain '$needle':" >&2
-    cat "$LOG_FILE" >&2
-    fail=1
-  fi
-}
-assert_not_contains_log() {
-  local desc="$1" needle="$2"
-  if grep -qF -- "$needle" "$LOG_FILE"; then
-    echo "FAIL: $desc — log must not contain '$needle':" >&2
-    cat "$LOG_FILE" >&2
-    fail=1
-  fi
-}
-
-run_pr_merge() {
-  local extra_args="$1"; shift
-  (
-    cd "$REPO_DIR"
-    # shellcheck disable=SC2086 # extra_args is deliberately word-split wrapper args
-    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
-      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" "$@" \
-      bash "$TOOLS_DIR/git/pr-merge.sh" -n 42 $extra_args
-  )
-}
-
-# ---------------------------------------------------------------------------
-# 1. --dry-run reports the resolved acting principal truthfully.
-# ---------------------------------------------------------------------------
-out=$(run_pr_merge "--dry-run" MOSAIC_GIT_IDENTITY=agentX)
-if [[ "$out" != *"as git identity 'agentX' (per-slot credential)"* ]]; then
-  echo "FAIL: dry-run identity — principal not reported: $out" >&2
-  fail=1
-fi
-
-out=$(run_pr_merge "--dry-run --login fred-ms" MOSAIC_GIT_IDENTITY=agentX)
-if [[ "$out" != *"as tea login 'fred-ms'"* ]]; then
-  echo "FAIL: dry-run login override — login not reported (must beat env identity): $out" >&2
-  fail=1
-fi
-
-out=$(run_pr_merge "--dry-run")
-if [[ "$out" != *"as default host credential"* ]]; then
-  echo "FAIL: dry-run default — not reported: $out" >&2
-  fail=1
-fi
-
-# ---------------------------------------------------------------------------
-# 2. --dry-run fails closed when the requested principal has no credential.
-# ---------------------------------------------------------------------------
-stderr_file="$WORK_DIR/stderr.tmp"
-set +e
-out=$(run_pr_merge "--dry-run --login ghost" 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]] || [[ "$(cat "$stderr_file")" != *"ghost"* ]]; then
-  echo "FAIL: dry-run unknown --login — expected fail-loud naming 'ghost', rc=$rc" >&2
-  cat "$stderr_file" >&2
-  fail=1
-fi
-
-: > "$stderr_file"
-set +e
-out=$(run_pr_merge "--dry-run" MOSAIC_GIT_IDENTITY=agentNoSlot 2>"$stderr_file")
-rc=$?
-set -e
-err=$(cat "$stderr_file")
-if [[ "$rc" -eq 0 ]] || [[ "$err" != *"agentNoSlot"* ]] \
-  || [[ "$err" != *"$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentNoSlot.token"* ]]; then
-  echo "FAIL: dry-run identity without slot — expected fail-loud naming identity + slot path, rc=$rc" >&2
-  echo "$err" >&2
-  fail=1
-fi
-
-# ---------------------------------------------------------------------------
-# 3. The real merge POST carries the resolved principal's credential ONLY.
-# ---------------------------------------------------------------------------
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_merge "--login fred-ms" MOSAIC_GIT_IDENTITY=agentX 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: merge with --login — expected rc=0, got $rc" >&2
-  cat "$stderr_file" >&2
-  fail=1
-fi
-assert_contains_log "merge --login uses the login token" "CURL-AUTH: Authorization: token SECRET-fred-ms-tea-token"
-assert_not_contains_log "merge --login must not use the identity slot token" "SECRET-agentX-slot-token"
-assert_not_contains_log "merge --login must not use the shared token" "shared-mosaicstack-token"
-
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_merge "" MOSAIC_GIT_IDENTITY=agentX 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: merge with identity — expected rc=0, got $rc" >&2
-  cat "$stderr_file" >&2
-  fail=1
-fi
-assert_contains_log "merge identity uses the per-slot token" "CURL-AUTH: Authorization: token SECRET-agentX-slot-token"
-assert_not_contains_log "merge identity must not use the shared token" "shared-mosaicstack-token"
-
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_merge "--login ghost" 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: merge with unknown --login — expected nonzero, got 0" >&2
-  fail=1
-fi
-assert_not_contains_log "merge with unknown --login must not reach the provider" "CURL-URL"
-
-if [[ "$fail" -eq 0 ]]; then
-  echo "pr-merge identity-first principal resolution regression passed"
-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": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_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/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_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-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-gitea-principal-resolution.sh && bash framework/tools/git/test-pr-create-identity-first.sh && bash framework/tools/git/test-pr-merge-principal-resolution.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_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/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_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-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/commands/fleet-place-unit.spec.ts

@@ -0,0 +1,177 @@
+import { lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { placeUnitFile, resolveLeaseBrokerSocketForPreflight } from './fleet.js';
+
+/**
+ * Unit-placement regression harness for #1292.
+ *
+ * The two measured defects this suite pins:
+ *  1. `systemctl enable <name>` does NOT rewrite an existing by-path
+ *     wants-symlink — so placement must remove stale residue explicitly, and
+ *     acceptance asserts on the RESULTING SYMLINK TARGET, never on the enable
+ *     call's argument (asserting the call cannot see where the link ended up).
+ *  2. Node's copyFile FOLLOWS a by-path symlink at the destination and
+ *     overwrites the SEED template. Acceptance asserts on the SEED's bytes
+ *     AND mtime — unchanged — which is the only check that can redden for
+ *     finding 2. The symlink-target assertion catches finding 1; these are
+ *     different defects with different failure modes.
+ *
+ * Fixtures are entirely inside tmpdirs (source template, active systemd dir,
+ * wants dir) — no real host paths are touched by this suite.
+ */
+
+describe('placeUnitFile (#1292 unit placement)', () => {
+  const cleanup: string[] = [];
+  afterEach(async () => {
+    while (cleanup.length > 0) {
+      await rm(cleanup.pop()!, { recursive: true, force: true });
+    }
+  });
+
+  async function fixture() {
+    const root = await mkdtemp(join(tmpdir(), 'place-unit-'));
+    cleanup.push(root);
+    const seedDir = join(root, 'seed');
+    const activeDir = join(root, 'active');
+    await mkdir(seedDir, { recursive: true });
+    await mkdir(activeDir, { recursive: true });
+    const seedTemplate = join(seedDir, 'unit-under-test.service');
+    await writeFile(
+      seedTemplate,
+      '[Unit]\nDescription=seed template\n[Service]\nType=oneshot\nExecStart=/bin/true\n[Install]\nWantedBy=default.target\n',
+    );
+    const activeSource = join(root, 'active-source.service');
+    await writeFile(
+      activeSource,
+      '[Unit]\nDescription=active copy v2\n[Service]\nType=oneshot\nExecStart=/bin/true\n[Install]\nWantedBy=default.target\n',
+    );
+    return { root, seedDir, activeDir, seedTemplate, activeSource };
+  }
+
+  it('places a regular file on a clean host (negative control: no residue anywhere)', async () => {
+    const f = await fixture();
+    const result = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    expect(result.unlinkedDestinationSymlink).toBe(false);
+    expect(result.removedStaleWantsSymlink).toBe(false);
+    const info = await lstat(join(f.activeDir, 'unit-under-test.service'));
+    expect(info.isSymbolicLink()).toBe(false);
+    expect(await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8')).toContain(
+      'active copy v2',
+    );
+    // Seed untouched by construction — but assert it, so the clean-host case
+    // cannot silently regress into seed-mutation.
+    expect(await readFile(f.seedTemplate, 'utf8')).toContain('seed template');
+  });
+
+  it('by-path residue: unlinks destination symlink, places the file, seed bytes AND mtime unchanged (finding 2)', async () => {
+    const f = await fixture();
+    const seedBefore = await readFile(f.seedTemplate, 'utf8');
+    const mtimeBefore = (await lstat(f.seedTemplate)).mtimeMs;
+    // The fomo-lin convention: by-path enable left a symlink AT the unit name
+    // pointing at the seed template, plus a wants-symlink doing the same.
+    await symlink(f.seedTemplate, join(f.activeDir, 'unit-under-test.service'));
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(f.seedTemplate, join(wantsDir, 'unit-under-test.service'));
+
+    const result = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    expect(result.unlinkedDestinationSymlink).toBe(true);
+    expect(result.removedStaleWantsSymlink).toBe(true);
+
+    // FINDING 2's check: the seed is byte-identical and its mtime did not move.
+    expect(await readFile(f.seedTemplate, 'utf8')).toBe(seedBefore);
+    expect((await lstat(f.seedTemplate)).mtimeMs).toBe(mtimeBefore);
+
+    // The destination is now a regular file carrying the ACTIVE content.
+    const destInfo = await lstat(join(f.activeDir, 'unit-under-test.service'));
+    expect(destInfo.isSymbolicLink()).toBe(false);
+    expect(await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8')).toContain(
+      'active copy v2',
+    );
+  });
+
+  it('by-path residue: no wants-symlink remains pointing at the seed (finding 1 residue cleared)', async () => {
+    const f = await fixture();
+    await symlink(f.seedTemplate, join(f.activeDir, 'unit-under-test.service'));
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(f.seedTemplate, join(wantsDir, 'unit-under-test.service'));
+
+    await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+
+    // After placement the stale wants link is GONE (enable-by-name recreates
+    // it correctly). A link still present must not point at the seed.
+    try {
+      const link = await lstat(join(wantsDir, 'unit-under-test.service'));
+      if (link.isSymbolicLink()) {
+        const target = await readFile(join(wantsDir, 'unit-under-test.service'), 'utf8').catch(
+          async () => '',
+        );
+        expect(target).not.toContain('seed template');
+      }
+    } catch {
+      // absent wants link — the expected post-placement state
+    }
+  });
+
+  it('idempotence: second placement on a reconciled host is a no-op producing the identical final state', async () => {
+    const f = await fixture();
+    // Reconciled starting state: regular file at the name, wants link to the active copy.
+    await writeFile(
+      join(f.activeDir, 'unit-under-test.service'),
+      await readFile(f.activeSource, 'utf8'),
+    );
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(
+      join(f.activeDir, 'unit-under-test.service'),
+      join(wantsDir, 'unit-under-test.service'),
+    );
+    const before = await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8');
+
+    const result = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    // No destructive step fired: no unlink, no wants removal.
+    expect(result.unlinkedDestinationSymlink).toBe(false);
+    expect(result.removedStaleWantsSymlink).toBe(false);
+    // Identical final state.
+    expect(await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8')).toBe(before);
+    const link = await lstat(join(wantsDir, 'unit-under-test.service'));
+    expect(link.isSymbolicLink()).toBe(true);
+  });
+
+  it('double install on by-path residue converges to the identical reconciled state', async () => {
+    const f = await fixture();
+    await symlink(f.seedTemplate, join(f.activeDir, 'unit-under-test.service'));
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(f.seedTemplate, join(wantsDir, 'unit-under-test.service'));
+
+    await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    const first = await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8');
+    const secondRun = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    const second = await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8');
+    expect(secondRun.unlinkedDestinationSymlink).toBe(false);
+    expect(second).toBe(first);
+  });
+});
+
+describe('resolveLeaseBrokerSocketForPreflight (#1292 preflight resolution)', () => {
+  it('explicit MOSAIC_LEASE_BROKER_SOCKET wins', () => {
+    expect(
+      resolveLeaseBrokerSocketForPreflight({ MOSAIC_LEASE_BROKER_SOCKET: '/custom/sock' }, 1000),
+    ).toBe('/custom/sock');
+  });
+  it('XDG_RUNTIME_DIR next', () => {
+    expect(resolveLeaseBrokerSocketForPreflight({ XDG_RUNTIME_DIR: '/run/user/1001' }, 1000)).toBe(
+      '/run/user/1001/mosaic-lease/broker.sock',
+    );
+  });
+  it('falls back to /run/user/<uid>', () => {
+    expect(resolveLeaseBrokerSocketForPreflight({}, 1002)).toBe(
+      '/run/user/1002/mosaic-lease/broker.sock',
+    );
+  });
+});

packages/mosaic/src/commands/fleet.spec.ts

@@ -835,13 +835,25 @@ describe('fleet command construction', () => {
     };
     const program = new Command();
     program.exitOverride();
-    registerFleetCommand(program, { runner, mosaicHome: home });
+    // #1292: inject a present broker socket so the preflight passes and this
+    // spec keeps testing its ORIGINAL property (holder-before-agent ordering).
+    // The preflight's own refusal behavior has dedicated specs below.
+    registerFleetCommand(program, {
+      runner,
+      mosaicHome: home,
+      checkBrokerSocket: async () => true,
+    });
 
     try {
       await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
       await program.parseAsync(['node', 'mosaic', 'fleet', 'stop']);
 
       expect(calls).toEqual([
+        // #1292: fleet start enables + starts the broker FIRST (enable is
+        // idempotent; the unit exists after install), re-checking the socket
+        // before any holder/agent lifecycle effect.
+        ['systemctl', '--user', 'enable', 'mosaic-lease-broker.service'],
+        ['systemctl', '--user', 'start', 'mosaic-lease-broker.service'],
         ['systemctl', '--user', 'start', 'mosaic-tmux-holder.service'],
         ['systemctl', '--user', 'start', '[email protected]'],
         ['systemctl', '--user', 'stop', '[email protected]'],
@@ -852,6 +864,92 @@ describe('fleet command construction', () => {
     }
   });
 
+  it('fleet start refuses with a named error when the broker socket does not appear (#1292)', async () => {
+    const home = await tempDir();
+    const rosterPath = join(home, 'fleet', 'roster.yaml');
+    await mkdir(join(home, 'fleet'), { recursive: true });
+    await writeFile(
+      rosterPath,
+      ['version: 1', 'transport: tmux', 'agents:', '  - name: coder0', '    runtime: codex'].join(
+        '\n',
+      ),
+    );
+    const calls: string[][] = [];
+    const runner: CommandRunner = async (command, args) => {
+      calls.push([command, ...args]);
+      return { stdout: '', stderr: '', exitCode: 0 };
+    };
+    const program = new Command();
+    program.exitOverride();
+    const errors: string[] = [];
+    const origError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args.join(' '));
+    };
+    registerFleetCommand(program, {
+      runner,
+      mosaicHome: home,
+      checkBrokerSocket: async () => false,
+    });
+    try {
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
+      // Refused: no holder/agent starts were issued after the broker attempt.
+      expect(calls).toEqual([
+        ['systemctl', '--user', 'enable', 'mosaic-lease-broker.service'],
+        ['systemctl', '--user', 'start', 'mosaic-lease-broker.service'],
+      ]);
+      expect(errors.join('\n')).toContain('broker-absent');
+      expect(errors.join('\n')).toContain('mosaic fleet install');
+    } finally {
+      console.error = origError;
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('fleet start re-probes the broker on the SECOND invocation — no ActiveState trust (#1292 sticky half)', async () => {
+    const home = await tempDir();
+    const rosterPath = join(home, 'fleet', 'roster.yaml');
+    await mkdir(join(home, 'fleet'), { recursive: true });
+    await writeFile(
+      rosterPath,
+      ['version: 1', 'transport: tmux', 'agents:', '  - name: coder0', '    runtime: codex'].join(
+        '\n',
+      ),
+    );
+    const calls: string[][] = [];
+    const runner: CommandRunner = async (command, args) => {
+      calls.push([command, ...args]);
+      return { stdout: '', stderr: '', exitCode: 0 };
+    };
+    const program = new Command();
+    program.exitOverride();
+    // Broker socket NEVER appears — the second start must refuse exactly like
+    // the first; RemainAfterExit-style stale unit state changes nothing
+    // because the check is the socket, not systemctl.
+    registerFleetCommand(program, {
+      runner,
+      mosaicHome: home,
+      checkBrokerSocket: async () => false,
+    });
+    const errors: string[] = [];
+    const origError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args.join(' '));
+    };
+    try {
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
+      // Two invocations, each refusing after its own broker attempt:
+      expect(
+        calls.filter((c) => c.join(' ') === 'systemctl --user start [email protected]'),
+      ).toHaveLength(0);
+      expect(errors.filter((e) => e.includes('broker-absent')).length).toBeGreaterThanOrEqual(2);
+    } finally {
+      console.error = origError;
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
   it('waits for an in-flight restart to clear before relaunching (re-entry guard)', async () => {
     const home = await tempDir();
     const rosterPath = join(home, 'fleet', 'roster.yaml');
@@ -2065,8 +2163,19 @@ describe('fleet install — auto-enable units for boot-survival', () => {
 
     await enableFleetUnits(runner, minimalRoster, {});
 
+    expect(calls).toContainEqual(['systemctl', '--user', 'enable', 'mosaic-lease-broker.service']);
     expect(calls).toContainEqual(['systemctl', '--user', 'enable', 'mosaic-tmux-holder.service']);
     expect(calls).toContainEqual(['systemctl', '--user', 'enable', '[email protected]']);
+    // The broker must be enabled BEFORE the holder and agents: a start of any
+    // gated runtime without the broker is exactly the #1292 4-second death.
+    const brokerIndex = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user enable mosaic-lease-broker.service',
+    );
+    const holderIndex = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user enable mosaic-tmux-holder.service',
+    );
+    expect(brokerIndex).toBeGreaterThanOrEqual(0);
+    expect(brokerIndex).toBeLessThan(holderIndex);
   });
 
   it('install still succeeds when systemctl enable returns non-zero (non-fatal)', async () => {

packages/mosaic/src/commands/fleet.ts

@@ -3,9 +3,11 @@ import {
   access,
   chmod,
   copyFile,
+  lstat,
   mkdir,
   open,
   readFile,
+  readlink,
   stat,
   unlink,
   writeFile,
@@ -89,6 +91,8 @@ export type SleepFn = (ms: number) => Promise<void>;
 
 export interface FleetCommandDeps {
   runner?: CommandRunner;
+  /** Test seam for the #1292 fleet-start broker preflight (socket presence). */
+  checkBrokerSocket?: (path: string) => Promise<boolean> | boolean;
   /** Injectable interactive runner for commands needing inherited TTY (e.g., `tmux attach`). */
   interactiveRunner?: InteractiveRunner;
   /**
@@ -797,6 +801,96 @@ export function buildSystemdEnableCommand(unit: string): string[] {
   return ['systemctl', '--user', 'enable', unit];
 }
 
+/**
+ * Place a unit file into the ACTIVE systemd user directory, never through a
+ * symlink (#1292, measured 2026-08-17).
+ *
+ * ⚠ SET-INDEPENDENCE (fomo-lin, 2026-08-17): the set of unit names carrying
+ * by-path residue and the set of unit names this install copies are
+ * INDEPENDENT. Until 0.0.50 they were disjoint only by accident of which
+ * units the install happened to name — fomo-lin survived copy-through solely
+ * because its one by-path symlink (the broker) was the one unit the install
+ * did NOT copy. Adding the broker to the copy set made the intersection
+ * non-empty on the first run. Whoever adds a fifth unit to the placement
+ * list inherits this helper and its unlink step; do not place units with a
+ * bare copyFile.
+ *
+ * A host provisioned by the enable-by-path convention carries a symlink AT
+ * the unit-name path in ~/.config/systemd/user/ pointing at the shipped
+ * template under ~/.config/mosaic/systemd/user/. Node's copyFile FOLLOWS
+ * that link and overwrites the SEED template instead of placing the active
+ * unit (verified with fs.copyFile on a throwaway systemd user instance) —
+ * silent, rc=0, and it mutates the directory every later reseed reads from.
+ * The same measurement showed `systemctl enable <name>` does NOT rewrite an
+ * existing by-path wants-symlink, so reconciliation must be explicit.
+ *
+ * Placement therefore: if the destination is a symlink, unlink it first
+ * (unlink → copy — copy-then-unlink would mutate the seed and then destroy
+ * the evidence that it did); then copy. Also removes a stale
+ * `default.target.wants/<name>` symlink that points outside the active
+ * directory (readlink — NOT readFile, which follows the link and returns the
+ * target's CONTENT), so the subsequent enable-by-name recreates it against
+ * the active copy. Idempotent: on a clean or already-reconciled destination
+ * every step is a no-op (the copy rewrites identical bytes).
+ *
+ * Returns what was done, for assertions and install reporting.
+ */
+export interface PlaceUnitResult {
+  readonly unit: string;
+  readonly destination: string;
+  /** A symlink at the unit-name path was unlinked (by-path residue). */
+  readonly unlinkedDestinationSymlink: boolean;
+  /** A stale wants-symlink pointing outside the active dir was removed. */
+  readonly removedStaleWantsSymlink: boolean;
+}
+
+export async function placeUnitFile(
+  source: string,
+  systemdUserDir: string,
+  unit: string,
+): Promise<PlaceUnitResult> {
+  const destination = join(systemdUserDir, unit);
+  let unlinkedDestinationSymlink = false;
+  try {
+    const destInfo = await lstat(destination);
+    if (destInfo.isSymbolicLink()) {
+      await unlink(destination);
+      unlinkedDestinationSymlink = true;
+    }
+  } catch {
+    // absent destination — nothing to unlink
+  }
+  await copyFile(source, destination);
+
+  let removedStaleWantsSymlink = false;
+  const wantsLink = join(systemdUserDir, 'default.target.wants', unit);
+  try {
+    const wantsInfo = await lstat(wantsLink);
+    if (wantsInfo.isSymbolicLink()) {
+      // readlink — NOT readFile: readFile FOLLOWS the link and returns the
+      // target file's CONTENT, which is not the question being asked.
+      let target: string | undefined;
+      try {
+        target = await readlink(wantsLink);
+      } catch {
+        target = undefined;
+      }
+      // Normalize (systemctl writes absolute targets; a relative one resolves
+      // against the wants dir). A wants-symlink pointing anywhere other than
+      // the active copy (the by-path convention points at the seed template)
+      // survives enable-by-name unchanged — remove it so enable recreates it.
+      if (target !== undefined && resolve(dirname(wantsLink), target) !== destination) {
+        await unlink(wantsLink);
+        removedStaleWantsSymlink = true;
+      }
+    }
+  } catch {
+    // absent wants link — nothing to reconcile
+  }
+
+  return { unit, destination, unlinkedDestinationSymlink, removedStaleWantsSymlink };
+}
+
 /**
  * Returns the systemctl --user disable command for a given unit.
  * Used by `fleet remove` so a removed agent's enabled unit cannot resurrect on
@@ -831,6 +925,22 @@ export async function enableFleetUnits(
     let succeeded = 0;
     let failed = 0;
 
+    // The lease broker ships with the fleet and every gated runtime needs it
+    // (#1292): seats die at lease registration without it, and no documented
+    // path ever enabled it. Enabled first — alongside the holder — and the
+    // unit must have been placed by installFleet's placeUnitFile step.
+    const brokerResult = await runner(
+      ...splitCommand(buildSystemdEnableCommand('mosaic-lease-broker.service')),
+    );
+    if (brokerResult.exitCode === 0) {
+      succeeded++;
+    } else {
+      failed++;
+      process.stderr.write(
+        `Warning: could not enable mosaic-lease-broker.service: ${brokerResult.stderr || brokerResult.stdout || 'non-zero exit'}\n`,
+      );
+    }
+
     const holderResult = await runner(
       ...splitCommand(buildSystemdEnableCommand('mosaic-tmux-holder.service')),
     );
@@ -1527,7 +1637,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Install local fleet tools and user systemd units')
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
-      await installFleet(cmd, frameworkRoot);
+      await installFleet(cmd, frameworkRoot, runner);
       // Unit enablement needs agent names only, so it reads either version.
       const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
@@ -1538,7 +1648,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Install local fleet tools and user systemd units')
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
-      await installFleet(cmd, frameworkRoot);
+      await installFleet(cmd, frameworkRoot, runner);
       // Unit enablement needs agent names only, so it reads either version.
       const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
@@ -1591,6 +1701,37 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
             );
             return;
           }
+          if (action === 'start') {
+            // Broker preflight (#1292), re-probed on EVERY invocation: a
+            // gated runtime started without a live lease broker dies ~4s in
+            // while the unit reports active (RemainAfterExit) — enabling +
+            // starting here and then RE-CHECKING the socket refuses loudly
+            // instead of reporting rc0 over a doomed start. This is the
+            // second-start check as much as the first: it never trusts unit
+            // ActiveState.
+            await runChecked(runner, [
+              'systemctl',
+              '--user',
+              'enable',
+              'mosaic-lease-broker.service',
+            ]);
+            await runChecked(runner, [
+              'systemctl',
+              '--user',
+              'start',
+              'mosaic-lease-broker.service',
+            ]);
+            if (!(await brokerSocketPresent(deps))) {
+              console.error(
+                '[fleet] broker-absent: lease broker socket did not appear after enable+start (#1292).',
+              );
+              console.error(
+                '[fleet] remedy: mosaic fleet install (it reconciles either enable convention)',
+              );
+              process.exitCode = 1;
+              return;
+            }
+          }
           if (action === 'restart') {
             // Serialize the holder+agents teardown/relaunch behind the restart lock
             // so a re-entrant restart waits for clean shutdown before relaunching,
@@ -2349,7 +2490,11 @@ export function registerFleetAgentCommands(
     });
 }
 
-async function installFleet(cmd: Command, frameworkRoot: string): Promise<void> {
+async function installFleet(
+  cmd: Command,
+  frameworkRoot: string,
+  runner: CommandRunner,
+): Promise<void> {
   const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
   assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
   // Read model first: every file this function places is roster-independent, and
@@ -2401,18 +2546,40 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
   for (const toolPath of executableToolPaths) {
     await chmod(toolPath, 0o755);
   }
-  await copyFile(
-    join(frameworkRoot, 'systemd', 'user', 'mosaic-tmux-holder.service'),
-    join(activePaths.systemdUserDir, 'mosaic-tmux-holder.service'),
+  // Unit placement (#1292): every unit goes through placeUnitFile — never a
+  // bare copyFile — so a by-path-enable symlink at the destination is
+  // unlinked rather than written through (copy-through would silently
+  // overwrite the SEED template, measured 2026-08-17). The lease broker unit
+  // is placed here too: previously the install named three units and omitted
+  // the broker entirely, which is why no documented path ever enabled it.
+  const placedUnits = await Promise.all(
+    [
+      'mosaic-tmux-holder.service',
+      '[email protected]',
+      '[email protected]',
+      'mosaic-lease-broker.service',
+    ].map((unit) =>
+      placeUnitFile(join(frameworkRoot, 'systemd', 'user', unit), activePaths.systemdUserDir, unit),
+    ),
   );
-  await copyFile(
-    join(frameworkRoot, 'systemd', 'user', '[email protected]'),
-    join(activePaths.systemdUserDir, '[email protected]'),
-  );
-  await copyFile(
-    join(frameworkRoot, 'systemd', 'user', '[email protected]'),
-    join(activePaths.systemdUserDir, '[email protected]'),
+  const reconciled = placedUnits.filter(
+    (result) => result.unlinkedDestinationSymlink || result.removedStaleWantsSymlink,
   );
+  if (reconciled.length > 0) {
+    console.log(
+      `Reconciled ${reconciled.length} unit placement(s) from by-path enable residue: ${reconciled.map((r) => r.unit).join(', ')}`,
+    );
+  }
+  // systemd will not see a replaced unit file without a reload; do it once
+  // after all placements, before any enable call below. runCommand never
+  // rejects (it resolves exitCode 127 on spawn error), so a plain await with
+  // an exitCode check matches the rest of this file's systemctl handling.
+  const reloadResult = await runner(...splitCommand(['systemctl', '--user', 'daemon-reload']));
+  if (reloadResult.exitCode !== 0) {
+    process.stderr.write(
+      `Warning: systemctl --user daemon-reload after unit placement failed (non-systemd host?): ${reloadResult.stderr || reloadResult.stdout || 'non-zero exit'}\n`,
+    );
+  }
 
   // On roster v2 the reconciler owns the generated env: `apply` writes it and
   // `regen` rebuilds it, both from projectRosterV2AgentGeneratedEnv. Writing it
@@ -2609,6 +2776,40 @@ function splitCommand(command: string[]): [string, string[]] {
   return [bin, args];
 }
 
+/**
+ * Lease-broker socket presence for the fleet-start preflight (#1292).
+ * Resolution precedence matches launch.ts's defaultLeaseBrokerSocket and
+ * start-agent-session.sh's broker_socket_path: explicit
+ * MOSAIC_LEASE_BROKER_SOCKET, else $XDG_RUNTIME_DIR/mosaic-lease/broker.sock,
+ * else /run/user/<uid>/mosaic-lease/broker.sock. Pure filesystem check — this
+ * deliberately does NOT consult systemd state: a unit can be active
+ * (RemainAfterExit) with no live socket, and the socket is the thing the
+ * gated runtime connects to. Injectable via deps for tests.
+ */
+export function resolveLeaseBrokerSocketForPreflight(
+  env: NodeJS.ProcessEnv = process.env,
+  uid: number = typeof process.getuid === 'function' ? process.getuid() : 0,
+): string {
+  if (env['MOSAIC_LEASE_BROKER_SOCKET']) return env['MOSAIC_LEASE_BROKER_SOCKET'];
+  const runtimeDir = env['XDG_RUNTIME_DIR'] ?? `/run/user/${uid}`;
+  return join(runtimeDir, 'mosaic-lease', 'broker.sock');
+}
+
+async function brokerSocketPresent(
+  deps: FleetCommandDeps,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<boolean> {
+  const check = deps.checkBrokerSocket;
+  if (check) return check(resolveLeaseBrokerSocketForPreflight(env));
+  try {
+    const socketPath = resolveLeaseBrokerSocketForPreflight(env);
+    await access(socketPath, constants.S_IFSOCK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** All supported fleet profile names. */
 export type FleetProfile =
   | 'general'

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

@@ -205,6 +205,12 @@ export async function runLeaseEnforcementDoctorCheck(
     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.',
+      // #1292: one remedy, correct under BOTH enable conventions (by-path on
+      // the seed template, and copy-then-enable in the active dir). Written
+      // from the 2026-08-17 symlink measurement: `systemctl enable` by name
+      // does NOT rewrite an existing by-path wants-symlink, so teaching a
+      // manual systemctl line here could leave a host with two competing
+      // wants links. fleet install reconciles either shape.
+      'Remedy: run `mosaic fleet install` (it reconciles either enable convention), or remove the enforcement hooks from ~/.claude/settings.json.',
   };
 }

packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts

@@ -459,6 +459,7 @@ describe('FCM-M3-002 reconciler lifecycle acceptance', (): void => {
       plan: {
         generation: 7,
         holder: 'owned',
+        broker: { unitInstalled: false, socketPresent: false },
         agents: [
           {
             name: 'coder0',

packages/mosaic/src/fleet/fleet-reconciler.spec.ts

@@ -92,6 +92,112 @@ async function run(command: FleetReconcileCommand, overrides: Partial<FleetRecon
 }
 
 describe('fleet roster-owned reconciler', (): void => {
+  // ── #1292: broker as first-class plan member + broker-first start ordering ──
+
+  it('reports broker unit and socket state in the plan (socket is the signal, not unit state)', async (): Promise<void> => {
+    const result = await run('status', {
+      statPath: async () => true,
+      checkBrokerSocket: async () => true,
+    });
+    expect(result.plan.broker).toEqual({ unitInstalled: true, socketPresent: true });
+  });
+
+  it('reports a dead broker as socketPresent=false even when the unit is installed (enabled-but-dead is the #1292 shape)', async (): Promise<void> => {
+    const result = await run('status', {
+      statPath: async () => true,
+      checkBrokerSocket: async () => false,
+    });
+    expect(result.plan.broker).toEqual({ unitInstalled: true, socketPresent: false });
+  });
+
+  it('reports broker-absent when neither seam is present (defaults false, never guesses healthy)', async (): Promise<void> => {
+    const result = await run('status');
+    expect(result.plan.broker).toEqual({ unitInstalled: false, socketPresent: false });
+  });
+
+  it('command start enables and starts the broker BEFORE the holder and any agent unit', async (): Promise<void> => {
+    const calls: string[][] = [];
+    const result = await run('start', {
+      runner: async (command, args) => {
+        calls.push([command, ...args]);
+        if (command === 'tmux' && args.includes('list-sessions')) {
+          return { stdout: '_holder\ncoder0\n', stderr: '', exitCode: 0 };
+        }
+        if (command === 'tmux' && args.includes('show-environment')) {
+          return {
+            stdout:
+              'HOME=/home/mosaic\nMOSAIC_FLEET_OWNER=11111111-1111-4111-8111-111111111111\nMOSAIC_TMUX_HOLDER=_holder\nMOSAIC_TMUX_SOCKET=mosaic-fleet\nPATH=/usr/bin:/bin\nPWD=/home/mosaic\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    });
+    expect(result.lifecycle).toBe('complete');
+    const brokerEnable = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user enable mosaic-lease-broker.service',
+    );
+    const brokerStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start mosaic-lease-broker.service',
+    );
+    const holderStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start mosaic-tmux-holder.service',
+    );
+    const agentStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start [email protected]',
+    );
+    expect(brokerEnable).toBeGreaterThanOrEqual(0);
+    expect(brokerStart).toBeGreaterThan(brokerEnable);
+    // Holder start may be absent (holder 'owned' in this fixture); if present it must follow the broker.
+    if (holderStart >= 0) expect(holderStart).toBeGreaterThan(brokerStart);
+    expect(agentStart).toBeGreaterThan(brokerStart);
+  });
+
+  it('apply with a running desired agent also enables and starts the broker first', async (): Promise<void> => {
+    const calls: string[][] = [];
+    const runningRoster: FleetRosterV2 = {
+      ...roster,
+      agents: roster.agents.map((agent) =>
+        agent.name === 'coder0'
+          ? { ...agent, lifecycle: { enabled: true, desiredState: 'running' as const } }
+          : agent,
+      ),
+    };
+    const result = await executeFleetReconcile({
+      roster: runningRoster,
+      command: 'apply',
+      expectedGeneration: 7,
+      deps: deps({
+        readRoster: async () => runningRoster,
+        runner: async (command, args) => {
+          calls.push([command, ...args]);
+          if (command === 'tmux' && args.includes('list-sessions')) {
+            return { stdout: '_holder\n', stderr: '', exitCode: 0 };
+          }
+          if (command === 'tmux' && args.includes('show-environment')) {
+            return {
+              stdout:
+                'HOME=/home/mosaic\nMOSAIC_FLEET_OWNER=11111111-1111-4111-8111-111111111111\nMOSAIC_TMUX_HOLDER=_holder\nMOSAIC_TMUX_SOCKET=mosaic-fleet\nPATH=/usr/bin:/bin\nPWD=/home/mosaic\n',
+              stderr: '',
+              exitCode: 0,
+            };
+          }
+          return { stdout: '', stderr: '', exitCode: 0 };
+        },
+      }),
+    });
+    expect(result.applied).toBe(true);
+    const brokerStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start mosaic-lease-broker.service',
+    );
+    const agentStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start [email protected]',
+    );
+    expect(brokerStart).toBeGreaterThanOrEqual(0);
+    expect(agentStart).toBeGreaterThan(brokerStart);
+  });
+
   it('fails closed on a symlinked fleet ancestor without touching its target', async (): Promise<void> => {
     const home = await lockHome();
     const fleet = join(home, 'fleet');

packages/mosaic/src/fleet/fleet-reconciler.ts

@@ -43,6 +43,10 @@ export interface FleetReconcileDeps {
   readonly overrideDir?: string;
   readonly homeDirectory?: string;
   readonly readHolderIdentity?: () => Promise<string>;
+  /** Test/observation seams for the lease-broker plan member (#1292). */
+  readonly statPath?: (path: string) => Promise<boolean> | boolean;
+  readonly checkBrokerSocket?: (path: string) => Promise<boolean> | boolean;
+  readonly brokerSocketEnv?: NodeJS.ProcessEnv;
   readonly validateRoster?: (roster: FleetRosterV2) => Promise<void>;
   readonly prepareProjections?: (roster: FleetRosterV2) => Promise<readonly unknown[]>;
   readonly applyProjection?: (prepared: unknown) => Promise<unknown>;
@@ -74,6 +78,17 @@ export interface FleetReconcileObservedAgent {
 export interface FleetReconcilePlan {
   readonly generation: number;
   readonly holder: 'owned' | 'missing' | 'ownership-mismatch';
+  /**
+   * Lease broker observation (#1292): every gated runtime registers with the
+   * broker or dies ~4s in — a broker not in the plan cannot be reported as
+   * drifted, which made "broker died an hour ago" and "broker fine"
+   * produce identical output. `unitInstalled` = unit file present in the
+   * active dir; `socketPresent` = live broker at the resolved socket path.
+   */
+  readonly broker: {
+    readonly unitInstalled: boolean;
+    readonly socketPresent: boolean;
+  };
   readonly agents: readonly FleetReconcileObservedAgent[];
   readonly unmanagedSessions: readonly string[];
 }
@@ -314,6 +329,39 @@ function isObservational(command: FleetReconcileCommand): boolean {
   return command === 'plan' || command === 'status' || command === 'verify' || command === 'doctor';
 }
 
+/**
+ * Observe the lease broker for the plan (#1292). Unit presence via systemctl
+ * is-system-running is NOT the signal — a unit can be enabled-but-dead. The
+ * authoritative signal is the socket the gated runtimes connect to, matching
+ * broker-supervisor.ts's `checkBrokerSupervisorHealth` (healthy ===
+ * socketPresent). Injectable so tests drive every branch without a broker.
+ */
+async function observeBroker(deps: FleetReconcileDeps): Promise<FleetReconcilePlan['broker']> {
+  const homeDirectory = deps.homeDirectory ?? homedir();
+  const env = (deps.brokerSocketEnv ?? process.env) as NodeJS.ProcessEnv;
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+  const runtimeDir = env['XDG_RUNTIME_DIR'] ?? `/run/user/${uid}`;
+  const socketPath =
+    env['MOSAIC_LEASE_BROKER_SOCKET'] ?? join(runtimeDir, 'mosaic-lease', 'broker.sock');
+  const configHome = env['XDG_CONFIG_HOME'] ?? join(homeDirectory, '.config');
+  const unitPath = join(configHome, 'systemd', 'user', 'mosaic-lease-broker.service');
+  const statPath = deps.statPath;
+  const checkBrokerSocket = deps.checkBrokerSocket;
+  let unitInstalled = false;
+  let socketPresent = false;
+  try {
+    unitInstalled = statPath ? await statPath(unitPath) : false;
+  } catch {
+    unitInstalled = false;
+  }
+  try {
+    socketPresent = checkBrokerSocket ? await checkBrokerSocket(socketPath) : false;
+  } catch {
+    socketPresent = false;
+  }
+  return { unitInstalled, socketPresent };
+}
+
 async function observeFleet(
   roster: FleetRosterV2,
   deps: FleetReconcileDeps,
@@ -324,10 +372,12 @@ async function observeFleet(
     '-F',
     '#{session_name}',
   ]);
+  const broker = await observeBroker(deps);
   if (sessionsResult.exitCode !== 0) {
     return {
       generation: roster.generation,
       holder: 'missing',
+      broker,
       agents: await observeAgents(roster, deps, new Set<string>()),
       unmanagedSessions: [],
     };
@@ -350,6 +400,7 @@ async function observeFleet(
   return {
     generation: roster.generation,
     holder,
+    broker,
     agents: await observeAgents(roster, deps, sessions),
     unmanagedSessions: Object.freeze(unmanagedSessions.sort()),
   };
@@ -517,6 +568,24 @@ async function executeExplicitLifecycle(
     }
   }
   try {
+    // Broker FIRST (#1292): a gated runtime started without a running lease
+    // broker dies ~4 seconds in at registration — enable the unit (install
+    // places it) and start it before any holder/agent lifecycle effect. The
+    // socket re-check after start is the same probe observeBroker uses, so a
+    // unit that starts but never produces a socket is caught here, not four
+    // seconds later inside a doomed seat.
+    if (request.command === 'start') {
+      await runChecked(request.deps, 'systemctl', [
+        '--user',
+        'enable',
+        'mosaic-lease-broker.service',
+      ]);
+      await runChecked(request.deps, 'systemctl', [
+        '--user',
+        'start',
+        'mosaic-lease-broker.service',
+      ]);
+    }
     if (request.command === 'start' && plan.holder === 'missing') {
       await runChecked(request.deps, 'systemctl', [
         '--user',
@@ -562,6 +631,12 @@ async function applyDesiredLifecycle(
     (agent: FleetRosterV2Agent): boolean =>
       agent.lifecycle.enabled && agent.lifecycle.desiredState === 'running',
   );
+  // Broker before any running agent, same ordering and reason as the
+  // command-driven path above (#1292).
+  if (needsRunningAgent) {
+    await runChecked(deps, 'systemctl', ['--user', 'enable', 'mosaic-lease-broker.service']);
+    await runChecked(deps, 'systemctl', ['--user', 'start', 'mosaic-lease-broker.service']);
+  }
   if (needsRunningAgent && plan.holder === 'missing') {
     await runChecked(deps, 'systemctl', ['--user', 'start', 'mosaic-tmux-holder.service']);
   }