test(gateway): size the enrollment clamp tolerance to CI jitter, not to a fast machine

Closes #1090.

`clamps ttlSeconds to 900` asserted a wall-clock delta against a fixed 100 ms
budget:

    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + 100);

That budget covers everything between `Date.now()` and the service computing
`expiresAt`. On a loaded CI agent — this step runs alongside a Postgres service
container and several other workspaces — it came back at 900_106 and failed by
6 ms (#1090, observed on pipeline 2258).

The property under test is CLAMPING: a 9999s request must come back as 900s.
The gap between clamped and unclamped is 9_099_000 ms, so the tolerance only has
to exceed scheduler jitter to stay discriminating:

    clamped   ~900_000 ms   <= 905_000 ✓   < 1_000_000 ✓
    unclamped ~9_999_000 ms <= 905_000 ✗   < 1_000_000 ✗

A 5s allowance consumes 0.055% of that margin, and an unclamped implementation
still misses by three orders of magnitude.

Also pins the clamp explicitly with `toBeLessThan(1_000_000)`, so the property
is asserted independently of any timing allowance — widening the jitter budget
later cannot silently weaken it.

NOT DONE: I could not execute vitest here (no node_modules; a full install is
minutes). The discrimination argument above is arithmetic, not an executed
red/green. A reviewer should run the suite, and if it is cheap, confirm that
removing the clamp in the service still fails this test.

apps/gateway/src/federation/__tests__/enrollment.service.spec.ts

@@ -245,9 +245,21 @@ describe('EnrollmentService.createToken', () => {
     const after = Date.now();
 
     const expiresMs = new Date(result.expiresAt).getTime();
-    // Should be at most 900s from now
+
-    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + 100);
+    // The property under test is CLAMPING: a 9999s request must come back as 900s.
+    // The gap between clamped and unclamped is 9_099_000 ms, so the tolerance below
+    // only has to exceed CI scheduling jitter — it does not need to be tight to keep
+    // the assertion discriminating. A 5s allowance consumes 0.05% of that margin and
+    // an unclamped result still misses by three orders of magnitude.
+    //
+    // It was 100ms and failed on a loaded agent at 900_106 — 6ms over (#1090). A
+    // wall-clock budget sized to a fast machine is a flake, not a tighter test.
+    const CI_JITTER_MS = 5_000;
+    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + CI_JITTER_MS);
     expect(expiresMs - after).toBeGreaterThanOrEqual(0);
+    // Explicitly pin the clamp itself, independent of any timing allowance:
+    // unclamped (9999s) would exceed this by ~9_099_000 ms.
+    expect(expiresMs - before).toBeLessThan(1_000_000);
   });
 });
 

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

@@ -5,7 +5,10 @@
 
 detect_platform() {
     local remote_url
-    remote_url=$(git remote get-url origin 2>/dev/null)
+    # `|| true` is load-bearing under `set -e`: outside a git repo this returns 128 and
+    # kills the CALLER before the -z check below can run, so the error message that is
+    # already written here was unreachable. Same idiom as get_gitea_repo_args() below.
+    remote_url=$(git remote get-url origin 2>/dev/null) || true
 
     if [[ -z "$remote_url" ]]; then
         echo "error: not a git repository or no origin remote" >&2
@@ -39,7 +42,10 @@ detect_platform() {
 
 get_repo_info() {
     local remote_url
-    remote_url=$(git remote get-url origin 2>/dev/null)
+    # `|| true` is load-bearing under `set -e`: outside a git repo this returns 128 and
+    # kills the CALLER before the -z check below can run, so the error message that is
+    # already written here was unreachable. Same idiom as get_gitea_repo_args() below.
+    remote_url=$(git remote get-url origin 2>/dev/null) || true
 
     if [[ -z "$remote_url" ]]; then
         echo "error: not a git repository or no origin remote" >&2
@@ -240,6 +246,21 @@ PY
     } >&2
 }
 
+# Explain tea's most misleading failure. `user does not exist [uid: 0, name: ]` reads
+# as a missing account; it almost always means a REVOKED OR STALE TOKEN. `tea login`
+# keeps its OWN COPY of the token, so rotating the credential store does not update it.
+# Diagnostic only -- stderr, no control flow, no exit.
+explain_tea_user_does_not_exist() {
+    cat >&2 <<'MSG'
+NOTE: `user does not exist [uid: 0, name: ]` from tea usually means a REVOKED OR STALE TOKEN,
+      not a missing account. A `tea login` stores its OWN COPY of the token; rotating the
+      credential store does NOT update it.
+      CHECK: the login's cached copy (`tea login list` -- read the FULL table, never `| head`),
+             then re-register that login against the current token.
+      DO NOT probe capability with a mutating request; a POST is the action, not a check.
+MSG
+}
+
 get_gitea_login_for_host() {
     local host="${1:-}"
     local login

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

@@ -156,6 +156,7 @@ case "$PLATFORM" in
                 exit 0
             fi
             echo "Warning: tea issue create failed, trying Gitea API fallback..." >&2
+            { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
         fi
         gitea_issue_create_api
         ;;

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

@@ -71,6 +71,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             exit 0
         fi
         echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2
+        { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
     fi
     gitea_issue_view_api
 else

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

@@ -219,6 +219,7 @@ case "$PLATFORM" in
             exit 0
         fi
         echo "Warning: tea pr create failed, trying Gitea API fallback..." >&2
+        { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
         gitea_pr_create_api
         ;;
     *)

packages/mosaic/framework/tools/git/test-detect-platform-outside-repo.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Regression: detect_platform / get_repo_info must FAIL LOUDLY outside a git repo,
+# not kill the caller silently.
+#
+# Both functions already contained the right error path:
+#     if [[ -z "$remote_url" ]]; then echo "error: not a git repository..." >&2; return 1; fi
+# but under `set -e` -- which every wrapper in this directory uses -- the preceding
+# assignment `remote_url=$(git remote get-url origin 2>/dev/null)` returns git's 128
+# outside a repo and terminates the CALLER first. The message was unreachable.
+#
+# Observed cost: pr-review.sh invoked from a non-repo cwd exits 128 with NO stdout and
+# NO stderr, even when -r/--repo and -H/--host are supplied -- the flags documented as
+# "skips git-remote inference". Two reviewer seats hit this and correctly reported
+# `blocked` with no diagnostic to report.
+#
+# The control that matters is the LOUD one: asserting "rc != 0" passes on the broken
+# build too, because 128 is also non-zero. The test must assert the MESSAGE.
+set -uo pipefail
+fail=0
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+
+run_outside() { # $1=function name -> "rc:sawmessage"
+    local fn="$1" out rc
+    out=$( cd "$TMP" && bash -c "set -e; source '$HERE/detect-platform.sh'; $fn" 2>&1 ); rc=$?
+    printf '%s:%s' "$rc" "$(grep -qi 'not a git repository' <<<"$out" && echo yes || echo no)"
+}
+check() { if [ "$2" = "$3" ]; then echo "  PASS  $1 ($2)"; else echo "  FAIL  $1: got $2, want $3"; fail=1; fi; }
+
+# $TMP must not be inside a git repo. Do not SKIP on failure: be-coder-07 showed the
+# original SKIP exited 0, so pointing TMPDIR beneath a git worktree made this test PASS
+# against unchanged main. A skip that exits 0 is indistinguishable from a pass.
+# GIT_CEILING_DIRECTORIES stops git walking above $TMP, making the condition hold
+# regardless of where TMPDIR lives, rather than merely detecting when it does not.
+# GIT_CEILING_DIRECTORIES is matched against the PHYSICAL path -- a symlinked TMPDIR
+# (/tmp is commonly one) makes the logical path never match, and the ceiling silently
+# does nothing. Resolve it before exporting.
+TMP="$(cd "$TMP" && pwd -P)"
+export GIT_CEILING_DIRECTORIES="$TMP"
+if ( cd "$TMP" && git rev-parse --git-dir >/dev/null 2>&1 ); then
+    echo "  FAIL  scratch dir is inside a git repo even with GIT_CEILING_DIRECTORIES set;"
+    echo "        the outside-a-repo precondition cannot be established -- refusing to report a result"
+    exit 1
+fi
+
+echo "== outside a git repo: rc=1 AND the diagnostic is emitted =="
+check "detect_platform" "$(run_outside detect_platform)" "1:yes"
+check "get_repo_info"   "$(run_outside get_repo_info)"   "1:yes"
+
+echo "== inside a git repo the functions still work =="
+git init -q "$TMP/repo" 2>/dev/null
+git -C "$TMP/repo" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git 2>/dev/null
+out=$( cd "$TMP/repo" && bash -c "set -e; source '$HERE/detect-platform.sh'; detect_platform" 2>&1 ); rc=$?
+if [ "$rc" -eq 0 ] && grep -qi 'gitea' <<<"$out"; then echo "  PASS  detect_platform in-repo (rc=0, $out)"
+else echo "  FAIL  detect_platform in-repo: rc=$rc out=$out"; fail=1; fi
+
+[ "$fail" -eq 0 ] && echo "OK  detect-platform fails loudly outside a repo" || echo "FAILED"
+exit "$fail"

packages/mosaic/framework/tools/git/test-explain-diagnostic-status-neutral.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Regression: the tea-failure diagnostic must be STATUS-NEUTRAL.
+#
+# Found by be-coder-08 reviewing PR #1086. At all three call sites the diagnostic is emitted
+# immediately BEFORE the Gitea API fallback. Written as the last command of an && list:
+#     declare -F explain_... >/dev/null && explain_...
+# under `set -e` a FAILING diagnostic exits and the fallback never runs -- a diagnostic that
+# suppresses the recovery path it exists to explain. It misbehaves ONLY when the helper is
+# PRESENT, so the helper-absent path (pre-#1086 behaviour) keeps working and reads as a
+# passing control.
+#
+# TWO DEFECTS IN THE FIRST VERSION OF THIS TEST, both found by be-coder-08:
+#   1. `out=$( ... ) 2>"$errto"` applies the redirection to the ASSIGNMENT, not to the
+#      command substitution, so the probe's stderr was never actually pointed at /dev/full
+#      and the /dev/full rows proved nothing. Verified: `out=$(echo x >&2) 2>/dev/full`
+#      leaks to the terminal and returns 0; the redirect must be INSIDE the substitution.
+#   2. `eval "$CONSTRUCT"` changes `set -e` semantics for a bare && list, so the probe did
+#      not exercise the construct as the shipped file executes it. It now writes the line
+#      into a real script and runs it -- same parse, same set -e rules, no eval.
+# The construct is still LIFTED FROM THE SHIPPED FILE: retyping the fixed form makes the
+# probe pass on a build whose real call sites still carry the bare && form.
+set -uo pipefail
+fail=0
+GIT_DIR_UNDER_TEST="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+
+probe() { # $1=present|absent  $2=stderr target  $3=source file  -> "rc:fallback"
+    local helper="$1" errto="$2" src="$3" construct script out rc
+    construct=$(grep -m1 'explain_tea_user_does_not_exist' "$GIT_DIR_UNDER_TEST/$src" | sed 's/^[[:space:]]*//')
+    [ -n "$construct" ] || { printf 'no-construct:no'; return; }
+    script="$TMP/probe.sh"
+    {
+        echo '#!/bin/bash'
+        echo 'set -e'
+        echo 'explain_tea_user_does_not_exist() { echo "diagnostic" >&2; }'
+        [ "$helper" = absent ] && echo 'unset -f explain_tea_user_does_not_exist'
+        echo "$construct"                # the shipped line, parsed by a real shell
+        echo 'echo FALLBACK_REACHED'
+    } > "$script"
+    # redirect INSIDE the substitution so the subshell's stderr really is $errto
+    out=$( bash "$script" 2>"$errto" ); rc=$?
+    printf '%s:%s' "$rc" "$(grep -q FALLBACK_REACHED <<<"$out" && echo yes || echo no)"
+}
+
+check() { if [ "$2" = "$3" ]; then echo "  PASS  $1 ($2)"; else echo "  FAIL  $1: got $2, want $3"; fail=1; fi; }
+
+echo "== diagnostic must not alter exit status or skip the fallback =="
+# /dev/full makes every stderr write fail -- the real-world shape is a closed or full fd.
+for src in pr-create.sh issue-view.sh issue-create.sh; do
+    check "$src stderr OK      / helper present" "$(probe present /dev/null "$src")" "0:yes"
+    check "$src stderr OK      / helper absent " "$(probe absent  /dev/null "$src")" "0:yes"
+    check "$src stderr FAILING / helper present" "$(probe present /dev/full "$src")" "0:yes"
+    check "$src stderr FAILING / helper absent " "$(probe absent  /dev/full "$src")" "0:yes"
+done
+
+echo "== all three call sites use the status-neutral form =="
+for f in pr-create.sh issue-view.sh issue-create.sh; do
+    p="$GIT_DIR_UNDER_TEST/$f"
+    grep -q '{ declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true' "$p" \
+        && echo "  PASS  $f guarded" || { echo "  FAIL  $f: diagnostic is not status-neutral"; fail=1; }
+done
+
+[ "$fail" -eq 0 ] && echo "OK  diagnostic is status-neutral" || echo "FAILED"
+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/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-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/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"
+    "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/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-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-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.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"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",