docs(remote-mcp): inventory stdio- and localhost-coupled assumptions (#930 )

Add docs/remote-mcp/coupling-inventory.md, the blocking first child of epic #929. It enumerates every place gitea_mcp_server.py and its supporting modules depend on being a local, client-spawned, stdio-attached process on the operator's machine. 62 entries across the seven required categories: transport bind, launch provenance, role binding, credentials, runtime freshness, local filesystem, and durable state. Each entry carries a file and line anchor resolving at 7bf4f12584, states what the code assumes today and what it would observe on a remote host, is classified as portable as written / needs a seam / needs a replacement / cannot be remote, and is assigned to exactly one epic child. Every child from #931 through #939 is named by at least one entry. Summary tables count entries per category, per classification, per category-by-classification, and per child. Documentation only. No server behavior changes. Closes #930 Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01HvJz7bUz5CkZgUxq8twHMz
Merge pull request 'fix(guardrail): detect and reject manually launched duplicate MCP role servers (#686 )' (#925 ) from fix/issue-686-detect-reject-manual-mcp into master
2026-07-26 02:09:09 -04:00 · 2026-07-25 18:32:23 -05:00 · 2026-07-25 19:27:12 -04:00 · 2026-07-25 19:25:23 -04:00
15 changed files with 591 additions and 470 deletions
@@ -153,7 +153,19 @@ not a tool argument: a session must never be able to authorize itself.
 ## Related
 - #630 — manual daemon killing as contaminated recovery (this contrast, enforced).
 - #657 — restart-path inventory and daemon classification.
 - #686 — manual server launch detection & fail-closed provenance gate.
 - #531 / #544 — stale-runtime detection (`ps`-based); sibling failure mode.
 - #558 / `docs/mcp-daemon-import-guard.md` — why shell imports are not a repair.
 - `docs/mcp-client-registration.md` — per-server registration contract.
 - `docs/mcp-namespace-health.md` — probe sources and mutation enforcement.
 ## Sanctioned reconnect vs forbidden manual launch (#686)
 In addition to manual process killing (#630), manually launching a duplicate role server from an ad hoc shell (`python3 mcp_server.py`) is forbidden and fail-closed:
 - **Why manual launches are unsupported:** A terminal-launched `mcp_server.py` holds its own stdio transport; it can never bind to the IDE client's stdio pipes. It cannot restore a dropped IDE namespace, and a manual duplicate process masks stale client-managed runtimes for that profile, defeating stale-runtime gates.
 - **Sanctioned path:** Supported recovery is IDE/client-managed reconnect only (`/mcp reconnect`, IDE restart, or sanctioned reconnect exposure).
 - **Fail-closed enforcement (#686):** Mutating tools on a server lacking client-managed launch provenance (`GITEA_CLIENT_MANAGED=1`) refuse execution fail-closed with typed blocker `unsupported_manual_launch` and an exact next action. Unsupported `GITEA_*` env overrides (e.g. `GITEA_DUMMY`) are surfaced in diagnostics rather than silently ignored.
 - **Inventory & staleness:** Staleness diagnostics ignore non-client-managed duplicates when evaluating runtime freshness and inventory duplicate processes per profile (#657, #686).
@@ -0,0 +1,230 @@
 # Remote-MCP coupling inventory
 Every place the Gitea MCP server depends on being a local, client-spawned, stdio-attached
 process on the operator's machine.
 - **Issue:** #930 (Remote-MCP 01), child 1 of epic #929.
 - **Generated against commit:** `7bf4f1258451823a55b36d2157e74f8457165088` (`master`).
 - **Anchors:** every `file:line` below resolves at the commit above and at the commit that
  adds this document. This change adds one new file and edits no existing file, so no
  existing line number shifts between the two.
 - **Scope:** documentation only. No server behavior changes in this child.
 ## How to read an entry
 | Field | Meaning |
 | ----- | ------- |
 | **Anchor** | `file:line` at the commit under review. |
 | **Assumes today** | What the code takes for granted while running as a local stdio process. |
 | **Observes remotely** | What the same code would actually see on a shared remote host. |
 | **Class** | One of: *portable as written*, *needs a seam*, *needs a replacement*, *cannot be remote*. |
 | **Owner** | Exactly one epic child (#931–#939) responsible for the fix. |
 Classification meanings:
 - **portable as written** — the code is already transport-, host-, and principal-neutral; it
  moves unchanged once its inputs are supplied by a remote-aware caller.
 - **needs a seam** — the logic is correct but is wired to a hard-coded local source. It needs
  an injection point, not new semantics.
 - **needs a replacement** — the semantics themselves are local-only. A remote deployment
  needs a differently-defined mechanism, not the same mechanism relocated.
 - **cannot be remote** — the operation is inherently about the operator's own machine
  (its process table, its keychain, its checkout). It must either stay local behind an
  explicit boundary or be deleted from the remote surface.
 ---
 ## 1. Transport bind
 The transport is bound literally, once, at process start, and the bound value is the root of
 the mutation-authorization chain.
 | ID | Anchor | Assumes today | Observes remotely | Class | Owner |
 | -- | ------ | ------------- | ----------------- | ----- | ----- |
 | T1 | `gitea_mcp_server.py:23750` | The single production bind call passes the literal `transport="stdio"` immediately before the server loop. | The literal is wrong for any non-stdio deployment; there is no parameter to change it. | needs a seam | #931 |
 | T2 | `mcp_daemon_guard.py:45` | `_PRODUCTION_TRANSPORTS = frozenset({"stdio"})` is the closed allowlist of production transports. | A remote transport name is rejected by the allowlist before any other check runs. | needs a seam | #931 |
 | T3 | `mcp_daemon_guard.py:174` | `bind_native_mcp_transport` raises `UnsanctionedRuntimeError` for any transport outside `_PRODUCTION_TRANSPORTS` (raise at `mcp_daemon_guard.py:187`). | The remote server fails to start rather than degrading; the failure is correct, but the allowlist is the only thing that must change. | needs a seam | #931 |
 | T4 | `mcp_daemon_guard.py:328` | `is_native_mcp_transport()` asserts a process-local runtime record whose `pid` matches `os.getpid()` and whose phase is `transport_bound`. The predicate itself names no transport. | Unchanged semantics: one server process that bound one transport. It stays true on a remote host. | portable as written | #931 |
 | T5 | `mcp_daemon_guard.py:349` | `is_production_native_mcp_transport()` adds only a `mode == production` check on top of T4. | Unchanged. | portable as written | #931 |
 | T6 | `irrecoverable_provenance.py:497` | `assess_transport_for_auth_mint()` requires production native transport before minting non-forgeable recovery authorization (#709 F1). | The gate is transport-agnostic in form, but its guarantee — "an ordinary Python process cannot reach this" — is currently underwritten by the stdio bind. Under a remote transport the guarantee must be re-derived from the authenticated session, not from the bind. | needs a seam | #931 |
 | T7 | `gitea_mcp_server.py:8375` | Consumer: refuses to proceed unless `assess_transport_for_auth_mint()` allows. | Unchanged given a corrected T6. | portable as written | #931 |
 | T8 | `gitea_mcp_server.py:8624` | Second consumer of the same gate on the confirmation path. | Unchanged given a corrected T6. | portable as written | #931 |
 | T9 | `mcp_server.py:4` | Module docstring asserts "Runs over stdio." as a property of the server. | The stated contract becomes false on the remote deployment and is load-bearing documentation for operators. | needs a replacement | #931 |
 ## 2. Launch provenance
 Mutations fail closed unless the process can prove a client launched it with real stdio pipes
 and `GITEA_CLIENT_MANAGED` provenance. Every proof in this section is a statement about the
 local operating system.
 | ID | Anchor | Assumes today | Observes remotely | Class | Owner |
 | -- | ------ | ------------- | ----------------- | ----- | ----- |
 | P1 | `gitea_mcp_server.py:14588` | `_is_client_managed_process()` derives provenance from `GITEA_CLIENT_MANAGED` / `GITEA_MCP_CLIENT_MANAGED` / `GITEA_SERVER_PROVENANCE` / `GITEA_FORCE_CLIENT_MANAGED` on this process's own environment. | A long-lived remote process has one environment for all callers, so a per-process env var can no longer say anything about the caller that issued a request. | needs a replacement | #934 |
 | P2 | `gitea_mcp_server.py:14606` | Falls back to `sys.stdin.isatty()`: an active TTY on stdin means a human launched it from a terminal, so refuse. | A remote server has no meaningful stdin. The signal is absent, not merely different. | cannot be remote | #934 |
 | P3 | `gitea_mcp_server.py:14618` | `_provenance_mutation_block()` emits `blocker_kind: "unsupported_manual_launch"` and a "reconnect the IDE/client-managed MCP namespace" remediation. | The block shape is reusable; its predicate and its remediation text are both stdio-specific. | needs a seam | #934 |
 | P4 | `gitea_mcp_server.py:20599` | `_check_mcp_runtimes_diagnostics()` shells `ps -o pid,lstart,command -ax` and greps for `mcp_server.py` to find peer role servers. | On a shared host the process table lists unrelated tenants' processes, or none at all under a container. Peer discovery by `ps` has no remote meaning. | cannot be remote | #934 |
 | P5 | `gitea_mcp_server.py:20702` | More than one process per `GITEA_MCP_PROFILE` in the local process table is reported as a duplicate-launch fault. | A remote endpoint is expected to serve many concurrent sessions per role. "Two processes for one role" becomes the normal case, so the check inverts from a safety net into a false wall. | cannot be remote | #934 |
 | P6 | `gitea_mcp_server.py:20715` | Processes lacking client-managed provenance are ignored for runtime freshness and reported as manual launches. | Same defect as P5: correctness depends on enumerating local peers. | cannot be remote | #934 |
 | P7 | `gitea_config.py:1172` | `RECOGNIZED_GITEA_ENV_KEYS` is the allowlist of `GITEA_*` env vars a legitimately launched server may carry; anything else is contamination. | Configuration on a remote host arrives from deployment tooling, not from a client-authored env block. The allowlist keeps working mechanically but stops proving anything about provenance. | needs a replacement | #934 |
 | P8 | `gitea_mcp_server.py:20683` | The unsupported-env scan applies `RECOGNIZED_GITEA_ENV_KEYS` to *other* processes' environments harvested via `ps eww <pid>`. | Reading another process's environment is unavailable or prohibited across tenants, and is not exposed in this form outside macOS/BSD `ps`. | cannot be remote | #934 |
 | P9 | `mcp_daemon_guard.py:126` | `mark_sanctioned_daemon()` requires the claiming stack frame's resolved absolute path to be the canonical `mcp_server.py` / `gitea_mcp_server.py` next to the guard module; basename spoofing is rejected. | Entrypoint-path identity still exists on a remote host, but it authenticates the *deployment*, not the *caller*. It must be kept and demoted from "authorizes mutations" to "authorizes the process". | needs a seam | #934 |
 | P10 | `gitea_config.py:1233` | The client-config generator emits `"GITEA_CLIENT_MANAGED": "1"` into each generated MCP client entry, alongside `GITEA_MCP_CONFIG` / `GITEA_MCP_PROFILE`. | A remote endpoint is addressed by URL and credential, not by a spawn command with an env block. This generator produces the wrong artifact entirely. | needs a replacement | #938 |
 | P11 | `mcp_namespace_health.py:232` | Namespace health classifies a namespace as `client_managed` or `manual_launch` from the reported env summary. | During dual-run, local and remote namespaces coexist and must both be classifiable; a two-valued local/manual axis cannot express "remote endpoint, authenticated session". | needs a replacement | #939 |
 | P12 | `gitea_mcp_server.py:18161` | The diagnostics payload reports `server_provenance` as exactly `"client_managed"` or `"manual_launch"`. | This is the field a cutover operator reads to confirm which deployment served a call. It must gain a remote value before dual-run parity can be validated. | needs a replacement | #939 |
 ## 3. Role binding
 Role separation is currently enforced by *which process a call reaches*. The process is pinned
 to one role for its lifetime by an environment variable.
 | ID | Anchor | Assumes today | Observes remotely | Class | Owner |
 | -- | ------ | ------------- | ----------------- | ----- | ----- |
 | R1 | `gitea_config.py:54` | `ENV_PROFILE = "GITEA_MCP_PROFILE"` is the single source of the active profile, read from the process environment. | One shared process serves several principals; a process-wide profile cannot answer "who is calling now". This is the root of the coupling. | needs a replacement | #932 |
 | R2 | `review_workflow_load.py:95` | Reads `GITEA_MCP_PROFILE` directly to decide the reviewer workflow binding. | Reads the deployment's profile, not the caller's, silently granting or denying the wrong role. | needs a replacement | #932 |
 | R3 | `mcp_discoverability.py:152` | Reads `GITEA_MCP_PROFILE` to describe the namespace to the client. | Correct logic, wrong input source; it needs the request principal injected. | needs a seam | #932 |
 | R4 | `webui/deployment_boundary.py:115` | Reads `GITEA_MCP_PROFILE` to classify the deployment boundary for the console. | Same as R3. | needs a seam | #932 |
 | R5 | `gitea_mcp_server.py:21106` | Remediation text instructs the operator to "Relaunch the server with `GITEA_MCP_PROFILE` set to a profile that has the required permission". | Relaunching a shared remote endpoint to change one caller's role is not a valid instruction; it would re-role every other session. | needs a replacement | #932 |
 | R6 | `native_mcp_preference.py:93` | Detects shell commands that override `GITEA_MCP_PROFILE` away from the session (`native_mcp_preference.py:223`) and flags them as CLI auth divergence. | The divergence check is genuinely useful and survives, but its notion of "the session's profile" must come from the request principal. | needs a seam | #932 |
 | R7 | `gitea_mcp_server.py:20671` | Recovers a peer server's role by regexing `GITEA_MCP_PROFILE=` out of that process's environment. | Depends on P4/P8 process-table access; role discovery by peer-env scraping has no remote analogue. | cannot be remote | #932 |
 ## 4. Credentials
 Every token resolves, directly or indirectly, from one human's macOS keychain.
 | ID | Anchor | Assumes today | Observes remotely | Class | Owner |
 | -- | ------ | ------------- | ----------------- | ----- | ----- |
 | C1 | `gitea_config.py:956` | `_keychain_token()` shells `security find-generic-password -s <item> -w`. | `security(1)` is a macOS binary reading the calling user's login keychain. It does not exist on a Linux host and would be the wrong identity even on a shared Mac. | cannot be remote | #933 |
 | C2 | `gitea_config.py:974` | `resolve_token(profile, keychain_lookup=_keychain_token)` dispatches on `auth.type` of `env` or `keychain`, defaulting the lookup to C1. | The injectable `keychain_lookup` parameter is the existing seam; a remote credential provider plugs in here without changing the dispatch. | needs a seam | #933 |
 | C3 | `gitea_config.py:1015` | `keychain_auth(item_id)` constructs the `{"type": "keychain", "id": ...}` reference stored in profiles. | The reference type itself encodes "macOS keychain" into persisted config. A remote provider needs a new auth reference type, not a new value of this one. | needs a replacement | #933 |
 | C4 | `mcp_daemon_guard.py:440` | `assert_keychain_access_allowed()` fails closed for git-credential keychain fill outside a sanctioned daemon, with an operator opt-out env var. | The gate protects a mechanism that will not exist remotely. Its replacement must gate the *credential provider* call, not the keychain call, or the protection silently lapses. | needs a replacement | #933 |
 | C5 | `sentry_incident_bridge.py:190` | `resolve_token(env)` resolves the Sentry token from an injected env mapping with no keychain path. | Already host-neutral; it is the shape the Gitea credential path should converge on. | portable as written | #933 |
 | C6 | `gitea_mcp_server.py:18469` | The profile-audit tool calls `gitea_config.resolve_token(p)` for every configured profile to report "credentials present" without networking. | On a remote host this would materialize every principal's credential inside one process — an audit surface that becomes a credential-aggregation risk. | needs a seam | #933 |
 ## 5. Runtime freshness
 The mutation gate is defined as "the commit this process started at matches the checkout on
 this disk, and both match live master". Two of those three terms are local-disk facts.
 | ID | Anchor | Assumes today | Observes remotely | Class | Owner |
 | -- | ------ | ------------- | ----------------- | ----- | ----- |
 | F1 | `master_parity_gate.py:168` | `capture_startup_parity(root)` reads git `HEAD` from the server's own root once at startup and returns it as the baseline. | A remote host carries a deployed artifact, not the operator's checkout. Its `HEAD` says nothing about the operator's working tree, which is the thing the gate exists to protect. | cannot be remote | #935 |
 | F2 | `master_parity_gate.py:255` | `mutation_safe = determinable and in_parity and live_known and not live_stale` — a conjunction of two local-HEAD comparisons and one live-remote comparison. | Two of the three conjuncts lose meaning, so the whole verdict does. A remote deployment needs a redefined, testable freshness predicate rather than this one relocated. | needs a replacement | #935 |
 | F3 | `master_parity_gate.py:164` | The live-remote head is probed and cached per `(root, remote, branch)`, keyed on the local root. | The live-remote probe is the one conjunct that survives; it needs a key that is not the operator's filesystem path. | needs a seam | #935 |
 | F4 | `gitea_mcp_server.py:18262` | `gitea_assess_master_parity` publishes `startup_head` / `local_head` / `live_remote_head` / `mutation_safe` as the authoritative mutation-safety verdict. | The tool's contract is consumed by every mutation caller and by the operator; it must keep its shape while its semantics are redefined, or every consumer breaks at once. | needs a replacement | #935 |
 | F5 | `gitea_mcp_server.py:23054` | Falls back to `_process_boot_head_sha` — the commit this process booted at — when the parity payload has no `startup_head`. | Same defect as F1, in a fallback path that is easy to miss when F1 is fixed. | needs a seam | #935 |
 | F6 | `gitea_mcp_server.py:20615` | Staleness is also inferred from `os.path.getmtime()` of `gitea_mcp_server.py` under `PROJECT_ROOT` (`gitea_mcp_server.py:20611`), compared against peer process start times. | File mtime on a deployed artifact tracks the deploy, not the operator's edits, and the peer start times it is compared against come from the unavailable process table (P4). | cannot be remote | #935 |
 ## 6. Local filesystem
 Author and reviewer tools act directly on the operator's checkout.
 | ID | Anchor | Assumes today | Observes remotely | Class | Owner |
 | -- | ------ | ------------- | ----------------- | ----- | ----- |
 | L1 | `gitea_mcp_server.py:10122` | `gitea_bootstrap_author_issue_worktree` creates and binds a git worktree on the server's own disk. | The remote host has no operator checkout to add a worktree to. Executing this remotely would act on the wrong disk while reporting success. | cannot be remote | #936 |
 | L2 | `gitea_mcp_server.py:190` | `ACTIVE_WORKTREE_ENV = "GITEA_ACTIVE_WORKTREE"` and `AUTHOR_WORKTREE_ENV` (`gitea_mcp_server.py:191`) carry the active workspace as process-wide environment. | Process-wide workspace state cannot represent per-session workspaces on a shared endpoint. | needs a replacement | #936 |
 | L3 | `gitea_mcp_server.py:9801` | Binding a worktree writes `os.environ["GITEA_AUTHOR_WORKTREE"]` and `os.environ["GITEA_ACTIVE_WORKTREE"]` (`gitea_mcp_server.py:9802`), mutating global process state. | One session's bind would silently retarget every other concurrent session in the same process. This is a correctness bug the moment concurrency is real. | needs a replacement | #936 |
 | L4 | `reviewer_inventory_worktree.py:48` | `_BRANCHES_WORKTREE_RE = re.compile(r"\bbranches/", re.I)` requires review worktree paths to sit under `branches/`. | A path convention on the operator's machine, asserted as a validation rule. It needs to become a property of a declared workspace, not a substring test. | needs a seam | #936 |
 | L5 | `stable_control_runtime.py:54` | `DEV_WORKTREE_SEGMENT = "branches"` classifies a process root as a development worktree by path segment. | Same class of assumption as L4, on the runtime-classification side. | needs a seam | #936 |
 | L6 | `mcp_server.py:42` | `check_conflict_markers()` runs at import and `os.walk`s the install directory for unresolved conflict markers, `sys.exit(1)` on a hit. | On a remote host it scans a deployed artifact, which by construction never has conflict markers — so the guard passes trivially and stops protecting the thing it was written to protect. | needs a replacement | #936 |
 | L7 | `role_session_router.py:487` | `check_mid_merge()` reports infra-stop from `.git/MERGE_HEAD`, `rebase-merge`, `rebase-apply` and a source conflict scan under the server's project root. | Same inversion as L6: it would report the deployment's git state, not the operator's. | needs a replacement | #936 |
 | L8 | `author_issue_bootstrap.py:996` | Enumerates worktrees with `git -C <root> worktree list --porcelain`. | Requires a real local clone with real worktrees; there is nothing equivalent to enumerate remotely. | cannot be remote | #936 |
 | L9 | `mcp_server.py:10` | Redirects `sys.stderr` to the fixed path `/tmp/mcp_server_stderr.log` outside pytest. | A single fixed `/tmp` path is shared by every concurrent server on a host and is not a deployment's logging surface. | needs a replacement | #938 |
 | L10 | `gitea_mcp_server.py:2314` | `ISSUE_LOCK_FILE = "/tmp/gitea_issue_lock.json"` — the legacy single global lock slot. | One global `/tmp` slot per host cannot represent concurrent remote sessions and is world-visible on a shared machine. | needs a replacement | #937 |
 | L11 | `issue_lock_provenance.py:14` | `ISSUE_LOCK_FILE = os.environ.get("GITEA_ISSUE_LOCK_FILE", "/tmp/gitea_issue_lock.json")` keeps the same `/tmp` default in the provenance path. | Same as L10; the env override is a local escape hatch, not a remote design. | needs a replacement | #937 |
 ## 7. Durable state
 Locks, leases, session state, and the control-plane database live in the operator's home
 directory and are keyed on local PIDs.
 | ID | Anchor | Assumes today | Observes remotely | Class | Owner |
 | -- | ------ | ------------- | ----------------- | ----- | ----- |
 | S1 | `issue_lock_store.py:26` | `DEFAULT_LOCK_DIR = ~/.cache/gitea-tools/issue-locks` — per-issue lock files under one user's home. | A shared endpoint has no single operator home; per-user paths make locks invisible across sessions and hosts. | needs a replacement | #937 |
 | S2 | `issue_lock_store.py:83` | `session_pointer_path()` names the session pointer file `session-<os.getpid()>.json`. | Many sessions share one PID on a remote server, so the pointer collapses to a single slot and sessions overwrite each other. | cannot be remote | #937 |
 | S3 | `issue_lock_store.py:98` | `is_process_alive(pid)` decides lock liveness by probing the local process table. | A PID recorded by one host is meaningless on another, and may coincidentally match a live unrelated process. | cannot be remote | #937 |
 | S4 | `issue_lock_store.py:213` | Lock records stamp `session_pid` and `pid` from `os.getpid()`. | The recorded identity no longer distinguishes sessions; ownership checks silently pass for the wrong caller. | needs a replacement | #937 |
 | S5 | `mcp_session_state.py:27` | `DEFAULT_STATE_DIR = ~/.cache/gitea-tools/session-state`, mode `0o700`. | Same home-directory coupling as S1, for review decision locks and workflow proofs. | needs a replacement | #937 |
 | S6 | `mcp_session_state.py:559` | Session bodies stamp `session_pid` and `writer_pid` from `os.getpid()` (`mcp_session_state.py:560`). | Writer attribution collapses across concurrent sessions in one process. | needs a replacement | #937 |
 | S7 | `control_plane_db.py:47` | `DEFAULT_DB_PATH = ~/.cache/gitea-tools/control-plane/control_plane.sqlite3`. | A per-user SQLite file is not reachable by, or safe for, multiple remote sessions or multiple hosts. | needs a replacement | #937 |
 | S8 | `control_plane_db.py:386` | `sqlite3.connect(self.db_path, timeout=30)` — single-writer file locking tuned for one local process. | SQLite's write lock does not extend across hosts and degrades sharply under real concurrency; the store needs a concurrency-safe backend. | needs a replacement | #937 |
 | S9 | `control_plane_db.py:1145` | Lease rows record `owner_pid` defaulting to `os.getpid()` (also `control_plane_db.py:2039`). | PID-keyed lease ownership is unusable across hosts and ambiguous within one shared process. | cannot be remote | #937 |
 | S10 | `mcp_daemon_guard.py:53` | `_DEFAULT_SESSION_STATE_DIR` is pinned once at transport bind so a later `GITEA_MCP_SESSION_STATE_DIR` change cannot manufacture a second authority domain (#695 AC2). | The single-authority-domain invariant is exactly right and must be preserved; only its backing location needs to move. | needs a seam | #937 |
 | S11 | `gitea_mcp_server.py:11875` | Reviewer-lease reclaim reads `owner_pid_alive` from the lease freshness record to decide whether an owner is dead. | Consumes S3/S9; a false "owner alive" or "owner dead" here reclaims or refuses a live lease. This is the highest-consequence consumer of PID liveness. | cannot be remote | #937 |
 ---
 ## Summary
 ### Entries per category
 | Category | Entries |
 | -------- | ------: |
 | 1. Transport bind | 9 |
 | 2. Launch provenance | 12 |
 | 3. Role binding | 7 |
 | 4. Credentials | 6 |
 | 5. Runtime freshness | 6 |
 | 6. Local filesystem | 11 |
 | 7. Durable state | 11 |
 | **Total** | **62** |
 No category is empty, so no "this category has no coupling" justification is required.
 ### Entries per classification
 | Classification | Entries |
 | -------------- | ------: |
 | portable as written | 5 |
 | needs a seam | 16 |
 | needs a replacement | 26 |
 | cannot be remote | 15 |
 | **Total** | **62** |
 ### Category × classification
 | Category | portable | seam | replacement | cannot | Total |
 | -------- | -------: | ---: | ----------: | -----: | ----: |
 | 1. Transport bind | 4 | 4 | 1 | 0 | 9 |
 | 2. Launch provenance | 0 | 2 | 5 | 5 | 12 |
 | 3. Role binding | 0 | 3 | 3 | 1 | 7 |
 | 4. Credentials | 1 | 2 | 2 | 1 | 6 |
 | 5. Runtime freshness | 0 | 2 | 2 | 2 | 6 |
 | 6. Local filesystem | 0 | 2 | 7 | 2 | 11 |
 | 7. Durable state | 0 | 1 | 6 | 4 | 11 |
 | **Total** | **5** | **16** | **26** | **15** | **62** |
 ### Entries per epic child
 Every child from 2 through 10 is named by at least one entry, and every entry names exactly
 one child.
 | Child | Issue | Title | Entries | IDs |
 | ----: | ----- | ----- | ------: | --- |
 | 2 | #931 | Transport-neutral bind seam | 9 | T1–T9 |
 | 3 | #932 | Per-request principal resolution | 7 | R1–R7 |
 | 4 | #933 | Server-side credential provider | 6 | C1–C6 |
 | 5 | #934 | Remote-session provenance | 9 | P1–P9 |
 | 6 | #935 | Redefined master-parity gate | 6 | F1–F6 |
 | 7 | #936 | Local-filesystem vs remotable tool split | 8 | L1–L8 |
 | 8 | #937 | Concurrency-safe session, lock, and lease state | 13 | L10, L11, S1–S11 |
 | 9 | #938 | Authenticated remote MCP endpoint | 2 | P10, L9 |
 | 10 | #939 | Dual-run cutover and rollback | 2 | P11, P12 |
 | | | **Total** | **62** | |
 ## Notes for downstream children
 - **The three highest-risk entries are P5, F2, and S11.** Each is a guard that does not
  merely stop working remotely — it inverts. P5 turns concurrency into a reported fault,
  F2 returns a verdict computed from terms that no longer mean anything, and S11 reclaims
  or refuses leases on a PID-liveness answer that is wrong rather than unknown. A gate that
  fails open while still reporting green is worse than one that fails to start.
 - **T4, T5, T7, T8, and C5 are the portable core.** They show the target shape: predicates
  over injected inputs, with no reference to the host, the process table, or the operator's
  disk.
 - **The keychain seam already exists** at C2 (`resolve_token`'s injectable `keychain_lookup`).
  #933 should widen that seam rather than introduce a parallel path, and must remember C4 —
  the guard protecting the old mechanism has to be re-pointed, or the protection lapses
  silently when the mechanism is replaced.
 - **`branches/` appears as a validation rule in at least two independent places** (L4, L5).
  Path-substring conventions tend to have more copies than expected; #936 should re-grep
  rather than trust this list to be exhaustive for that specific pattern.
@@ -1169,10 +1169,57 @@ def server_command():
    return python, [os.path.join(root, "mcp_server.py")]
 RECOGNIZED_GITEA_ENV_KEYS = frozenset({
    "GITEA_MCP_CONFIG",
    "GITEA_MCP_PROFILE",
    "GITEA_PROFILE_NAME",
    "GITEA_SERVICE",
    "GITEA_EXECUTION_ROLE",
    "GITEA_CLIENT_MANAGED",
    "GITEA_MCP_CLIENT_MANAGED",
    "GITEA_SERVER_PROVENANCE",
    "GITEA_AUTHOR_WORKTREE",
    "GITEA_ACTIVE_WORKTREE",
    "GITEA_DISABLE_KEYCHAIN",
    "GITEA_CONTROL_PLANE_DB",
    "GITEA_DB_PATH",
    "GITEA_LOG_LEVEL",
    "GITEA_DEBUG",
    "GITEA_HMAC_SECRET",
    "GITEA_IRRECOVERABLE_HMAC_SECRET",
    "GITEA_FORCE_MCP_RUNTIME_CHECK",
    "GITEA_FORCE_CLIENT_MANAGED",
 })
 RECOGNIZED_GITEA_ENV_PREFIXES = (
    "GITEA_TOKEN_",
    "GITEA_PASS_",
    "GITEA_USER_",
    "GITEA_URL_",
    "GITEA_HOST_",
    "GITEA_REMOTE_",
    "GITEA_HTTP_HEADER_",
 )
 def get_unconsumed_gitea_env_overrides(env=None) -> dict[str, str]:
    """Find unsupported GITEA_* env vars present in *env* (defaults to os.environ)."""
    target = os.environ if env is None else env
    unconsumed = {}
    for key, value in target.items():
        if key.startswith("GITEA_"):
            if key in RECOGNIZED_GITEA_ENV_KEYS:
                continue
            if any(key.startswith(p) for p in RECOGNIZED_GITEA_ENV_PREFIXES):
                continue
            unconsumed[key] = str(value)
    return unconsumed
 def launcher_entry(profile_name, config_path=None):
    """Return a thin MCP launcher entry for *profile_name*.
-    Contains only command/args and the two GITEA_MCP_* env vars — never a token
+    Contains command/args and the GITEA_MCP_* / GITEA_CLIENT_MANAGED env vars — never a token
    or password. Suitable for Claude / Gemini / Codex ``mcpServers`` blocks.
    """
    command, args = server_command()
@@ -1183,11 +1230,13 @@ def launcher_entry(profile_name, config_path=None):
            "env": {
                "GITEA_MCP_CONFIG": config_path or DEFAULT_CONFIG_PATH,
                "GITEA_MCP_PROFILE": profile_name,
                "GITEA_CLIENT_MANAGED": "1",
            },
        }
    }
 def keychain_set(item_id, token, account=None, runner=subprocess.run):
    """Store *token* in the macOS keychain under service *item_id*.
@@ -24,8 +24,6 @@ import subprocess
 import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Any
 import hashlib
@@ -2260,12 +2258,7 @@ def _seed_session_context(
        expected_username=expected,
        source=source,
        canonical_repository_root=canonical_root_pin,
        cohort_id=_COHORT_ID,
        startup_sha=_STARTUP_PARITY.get("startup_head"),
        endpoint=host or (profile.get("base_url") or "").strip() or None,
        config_fingerprint=_CONFIG_FINGERPRINT,
    )
 import issue_work_duplicate_gate  # noqa: E402
 import issue_workflow_labels  # noqa: E402
 import terminal_pr_label_cleanup  # noqa: E402  # #780 status:pr-open terminal rule
@@ -2294,11 +2287,6 @@ import stable_control_runtime  # noqa: E402
 # master has advanced past the running code and fail closed until restart.
 # Read-only operations are never blocked by staleness.
 _STARTUP_PARITY = master_parity_gate.capture_startup_parity(PROJECT_ROOT)
 _COHORT_ID: str = f"cohort-p{os.getpid()}-{_STARTUP_PARITY.get('startup_head') or 'unknown'}"
 _CONFIG_FINGERPRINT: str = hashlib.sha256(
    (PROJECT_ROOT + str(_STARTUP_PARITY.get("startup_head"))).encode("utf-8")
 ).hexdigest()[:16]
 # Stable-control runtime facts (#615): which runtime this process serves from.
 # These are the *immutable* facts -- process root, branch, head, checkout-ness --
@@ -14209,10 +14197,8 @@ def _current_master_parity() -> dict:
    current_head = master_parity_gate.read_git_head(PROJECT_ROOT)
    live_head = master_parity_gate.read_remote_master_head(
        PROJECT_ROOT, remote=_git_default_remote_name(PROJECT_ROOT))
    bound_context = session_ctx.get_session_context()
    return master_parity_gate.assess_master_parity(
-        _STARTUP_PARITY, current_head, live_remote_head=live_head, bound_cohort=bound_context)
+        _STARTUP_PARITY, current_head, live_remote_head=live_head)
 def _current_runtime_mode_report(refresh: bool = False) -> dict:
@@ -14599,6 +14585,56 @@ def _session_context_mutation_block(
    return blocked
 def _is_client_managed_process() -> bool:
    """Check whether the current MCP server process has client-managed launch provenance (#686)."""
    val = (
        os.environ.get("GITEA_CLIENT_MANAGED")
        or os.environ.get("GITEA_MCP_CLIENT_MANAGED")
        or os.environ.get("GITEA_SERVER_PROVENANCE")
        or os.environ.get("GITEA_FORCE_CLIENT_MANAGED")
        or ""
    ).strip().lower()
    if val in ("0", "false", "no", "manual", "manual_launch"):
        return False
    if val in ("1", "true", "yes", "client_managed"):
        return True
    # A terminal launch has an active TTY on stdin
    try:
        if sys.stdin and sys.stdin.isatty():
            return False
    except Exception:
        pass
    # Standard client launch or test runner with stdio pipe and profile env
    if "GITEA_MCP_CONFIG" in os.environ or "GITEA_MCP_PROFILE" in os.environ or "GITEA_PROFILE_NAME" in os.environ:
        return True
    return False
 def _provenance_mutation_block(**extra_fields) -> dict | None:
    """Refuse mutating tool calls on processes lacking client-managed launch provenance (#686)."""
    if _is_client_managed_process():
        return None
    unconsumed = gitea_config.get_unconsumed_gitea_env_overrides()
    blocked = {
        "success": False,
        "performed": False,
        "blocker_kind": "unsupported_manual_launch",
        "reasons": [
            "mutation denied: server process was launched manually from a terminal without client-managed provenance (fail closed). Manually launched mcp_server.py processes cannot receive IDE stdio or serve workflow mutations."
        ],
        "exact_next_action": "BLOCKED + RECONNECT: Reconnect the IDE/client-managed MCP server namespace instead of an ad hoc terminal launch. Hand-launched processes and mcp_config.json hand-edits are classified as workflow contamination.",
        "provenance": "manual_launch",
        "unconsumed_gitea_env": unconsumed,
    }
    blocked.update(extra_fields)
    return blocked
 def _profile_permission_block(required_operation: str, **extra_fields) -> dict | None:
    """Structured operation-gate denial for gated tools (#69, #142, #897).
@@ -14615,6 +14651,10 @@ def _profile_permission_block(required_operation: str, **extra_fields) -> dict |
    # #714: evaluate active profile only — never auto-switch.
    _ensure_matching_profile(required_operation, req_role, extra_fields.get("remote"))
    prov_block = _provenance_mutation_block(**extra_fields)
    if prov_block is not None:
        return prov_block
    reasons = _profile_operation_gate(required_operation)
    if reasons:
        return _build_operation_gate_refusal(
@@ -14648,6 +14688,10 @@ def _namespace_mutation_block(mutation_task: str, **extra_fields) -> dict | None
    # #714: evaluate active profile only — never auto-switch.
    _ensure_matching_profile(required_permission, required_role, extra_fields.get("remote"))
    prov_block = _provenance_mutation_block(**extra_fields)
    if prov_block is not None:
        return prov_block
    try:
        profile = get_profile()
    except Exception as exc:
@@ -18095,6 +18139,9 @@ def gitea_get_runtime_context(
        source="gitea_get_runtime_context",
    )
    is_client_managed = _is_client_managed_process()
    unconsumed_env = gitea_config.get_unconsumed_gitea_env_overrides()
    result = {
        "active_profile": profile["profile_name"],
        "authenticated_username": username,
@@ -18111,6 +18158,9 @@ def gitea_get_runtime_context(
        "review_merge_blocked_reasons": blocked_reasons,
        "suggested_fix": suggested_fix,
        "safe_next_action": safe_next_action,
        "server_provenance": "client_managed" if is_client_managed else "manual_launch",
        "is_client_managed": is_client_managed,
        "unconsumed_gitea_env": unconsumed_env,
        "preflight_ready": preflight["preflight_ready"],
        "preflight_block_reasons": preflight["preflight_block_reasons"],
        "preflight_workspace": preflight.get("preflight_workspace"),
@@ -18124,6 +18174,13 @@ def gitea_get_runtime_context(
            PROJECT_ROOT),
    }
    if not is_client_managed:
        result["safe_next_action"] = (
            "BLOCKED + RECONNECT: Serving process lacks client-managed launch provenance (manual launch). "
            "Reconnect the IDE/client-managed MCP server namespace instead of an ad hoc terminal launch."
        )
    # #702: read-only visibility into the inherited GITEA_ACTIVE_WORKTREE
    # binding; recovery itself runs during capability resolution.
    try:
@@ -20581,7 +20638,9 @@ def _check_mcp_runtimes_diagnostics(task: str, matching_profiles: list[str]) ->
    self_pid = os.getpid()
    self_stale = False
-    running_profiles = {}
+    all_profile_procs: dict[str, list[dict]] = {}
    unsupported_env_found = set()
    for line in proc.stdout.splitlines()[1:]:
        line = line.strip()
        if not line or "mcp_server.py" not in line:
@@ -20613,16 +20672,55 @@ def _check_mcp_runtimes_diagnostics(task: str, matching_profiles: list[str]) ->
        if match:
            profile = match.group(1)
        is_client_managed = bool(
            re.search(r'\bGITEA_CLIENT_MANAGED=(1|true|yes|client_managed)\b', env_out, re.IGNORECASE)
            or re.search(r'\bGITEA_MCP_CLIENT_MANAGED=(1|true|yes|client_managed)\b', env_out, re.IGNORECASE)
            or re.search(r'\bGITEA_SERVER_PROVENANCE=client_managed\b', env_out, re.IGNORECASE)
        )
        for env_match in re.finditer(r'\b(GITEA_[A-Z0-9_]+)=([^\s]+)', env_out):
            k, v = env_match.group(1), env_match.group(2)
            if k not in gitea_config.RECOGNIZED_GITEA_ENV_KEYS and not any(k.startswith(p) for p in gitea_config.RECOGNIZED_GITEA_ENV_PREFIXES):
                unsupported_env_found.add(f"{k}={v}")
        is_stale = (start_time < code_mtime) or git_stale
        if pid == self_pid and is_stale:
            self_stale = True
-        if profile not in running_profiles or start_time > running_profiles[profile]["start_time"]:
+        proc_info = {
-            running_profiles[profile] = {
+            "pid": pid,
-                "pid": pid,
+            "start_time": start_time,
-                "start_time": start_time,
+            "is_stale": is_stale,
-                "is_stale": is_stale
+            "is_client_managed": is_client_managed,
-            }
+        }
        if profile not in all_profile_procs:
            all_profile_procs[profile] = []
        all_profile_procs[profile].append(proc_info)
    running_profiles = {}
    for profile, procs in all_profile_procs.items():
        if len(procs) > 1:
            pids_str = ", ".join(str(p["pid"]) for p in procs)
            reasons.append(
                f"stale-runtime: Duplicate MCP server process(es) detected for profile '{profile}' (PIDs: {pids_str}). "
                "Manual or duplicate launches defeat staleness detection and cannot receive client stdio."
            )
        client_procs = [p for p in procs if p["is_client_managed"]]
        if client_procs:
            client_procs.sort(key=lambda p: p["start_time"], reverse=True)
            running_profiles[profile] = client_procs[0]
        else:
            pids_str = ", ".join(str(p["pid"]) for p in procs)
            reasons.append(
                f"stale-runtime: Manually launched MCP process(es) detected without client-managed provenance for profile '{profile}' (PIDs: {pids_str}). "
                "Manual launches cannot serve client stdio and are ignored for runtime freshness."
            )
    if unsupported_env_found:
        reasons.append(
            f"unsupported-env: Unsupported GITEA_* environment variable override(s) detected: {', '.join(sorted(unsupported_env_found))}. "
            "Unknown env overrides are unsupported."
        )
    if self_stale:
        # #685: report-only — no config utime, no thread, no os._exit.
@@ -20657,6 +20755,7 @@ def _check_mcp_runtimes_diagnostics(task: str, matching_profiles: list[str]) ->
    return reasons
@mcp.tool()
 def gitea_resolve_task_capability(
    task: str,
@@ -183,7 +183,6 @@ def assess_master_parity(
    startup: dict | None,
    current_head: str | None,
    live_remote_head: str | None = None,
    bound_cohort: dict | None = None,
 ) -> dict:
    """Compare the startup baseline against the current on-disk ``HEAD``.
@@ -193,8 +192,7 @@ def assess_master_parity(
      could not be determined, which is not treated as stale).
    - ``stale``        -- the on-disk master has definitively advanced past the
      running process.
-    - ``restart_required`` -- ``stale``, ``live_stale``, or ``cohort_stale``; the
+    - ``restart_required`` -- ``stale`` or ``live_stale``; the recovery action.
      recovery action.
    - ``determinable`` -- whether both local HEADs were known well enough to
      compare.
    - ``startup_head`` / ``current_head`` / ``reasons``.
@@ -211,69 +209,24 @@ def assess_master_parity(
    - ``live_known`` -- whether the live remote target was resolved.
    - ``live_stale`` -- the live remote master has advanced past the running
      process (daemon is behind live master) even if local parity is green.
-    - ``bound_cohort`` -- metadata describing the bound MCP cohort.
+    - ``mutation_safe`` -- the daemon code, local checkout, and live remote
-    - ``cohort_parity_match`` -- whether bound cohort startup SHA matches parity.
+      target all agree; the only state in which a mutation may rely on parity.
    - ``cohort_stale`` -- bound cohort startup SHA is stale relative to parity.
    - ``mutation_safe`` -- the daemon code, local checkout, live remote target,
      and bound cohort all agree; the only state in which a mutation may rely
      on parity.
    """
    startup_head = (startup or {}).get("startup_head")
    reasons: list[str] = []
    cohort_info: dict | None = None
    cohort_parity_match = True
    cohort_stale = False
    if bound_cohort:
        c_id = str(bound_cohort.get("cohort_id") or "").strip() or None
        c_pid = bound_cohort.get("pid")
        c_sha = str(
            bound_cohort.get("startup_sha")
            or bound_cohort.get("git_head")
            or ""
        ).strip() or None
        c_endpoint = str(bound_cohort.get("endpoint") or "").strip() or None
        c_fingerprint = str(
            bound_cohort.get("config_fingerprint") or ""
        ).strip() or None
        cohort_info = {
            "cohort_id": c_id,
            "pid": c_pid,
            "startup_sha": c_sha,
            "endpoint": c_endpoint,
            "config_fingerprint": c_fingerprint,
        }
        parity_ref = live_remote_head or current_head or startup_head
        if c_sha and parity_ref:
            if c_sha.lower() != parity_ref.lower():
                cohort_parity_match = False
                cohort_stale = True
                reasons.append(
                    f"bound cohort startup SHA '{_short(c_sha)}' does not "
                    f"match authoritative parity SHA '{_short(parity_ref)}' "
                    "(stale cohort refused)"
                )
    if startup_head is None:
        reasons.append(
            "startup commit was not captured; code parity cannot be enforced")
        return _result(True, False, False, startup_head, current_head,
-                       live_remote_head, False, reasons,
+                       live_remote_head, False, reasons)
                       bound_cohort=cohort_info,
                       cohort_parity_match=cohort_parity_match,
                       cohort_stale=cohort_stale)
    if current_head is None:
        reasons.append(
            "current workspace HEAD could not be read; code parity cannot be "
            "enforced")
        return _result(True, False, False, startup_head, current_head,
-                       live_remote_head, False, reasons,
+                       live_remote_head, False, reasons)
                       bound_cohort=cohort_info,
                       cohort_parity_match=cohort_parity_match,
                       cohort_stale=cohort_stale)
    local_in_parity = startup_head == current_head
    local_stale = not local_in_parity
@@ -293,28 +246,18 @@ def assess_master_parity(
    return _result(
        local_in_parity, local_stale, True, startup_head, current_head,
-        live_remote_head, live_stale, reasons,
+        live_remote_head, live_stale, reasons)
        bound_cohort=cohort_info,
        cohort_parity_match=cohort_parity_match,
        cohort_stale=cohort_stale)
 def _result(in_parity, stale, determinable, startup_head, current_head,
-            live_remote_head, live_stale, reasons, bound_cohort=None,
+            live_remote_head, live_stale, reasons):
            cohort_parity_match=True, cohort_stale=False):
    live_known = live_remote_head is not None
    mutation_safe = (
-        determinable
+        determinable and in_parity and live_known and not live_stale)
        and in_parity
        and live_known
        and not live_stale
        and cohort_parity_match
        and not cohort_stale
    )
    return {
        "in_parity": in_parity,
        "stale": stale,
-        "restart_required": stale or live_stale or cohort_stale,
+        "restart_required": stale or live_stale,
        "determinable": determinable,
        "startup_head": startup_head,
        "current_head": current_head,
@@ -324,15 +267,11 @@ def _result(in_parity, stale, determinable, startup_head, current_head,
        "live_remote_head": live_remote_head,
        "live_known": live_known,
        "live_stale": live_stale,
        "cohort_parity_match": cohort_parity_match,
        "cohort_stale": cohort_stale,
        "bound_cohort": bound_cohort,
        "mutation_safe": mutation_safe,
        "reasons": list(reasons),
    }
 def gate_disabled() -> bool:
    """Whether the parity gate is disabled by env escape hatch."""
    return bool((os.environ.get(ENV_DISABLE) or "").strip())
@@ -104,8 +104,6 @@ def classify_namespace_probe(
    profile: str | None = None,
    configured: bool = True,
    probe_source: str | None = None,
    expected_parity_sha: str | None = None,
    bound_cohort: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
    """Classify whether a required tool is callable through a live namespace.
@@ -137,50 +135,20 @@ def classify_namespace_probe(
        else:
            error_type = "namespace_call_failed"
    # Extract cohort metadata
    cohort_meta = bound_cohort or probe.get("cohort") or probe.get("bound_cohort") or {}
    cohort_id = str(
        cohort_meta.get("cohort_id") or probe.get("cohort_id") or ""
    ).strip() or None
    startup_sha = str(
        cohort_meta.get("startup_sha")
        or cohort_meta.get("git_head")
        or probe.get("startup_sha")
        or probe.get("git_head")
        or ""
    ).strip() or None
    endpoint = str(
        cohort_meta.get("endpoint") or probe.get("endpoint") or ""
    ).strip() or None
    config_fingerprint = str(
        cohort_meta.get("config_fingerprint") or probe.get("config_fingerprint") or ""
    ).strip() or None
    expected_sha = (expected_parity_sha or "").strip().lower() or None
    stale_cohort = False
    if expected_sha and startup_sha:
        if startup_sha.lower() != expected_sha:
            stale_cohort = True
            error_type = "stale_cohort_refused"
    if not configured:
        error_type = "namespace_not_configured"
    elif registered is False:
        error_type = "tool_missing"
    elif not probe_result:
        error_type = "live_probe_missing"
    elif stale_cohort:
        error_type = "stale_cohort_refused"
    elif not probe_success and not error_type:
        error_type = "namespace_call_failed"
-    callable_live = bool(configured and probe_result and probe_success and not stale_cohort)
+    callable_live = bool(configured and probe_result and probe_success)
    # Probe-path health (spawn or client). IDE-proven only for client path.
    healthy = bool(configured and registered is not False and callable_live)
    ide_namespace_proven = bool(healthy and source == PROBE_SOURCE_CLIENT)
-    process_pid = process.get("pid") if isinstance(process, dict) else (
+    process_pid = process.get("pid") if isinstance(process, dict) else None
        cohort_meta.get("pid") if isinstance(cohort_meta, dict) else None
    )
    profile_name = profile or (
        process.get("profile") if isinstance(process, dict) else None
    )
@@ -193,13 +161,7 @@ def classify_namespace_probe(
        reasons.append(
            f"Required tool '{tool}' is not registered in namespace '{ns}'."
        )
-    if error_type == "stale_cohort_refused":
+    if error_type == "live_probe_missing":
        reasons.append(
            f"Bound cohort startup SHA '{startup_sha[:12] if startup_sha else 'unknown'}' "
            f"does not match expected parity SHA '{expected_sha[:12] if expected_sha else 'unknown'}' "
            "(stale cohort refused)."
        )
    elif error_type == "live_probe_missing":
        reasons.append(
            f"No live client invocation proof was supplied for '{ns}.{tool}'."
        )
@@ -263,6 +225,16 @@ def classify_namespace_probe(
        # on bad data without treating success as IDE proof).
        blocks = namespace_health_blocks_task("merge_pr", healthy)
    import gitea_config
    raw_env = process.get("env") if isinstance(process, dict) else None
    unconsumed_env = gitea_config.get_unconsumed_gitea_env_overrides(raw_env)
    is_client_managed = bool(
        env_summary.get("GITEA_CLIENT_MANAGED") in ("1", "true", "yes", "client_managed")
        or env_summary.get("GITEA_MCP_CLIENT_MANAGED") in ("1", "true", "yes", "client_managed")
        or env_summary.get("GITEA_SERVER_PROVENANCE") == "client_managed"
    )
    provenance = "client_managed" if is_client_managed else "manual_launch"
    return {
        "success": healthy,
        "healthy": healthy,
@@ -278,6 +250,9 @@ def classify_namespace_probe(
        "error_message": error_message or None,
        "reasons": reasons,
        "remediation": remediation,
        "provenance": provenance,
        "is_client_managed": is_client_managed,
        "unconsumed_gitea_env": unconsumed_env,
        "diagnostics": {
            "namespace": ns,
            "required_tool": tool,
@@ -286,10 +261,9 @@ def classify_namespace_probe(
            "env": env_summary,
            "config_path": config_path,
            "probe_source": source,
-            "cohort_id": cohort_id,
+            "provenance": provenance,
-            "startup_sha": startup_sha,
+            "is_client_managed": is_client_managed,
-            "endpoint": endpoint,
+            "unconsumed_gitea_env": unconsumed_env,
            "config_fingerprint": config_fingerprint,
        },
        "blocks_merge_workflow": blocks,
    }
@@ -151,16 +151,12 @@ class RestartCompletionProof:
    unresolved_count: int
    skipped_count: int
    note: str
    binding_unchanged: bool = False
    prior_reconcile_id: str | None = None
    def as_dict(self) -> dict[str, Any]:
        return {
            "schema_version": self.schema_version,
            "reconcile_version": self.reconcile_version,
            "reconcile_id": self.reconcile_id,
            "binding_unchanged": self.binding_unchanged,
            "prior_reconcile_id": self.prior_reconcile_id,
            "started_at": self.started_at,
            "finished_at": self.finished_at,
            "boot_head_sha": self.boot_head_sha,
@@ -177,7 +173,6 @@ class RestartCompletionProof:
            "skipped_count": self.skipped_count,
            "note": self.note,
            "links": {
                "umbrella": 655,
                "vision": 652,
                "roadmap": 653,
@@ -364,9 +359,7 @@ def reconcile_after_restart(
    now: datetime | None = None,
    mode: str = MODE_LOG_ONLY,
    reconcile_id: str | None = None,
    prior_reconcile_id: str | None = None,
 ) -> RestartCompletionProof:
    """Classify a post-restart inventory into a completion proof (#662).
    Parameters
@@ -757,26 +750,12 @@ def reconcile_after_restart(
        f"Mode={mode_norm}."
    )
    prior_id = str(
        prior_reconcile_id
        or inventory.get("prior_reconcile_id")
        or ""
    ).strip() or None
    target_rec_id = str(reconcile_id or "").strip() or None
    binding_unchanged = bool(
        prior_id and target_rec_id and target_rec_id == prior_id
    )
    final_reconcile_id = target_rec_id or f"reconcile-{uuid4().hex[:12]}"
    return RestartCompletionProof(
        schema_version=SCHEMA_VERSION,
        reconcile_version=RECONCILE_VERSION,
-        reconcile_id=final_reconcile_id,
+        reconcile_id=(reconcile_id or f"reconcile-{uuid4().hex[:12]}"),
        binding_unchanged=binding_unchanged,
        prior_reconcile_id=prior_id,
        started_at=_ts(started),
        finished_at=_ts(finished),
        boot_head_sha=(
            str(inventory.get("boot_head_sha")).strip()
            if inventory.get("boot_head_sha")
@@ -33,10 +33,6 @@ class _SessionContext:
    source: str
    pid: int
    canonical_repository_root: str | None = None
    cohort_id: str | None = None
    startup_sha: str | None = None
    endpoint: str | None = None
    config_fingerprint: str | None = None
    def as_dict(self) -> dict[str, Any]:
        return {
@@ -51,14 +47,9 @@ class _SessionContext:
            "source": self.source,
            "pid": self.pid,
            "canonical_repository_root": self.canonical_repository_root,
            "cohort_id": self.cohort_id,
            "startup_sha": self.startup_sha,
            "endpoint": self.endpoint,
            "config_fingerprint": self.config_fingerprint,
        }
 # Process-local only — never a shared file (same rationale as mutation authority).
 # The frozen value prevents partial mutation, while the lock makes first-bind and
 # sanctioned rebind atomic across concurrent MCP calls.
@@ -81,13 +72,6 @@ def _reset_session_context_for_testing() -> None:
        _SESSION_CONTEXT = None
 def clear_session_context() -> None:
    """Purge process-session context and cohort bindings on disconnect."""
    global _SESSION_CONTEXT
    with _SESSION_CONTEXT_LOCK:
        _SESSION_CONTEXT = None
 def get_session_context() -> dict[str, Any] | None:
    """Return a detached snapshot of the bound context, or None if unbound."""
    with _SESSION_CONTEXT_LOCK:
@@ -162,10 +146,6 @@ def bind_session_context(
    expected_username: str | None = None,
    source: str = "bind",
    canonical_repository_root: str | None = None,
    cohort_id: str | None = None,
    startup_sha: str | None = None,
    endpoint: str | None = None,
    config_fingerprint: str | None = None,
 ) -> dict[str, Any]:
    """Atomically bind/re-bind context (the explicit activation path)."""
    with _SESSION_CONTEXT_LOCK:
@@ -180,10 +160,6 @@ def bind_session_context(
            expected_username=expected_username,
            source=source,
            canonical_repository_root=canonical_repository_root,
            cohort_id=cohort_id,
            startup_sha=startup_sha,
            endpoint=endpoint,
            config_fingerprint=config_fingerprint,
        )
@@ -199,10 +175,6 @@ def _bind_session_context_unlocked(
    expected_username: str | None,
    source: str,
    canonical_repository_root: str | None = None,
    cohort_id: str | None = None,
    startup_sha: str | None = None,
    endpoint: str | None = None,
    config_fingerprint: str | None = None,
 ) -> dict[str, Any]:
    """Store a complete immutable context while the caller holds the lock."""
    global _SESSION_CONTEXT
@@ -218,10 +190,6 @@ def _bind_session_context_unlocked(
        source=source,
        pid=os.getpid(),
        canonical_repository_root=(canonical_repository_root or "").strip() or None,
        cohort_id=(cohort_id or "").strip() or None,
        startup_sha=(startup_sha or "").strip() or None,
        endpoint=(endpoint or "").strip() or None,
        config_fingerprint=(config_fingerprint or "").strip() or None,
    )
    return _SESSION_CONTEXT.as_dict()
@@ -238,10 +206,6 @@ def seed_session_context_if_unbound(
    expected_username: str | None = None,
    source: str = "seed",
    canonical_repository_root: str | None = None,
    cohort_id: str | None = None,
    startup_sha: str | None = None,
    endpoint: str | None = None,
    config_fingerprint: str | None = None,
 ) -> dict[str, Any]:
    """Atomically bind only when this process has no current context.
@@ -263,15 +227,10 @@ def seed_session_context_if_unbound(
                expected_username=expected_username,
                source=source,
                canonical_repository_root=canonical_repository_root,
                cohort_id=cohort_id,
                startup_sha=startup_sha,
                endpoint=endpoint,
                config_fingerprint=config_fingerprint,
            )
        return _SESSION_CONTEXT.as_dict()
 def assess_session_context(
    *,
    profile_name: str | None,
@@ -627,10 +586,6 @@ def mutation_context_audit_fields(
            "session_identity": None,
            "session_repository": None,
            "session_org": None,
            "session_cohort_id": None,
            "session_startup_sha": None,
            "session_endpoint": None,
            "session_config_fingerprint": None,
        }
    return {
        "session_context_bound": True,
@@ -643,14 +598,9 @@ def mutation_context_audit_fields(
        "session_role_kind": data.get("role_kind"),
        "session_context_source": data.get("source"),
        "session_canonical_repository_root": data.get("canonical_repository_root"),
        "session_cohort_id": data.get("cohort_id"),
        "session_startup_sha": data.get("startup_sha"),
        "session_endpoint": data.get("endpoint"),
        "session_config_fingerprint": data.get("config_fingerprint"),
    }
 def _assessment(
    proven: bool, reasons: list[str], ctx: Mapping[str, Any] | None
 ) -> dict[str, Any]:
@@ -44,6 +44,8 @@ def _reset_mutation_authority(monkeypatch):
    ]:
        monkeypatch.delenv(env_key, raising=False)
    monkeypatch.setenv("GITEA_CLIENT_MANAGED", "1")
    # Isolate durable session-state files so tests never share host cache (#559).
    import tempfile
@@ -35,7 +35,7 @@ CONFIG = {
            ],
            "forbidden_operations": [],
            "execution_profile": "full-author",
-        "allowed_repositories": ["Example-Org/Example-Repo"],
+        "allowed_repositories": ["Scaled-Tech-Consulting/Gitea-Tools", "Example-Org/Example-Repo"],
        },
        "reviewer-no-commit": {
            "enabled": True,
@@ -50,7 +50,7 @@ CONFIG = {
                "gitea.repo.commit", "gitea.pr.create", "gitea.branch.push"
            ],
            "execution_profile": "reviewer-no-commit",
-        "allowed_repositories": ["Example-Org/Example-Repo"],
+        "allowed_repositories": ["Scaled-Tech-Consulting/Gitea-Tools", "Example-Org/Example-Repo"],
        },
    },
    "rules": {"allow_runtime_switching": False},
@@ -175,7 +175,7 @@ class TestLauncherSnippets(unittest.TestCase):
    def test_only_safe_keys_no_secrets(self):
        entry = gitea_config.launcher_entry("prgs", "/cfg/profiles.json")["gitea-tools"]
        self.assertEqual(set(entry), {"command", "args", "env"})
-        self.assertEqual(set(entry["env"]), {"GITEA_MCP_CONFIG", "GITEA_MCP_PROFILE"})
+        self.assertEqual(set(entry["env"]), {"GITEA_MCP_CONFIG", "GITEA_MCP_PROFILE", "GITEA_CLIENT_MANAGED"})
        self.assertEqual(entry["env"]["GITEA_MCP_PROFILE"], "prgs")
        blob = json.dumps(entry).lower()
        for word in ("token", "password", "secret"):
@@ -0,0 +1,139 @@
 """Tests for Issue #686: Detect and reject manually launched duplicate MCP role servers."""
 import os
 import unittest
 from unittest.mock import patch, MagicMock
 from datetime import datetime
 import gitea_config
 import gitea_mcp_server
 import mcp_namespace_health
 class TestIssue686ManualMcpProvenance(unittest.TestCase):
    def test_client_managed_process_detection(self):
        """Test _is_client_managed_process correctly detects provenance markers."""
        with patch.dict(os.environ, {"GITEA_CLIENT_MANAGED": "1"}, clear=True):
            self.assertTrue(gitea_mcp_server._is_client_managed_process())
        with patch.dict(os.environ, {"GITEA_MCP_CLIENT_MANAGED": "true"}, clear=True):
            self.assertTrue(gitea_mcp_server._is_client_managed_process())
        with patch.dict(os.environ, {"GITEA_SERVER_PROVENANCE": "client_managed"}, clear=True):
            self.assertTrue(gitea_mcp_server._is_client_managed_process())
        with patch.dict(os.environ, {"GITEA_CLIENT_MANAGED": "0"}, clear=True):
            self.assertFalse(gitea_mcp_server._is_client_managed_process())
    def test_unconsumed_gitea_env_overrides(self):
        """Test surfacing of unsupported GITEA_* env overrides (e.g. GITEA_DUMMY)."""
        env = {
            "GITEA_MCP_PROFILE": "prgs-author",
            "GITEA_CLIENT_MANAGED": "1",
            "GITEA_DUMMY": "2",
            "GITEA_UNKNOWN_FLAG": "abc",
        }
        unconsumed = gitea_config.get_unconsumed_gitea_env_overrides(env)
        self.assertIn("GITEA_DUMMY", unconsumed)
        self.assertEqual(unconsumed["GITEA_DUMMY"], "2")
        self.assertIn("GITEA_UNKNOWN_FLAG", unconsumed)
        self.assertNotIn("GITEA_MCP_PROFILE", unconsumed)
        self.assertNotIn("GITEA_CLIENT_MANAGED", unconsumed)
    def test_manual_server_mutation_fail_closed(self):
        """AC 2: Mutating tools on a server without client-managed provenance fail closed with a typed blocker."""
        with patch.dict(os.environ, {"GITEA_CLIENT_MANAGED": "0"}, clear=True):
            block = gitea_mcp_server._provenance_mutation_block(task="create_issue")
            self.assertIsNotNone(block)
            self.assertFalse(block["success"])
            self.assertFalse(block["performed"])
            self.assertEqual(block["blocker_kind"], "unsupported_manual_launch")
            self.assertEqual(block["provenance"], "manual_launch")
            self.assertTrue(any("mutation denied: server process was launched manually" in r for r in block["reasons"]))
            self.assertIn("BLOCKED + RECONNECT", block["exact_next_action"])
    def test_client_managed_server_mutation_passes_provenance_gate(self):
        """AC 3: Clean client-managed baseline passes the provenance gate."""
        with patch.dict(os.environ, {"GITEA_CLIENT_MANAGED": "1"}, clear=True):
            block = gitea_mcp_server._provenance_mutation_block(task="create_issue")
            self.assertIsNone(block)
    @patch("subprocess.run")
    @patch("os.path.getmtime")
    @patch("os.path.exists")
    @patch("os.getpid")
    def test_manual_duplicate_does_not_mask_stale_runtime(
        self, mock_getpid, mock_exists, mock_getmtime, mock_run
    ):
        """AC 1 & AC 3: Staleness detection ignores manual duplicates and reports stale supported runtimes."""
        mock_getpid.return_value = 12345
        mock_exists.return_value = True
        code_time = datetime(2026, 7, 8, 14, 0, 0)
        mock_getmtime.return_value = code_time.timestamp()
        # PID 12345: stale client-managed process (started at 13:00)
        # PID 99999: fresh manual duplicate process (started at 15:00, no GITEA_CLIENT_MANAGED)
        ps_output = (
            "  PID LSTART COMMAND\n"
            "12345 Wed Jul  8 13:00:00 2026 /path/to/python mcp_server.py\n"
            "99999 Wed Jul  8 15:00:00 2026 /path/to/python mcp_server.py\n"
        )
        mock_run_ps = MagicMock()
        mock_run_ps.stdout = ps_output
        mock_env_12345 = MagicMock()
        mock_env_12345.stdout = "GITEA_MCP_PROFILE=prgs-author GITEA_CLIENT_MANAGED=1"
        mock_env_99999 = MagicMock()
        mock_env_99999.stdout = "GITEA_MCP_PROFILE=prgs-author GITEA_DUMMY=2"
        def side_effect(args, **kwargs):
            if args[0] == "ps" and "eww" in args:
                pid = args[2]
                if pid == "12345":
                    return mock_env_12345
                elif pid == "99999":
                    return mock_env_99999
            elif args[0] == "ps":
                return mock_run_ps
            raise ValueError(f"Unexpected args: {args}")
        mock_run.side_effect = side_effect
        reasons = gitea_mcp_server._check_mcp_runtimes_diagnostics("create_issue", ["prgs-author"])
        # Manual duplicate process must be flagged
        self.assertTrue(any("Duplicate MCP server process(es) detected" in r for r in reasons))
        # Unsupported env override (GITEA_DUMMY=2) must be flagged
        self.assertTrue(any("unsupported-env: Unsupported GITEA_* environment variable override(s) detected: GITEA_DUMMY=2" in r for r in reasons))
        # Stale runtime must NOT be masked by fresh manual process 99999!
        self.assertTrue(any("All matching profiles for task 'create_issue' (['prgs-author']) are running but stale" in r for r in reasons))
    def test_namespace_health_classification_includes_provenance(self):
        """AC 1 & 4: mcp_namespace_health diagnostics include provenance and unconsumed_gitea_env."""
        process = {
            "pid": 5555,
            "profile": "prgs-author",
            "env": {
                "GITEA_MCP_PROFILE": "prgs-author",
                "GITEA_DUMMY": "99",
            },
        }
        res = mcp_namespace_health.classify_namespace_probe(
            "gitea-author",
            configured=True,
            registered_tools=["gitea_whoami"],
            probe_result={"success": True},
            process=process,
            probe_source="client_namespace",
        )
        self.assertEqual(res["provenance"], "manual_launch")
        self.assertFalse(res["is_client_managed"])
        self.assertEqual(res["unconsumed_gitea_env"], {"GITEA_DUMMY": "99"})
        self.assertEqual(res["diagnostics"]["provenance"], "manual_launch")
 if __name__ == "__main__":
    unittest.main()
@@ -1,253 +0,0 @@
 """Tests for Issue #689: Deterministic MCP namespace attachment.
 Verifies cohort identity exposure, stale cohort refusal, parity matching,
 reconcile_id freshness, session context cleanup, and regression scenarios.
 """
 from __future__ import annotations
 import os
 import unittest
 from unittest.mock import patch
 import master_parity_gate
 import mcp_namespace_health
 import post_restart_reconcile
 import session_context_binding as session_ctx
 class TestIssue689DeterministicCohortAttachment(unittest.TestCase):
    """Suite covering Issue #689 acceptance criteria."""
    def setUp(self) -> None:
        session_ctx._reset_session_context_for_testing()
    def tearDown(self) -> None:
        session_ctx._reset_session_context_for_testing()
    def test_ac1_session_context_exposes_cohort_identity(self) -> None:
        """AC1: Session context exposes cohort ID, startup SHA, endpoint, and config fingerprint."""
        ctx = session_ctx.bind_session_context(
            profile_name="prgs-author",
            remote="prgs",
            host="gitea.prgs.cc",
            identity="jcwalker3",
            repository="Gitea-Tools",
            org="Scaled-Tech-Consulting",
            role_kind="author",
            cohort_id="cohort-p1234-abc123456789",
            startup_sha="abc123456789def",
            endpoint="gitea.prgs.cc",
            config_fingerprint="fingerprint12345",
        )
        self.assertEqual(ctx["cohort_id"], "cohort-p1234-abc123456789")
        self.assertEqual(ctx["startup_sha"], "abc123456789def")
        self.assertEqual(ctx["endpoint"], "gitea.prgs.cc")
        self.assertEqual(ctx["config_fingerprint"], "fingerprint12345")
        fetched = session_ctx.get_session_context()
        self.assertIsNotNone(fetched)
        self.assertEqual(fetched["cohort_id"], "cohort-p1234-abc123456789")
        self.assertEqual(fetched["startup_sha"], "abc123456789def")
    def test_ac2_stale_cohort_refused_by_probe_classifier(self) -> None:
        """AC2: Probe classifier refuses binding to a stale cohort as stale_cohort_refused."""
        probe_res = {
            "success": True,
            "cohort": {
                "cohort_id": "cohort-obsolete-1",
                "startup_sha": "22698c1000000000000000000000000000000000",
                "endpoint": "gitea.prgs.cc",
                "config_fingerprint": "fp-old",
            },
        }
        res = mcp_namespace_health.classify_namespace_probe(
            "gitea-author",
            probe_result=probe_res,
            probe_source="client_namespace",
            expected_parity_sha="a4c73766f4b0cc32f7c3808688eceeb6fee74335",
        )
        self.assertFalse(res["healthy"])
        self.assertFalse(res["success"])
        self.assertEqual(res["error_type"], "stale_cohort_refused")
        self.assertIn("stale cohort refused", " ".join(res["reasons"]))
        self.assertEqual(
            res["diagnostics"]["startup_sha"],
            "22698c1000000000000000000000000000000000",
        )
    def test_ac3_reconnection_parity_matching_and_fail_closed(self) -> None:
        """AC3: Parity gate fails closed when bound cohort startup SHA mismatches parity."""
        startup = {"startup_head": "a4c73766f4b0cc32f7c3808688eceeb6fee74335"}
        current = "a4c73766f4b0cc32f7c3808688eceeb6fee74335"
        live_remote = "a4c73766f4b0cc32f7c3808688eceeb6fee74335"
        # Matching cohort
        matching_cohort = {
            "cohort_id": "cohort-fresh",
            "startup_sha": "a4c73766f4b0cc32f7c3808688eceeb6fee74335",
        }
        res_matching = master_parity_gate.assess_master_parity(
            startup, current, live_remote_head=live_remote, bound_cohort=matching_cohort
        )
        self.assertTrue(res_matching["cohort_parity_match"])
        self.assertFalse(res_matching["cohort_stale"])
        self.assertTrue(res_matching["mutation_safe"])
        # Mismatched obsolete cohort
        obsolete_cohort = {
            "cohort_id": "cohort-obsolete-22698c1",
            "startup_sha": "22698c1000000000000000000000000000000000",
        }
        res_stale = master_parity_gate.assess_master_parity(
            startup, current, live_remote_head=live_remote, bound_cohort=obsolete_cohort
        )
        self.assertFalse(res_stale["cohort_parity_match"])
        self.assertTrue(res_stale["cohort_stale"])
        self.assertTrue(res_stale["restart_required"])
        self.assertFalse(res_stale["mutation_safe"])
    def test_ac4_reconcile_id_freshness(self) -> None:
        """AC4: Re-attachment distinguishes new reconcile_id from preserved binding."""
        inventory = {"inventory_complete": True}
        # New attachment generates fresh reconcile_id
        proof1 = post_restart_reconcile.reconcile_after_restart(inventory)
        self.assertFalse(proof1.binding_unchanged)
        self.assertTrue(proof1.reconcile_id.startswith("reconcile-"))
        # Preserved binding reports binding_unchanged=True
        proof2 = post_restart_reconcile.reconcile_after_restart(
            inventory,
            reconcile_id=proof1.reconcile_id,
            prior_reconcile_id=proof1.reconcile_id,
        )
        self.assertTrue(proof2.binding_unchanged)
        self.assertEqual(proof2.reconcile_id, proof1.reconcile_id)
        # Disconnected re-attachment gets new reconcile_id
        proof3 = post_restart_reconcile.reconcile_after_restart(
            inventory,
            prior_reconcile_id=proof1.reconcile_id,
        )
        self.assertFalse(proof3.binding_unchanged)
        self.assertNotEqual(proof3.reconcile_id, proof1.reconcile_id)
    def test_ac5_session_disconnect_clears_bindings(self) -> None:
        """AC5: clear_session_context purges session context on disconnect."""
        session_ctx.bind_session_context(
            profile_name="prgs-author",
            remote="prgs",
            host="gitea.prgs.cc",
            identity="jcwalker3",
            cohort_id="cohort-1",
        )
        self.assertIsNotNone(session_ctx.get_session_context())
        session_ctx.clear_session_context()
        self.assertIsNone(session_ctx.get_session_context())
    def test_ac6_bound_cohort_in_diagnostics(self) -> None:
        """AC6: Bound cohort identity appears in audit diagnostics."""
        session_ctx.bind_session_context(
            profile_name="prgs-author",
            remote="prgs",
            host="gitea.prgs.cc",
            identity="jcwalker3",
            cohort_id="cohort-test-99",
            startup_sha="sha99999",
            endpoint="gitea.prgs.cc",
            config_fingerprint="fp999",
        )
        audit = session_ctx.mutation_context_audit_fields()
        self.assertTrue(audit["session_context_bound"])
        self.assertEqual(audit["session_cohort_id"], "cohort-test-99")
        self.assertEqual(audit["session_startup_sha"], "sha99999")
        self.assertEqual(audit["session_endpoint"], "gitea.prgs.cc")
        self.assertEqual(audit["session_config_fingerprint"], "fp999")
    def test_ac7_regression_n_reconnects_never_bind_to_obsolete_daemon(self) -> None:
        """AC7: N reconnects against a daemon set containing obsolete daemons never bind obsolete ones."""
        live_master = "master-head-latest-12345"
        daemons = [
            {"id": "d1", "startup_sha": "obsolete-head-11111"},
            {"id": "d2", "startup_sha": "obsolete-head-22698c1"},
            {"id": "d3", "startup_sha": live_master},
            {"id": "d4", "startup_sha": "obsolete-head-33333"},
        ]
        for _ in range(5):
            for daemon in daemons:
                res = master_parity_gate.assess_master_parity(
                    {"startup_head": live_master},
                    live_master,
                    live_remote_head=live_master,
                    bound_cohort=daemon,
                )
                if daemon["startup_sha"] != live_master:
                    self.assertFalse(res["mutation_safe"])
                    self.assertTrue(res["cohort_stale"])
                else:
                    self.assertTrue(res["mutation_safe"])
                    self.assertFalse(res["cohort_stale"])
    def test_ac8_regression_incident_shape_reproduction(self) -> None:
        """AC8: Reproduce incident shape — obsolete cohort 22698c1 resident vs newer daemon."""
        live_master = "a4c73766f4b0cc32f7c3808688eceeb6fee74335"
        obsolete_cohort = {
            "cohort_id": "cohort-resident-22698c1",
            "startup_sha": "22698c1000000000000000000000000000000000",
        }
        new_cohort = {
            "cohort_id": "cohort-spawned-new",
            "startup_sha": live_master,
        }
        # Obsolete cohort fails parity check
        obs_res = mcp_namespace_health.classify_namespace_probe(
            "gitea-author",
            probe_result={"success": True, "cohort": obsolete_cohort},
            probe_source="client_namespace",
            expected_parity_sha=live_master,
        )
        self.assertFalse(obs_res["healthy"])
        self.assertEqual(obs_res["error_type"], "stale_cohort_refused")
        # Fresh cohort succeeds
        new_res = mcp_namespace_health.classify_namespace_probe(
            "gitea-author",
            probe_result={"success": True, "cohort": new_cohort},
            probe_source="client_namespace",
            expected_parity_sha=live_master,
        )
        self.assertTrue(new_res["healthy"])
    def test_ac9_regression_bound_cohort_going_stale_detected(self) -> None:
        """AC9: A bound cohort that later goes stale is detected on next attachment check."""
        initial_master = "sha-v1-initial"
        cohort = {"cohort_id": "c1", "startup_sha": initial_master}
        # Initial state: in parity
        res1 = master_parity_gate.assess_master_parity(
            {"startup_head": initial_master},
            initial_master,
            live_remote_head=initial_master,
            bound_cohort=cohort,
        )
        self.assertTrue(res1["mutation_safe"])
        # Master advances to sha-v2-advanced while cohort remains at sha-v1-initial
        advanced_master = "sha-v2-advanced"
        res2 = master_parity_gate.assess_master_parity(
            {"startup_head": initial_master},
            advanced_master,
            live_remote_head=advanced_master,
            bound_cohort=cohort,
        )
        self.assertFalse(res2["mutation_safe"])
        self.assertTrue(res2["restart_required"])
        self.assertTrue(res2["cohort_stale"])
 if __name__ == "__main__":
    unittest.main()
@@ -35,10 +35,10 @@ class TestMcpStaleRuntime(unittest.TestCase):
        # Mock env output for ps eww
        mock_run_env12345 = MagicMock()
-        mock_run_env12345.stdout = "GITEA_MCP_PROFILE=prgs-reconciler"
+        mock_run_env12345.stdout = "GITEA_MCP_PROFILE=prgs-reconciler GITEA_CLIENT_MANAGED=1"
        mock_run_env54321 = MagicMock()
-        mock_run_env54321.stdout = "GITEA_MCP_PROFILE=prgs-author"
+        mock_run_env54321.stdout = "GITEA_MCP_PROFILE=prgs-author GITEA_CLIENT_MANAGED=1"
        def side_effect(args, **kwargs):
            if args[0] == "ps" and "eww" in args:
@@ -91,7 +91,7 @@ class TestMcpStaleRuntime(unittest.TestCase):
        mock_run_ps.stdout = ps_output
        mock_run_env = MagicMock()
-        mock_run_env.stdout = "GITEA_MCP_PROFILE=prgs-author"
+        mock_run_env.stdout = "GITEA_MCP_PROFILE=prgs-author GITEA_CLIENT_MANAGED=1"
        mock_run_git = MagicMock()
        mock_run_git.stdout = "FAKE2" # different SHA
@@ -243,9 +243,10 @@ class TestRuntimeClarity(unittest.TestCase):
        self.assertIn("switching is disabled", res["message"].lower())
        self.assertIsNone(gitea_config._active_profile_override)
    @patch("mcp_server._trusted_session_repository", return_value={"repository": "Example-Org/Example-Repo", "org": "Example-Org", "repo": "Example-Repo", "reasons": []})
    @patch("mcp_server.api_request")
    @patch("mcp_server.get_auth_header")
-    def test_activate_profile_succeeds_when_enabled(self, mock_auth, mock_api):
+    def test_activate_profile_succeeds_when_enabled(self, mock_auth, mock_api, mock_trusted):
        self._write_config(CONFIG_SWITCHING_ENABLED)
        # Setup mock responses for whoami checks
Author	SHA1	Message	Date
sysadminandClaude Opus 5	97bc190fc2	docs(remote-mcp): inventory stdio- and localhost-coupled assumptions (#930 ) Add docs/remote-mcp/coupling-inventory.md, the blocking first child of epic #929. It enumerates every place gitea_mcp_server.py and its supporting modules depend on being a local, client-spawned, stdio-attached process on the operator's machine. 62 entries across the seven required categories: transport bind, launch provenance, role binding, credentials, runtime freshness, local filesystem, and durable state. Each entry carries a file and line anchor resolving at `7bf4f12584`, states what the code assumes today and what it would observe on a remote host, is classified as portable as written / needs a seam / needs a replacement / cannot be remote, and is assigned to exactly one epic child. Every child from #931 through #939 is named by at least one entry. Summary tables count entries per category, per classification, per category-by-classification, and per child. Documentation only. No server behavior changes. Closes #930 Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01HvJz7bUz5CkZgUxq8twHMz	2026-07-26 02:09:09 -04:00
sysadmin	7bf4f12584	Merge pull request 'fix(guardrail): detect and reject manually launched duplicate MCP role servers (#686 )' (#925 ) from fix/issue-686-detect-reject-manual-mcp into master	2026-07-25 18:32:23 -05:00
sysadmin	dc0bff764d	test(runtime): patch _trusted_session_repository in test_activate_profile_succeeds_when_enabled	2026-07-25 19:27:12 -04:00
sysadmin	dfe8d7c28d	fix(mcp): detect and reject manually launched duplicate MCP role servers (Closes #686 )	2026-07-25 19:25:23 -04:00