[qingyun-wu]

What changed, and why

After a move from ag2.space to s.space, the s.space row is primary and the legacy ag2.space row is parked. Several readers still assumed the legacy unsuffixed bridge was the install's gateway:

Reader (origin/main)	What it did	Now
src/health-check.py check_gateway_bridge and the sidecar readers _gateway_last_ok_age_h, check_runtime_identity, _gateway_status_stale_age_s, _gateway_status_ts_malformed, _gateway_serving (each defaulted to gateway-status.json)	read the parked legacy bridge's stale sidecar as the primary and warned "…ag2.space mobile messages may not be delivered"	read the primary row's sidecar (connections.sidecar_name(primary.instance)). Lane scans skip the primary's own lane and every parked or disabled row's lane, found by walking the rows with status_for. Messages name the primary's server, and lanes read as lane (server)
_gateway_configured (health-check), _gateway_configured (src/runtime-health.py), navigateUiAvailable (skills/ag2space-voice/navigate.ts)	true only for the legacy env key or channels/ag2space/.env, so a fresh s.space-only install read as unconfigured	also true when any enabled row exists (neither disabled nor parked), through one helper, connections.enabled_rows. The TS side asks it through the CLI (scripts/connections.py enabled) instead of copying the rule
src/dotspace.py current_server → default_link_via / default_cloud_origin fell back to LEGACY_SERVER	an install with no AGENT_MXID linked via ag2.space	callers pass primary_server=; dotspace stays stdlib-only and reads no record. Vendored copy synced with tools/sync_from_src.py (drift test green). src/ag2space_links.py passes it, behind a guarded import so a skill without core still falls back
scripts/sutando-whoami.sh, src/runtime-api/rundir.py enrolled_agent_id	reported the device env / enrollment record's agent	the primary row's agent_mxid first, then the old sources

Primary-row helpers in src/connections.py, for other connections work to reuse: this branch uses the read-only primary_row(workspace) that #5980 added on main, and adds read_rows(workspace) (every row, read-only, never imports from the environment, unlike list_connections), primary_server(workspace), enabled_rows(workspace) and sidecar_name(instance). _sidecar now uses sidecar_name. None of them touches launch_env or room-to-connection resolution.

The user-facing health-check wording became server-neutral here, not in the docs PR, because this PR rewrites those lines: GATEWAY_DOWN_DETAIL, the not-serving/stale details, and "gateway not configured on this host". The health-check fragments in tests/dotspace-literal-guard.test.py's allowlist are now unused. They are left in place so this PR does not conflict with the docs PR's edit to the neighbouring allowlist line.

Where to look first

src/health-check.py (new _gateway_* helpers before GATEWAY_STATUS_MAX_AGE_S, the default-path readers, the lane skips), then src/connections.py (helpers after primary_instance), then src/dotspace.py current_server.

Evidence (before / after)

A moved install: s.space primary, ag2.space legacy row parked with a day-old gateway-status.json, a fresh gateway-status.s-space.json, no legacy token anywhere. Same script against origin/main and this branch:

== origin/main
configured (s.space-only rows, no legacy token): False
gateway-bridge: {'status': 'warn', 'detail': 'process running but its status sidecar has not been written for 86400s (freshness window 180s) — the bridge is not reporting poll outcomes, so ag2.space mobile messages may not be delivered'}
== this branch
configured (s.space-only rows, no legacy token): True
gateway-bridge: {'status': 'ok', 'detail': 'running + connected (s.space)'}

The new suite at origin/main: FAILED (failures=3, errors=13). At HEAD: OK (16 tests). Mutation check: reverting only the sidecar default path to gateway-status.json fails the moved-install, silent-primary and three-server cases.

Tests

New, tests/health-check-gateway-primary-connection.test.py:

• moved install: parked legacy row with a stale status file gives no warning. A parked named row is no stalled lane. A silent primary is still reported by its server. check_runtime_identity reads the primary sidecar.
• s.space-only: health-check and runtime-health count it as configured. connections.py enabled exits 0 with s-space. Parked or disabled rows alone configure nothing (exit 1).
• three servers (ag2.space parked, s.space secondary, dev.s.space primary): dev.s.space is read as the primary and s.space as a lane (lane s-space (s.space)). primary_server drives current_server and default_link_via.
• read helpers never import from the environment, and an unreadable record reads as none. current_server precedence: mxid, then gateway, then primary, then "", and an invalid primary is ignored. default_cloud_origin(primary_server=) stays within configured entries. Links use the primary. rundir reads the primary, then the enrollment record, and falls back when the record raises.

Updated: tests/ag2space-voice-navigate.test.ts (connection-only install offers navigation. enabledConnectionExists against a real record: no record, parked plus disabled, s.space-only), tests/sutando-whoami.test.sh (primary row's agent wins), tests/health-check-gateway-bridge.test.py (pins an empty workspace so the host's own rows never leak into the legacy-token cases).

python3 tests/health-check-gateway-primary-connection.test.py    OK (16)
npx tsx --test tests/ag2space-voice-navigate.test.ts             pass 38/38 (the new cases included)
bash tests/sutando-whoami.test.sh                                PASS
274 suite files matching health-check* / connections* / dotspace* / runtime-* / ag2space-* / gateway-* / ag2-sparrow-drift / util-paths-runtime* / core-health* / skill-usage*, plus whoami and rundir-resolver: 272 pass, 2 fail (both below)
npm run typecheck && npm run typecheck:skills                   rc 0
npx eslint (changed TS)                                          rc 0
bash scripts/review-checks.sh --diff <(git diff origin/main...HEAD)   PASS
python3 tests/hermetic-env-structural.test.py                    OK
python3 scripts/hermetic-workspace-guard.py run <new suite>      OK
python3 scripts/lint-hermetic-bridge-tests.py                    ok
python3 skills/release/scripts/docs_audit.py                     PASS
diff-cover (coverage over the touched suites) vs origin/main     95%+: connections, dotspace, ag2space_links, runtime-health, scripts/connections.py 100%; rundir 100% after the added fallback case

tests/health-check-fix-down-bridges.test.py case f fails identically on origin/main on a host whose own Slack bridge is running. That is a pre-existing host dependence and not touched here. tests/runtime-api-request-expiry.test.py failed once during the long batch run and passes when run alone (rc 0). In CI, tests/remote-gateway-bridge.test.py (python shard 1/9) also fails on main at b72b5ca, before this PR.

Feature/documentation consistency

docs/connections.md documents the read-only helpers, the enabled CLI verb and what the health check reads. docs/dotspace.md documents primary_server=. docs/catalog.json dates are bumped.

Risks / edge cases

• Runtime identity moves with the primary. rundir.enrolled_agent_id now prefers the primary row's agent, so the per-actor run dir key follows a primary flip. A runtime daemon started before the flip keeps its old socket until it restarts. util_paths' canonical actor uses the same function, so the two sides agree.
• cloud_auth.DEFAULT_CLOUD_ORIGIN is deliberately unchanged. For every registered server without its own Cloud the answer is the same, and changing the credential owner's default deserves its own review.
• Without a connections record, every reader behaves exactly as before (legacy sidecar, legacy tokens).

Follow-ups

• --notify-gateway (_gateway_creds and the alert path) belongs to the shared room/connection resolver work (fix(connections): room tools act through the connection serving the room's server #5977 / fix(connections): every gateway client acts through the room's own connection #5980, now on main) and is deliberately not touched here.
• Once both PRs land, drop the unused health-check fragments from tests/dotspace-literal-guard.test.py.

🤖 Generated with Claude Code

[liususan091219]

Requesting changes: the health-check readers now follow the primary row, but two sibling readers of the same sidecar are left on the legacy file.

• Bandaid, sibling sites: src/core-input-watch.py:529 (_gateway_status, which feeds gateway_alive() and so the core's gateway-down state) and src/services_status.py:73 (GATEWAY_STATUS_PATH, the desktop services row) still hard-code gateway-status.json. On the moved install this PR targets, that file is the parked bridge's stale sidecar, so both always read "no opinion" and fall back to the identity-blind pgrep their own docstrings call a proxy for the wrong thing. connections.sidecar_name(primary.instance) added here is the fix for both. Please move them too, or file an issue and name them under Follow-ups.
• Nit, non-blocking: _gateway_lane_label(ln) without rows (src/health-check.py:6956, :6958, :6966) runs _gateway_rows(), which calls status_for (sidecar read plus lease probe) on every row, once per lane. _gateway_lanes_not_served also needs only the raw primary/disabled/parked flags, so read_rows would do.
• Checked, fine: disabled rows derive state == "parked" (derive_state), so the lane skip covers both, as the body says. Tests import and exercise the real modules, with no source-text assertions. The new suite and health-check-gateway-bridge pass locally at head. The SUTANDO_WORKSPACE in tests/sutando-whoami.test.sh is a test-mode fixture, not a default.
• CI: python shard 1/9 fails on tests/remote-gateway-bridge.test.py. It also failed on main at b72b5ca, and main fixed it in 9826add (#5984). A rebase should clear it. license/cla is present.
• There are no approvals yet.

— Sutando (susans-MacBook-Pro)

[qingyun-wu]

Addressed in 8881b56 (main merged in):

• Sibling sites: core-input-watch (_gateway_status, so gateway_alive()) and services_status (the services row; GATEWAY_STATUS_PATH replaced by gateway_status_path()) now read the primary's sidecar. All three readers share one resolver, connections.primary_sidecar_name(state_dir), and health-check's own helper delegates to it. A sweep of gateway-status readers found no others needing the primary: the rest are the bridge writer, instance-aware hatch readers, and glob-all-lanes scans.
• Nit: the lane label and lane skip now use stored rows (read_rows plus the raw primary/parked/disabled flags), with no sidecar read or lease probe per lane.
• Tests cover both readers against a moved install, the unreadable-record fallback, and the no-probe rows.

[github-actions]

@cla-assistant check

[github-actions]

Coverage Gate

✅ Diff coverage PASSES the 95% bar. Whole-tree (informational): 94%.

Diff Coverage

Diff: origin/main...HEAD, staged and unstaged changes

• scripts/connections.py (100%)
• src/ag2space_links.py (100%)
• src/connections.py (100%)
• src/core-input-watch.py (100%)
• src/dotspace.py (100%)
• src/health-check.py (100%)
• src/runtime-api/rundir.py (100%)
• src/runtime-health.py (100%)
• src/services_status.py (100%)

Summary

• Total: 100 lines
• Missing: 0 lines
• Coverage: 100%