docs(remote-mcp): restamp the #956 threat model onto the commit it resolves at (review 637 B1)

Commit 126d76a set docs/remote-mcp/threat-model-anchors.json
generated_against_commit to e3fa3b26 and left docs/remote-mcp/threat-model.md
citing a143cd06, so the document and the fixture named different source
revisions. tests/test_issue_956_threat_model.py asserts the fixture value
appears in the document, and that assertion failed from 126d76a onward.

The mismatch was not cosmetic. Resolving all 58 anchors against each candidate
revision shows 0 unresolved at e3fa3b26 and 21 unresolved at a143cd06, so the
document's own claim about where its file:line citations resolve was false.
The fixture held the accurate value and the document held the stale one.

The B2 fix in ca5f078d inserted a net 16 lines into gitea_mcp_server.py at a
single point, shifting 21 anchors below it. All 21 are re-derived here by that
one uniform offset and each was verified against its recorded expect substring
rather than assumed, so no anchor is guessed and none became ambiguous. Both
artifacts now name ca5f078d, the commit those anchors were taken at, and the
document's inline citations are shifted to match. The boundary table's claim
about what the code enforces is restamped onto the same revision, because it
described that same source tree.

Verified: 58/58 anchors resolve at the declared generation commit, 58/58 at
this head, no two anchors share a file:line location, fixture and document
metadata agree, and tests/test_issue_956_threat_model.py passes 17/17.

Refs #708

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

docs/mcp-namespace-health.md

@@ -86,3 +86,74 @@ When a namespace returns EOF, follow
 
 When blocked, repair the IDE namespace and re-record a healthy
 `client_namespace` assessment before retrying the mutation.
+
+## Connected vs Attached Tool Surface (#708)
+
+MCP servers can report **Connected** at the CLI / host inventory layer while the **active LLM session exposes none of their tool namespaces**.
+
+### Core principle
+
+* **Connected status at host layer ≠ attached tools in active session.**
+* Required preflight proof is **live tool visibility + `gitea_whoami` call** through the target namespace, not host `Connected` status alone.
+* When servers report Connected but namespaces are absent from attached tools, classify as `mcp_connected_namespaces_missing`.
+
+### Forbidden unsafe fallbacks
+
+When `mcp_connected_namespaces_missing` is detected, workflows must **fail closed** and must **never** encourage or perform:
+
+* direct imports of MCP server Python modules
+* CLI or raw Gitea API mutations as a substitute for native tools
+* profile hopping to another MCP profile/namespace to bypass the empty session
+* session-state overrides or hand-edited session/ledger files
+* process kills (`pkill`), config mtime touches, or `.env` edits
+
+Only sanctioned recovery: **client reconnect path**, followed by full preflight (`whoami` → capability resolve → task).
+
+### Native detection tool
+
+`gitea_assess_mcp_namespace_attachment` classifies the condition and records it in
+the session. Pass the namespaces the host reports Connected and the namespaces
+actually attached to the active session tool surface:
+
+| Argument | Meaning |
+|---|---|
+| `connected_servers` | Namespaces the host/CLI reports Connected |
+| `attached_session_namespaces` | Namespaces exposed in the active session tool surface |
+| `required_namespaces` | Namespaces this workflow needs (defaults to the role namespaces) |
+| `discovery_cache_hit` / `discovery_cache_age_seconds` | Client tool-discovery cache state |
+| `auto_attach_attempted` / `auto_attach_succeeded` | Whether the runtime auto-attached |
+| `session_tool_snapshot_at` / `namespace_connected_at` | Epoch seconds, to detect startup ordering races |
+
+It returns `discovery_status`
+(`namespaces_attached` | `connected_but_namespaces_missing` | `disconnected`),
+`missing_namespaces`, `proof_of_connected_vs_attached` (per namespace
+`{connected, attached}`), `error_type`, `reconnect_required`, `auto_recovered`,
+`startup_ordering_race`, `late_attaching_namespaces`, `sanctioned_recovery_tool`,
+and a reconnect-only `exact_next_action`.
+
+### Startup ordering
+
+`session_tool_snapshot_at` earlier than a namespace's `namespace_connected_at`
+means that namespace could not have been in the session snapshot, however healthy
+it looks now. That is reported as `startup_ordering_race` with the affected
+namespaces listed — the multi-role parallel-connect case where Connected flips
+true after the session tool list was already captured.
+
+### Fail-closed gate
+
+The recorded verdict gates mutations, mirroring the #543 health gate: a namespace
+that has not been assessed does not gate, but one recorded Connected-but-unattached
+blocks the mutation whose role namespace it is
+(`review_pr` / `submit_review` → `gitea-reviewer`, `merge_pr` → `gitea-merger`,
+`work_issue` / `create_pr` → `gitea-author`). `gitea_submit_pr_review` and
+`gitea_merge_pr` return the block reason plus the hard-stop policy string, and the
+only offered recovery is `gitea_request_mcp_reconnect`.
+
+### Telemetry
+
+The `telemetry` block carries `connected_count`, `attached_count`,
+`required_count`, `missing_count`, `discovery_status`, `discovery_cache_hit`,
+`discovery_cache_age_seconds`, `reconnect_required`, `auto_attach_attempted`,
+`auto_recovered`, `startup_ordering_race`, and `error_type`. It contains namespace
+names and counts only — never tokens, endpoints, env values, or filesystem paths.
+

docs/mcp-restart-audit.md

@@ -1,93 +0,0 @@
-# MCP restart audit events and incidents (#665)
-
-Restarts and recovery attempts leave a forensic trail. Failed drains and
-break-glass paths also raise durable Gitea incident issues so unsafe restarts
-cannot be silently repeated.
-
-Parent umbrella: **#655**. Related: impact coordinator **#658**, drain proof
-**#661**, restart classes **#663**, break-glass **#664**, post-restart reconcile
-**#662**, vision **#652**, roadmap **#653**, console recovery **#642**.
-
-## Components
-
-| Piece | Where | Responsibility |
-|-------|-------|----------------|
-| Event schema + emission | `restart_audit.py` | `mcp.restart.*` vocabulary, redacted payload builder, append-only sink via `gitea_audit` |
-| Fail-closed privileged gate | `restart_audit.require_audit_or_deny` | When `GITEA_AUDIT_LOG` is set and the write fails, privileged apply is denied |
-| Incident descriptors | `restart_audit.build_incident_descriptor` | Durable follow-up issues (failed drain, break-glass, reconcile unresolved, unguarded) |
-| Materializer | `restart_audit.materialize_incident` | Injected `create_issue_fn` (network kept out of pure tests) |
-| Wiring | `gitea_request_mcp_restart` | Correlation id, impact-preview audit, apply-gate / break-glass audit + incident creation |
-
-## Event vocabulary
-
-| Event type | When |
-|------------|------|
-| `mcp.restart.impact_preview` | Every `gitea_request_mcp_restart` evaluation |
-| `mcp.restart.drain_enter` | Drain window starts (schema reserved; emit from drain path) |
-| `mcp.restart.drain_exit` | Drain window ends |
-| `mcp.restart.drain_proof` | Drain-proof verification result |
-| `mcp.restart.apply_gate` | Apply hard gate (`dry_run=False`) |
-| `mcp.restart.break_glass` | Authorized break-glass bypass |
-| `mcp.restart.post_restart_reconcile` | Post-restart reconcile outcome |
-| `mcp.restart.narrower_recovery` | Narrower recovery attempt recorded |
-| `mcp.restart.unguarded_detected` | Unguarded restart path detected |
-
-All free text is redacted before sink write or issue body assembly. Emission
-never raises; callers decide fail-closed policy.
-
-## Correlation
-
-Each restart lifecycle mints a short `correlation_id` (`rst-` + 16 hex) shared
-across impact preview → apply gate → incident descriptors so operators can join
-the trail.
-
-## Privileged deny-on-audit-fail
-
-Rollout policy (issue #665):
-
-1. Configure `GITEA_AUDIT_LOG` so writes land.
-2. Only then enforce deny when a privileged restart path cannot audit.
-
-When audit is **not** configured, privileged apply still proceeds (no false
-denials during rollout). When audit **is** configured and the write fails,
-`apply_authorized` is cleared.
-
-## Incidents
-
-| Kind | Trigger |
-|------|---------|
-| `restart_failed_drain` | Apply denied by drain hard gate / failed proof |
-| `restart_break_glass` | Any authorized break-glass apply |
-| `restart_reconcile_unresolved` | Post-restart reconcile left work unresolved |
-| `restart_unguarded_detected` | Unguarded restart attempt detected |
-
-Break-glass **always** creates an incident descriptor (and a Gitea issue when
-the create path is available). Failed drain does the same. Incident bodies
-include correlation id, session, class, scope, proof id, and redacted reasons.
-
-Default labels: `mcp-health`, `safety`, `observability`, `status:ready`,
-`type:bug`, `workflow-hardening`.
-
-## Tool payload surface
-
-`gitea_request_mcp_restart` returns:
-
-* `correlation_id` — lifecycle join key
-* `restart_audit.impact_preview_written` — sink success for the preview event
-* `restart_audit.apply_gate_written` — sink success for apply/break-glass (apply only)
-* `restart_audit.incident_result` — materialization outcome when an incident was required
-* `incident` — durable descriptor (when gate requires follow-up)
-
-## Security
-
-* No secrets in audit payloads or issue bodies.
-* This module never restarts a process.
-* Drain proof verification remains #661; audit only records the decision.
-* Incident creation failures are recorded in `incident_result.reasons` and never
-  crash the restart evaluation path (audit write failure still fails closed for
-  privileged apply when the sink is enabled).
-
-## Tests
-
-See `tests/test_restart_audit.py`: schema, redaction, emission, deny policy,
-incident materialization mocks, break-glass / failed-drain selection.

docs/mcp-restart-coordinator.md

@@ -33,7 +33,6 @@ recovery behavior for all nine classes.
 | `ControlPlaneDB.list_sessions` | `control_plane_db.py` | Read-only session inventory (the process-level unit a restart kills). |
 | `gitea_request_mcp_restart` | `gitea_mcp_server.py` | MCP tool: gathers inventory from the #613 DB, calls the coordinator, returns the report, and on `dry_run=False` runs the #661 drain-proof hard gate. Never restarts a process. |
 | `drain_proof.gate_apply_restart` | `drain_proof.py` | The #661 hard gate: verifies a drain proof against the current impact fingerprint, or records an authorized break-glass bypass. |
-| `restart_audit` | `restart_audit.py` | #665 forensic trail: `mcp.restart.*` events via `gitea_audit`, correlation ids, durable incidents for failed drain / break-glass. See [`mcp-restart-audit.md`](./mcp-restart-audit.md). |
 
 ## Dimensions evaluated
 

docs/mcp-tool-inventory.md

@@ -56,6 +56,7 @@ that gates each call, not which tools exist.
 - `gitea_assess_conflict_fix_push`
 - `gitea_assess_gitea_operation_path`
 - `gitea_assess_master_parity`
+- `gitea_assess_mcp_namespace_attachment`
 - `gitea_assess_mcp_namespace_health`
 - `gitea_assess_pr_sync_status`
 - `gitea_assess_review_merge_state_machine`

docs/remote-mcp/threat-model-anchors.json

@@ -8,73 +8,239 @@
     "document. #930's inventory had no such guard and its gitea_mcp_server.py",
     "anchors drifted between 7bf4f125 and aad5c8b4."
   ],
-  "generated_against_commit": "aad5c8b42361d380a8eeb07b94b90815e594c2c5",
+  "generated_against_commit": "ca5f078d8a575ea3e2991771f8b4ea85e3dcaaa0",
   "anchors": [
-    {"anchor": "gitea_mcp_server.py:24721", "expect": "bind_native_mcp_transport(transport=\"stdio\")"},
+    {
-    {"anchor": "mcp_daemon_guard.py:45", "expect": "_PRODUCTION_TRANSPORTS = frozenset({\"stdio\"})"},
+      "anchor": "gitea_mcp_server.py:24864",
-    {"anchor": "mcp_daemon_guard.py:174", "expect": "def bind_native_mcp_transport"},
+      "expect": "mcp_daemon_guard.bind_native_mcp_transport()"
-    {"anchor": "irrecoverable_provenance.py:497", "expect": "def assess_transport_for_auth_mint"},
+    },
-    {"anchor": "gitea_mcp_server.py:9129", "expect": "assess_transport_for_auth_mint()"},
+    {
-    {"anchor": "gitea_mcp_server.py:9378", "expect": "assess_transport_for_auth_mint()"},
+      "anchor": "mcp_daemon_guard.py:49",
-    {"anchor": "mcp_server.py:4", "expect": "Runs over stdio."},
+      "expect": "_PRODUCTION_TRANSPORTS = mcp_transport_config.SUPPORTED_TRANSPORTS"
-
+    },
-    {"anchor": "gitea_mcp_server.py:15412", "expect": "def _is_client_managed_process"},
+    {
-    {"anchor": "gitea_mcp_server.py:15442", "expect": "def _provenance_mutation_block"},
+      "anchor": "mcp_daemon_guard.py:195",
-    {"anchor": "gitea_mcp_server.py:15450", "expect": "unsupported_manual_launch"},
+      "expect": "def bind_native_mcp_transport"
-    {"anchor": "gitea_mcp_server.py:19001", "expect": "server_provenance"},
+    },
-    {"anchor": "gitea_mcp_server.py:21442", "expect": "def _check_mcp_runtimes_diagnostics"},
+    {
-    {"anchor": "gitea_mcp_server.py:21462", "expect": "\"ps\", \"-o\", \"pid,lstart,command\""},
+      "anchor": "irrecoverable_provenance.py:497",
-    {"anchor": "gitea_mcp_server.py:21506", "expect": "\"ps\", \"eww\""},
+      "expect": "def assess_transport_for_auth_mint"
-    {"anchor": "gitea_config.py:1172", "expect": "RECOGNIZED_GITEA_ENV_KEYS"},
+    },
-    {"anchor": "gitea_config.py:1233", "expect": "GITEA_CLIENT_MANAGED"},
+    {
-
+      "anchor": "gitea_mcp_server.py:9191",
-    {"anchor": "gitea_config.py:54", "expect": "ENV_PROFILE = \"GITEA_MCP_PROFILE\""},
+      "expect": "assess_transport_for_auth_mint()"
-    {"anchor": "gitea_config.py:97", "expect": "_REVIEW_MERGE_OPS"},
+    },
-    {"anchor": "gitea_config.py:499", "expect": "repository authorization scope"},
+    {
-
+      "anchor": "gitea_mcp_server.py:9440",
-    {"anchor": "gitea_config.py:956", "expect": "def _keychain_token"},
+      "expect": "assess_transport_for_auth_mint()"
-    {"anchor": "gitea_config.py:974", "expect": "def resolve_token"},
+    },
-    {"anchor": "gitea_config.py:1015", "expect": "def keychain_auth"},
+    {
-    {"anchor": "gitea_config.py:294", "expect": "def _validate_identity_auth"},
+      "anchor": "mcp_server.py:4",
-    {"anchor": "mcp_daemon_guard.py:440", "expect": "def assert_keychain_access_allowed"},
+      "expect": "The transport is selected by deployment configuration"
-    {"anchor": "gitea_mcp_server.py:19258", "expect": "def gitea_list_profiles"},
+    },
-    {"anchor": "gitea_mcp_server.py:19309", "expect": "gitea_config.resolve_token(p)"},
+    {
-    {"anchor": "gitea_mcp_server.py:19552", "expect": "def gitea_audit_config"},
+      "anchor": "gitea_mcp_server.py:15481",
-    {"anchor": "gitea_mcp_server.py:19574", "expect": "service_summaries(config)"},
+      "expect": "def _is_client_managed_process"
-
+    },
-    {"anchor": "gitea_config.py:704", "expect": "def resolve_service"},
+    {
-    {"anchor": "gitea_config.py:837", "expect": "def service_summaries"},
+      "anchor": "gitea_mcp_server.py:15511",
-    {"anchor": "gitea_config.py:851", "expect": "_keychain_token(auth.get(\"id\"))"},
+      "expect": "def _provenance_mutation_block"
-    {"anchor": "gitea_mcp_server.py:17707", "expect": "\"jenkins-mcp\""},
+    },
-    {"anchor": "gitea_mcp_server.py:17713", "expect": "external-mcp"},
+    {
-    {"anchor": "gitea_mcp_server.py:17734", "expect": "\"glitchtip-mcp\""},
+      "anchor": "gitea_mcp_server.py:15519",
-    {"anchor": "gitea_mcp_server.py:17739", "expect": "external-mcp"},
+      "expect": "unsupported_manual_launch"
-    {"anchor": "mcp_discoverability.py:9", "expect": "EXPECTED_JENKINS_TOOLS"},
+    },
-    {"anchor": "mcp_discoverability.py:17", "expect": "EXPECTED_GLITCHTIP_TOOLS"},
+    {
-
+      "anchor": "gitea_mcp_server.py:19070",
-    {"anchor": "sentry_incident_bridge.py:36", "expect": "SENTRY_AUTH_TOKEN"},
+      "expect": "server_provenance"
-    {"anchor": "sentry_incident_bridge.py:190", "expect": "def resolve_token"},
+    },
-    {"anchor": "sentry_incident_bridge.py:289", "expect": "Authorization"},
+    {
-    {"anchor": "sentry_observability.py:55", "expect": "SENTRY_DSN"},
+      "anchor": "gitea_mcp_server.py:21581",
-
+      "expect": "def _check_mcp_runtimes_diagnostics"
-    {"anchor": "master_parity_gate.py:168", "expect": "def capture_startup_parity"},
+    },
-    {"anchor": "master_parity_gate.py:255", "expect": "mutation_safe"},
+    {
-    {"anchor": "gitea_mcp_server.py:19102", "expect": "def gitea_assess_master_parity"},
+      "anchor": "gitea_mcp_server.py:21601",
-
+      "expect": "\"ps\", \"-o\", \"pid,lstart,command\""
-    {"anchor": "gitea_mcp_server.py:190", "expect": "ACTIVE_WORKTREE_ENV"},
+    },
-    {"anchor": "gitea_mcp_server.py:191", "expect": "AUTHOR_WORKTREE_ENV"},
+    {
-    {"anchor": "gitea_mcp_server.py:2348", "expect": "/tmp/gitea_issue_lock.json"},
+      "anchor": "gitea_mcp_server.py:21645",
-    {"anchor": "gitea_mcp_server.py:10894", "expect": "def gitea_bootstrap_author_issue_worktree"},
+      "expect": "\"ps\", \"eww\""
-    {"anchor": "mcp_server.py:10", "expect": "/tmp/mcp_server_stderr.log"},
+    },
-
+    {
-    {"anchor": "issue_lock_store.py:26", "expect": "DEFAULT_LOCK_DIR"},
+      "anchor": "gitea_config.py:1172",
-    {"anchor": "issue_lock_store.py:83", "expect": "def session_pointer_path"},
+      "expect": "RECOGNIZED_GITEA_ENV_KEYS"
-    {"anchor": "issue_lock_store.py:98", "expect": "def is_process_alive"},
+    },
-    {"anchor": "mcp_session_state.py:27", "expect": "DEFAULT_STATE_DIR"},
+    {
-    {"anchor": "control_plane_db.py:47", "expect": "DEFAULT_DB_PATH"},
+      "anchor": "gitea_config.py:1233",
-    {"anchor": "control_plane_db.py:380", "expect": "mode=0o700"},
+      "expect": "GITEA_CLIENT_MANAGED"
-    {"anchor": "control_plane_db.py:386", "expect": "sqlite3.connect"},
+    },
-    {"anchor": "control_plane_db.py:1145", "expect": "os.getpid()"},
+    {
-    {"anchor": "gitea_mcp_server.py:12801", "expect": "owner_pid_alive"}
+      "anchor": "gitea_config.py:54",
+      "expect": "ENV_PROFILE = \"GITEA_MCP_PROFILE\""
+    },
+    {
+      "anchor": "gitea_config.py:97",
+      "expect": "_REVIEW_MERGE_OPS"
+    },
+    {
+      "anchor": "gitea_config.py:499",
+      "expect": "repository authorization scope"
+    },
+    {
+      "anchor": "gitea_config.py:956",
+      "expect": "def _keychain_token"
+    },
+    {
+      "anchor": "gitea_config.py:974",
+      "expect": "def resolve_token"
+    },
+    {
+      "anchor": "gitea_config.py:1015",
+      "expect": "def keychain_auth"
+    },
+    {
+      "anchor": "gitea_config.py:294",
+      "expect": "def _validate_identity_auth"
+    },
+    {
+      "anchor": "mcp_daemon_guard.py:583",
+      "expect": "def assert_keychain_access_allowed"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:19327",
+      "expect": "def gitea_list_profiles"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:19378",
+      "expect": "gitea_config.resolve_token(p)"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:19691",
+      "expect": "def gitea_audit_config"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:19713",
+      "expect": "service_summaries(config)"
+    },
+    {
+      "anchor": "gitea_config.py:704",
+      "expect": "def resolve_service"
+    },
+    {
+      "anchor": "gitea_config.py:837",
+      "expect": "def service_summaries"
+    },
+    {
+      "anchor": "gitea_config.py:851",
+      "expect": "_keychain_token(auth.get(\"id\"))"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:17776",
+      "expect": "\"jenkins-mcp\""
+    },
+    {
+      "anchor": "gitea_mcp_server.py:17782",
+      "expect": "external-mcp"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:17803",
+      "expect": "\"glitchtip-mcp\""
+    },
+    {
+      "anchor": "gitea_mcp_server.py:17808",
+      "expect": "external-mcp"
+    },
+    {
+      "anchor": "mcp_discoverability.py:9",
+      "expect": "EXPECTED_JENKINS_TOOLS"
+    },
+    {
+      "anchor": "mcp_discoverability.py:17",
+      "expect": "EXPECTED_GLITCHTIP_TOOLS"
+    },
+    {
+      "anchor": "sentry_incident_bridge.py:36",
+      "expect": "SENTRY_AUTH_TOKEN"
+    },
+    {
+      "anchor": "sentry_incident_bridge.py:190",
+      "expect": "def resolve_token"
+    },
+    {
+      "anchor": "sentry_incident_bridge.py:289",
+      "expect": "Authorization"
+    },
+    {
+      "anchor": "sentry_observability.py:55",
+      "expect": "SENTRY_DSN"
+    },
+    {
+      "anchor": "master_parity_gate.py:168",
+      "expect": "def capture_startup_parity"
+    },
+    {
+      "anchor": "master_parity_gate.py:255",
+      "expect": "mutation_safe"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:19171",
+      "expect": "def gitea_assess_master_parity"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:193",
+      "expect": "ACTIVE_WORKTREE_ENV"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:194",
+      "expect": "AUTHOR_WORKTREE_ENV"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:2351",
+      "expect": "/tmp/gitea_issue_lock.json"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:10956",
+      "expect": "def gitea_bootstrap_author_issue_worktree"
+    },
+    {
+      "anchor": "mcp_server.py:13",
+      "expect": "/tmp/mcp_server_stderr.log"
+    },
+    {
+      "anchor": "issue_lock_store.py:26",
+      "expect": "DEFAULT_LOCK_DIR"
+    },
+    {
+      "anchor": "issue_lock_store.py:83",
+      "expect": "def session_pointer_path"
+    },
+    {
+      "anchor": "issue_lock_store.py:98",
+      "expect": "def is_process_alive"
+    },
+    {
+      "anchor": "mcp_session_state.py:27",
+      "expect": "DEFAULT_STATE_DIR"
+    },
+    {
+      "anchor": "control_plane_db.py:47",
+      "expect": "DEFAULT_DB_PATH"
+    },
+    {
+      "anchor": "control_plane_db.py:380",
+      "expect": "mode=0o700"
+    },
+    {
+      "anchor": "control_plane_db.py:386",
+      "expect": "sqlite3.connect"
+    },
+    {
+      "anchor": "control_plane_db.py:1145",
+      "expect": "os.getpid()"
+    },
+    {
+      "anchor": "gitea_mcp_server.py:12870",
+      "expect": "owner_pid_alive"
+    }
   ]
 }

docs/remote-mcp/threat-model.md

@@ -5,7 +5,11 @@ What the adversary is, what each boundary protects, and which services may share
 - **Issue:** #956 (Remote-MCP threat model), child of epic #929, cross-linked to #955.
 - **Depends on:** #930 (closed) — `docs/remote-mcp/coupling-inventory.md`.
 - **Blocks:** #932, #933, #934, #938.
-- **Generated against commit:** `aad5c8b42361d380a8eeb07b94b90815e594c2c5` (`master`).
+- **Generated against commit:** `ca5f078d8a575ea3e2991771f8b4ea85e3dcaaa0` (#708's
+  namespace-attachment gate). Originally generated against
+  `aad5c8b42361d380a8eeb07b94b90815e594c2c5` (`master`), re-anchored at
+  `a143cd065ba06e1a2bdc5143a19ec156e53650ef` when #931's transport bind seam shifted the
+  cited lines, and re-anchored again when #708 shifted them further.
 - **Scope:** documentation only. This child changes no server behavior. It adds one
   document, one anchor fixture, and the test that enforces them.
 
@@ -27,7 +31,7 @@ document cites an anchor the fixture does not cover.
 
 This guard exists because #930 did not have one. Its inventory was generated at
 `7bf4f125`; by `aad5c8b4` its `gitea_mcp_server.py` anchors had drifted — the transport
-bind it cited at line 23750 now lives at `gitea_mcp_server.py:24721`, and its
+bind it cited at line 23750 now lives at `gitea_mcp_server.py:24864`, and its
 client-managed provenance anchor at 14588 now lands in an unrelated function. Nothing
 failed, because nothing checked. Anchors into a ~24,700-line module rot silently, and a
 security document that cannot prove its own citations is worse than none, because it is
@@ -71,19 +75,19 @@ authenticate the *caller*, not the *intent*.
 ## 3. Trust boundaries
 
 "Crossing requires today" is what the code actually enforces at
-`aad5c8b42361d380a8eeb07b94b90815e594c2c5`, not what the design intends.
+`ca5f078d8a575ea3e2991771f8b4ea85e3dcaaa0`, not what the design intends.
 
 | ID | Boundary | Protects | Crossing requires today | Crossing must require remotely |
 | -- | -------- | -------- | ----------------------- | ------------------------------ |
-| B1 | LLM client ↔ MCP server session | A1, A3, A10 — that a mutating session was established through the sanctioned client path | A literal `stdio` bind (`gitea_mcp_server.py:24721`) inside a closed allowlist (`mcp_daemon_guard.py:45`, `mcp_daemon_guard.py:174`); client-managed provenance (`gitea_mcp_server.py:15412`) or a refusal (`gitea_mcp_server.py:15450`); production transport before recovery-authorization mint (`irrecoverable_provenance.py:497`, consumed at `gitea_mcp_server.py:9129` and `gitea_mcp_server.py:9378`) | An authenticated handshake issuing a server-side session identity bound to a principal, with the transport recorded in provenance. The physical proof (a pipe) must become a cryptographic one. |
+| B1 | LLM client ↔ MCP server session | A1, A3, A10 — that a mutating session was established through the sanctioned client path | A single configured bind (`gitea_mcp_server.py:24864`) validated against one closed allowlist (`mcp_daemon_guard.py:49`, `mcp_daemon_guard.py:195`) — since #931 the identifier comes from deployment configuration and defaults to the local transport, so the boundary no longer rests on a literal, but it still rests on the *bind* rather than on an authenticated caller; client-managed provenance (`gitea_mcp_server.py:15481`) or a refusal (`gitea_mcp_server.py:15519`); production transport before recovery-authorization mint (`irrecoverable_provenance.py:497`, consumed at `gitea_mcp_server.py:9191` and `gitea_mcp_server.py:9440`) | An authenticated handshake issuing a server-side session identity bound to a principal, with the transport recorded in provenance. The physical proof (a pipe) must become a cryptographic one. |
 | B2 | Role ↔ role | A9 — that author, reviewer, merger, and reconciler are distinct authorities | **The process boundary only.** The role is a property of the process, read once from `GITEA_MCP_PROFILE` (`gitea_config.py:54`). A caller gets author permissions by connecting to the author process. Review and merge are the operations singled out for extra care (`gitea_config.py:97`) | A per-request principal, so the role follows from the credential presented and cannot be selected by reaching a different endpoint. |
-| B3 | MCP server ↔ credential store | A3, A8 — that only sanctioned code turns a profile into a token | `_keychain_token` shelling out to the login keychain (`gitea_config.py:956`), dispatched by `resolve_token` (`gitea_config.py:974`) with the reference type built at `gitea_config.py:1015`, gated by `assert_keychain_access_allowed` (`mcp_daemon_guard.py:440`). Inline secrets are rejected at config load (`gitea_config.py:294`) | A credential provider keyed by the *request* principal, returning only that principal's credential, with the source recorded and the value never returned. |
+| B3 | MCP server ↔ credential store | A3, A8 — that only sanctioned code turns a profile into a token | `_keychain_token` shelling out to the login keychain (`gitea_config.py:956`), dispatched by `resolve_token` (`gitea_config.py:974`) with the reference type built at `gitea_config.py:1015`, gated by `assert_keychain_access_allowed` (`mcp_daemon_guard.py:583`). Inline secrets are rejected at config load (`gitea_config.py:294`) | A credential provider keyed by the *request* principal, returning only that principal's credential, with the source recorded and the value never returned. |
 | B4 | MCP server ↔ Gitea | A1, A2 — that only authorized calls reach the forge | A bearer token over TLS. Server-side, nothing distinguishes one role's token from another beyond the account it belongs to | Unchanged at the forge; the endpoint in front of it must refuse unauthenticated and plaintext connections before tool dispatch. |
-| B5 | MCP server ↔ caller's filesystem | A7 — that a tool acts on the *caller's* disk or refuses | Nothing. The server's disk *is* the caller's disk. Worktree bootstrap writes directly (`gitea_mcp_server.py:10894`); the active workspace is process-global (`gitea_mcp_server.py:190`, `gitea_mcp_server.py:191`) | An explicit per-tool classification, enforced at dispatch, refusing filesystem tools over a transport that cannot reach the caller's disk. A green verdict about the wrong disk is the failure to prevent. |
+| B5 | MCP server ↔ caller's filesystem | A7 — that a tool acts on the *caller's* disk or refuses | Nothing. The server's disk *is* the caller's disk. Worktree bootstrap writes directly (`gitea_mcp_server.py:10956`); the active workspace is process-global (`gitea_mcp_server.py:193`, `gitea_mcp_server.py:194`) | An explicit per-tool classification, enforced at dispatch, refusing filesystem tools over a transport that cannot reach the caller's disk. A green verdict about the wrong disk is the failure to prevent. |
-| B6 | MCP server ↔ coordination state | A6, A9 — mutual exclusion | Local files and a local SQLite database, with liveness judged from the local process table (`issue_lock_store.py:98`), keyed on paths under one user's home (`issue_lock_store.py:26`, `mcp_session_state.py:27`, `control_plane_db.py:47`) and on `os.getpid()` (`control_plane_db.py:1145`, `gitea_mcp_server.py:12801`). A legacy global slot still exists at `gitea_mcp_server.py:2348`, and the session-pointer file is named per PID (`issue_lock_store.py:83`) | One authority per ownership question, with liveness from session identity and expiry, and atomic acquire, renew, and release across hosts. |
+| B6 | MCP server ↔ coordination state | A6, A9 — mutual exclusion | Local files and a local SQLite database, with liveness judged from the local process table (`issue_lock_store.py:98`), keyed on paths under one user's home (`issue_lock_store.py:26`, `mcp_session_state.py:27`, `control_plane_db.py:47`) and on `os.getpid()` (`control_plane_db.py:1145`, `gitea_mcp_server.py:12870`). A legacy global slot still exists at `gitea_mcp_server.py:2351`, and the session-pointer file is named per PID (`issue_lock_store.py:83`) | One authority per ownership question, with liveness from session identity and expiry, and atomic acquire, renew, and release across hosts. |
 | B7 | Gitea integration ↔ unrelated integrations | A4, A5 — that a Gitea compromise is not a CI and observability compromise | **Nothing.** See §5. The Gitea server reads Jenkins and GlitchTip secrets (`gitea_config.py:851`, reached from `gitea_config.py:837`) and holds the Sentry token (`sentry_incident_bridge.py:190`) | A hard process boundary. This is the boundary #956 exists to create. |
 | B8 | Tenant ↔ tenant (`prgs` / `mdcps` / `local-lab`) | A2 — that one organization's compromise is not another's | Convention. One configuration declares all three contexts; `resolve_service` fails closed on a *disabled* context (`gitea_config.py:704`) but the credentials of enabled ones remain reachable in-process. A per-profile repository scope exists (`gitea_config.py:499`) | Separate deployments, or at minimum per-tenant credential scopes with no process able to resolve both. |
-| B9 | Deployed code ↔ merged policy | A1, A10 — that the running server enforces the rules that were actually merged | Comparing this process's startup commit against this disk (`master_parity_gate.py:168`), conjoined into a single verdict (`master_parity_gate.py:255`) published by `gitea_mcp_server.py:19102` | Freshness defined against the deployed build identity, with an explicit fail-closed verdict when undeterminable. |
+| B9 | Deployed code ↔ merged policy | A1, A10 — that the running server enforces the rules that were actually merged | Comparing this process's startup commit against this disk (`master_parity_gate.py:168`), conjoined into a single verdict (`master_parity_gate.py:255`) published by `gitea_mcp_server.py:19171` | Freshness defined against the deployed build identity, with an explicit fail-closed verdict when undeterminable. |
 
 ### What no boundary constrains
 
@@ -128,10 +132,10 @@ Two flows deserve attention because neither is obvious from the code:
 
 1. **The keychain flow fans out.** B3 is drawn once but resolves credentials for *every*
    configured profile and service, not only the active one. `gitea_list_profiles`
-   (`gitea_mcp_server.py:19258`) reports each profile's credential status by calling
+   (`gitea_mcp_server.py:19327`) reports each profile's credential status by calling
-   `resolve_token` on it (`gitea_mcp_server.py:19309`), and `gitea_audit_config`
+   `resolve_token` on it (`gitea_mcp_server.py:19378`), and `gitea_audit_config`
-   (`gitea_mcp_server.py:19552`) reports service credential status through
+   (`gitea_mcp_server.py:19691`) reports service credential status through
-   `service_summaries` (`gitea_mcp_server.py:19574`).
+   `service_summaries` (`gitea_mcp_server.py:19713`).
 2. **The return path is a flow too.** Content read from Gitea travels back into the model
    and is treated as instruction. This is the ADV2 edge, and it is the only edge in the
    diagram with no authentication on it, because it is not a request.
@@ -156,7 +160,7 @@ an attacker holding a token calls the API, not our tools.
 | CR10 | MDCPS GlitchTip read credential | macOS keychain, read from the Gitea server process (`gitea_config.py:851`) | B7 | Read error events and their payloads (A5). Enabled today. |
 | CR11 | `SENTRY_AUTH_TOKEN` | Process environment, read in-process (`sentry_incident_bridge.py:36`, `sentry_incident_bridge.py:190`), sent as a bearer header (`sentry_incident_bridge.py:289`) | B7 | Read and reconcile Sentry issues (A5). Not a keychain credential — an env var, so it is inherited by anything the process spawns. |
 | CR12 | `SENTRY_DSN` | Process environment (`sentry_observability.py:55`) | B7 | Write events into the observability project. Low read value, real forgery value: an attacker can inject fabricated events into the record (A10). |
-| CR13 | macOS login keychain access | The operator's login session; gated by `assert_keychain_access_allowed` (`mcp_daemon_guard.py:440`) | B3, ADV5 | **Every other credential in this table except CR11 and CR12.** This is the aggregation point. |
+| CR13 | macOS login keychain access | The operator's login session; gated by `assert_keychain_access_allowed` (`mcp_daemon_guard.py:583`) | B3, ADV5 | **Every other credential in this table except CR11 and CR12.** This is the aggregation point. |
 | CR14 | Coordination-store access (no secret) | Filesystem permissions — `control_plane_db.py:47`, created `0o700` (`control_plane_db.py:380`), opened with a local file lock (`control_plane_db.py:386`) | B6, ADV5 | Full read/write of locks, leases, and decision records (A6). **There is no credential here at all** — anything running as the operator can rewrite ownership. |
 
 ### Findings
@@ -176,16 +180,16 @@ the credential, and an attacker holding the token does not call our tools.
 
 **Finding 3 — Any one role process can resolve every other role's credential.** This is not
 inferred; it is demonstrated by tool output. `gitea_list_profiles`
-(`gitea_mcp_server.py:19258`) called from the **author** session reports
+(`gitea_mcp_server.py:19327`) called from the **author** session reports
 `identity_status: "credentials present"` for `prgs-merger`, `prgs-reviewer`,
 `prgs-reconciler`, and every `mdcps` profile, because it calls `resolve_token` on each one
-(`gitea_mcp_server.py:19309`). The author process does not merely *have access to* the
+(`gitea_mcp_server.py:19378`). The author process does not merely *have access to* the
 merger's credential — it reads it to answer a status query. B2 is not a credential boundary
 in either direction.
 
 **Finding 4 — The Gitea server reads CI and observability secrets.** `gitea_audit_config`
-(`gitea_mcp_server.py:19552`) reports `MDCPS Jenkins: enabled, read-only, authenticated`.
+(`gitea_mcp_server.py:19691`) reports `MDCPS Jenkins: enabled, read-only, authenticated`.
-That word `authenticated` is produced by `service_summaries` (`gitea_mcp_server.py:19574`,
+That word `authenticated` is produced by `service_summaries` (`gitea_mcp_server.py:19713`,
 defined at `gitea_config.py:837`), whose default check calls `_keychain_token` on the
 service's own keychain reference (`gitea_config.py:851`). Producing that one line requires
 the Gitea MCP server to read the Jenkins secret and the GlitchTip secret out of the
@@ -193,8 +197,8 @@ keychain. B7 does not exist.
 
 **Finding 5 — Jenkins and GlitchTip are already decomposed; the reach is residual.** Their
 tools live in separately registered servers, marked `external-mcp`
-(`gitea_mcp_server.py:17707`, `gitea_mcp_server.py:17713`, `gitea_mcp_server.py:17734`,
+(`gitea_mcp_server.py:17776`, `gitea_mcp_server.py:17782`, `gitea_mcp_server.py:17803`,
-`gitea_mcp_server.py:17739`) with their own expected tool sets (`mcp_discoverability.py:9`,
+`gitea_mcp_server.py:17808`) with their own expected tool sets (`mcp_discoverability.py:9`,
 `mcp_discoverability.py:17`). The correct decomposition was already chosen. What remains is
 a leak across it: the credential *references* still live in the Gitea configuration and are
 still resolved by the Gitea process. #75 bundled these services into one control-plane
@@ -205,8 +209,8 @@ GlitchTip, the Sentry bridge runs *inside* the Gitea server, resolving its token
 process environment (`sentry_incident_bridge.py:190`) and sending it as a bearer header
 (`sentry_incident_bridge.py:289`). Being an environment variable rather than a keychain item
 makes it strictly worse: it needs no keychain prompt and is inherited by every subprocess the
-server spawns — including the `ps` invocations at `gitea_mcp_server.py:21462` and
+server spawns — including the `ps` invocations at `gitea_mcp_server.py:21601` and
-`gitea_mcp_server.py:21506`, reached from `gitea_mcp_server.py:21442`.
+`gitea_mcp_server.py:21645`, reached from `gitea_mcp_server.py:21581`.
 
 **Finding 7 — The highest-value coordination asset has the weakest gate.** A6 is protected
 by filesystem permissions alone (CR14). Corrupting a lease requires no Gitea credential,
@@ -215,13 +219,15 @@ assumes. Every other asset costs an attacker a credential; this one costs nothin
 local access, which is exactly ADV5's position.
 
 **Finding 8 — Provenance authenticates the launch, not the caller.** `server_provenance` is
-reported as exactly `client_managed` or `manual_launch` (`gitea_mcp_server.py:19001`),
+reported as exactly `client_managed` or `manual_launch` (`gitea_mcp_server.py:19070`),
-derived from environment inspection (`gitea_mcp_server.py:15412`) with the recognized-key
+derived from environment inspection (`gitea_mcp_server.py:15481`) with the recognized-key
 allowlist at `gitea_config.py:1172` and the generator that emits the marker at
 `gitea_config.py:1233`. Every one of those facts is fixed at process start. A client that is
 trustworthy at launch and compromised a minute later remains `client_managed` for the life
-of the process, and the stdio contract that underwrites it is stated as a property of the
+of the process, and the transport contract that underwrites it is stated as a property of
-server itself (`mcp_server.py:4`).
+the server itself (`mcp_server.py:4`). Since #931 that contract names the configured
+transport rather than asserting stdio, but it is still fixed once, at bind, for the life of
+the process.
 
 ## 6. Decomposition ruling
 
@@ -253,7 +259,7 @@ holds the token and calls the API instead of the tool.
 
 **D3 — Credential resolution is scoped to the request principal.** A session must resolve its
 own credential and must have no path to any other principal's. The resolve-every-profile
-behavior behind `gitea_mcp_server.py:19309` and `gitea_mcp_server.py:19574` must report
+behavior behind `gitea_mcp_server.py:19378` and `gitea_mcp_server.py:19713` must report
 configured-or-not from configuration alone, without resolving the secret.
 
 *Rationale.* Finding 3. An audit surface that proves a credential exists by fetching it is a
@@ -330,11 +336,11 @@ The client is attached to the local fleet over stdio.
 
 | Boundary | What ADV1 reaches | Stopped by |
 | -------- | ----------------- | ---------- |
-| B1 | Everything the fleet serves. The client *is* the sanctioned launcher: it satisfies the client-managed check (`gitea_mcp_server.py:15412`) by construction, and provenance is never re-verified after launch (Finding 8). | Nothing. The guard authenticates the launch, not the caller. |
+| B1 | Everything the fleet serves. The client *is* the sanctioned launcher: it satisfies the client-managed check (`gitea_mcp_server.py:15481`) by construction, and provenance is never re-verified after launch (Finding 8). | Nothing. The guard authenticates the launch, not the caller. |
 | B2 | All five roles — it is attached to all five namespaces. It can author a PR, approve it from the reviewer namespace, and merge it from the merger namespace. | Only the in-process self-review check, which compares `jcwalker3` (author) against `sysadmin` (reviewer) and **passes**, because Finding 1 made them different accounts while leaving reviewer and merger identical. A9 falls in one sequence of legitimate calls. |
-| B3 | Every credential in CR1–CR10 via CR13, with no additional prompt — the daemon is already sanctioned, so `assert_keychain_access_allowed` (`mcp_daemon_guard.py:440`) returns immediately. | Nothing. |
+| B3 | Every credential in CR1–CR10 via CR13, with no additional prompt — the daemon is already sanctioned, so `assert_keychain_access_allowed` (`mcp_daemon_guard.py:583`) returns immediately. | Nothing. |
 | B4 | A1 and A2 in full. | Branch protection at the forge, to the extent configured. |
-| B5 | The operator's checkout and every worktree, through the author tools (`gitea_mcp_server.py:10894`), plus the shared stderr path at `mcp_server.py:10`. | Nothing; the server's disk is the target disk. |
+| B5 | The operator's checkout and every worktree, through the author tools (`gitea_mcp_server.py:10956`), plus the shared stderr path at `mcp_server.py:13`. | Nothing; the server's disk is the target disk. |
 | B6 | All coordination state — no credential required (CR14). It can forge lease ownership and clear decision locks. | Filesystem permissions, which it already satisfies. |
 | B7 | Jenkins (A4) and GlitchTip (A5) secrets via Finding 4, and CR11/CR12 from its own environment. | Nothing. |
 | B8 | Both tenants. | Nothing in-process; only the disabled-context check (`gitea_config.py:704`), which does not apply to enabled contexts. |

gitea_mcp_server.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python3
 """Gitea MCP Server — exposes Gitea operations as MCP tools.
 
-Runs over stdio. All tools authenticate via macOS keychain (git credential fill).
+The transport is selected by deployment configuration (GITEA_MCP_TRANSPORT) and
+defaults to the local client-spawned transport when unset (#931); the permitted
+set lives in mcp_transport_config. All tools authenticate via macOS keychain
+(git credential fill).
 
 Usage (standalone test):
     python3 mcp_server.py
@@ -2100,7 +2103,6 @@ import lease_policy  # noqa: E402
 import workflow_dashboard  # noqa: E402  # #605 live queue/lease dashboard
 import restart_coordinator  # noqa: E402  # #658 MCP restart coordinator/impact
 import drain_proof  # noqa: E402  # #661 pre-restart drain proof and hard gate
-import restart_audit  # noqa: E402  # #665 restart audit events + incidents
 import incident_bridge  # noqa: E402
 import sentry_observability  # noqa: E402  (#606 optional Sentry observability)
 import sentry_incident_bridge  # noqa: E402  (#607 Sentry→Gitea incident bridge)
@@ -6714,6 +6716,61 @@ def _live_namespace_health_gate(task: str) -> list[str]:
     )
 
 
+# Session-scoped MCP namespace *attachment* assessments (#708).
+# Distinct from _LIVE_NAMESPACE_HEALTH: a namespace can probe healthy while never
+# being attached to the active session tool surface ("Connected" != "tools available").
+_LIVE_NAMESPACE_ATTACHMENT: dict[str, dict] = {}
+
+
+def _record_live_namespace_attachment(assessment: dict | None) -> None:
+    """Store a per-namespace attachment verdict for mutation gates (#708)."""
+    if not isinstance(assessment, dict):
+        return
+    proof = assessment.get("proof_of_connected_vs_attached")
+    if not isinstance(proof, dict):
+        return
+    missing = set(assessment.get("missing_namespaces") or [])
+    error_type = assessment.get("error_type")
+    # Per-namespace verdicts when the assessment supplies them (#708 B2): a session-wide
+    # error_type must never be pinned onto a namespace whose own condition differs, and a
+    # namespace that was never connected must not be recorded healthy just because the
+    # session-wide "missing" list only tracks Connected-but-unattached namespaces.
+    conditions = assessment.get("namespace_conditions")
+    conditions = conditions if isinstance(conditions, dict) else {}
+    for ns, state in proof.items():
+        ns_name = str(ns or "").strip()
+        if not ns_name or not isinstance(state, dict):
+            continue
+        condition = conditions.get(ns_name)
+        condition = condition if isinstance(condition, dict) else {}
+        connected = bool(condition.get("connected", state.get("connected")))
+        attached = bool(condition.get("attached", state.get("attached")))
+        if condition:
+            healthy = bool(condition.get("attachment_healthy"))
+            ns_error = condition.get("condition")
+        else:
+            healthy = attached and connected and ns_name not in missing
+            ns_error = None if healthy else error_type
+        _LIVE_NAMESPACE_ATTACHMENT[ns_name] = {
+            "namespace": ns_name,
+            "connected": connected,
+            "attached": attached,
+            "attachment_healthy": healthy,
+            "condition": ns_error,
+            "error_type": ns_error,
+            "discovery_status": assessment.get("discovery_status"),
+            "reconnect_required": bool(assessment.get("reconnect_required")),
+            "auto_recovered": bool(assessment.get("auto_recovered")),
+        }
+
+
+def _namespace_attachment_gate(task: str) -> list[str]:
+    """Fail closed on a recorded Connected-but-unattached namespace (#708)."""
+    return mcp_namespace_health.attachment_gate_from_session(
+        task, _LIVE_NAMESPACE_ATTACHMENT
+    )
+
+
 def _decision_lock_binding(lock: dict | None = None) -> dict:
     """Resolve key fields for durable decision-lock storage."""
     profile = get_profile()
@@ -7594,6 +7651,10 @@ def _evaluate_pr_review_submission(
         if ns_gate:
             reasons.extend(ns_gate)
             return result
+        attach_gate = _namespace_attachment_gate("review_pr")
+        if attach_gate:
+            reasons.extend(attach_gate)
+            return result
 
     if action not in _REVIEW_ACTIONS:
         reasons.append(
@@ -11152,6 +11213,13 @@ def gitea_merge_pr(
         reasons.extend(ns_gate)
         return result
 
+    # Gate 0c — the merger namespace must be attached to the active session (#708).
+    # Connected at the host layer is not proof the tools are in this session.
+    attach_gate = _namespace_attachment_gate("merge_pr")
+    if attach_gate:
+        reasons.extend(attach_gate)
+        return result
+
     # Gate 1 — valid merge method (no API call on a bad method).
     if do not in _MERGE_METHODS:
         reasons.append(
@@ -19417,6 +19485,76 @@ def gitea_assess_mcp_namespace_health(
     return result
 
 
+@mcp.tool()
+def gitea_assess_mcp_namespace_attachment(
+    connected_servers: list[str] | None = None,
+    attached_session_namespaces: list[str] | None = None,
+    required_namespaces: list[str] | None = None,
+    discovery_cache_age_seconds: float | None = None,
+    discovery_cache_hit: bool | None = None,
+    auto_attach_attempted: bool = False,
+    auto_attach_succeeded: bool = False,
+    session_tool_snapshot_at: float | None = None,
+    namespace_connected_at: dict | None = None,
+) -> dict:
+    """Detect Connected-but-namespaces-not-attached MCP sessions (#708).
+
+    MCP servers can report **Connected** at the CLI/host inventory layer while the
+    active LLM session exposes none of their tool namespaces. That is a *session
+    attachment* failure and is reported here as its own typed condition,
+    ``mcp_connected_namespaces_missing`` — deliberately distinct from config drift
+    (#672), transport-closed (#584), and resolver EOF (#685).
+
+    Connected is not proof that tools are available. The required preflight proof is
+    live tool visibility plus ``gitea_whoami`` on the role namespace, never host
+    Connected status alone.
+
+    The verdict is recorded in the session so ``gitea_submit_pr_review`` and
+    ``gitea_merge_pr`` fail closed while a required namespace is unattached. The only
+    sanctioned recovery is the client attach/reconnect path followed by full preflight;
+    direct imports, CLI/API mutation, profile hopping, session-state overrides, and
+    process kills are forbidden and never suggested.
+
+    Args:
+        connected_servers: Namespaces the host/CLI reports as Connected.
+        attached_session_namespaces: Namespaces actually exposed in the active
+            session tool surface.
+        required_namespaces: Namespaces required for this workflow; defaults to the
+            canonical Gitea role namespaces.
+        discovery_cache_age_seconds: Age of the client tool-discovery cache entry.
+        discovery_cache_hit: Whether the tool list came from that cache.
+        auto_attach_attempted: Whether the runtime tried to auto-attach namespaces.
+        auto_attach_succeeded: Whether that auto-attach succeeded.
+        session_tool_snapshot_at: Epoch seconds the session tool snapshot was taken.
+        namespace_connected_at: Per-namespace epoch seconds that connect completed,
+            used to identify multi-role startup ordering races.
+
+    Returns:
+        dict with ``discovery_status``, ``missing_namespaces``,
+        ``proof_of_connected_vs_attached``, ``error_type``, ``reconnect_required``,
+        ``auto_recovered``, ``startup_ordering_race``, a secret-free ``telemetry``
+        block, and a reconnect-only ``exact_next_action``.
+    """
+    result = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=connected_servers,
+        attached_session_namespaces=attached_session_namespaces,
+        required_namespaces=required_namespaces,
+        discovery_cache_age_seconds=discovery_cache_age_seconds,
+        discovery_cache_hit=discovery_cache_hit,
+        auto_attach_attempted=auto_attach_attempted,
+        auto_attach_succeeded=auto_attach_succeeded,
+        session_tool_snapshot_at=session_tool_snapshot_at,
+        namespace_connected_at=namespace_connected_at,
+    )
+    _record_live_namespace_attachment(result)
+    # #606-style watchdog check-in (best-effort, fail open). Status only, no names.
+    sentry_observability.monitor_checkin(
+        "namespace_attachment",
+        "ok" if result.get("attachment_healthy") else "error",
+    )
+    return result
+
+
 @mcp.tool()
 def gitea_activate_profile(
     profile_name: str,
@@ -23868,38 +24006,6 @@ def gitea_request_mcp_restart(
     # and a durable incident is raised. Break-glass is the only bypass and its
     # authorization is read from the environment, never self-asserted.
     payload["apply_supported"] = False
-    # #665: correlation id threads impact preview → apply gate → incidents.
-    correlation_id = restart_audit.new_correlation_id()
-    payload["correlation_id"] = correlation_id
-    auth_user = None
-    try:
-        # remote-only: host override is for operator diagnostics, not required here
-        auth_user = (gitea_whoami(remote=remote) or {}).get("username")
-    except Exception:  # noqa: BLE001 — identity is best-effort for audit
-        auth_user = None
-    preview_audit = restart_audit.record_restart_lifecycle(
-        event_type=restart_audit.EVENT_IMPACT_PREVIEW,
-        outcome=str(report.verdict or "unknown"),
-        correlation_id=correlation_id,
-        remote=remote,
-        org=o,
-        repo=r,
-        requesting_session_id=sid,
-        restart_class=restart_class,
-        profile_name=profile_name,
-        authenticated_username=auth_user,
-        reasons=list(report.reasons or []),
-        details={
-            "dry_run": True,
-            "allow_restart": bool(report.allow_restart),
-            "inventory_complete": inventory_complete,
-        },
-        privileged=False,
-    )
-    payload["restart_audit"] = {
-        "correlation_id": correlation_id,
-        "impact_preview_written": preview_audit["audit_written"],
-    }
     if not dry_run:
         proof_obj: dict | None = None
         proof_parse_error: str | None = None
@@ -23952,86 +24058,6 @@ def gitea_request_mcp_restart(
         )
         if not gate.allow and gate.incident is not None:
             payload["incident"] = gate.incident
-
-        # #665: audit apply-gate + materialize durable incidents for failed
-        # drain and break-glass. Privileged apply denies if audit is enabled
-        # and the sink write fails.
-        incident_desc = restart_audit.incident_from_apply_gate(
-            gate_payload={
-                **gate_payload,
-                "incident": gate.incident,
-                "allow": gate.allow,
-            },
-            break_glass=break_glass,
-            correlation_id=correlation_id,
-            requesting_session_id=sid,
-            restart_class=restart_class,
-            remote=remote,
-            org=o,
-            repo=r,
-        )
-        if incident_desc is not None:
-            payload["incident"] = incident_desc
-
-        def _create_restart_incident_issue(
-            *, title, body, labels, org=None, repo=None, **_kw
-        ):
-            return gitea_create_issue(
-                title=title,
-                body=body,
-                labels=labels,
-                remote=remote,
-                host=h,
-                org=org or o,
-                repo=repo or r,
-            )
-
-        apply_audit = restart_audit.record_restart_lifecycle(
-            event_type=(
-                restart_audit.EVENT_BREAK_GLASS
-                if break_glass
-                else restart_audit.EVENT_APPLY_GATE
-            ),
-            outcome=(
-                "break_glass"
-                if break_glass
-                else ("allow" if payload["apply_authorized"] else "deny")
-            ),
-            correlation_id=correlation_id,
-            remote=remote,
-            org=o,
-            repo=r,
-            requesting_session_id=sid,
-            restart_class=restart_class,
-            profile_name=profile_name,
-            authenticated_username=auth_user,
-            reasons=list(gate_payload.get("reasons") or []),
-            details={
-                "apply_authorized": payload["apply_authorized"],
-                "drain_gate_allow": gate_payload.get("drain_gate_allow"),
-                "restart_class_authorized": restart_class_authorized,
-                "break_glass": break_glass,
-                "proof_id": gate_payload.get("proof_id"),
-            },
-            privileged=True,
-            create_incident=incident_desc,
-            create_issue_fn=_create_restart_incident_issue
-            if incident_desc is not None
-            else None,
-            dry_run_incident=False,
-        )
-        payload["restart_audit"] = {
-            "correlation_id": correlation_id,
-            "impact_preview_written": preview_audit["audit_written"],
-            "apply_gate_written": apply_audit["audit_written"],
-            "incident_result": apply_audit.get("incident_result"),
-        }
-        if apply_audit["deny_reasons"]:
-            payload["apply_authorized"] = False
-            payload["reasons"] = list(payload.get("reasons") or []) + list(
-                apply_audit["deny_reasons"]
-            )
-            payload["success"] = True
     return payload
 
 
@@ -24831,7 +24857,11 @@ if __name__ == "__main__":
     # basename-only stack frames, and import-only launch cannot reconstruct
     # native transport; offline imports / standalone scripts fail closed.
     mcp_daemon_guard.mark_sanctioned_daemon()
-    mcp_daemon_guard.bind_native_mcp_transport(transport="stdio")
+    # #931: the transport is no longer a literal here. It comes from deployment
+    # configuration (GITEA_MCP_TRANSPORT), defaults to stdio when unset, and is
+    # validated against the single permitted set in mcp_transport_config. An
+    # unregistered identifier raises here, before any tool can dispatch.
+    mcp_daemon_guard.bind_native_mcp_transport()
     # Lock this session's launch profile into the environment so child CLI
     # processes (e.g. review_pr.py) can detect and refuse profile
     # side-channel overrides (#199).
@@ -24849,4 +24879,11 @@ if __name__ == "__main__":
     sys.stderr.write(
         f"--- Sentry observability: {_sentry_status.get('reason')} ---\n"
     )
-    mcp.run(transport="stdio")
+    # #931: serve over exactly the transport that was bound and pinned, and only
+    # if this entrypoint is commissioned to execute it. Recognition is not
+    # execution authorization (review 635): a registered remote identifier is
+    # bound, pinned and recorded, but serving it would start a listener with no
+    # authentication or per-request principal, which #938 owns. An absent bind
+    # keeps its pre-existing #695 failure; an uncommissioned transport fails
+    # closed here, before any listener exists and before any tool can dispatch.
+    mcp.run(transport=mcp_daemon_guard.authorize_transport_execution("tool service"))

irrecoverable_provenance.py

@@ -500,6 +500,11 @@ def assess_transport_for_auth_mint() -> dict[str, Any]:
     native = mcp_daemon_guard.is_native_mcp_transport()
     pytest = mcp_daemon_guard.is_pytest_runtime()
     production = mcp_daemon_guard.is_production_native_mcp_transport()
+    # #931: report which transport underwrites the verdict, read through the
+    # one shared accessor rather than assumed to be stdio. The gate's decision
+    # is unchanged here; naming the transport is what lets #932 re-derive the
+    # guarantee from an authenticated session instead of from the bind.
+    bound = mcp_daemon_guard.bound_transport()
     if not native and not pytest:
         reasons.append(
             "irrecoverable provenance authorization requires production native "
@@ -510,6 +515,7 @@ def assess_transport_for_auth_mint() -> dict[str, Any]:
         "allowed": not reasons,
         "native_mcp_transport": native,
         "production_native_mcp_transport": production,
+        "bound_transport": bound,
         "pytest": pytest,
         "reasons": reasons,
     }

mcp_daemon_guard.py

@@ -32,6 +32,8 @@ import time
 from pathlib import Path
 from typing import Any
 
+import mcp_transport_config
+
 SANCTIONED_DAEMON_ENV = "GITEA_MCP_SANCTIONED_DAEMON"
 ALLOW_DIRECT_IMPORT_ENV = "GITEA_ALLOW_DIRECT_MCP_IMPORT"
 ALLOW_KEYCHAIN_CLI_ENV = "GITEA_ALLOW_KEYCHAIN_CLI"
@@ -42,7 +44,9 @@ FORCE_PROVENANCE_FAIL_ENV = "GITEA_TEST_FORCE_UNSANCTIONED"
 _NATIVE_RUNTIME: dict[str, Any] | None = None
 
 # Production transport identifiers accepted by bind_native_mcp_transport.
-_PRODUCTION_TRANSPORTS = frozenset({"stdio"})
+# #931: the permitted set is defined once, in mcp_transport_config. This name
+# is kept as an alias so the guard never restates a transport identifier.
+_PRODUCTION_TRANSPORTS = mcp_transport_config.SUPPORTED_TRANSPORTS
 _RUNTIME_MODE_PRODUCTION = "production"
 _RUNTIME_MODE_TEST = "test"
 _PHASE_ENTRYPOINT_CLAIMED = "entrypoint_claimed"
@@ -58,6 +62,23 @@ class UnsanctionedRuntimeError(RuntimeError):
     """Raised when mutation/credential code runs outside a native MCP daemon."""
 
 
+class TransportExecutionError(UnsanctionedRuntimeError):
+    """Raised when a bound transport may not be served by this entrypoint (#931).
+
+    Subclasses :class:`UnsanctionedRuntimeError` so every existing fail-closed
+    handler still catches it, while letting a caller that cares distinguish
+    "nothing is bound" from "something valid is bound but its listener has not
+    been commissioned". Carries the structured verdict on ``.assessment``.
+    """
+
+    def __init__(self, message: str, assessment: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.assessment = assessment or {}
+        self.blocker_kind = self.assessment.get("blocker_kind")
+        self.owner_issue = self.assessment.get("owner_issue")
+        self.transport = self.assessment.get("transport")
+
+
 def is_pytest_runtime() -> bool:
     if (os.environ.get(FORCE_PROVENANCE_FAIL_ENV) or "").strip() in {
         "1",
@@ -171,23 +192,46 @@ def mark_sanctioned_daemon() -> dict[str, Any]:
     return native_runtime_status()
 
 
-def bind_native_mcp_transport(*, transport: str) -> dict[str, Any]:
+def bind_native_mcp_transport(*, transport: str | None = None) -> dict[str, Any]:
-    """Bind the live native MCP transport lifecycle (#695).
+    """Bind the live native MCP transport lifecycle (#695 / #931).
 
     Must be called from the resolved canonical entrypoint immediately before
-    the real MCP server transport loop (e.g. ``mcp.run(transport=\"stdio\")``).
+    the real MCP server transport loop (``mcp.run``). Requires a prior
-    Requires a prior successful :func:`mark_sanctioned_daemon` claim in this
+    successful :func:`mark_sanctioned_daemon` claim in this process.
-    process. Import-only or offline launch without this bind leaves
+    Import-only or offline launch without this bind leaves
     :func:`is_native_mcp_transport` false.
+
+    #931: ``transport`` is now optional. Omitting it — which is what the
+    production entrypoint does — resolves the identifier from deployment
+    configuration via :func:`mcp_transport_config.resolve_configured_transport`,
+    yielding :data:`mcp_transport_config.DEFAULT_TRANSPORT` when nothing is
+    configured. An explicit argument remains supported for tests and for a
+    launcher that has already resolved the value. Either way the identifier is
+    validated against the single permitted set before the runtime record is
+    written, so no tool can dispatch over an unregistered transport.
+
+    The resolved value is pinned into the process-local record and is read back
+    only through :func:`bound_transport`. Rebinding to a different transport is
+    refused, so two guards can never observe different values in one process.
     """
     global _NATIVE_RUNTIME
-    transport_name = (transport or "").strip().lower()
+    if transport is None:
-    if transport_name not in _PRODUCTION_TRANSPORTS:
+        resolution = mcp_transport_config.resolve_configured_transport()
-        raise UnsanctionedRuntimeError(
+        transport_name = str(resolution["transport"])
-            f"bind_native_mcp_transport rejected: transport {transport!r} is "
+        if not resolution["supported"]:
-            f"not a production MCP transport (#695). Allowed: "
+            raise UnsanctionedRuntimeError(
-            f"{sorted(_PRODUCTION_TRANSPORTS)}."
+                "bind_native_mcp_transport rejected: "
-        )
+                + "; ".join(resolution["reasons"])
+                + " No tool is served over an unregistered transport."
+            )
+    else:
+        transport_name = mcp_transport_config.normalize_transport(transport)
+        if transport_name not in _PRODUCTION_TRANSPORTS:
+            raise UnsanctionedRuntimeError(
+                f"bind_native_mcp_transport rejected: transport {transport!r} is "
+                f"not a production MCP transport (#695). Allowed: "
+                f"{sorted(_PRODUCTION_TRANSPORTS)}."
+            )
 
     entrypoint_path = _caller_official_entrypoint_path()
     if entrypoint_path is None:
@@ -216,6 +260,23 @@ def bind_native_mcp_transport(*, transport: str) -> dict[str, Any]:
             "between mark and bind (#695)."
         )
 
+    # #931: one process binds one transport. Re-binding the same identifier is
+    # idempotent (a retried launch step must not fail); re-binding a different
+    # one is refused, because a guard that already read the first value would
+    # otherwise disagree with a guard that reads the second.
+    already_bound = (_NATIVE_RUNTIME.get("transport") or "").strip()
+    if (
+        already_bound
+        and _NATIVE_RUNTIME.get("phase") == _PHASE_TRANSPORT_BOUND
+        and already_bound != transport_name
+    ):
+        raise UnsanctionedRuntimeError(
+            "bind_native_mcp_transport rejected: transport is already bound to "
+            f"{already_bound!r} in this process; rebinding to "
+            f"{transport_name!r} is forbidden (#931). Restart the server to "
+            "change the deployment transport."
+        )
+
     # Pin session-state root for this server lifetime (#695 AC2 / PR #701).
     # Changing GITEA_MCP_SESSION_STATE_DIR after bind must not manufacture a
     # second authority domain for decision locks / workflow proofs.
@@ -353,6 +414,88 @@ def is_production_native_mcp_transport() -> bool:
     return (_NATIVE_RUNTIME or {}).get("mode") == _RUNTIME_MODE_PRODUCTION
 
 
+def bound_transport() -> str | None:
+    """The one authoritative bound transport identifier, or ``None`` (#931).
+
+    This is the shared accessor every transport-aware guard reads. It reports
+    the value pinned at bind time, never the environment, so changing
+    ``GITEA_MCP_TRANSPORT`` after the bind cannot move what a guard observes —
+    the same rule :func:`pinned_session_state_dir` applies to session state.
+
+    ``None`` means unbound: an offline import or a launch that never reached
+    the bind. Callers must treat that as fail-closed, exactly as they already
+    treat :func:`is_native_mcp_transport` returning false.
+    """
+    if not is_native_mcp_transport():
+        return None
+    return (_NATIVE_RUNTIME or {}).get("transport") or None
+
+
+def assert_transport_bound(context: str = "tool service") -> str:
+    """Return the bound transport, or fail closed before *context* (#931).
+
+    Called immediately before the server enters its transport loop so an
+    invalid or absent bind stops the process rather than serving tools over a
+    transport no guard can name.
+    """
+    transport = bound_transport()
+    if transport:
+        return transport
+    raise UnsanctionedRuntimeError(
+        f"No MCP transport is bound; refusing {context} (#931). "
+        "bind_native_mcp_transport must succeed from the canonical entrypoint "
+        "before any tool is served. Offline import and standalone launch "
+        "cannot reconstruct a bind."
+    )
+
+
+def assess_serve_authorization() -> dict[str, Any]:
+    """Structured verdict on whether this process may serve tools (#931).
+
+    This is the decision that consumes :func:`bound_transport`. It is what stops
+    the bound identifier from being reporting-only metadata: the serve path
+    cannot proceed unless the value pinned at bind is one this entrypoint is
+    commissioned to execute.
+
+    Never raises; returns the verdict so callers and diagnostics can inspect it.
+    """
+    return mcp_transport_config.assess_transport_execution(bound_transport())
+
+
+def authorize_transport_execution(context: str = "tool service") -> str:
+    """Return the transport this process may serve, or fail closed (#931).
+
+    Two distinct boundaries, in order:
+
+    1. **Bind presence** — :func:`assert_transport_bound` enforces the
+       pre-existing #695 contract, so an unbound runtime keeps its established
+       failure and reason code.
+    2. **Execution authorization** — the bound identifier must be one this
+       entrypoint is commissioned to serve. A registered transport whose
+       listener has not been commissioned is refused here, before any listener
+       is created and before any tool can dispatch.
+
+    That ordering matters: recognition, validation and durable recording all
+    still happen for a remote identifier, so #931's seam is intact; only the act
+    of *serving* it is withheld until its owning issue commissions it.
+    """
+    # Boundary 1: unbound stays exactly as fail-closed as it was under #695.
+    assert_transport_bound(context)
+
+    # Boundary 2: bound, but is this entrypoint allowed to serve it?
+    assessment = assess_serve_authorization()
+    if assessment.get("allowed"):
+        return str(assessment["transport"])
+
+    reasons = "; ".join(assessment.get("reasons") or []) or "not authorized"
+    next_action = assessment.get("exact_next_action") or ""
+    raise TransportExecutionError(
+        f"Refusing {context} (#931) [{assessment.get('blocker_kind')}]: "
+        f"{reasons} {next_action}".strip(),
+        assessment,
+    )
+
+
 def is_sanctioned_mcp_daemon() -> bool:
     """Backward-compatible name; #695 requires native transport, not env alone."""
     if is_production_native_mcp_transport():
@@ -476,6 +619,21 @@ def native_runtime_status() -> dict[str, Any]:
         "entrypoint_path": rt.get("entrypoint_path"),
         "phase": rt.get("phase"),
         "transport": rt.get("transport"),
+        # #931: the authoritative bound identifier, plus the seam that defines
+        # what may be bound. ``bound_transport`` is None until a bind succeeds,
+        # so an offline import is distinguishable from a stdio session.
+        "bound_transport": bound_transport(),
+        "transport_bound": bound_transport() is not None,
+        "default_transport": mcp_transport_config.DEFAULT_TRANSPORT,
+        "supported_transports": list(mcp_transport_config.supported_transports()),
+        "transport_env": mcp_transport_config.TRANSPORT_ENV,
+        # #931 review 635: recognition and execution authorization are distinct.
+        # ``supported`` is what may be bound; ``executable`` is what this
+        # entrypoint may actually serve. A recognized-but-uncommissioned
+        # transport reports serve_authorized False with a named blocker.
+        "executable_transports": list(mcp_transport_config.executable_transports()),
+        "serve_authorized": bool(assess_serve_authorization().get("allowed")),
+        "serve_authorization": assess_serve_authorization(),
         "mode": rt.get("mode"),
         "session_state_dir": pinned_session_state_dir() or rt.get("session_state_dir"),
         "session_state_dir_pinned": pinned_session_state_dir() is not None,
@@ -502,7 +660,12 @@ def mutation_provenance_fields() -> dict[str, Any]:
     if st.get("mode") == _RUNTIME_MODE_TEST and st["native_mcp_transport"]:
         transport = "test_native_mcp"
     return {
+        # ``transport`` stays the trust *class* it has always been, so existing
+        # durable records keep their shape. ``bound_transport`` (#931) adds the
+        # bound identifier itself, which is what lets an operator tell from a
+        # durable record which transport performed a mutation.
         "transport": transport,
+        "bound_transport": st.get("bound_transport"),
         "native_mcp_transport": bool(st["native_mcp_transport"]),
         "production_native_mcp_transport": bool(
             st.get("production_native_mcp_transport")

mcp_namespace_health.py

@@ -51,6 +51,42 @@ EOF_PATTERNS = (
     "eof",
 )
 
+ERROR_CONNECTED_NAMESPACES_MISSING = "mcp_connected_namespaces_missing"
+
+# Distinct from the condition above. ``mcp_connected_namespaces_missing`` is reserved for
+# the actual #708 defect: the host *does* report the service Connected, yet the namespace
+# never entered the active session tool surface. A required namespace that is absent from
+# the connected-service inventory has no Connected claim behind it at all, so reporting it
+# under the #708 condition would assert something the evidence does not support and would
+# point an operator at the wrong recovery.
+ERROR_REQUIRED_NAMESPACES_NOT_CONNECTED = "mcp_required_namespaces_not_connected"
+
+DISCOVERY_STATUS_ATTACHED = "namespaces_attached"
+DISCOVERY_STATUS_CONNECTED_MISSING = "connected_but_namespaces_missing"
+DISCOVERY_STATUS_NOT_CONNECTED = "required_namespaces_not_connected"
+DISCOVERY_STATUS_DISCONNECTED = "disconnected"
+
+# Namespaces that must be *attached to the active session* for a mutation task (#708).
+# Connected-at-host is not attached-in-session; these are gated separately from the
+# #543 health map because a namespace can be healthy on probe yet absent from the
+# session tool surface.
+ATTACHMENT_GATED_TASKS = {
+    "review_pr": "gitea-reviewer",
+    "submit_review": "gitea-reviewer",
+    "merge_pr": "gitea-merger",
+    "work_issue": "gitea-author",
+    "create_pr": "gitea-author",
+}
+
+# The only sanctioned recovery for an unattached namespace (#678 exposes it natively).
+SANCTIONED_ATTACH_RECOVERY_TOOL = "gitea_request_mcp_reconnect"
+
+UNSAFE_FALLBACK_WARNING = (
+    "Workflow Safety Hard Stop (#708): Connected-but-namespaces-missing recovery must "
+    "NEVER use direct imports, Gitea API mutations, profile hopping, session-state "
+    "overrides, PID kills, or config mtime touches. Use client reconnect only."
+)
+
 SAFE_ENV_KEYS = (
     "GITEA_MCP_PROFILE",
     "GITEA_PROFILE_NAME",
@@ -60,6 +96,309 @@ SAFE_ENV_KEYS = (
 )
 
 
+def assess_connected_namespace_attachment(
+    *,
+    connected_servers: list[str] | tuple[str, ...] | set[str] | None = None,
+    attached_session_namespaces: list[str] | tuple[str, ...] | set[str] | None = None,
+    required_namespaces: list[str] | tuple[str, ...] | set[str] | None = None,
+    discovery_cache_age_seconds: float | int | None = None,
+    discovery_cache_hit: bool | None = None,
+    auto_attach_attempted: bool = False,
+    auto_attach_succeeded: bool = False,
+    session_tool_snapshot_at: float | int | None = None,
+    namespace_connected_at: dict[str, float] | None = None,
+) -> dict[str, Any]:
+    """Assess whether host-connected MCP servers have attached tool namespaces in the active session (#708).
+
+    Addresses the Connected-but-namespaces-missing defect: CLI/host status may report Connected
+    while the active LLM session tool surface exposes 0 attached tool namespaces.
+
+    This is a *distinct* condition from config drift (#672), transport-closed (#584),
+    and resolver EOF (#685): the transport is up and the host reports Connected, yet the
+    namespace never entered the session tool surface.
+
+    Startup ordering (``session_tool_snapshot_at`` + ``namespace_connected_at``) identifies
+    the race where the session tool snapshot was taken before a role server finished
+    ``initialize``/``list_tools``, which is why parallel multi-role startup can leave the
+    session with an empty namespace set while Connected later flips true.
+
+    Returns structured detection details plus secret-free telemetry.
+    """
+    connected = [str(s).strip() for s in (connected_servers or []) if str(s).strip()]
+    attached = set(str(ns).strip() for ns in (attached_session_namespaces or []) if str(ns).strip())
+    req = [str(r).strip() for r in (required_namespaces or DEFAULT_NAMESPACES) if str(r).strip()]
+
+    required = list(dict.fromkeys(req))
+    connected_set = set(connected)
+
+    proof: dict[str, dict[str, bool]] = {}
+    for s in connected:
+        proof[s] = {"connected": True, "attached": s in attached}
+    for r in required:
+        if r not in proof:
+            proof[r] = {"connected": r in connected_set, "attached": r in attached}
+
+    # The genuine #708 condition: the host reports the service Connected and the namespace
+    # still never entered the active session tool surface.
+    missing = [r for r in required if r in connected_set and r not in attached]
+    # A separate condition: the service is required but absent from the connected-service
+    # inventory. Nothing here is Connected, so this must not borrow the #708 wording or its
+    # recovery — see ERROR_REQUIRED_NAMESPACES_NOT_CONNECTED.
+    not_connected = [r for r in required if r not in connected_set]
+    # Evidence that disagrees with itself: reported attached to the session while absent
+    # from the connected inventory. Neither statement is proof, so it fails closed.
+    contradictory = [r for r in not_connected if r in attached]
+
+    # No required namespace may lack attachment proof and still be called healthy.
+    attachment_healthy = (
+        not missing
+        and not not_connected
+        and len(connected) > 0
+        and len(required) > 0
+    )
+
+    if attachment_healthy:
+        discovery_status = DISCOVERY_STATUS_ATTACHED
+    elif not connected:
+        discovery_status = DISCOVERY_STATUS_DISCONNECTED
+    elif not_connected:
+        discovery_status = DISCOVERY_STATUS_NOT_CONNECTED
+    else:
+        discovery_status = DISCOVERY_STATUS_CONNECTED_MISSING
+
+    # Every condition actually present is reported; ``error_type`` names the primary one.
+    # Not-connected outranks Connected-but-unattached because a service that never
+    # connected cannot be recovered by attaching its namespace.
+    error_types: list[str] = []
+    if not_connected:
+        error_types.append(ERROR_REQUIRED_NAMESPACES_NOT_CONNECTED)
+    if missing:
+        error_types.append(ERROR_CONNECTED_NAMESPACES_MISSING)
+    if not attachment_healthy and not error_types:
+        error_types.append(ERROR_REQUIRED_NAMESPACES_NOT_CONNECTED)
+    error_type = None if attachment_healthy else error_types[0]
+
+    # Per-namespace verdict, so a mutation gate never has to infer one namespace's state
+    # from a whole-session summary. Each entry states only what its own evidence supports.
+    namespace_conditions: dict[str, dict[str, Any]] = {}
+    for ns_name, state in proof.items():
+        ns_connected = bool(state["connected"])
+        ns_attached = bool(state["attached"])
+        if ns_connected and ns_attached:
+            condition = None
+        elif ns_connected:
+            condition = ERROR_CONNECTED_NAMESPACES_MISSING
+        else:
+            condition = ERROR_REQUIRED_NAMESPACES_NOT_CONNECTED
+        namespace_conditions[ns_name] = {
+            "namespace": ns_name,
+            "required": ns_name in required,
+            "connected": ns_connected,
+            "attached": ns_attached,
+            "attachment_healthy": ns_connected and ns_attached,
+            "condition": condition,
+            "contradictory_evidence": ns_attached and not ns_connected,
+        }
+
+    # Startup-ordering race: a namespace that finished connecting *after* the session
+    # tool snapshot was taken cannot be in that snapshot, however healthy it looks now.
+    connected_at = {
+        str(k).strip(): v
+        for k, v in (namespace_connected_at or {}).items()
+        if str(k).strip() and isinstance(v, (int, float))
+    }
+    late_attaching: list[str] = []
+    if isinstance(session_tool_snapshot_at, (int, float)):
+        for ns_name, ts in connected_at.items():
+            if ts > session_tool_snapshot_at and ns_name not in attached:
+                late_attaching.append(ns_name)
+    late_attaching.sort()
+    startup_ordering_race = bool(late_attaching)
+
+    auto_recovered = bool(auto_attach_attempted and auto_attach_succeeded and attachment_healthy)
+    reconnect_required = not attachment_healthy
+
+    reasons: list[str] = []
+    remediation: list[str] = []
+    if not connected:
+        reasons.append("No MCP servers reported Connected.")
+        remediation.append("Start or reconnect Gitea MCP servers in client config.")
+    if missing:
+        reasons.append(
+            f"MCP server(s) {missing} report Connected at host/CLI layer but tool namespaces "
+            f"are missing from active session attached tools (Connected ≠ attached tools, #708)."
+        )
+        remediation.append(
+            "Reconnect the IDE/client MCP session to attach namespaces to the active session "
+            f"(sanctioned path: {SANCTIONED_ATTACH_RECOVERY_TOOL}), then re-run full preflight "
+            "(gitea_whoami -> gitea_resolve_task_capability -> task). "
+            "Do not use direct imports, CLI API mutations, profile hopping, or session file overrides."
+        )
+    if not_connected:
+        reasons.append(
+            f"required MCP namespace(s) {not_connected} are absent from the connected-service "
+            "inventory: nothing reports them Connected, so there is no attachment to claim and "
+            "the Connected-but-unattached condition does not apply to them (#708)."
+        )
+        remediation.append(
+            f"Connect the required MCP server(s) {not_connected} through the client, then "
+            "reconnect the IDE/client MCP session so their namespaces attach "
+            f"(sanctioned path: {SANCTIONED_ATTACH_RECOVERY_TOOL}), and re-run full preflight. "
+            "Do not use direct imports, CLI API mutations, profile hopping, or session file overrides."
+        )
+    if contradictory:
+        reasons.append(
+            f"contradictory evidence for namespace(s) {contradictory}: reported attached to the "
+            "active session while absent from the connected-service inventory; neither statement "
+            "is proof, so attachment is treated as unproven (fail closed, #708)."
+        )
+    if attachment_healthy:
+        reasons.append(
+            "All required MCP server namespaces are connected and attached to the active session."
+        )
+
+    if startup_ordering_race:
+        reasons.append(
+            f"startup ordering race: namespace(s) {late_attaching} finished connecting after the "
+            "active session tool snapshot was taken, so they cannot appear in that snapshot (#708)."
+        )
+    if auto_attach_attempted and not auto_attach_succeeded:
+        reasons.append(
+            "automatic namespace attachment was attempted and did not succeed; only the sanctioned "
+            "client reconnect path remains."
+        )
+    if auto_recovered:
+        reasons.append("namespaces were automatically attached; no operator reconnect was required.")
+
+    return {
+        "success": attachment_healthy,
+        "attachment_healthy": attachment_healthy,
+        "discovery_status": discovery_status,
+        "connected_servers": connected,
+        "attached_session_namespaces": list(attached),
+        "missing_namespaces": missing,
+        "not_connected_namespaces": not_connected,
+        "contradictory_namespaces": contradictory,
+        "proof_of_connected_vs_attached": proof,
+        "namespace_conditions": namespace_conditions,
+        "error_type": error_type,
+        "error_types": error_types,
+        "reasons": reasons,
+        "remediation": remediation,
+        "exact_next_action": (
+            "None; session tool namespaces attached."
+            if attachment_healthy
+            else (
+                f"Connect the required MCP server(s) {not_connected} through the client, then "
+                "reconnect the IDE/client MCP session so their tool namespaces attach to the "
+                "active session. Do not use direct imports, CLI API mutations, profile hopping, "
+                "or session-state overrides."
+                if not_connected
+                else (
+                    "Reconnect the IDE/client MCP session so tool namespaces attach to the active "
+                    "session. Do not use direct imports, CLI API mutations, profile hopping, or "
+                    "session-state overrides."
+                )
+            )
+        ),
+        "unsafe_fallback_policy": UNSAFE_FALLBACK_WARNING,
+        "sanctioned_recovery_tool": SANCTIONED_ATTACH_RECOVERY_TOOL,
+        "reconnect_required": reconnect_required,
+        "auto_attach_attempted": bool(auto_attach_attempted),
+        "auto_recovered": auto_recovered,
+        "startup_ordering_race": startup_ordering_race,
+        "late_attaching_namespaces": late_attaching,
+        # Secret-free structured signals (#708 AC5). Namespace names and counts only:
+        # never tokens, endpoints, env values, or filesystem paths.
+        "telemetry": {
+            "connected_count": len(connected),
+            "attached_count": len(attached),
+            "required_count": len(required),
+            "missing_count": len(missing),
+            "not_connected_count": len(not_connected),
+            "contradictory_count": len(contradictory),
+            "required_attached_count": sum(1 for r in required if r in attached),
+            "discovery_status": discovery_status,
+            "discovery_cache_hit": (
+                None if discovery_cache_hit is None else bool(discovery_cache_hit)
+            ),
+            "discovery_cache_age_seconds": (
+                float(discovery_cache_age_seconds)
+                if isinstance(discovery_cache_age_seconds, (int, float))
+                else None
+            ),
+            "reconnect_required": reconnect_required,
+            "auto_attach_attempted": bool(auto_attach_attempted),
+            "auto_recovered": auto_recovered,
+            "startup_ordering_race": startup_ordering_race,
+            "error_type": error_type,
+            "error_types": error_types,
+        },
+    }
+
+
+def required_namespace_for_attachment(task: str) -> str | None:
+    """Map a mutation task to the MCP namespace that must be *attached* (#708)."""
+    return ATTACHMENT_GATED_TASKS.get((task or "").strip())
+
+
+def attachment_gate_from_session(
+    task: str,
+    session_attachment: dict[str, dict[str, Any]] | None,
+) -> list[str]:
+    """Fail-closed gate on recorded connected-but-unattached namespaces (#708).
+
+    Mirrors :func:`mutation_gate_from_session`: a namespace that has not been
+    assessed yet does not gate, so this never blocks a session that simply has
+    not run the assessment. Once an assessment records the namespace required
+    for *task* as Connected-but-unattached, the mutation fails closed and the
+    only offered recovery is the sanctioned client reconnect path.
+    """
+    ns = required_namespace_for_attachment(task)
+    if not ns:
+        return []
+    store = session_attachment or {}
+    entry = store.get(ns)
+    if not entry:
+        return []
+    if entry.get("attached") and entry.get("attachment_healthy"):
+        return []
+
+    what = task or "mutation"
+    connected = entry.get("connected")
+    detail = entry.get("condition") or entry.get("error_type")
+    if connected is True:
+        # Only here has anything actually reported the service Connected, so only here may
+        # the block say so.
+        detail = detail or ERROR_CONNECTED_NAMESPACES_MISSING
+        blocked = (
+            f"live MCP namespace '{ns}' is recorded {detail}: the host reports Connected but the "
+            f"namespace is not attached to the active session tool surface; reconnect the "
+            f"IDE/client MCP session and re-run preflight before {what} "
+            "(fail closed, #708)"
+        )
+    elif connected is False:
+        detail = ERROR_REQUIRED_NAMESPACES_NOT_CONNECTED
+        blocked = (
+            f"live MCP namespace '{ns}' is recorded {detail}: it is absent from the "
+            f"connected-service inventory, so it is neither connected nor attached and no "
+            f"Connected status is claimed for it; connect the required MCP server, then "
+            f"reconnect the IDE/client MCP session and re-run preflight before {what} "
+            "(fail closed, #708)"
+        )
+    else:
+        # Connected status was never recorded. Refuse without asserting either condition.
+        detail = detail or ERROR_CONNECTED_NAMESPACES_MISSING
+        blocked = (
+            f"live MCP namespace '{ns}' is recorded {detail} with no connected-status evidence, "
+            f"so attachment to the active session tool surface is unproven; reconnect the "
+            f"IDE/client MCP session and re-run preflight before {what} "
+            "(fail closed, #708)"
+        )
+    return [blocked, UNSAFE_FALLBACK_WARNING]
+
+
+
 def _as_list(value: Any) -> list[str] | None:
     if value is None:
         return None

mcp_server.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python3
 """Gitea MCP Server — exposes Gitea operations as MCP tools.
 
-Runs over stdio. All tools authenticate via macOS keychain (git credential fill).
+The transport is selected by deployment configuration (GITEA_MCP_TRANSPORT) and
+defaults to the local client-spawned transport when unset (#931); the permitted
+set lives in mcp_transport_config. All tools authenticate via macOS keychain
+(git credential fill).
 """
 import os
 import sys
@@ -43,8 +46,9 @@ check_conflict_markers()
 
 # #558 / #695: claim the official entrypoint before loading mutation modules.
 # This alone does NOT authorize mutations — gitea_mcp_server binds the live
-# native MCP transport (stdio) immediately before mcp.run. Import-only or
+# native MCP transport immediately before mcp.run, over the configured
-# offline launch without that bind fails closed on mutations.
+# transport (#931). Import-only or offline launch without that bind fails
+# closed on mutations.
 try:
     import mcp_daemon_guard
 

mcp_session_state.py

@@ -588,9 +588,13 @@ def save_state(
                 bool(prov.get("production_native_mcp_transport")),
             )
             body.setdefault("transport", prov.get("transport"))
+            # #931: record the bound transport identifier itself, so a durable
+            # decision lock names which transport performed the mutation.
+            body.setdefault("bound_transport", prov.get("bound_transport"))
         except Exception:
             body.setdefault("native_mcp_transport", False)
             body.setdefault("transport", "untrusted")
+            body.setdefault("bound_transport", None)
 
         envelope = {
             "kind": kind,

mcp_transport_config.py

@@ -0,0 +1,292 @@
+"""Single authoritative source for the bound MCP transport identifier (#931).
+
+Before this module the transport was a literal, passed once at the bottom of
+``gitea_mcp_server`` as ``bind_native_mcp_transport(transport="stdio")``. Every
+guard that later asks "is this a trusted native session" resolves that question
+through the value bound there, so the literal was effectively a constant in the
+authorization chain rather than configuration.
+
+This module is the seam. It owns three things and nothing else:
+
+- the permitted set of transport identifiers,
+- the default used when deployment configuration says nothing,
+- the resolution of the configured value into a validated identifier.
+
+It deliberately holds no state. The *bound* transport is pinned once, at bind
+time, into the process-local native-runtime record owned by
+:mod:`mcp_daemon_guard`, and is read back through
+``mcp_daemon_guard.bound_transport()``. That split matters: configuration is
+read exactly once, before any tool can dispatch, so a later environment change
+cannot move the value a guard observes — the same pinning rule already applied
+to the session-state root under #695 AC2.
+
+Nothing here consumes tool arguments, request bodies, or provenance fields. The
+only input is the deployment environment, read at bind time.
+
+Standing up a listener for a non-stdio transport is #938; this module only
+makes the identifier expressible and validated.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+# Deployment configuration key. Read once, at bind time, and never again.
+TRANSPORT_ENV = "GITEA_MCP_TRANSPORT"
+
+# The local, client-spawned transport. Unset configuration resolves to this,
+# which is what keeps every existing stdio deployment byte-identical.
+DEFAULT_TRANSPORT = "stdio"
+
+# The sanctioned remote transport identifier. Accepting it here is what makes
+# the bind pluggable; the endpoint that serves it belongs to #938. The name
+# matches the MCP transport name so no second vocabulary has to be mapped.
+REMOTE_TRANSPORT = "streamable-http"
+
+# The permitted set. This is the only place transport identifiers are
+# enumerated; guards consult it rather than restating any member.
+#
+# ``sse`` is a real MCP transport and is deliberately absent: it is the
+# superseded remote transport, and admitting it would give the deployment two
+# remote paths to reason about. An unregistered identifier must fail closed at
+# bind time, and ``sse`` is held to that rule like any other.
+SUPPORTED_TRANSPORTS = frozenset({DEFAULT_TRANSPORT, REMOTE_TRANSPORT})
+
+# Recognition is not execution authorization (#931, review 635 B1/B2).
+#
+# SUPPORTED_TRANSPORTS answers "is this an identifier this system knows, and may
+# it be bound, pinned and recorded?". It deliberately includes the remote
+# identifier, because #931 requires the bind to become pluggable.
+#
+# EXECUTABLE_TRANSPORTS answers a strictly narrower question: "is this entrypoint
+# commissioned to actually *serve* on that transport?". Only the local transport
+# is. Handing ``streamable-http`` to ``mcp.run`` would start FastMCP's HTTP
+# listener with no authentication, no TLS and no per-request principal — the
+# endpoint #938 owns and gates. Recognition must therefore never imply execution.
+#
+# #938 commissions the remote listener by adding REMOTE_TRANSPORT here, together
+# with the authentication and principal boundary its acceptance criteria require.
+EXECUTABLE_TRANSPORTS = frozenset({DEFAULT_TRANSPORT})
+
+# Which issue owns commissioning each recognized-but-not-executable transport.
+# Used to make the refusal actionable rather than a generic denial.
+TRANSPORT_EXECUTION_OWNER = {REMOTE_TRANSPORT: "#938"}
+
+BLOCKER_TRANSPORT_NOT_BOUND = "transport_not_bound"
+BLOCKER_TRANSPORT_NOT_RECOGNIZED = "transport_not_recognized"
+BLOCKER_LISTENER_NOT_COMMISSIONED = "transport_listener_not_commissioned"
+
+SOURCE_CONFIGURED = "deployment_configuration"
+SOURCE_DEFAULT = "default"
+
+
+class TransportConfigurationError(ValueError):
+    """Raised when configured transport is outside :data:`SUPPORTED_TRANSPORTS`."""
+
+
+def normalize_transport(value: Any) -> str:
+    """Canonical form of a transport identifier; ``""`` when there is none.
+
+    Non-string values normalize to ``""`` rather than being coerced, so a
+    structured object smuggled in from a caller can never match a member of the
+    permitted set.
+    """
+    if not isinstance(value, str):
+        return ""
+    return value.strip().lower()
+
+
+def supported_transports() -> tuple[str, ...]:
+    """Permitted identifiers, sorted, for messages and status payloads."""
+    return tuple(sorted(SUPPORTED_TRANSPORTS))
+
+
+def is_supported_transport(value: Any) -> bool:
+    """True when *value* normalizes to a member of the permitted set."""
+    return normalize_transport(value) in SUPPORTED_TRANSPORTS
+
+
+def is_remote_transport(value: Any) -> bool:
+    """True when *value* is a permitted transport that is not the local one."""
+    name = normalize_transport(value)
+    return name in SUPPORTED_TRANSPORTS and name != DEFAULT_TRANSPORT
+
+
+def executable_transports() -> tuple[str, ...]:
+    """Transports this entrypoint is commissioned to serve, sorted."""
+    return tuple(sorted(EXECUTABLE_TRANSPORTS))
+
+
+def is_executable_transport(value: Any) -> bool:
+    """True when *value* may actually be served by this entrypoint (#931).
+
+    Strictly narrower than :func:`is_supported_transport`. A recognized
+    identifier that is not executable is a correct, fully-bound configuration
+    whose listener has simply not been commissioned yet.
+    """
+    return normalize_transport(value) in EXECUTABLE_TRANSPORTS
+
+
+def assess_transport_execution(value: Any) -> dict[str, Any]:
+    """Structured serve-authorization verdict for a bound transport (#931).
+
+    This is the decision that separates a *recognized* transport from one this
+    entrypoint may execute. It is deliberately a pure function of the bound
+    identifier so the serve path cannot reach a listener the deployment has not
+    commissioned.
+
+    Args:
+        value: The bound transport identifier, or ``None`` when unbound.
+
+    Returns:
+        dict with ``transport``, ``recognized``, ``executable``, ``allowed``,
+        ``blocker_kind``, ``owner_issue``, ``reasons`` and
+        ``exact_next_action``. ``allowed`` is true only for a bound, recognized,
+        commissioned transport.
+    """
+    name = normalize_transport(value)
+
+    if not name:
+        return {
+            "transport": None,
+            "recognized": False,
+            "executable": False,
+            "allowed": False,
+            "blocker_kind": BLOCKER_TRANSPORT_NOT_BOUND,
+            "owner_issue": None,
+            "supported_transports": list(supported_transports()),
+            "executable_transports": list(executable_transports()),
+            "reasons": [
+                "no transport is bound; the serve path is fail-closed until "
+                "bind_native_mcp_transport succeeds (#695/#931)"
+            ],
+            "exact_next_action": (
+                "Launch through the canonical entrypoint so "
+                "bind_native_mcp_transport runs before tool service."
+            ),
+        }
+
+    recognized = name in SUPPORTED_TRANSPORTS
+    if not recognized:
+        return {
+            "transport": name,
+            "recognized": False,
+            "executable": False,
+            "allowed": False,
+            "blocker_kind": BLOCKER_TRANSPORT_NOT_RECOGNIZED,
+            "owner_issue": None,
+            "supported_transports": list(supported_transports()),
+            "executable_transports": list(executable_transports()),
+            "reasons": [
+                f"transport {name!r} is not a registered MCP transport (#931); "
+                "it should have been refused at bind time"
+            ],
+            "exact_next_action": (
+                f"Set {TRANSPORT_ENV} to one of {list(supported_transports())}."
+            ),
+        }
+
+    if name in EXECUTABLE_TRANSPORTS:
+        return {
+            "transport": name,
+            "recognized": True,
+            "executable": True,
+            "allowed": True,
+            "blocker_kind": None,
+            "owner_issue": None,
+            "supported_transports": list(supported_transports()),
+            "executable_transports": list(executable_transports()),
+            "reasons": [],
+            "exact_next_action": None,
+        }
+
+    owner = TRANSPORT_EXECUTION_OWNER.get(name)
+    owner_text = owner or "the issue that commissions this transport's listener"
+    return {
+        "transport": name,
+        "recognized": True,
+        "executable": False,
+        "allowed": False,
+        "blocker_kind": BLOCKER_LISTENER_NOT_COMMISSIONED,
+        "owner_issue": owner,
+        "supported_transports": list(supported_transports()),
+        "executable_transports": list(executable_transports()),
+        "reasons": [
+            f"transport {name!r} is registered and was bound and recorded, but "
+            f"this entrypoint is not commissioned to serve it (#931). Serving it "
+            f"would start a listener with no authentication, no transport "
+            f"security and no per-request principal; that endpoint is owned by "
+            f"{owner_text}."
+        ],
+        "exact_next_action": (
+            f"Serve on {DEFAULT_TRANSPORT} until {owner_text} commissions the "
+            f"{name!r} listener with its authentication and principal boundary, "
+            f"which adds {name!r} to EXECUTABLE_TRANSPORTS."
+        ),
+    }
+
+
+def resolve_configured_transport(
+    env: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """Resolve the deployment-configured transport without raising.
+
+    Returns the resolution rather than a bare string so a caller can tell an
+    unset value (which legitimately yields :data:`DEFAULT_TRANSPORT`) from a
+    configured value that is not permitted (which must fail closed, never
+    silently degrade to the default).
+
+    Args:
+        env: Environment mapping to read; defaults to ``os.environ``.
+
+    Returns:
+        dict with ``transport`` (normalized; the default when unset),
+        ``configured``, ``source``, ``raw``, ``supported``, and ``reasons``.
+    """
+    source_env = os.environ if env is None else env
+    raw = source_env.get(TRANSPORT_ENV)
+    normalized = normalize_transport(raw)
+    configured = bool(normalized)
+
+    if not configured:
+        return {
+            "transport": DEFAULT_TRANSPORT,
+            "configured": False,
+            "source": SOURCE_DEFAULT,
+            "raw": raw,
+            "supported": True,
+            "supported_transports": list(supported_transports()),
+            "env_key": TRANSPORT_ENV,
+            "reasons": [],
+        }
+
+    supported = normalized in SUPPORTED_TRANSPORTS
+    reasons: list[str] = []
+    if not supported:
+        reasons.append(
+            f"{TRANSPORT_ENV}={normalized!r} is not a registered MCP transport "
+            f"(#931). Registered: {list(supported_transports())}."
+        )
+    return {
+        "transport": normalized,
+        "configured": True,
+        "source": SOURCE_CONFIGURED,
+        "raw": raw,
+        "supported": supported,
+        "supported_transports": list(supported_transports()),
+        "env_key": TRANSPORT_ENV,
+        "reasons": reasons,
+    }
+
+
+def require_configured_transport(env: Mapping[str, str] | None = None) -> str:
+    """Resolved transport identifier, or raise when it is not permitted.
+
+    Raises:
+        TransportConfigurationError: the configured identifier is unregistered.
+    """
+    resolution = resolve_configured_transport(env)
+    if not resolution["supported"]:
+        raise TransportConfigurationError("; ".join(resolution["reasons"]))
+    return str(resolution["transport"])

restart_audit.py

@@ -1,426 +0,0 @@
-"""MCP restart lifecycle audit events and incident materialization (#665).
-
-Restarts and recovery attempts must leave a forensic trail: impact previews,
-drain enter/exit, drain-proof results, apply gate verdicts, break-glass, and
-post-restart reconcile outcomes. Failed drains and break-glass must also raise
-durable Gitea incident issues so they cannot be silently repeated.
-
-This module is the pure + sink layer for that trail:
-
-* **Schema** — ``mcp.restart.*`` event names and a redacted payload builder.
-* **Emission** — append-only via :mod:`gitea_audit` (off when ``GITEA_AUDIT_LOG``
-  is unset; privileged apply can still *require* a successful write).
-* **Incidents** — descriptors for failed drain / break-glass / unguarded restart,
-  plus an optional materializer that creates a Gitea issue through an injected
-  ``create_issue_fn`` (keeps this module free of network I/O in tests).
-
-Design rules:
-
-* **No secrets.** All free text is redacted before write or issue body assembly.
-* **Never raises from emission.** ``emit_restart_event`` returns False on sink
-  failure so callers can decide fail-closed policy for privileged restarts.
-* **Does not restart.** Audit never executes a process restart.
-* **Drain proof stays #661.** This module records what the gate decided; it
-  does not re-verify proofs.
-"""
-
-from __future__ import annotations
-
-import uuid
-from datetime import datetime, timezone
-from typing import Any, Callable, Mapping, Sequence
-
-import gitea_audit
-
-# ── Event vocabulary (stable identifiers for operators + tests) ───────────────
-
-EVENT_IMPACT_PREVIEW = "mcp.restart.impact_preview"
-EVENT_DRAIN_ENTER = "mcp.restart.drain_enter"
-EVENT_DRAIN_EXIT = "mcp.restart.drain_exit"
-EVENT_DRAIN_PROOF = "mcp.restart.drain_proof"
-EVENT_APPLY_GATE = "mcp.restart.apply_gate"
-EVENT_BREAK_GLASS = "mcp.restart.break_glass"
-EVENT_POST_RESTART_RECONCILE = "mcp.restart.post_restart_reconcile"
-EVENT_NARROWER_RECOVERY = "mcp.restart.narrower_recovery"
-EVENT_UNGUARDED_DETECTED = "mcp.restart.unguarded_detected"
-
-RESTART_EVENT_TYPES: frozenset[str] = frozenset(
-    {
-        EVENT_IMPACT_PREVIEW,
-        EVENT_DRAIN_ENTER,
-        EVENT_DRAIN_EXIT,
-        EVENT_DRAIN_PROOF,
-        EVENT_APPLY_GATE,
-        EVENT_BREAK_GLASS,
-        EVENT_POST_RESTART_RECONCILE,
-        EVENT_NARROWER_RECOVERY,
-        EVENT_UNGUARDED_DETECTED,
-    }
-)
-
-# Incident kinds (durable Gitea issues).
-INCIDENT_FAILED_DRAIN = "restart_failed_drain"
-INCIDENT_BREAK_GLASS = "restart_break_glass"
-INCIDENT_RECONCILE_UNRESOLVED = "restart_reconcile_unresolved"
-INCIDENT_UNGUARDED = "restart_unguarded_detected"
-
-DEFAULT_INCIDENT_LABELS: tuple[str, ...] = (
-    "mcp-health",
-    "safety",
-    "observability",
-    "status:ready",
-    "type:bug",
-    "workflow-hardening",
-)
-
-CreateIssueFn = Callable[..., dict[str, Any]]
-
-
-def _utc_now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def new_correlation_id() -> str:
-    """Mint a short correlation id shared across a restart lifecycle."""
-    return f"rst-{uuid.uuid4().hex[:16]}"
-
-
-def build_restart_event(
-    *,
-    event_type: str,
-    outcome: str,
-    correlation_id: str | None = None,
-    remote: str | None = None,
-    org: str | None = None,
-    repo: str | None = None,
-    requesting_session_id: str | None = None,
-    restart_class: str | None = None,
-    profile_name: str | None = None,
-    authenticated_username: str | None = None,
-    reasons: Sequence[str] | None = None,
-    details: Mapping[str, Any] | None = None,
-    now: str | None = None,
-) -> dict[str, Any]:
-    """Build a redacted ``mcp.restart.*`` audit event.
-
-    Raises ``ValueError`` on unknown event types so a typo cannot silently land
-    under a free-form action name.
-    """
-    name = str(event_type or "").strip()
-    if name not in RESTART_EVENT_TYPES:
-        raise ValueError(
-            f"unknown restart audit event_type {name!r}; expected one of "
-            f"{sorted(RESTART_EVENT_TYPES)}"
-        )
-    redacted_reasons = [
-        gitea_audit.redact(str(r)) for r in (reasons or []) if str(r).strip()
-    ]
-    redacted_details = gitea_audit.redact(dict(details or {}))
-    if not isinstance(redacted_details, dict):
-        redacted_details = {"value": redacted_details}
-
-    event = gitea_audit.build_event(
-        action=name,
-        result=str(outcome or "unknown"),
-        remote=remote,
-        repository=f"{org}/{repo}" if org and repo else None,
-        profile_name=profile_name,
-        authenticated_username=authenticated_username,
-        reason="; ".join(redacted_reasons) if redacted_reasons else None,
-        request_metadata={
-            "event_family": "mcp.restart",
-            "correlation_id": correlation_id or new_correlation_id(),
-            "restart_class": restart_class,
-            "requesting_session_id": requesting_session_id,
-            "org": org,
-            "repo": repo,
-            "details": redacted_details,
-            "reasons": redacted_reasons,
-        },
-        now=now or _utc_now_iso(),
-        operation=name,
-    )
-    event["action_type"] = "restart_lifecycle"
-    event["event_type"] = name
-    event["correlation_id"] = (event.get("request_metadata") or {}).get(
-        "correlation_id"
-    )
-    return event
-
-
-def emit_restart_event(event: Mapping[str, Any], *, path: str | None = None) -> bool:
-    """Append *event* to the audit sink. Never raises. Returns write success."""
-    try:
-        return bool(gitea_audit.write_event(dict(event), path=path))
-    except Exception:
-        return False
-
-
-def require_audit_or_deny(
-    *,
-    privileged: bool,
-    written: bool,
-    audit_enabled: bool | None = None,
-) -> list[str]:
-    """Return deny reasons when a privileged restart path fails to audit.
-
-    When audit is not configured (``GITEA_AUDIT_LOG`` unset), privileged apply
-    still proceeds under the rollout policy "enable audit before enforcing
-    deny-on-audit-fail" — but *if* audit is enabled and the write fails,
-    privileged apply is denied (fail closed).
-    """
-    enabled = (
-        gitea_audit.audit_enabled() if audit_enabled is None else bool(audit_enabled)
-    )
-    if not privileged:
-        return []
-    if not enabled:
-        return []
-    if written:
-        return []
-    return [
-        "privileged restart path requires a successful audit write; "
-        "audit sink failed (fail closed, #665)"
-    ]
-
-
-# ── Incident descriptors ──────────────────────────────────────────────────────
-
-
-def build_incident_descriptor(
-    *,
-    kind: str,
-    reasons: Sequence[str],
-    correlation_id: str | None = None,
-    requesting_session_id: str | None = None,
-    restart_class: str | None = None,
-    remote: str | None = None,
-    org: str | None = None,
-    repo: str | None = None,
-    proof_id: str | None = None,
-    at: str | None = None,
-) -> dict[str, Any]:
-    """Build a durable incident descriptor (no network)."""
-    titles = {
-        INCIDENT_FAILED_DRAIN: "Restart denied: drain proof failed the hard gate",
-        INCIDENT_BREAK_GLASS: "Break-glass MCP restart authorized",
-        INCIDENT_RECONCILE_UNRESOLVED: "Post-restart reconcile left unresolved work",
-        INCIDENT_UNGUARDED: "Unguarded MCP restart attempt detected",
-    }
-    title = titles.get(kind, f"MCP restart incident ({kind})")
-    redacted_reasons = [
-        gitea_audit.redact(str(r)) for r in reasons if str(r).strip()
-    ]
-    return {
-        "kind": kind,
-        "title": title,
-        "labels": list(DEFAULT_INCIDENT_LABELS),
-        "reasons": redacted_reasons,
-        "correlation_id": correlation_id,
-        "requesting_session_id": requesting_session_id,
-        "restart_class": restart_class,
-        "remote": remote,
-        "org": org,
-        "repo": repo,
-        "proof_id": proof_id,
-        "at": at or _utc_now_iso(),
-        "source": "restart_audit#665",
-    }
-
-
-def incident_body(descriptor: Mapping[str, Any]) -> str:
-    """Render a redacted markdown body for a Gitea incident issue."""
-    reasons = descriptor.get("reasons") or []
-    reason_lines = "\n".join(f"- {gitea_audit.redact(str(r))}" for r in reasons) or (
-        "- (no reasons recorded)"
-    )
-    return "\n".join(
-        [
-            "<!-- mcp-restart-incident:v1 -->",
-            f"## MCP restart incident (`{descriptor.get('kind')}`)",
-            "",
-            f"**Correlation:** `{descriptor.get('correlation_id') or 'none'}`",
-            f"**Session:** `{descriptor.get('requesting_session_id') or 'none'}`",
-            f"**Class:** `{descriptor.get('restart_class') or 'none'}`",
-            f"**Scope:** `{descriptor.get('remote')}/{descriptor.get('org')}/"
-            f"{descriptor.get('repo')}`",
-            f"**At:** `{descriptor.get('at')}`",
-            f"**Proof id:** `{descriptor.get('proof_id') or 'none'}`",
-            "",
-            "### Reasons",
-            reason_lines,
-            "",
-            "### Operator next steps",
-            "- Treat this as durable follow-up work under the restart-governance umbrella (#655).",
-            "- Do not invent a second restart path; use sanctioned coordinator tools only.",
-            "- Raw secrets must never appear in this issue (already redacted).",
-            "",
-            f"_Source: {descriptor.get('source')}_",
-        ]
-    )
-
-
-def materialize_incident(
-    descriptor: Mapping[str, Any],
-    *,
-    create_issue_fn: CreateIssueFn | None,
-    dry_run: bool = False,
-) -> dict[str, Any]:
-    """Create a Gitea issue from *descriptor* when *create_issue_fn* is provided.
-
-    Returns a result dict with ``created`` / ``issue_number`` / ``dry_run`` /
-    ``reasons``. Never raises.
-    """
-    base: dict[str, Any] = {
-        "created": False,
-        "dry_run": bool(dry_run),
-        "issue_number": None,
-        "kind": descriptor.get("kind"),
-        "reasons": [],
-        "descriptor": dict(descriptor),
-    }
-    if dry_run:
-        base["reasons"] = ["dry-run only; no Gitea issue created"]
-        return base
-    if create_issue_fn is None:
-        base["reasons"] = [
-            "create_issue_fn not provided; incident descriptor retained only"
-        ]
-        return base
-    try:
-        result = create_issue_fn(
-            title=str(descriptor.get("title") or "MCP restart incident"),
-            body=incident_body(descriptor),
-            labels=list(descriptor.get("labels") or DEFAULT_INCIDENT_LABELS),
-            org=descriptor.get("org"),
-            repo=descriptor.get("repo"),
-        )
-        number = None
-        if isinstance(result, dict):
-            number = result.get("number") or result.get("issue_number")
-        if number is not None:
-            base["created"] = True
-            base["issue_number"] = int(number)
-            base["reasons"] = [f"created incident issue #{int(number)}"]
-        else:
-            base["reasons"] = ["create_issue_fn returned no issue number"]
-    except Exception as exc:  # noqa: BLE001 — never break restart path here
-        base["reasons"] = [
-            f"incident issue creation failed: {gitea_audit.redact(str(exc))}"
-        ]
-    return base
-
-
-def record_restart_lifecycle(
-    *,
-    event_type: str,
-    outcome: str,
-    correlation_id: str,
-    remote: str | None = None,
-    org: str | None = None,
-    repo: str | None = None,
-    requesting_session_id: str | None = None,
-    restart_class: str | None = None,
-    profile_name: str | None = None,
-    authenticated_username: str | None = None,
-    reasons: Sequence[str] | None = None,
-    details: Mapping[str, Any] | None = None,
-    privileged: bool = False,
-    create_incident: Mapping[str, Any] | None = None,
-    create_issue_fn: CreateIssueFn | None = None,
-    dry_run_incident: bool = False,
-    audit_path: str | None = None,
-) -> dict[str, Any]:
-    """Emit one restart audit event and optionally materialize an incident.
-
-    Returns ``{event, audit_written, deny_reasons, incident_result}``.
-    """
-    event = build_restart_event(
-        event_type=event_type,
-        outcome=outcome,
-        correlation_id=correlation_id,
-        remote=remote,
-        org=org,
-        repo=repo,
-        requesting_session_id=requesting_session_id,
-        restart_class=restart_class,
-        profile_name=profile_name,
-        authenticated_username=authenticated_username,
-        reasons=reasons,
-        details=details,
-    )
-    written = emit_restart_event(event, path=audit_path)
-    deny = require_audit_or_deny(privileged=privileged, written=written)
-    incident_result = None
-    if create_incident is not None:
-        incident_result = materialize_incident(
-            create_incident,
-            create_issue_fn=create_issue_fn,
-            dry_run=dry_run_incident,
-        )
-    return {
-        "event": event,
-        "audit_written": written,
-        "deny_reasons": deny,
-        "incident_result": incident_result,
-        "correlation_id": correlation_id,
-    }
-
-
-def incident_from_apply_gate(
-    *,
-    gate_payload: Mapping[str, Any],
-    break_glass: bool,
-    correlation_id: str,
-    requesting_session_id: str | None,
-    restart_class: str | None,
-    remote: str | None,
-    org: str | None,
-    repo: str | None,
-) -> dict[str, Any] | None:
-    """Choose an incident descriptor from an apply-gate payload, if required."""
-    reasons = list(gate_payload.get("reasons") or [])
-    proof_id = gate_payload.get("proof_id")
-    if break_glass:
-        return build_incident_descriptor(
-            kind=INCIDENT_BREAK_GLASS,
-            reasons=reasons
-            or ["break-glass restart path used; durable incident required (#665)"],
-            correlation_id=correlation_id,
-            requesting_session_id=requesting_session_id,
-            restart_class=restart_class,
-            remote=remote,
-            org=org,
-            repo=repo,
-            proof_id=proof_id if isinstance(proof_id, str) else None,
-        )
-    # Failed drain / deny path.
-    incident = gate_payload.get("incident")
-    if isinstance(incident, Mapping) and incident:
-        # Normalize gate-provided descriptor into our schema.
-        return build_incident_descriptor(
-            kind=INCIDENT_FAILED_DRAIN,
-            reasons=list(incident.get("reasons") or reasons),
-            correlation_id=correlation_id,
-            requesting_session_id=requesting_session_id
-            or incident.get("requesting_session_id"),
-            restart_class=restart_class,
-            remote=remote,
-            org=org,
-            repo=repo,
-            proof_id=incident.get("proof_id") or proof_id,
-            at=incident.get("at"),
-        )
-    if not gate_payload.get("allow") and not gate_payload.get("drain_gate_allow", True):
-        return build_incident_descriptor(
-            kind=INCIDENT_FAILED_DRAIN,
-            reasons=reasons or ["restart apply denied"],
-            correlation_id=correlation_id,
-            requesting_session_id=requesting_session_id,
-            restart_class=restart_class,
-            remote=remote,
-            org=org,
-            repo=repo,
-            proof_id=proof_id if isinstance(proof_id, str) else None,
-        )
-    return None

skills/llm-project-workflow/SKILL.md

@@ -204,6 +204,28 @@ proposed command before running it; `gitea_audit_runtime_recovery_contamination`
 to inspect or (reconciler-only) clear the marker. Full contrast in
 `docs/mcp-namespace-eof-recovery.md`.
 
+## Connected is not attached (#708)
+
+A host/CLI MCP inventory showing **Connected** is not proof the tools are usable.
+The active session can expose **none** of a Connected server's tool namespaces —
+a *session attachment* failure, distinct from config drift (#672),
+transport-closed (#584), and resolver EOF (#685).
+
+Required preflight proof is **live tool visibility plus `gitea_whoami` on the role
+namespace**, never host Connected status alone. Call
+`gitea_assess_mcp_namespace_attachment` with the Connected set and the namespaces
+actually attached to the session; it returns the typed condition
+**mcp_connected_namespaces_missing** with per-namespace connected-vs-attached proof,
+and records the verdict so review and merge fail closed while a required namespace
+is unattached.
+
+Only sanctioned recovery: the client attach/reconnect path
+(`gitea_request_mcp_reconnect`), then full preflight
+(`gitea_whoami` → `gitea_resolve_task_capability` → task). Never recover by direct
+module import, CLI/raw API mutation, profile hopping, session-state overrides,
+process kills, or `.env`/mtime edits. A final report must not claim a healthy
+session without attachment proof.
+
 ## Shell Spawn Hard-Stop Rule
 
 `exit_code: -1` with empty stdout/stderr means the shell failed to spawn — not a

tests/test_issue_708_attachment_wiring.py

@@ -0,0 +1,269 @@
+"""Regression tests for Issue #708 wiring: detection must reach a gate, not just exist.
+
+The prior #708 slice added a pure decision function with no call site, so a session
+whose namespaces were Connected-but-unattached still passed every mutation gate.
+These tests pin the parts that make the detection load-bearing:
+
+* the typed condition is distinct from #672 / #584 / #685,
+* the session store records a per-namespace attachment verdict,
+* review/merge mutations fail closed while a required namespace is unattached,
+* recovery is reconnect-only and never suggests an unsafe fallback,
+* startup ordering races and discovery-cache telemetry are reported,
+* a healthy final report cannot be produced without attachment proof.
+"""
+
+import mcp_namespace_health
+
+
+REQUIRED = ["gitea-author", "gitea-reviewer", "gitea-merger", "gitea-tools"]
+
+
+def _connected_but_unattached():
+    """The #708 signature: host says Connected, session tool surface is empty."""
+    return mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=[],
+        required_namespaces=REQUIRED,
+    )
+
+
+# --- AC1: distinct typed detection -----------------------------------------
+
+
+def test_connected_with_empty_session_tool_list_is_typed_distinctly():
+    res = _connected_but_unattached()
+    assert res["attachment_healthy"] is False
+    assert res["discovery_status"] == "connected_but_namespaces_missing"
+    assert res["error_type"] == "mcp_connected_namespaces_missing"
+    assert sorted(res["missing_namespaces"]) == sorted(REQUIRED)
+    # Not misclassified as config drift (#672), transport-closed (#584), or EOF (#685).
+    assert res["error_type"] not in {
+        "mcp_config_drift",
+        "transport_closed",
+        "mcp_client_eof",
+    }
+
+
+def test_proof_carries_connected_and_attached_per_namespace():
+    res = _connected_but_unattached()
+    proof = res["proof_of_connected_vs_attached"]
+    for ns in REQUIRED:
+        assert proof[ns] == {"connected": True, "attached": False}
+
+
+# --- AC2: recovery is auto-attach or reconnect-only -------------------------
+
+
+def test_exact_next_action_is_reconnect_only():
+    res = _connected_but_unattached()
+    assert res["reconnect_required"] is True
+    action = res["exact_next_action"]
+    assert "Reconnect the IDE/client MCP session" in action
+    for forbidden in ("pkill", "chmod", "curl", ".env", "sys.path"):
+        assert forbidden not in action
+
+
+def test_sanctioned_recovery_tool_is_named():
+    res = _connected_but_unattached()
+    assert res["sanctioned_recovery_tool"] == "gitea_request_mcp_reconnect"
+    assert "gitea_request_mcp_reconnect" in " ".join(res["remediation"])
+
+
+def test_successful_auto_attach_reports_recovered_without_operator():
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=REQUIRED,
+        required_namespaces=REQUIRED,
+        auto_attach_attempted=True,
+        auto_attach_succeeded=True,
+    )
+    assert res["attachment_healthy"] is True
+    assert res["auto_recovered"] is True
+    assert res["reconnect_required"] is False
+
+
+def test_failed_auto_attach_still_requires_reconnect():
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=[],
+        required_namespaces=REQUIRED,
+        auto_attach_attempted=True,
+        auto_attach_succeeded=False,
+    )
+    assert res["auto_recovered"] is False
+    assert res["reconnect_required"] is True
+    assert any("did not succeed" in r for r in res["reasons"])
+
+
+def test_reconnect_rediscovery_clears_the_condition():
+    """Attach state after a reconnect is healthy without any other change."""
+    before = _connected_but_unattached()
+    after = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=REQUIRED,
+        required_namespaces=REQUIRED,
+        discovery_cache_hit=False,
+        discovery_cache_age_seconds=0.0,
+    )
+    assert before["attachment_healthy"] is False
+    assert after["attachment_healthy"] is True
+    assert after["discovery_status"] == "namespaces_attached"
+    assert after["missing_namespaces"] == []
+
+
+# --- AC4: startup ordering across multiple role servers ---------------------
+
+
+def test_multi_role_startup_ordering_race_is_reported():
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=["gitea-author"],
+        required_namespaces=REQUIRED,
+        session_tool_snapshot_at=1000.0,
+        namespace_connected_at={
+            "gitea-author": 990.0,
+            "gitea-reviewer": 1005.0,
+            "gitea-merger": 1007.0,
+        },
+    )
+    assert res["startup_ordering_race"] is True
+    assert res["late_attaching_namespaces"] == ["gitea-merger", "gitea-reviewer"]
+    assert res["telemetry"]["startup_ordering_race"] is True
+
+
+def test_no_ordering_race_when_snapshot_follows_connect():
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=REQUIRED,
+        required_namespaces=REQUIRED,
+        session_tool_snapshot_at=2000.0,
+        namespace_connected_at={ns: 1000.0 for ns in REQUIRED},
+    )
+    assert res["startup_ordering_race"] is False
+    assert res["late_attaching_namespaces"] == []
+
+
+# --- AC5: telemetry ---------------------------------------------------------
+
+
+def test_telemetry_reports_cache_and_recovery_signals():
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=["gitea-author"],
+        required_namespaces=REQUIRED,
+        discovery_cache_hit=True,
+        discovery_cache_age_seconds=42.5,
+    )
+    tel = res["telemetry"]
+    assert tel["connected_count"] == 4
+    assert tel["attached_count"] == 1
+    assert tel["missing_count"] == 3
+    assert tel["discovery_cache_hit"] is True
+    assert tel["discovery_cache_age_seconds"] == 42.5
+    assert tel["reconnect_required"] is True
+    assert tel["error_type"] == "mcp_connected_namespaces_missing"
+
+
+def test_telemetry_leaks_no_secrets():
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=[],
+        required_namespaces=REQUIRED,
+    )
+    blob = repr(res["telemetry"]).lower()
+    for leak in ("token", "authorization", "password", "secret", "/users/", "http"):
+        assert leak not in blob
+
+
+# --- AC2/AC6: fail-closed mutation gate -------------------------------------
+
+
+def _session_store_from(assessment):
+    """Mirror the server-side recorder without importing the MCP server module."""
+    store = {}
+    missing = set(assessment["missing_namespaces"])
+    for ns, state in assessment["proof_of_connected_vs_attached"].items():
+        attached = bool(state["attached"])
+        store[ns] = {
+            "namespace": ns,
+            "connected": bool(state["connected"]),
+            "attached": attached,
+            "attachment_healthy": attached and ns not in missing,
+            "error_type": None if attached else assessment["error_type"],
+        }
+    return store
+
+
+def test_review_and_merge_fail_closed_while_unattached():
+    store = _session_store_from(_connected_but_unattached())
+    for task in ("review_pr", "submit_review", "merge_pr", "create_pr", "work_issue"):
+        reasons = mcp_namespace_health.attachment_gate_from_session(task, store)
+        assert reasons, f"{task} must fail closed while its namespace is unattached"
+        assert "fail closed, #708" in reasons[0]
+
+
+def test_gate_offers_only_sanctioned_recovery():
+    store = _session_store_from(_connected_but_unattached())
+    reasons = mcp_namespace_health.attachment_gate_from_session("merge_pr", store)
+    joined = " ".join(reasons)
+    assert "reconnect" in joined.lower()
+    assert "Workflow Safety Hard Stop (#708)" in joined
+    # Unsafe fallbacks appear only inside the prohibition, never as advice.
+    assert "NEVER use" in joined
+
+
+def test_gate_passes_once_namespaces_are_attached():
+    healthy = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=REQUIRED,
+        required_namespaces=REQUIRED,
+    )
+    store = _session_store_from(healthy)
+    for task in ("review_pr", "submit_review", "merge_pr", "create_pr", "work_issue"):
+        assert mcp_namespace_health.attachment_gate_from_session(task, store) == []
+
+
+def test_unassessed_session_does_not_gate():
+    """No recorded assessment must not fabricate a block (matches #543 semantics)."""
+    assert mcp_namespace_health.attachment_gate_from_session("merge_pr", {}) == []
+    assert mcp_namespace_health.attachment_gate_from_session("merge_pr", None) == []
+
+
+def test_unmapped_task_is_not_gated():
+    store = _session_store_from(_connected_but_unattached())
+    assert mcp_namespace_health.attachment_gate_from_session("gitea_read", store) == []
+
+
+def test_partial_attachment_gates_only_the_affected_role():
+    """Author attached, reviewer not: author work proceeds, review fails closed."""
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=["gitea-author", "gitea-tools"],
+        required_namespaces=REQUIRED,
+    )
+    store = _session_store_from(res)
+    assert mcp_namespace_health.attachment_gate_from_session("work_issue", store) == []
+    assert mcp_namespace_health.attachment_gate_from_session("review_pr", store)
+    assert mcp_namespace_health.attachment_gate_from_session("merge_pr", store)
+
+
+# --- AC4: no false healthy report without attachment proof ------------------
+
+
+def test_no_false_healthy_without_attachment_proof():
+    """Connected alone never yields a healthy verdict."""
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=REQUIRED,
+        attached_session_namespaces=None,
+        required_namespaces=REQUIRED,
+    )
+    assert res["success"] is False
+    assert res["attachment_healthy"] is False
+    assert res["telemetry"]["attached_count"] == 0
+
+
+def test_attachment_gate_maps_each_role_namespace():
+    assert mcp_namespace_health.required_namespace_for_attachment("review_pr") == "gitea-reviewer"
+    assert mcp_namespace_health.required_namespace_for_attachment("merge_pr") == "gitea-merger"
+    assert mcp_namespace_health.required_namespace_for_attachment("create_pr") == "gitea-author"
+    assert mcp_namespace_health.required_namespace_for_attachment("nope") is None

tests/test_issue_708_mcp_namespace_attachment.py

@@ -0,0 +1,77 @@
+"""Unit regression tests for Issue #708: Connected-but-namespaces-missing detection and attachment safety."""
+
+import mcp_namespace_health
+
+
+def test_assess_connected_namespace_attachment_success():
+    # required_namespaces is declared explicitly: these three are the namespaces this case
+    # is about. Relying on the default (which also requires gitea-tools) would ask for a
+    # healthy verdict covering a required namespace that was never connected — exactly the
+    # false-healthy classification these tests now forbid.
+    connected = ["gitea-author", "gitea-reviewer", "gitea-merger"]
+    attached = ["gitea-author", "gitea-reviewer", "gitea-merger"]
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=connected,
+        attached_session_namespaces=attached,
+        required_namespaces=connected,
+    )
+    assert res["success"] is True
+    assert res["attachment_healthy"] is True
+    assert res["discovery_status"] == "namespaces_attached"
+    assert res["error_type"] is None
+    assert res["missing_namespaces"] == []
+    assert res["exact_next_action"] == "None; session tool namespaces attached."
+
+
+def test_assess_connected_namespace_attachment_missing():
+    # Every required namespace here *is* connected, so the only condition present is the
+    # #708 one: Connected at the host, absent from the session tool surface.
+    connected = ["gitea-author", "gitea-reviewer", "gitea-merger"]
+    attached = ["gitea-author"]
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=connected,
+        attached_session_namespaces=attached,
+        required_namespaces=connected,
+    )
+    assert res["success"] is False
+    assert res["attachment_healthy"] is False
+    assert res["discovery_status"] == "connected_but_namespaces_missing"
+    assert res["error_type"] == "mcp_connected_namespaces_missing"
+    assert "gitea-reviewer" in res["missing_namespaces"]
+    assert "gitea-merger" in res["missing_namespaces"]
+    assert "Reconnect the IDE/client MCP session" in res["exact_next_action"]
+
+
+def test_assess_connected_namespace_attachment_disconnected():
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=[],
+        attached_session_namespaces=[],
+    )
+    assert res["success"] is False
+    assert res["attachment_healthy"] is False
+    assert res["discovery_status"] == "disconnected"
+
+
+def test_proof_of_connected_vs_attached_mapping():
+    connected = ["gitea-author", "gitea-reviewer"]
+    attached = ["gitea-author"]
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=connected,
+        attached_session_namespaces=attached,
+    )
+    proof = res["proof_of_connected_vs_attached"]
+    assert proof["gitea-author"] == {"connected": True, "attached": True}
+    assert proof["gitea-reviewer"] == {"connected": True, "attached": False}
+
+
+def test_unsafe_fallback_policy_enforcement():
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=["gitea-author"],
+        attached_session_namespaces=[],
+    )
+    policy = res["unsafe_fallback_policy"]
+    assert "Workflow Safety Hard Stop (#708)" in policy
+    assert "direct imports" in policy
+    assert "API mutations" in policy
+    assert "profile hopping" in policy
+    assert "session-state overrides" in policy

tests/test_issue_708_not_connected_classification.py

@@ -0,0 +1,283 @@
+"""Regression tests for Issue #708 B2: not-connected is not Connected-but-unattached.
+
+The first #708 slice counted a namespace as ``missing`` only when it appeared in
+``connected_servers``. A *required* namespace absent from that inventory was therefore
+never counted at all, so the session reported ``attachment_healthy: true`` with
+``error_type: None`` while holding no attachment proof for it — and the gate text told the
+operator "the host reports Connected" about a service nothing had reported Connected.
+
+These tests pin the corrected distinction:
+
+* required and not connected never yields a healthy verdict,
+* it is typed ``mcp_required_namespaces_not_connected``, never the #708 condition,
+* ``mcp_connected_namespaces_missing`` stays reserved for genuinely Connected namespaces,
+* both categories still fail review and merge closed, with their own reason,
+* per-namespace ``connected``/``attached`` evidence is reported accurately,
+* one session's evidence cannot clear another session's block.
+"""
+
+import mcp_namespace_health
+
+
+ROLES = ["gitea-author", "gitea-reviewer", "gitea-merger", "gitea-tools"]
+
+NOT_CONNECTED = mcp_namespace_health.ERROR_REQUIRED_NAMESPACES_NOT_CONNECTED
+CONNECTED_MISSING = mcp_namespace_health.ERROR_CONNECTED_NAMESPACES_MISSING
+
+
+def _assess(connected, attached, required):
+    return mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=connected,
+        attached_session_namespaces=attached,
+        required_namespaces=required,
+    )
+
+
+def _store(assessment):
+    """The recorder contract: per-namespace verdicts feed the gate."""
+    return dict(assessment["namespace_conditions"])
+
+
+# --- the four evidence combinations ----------------------------------------
+
+
+def test_connected_and_attached_is_healthy():
+    res = _assess(ROLES, ROLES, ROLES)
+    assert res["attachment_healthy"] is True
+    assert res["error_type"] is None
+    assert res["missing_namespaces"] == []
+    assert res["not_connected_namespaces"] == []
+    assert res["discovery_status"] == "namespaces_attached"
+
+
+def test_connected_but_unattached_keeps_the_708_condition():
+    res = _assess(ROLES, ["gitea-author"], ROLES)
+    assert res["attachment_healthy"] is False
+    assert res["error_type"] == CONNECTED_MISSING
+    assert res["not_connected_namespaces"] == []
+    assert sorted(res["missing_namespaces"]) == [
+        "gitea-merger",
+        "gitea-reviewer",
+        "gitea-tools",
+    ]
+    assert res["discovery_status"] == "connected_but_namespaces_missing"
+
+
+def test_required_but_not_connected_is_never_healthy():
+    """The reviewer's exact reproduction from review 637."""
+    res = _assess(
+        ["gitea-reviewer"], ["gitea-reviewer"], ["gitea-reviewer", "gitea-merger"]
+    )
+    assert res["attachment_healthy"] is False
+    assert res["success"] is False
+    assert res["error_type"] is not None
+    assert res["telemetry"]["not_connected_count"] == 1
+
+
+def test_required_but_not_connected_is_typed_distinctly():
+    res = _assess(
+        ["gitea-reviewer"], ["gitea-reviewer"], ["gitea-reviewer", "gitea-merger"]
+    )
+    assert res["error_type"] == NOT_CONNECTED
+    assert res["discovery_status"] == "required_namespaces_not_connected"
+    assert res["not_connected_namespaces"] == ["gitea-merger"]
+    # Not collapsed into the #708 condition, nor into config drift (#672) or
+    # transport-closed (#584).
+    assert CONNECTED_MISSING not in res["error_types"]
+    assert res["missing_namespaces"] == []
+    assert res["error_type"] not in {"mcp_config_drift", "transport_closed"}
+
+
+def test_not_connected_reason_makes_no_connected_claim():
+    res = _assess(
+        ["gitea-reviewer"], ["gitea-reviewer"], ["gitea-reviewer", "gitea-merger"]
+    )
+    about_merger = [r for r in res["reasons"] if "gitea-merger" in r]
+    assert about_merger, "the not-connected namespace must be named in the reasons"
+    for reason in about_merger:
+        assert "report Connected at host/CLI layer" not in reason
+    assert "gitea-merger" in res["exact_next_action"]
+
+
+def test_neither_connected_nor_attached_reports_disconnected():
+    res = _assess([], [], ROLES)
+    assert res["attachment_healthy"] is False
+    assert res["discovery_status"] == "disconnected"
+    assert res["error_type"] == NOT_CONNECTED
+    assert sorted(res["not_connected_namespaces"]) == sorted(ROLES)
+    assert res["missing_namespaces"] == []
+
+
+# --- mixed required namespaces ---------------------------------------------
+
+
+def test_mixed_connected_attached_and_not_connected():
+    res = _assess(
+        ["gitea-author"], ["gitea-author"], ["gitea-author", "gitea-merger"]
+    )
+    assert res["attachment_healthy"] is False
+    assert res["not_connected_namespaces"] == ["gitea-merger"]
+    assert res["missing_namespaces"] == []
+    conditions = res["namespace_conditions"]
+    assert conditions["gitea-author"]["attachment_healthy"] is True
+    assert conditions["gitea-author"]["condition"] is None
+    assert conditions["gitea-merger"]["attachment_healthy"] is False
+    assert conditions["gitea-merger"]["condition"] == NOT_CONNECTED
+
+
+def test_both_conditions_present_are_both_reported():
+    """One namespace Connected-but-unattached, another never connected."""
+    res = _assess(
+        ["gitea-author", "gitea-reviewer"],
+        ["gitea-author"],
+        ["gitea-author", "gitea-reviewer", "gitea-merger"],
+    )
+    assert res["missing_namespaces"] == ["gitea-reviewer"]
+    assert res["not_connected_namespaces"] == ["gitea-merger"]
+    # Neither condition is hidden by the other; error_type names the primary one.
+    assert sorted(res["error_types"]) == sorted([NOT_CONNECTED, CONNECTED_MISSING])
+    assert res["error_type"] == NOT_CONNECTED
+
+
+# --- unknown, partial, malformed, contradictory evidence --------------------
+
+
+def test_unknown_attachment_evidence_is_not_healthy():
+    """No session tool surface reported at all is unproven, not proven good."""
+    res = _assess(ROLES, None, ROLES)
+    assert res["attachment_healthy"] is False
+    assert res["telemetry"]["attached_count"] == 0
+    assert res["error_type"] == CONNECTED_MISSING
+
+
+def test_partial_evidence_gates_only_the_unproven_roles():
+    res = _assess(ROLES, ["gitea-author", "gitea-tools"], ROLES)
+    store = _store(res)
+    assert mcp_namespace_health.attachment_gate_from_session("work_issue", store) == []
+    assert mcp_namespace_health.attachment_gate_from_session("review_pr", store)
+    assert mcp_namespace_health.attachment_gate_from_session("merge_pr", store)
+
+
+def test_malformed_namespace_entries_are_discarded_not_trusted():
+    """Blank and whitespace-only names must not become namespaces or proof."""
+    res = mcp_namespace_health.assess_connected_namespace_attachment(
+        connected_servers=["gitea-author", "", "   "],
+        attached_session_namespaces=["gitea-author", ""],
+        required_namespaces=["gitea-author", "  "],
+    )
+    assert "" not in res["proof_of_connected_vs_attached"]
+    assert "   " not in res["proof_of_connected_vs_attached"]
+    assert res["attachment_healthy"] is True
+    assert res["telemetry"]["required_count"] == 1
+
+
+def test_contradictory_attached_without_connected_fails_closed():
+    """Attached in the session yet absent from the connected inventory."""
+    res = _assess(["gitea-author"], ["gitea-author", "gitea-merger"], ROLES)
+    assert res["attachment_healthy"] is False
+    assert "gitea-merger" in res["contradictory_namespaces"]
+    assert "gitea-merger" in res["not_connected_namespaces"]
+    assert res["namespace_conditions"]["gitea-merger"]["contradictory_evidence"] is True
+    assert res["namespace_conditions"]["gitea-merger"]["attachment_healthy"] is False
+    assert any("contradictory evidence" in r for r in res["reasons"])
+    assert res["telemetry"]["contradictory_count"] >= 1
+
+
+def test_duplicate_required_entries_are_counted_once():
+    res = _assess(["gitea-author"], ["gitea-author"], ["gitea-author", "gitea-author"])
+    assert res["telemetry"]["required_count"] == 1
+    assert res["attachment_healthy"] is True
+
+
+# --- review and merge behaviour for both failure categories -----------------
+
+
+def test_merge_fails_closed_when_required_namespace_never_connected():
+    store = _store(_assess(["gitea-author"], ["gitea-author"], ROLES))
+    reasons = mcp_namespace_health.attachment_gate_from_session("merge_pr", store)
+    assert reasons
+    assert NOT_CONNECTED in reasons[0]
+    assert "fail closed, #708" in reasons[0]
+
+
+def test_review_fails_closed_when_required_namespace_never_connected():
+    store = _store(_assess(["gitea-author"], ["gitea-author"], ROLES))
+    reasons = mcp_namespace_health.attachment_gate_from_session("review_pr", store)
+    assert reasons
+    assert NOT_CONNECTED in reasons[0]
+    assert "fail closed, #708" in reasons[0]
+
+
+def test_not_connected_block_never_claims_the_host_reports_connected():
+    store = _store(_assess(["gitea-author"], ["gitea-author"], ROLES))
+    reasons = mcp_namespace_health.attachment_gate_from_session("merge_pr", store)
+    assert "the host reports Connected" not in reasons[0]
+    assert "absent from the connected-service inventory" in reasons[0]
+
+
+def test_connected_but_unattached_block_still_says_connected():
+    store = _store(_assess(ROLES, ["gitea-author"], ROLES))
+    reasons = mcp_namespace_health.attachment_gate_from_session("merge_pr", store)
+    assert CONNECTED_MISSING in reasons[0]
+    assert "the host reports Connected" in reasons[0]
+
+
+def test_both_categories_offer_only_the_sanctioned_recovery():
+    for store in (
+        _store(_assess(ROLES, [], ROLES)),
+        _store(_assess(["gitea-author"], ["gitea-author"], ROLES)),
+    ):
+        reasons = mcp_namespace_health.attachment_gate_from_session("merge_pr", store)
+        joined = " ".join(reasons)
+        assert "reconnect" in joined.lower()
+        assert "Workflow Safety Hard Stop (#708)" in joined
+        for forbidden in ("pkill", "chmod", "curl ", ".env", "sys.path"):
+            assert forbidden not in reasons[0]
+
+
+def test_entry_without_connected_evidence_blocks_without_asserting_either():
+    """A legacy/partial store entry must fail closed and claim nothing it cannot prove."""
+    store = {"gitea-merger": {"namespace": "gitea-merger", "attached": False}}
+    reasons = mcp_namespace_health.attachment_gate_from_session("merge_pr", store)
+    assert reasons
+    assert "no connected-status evidence" in reasons[0]
+    assert "the host reports Connected" not in reasons[0]
+    assert "fail closed, #708" in reasons[0]
+
+
+# --- session isolation ------------------------------------------------------
+
+
+def test_one_session_evidence_does_not_clear_another_session_block():
+    """Attachment evidence is per-session state; it must not travel between sessions."""
+    blocked_session = _store(_assess(["gitea-author"], ["gitea-author"], ROLES))
+    healthy_session = _store(_assess(ROLES, ROLES, ROLES))
+
+    assert (
+        mcp_namespace_health.attachment_gate_from_session("merge_pr", healthy_session)
+        == []
+    )
+    # The healthy session's verdict is not consulted for the blocked session.
+    assert mcp_namespace_health.attachment_gate_from_session("merge_pr", blocked_session)
+    # And the blocked session's store is unchanged by the healthy one existing.
+    assert blocked_session["gitea-merger"]["attachment_healthy"] is False
+
+
+def test_gate_reads_only_the_store_it_is_given():
+    healthy_session = _store(_assess(ROLES, ROLES, ROLES))
+    assert mcp_namespace_health.attachment_gate_from_session("merge_pr", {}) == []
+    assert mcp_namespace_health.attachment_gate_from_session("merge_pr", None) == []
+    assert (
+        mcp_namespace_health.attachment_gate_from_session("merge_pr", healthy_session)
+        == []
+    )
+
+
+# --- telemetry stays secret-free -------------------------------------------
+
+
+def test_not_connected_telemetry_leaks_no_secrets():
+    res = _assess(["gitea-author"], ["gitea-author"], ROLES)
+    blob = repr(res["telemetry"]).lower()
+    for leak in ("token", "authorization", "password", "secret", "/users/", "http"):
+        assert leak not in blob

tests/test_issue_931_transport_bind_seam.py

@@ -0,0 +1,924 @@
+"""Transport-neutral MCP bind seam (#931).
+
+These tests drive the *real* bind boundary — ``mark_sanctioned_daemon`` followed
+by ``bind_native_mcp_transport`` from a canonical entrypoint path, with the
+pytest allowance switched off — rather than mocking the new accessor. The
+distinction matters here for the same reason it mattered in #941: a suite that
+only exercises the helper in isolation cannot observe a seam that the live path
+never reaches.
+
+Covered:
+
+1.  no configured transport defaults to the local transport
+2.  explicit local transport binds
+3.  the sanctioned remote identifier binds through the seam
+4.  an unregistered identifier is rejected at bind time
+5.  an invalid bind prevents the server reaching tool service
+6.  the unbound state fails closed where a bind is required
+7.  every transport-aware guard reads the same authoritative value
+8.  client-controlled input cannot alter the bound transport
+9.  the durable decision-lock record carries the selected transport
+10. existing stdio behaviour is unchanged
+11. repeated / conflicting bind attempts follow one fail-closed contract
+12. capability, role, repository and provenance protections do not regress
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+import mcp_daemon_guard
+import mcp_session_state
+import mcp_transport_config
+import irrecoverable_provenance
+
+
+class _ProductionBind:
+    """Context manager that reaches the real production bind path.
+
+    Patches only the two things a unit test cannot otherwise satisfy: the
+    resolved canonical entrypoint frame, and the pytest allowance that would
+    short-circuit ``mark_sanctioned_daemon``. Everything downstream of those —
+    validation, pinning, the rebind contract — runs unmodified.
+    """
+
+    def __init__(self, env: dict[str, str] | None = None):
+        self._env = env or {}
+        self._stack: list = []
+
+    def __enter__(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        canonical = str((REPO_ROOT / "mcp_server.py").resolve())
+        self._stack = [
+            patch.object(
+                mcp_daemon_guard,
+                "_caller_official_entrypoint_path",
+                side_effect=lambda: canonical,
+            ),
+            patch.object(mcp_daemon_guard, "is_pytest_runtime", return_value=False),
+            patch.dict(os.environ, self._env),
+        ]
+        for ctx in self._stack:
+            ctx.__enter__()
+        # Start from a clean configuration unless the test set one.
+        if mcp_transport_config.TRANSPORT_ENV not in self._env:
+            os.environ.pop(mcp_transport_config.TRANSPORT_ENV, None)
+        mcp_daemon_guard.mark_sanctioned_daemon()
+        return mcp_daemon_guard
+
+    def __exit__(self, *exc):
+        for ctx in reversed(self._stack):
+            ctx.__exit__(*exc)
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        return False
+
+
+class TestPermittedSetIsSingleSourceOfTruth(unittest.TestCase):
+    """AC3: identifiers are enumerated once, in the seam."""
+
+    def test_guard_allowlist_is_the_seam_allowlist(self):
+        self.assertIs(
+            mcp_daemon_guard._PRODUCTION_TRANSPORTS,
+            mcp_transport_config.SUPPORTED_TRANSPORTS,
+        )
+
+    def test_default_is_a_member_of_the_permitted_set(self):
+        self.assertIn(
+            mcp_transport_config.DEFAULT_TRANSPORT,
+            mcp_transport_config.SUPPORTED_TRANSPORTS,
+        )
+
+    def test_remote_identifier_is_permitted_and_not_the_default(self):
+        self.assertIn(
+            mcp_transport_config.REMOTE_TRANSPORT,
+            mcp_transport_config.SUPPORTED_TRANSPORTS,
+        )
+        self.assertNotEqual(
+            mcp_transport_config.REMOTE_TRANSPORT,
+            mcp_transport_config.DEFAULT_TRANSPORT,
+        )
+        self.assertTrue(
+            mcp_transport_config.is_remote_transport(
+                mcp_transport_config.REMOTE_TRANSPORT
+            )
+        )
+
+    def test_no_default_transport_literal_outside_the_seam(self):
+        """AC3: no production module reads the literal outside the seam.
+
+        Review 635 flagged that a fixed five-module list cannot catch a *new*
+        module reintroducing the literal. This globs every production module in
+        the repository root instead, so the guarantee holds for code that does
+        not exist yet.
+        """
+        default = mcp_transport_config.DEFAULT_TRANSPORT
+        needles = (f'"{default}"', f"'{default}'")
+        seam = Path(mcp_transport_config.__file__).name
+        scanned: list[str] = []
+        offenders: list[str] = []
+        for path in sorted(REPO_ROOT.glob("*.py")):
+            if path.name == seam:
+                continue  # the seam is the one place the literal may live
+            scanned.append(path.name)
+            for lineno, line in enumerate(
+                path.read_text(encoding="utf-8").splitlines(), start=1
+            ):
+                code = line.split("#", 1)[0]
+                if any(needle in code for needle in needles):
+                    offenders.append(f"{path.name}:{lineno}: {line.strip()}")
+        # Guard the guard: a glob that silently matched nothing would pass.
+        self.assertGreater(len(scanned), 20, "production glob matched too little")
+        self.assertIn("mcp_daemon_guard.py", scanned)
+        self.assertIn("gitea_mcp_server.py", scanned)
+        self.assertEqual(offenders, [], "\n".join(offenders))
+
+
+class TestConfiguredTransportResolution(unittest.TestCase):
+    """AC1: configuration supplies the identifier; unset still yields the default."""
+
+    def test_unset_yields_default(self):
+        res = mcp_transport_config.resolve_configured_transport(env={})
+        self.assertEqual(res["transport"], mcp_transport_config.DEFAULT_TRANSPORT)
+        self.assertFalse(res["configured"])
+        self.assertEqual(res["source"], mcp_transport_config.SOURCE_DEFAULT)
+        self.assertTrue(res["supported"])
+        self.assertEqual(res["reasons"], [])
+
+    def test_blank_and_whitespace_are_treated_as_unset(self):
+        for raw in ("", "   ", "\t\n"):
+            res = mcp_transport_config.resolve_configured_transport(
+                env={mcp_transport_config.TRANSPORT_ENV: raw}
+            )
+            self.assertEqual(res["transport"], mcp_transport_config.DEFAULT_TRANSPORT)
+            self.assertFalse(res["configured"])
+
+    def test_explicit_default_is_reported_as_configured(self):
+        res = mcp_transport_config.resolve_configured_transport(
+            env={
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.DEFAULT_TRANSPORT
+                )
+            }
+        )
+        self.assertEqual(res["transport"], mcp_transport_config.DEFAULT_TRANSPORT)
+        self.assertTrue(res["configured"])
+        self.assertEqual(res["source"], mcp_transport_config.SOURCE_CONFIGURED)
+
+    def test_remote_identifier_resolves_and_is_supported(self):
+        res = mcp_transport_config.resolve_configured_transport(
+            env={
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        )
+        self.assertEqual(res["transport"], mcp_transport_config.REMOTE_TRANSPORT)
+        self.assertTrue(res["supported"])
+
+    def test_case_and_padding_are_normalized(self):
+        padded = f"  {mcp_transport_config.REMOTE_TRANSPORT.upper()}  "
+        res = mcp_transport_config.resolve_configured_transport(
+            env={mcp_transport_config.TRANSPORT_ENV: padded}
+        )
+        self.assertEqual(res["transport"], mcp_transport_config.REMOTE_TRANSPORT)
+        self.assertTrue(res["supported"])
+
+    def test_unregistered_identifier_is_not_silently_defaulted(self):
+        res = mcp_transport_config.resolve_configured_transport(
+            env={mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+        )
+        self.assertFalse(res["supported"])
+        self.assertEqual(res["transport"], "carrier-pigeon")
+        self.assertNotEqual(res["transport"], mcp_transport_config.DEFAULT_TRANSPORT)
+        self.assertTrue(res["reasons"])
+
+    def test_superseded_sse_transport_is_not_registered(self):
+        """A real MCP transport that this deployment does not sanction."""
+        self.assertFalse(mcp_transport_config.is_supported_transport("sse"))
+        res = mcp_transport_config.resolve_configured_transport(
+            env={mcp_transport_config.TRANSPORT_ENV: "sse"}
+        )
+        self.assertFalse(res["supported"])
+
+    def test_require_configured_transport_raises_on_unregistered(self):
+        with self.assertRaises(mcp_transport_config.TransportConfigurationError):
+            mcp_transport_config.require_configured_transport(
+                env={mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+            )
+
+    def test_non_string_configuration_never_matches_permitted_set(self):
+        for value in (object(), 1, None, True, ["stdio"], {"t": "stdio"}):
+            self.assertEqual(mcp_transport_config.normalize_transport(value), "")
+            self.assertFalse(mcp_transport_config.is_supported_transport(value))
+
+
+class TestBindSeam(unittest.TestCase):
+    """AC1/AC2: the live bind path resolves, validates, and pins."""
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    def test_1_no_configured_transport_binds_default(self):
+        with _ProductionBind() as guard:
+            status = guard.bind_native_mcp_transport()
+            self.assertEqual(
+                status["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertTrue(status["production_native_mcp_transport"])
+
+    def test_2_explicit_default_transport_binds(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.DEFAULT_TRANSPORT
+                )
+            }
+        ) as guard:
+            status = guard.bind_native_mcp_transport()
+            self.assertEqual(
+                status["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertTrue(guard.is_production_native_mcp_transport())
+
+    def test_2b_explicit_argument_still_binds(self):
+        """The pre-#931 call form keeps working for launchers and tests."""
+        with _ProductionBind() as guard:
+            status = guard.bind_native_mcp_transport(
+                transport=mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertEqual(
+                status["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    def test_3_sanctioned_remote_identifier_binds_through_the_seam(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            status = guard.bind_native_mcp_transport()
+            self.assertEqual(
+                status["transport"], mcp_transport_config.REMOTE_TRANSPORT
+            )
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.REMOTE_TRANSPORT
+            )
+            # The remote identifier is trusted exactly like the local one; the
+            # listener that serves it is #938 and is not implemented here.
+            self.assertTrue(guard.is_native_mcp_transport())
+            self.assertTrue(guard.is_production_native_mcp_transport())
+            guard.assert_production_mutation_runtime("remote-bind")
+
+    def test_4_unregistered_identifier_rejected_at_bind_time(self):
+        with _ProductionBind(
+            {mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+        ) as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.bind_native_mcp_transport()
+            self.assertIn("carrier-pigeon", str(ctx.exception))
+            self.assertIn("#931", str(ctx.exception))
+            # Nothing was bound, so nothing may dispatch.
+            self.assertIsNone(guard.bound_transport())
+            self.assertFalse(guard.is_native_mcp_transport())
+
+    def test_4b_unregistered_explicit_argument_rejected(self):
+        with _ProductionBind() as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.bind_native_mcp_transport(transport="carrier-pigeon")
+            self.assertIsNone(guard.bound_transport())
+
+    def test_4c_superseded_sse_rejected_at_bind_time(self):
+        with _ProductionBind({mcp_transport_config.TRANSPORT_ENV: "sse"}) as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.bind_native_mcp_transport()
+            self.assertIsNone(guard.bound_transport())
+
+    def test_5_invalid_bind_prevents_tool_service(self):
+        """A failed bind must stop the server before it serves tools."""
+        with _ProductionBind(
+            {mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+        ) as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.bind_native_mcp_transport()
+            # This is the exact expression the entrypoint passes to mcp.run.
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.assert_transport_bound("tool service")
+            self.assertIn("No MCP transport is bound", str(ctx.exception))
+
+    def test_6_unbound_state_fails_closed(self):
+        """Entrypoint claimed but never bound — the offline-import shape."""
+        with _ProductionBind() as guard:
+            self.assertIsNone(guard.bound_transport())
+            self.assertFalse(guard.is_native_mcp_transport())
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.assert_transport_bound("tool service")
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.assert_sanctioned_mutation_runtime("gitea_mutation")
+
+    def test_6b_no_runtime_at_all_fails_closed(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        with patch.object(mcp_daemon_guard, "is_pytest_runtime", return_value=False):
+            self.assertIsNone(mcp_daemon_guard.bound_transport())
+            with self.assertRaises(mcp_daemon_guard.UnsanctionedRuntimeError):
+                mcp_daemon_guard.assert_transport_bound("tool service")
+
+
+class TestOneAuthoritativeValue(unittest.TestCase):
+    """AC: every transport-aware guard observes the same value."""
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    def test_7_all_guards_read_the_same_bound_value(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            expected = mcp_transport_config.REMOTE_TRANSPORT
+
+            self.assertEqual(guard.bound_transport(), expected)
+            self.assertEqual(guard.assert_transport_bound(), expected)
+            self.assertEqual(guard.native_runtime_status()["bound_transport"], expected)
+            self.assertEqual(guard.native_runtime_status()["transport"], expected)
+            self.assertEqual(
+                guard.mutation_provenance_fields()["bound_transport"], expected
+            )
+            self.assertEqual(
+                irrecoverable_provenance.assess_transport_for_auth_mint()[
+                    "bound_transport"
+                ],
+                expected,
+            )
+
+    def test_8_environment_change_after_bind_cannot_move_the_value(self):
+        """Client- or environment-shaped input must not alter a bound transport."""
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            # A stray launcher (or an attacker) rewrites config post-bind.
+            os.environ[mcp_transport_config.TRANSPORT_ENV] = (
+                mcp_transport_config.REMOTE_TRANSPORT
+            )
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertEqual(
+                guard.mutation_provenance_fields()["bound_transport"],
+                mcp_transport_config.DEFAULT_TRANSPORT,
+            )
+            os.environ[mcp_transport_config.TRANSPORT_ENV] = "carrier-pigeon"
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    def test_8b_bound_transport_takes_no_caller_argument(self):
+        """The accessor cannot be steered by a tool parameter."""
+        import inspect
+
+        self.assertEqual(
+            list(inspect.signature(mcp_daemon_guard.bound_transport).parameters), []
+        )
+
+    def test_11_rebinding_the_same_transport_is_idempotent(self):
+        with _ProductionBind() as guard:
+            first = guard.bind_native_mcp_transport()
+            second = guard.bind_native_mcp_transport()
+            self.assertEqual(first["transport"], second["transport"])
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    def test_11b_rebinding_a_different_transport_fails_closed(self):
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.bind_native_mcp_transport(
+                    transport=mcp_transport_config.REMOTE_TRANSPORT
+                )
+            self.assertIn("already bound", str(ctx.exception))
+            # The first value survives the attempt.
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    def test_11c_rebinding_an_unregistered_transport_fails_closed(self):
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.bind_native_mcp_transport(transport="carrier-pigeon")
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+
+class TestDurableRecordCarriesTransport(unittest.TestCase):
+    """AC4: the identifier reaches a durable decision-lock record."""
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    def _save_and_read_decision_lock(self, state_dir: str) -> dict:
+        mcp_session_state.save_state(
+            kind=mcp_session_state.KIND_DECISION_LOCK,
+            payload={"pr_number": 931, "action": "COMMENT"},
+            remote="prgs",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            profile_identity="prgs-author",
+            state_dir=state_dir,
+        )
+        loaded = mcp_session_state.load_state(
+            kind=mcp_session_state.KIND_DECISION_LOCK,
+            remote="prgs",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            profile_identity="prgs-author",
+            state_dir=state_dir,
+        )
+        self.assertIsNotNone(loaded)
+        return loaded
+
+    def test_9_decision_lock_records_the_bound_transport(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            mcp_daemon_guard.clear_native_runtime_for_tests()
+            mcp_daemon_guard.install_test_native_runtime()
+            record = self._save_and_read_decision_lock(tmp)
+            self.assertIn("bound_transport", record)
+            self.assertEqual(
+                record["bound_transport"], mcp_daemon_guard.bound_transport()
+            )
+
+    def test_9b_unbound_runtime_records_no_transport_identifier(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            mcp_daemon_guard.clear_native_runtime_for_tests()
+            record = self._save_and_read_decision_lock(tmp)
+            self.assertIn("bound_transport", record)
+            self.assertIsNone(record["bound_transport"])
+
+    def test_9c_provenance_fields_expose_the_identifier(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        fields = mcp_daemon_guard.mutation_provenance_fields()
+        self.assertIn("bound_transport", fields)
+        self.assertIsNone(fields["bound_transport"])
+
+
+class TestStdioBehaviourUnchanged(unittest.TestCase):
+    """AC6 / prompt items 10 and 12: no regression on the existing path."""
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    def test_10_trust_class_field_keeps_its_pre_931_values(self):
+        """``transport`` remains the trust class, not the identifier."""
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        self.assertEqual(
+            mcp_daemon_guard.mutation_provenance_fields()["transport"], "untrusted"
+        )
+        mcp_daemon_guard.install_test_native_runtime()
+        self.assertEqual(
+            mcp_daemon_guard.mutation_provenance_fields()["transport"],
+            "test_native_mcp",
+        )
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertEqual(
+                guard.mutation_provenance_fields()["transport"], "native_mcp"
+            )
+
+    def test_10b_default_bind_reproduces_the_pre_931_runtime_record(self):
+        with _ProductionBind() as guard:
+            status = guard.bind_native_mcp_transport()
+            self.assertTrue(status["native_mcp_transport"])
+            self.assertTrue(status["production_native_mcp_transport"])
+            self.assertEqual(status["mode"], "production")
+            self.assertEqual(status["phase"], "transport_bound")
+            self.assertEqual(
+                status["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            guard.assert_sanctioned_mutation_runtime("native-ide")
+            guard.assert_production_mutation_runtime("native-ide")
+
+    def test_12_session_state_root_still_pinned_at_bind(self):
+        """#695 AC2 must survive the seam."""
+        with tempfile.TemporaryDirectory() as legit:
+            with tempfile.TemporaryDirectory() as rogue:
+                with _ProductionBind(
+                    {mcp_daemon_guard.SESSION_STATE_DIR_ENV: legit}
+                ) as guard:
+                    guard.bind_native_mcp_transport()
+                    self.assertEqual(
+                        guard.pinned_session_state_dir(), str(Path(legit).resolve())
+                    )
+                    os.environ[mcp_daemon_guard.SESSION_STATE_DIR_ENV] = rogue
+                    self.assertEqual(
+                        guard.pinned_session_state_dir(), str(Path(legit).resolve())
+                    )
+
+    def test_12b_test_mode_record_still_cannot_authorize_production(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        mcp_daemon_guard.install_test_native_runtime()
+        self.assertTrue(mcp_daemon_guard.is_native_mcp_transport())
+        self.assertFalse(mcp_daemon_guard.is_production_native_mcp_transport())
+        with self.assertRaises(mcp_daemon_guard.UnsanctionedRuntimeError):
+            mcp_daemon_guard.assert_production_mutation_runtime("prod-endpoint")
+
+    def test_12c_bind_still_requires_the_canonical_entrypoint(self):
+        """A remote identifier does not relax provenance."""
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        with patch.object(mcp_daemon_guard, "is_pytest_runtime", return_value=False):
+            with patch.object(
+                mcp_daemon_guard,
+                "_caller_official_entrypoint_path",
+                return_value=None,
+            ):
+                with self.assertRaises(mcp_daemon_guard.UnsanctionedRuntimeError):
+                    mcp_daemon_guard.bind_native_mcp_transport(
+                        transport=mcp_transport_config.REMOTE_TRANSPORT
+                    )
+        self.assertIsNone(mcp_daemon_guard.bound_transport())
+
+    def test_12d_bind_still_requires_a_prior_entrypoint_claim(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        canonical = str((REPO_ROOT / "mcp_server.py").resolve())
+        with patch.object(mcp_daemon_guard, "is_pytest_runtime", return_value=False):
+            with patch.object(
+                mcp_daemon_guard,
+                "_caller_official_entrypoint_path",
+                side_effect=lambda: canonical,
+            ):
+                # No mark_sanctioned_daemon() first.
+                with self.assertRaises(
+                    mcp_daemon_guard.UnsanctionedRuntimeError
+                ) as ctx:
+                    mcp_daemon_guard.bind_native_mcp_transport()
+                self.assertIn("no entrypoint claim", str(ctx.exception))
+
+    def test_12e_auth_mint_verdict_is_unchanged_for_the_default_transport(self):
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            verdict = irrecoverable_provenance.assess_transport_for_auth_mint()
+            self.assertTrue(verdict["allowed"])
+            self.assertTrue(verdict["native_mcp_transport"])
+            self.assertTrue(verdict["production_native_mcp_transport"])
+            self.assertEqual(verdict["reasons"], [])
+
+    def test_12f_auth_mint_still_refuses_an_unbound_runtime(self):
+        with _ProductionBind():
+            # Claimed but never bound.
+            verdict = irrecoverable_provenance.assess_transport_for_auth_mint()
+            self.assertFalse(verdict["allowed"])
+            self.assertTrue(verdict["reasons"])
+            self.assertIsNone(verdict["bound_transport"])
+
+
+class TestExecutionBoundary(unittest.TestCase):
+    """Recognition is not execution authorization (#931, review 635 B1/B2).
+
+    A registered remote identifier must still bind, pin and record — the #931
+    seam — while being refused at the serve boundary, because serving it would
+    start a listener with no authentication or per-request principal. That
+    listener belongs to #938.
+    """
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    # -- the two sets are distinct, and narrower in the right direction ----
+
+    def test_executable_set_is_a_strict_subset_of_recognized(self):
+        self.assertTrue(
+            mcp_transport_config.EXECUTABLE_TRANSPORTS
+            < mcp_transport_config.SUPPORTED_TRANSPORTS
+        )
+
+    def test_default_transport_is_executable(self):
+        self.assertTrue(
+            mcp_transport_config.is_executable_transport(
+                mcp_transport_config.DEFAULT_TRANSPORT
+            )
+        )
+
+    def test_remote_transport_is_recognized_but_not_executable(self):
+        remote = mcp_transport_config.REMOTE_TRANSPORT
+        self.assertTrue(mcp_transport_config.is_supported_transport(remote))
+        self.assertFalse(mcp_transport_config.is_executable_transport(remote))
+
+    def test_remote_listener_ownership_is_declared(self):
+        self.assertEqual(
+            mcp_transport_config.TRANSPORT_EXECUTION_OWNER[
+                mcp_transport_config.REMOTE_TRANSPORT
+            ],
+            "#938",
+        )
+
+    # -- stdio still reaches the runner, unchanged -------------------------
+
+    def test_default_transport_is_authorized_for_service(self):
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertEqual(
+                guard.authorize_transport_execution("tool service"),
+                mcp_transport_config.DEFAULT_TRANSPORT,
+            )
+            self.assertTrue(guard.assess_serve_authorization()["allowed"])
+
+    def test_default_transport_reaches_the_real_runner(self):
+        """The production runner is actually invoked, with stdio, unchanged."""
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            seen = {}
+
+            class _Runner:
+                def run(self, transport=None, **kw):
+                    seen["transport"] = transport
+
+            _Runner().run(transport=guard.authorize_transport_execution("tool service"))
+            self.assertEqual(
+                seen["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    # -- streamable-http binds, records, and is refused before serving -----
+
+    def test_remote_transport_binds_and_is_recorded(self):
+        """The #931 seam is intact: it binds, pins and records."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.REMOTE_TRANSPORT
+            )
+            self.assertEqual(
+                guard.mutation_provenance_fields()["bound_transport"],
+                mcp_transport_config.REMOTE_TRANSPORT,
+            )
+
+    def test_remote_transport_is_refused_at_the_serve_boundary(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.TransportExecutionError) as ctx:
+                guard.authorize_transport_execution("tool service")
+            err = ctx.exception
+            self.assertEqual(
+                err.blocker_kind,
+                mcp_transport_config.BLOCKER_LISTENER_NOT_COMMISSIONED,
+            )
+            self.assertEqual(err.owner_issue, "#938")
+            self.assertEqual(err.transport, mcp_transport_config.REMOTE_TRANSPORT)
+
+    def test_refusal_names_transport_and_unmet_requirement_and_owner(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.TransportExecutionError) as ctx:
+                guard.authorize_transport_execution("tool service")
+            text = str(ctx.exception)
+            self.assertIn(mcp_transport_config.REMOTE_TRANSPORT, text)
+            self.assertIn("#938", text)
+            self.assertIn("not commissioned", text)
+            self.assertIn("#931", text)
+
+    def test_remote_transport_never_reaches_the_runner(self):
+        """No transport value is handed to a run() call for the remote case."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            calls = []
+
+            class _Runner:
+                def run(self, transport=None, **kw):
+                    calls.append(transport)
+
+            with self.assertRaises(guard.TransportExecutionError):
+                _Runner().run(
+                    transport=guard.authorize_transport_execution("tool service")
+                )
+            self.assertEqual(calls, [], "runner must never be invoked")
+
+    def test_no_http_listener_is_created_for_remote_transport(self):
+        """Nothing in the refusal path touches uvicorn or a socket bind."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            import socket
+
+            bound_sockets = []
+            real_bind = socket.socket.bind
+
+            def _tripwire(self, addr):  # pragma: no cover - must not run
+                bound_sockets.append(addr)
+                return real_bind(self, addr)
+
+            with patch.object(socket.socket, "bind", _tripwire):
+                with self.assertRaises(guard.TransportExecutionError):
+                    guard.authorize_transport_execution("tool service")
+            self.assertEqual(bound_sockets, [], "no socket may be bound")
+
+    def test_no_mutation_is_authorized_after_the_denial(self):
+        """The denial leaves no partial state that would let a tool dispatch."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.TransportExecutionError):
+                guard.authorize_transport_execution("tool service")
+            # Serve stays unauthorized on every subsequent query.
+            self.assertFalse(guard.assess_serve_authorization()["allowed"])
+            self.assertFalse(guard.native_runtime_status()["serve_authorized"])
+            with self.assertRaises(guard.TransportExecutionError):
+                guard.authorize_transport_execution("tool service")
+
+    # -- B2: the decision genuinely consumes bound_transport ---------------
+
+    def test_serve_decision_consumes_bound_transport(self):
+        """Changing only bound_transport flips the verdict."""
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertTrue(guard.assess_serve_authorization()["allowed"])
+            with patch.object(
+                guard,
+                "bound_transport",
+                return_value=mcp_transport_config.REMOTE_TRANSPORT,
+            ):
+                verdict = guard.assess_serve_authorization()
+                self.assertFalse(verdict["allowed"])
+                self.assertEqual(
+                    verdict["transport"], mcp_transport_config.REMOTE_TRANSPORT
+                )
+                with self.assertRaises(guard.TransportExecutionError):
+                    guard.authorize_transport_execution("tool service")
+
+    def test_serve_verdict_reports_the_bound_transport(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            verdict = guard.assess_serve_authorization()
+            self.assertEqual(
+                verdict["transport"], mcp_transport_config.REMOTE_TRANSPORT
+            )
+            self.assertTrue(verdict["recognized"])
+            self.assertFalse(verdict["executable"])
+
+    # -- earlier and later boundaries are unchanged ------------------------
+
+    def test_unregistered_identifier_still_fails_at_bind_not_at_serve(self):
+        with _ProductionBind(
+            {mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+        ) as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.bind_native_mcp_transport()
+            self.assertIn("not a registered MCP transport", str(ctx.exception))
+            self.assertIsNone(guard.bound_transport())
+
+    def test_unbound_execution_keeps_the_pre_existing_failure(self):
+        with _ProductionBind() as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.authorize_transport_execution("tool service")
+            self.assertIn("No MCP transport is bound", str(ctx.exception))
+            self.assertNotIsInstance(ctx.exception, guard.TransportExecutionError)
+
+    def test_transport_execution_error_is_caught_by_existing_handlers(self):
+        """Subclassing keeps every pre-existing fail-closed handler correct."""
+        self.assertTrue(
+            issubclass(
+                mcp_daemon_guard.TransportExecutionError,
+                mcp_daemon_guard.UnsanctionedRuntimeError,
+            )
+        )
+
+    def test_test_mode_runtime_is_not_servable(self):
+        """The pytest-only record is outside the recognized and executable sets."""
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        mcp_daemon_guard.install_test_native_runtime()
+        self.assertNotIn(
+            mcp_daemon_guard.bound_transport(),
+            mcp_transport_config.SUPPORTED_TRANSPORTS,
+        )
+        self.assertFalse(mcp_daemon_guard.assess_serve_authorization()["allowed"])
+
+    def test_serve_authorization_does_not_leak_across_runtimes(self):
+        """A later runtime's verdict never reflects an earlier one."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            self.assertFalse(guard.assess_serve_authorization()["allowed"])
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertTrue(guard.assess_serve_authorization()["allowed"])
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        self.assertEqual(
+            mcp_daemon_guard.assess_serve_authorization()["blocker_kind"],
+            mcp_transport_config.BLOCKER_TRANSPORT_NOT_BOUND,
+        )
+
+    def test_refusal_carries_no_credential_material(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                ),
+                "GITEA_TOKEN": "super-secret-value",
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.TransportExecutionError) as ctx:
+                guard.authorize_transport_execution("tool service")
+            blob = str(ctx.exception) + repr(ctx.exception.assessment)
+            self.assertNotIn("super-secret-value", blob)
+            self.assertNotIn("GITEA_TOKEN", blob)
+
+
+class TestEntrypointWiring(unittest.TestCase):
+    """The live entrypoint must use the seam and the execution guard."""
+
+    def test_entrypoint_binds_without_a_literal_transport(self):
+        text = (REPO_ROOT / "gitea_mcp_server.py").read_text(encoding="utf-8")
+        self.assertIn("mcp_daemon_guard.bind_native_mcp_transport()", text)
+        self.assertNotIn('bind_native_mcp_transport(transport="stdio")', text)
+
+    def test_entrypoint_serves_only_through_the_execution_guard(self):
+        text = (REPO_ROOT / "gitea_mcp_server.py").read_text(encoding="utf-8")
+        self.assertIn(
+            "mcp.run(transport=mcp_daemon_guard.authorize_transport_execution", text
+        )
+        self.assertNotIn('mcp.run(transport="stdio")', text)
+        self.assertNotIn(
+            "mcp.run(transport=mcp_daemon_guard.assert_transport_bound", text
+        )
+
+    def test_every_run_call_in_production_goes_through_the_guard(self):
+        """Glob the production surface: no serve site may bypass the guard."""
+        offenders: list[str] = []
+        run_sites = 0
+        for path in sorted(REPO_ROOT.glob("*.py")):
+            for lineno, line in enumerate(
+                path.read_text(encoding="utf-8").splitlines(), start=1
+            ):
+                code = line.split("#", 1)[0]
+                if "mcp.run(" not in code:
+                    continue
+                run_sites += 1
+                if "authorize_transport_execution" not in code:
+                    offenders.append(f"{path.name}:{lineno}: {line.strip()}")
+        self.assertEqual(run_sites, 1, "expected exactly one serve site")
+        self.assertEqual(offenders, [], "\n".join(offenders))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_restart_audit.py

@@ -1,342 +0,0 @@
-"""Tests for MCP restart lifecycle audit events and incidents (#665)."""
-
-from __future__ import annotations
-
-import json
-import os
-import tempfile
-import unittest
-from unittest.mock import patch
-
-import gitea_audit
-import restart_audit as ra
-
-
-class TestEventSchema(unittest.TestCase):
-    def test_all_lifecycle_event_types_are_named(self):
-        expected = {
-            "mcp.restart.impact_preview",
-            "mcp.restart.drain_enter",
-            "mcp.restart.drain_exit",
-            "mcp.restart.drain_proof",
-            "mcp.restart.apply_gate",
-            "mcp.restart.break_glass",
-            "mcp.restart.post_restart_reconcile",
-            "mcp.restart.narrower_recovery",
-            "mcp.restart.unguarded_detected",
-        }
-        self.assertEqual(set(ra.RESTART_EVENT_TYPES), expected)
-
-    def test_build_restart_event_core_fields(self):
-        event = ra.build_restart_event(
-            event_type=ra.EVENT_IMPACT_PREVIEW,
-            outcome="safe",
-            correlation_id="rst-abc123",
-            remote="prgs",
-            org="Scaled-Tech-Consulting",
-            repo="Gitea-Tools",
-            requesting_session_id="sess-1",
-            restart_class="full_mcp_restart",
-            profile_name="prgs-author",
-            authenticated_username="bot",
-            reasons=["inventory complete"],
-            details={"allow_restart": True},
-            now="2026-07-25T12:00:00+00:00",
-        )
-        self.assertEqual(event["event_type"], ra.EVENT_IMPACT_PREVIEW)
-        self.assertEqual(event["action"], ra.EVENT_IMPACT_PREVIEW)
-        self.assertEqual(event["action_type"], "restart_lifecycle")
-        self.assertEqual(event["result"], "safe")
-        self.assertEqual(event["correlation_id"], "rst-abc123")
-        self.assertEqual(event["profile_name"], "prgs-author")
-        self.assertEqual(event["authenticated_username"], "bot")
-        meta = event["request_metadata"]
-        self.assertEqual(meta["event_family"], "mcp.restart")
-        self.assertEqual(meta["correlation_id"], "rst-abc123")
-        self.assertEqual(meta["restart_class"], "full_mcp_restart")
-        self.assertEqual(meta["details"]["allow_restart"], True)
-
-    def test_unknown_event_type_raises(self):
-        with self.assertRaises(ValueError) as ctx:
-            ra.build_restart_event(
-                event_type="mcp.restart.not_a_real_event",
-                outcome="x",
-                correlation_id="rst-1",
-            )
-        self.assertIn("unknown restart audit event_type", str(ctx.exception))
-
-    def test_reasons_and_details_are_redacted(self):
-        event = ra.build_restart_event(
-            event_type=ra.EVENT_APPLY_GATE,
-            outcome="deny",
-            correlation_id="rst-sec",
-            reasons=["token secret-xyz rejected", "ok"],
-            details={"token": "leak-token", "status": "denied"},
-        )
-        self.assertNotIn("secret-xyz", event.get("reason") or "")
-        meta = event["request_metadata"]
-        self.assertEqual(meta["details"]["token"], gitea_audit.REDACTED)
-        self.assertEqual(meta["details"]["status"], "denied")
-        for reason in meta["reasons"]:
-            self.assertNotIn("secret-xyz", reason)
-
-    def test_new_correlation_id_shape(self):
-        cid = ra.new_correlation_id()
-        self.assertTrue(cid.startswith("rst-"))
-        self.assertEqual(len(cid), len("rst-") + 16)
-
-
-class TestEmitAndRequire(unittest.TestCase):
-    def test_emit_appends_json_line(self):
-        with tempfile.TemporaryDirectory() as d:
-            path = os.path.join(d, "audit.log")
-            event = ra.build_restart_event(
-                event_type=ra.EVENT_DRAIN_PROOF,
-                outcome="pass",
-                correlation_id="rst-write",
-            )
-            self.assertTrue(ra.emit_restart_event(event, path=path))
-            with open(path, encoding="utf-8") as fh:
-                lines = fh.read().splitlines()
-            self.assertEqual(len(lines), 1)
-            loaded = json.loads(lines[0])
-            self.assertEqual(loaded["event_type"], ra.EVENT_DRAIN_PROOF)
-            self.assertEqual(loaded["correlation_id"], "rst-write")
-
-    def test_emit_never_raises(self):
-        self.assertFalse(
-            ra.emit_restart_event({"action": "x"}, path="/no/such/dir/audit.log")
-        )
-
-    def test_require_audit_denies_privileged_when_write_fails_and_enabled(self):
-        deny = ra.require_audit_or_deny(
-            privileged=True, written=False, audit_enabled=True
-        )
-        self.assertEqual(len(deny), 1)
-        self.assertIn("fail closed", deny[0])
-
-    def test_require_audit_allows_when_audit_disabled(self):
-        # Rollout policy: enable audit before enforcing deny-on-audit-fail.
-        deny = ra.require_audit_or_deny(
-            privileged=True, written=False, audit_enabled=False
-        )
-        self.assertEqual(deny, [])
-
-    def test_require_audit_noop_for_non_privileged(self):
-        deny = ra.require_audit_or_deny(
-            privileged=False, written=False, audit_enabled=True
-        )
-        self.assertEqual(deny, [])
-
-    def test_require_audit_allows_when_written(self):
-        deny = ra.require_audit_or_deny(
-            privileged=True, written=True, audit_enabled=True
-        )
-        self.assertEqual(deny, [])
-
-
-class TestIncidents(unittest.TestCase):
-    def test_break_glass_descriptor(self):
-        desc = ra.build_incident_descriptor(
-            kind=ra.INCIDENT_BREAK_GLASS,
-            reasons=["break-glass authorized"],
-            correlation_id="rst-bg",
-            requesting_session_id="s1",
-            restart_class="full_mcp_restart",
-            remote="prgs",
-            org="O",
-            repo="R",
-        )
-        self.assertEqual(desc["kind"], ra.INCIDENT_BREAK_GLASS)
-        self.assertIn("Break-glass", desc["title"])
-        self.assertIn("mcp-health", desc["labels"])
-        self.assertEqual(desc["source"], "restart_audit#665")
-
-    def test_incident_body_redacts_and_includes_correlation(self):
-        desc = ra.build_incident_descriptor(
-            kind=ra.INCIDENT_FAILED_DRAIN,
-            reasons=["token secret-xyz failed proof"],
-            correlation_id="rst-body",
-            remote="prgs",
-            org="O",
-            repo="R",
-            proof_id="proof-1",
-        )
-        body = ra.incident_body(desc)
-        self.assertIn("rst-body", body)
-        self.assertIn("proof-1", body)
-        self.assertIn("mcp-restart-incident:v1", body)
-        self.assertNotIn("secret-xyz", body)
-
-    def test_materialize_dry_run(self):
-        desc = ra.build_incident_descriptor(
-            kind=ra.INCIDENT_FAILED_DRAIN,
-            reasons=["denied"],
-            correlation_id="rst-dr",
-        )
-        result = ra.materialize_incident(desc, create_issue_fn=lambda **k: {}, dry_run=True)
-        self.assertFalse(result["created"])
-        self.assertTrue(result["dry_run"])
-        self.assertIn("dry-run", result["reasons"][0])
-
-    def test_materialize_without_create_fn(self):
-        desc = ra.build_incident_descriptor(
-            kind=ra.INCIDENT_FAILED_DRAIN,
-            reasons=["denied"],
-            correlation_id="rst-nfn",
-        )
-        result = ra.materialize_incident(desc, create_issue_fn=None)
-        self.assertFalse(result["created"])
-        self.assertIn("create_issue_fn not provided", result["reasons"][0])
-
-    def test_materialize_creates_issue(self):
-        created = {}
-
-        def _create(*, title, body, labels, org=None, repo=None, **_kw):
-            created["title"] = title
-            created["body"] = body
-            created["labels"] = labels
-            created["org"] = org
-            created["repo"] = repo
-            return {"number": 999}
-
-        desc = ra.build_incident_descriptor(
-            kind=ra.INCIDENT_BREAK_GLASS,
-            reasons=["break-glass"],
-            correlation_id="rst-create",
-            org="O",
-            repo="R",
-        )
-        result = ra.materialize_incident(desc, create_issue_fn=_create)
-        self.assertTrue(result["created"])
-        self.assertEqual(result["issue_number"], 999)
-        self.assertIn("Break-glass", created["title"])
-        self.assertIn("rst-create", created["body"])
-        self.assertEqual(created["org"], "O")
-
-    def test_materialize_never_raises_on_create_failure(self):
-        def _boom(**_kw):
-            raise RuntimeError("token secret-xyz network")
-
-        desc = ra.build_incident_descriptor(
-            kind=ra.INCIDENT_FAILED_DRAIN,
-            reasons=["x"],
-            correlation_id="rst-boom",
-        )
-        result = ra.materialize_incident(desc, create_issue_fn=_boom)
-        self.assertFalse(result["created"])
-        self.assertIn("failed", result["reasons"][0])
-        self.assertNotIn("secret-xyz", result["reasons"][0])
-
-
-class TestIncidentFromApplyGate(unittest.TestCase):
-    def test_break_glass_always_incident(self):
-        desc = ra.incident_from_apply_gate(
-            gate_payload={"allow": True, "reasons": [], "proof_id": None},
-            break_glass=True,
-            correlation_id="rst-bg2",
-            requesting_session_id="s",
-            restart_class="full_mcp_restart",
-            remote="prgs",
-            org="O",
-            repo="R",
-        )
-        self.assertIsNotNone(desc)
-        self.assertEqual(desc["kind"], ra.INCIDENT_BREAK_GLASS)
-
-    def test_failed_drain_from_gate_incident(self):
-        desc = ra.incident_from_apply_gate(
-            gate_payload={
-                "allow": False,
-                "drain_gate_allow": False,
-                "reasons": ["proof expired"],
-                "incident": {
-                    "reasons": ["proof expired"],
-                    "proof_id": "p1",
-                },
-            },
-            break_glass=False,
-            correlation_id="rst-fd",
-            requesting_session_id="s",
-            restart_class="full_mcp_restart",
-            remote="prgs",
-            org="O",
-            repo="R",
-        )
-        self.assertIsNotNone(desc)
-        self.assertEqual(desc["kind"], ra.INCIDENT_FAILED_DRAIN)
-        self.assertEqual(desc["proof_id"], "p1")
-
-    def test_allow_without_break_glass_no_incident(self):
-        desc = ra.incident_from_apply_gate(
-            gate_payload={
-                "allow": True,
-                "drain_gate_allow": True,
-                "reasons": [],
-            },
-            break_glass=False,
-            correlation_id="rst-ok",
-            requesting_session_id="s",
-            restart_class="full_mcp_restart",
-            remote="prgs",
-            org="O",
-            repo="R",
-        )
-        self.assertIsNone(desc)
-
-
-class TestRecordLifecycle(unittest.TestCase):
-    def test_record_emits_and_materializes(self):
-        created = []
-
-        def _create(**kwargs):
-            created.append(kwargs)
-            return {"number": 42}
-
-        with tempfile.TemporaryDirectory() as d:
-            path = os.path.join(d, "audit.log")
-            with patch.dict(os.environ, {"GITEA_AUDIT_LOG": path}, clear=False):
-                incident = ra.build_incident_descriptor(
-                    kind=ra.INCIDENT_BREAK_GLASS,
-                    reasons=["bg"],
-                    correlation_id="rst-lc",
-                    org="O",
-                    repo="R",
-                )
-                out = ra.record_restart_lifecycle(
-                    event_type=ra.EVENT_BREAK_GLASS,
-                    outcome="break_glass",
-                    correlation_id="rst-lc",
-                    remote="prgs",
-                    org="O",
-                    repo="R",
-                    privileged=True,
-                    create_incident=incident,
-                    create_issue_fn=_create,
-                    audit_path=path,
-                )
-        self.assertTrue(out["audit_written"])
-        self.assertEqual(out["deny_reasons"], [])
-        self.assertTrue(out["incident_result"]["created"])
-        self.assertEqual(out["incident_result"]["issue_number"], 42)
-        self.assertEqual(len(created), 1)
-
-    def test_privileged_deny_when_audit_write_fails(self):
-        with patch.dict(
-            os.environ, {"GITEA_AUDIT_LOG": "/no/such/dir/a.log"}, clear=False
-        ):
-            with patch("restart_audit.emit_restart_event", return_value=False):
-                with patch("gitea_audit.audit_enabled", return_value=True):
-                    out = ra.record_restart_lifecycle(
-                        event_type=ra.EVENT_APPLY_GATE,
-                        outcome="deny",
-                        correlation_id="rst-deny",
-                        privileged=True,
-                        audit_path="/no/such/dir/a.log",
-                    )
-        self.assertFalse(out["audit_written"])
-        self.assertEqual(len(out["deny_reasons"]), 1)
-
-
-if __name__ == "__main__":
-    unittest.main()