Merge pull request 'fix(bootstrap): allow author worktree bootstrap from clean control checkout (Closes #892)' (#926) from fix/issue-892-author-bootstrap-deadlock into master

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

author_issue_bootstrap.py

@@ -386,6 +386,68 @@ def run_compensating_recovery(
     return recovery_info
 
 
+def _normalize_sha(value: str | None) -> str | None:
+    """Normalize a Git object id for comparison, or ``None`` when unknown."""
+    normalized = (value or "").strip().lower()
+    return normalized or None
+
+
+def _author_bootstrap_assessment(
+    *,
+    not_applicable: bool,
+    allowed: bool,
+    block: bool,
+    reasons: list[str],
+    workspace: str,
+    root: str,
+    branch: str | None,
+    dirty: list[str],
+    under_branches: bool,
+    bootstrap_path: str | None = None,
+    local_head_sha: str | None = None,
+    remote_master_sha: str | None = None,
+    exact_next_action: str | None = None,
+) -> dict[str, Any]:
+    """Structured author-bootstrap assessment consumable by bootstrap_permits (#892).
+
+    Field shape mirrors :func:`create_issue_bootstrap._result` so the shared
+    ``bootstrap_permits_control_checkout`` predicate can prove control-checkout
+    eligibility for ``gitea_bootstrap_author_issue_worktree`` the same way it
+    does for ``create_issue``. Allowed control assessments must use empty
+    ``reasons`` — narrative belongs in other fields, not the refusal list.
+    """
+    local_tip = _normalize_sha(local_head_sha)
+    remote_tip = _normalize_sha(remote_master_sha)
+    base_tips_verified = bool(local_tip and remote_tip and local_tip == remote_tip)
+    return {
+        "not_applicable": not_applicable,
+        "allowed": allowed,
+        "block": block,
+        "proven": bool(allowed and not block and not not_applicable),
+        "reasons": list(reasons),
+        "workspace_path": workspace,
+        "canonical_repo_root": root,
+        "current_branch": branch,
+        "dirty_files": list(dirty),
+        "under_branches": under_branches,
+        "exact_next_action": exact_next_action,
+        "bootstrap_path": bootstrap_path,
+        "task_scope": "author_issue_bootstrap",
+        "local_head_sha": local_tip,
+        "remote_master_sha": remote_tip,
+        "base_tips_verified": base_tips_verified,
+    }
+
+
+EXACT_NEXT_ACTION_AUTHOR_BOOTSTRAP = (
+    "Restore the canonical control checkout to a clean accepted base branch "
+    "(master/main/dev) that matches live master, with no tracked local edits. "
+    "Re-resolve bootstrap_author_issue_worktree, then re-run "
+    "gitea_bootstrap_author_issue_worktree from that clean control checkout. "
+    "Do not use shell git worktree add as the primary path once bootstrap is healthy."
+)
+
+
 def assess_author_issue_bootstrap(
     *,
     workspace_path: str,
@@ -397,7 +459,13 @@ def assess_author_issue_bootstrap(
     remote_master_sha_error: str | None = None,
     task: str | None = None,
 ) -> dict[str, Any]:
-    """Assess whether author issue worktree bootstrap may proceed from control or worktree root."""
+    """Assess whether author issue worktree bootstrap may proceed from control or worktree root.
+
+    #892: control-checkout successes emit the full field set required by
+    ``create_issue_bootstrap.bootstrap_permits_control_checkout`` (empty reasons,
+    task_scope, base tip proof, binding paths) so the #274/#604 guards can
+    waive control-checkout for this one sanctioned bootstrap task.
+    """
     root = os.path.realpath(canonical_repo_root or "")
     workspace = os.path.realpath(workspace_path or root or ".")
     branch = (current_branch or "").strip()
@@ -407,34 +475,50 @@ def assess_author_issue_bootstrap(
         if root
         else False
     )
+    local_tip = _normalize_sha(head_sha)
+    remote_tip = _normalize_sha(remote_master_sha)
 
     if not is_author_issue_bootstrap_task(task):
-        return {
-            "not_applicable": True,
-            "allowed": False,
-            "block": False,
-            "proven": False,
-            "reasons": ["task is not author_issue_bootstrap"],
-        }
+        return _author_bootstrap_assessment(
+            not_applicable=True,
+            allowed=False,
+            block=False,
+            reasons=["task is not author_issue_bootstrap"],
+            workspace=workspace,
+            root=root,
+            branch=branch or None,
+            dirty=dirty,
+            under_branches=under_branches,
+        )
 
+    # Already under branches/: ordinary #274 path applies; not a control waiver.
     if under_branches:
-        return {
-            "not_applicable": False,
-            "allowed": True,
-            "block": False,
-            "proven": True,
-            "bootstrap_path": "existing_branches_worktree",
-            "reasons": [
-                "workspace is already a registered worktree under branches/"
-            ],
-        }
+        return _author_bootstrap_assessment(
+            not_applicable=True,
+            allowed=False,
+            block=False,
+            reasons=["workspace is under branches/; ordinary #274 path applies"],
+            workspace=workspace,
+            root=root,
+            branch=branch or None,
+            dirty=dirty,
+            under_branches=True,
+            bootstrap_path="existing_branches_worktree",
+            local_head_sha=local_tip,
+            remote_master_sha=remote_tip,
+        )
 
     reasons: list[str] = []
-    if workspace != root:
+    if not root or workspace != root:
         reasons.append(
             "bootstrap requires workspace to be canonical control checkout or branches/ worktree"
         )
-    if branch not in author_mutation_worktree.BASE_BRANCHES:
+    if not branch:
+        reasons.append(
+            "control checkout is detached HEAD; expected an accepted base branch "
+            f"({', '.join(sorted(author_mutation_worktree.BASE_BRANCHES))})"
+        )
+    elif branch not in author_mutation_worktree.BASE_BRANCHES:
         reasons.append(
             f"control checkout branch '{branch}' is not an accepted base branch "
             f"({', '.join(sorted(author_mutation_worktree.BASE_BRANCHES))})"
@@ -444,37 +528,64 @@ def assess_author_issue_bootstrap(
             f"control checkout has tracked local edits: {', '.join(dirty[:5])}"
         )
 
-    if remote_master_sha_error:
+    # Fail closed on missing tip proof (same bar as create_issue bootstrap #757).
+    if not local_tip:
         reasons.append(
-            f"could not verify live master tip: {remote_master_sha_error}"
+            "control checkout HEAD SHA is unknown; base equivalence to live "
+            "master cannot be proven (fail closed)"
+        )
+    resolver_error = (remote_master_sha_error or "").strip() or None
+    if resolver_error:
+        reasons.append(
+            f"live master tip could not be resolved ({resolver_error}); "
+            "base equivalence cannot be proven (fail closed)"
+        )
+    elif not remote_tip:
+        reasons.append(
+            "live master tip is unknown; base equivalence cannot be proven "
+            "(fail closed)"
+        )
+    elif local_tip and remote_tip and local_tip != remote_tip:
+        reasons.append(
+            f"control checkout HEAD ({local_tip[:12]}) != live master tip "
+            f"({remote_tip[:12]})"
         )
-    elif remote_master_sha and head_sha:
-        h = head_sha.strip().lower()
-        rm = remote_master_sha.strip().lower()
-        if h != rm:
-            reasons.append(
-                f"control checkout HEAD ({h[:12]}) != live master tip ({rm[:12]})"
-            )
 
     if reasons:
-        return {
-            "not_applicable": False,
-            "allowed": False,
-            "block": True,
-            "proven": False,
-            "reasons": reasons,
-        }
+        return _author_bootstrap_assessment(
+            not_applicable=False,
+            allowed=False,
+            block=True,
+            reasons=reasons,
+            workspace=workspace,
+            root=root,
+            branch=branch or None,
+            dirty=dirty,
+            under_branches=False,
+            local_head_sha=local_tip,
+            remote_master_sha=remote_tip,
+            exact_next_action=EXACT_NEXT_ACTION_AUTHOR_BOOTSTRAP,
+        )
 
-    return {
-        "not_applicable": False,
-        "allowed": True,
-        "block": False,
-        "proven": True,
-        "bootstrap_path": "clean_canonical_control_checkout",
-        "reasons": [
-            "control checkout is clean on accepted base branch matching live master"
-        ],
-    }
+    # Allowed: empty reasons so bootstrap_permits_control_checkout can pass.
+    return _author_bootstrap_assessment(
+        not_applicable=False,
+        allowed=True,
+        block=False,
+        reasons=[],
+        workspace=workspace,
+        root=root,
+        branch=branch or None,
+        dirty=dirty,
+        under_branches=False,
+        bootstrap_path="clean_canonical_control_checkout",
+        local_head_sha=local_tip,
+        remote_master_sha=remote_tip,
+        exact_next_action=(
+            "Call gitea_bootstrap_author_issue_worktree with the allocated "
+            "issue/lease pins; it will create the branches/ worktree and lock."
+        ),
+    )
 
 
 import fcntl

create_issue_bootstrap.py

@@ -241,9 +241,14 @@ def bootstrap_permits_control_checkout(
     caller's ordinary block in force.
 
     ``assessment`` is server-derived only: it is produced by
-    :func:`assess_create_issue_bootstrap` from inspected repository state. It is
-    never accepted from an MCP tool argument, so no caller can assert
-    eligibility it has not proven.
+    :func:`assess_create_issue_bootstrap` or
+    :func:`author_issue_bootstrap.assess_author_issue_bootstrap` from inspected
+    repository state. It is never accepted from an MCP tool argument, so no
+    caller can assert eligibility it has not proven.
+
+    #892: author issue worktree bootstrap uses the same predicate with
+    ``task_scope='author_issue_bootstrap'`` so a clean control checkout can
+    create the first ``branches/`` worktree without the lock↔worktree cycle.
     """
     if not isinstance(assessment, dict):
         return False
@@ -264,9 +269,16 @@ def bootstrap_permits_control_checkout(
     if assessment.get("reasons"):
         return False
 
-    # Scope proof: only the create_issue bootstrap, only via the clean
-    # canonical control checkout path.
-    if assessment.get("task_scope") != "create_issue_only":
+    # Scope proof: create_issue (#749) or author issue bootstrap (#850/#892),
+    # only via the clean canonical control checkout path.
+    task_scope = assessment.get("task_scope")
+    if is_create_issue_task(task):
+        if task_scope != "create_issue_only":
+            return False
+    elif author_issue_bootstrap.is_author_issue_bootstrap_task(task):
+        if task_scope != "author_issue_bootstrap":
+            return False
+    else:
         return False
     if assessment.get("bootstrap_path") != "clean_canonical_control_checkout":
         return False

docs/mcp-namespace-eof-recovery.md

@@ -47,33 +47,18 @@ Do the steps in order. Stop as soon as a live **client-namespace** call succeeds
    - Only the Gitea namespace fails → single-namespace transport close. Continue.
    - Every server fails → restart the whole MCP client, not just one namespace.
 
-2. **Request the sanctioned reconnect surface (#678), then reconnect through
-   the client — not the shell.** From a still-reachable Gitea MCP namespace
-   (or after host auto-reconnect), call:
-
-   ```text
-   gitea_request_mcp_reconnect(
-       namespace="gitea-author",   # or gitea-reviewer / gitea-merger / …
-       reason="transport_eof",
-       client="codex",            # or claude_code / generic
-   )
-   ```
-
-   The tool is **report-only**: it never restarts a process. It returns
-   namespace, profile, pid/session, startup SHA, current master SHA, boundary
-   status, and a **typed blocker** with exact operator UI steps for Codex
-   (Reload Developer Tools / per-server reconnect) or Claude Code (`/mcp`).
-   Then perform the host reconnect those steps describe so the client spawns a
-   fresh subprocess and re-opens the pipe. That clears the closed-client state
-   that a bare `kill`/respawn from a terminal does **not**.
+2. **Reconnect the namespace through the client, not the shell.** Use the IDE /
+   client MCP-reconnect action for that server entry (in Claude Code:
+   `/mcp` → reconnect the affected `gitea-*` server). Reconnecting forces the
+   client to spawn a fresh subprocess and re-open the pipe. This clears the
+   closed-client state that a bare `kill`/respawn from a terminal does **not**.
 
 3. **Do not "fix" it by importing the server or poking the process.** Reaching
    for `python -c 'import gitea_mcp_server ...'`, raw JSON-RPC from a shell,
    killing PIDs to force a respawn, or touching MCP config mtimes does **not**
    restore the *client's* view of the namespace and violates the daemon-import
    guard (#558, `docs/mcp-daemon-import-guard.md`). The only sanctioned repair
-   is a **client reconnect / relaunch** (or the typed operator path returned by
-   `gitea_request_mcp_reconnect`).
+   is a **client reconnect / relaunch**.
 
 4. **Verify through the same path the workflow will use.** After reconnect, call
    the specific tool the blocked workflow needs — not just any tool — through
@@ -168,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).
+

docs/mcp-restart-path-inventory.md

@@ -45,11 +45,10 @@ and *fails closed*.
 | `legacy_auto_restart_helper` | removed | A helper (`_trigger_mcp_auto_restart`) that actively restarted the server from the read-only resolver path. | Removed in #685; kept absent by `assert_auto_restart_helper_absent()`. | #685, #657 |
 | `config_touch_reload` | removed | Touching (utime) the MCP client config to make the host reload the server. | Removed from the resolver in #685: stale detection is report-only, never mutating config, spawning threads, or calling `os._exit`. | #685, #657 |
 | `master_advance_auto_restart` | guarded_fail_closed | On-disk master advancing past the running code. | `master_parity_gate` captures startup parity and blocks mutations while stale, emitting restart guidance; the process never self-restarts. | #420, #591, #657 |
-| `stale_runtime_resolver_reconnect` | guarded_fail_closed | The capability resolver detecting a stale serving process. | Report-only (#685): returns `restart_required`/`stop_required` and an exact reconnect action; no restart, thread, config touch, or `os._exit`. | #685, #657, #678 |
-| `codex_client_reconnect_request` | guarded_fail_closed | `gitea_request_mcp_reconnect` report-only tool for Codex/LLM sessions. | Report-only (#678): returns namespace/profile/pid/startup SHA/master SHA/boundary status and a typed operator blocker with exact client UI steps; never restarts or kills. | #678, #630, #685, #657 |
+| `stale_runtime_resolver_reconnect` | guarded_fail_closed | The capability resolver detecting a stale serving process. | Report-only (#685): returns `restart_required`/`stop_required` and an exact reconnect action; no restart, thread, config touch, or `os._exit`. | #685, #657 |
 | `manual_daemon_kill` | forbidden | Shell kills of the daemon: `pkill -f mcp_server.py`, `killall`, broad `pkill -f python` sweeps, or `kill <pid>` of a daemon pid. | Forbidden (#630): `runtime_recovery_guard` classifies these as contamination and `gitea_record_daemon_process_kill_attempt` writes a durable marker that fails later mutations closed. Operator maintenance authorization is read only from the environment. | #630, #657 |
 | `conflict_marker_infra_stop` | guarded_fail_closed | The daemon entrypoint scans for unresolved merge-conflict markers at startup and stops (`sys.exit(1)`). | Fail-closed startup stop, not a restart: the process exits and waits for the operator to resolve conflicts and relaunch; never loops. | #657 |
-| `ide_client_reconnect` | host_residual | A manual `/mcp reconnect` (or equivalent host action) that recreates the MCP client connection. Agents obtain exact UI steps via `gitea_request_mcp_reconnect` (#678). | Outside this process's control; the sanctioned recovery the gates point operators toward. No in-process code initiates it. | #584, #656, #657, #678 |
+| `ide_client_reconnect` | host_residual | A manual `/mcp reconnect` (or equivalent host action) that recreates the MCP client connection. | Outside this process's control; the sanctioned recovery the gates point operators toward. No in-process code initiates it. | #584, #656, #657 |
 | `profile_switch_runtime` | sanctioned_narrow_recovery | Switching the active execution profile at runtime (dynamic-profile mode). | In-process and restart-free: `runtime_switching_supported` is true, so a switch rebinds capability without recreating the process. | #656, #657 |
 
 ## Guards enforced in CI

docs/mcp-tool-inventory.md

@@ -137,7 +137,6 @@ that gates each call, not which tools exist.
 - `gitea_release_merger_pr_lease`
 - `gitea_release_reviewer_pr_lease`
 - `gitea_release_workflow_lease`
-- `gitea_request_mcp_reconnect`
 - `gitea_request_mcp_restart`
 - `gitea_resolve_task_capability`
 - `gitea_resume_review_draft`

docs/remote-mcp/coupling-inventory.md

@@ -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.

gitea_config.py

@@ -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*.
 

gitea_mcp_server.py

@@ -2092,7 +2092,6 @@ import root_checkout_guard  # noqa: E402
 import workflow_scope_guard  # noqa: E402  # #683 production scope / force-on guards
 import stable_branch_push_guard  # noqa: E402
 import runtime_recovery_guard  # noqa: E402  # #630 manual daemon-kill contamination
-import mcp_client_reconnect  # noqa: E402  # #678 sanctioned Codex reconnect request
 import remote_repo_guard  # noqa: E402
 import anti_stomp_preflight  # noqa: E402
 import issue_claim_heartbeat  # noqa: E402
@@ -14025,16 +14024,11 @@ def _classify_operation_gate_reasons(reasons: list[str]) -> dict:
 
 
 def _stale_runtime_reconnect_action() -> str:
-    """Sanctioned recovery for a stale daemon — reconnect only (#685/#897/#678)."""
+    """Sanctioned recovery for a stale daemon — reconnect only (#685/#897)."""
     return (
-        "blocker_kind=runtime_reconnect_required: call "
-        "gitea_request_mcp_reconnect(namespace=<active gitea-* namespace>, "
-        "reason='stale-runtime', client='codex') for a typed operator "
-        "reconnect blocker with exact UI steps, then reconnect the IDE/client "
-        "MCP session so the server reloads at the current master head. Do not "
-        "call gitea_activate_profile, pkill, touch configs, or switch MCP role "
-        "sessions — profile switching does not clear a stale daemon. After "
-        "reconnect restart from gitea_whoami → gitea_resolve_task_capability."
+        "Reconnect the IDE/client MCP session so the server reloads at the "
+        "current master head. Do not call gitea_activate_profile or switch "
+        "MCP role sessions — profile switching does not clear a stale daemon."
     )
 
 
@@ -14591,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).
 
@@ -14607,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(
@@ -14640,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:
@@ -18087,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,
@@ -18103,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"),
@@ -18116,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:
@@ -20573,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:
@@ -20605,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"]:
-            running_profiles[profile] = {
-                "pid": pid,
-                "start_time": start_time,
-                "is_stale": is_stale
-            }
+        proc_info = {
+            "pid": pid,
+            "start_time": start_time,
+            "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.
@@ -20649,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,
@@ -21004,15 +21111,10 @@ def gitea_resolve_task_capability(
     # serving process/profile inventory is stale — even if permission is OK.
     if runtime_stale_blocker:
         next_safe_action = (
-            "blocker_kind=runtime_reconnect_required: call "
-            "gitea_request_mcp_reconnect(namespace=<active gitea-* namespace>, "
-            "reason='stale-runtime', client='codex') for a typed operator "
-            "blocker with exact UI steps, then reconnect/reload the IDE-managed "
-            "Gitea MCP server for this profile so it reloads current master. "
-            "Do not edit mcp_config.json by hand, pkill, or touch configs; the "
-            "resolver does not touch config, spawn recovery threads, or "
-            "terminate the process. After reconnect restart from gitea_whoami → "
-            "gitea_resolve_task_capability."
+            "blocker_kind=runtime_reconnect_required: reconnect/restart the "
+            "IDE-managed Gitea MCP server for this profile so it reloads current "
+            "master. Do not edit mcp_config.json by hand; the resolver does not "
+            "touch config, spawn recovery threads, or terminate the process."
         )
 
     # Task/role alignment guards (#167): the requested task, not the
@@ -22570,129 +22672,6 @@ def gitea_workflow_dashboard(
     return payload
 
 
-@mcp.tool()
-def gitea_request_mcp_reconnect(
-    namespace: str | None = None,
-    reason: str | None = None,
-    client: str = "codex",
-    remote: str = "dadeschools",
-    host: str | None = None,
-    session_id: str | None = None,
-) -> dict:
-    """Request a sanctioned host/IDE MCP reconnect for a named namespace (#678).
-
-    Codex and other agent hosts can detect stale or closed Gitea MCP runtimes
-    (``stop_required`` / ``restart_required`` from capability resolution, transport
-    EOF, missing namespace attachment). The **host owns the transport** — this
-    process cannot reopen the client's stdio pipe. This tool is the callable
-    surface agents use to:
-
-    1. Report reconnect status fields (namespace, profile, pid/session,
-       startup SHA, current master SHA, boundary status).
-    2. Return a **typed blocker** with exact operator UI steps for Codex (or
-       another client) when reconnect is required.
-
-    This tool **never** restarts, kills, reloads, or reconfigures an MCP
-    process. Forbidden recovery paths (pkill, touch/mtime hacks, config/.env
-    edits, session-state edits, raw API) are never recommended.
-
-    After the operator reconnects, workflows must restart from preflight:
-    ``gitea_whoami`` → ``gitea_resolve_task_capability`` → task.
-
-    Args:
-        namespace: MCP namespace to reconnect (e.g. ``gitea-author``). Defaults
-            to the active profile's inferred namespace.
-        reason: Why reconnect is requested: ``stale-runtime``, ``transport_eof``,
-            ``missing_namespace``, ``not_required``, or free-form (normalized).
-        client: Operator UI surface — ``codex`` (default), ``claude_code``, or
-            ``generic``.
-        remote: Known instance — ``dadeschools`` or ``prgs`` (parity context).
-        host: Optional host override for parity context.
-        session_id: Optional session id to echo in the report.
-
-    Returns:
-        dict with reconnect report fields, ``reconnect_performed=False``,
-        ``typed_blocker`` when reconnect is required, and
-        ``forbidden_recovery_paths``.
-    """
-    # Read-only: gitea.read is sufficient. Never a mutation.
-    read_block = _profile_operation_gate("gitea.read")
-    if read_block:
-        return {
-            "success": False,
-            "read_only": True,
-            "reconnect_performed": False,
-            "mutation_performed": False,
-            "reasons": read_block,
-            "permission_report": _permission_block_report("gitea.read"),
-            "forbidden_recovery_paths": list(
-                mcp_client_reconnect.FORBIDDEN_RECOVERY_PATHS
-            ),
-        }
-
-    profile = get_profile()
-    profile_name = (profile.get("profile_name") or "").strip() or None
-    inferred_ns = role_namespace_gate.infer_mcp_namespace(profile_name)
-    ns = (namespace or "").strip() or inferred_ns or "gitea-tools"
-
-    parity = _current_master_parity()
-    startup_sha = (
-        parity.get("daemon_start_head")
-        or parity.get("startup_head")
-        or _process_boot_head_sha
-    )
-    current_sha = parity.get("local_head") or parity.get("current_head")
-    if not current_sha:
-        try:
-            current_sha = master_parity_gate.read_git_head(PROJECT_ROOT)
-        except Exception:  # noqa: BLE001
-            current_sha = None
-
-    boundary = mcp_client_reconnect.classify_boundary_status(
-        startup_sha=startup_sha if isinstance(startup_sha, str) else None,
-        current_master_sha=current_sha if isinstance(current_sha, str) else None,
-        live_stale=bool(parity.get("live_stale")) if parity.get("live_known") else None,
-        in_parity=parity.get("in_parity") if parity.get("determinable") else None,
-    )
-
-    # Infer reason from parity when caller left it unspecified.
-    effective_reason = reason
-    if not (effective_reason or "").strip():
-        if parity.get("restart_required") or parity.get("live_stale"):
-            effective_reason = mcp_client_reconnect.REASON_STALE_RUNTIME
-        elif boundary == mcp_client_reconnect.BOUNDARY_CLEAN:
-            effective_reason = mcp_client_reconnect.REASON_NOT_REQUIRED
-        else:
-            effective_reason = mcp_client_reconnect.REASON_UNSPECIFIED
-
-    payload = mcp_client_reconnect.build_reconnect_request(
-        namespace=ns,
-        profile=profile_name,
-        pid=os.getpid(),
-        session_id=session_id
-        or f"{(profile_name or 'session')}-{os.getpid()}",
-        startup_sha=startup_sha if isinstance(startup_sha, str) else None,
-        current_master_sha=current_sha if isinstance(current_sha, str) else None,
-        boundary_status=boundary,
-        reason=effective_reason,
-        client=client,
-        live_stale=bool(parity.get("live_stale")) if parity.get("live_known") else None,
-        in_parity=parity.get("in_parity") if parity.get("determinable") else None,
-        restart_required=bool(parity.get("restart_required")),
-        stop_required=bool(parity.get("restart_required")),
-        extra={
-            "remote": remote if remote in REMOTES else remote,
-            "host": host,
-            "session_context_audit": session_ctx.mutation_context_audit_fields(),
-            "parity_summary": master_parity_gate.format_parity(parity),
-            "live_stale": parity.get("live_stale"),
-            "live_known": parity.get("live_known"),
-            "in_parity": parity.get("in_parity"),
-        },
-    )
-    return payload
-
-
 @mcp.tool()
 def gitea_request_mcp_restart(
     remote: str = "dadeschools",

mcp_client_reconnect.py

@@ -1,328 +0,0 @@
-"""Sanctioned MCP client reconnect request surface for Codex/LLM sessions (#678).
-
-Codex and other agent hosts can detect stale or closed Gitea MCP runtimes, but
-the host owns the transport. This module never restarts, kills, or reloads a
-daemon. It builds:
-
-1. A **callable reconnect request** result agents can invoke via
-   ``gitea_request_mcp_reconnect`` (report-only, side-effect free).
-2. A **typed blocker** with exact operator UI steps when recovery must be
-   performed by the host/operator.
-
-Forbidden recovery paths (must never be recommended):
-
-* ``pkill`` / ``kill`` / ``killall`` of MCP daemons
-* ``touch`` / mtime config reload hacks
-* ``.env`` or MCP config edits as recovery
-* session-state file edits
-* raw Gitea API / direct server-import fallbacks
-
-After the operator reconnects, workflows restart from identity / runtime /
-capability preflight (``gitea_whoami`` → ``gitea_resolve_task_capability`` →
-task).
-"""
-
-from __future__ import annotations
-
-from typing import Any, Mapping
-
-# --- Reason vocabulary -------------------------------------------------------
-
-REASON_STALE_RUNTIME = "stale-runtime"
-REASON_TRANSPORT_EOF = "transport_eof"
-REASON_MISSING_NAMESPACE = "missing_namespace"
-REASON_NOT_REQUIRED = "not_required"
-REASON_UNSPECIFIED = "unspecified"
-
-VALID_REASONS = frozenset(
-    {
-        REASON_STALE_RUNTIME,
-        REASON_TRANSPORT_EOF,
-        REASON_MISSING_NAMESPACE,
-        REASON_NOT_REQUIRED,
-        REASON_UNSPECIFIED,
-    }
-)
-
-# Boundary statuses reported to callers (match review_workflow_boundary style).
-BOUNDARY_CLEAN = "clean"
-BOUNDARY_MISMATCH = "mismatch"
-BOUNDARY_STALE = "stale"
-BOUNDARY_UNKNOWN = "unknown"
-
-# Typed blocker kinds
-BLOCKER_OPERATOR_RECONNECT = "operator_mcp_reconnect_required"
-BLOCKER_NONE = "none"
-
-FORBIDDEN_RECOVERY_PATHS: tuple[str, ...] = (
-    "pkill / kill / killall of mcp_server.py, gitea_mcp_server, or broad python sweeps",
-    "touch / mtime-based MCP config reload hacks",
-    ".env edits as recovery",
-    "MCP config file edits as recovery",
-    "session-state file edits as recovery",
-    "raw Gitea API or direct MCP server-import fallbacks",
-)
-
-# Client-specific operator UI steps. Keep Codex first (issue title surface).
-OPERATOR_UI_STEPS: dict[str, tuple[str, ...]] = {
-    "codex": (
-        "In Codex, open the MCP / Developer tools panel for this workspace.",
-        "Locate the named Gitea MCP server entry (namespace) that needs reconnect "
-        "(e.g. gitea-author, gitea-reviewer, gitea-merger, gitea-tools, "
-        "gitea-controller, gitea-reconciler).",
-        "Click 'Reload Developer Tools' or the server reconnect/reload control "
-        "for that entry so the client spawns a fresh MCP subprocess.",
-        "If per-server reconnect is unavailable, fully restart the Codex client "
-        "(quit and relaunch) so all MCP namespaces reattach.",
-        "After reconnect, rerun the blocked workflow from preflight: "
-        "gitea_whoami → gitea_resolve_task_capability → the original task. "
-        "Do not resume mid-mutation.",
-    ),
-    "claude_code": (
-        "Run `/mcp` (or open the MCP servers UI) in Claude Code.",
-        "Reconnect the affected gitea-* server entry so the client reopens stdio.",
-        "If reconnect fails, relaunch the Claude Code session entirely.",
-        "After reconnect, restart the workflow from gitea_whoami → "
-        "gitea_resolve_task_capability → task.",
-    ),
-    "generic": (
-        "Use the host/IDE MCP reconnect or reload control for the named namespace.",
-        "If no per-namespace control exists, restart the MCP client/editor.",
-        "After reconnect, restart the workflow from identity/capability preflight.",
-    ),
-}
-
-DEFAULT_CLIENT = "codex"
-
-
-def normalize_reason(reason: str | None) -> str:
-    """Map free-form reason strings onto the closed vocabulary."""
-    raw = (reason or "").strip().lower()
-    if not raw:
-        return REASON_UNSPECIFIED
-    if raw in VALID_REASONS:
-        return raw
-    text = raw.replace(" ", "_").replace("-", "_")
-    aliases = {
-        "stale_runtime": REASON_STALE_RUNTIME,
-        "staleruntime": REASON_STALE_RUNTIME,
-        "runtime_stale": REASON_STALE_RUNTIME,
-        "stale": REASON_STALE_RUNTIME,
-        "transport_eof": REASON_TRANSPORT_EOF,
-        "transport_closed": REASON_TRANSPORT_EOF,
-        "eof": REASON_TRANSPORT_EOF,
-        "client_is_closing": REASON_TRANSPORT_EOF,
-        "missing_namespace": REASON_MISSING_NAMESPACE,
-        "namespace_missing": REASON_MISSING_NAMESPACE,
-        "not_required": REASON_NOT_REQUIRED,
-        "healthy": REASON_NOT_REQUIRED,
-        "ok": REASON_NOT_REQUIRED,
-        "unspecified": REASON_UNSPECIFIED,
-    }
-    if text in aliases:
-        return aliases[text]
-    hyphenated = text.replace("_", "-")
-    if hyphenated in VALID_REASONS:
-        return hyphenated
-    return REASON_UNSPECIFIED
-
-
-def normalize_client(client: str | None) -> str:
-    """Return a known client key for operator UI steps."""
-    text = (client or "").strip().lower().replace(" ", "_").replace("-", "_")
-    if text in ("codex", "openai_codex", "openai"):
-        return "codex"
-    if text in ("claude", "claude_code", "claude_desktop", "anthropic"):
-        return "claude_code"
-    if text in OPERATOR_UI_STEPS:
-        return text
-    return DEFAULT_CLIENT
-
-
-def classify_boundary_status(
-    *,
-    startup_sha: str | None,
-    current_master_sha: str | None,
-    live_stale: bool | None = None,
-    in_parity: bool | None = None,
-) -> str:
-    """Derive boundary_status from parity evidence."""
-    if live_stale is True or in_parity is False:
-        return BOUNDARY_STALE
-    start = (startup_sha or "").strip().lower()
-    current = (current_master_sha or "").strip().lower()
-    if start and current and start != current:
-        return BOUNDARY_MISMATCH
-    if start and current and start == current:
-        return BOUNDARY_CLEAN
-    if in_parity is True:
-        return BOUNDARY_CLEAN
-    return BOUNDARY_UNKNOWN
-
-
-def operator_ui_steps(client: str | None, *, namespace: str | None = None) -> list[str]:
-    """Exact operator UI steps for the named client."""
-    key = normalize_client(client)
-    steps = list(OPERATOR_UI_STEPS.get(key) or OPERATOR_UI_STEPS[DEFAULT_CLIENT])
-    ns = (namespace or "").strip()
-    if ns:
-        steps = [
-            s.replace("named Gitea MCP server entry (namespace)", f"namespace '{ns}'")
-            .replace("affected gitea-* server entry", f"server entry '{ns}'")
-            .replace("named namespace", f"namespace '{ns}'")
-            for s in steps
-        ]
-    return steps
-
-
-def build_reconnect_request(
-    *,
-    namespace: str,
-    profile: str | None = None,
-    pid: int | str | None = None,
-    session_id: str | None = None,
-    startup_sha: str | None = None,
-    current_master_sha: str | None = None,
-    boundary_status: str | None = None,
-    reason: str | None = None,
-    client: str | None = DEFAULT_CLIENT,
-    live_stale: bool | None = None,
-    in_parity: bool | None = None,
-    restart_required: bool | None = None,
-    stop_required: bool | None = None,
-    extra: Mapping[str, Any] | None = None,
-) -> dict[str, Any]:
-    """Build the structured reconnect-request / typed-blocker payload (#678).
-
-    Never mutates process, config, or session state. Always side-effect free.
-    """
-    ns = (namespace or "").strip() or "unknown"
-    normalized_reason = normalize_reason(reason)
-    boundary = (boundary_status or "").strip() or classify_boundary_status(
-        startup_sha=startup_sha,
-        current_master_sha=current_master_sha,
-        live_stale=live_stale,
-        in_parity=in_parity,
-    )
-
-    reconnect_needed = True
-    if normalized_reason == REASON_NOT_REQUIRED and boundary == BOUNDARY_CLEAN:
-        reconnect_needed = False
-    if restart_required is False and stop_required is False and boundary == BOUNDARY_CLEAN:
-        # Explicit healthy probe
-        if normalized_reason in (REASON_NOT_REQUIRED, REASON_UNSPECIFIED):
-            reconnect_needed = False
-            normalized_reason = REASON_NOT_REQUIRED
-
-    if restart_required is True or stop_required is True:
-        reconnect_needed = True
-        if normalized_reason in (REASON_NOT_REQUIRED, REASON_UNSPECIFIED):
-            normalized_reason = REASON_STALE_RUNTIME
-
-    client_key = normalize_client(client)
-    steps = operator_ui_steps(client_key, namespace=ns)
-
-    result: dict[str, Any] = {
-        "success": True,
-        "read_only": True,
-        "reconnect_performed": False,
-        "mutation_performed": False,
-        "reconnect_needed": reconnect_needed,
-        "namespace": ns,
-        "profile": (profile or "").strip() or None,
-        "pid": pid,
-        "session_id": (session_id or "").strip() or None,
-        "startup_sha": (startup_sha or "").strip() or None,
-        "current_master_sha": (current_master_sha or "").strip() or None,
-        "boundary_status": boundary,
-        "reason": normalized_reason,
-        "client": client_key,
-        "forbidden_recovery_paths": list(FORBIDDEN_RECOVERY_PATHS),
-        "post_reconnect_preflight": [
-            "gitea_whoami",
-            "gitea_resolve_task_capability",
-            "original_task",
-        ],
-        "exact_safe_next_action": None,
-        "blocker_kind": BLOCKER_NONE,
-        "operator_ui_steps": steps,
-        "typed_blocker": None,
-    }
-
-    if reconnect_needed:
-        result["blocker_kind"] = BLOCKER_OPERATOR_RECONNECT
-        result["stop_required"] = True
-        result["restart_required"] = True
-        result["exact_safe_next_action"] = (
-            f"blocker_kind={BLOCKER_OPERATOR_RECONNECT}: operator must reconnect "
-            f"MCP namespace '{ns}' via the host UI (client={client_key}). "
-            "Do not pkill, touch configs, edit session state, or use raw API. "
-            "After reconnect, restart from gitea_whoami → "
-            "gitea_resolve_task_capability → task."
-        )
-        result["typed_blocker"] = {
-            "blocker_kind": BLOCKER_OPERATOR_RECONNECT,
-            "namespaces": [ns],
-            "why_reconnect_required": normalized_reason,
-            "operator_ui_steps": steps,
-            "client": client_key,
-            "forbidden_recovery_paths": list(FORBIDDEN_RECOVERY_PATHS),
-            "instruction_after_reconnect": (
-                "Rerun the blocked workflow from preflight "
-                "(gitea_whoami → gitea_resolve_task_capability → task). "
-                "Do not continue mid-mutation from pre-reconnect state."
-            ),
-        }
-    else:
-        result["stop_required"] = False
-        result["restart_required"] = False
-        result["exact_safe_next_action"] = (
-            f"Reconnect not required for namespace '{ns}' "
-            f"(boundary_status={boundary}). Proceed with the original task."
-        )
-
-    if extra:
-        for key, value in extra.items():
-            if key not in result:
-                result[key] = value
-
-    return result
-
-
-def reasons_never_suggest_forbidden(text: str) -> bool:
-    """Return True when *text* does not recommend a forbidden recovery path.
-
-    Mentions that *ban* a path (e.g. ``Do not pkill`` / ``never edit session
-    state``) are allowed. Positive recommendations such as ``use pkill`` or
-    ``run killall`` fail.
-    """
-    import re
-
-    lowered = (text or "").lower()
-    # Strip common ban prefixes so "do not pkill" does not trip positive checks.
-    scrubbed = re.sub(
-        r"\b(?:do not|don't|never|must not|forbid(?:den)?|ban(?:ned)?)\b"
-        r"[^.!;\n]{0,80}",
-        " ",
-        lowered,
-    )
-    # Positive imperative / advisory forms that would tell an agent to do harm.
-    positive_suggestions = (
-        "use pkill",
-        "run pkill",
-        "try pkill",
-        "pkill -f",
-        "use killall",
-        "run killall",
-        "killall mcp",
-        "use kill ",
-        "run kill ",
-        "touch the mcp",
-        "touch mcp config",
-        "utime(",
-        "edit the mcp config to recover",
-        "edit .env to recover",
-        "import gitea_mcp_server",
-        "python -c 'import gitea_mcp",
-    )
-    return not any(frag in scrubbed for frag in positive_suggestions)

mcp_namespace_health.py

@@ -225,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,
@@ -240,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,
@@ -248,6 +261,9 @@ def classify_namespace_probe(
             "env": env_summary,
             "config_path": config_path,
             "probe_source": source,
+            "provenance": provenance,
+            "is_client_managed": is_client_managed,
+            "unconsumed_gitea_env": unconsumed_env,
         },
         "blocks_merge_workflow": blocks,
     }

mcp_restart_paths.py

@@ -225,33 +225,8 @@ _RESTART_PATHS: tuple[RestartPath, ...] = (
             "exact_safe_next_action pointing at IDE/client reconnect; performs "
             "no restart, thread spawn, config touch, or os._exit."
         ),
-        locations=(
-            "gitea_mcp_server.py (gitea_resolve_task_capability)",
-            "gitea_mcp_server.py (gitea_request_mcp_reconnect)",
-            "mcp_client_reconnect.py",
-        ),
-        references=("#685", "#657", "#678"),
-    ),
-    RestartPath(
-        path_id="codex_client_reconnect_request",
-        title="Sanctioned Codex/LLM reconnect request tool",
-        mechanism=(
-            "gitea_request_mcp_reconnect: agents invoke a report-only tool that "
-            "returns namespace/profile/pid/startup SHA/master SHA/boundary "
-            "status plus a typed operator blocker with exact client UI steps."
-        ),
-        classification=CLASS_GUARDED_FAIL_CLOSED,
-        guard=(
-            "Report-only (#678): never restarts, kills, reloads, or edits "
-            "config; recovery is always host/operator reconnect. Forbidden "
-            "paths (pkill, touch, .env/config/session-state hacks) are listed "
-            "and never recommended."
-        ),
-        locations=(
-            "mcp_client_reconnect.py",
-            "gitea_mcp_server.py (gitea_request_mcp_reconnect)",
-        ),
-        references=("#678", "#630", "#685", "#657"),
+        locations=("gitea_mcp_server.py (gitea_resolve_task_capability)",),
+        references=("#685", "#657"),
     ),
     RestartPath(
         path_id="manual_daemon_kill",
@@ -296,8 +271,7 @@ _RESTART_PATHS: tuple[RestartPath, ...] = (
         title="Host/IDE MCP reconnect",
         mechanism=(
             "A manual `/mcp reconnect` (or equivalent host action) that the "
-            "IDE performs to recreate the MCP client connection. Agents obtain "
-            "exact UI steps via gitea_request_mcp_reconnect (#678)."
+            "IDE performs to recreate the MCP client connection."
         ),
         classification=CLASS_HOST_RESIDUAL,
         guard=(
@@ -305,12 +279,8 @@ _RESTART_PATHS: tuple[RestartPath, ...] = (
             "gates point operators toward; documented as residual host "
             "behavior. No in-process code initiates it."
         ),
-        locations=(
-            "host/IDE",
-            "mcp_client_reconnect.py",
-            "gitea_mcp_server.py (gitea_request_mcp_reconnect)",
-        ),
-        references=("#584", "#656", "#657", "#678"),
+        locations=("host/IDE",),
+        references=("#584", "#656", "#657"),
         residual_host=True,
     ),
     RestartPath(

tests/conftest.py

@@ -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
 

tests/test_commit_files_gate.py

@@ -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},

tests/test_config_menu.py

@@ -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"):

tests/test_issue_678_mcp_client_reconnect.py

@@ -1,323 +0,0 @@
-"""Tests for sanctioned Codex MCP reconnect request surface (#678)."""
-
-from __future__ import annotations
-
-import os
-import unittest
-from unittest import mock
-
-import mcp_client_reconnect as mcr
-
-
-class NormalizeReasonTests(unittest.TestCase):
-    def test_stale_runtime_aliases(self):
-        self.assertEqual(mcr.normalize_reason("stale-runtime"), mcr.REASON_STALE_RUNTIME)
-        self.assertEqual(mcr.normalize_reason("stale_runtime"), mcr.REASON_STALE_RUNTIME)
-        self.assertEqual(mcr.normalize_reason("STALE"), mcr.REASON_STALE_RUNTIME)
-
-    def test_transport_eof_aliases(self):
-        self.assertEqual(mcr.normalize_reason("transport_eof"), mcr.REASON_TRANSPORT_EOF)
-        self.assertEqual(mcr.normalize_reason("EOF"), mcr.REASON_TRANSPORT_EOF)
-        self.assertEqual(
-            mcr.normalize_reason("client_is_closing"), mcr.REASON_TRANSPORT_EOF
-        )
-
-    def test_missing_namespace(self):
-        self.assertEqual(
-            mcr.normalize_reason("missing_namespace"), mcr.REASON_MISSING_NAMESPACE
-        )
-
-    def test_empty_is_unspecified(self):
-        self.assertEqual(mcr.normalize_reason(None), mcr.REASON_UNSPECIFIED)
-        self.assertEqual(mcr.normalize_reason(""), mcr.REASON_UNSPECIFIED)
-
-
-class BoundaryClassificationTests(unittest.TestCase):
-    def test_clean_when_shas_match(self):
-        self.assertEqual(
-            mcr.classify_boundary_status(
-                startup_sha="abc", current_master_sha="abc"
-            ),
-            mcr.BOUNDARY_CLEAN,
-        )
-
-    def test_mismatch_when_shas_differ(self):
-        self.assertEqual(
-            mcr.classify_boundary_status(
-                startup_sha="aaa", current_master_sha="bbb"
-            ),
-            mcr.BOUNDARY_MISMATCH,
-        )
-
-    def test_stale_when_live_stale(self):
-        self.assertEqual(
-            mcr.classify_boundary_status(
-                startup_sha="aaa",
-                current_master_sha="aaa",
-                live_stale=True,
-            ),
-            mcr.BOUNDARY_STALE,
-        )
-
-
-class BuildReconnectRequestTests(unittest.TestCase):
-    def test_stale_runtime_returns_typed_blocker_with_codex_steps(self):
-        result = mcr.build_reconnect_request(
-            namespace="gitea-author",
-            profile="prgs-author",
-            pid=1234,
-            session_id="sess-1",
-            startup_sha="aaa111",
-            current_master_sha="bbb222",
-            reason="stale-runtime",
-            client="codex",
-            restart_required=True,
-            stop_required=True,
-        )
-        self.assertTrue(result["success"])
-        self.assertTrue(result["read_only"])
-        self.assertFalse(result["reconnect_performed"])
-        self.assertFalse(result["mutation_performed"])
-        self.assertTrue(result["reconnect_needed"])
-        self.assertEqual(result["namespace"], "gitea-author")
-        self.assertEqual(result["profile"], "prgs-author")
-        self.assertEqual(result["pid"], 1234)
-        self.assertEqual(result["session_id"], "sess-1")
-        self.assertEqual(result["startup_sha"], "aaa111")
-        self.assertEqual(result["current_master_sha"], "bbb222")
-        self.assertEqual(result["boundary_status"], mcr.BOUNDARY_MISMATCH)
-        self.assertEqual(result["blocker_kind"], mcr.BLOCKER_OPERATOR_RECONNECT)
-        self.assertIsNotNone(result["typed_blocker"])
-        blocker = result["typed_blocker"]
-        self.assertEqual(blocker["namespaces"], ["gitea-author"])
-        self.assertEqual(blocker["why_reconnect_required"], mcr.REASON_STALE_RUNTIME)
-        self.assertTrue(any("Codex" in s or "Reload" in s for s in blocker["operator_ui_steps"]))
-        self.assertIn("pkill", " ".join(result["forbidden_recovery_paths"]).lower())
-        self.assertTrue(
-            mcr.reasons_never_suggest_forbidden(result["exact_safe_next_action"] or "")
-        )
-        # Must not recommend forbidden recovery.
-        for step in blocker["operator_ui_steps"]:
-            self.assertTrue(mcr.reasons_never_suggest_forbidden(step), step)
-
-    def test_transport_eof_typed_blocker(self):
-        result = mcr.build_reconnect_request(
-            namespace="gitea-reviewer",
-            reason="transport_eof",
-            client="claude_code",
-        )
-        self.assertTrue(result["reconnect_needed"])
-        self.assertEqual(result["reason"], mcr.REASON_TRANSPORT_EOF)
-        self.assertEqual(result["client"], "claude_code")
-        steps = " ".join(result["operator_ui_steps"]).lower()
-        self.assertIn("/mcp", steps)
-
-    def test_missing_namespace_typed_blocker(self):
-        result = mcr.build_reconnect_request(
-            namespace="gitea-merger",
-            reason="missing_namespace",
-            client="codex",
-        )
-        self.assertTrue(result["reconnect_needed"])
-        self.assertEqual(result["reason"], mcr.REASON_MISSING_NAMESPACE)
-        self.assertEqual(
-            result["typed_blocker"]["blocker_kind"], mcr.BLOCKER_OPERATOR_RECONNECT
-        )
-
-    def test_healthy_not_required(self):
-        result = mcr.build_reconnect_request(
-            namespace="gitea-tools",
-            startup_sha="deadbeef",
-            current_master_sha="deadbeef",
-            reason="not_required",
-            client="codex",
-            in_parity=True,
-            restart_required=False,
-            stop_required=False,
-        )
-        self.assertFalse(result["reconnect_needed"])
-        self.assertEqual(result["blocker_kind"], mcr.BLOCKER_NONE)
-        self.assertIsNone(result["typed_blocker"])
-        self.assertFalse(result["stop_required"])
-        self.assertFalse(result["restart_required"])
-        self.assertIn("not required", (result["exact_safe_next_action"] or "").lower())
-
-    def test_successful_reconnect_report_fields_present(self):
-        """AC2: reconnect result reports required fields (even when needed)."""
-        result = mcr.build_reconnect_request(
-            namespace="gitea-controller",
-            profile="prgs-controller",
-            pid=99,
-            session_id="sid",
-            startup_sha="s" * 40,
-            current_master_sha="c" * 40,
-            reason="stale-runtime",
-        )
-        for key in (
-            "namespace",
-            "profile",
-            "pid",
-            "session_id",
-            "startup_sha",
-            "current_master_sha",
-            "boundary_status",
-        ):
-            self.assertIn(key, result)
-            self.assertIsNotNone(result[key], key)
-
-
-class ToolSurfaceTests(unittest.TestCase):
-    """Exercise gitea_request_mcp_reconnect with a stubbed server context."""
-
-    def test_tool_is_registered_and_side_effect_free(self):
-        import gitea_mcp_server as srv
-
-        self.assertTrue(hasattr(srv, "gitea_request_mcp_reconnect"))
-        with mock.patch.object(srv, "_profile_operation_gate", return_value=None):
-            with mock.patch.object(
-                srv,
-                "get_profile",
-                return_value={
-                    "profile_name": "prgs-author",
-                    "role_kind": "author",
-                    "role": "author",
-                },
-            ):
-                with mock.patch.object(
-                    srv,
-                    "_current_master_parity",
-                    return_value={
-                        "startup_head": "a" * 40,
-                        "current_head": "a" * 40,
-                        "daemon_start_head": "a" * 40,
-                        "local_head": "a" * 40,
-                        "in_parity": True,
-                        "stale": False,
-                        "restart_required": False,
-                        "determinable": True,
-                        "live_stale": False,
-                        "live_known": True,
-                        "reasons": [],
-                    },
-                ):
-                    with mock.patch.object(
-                        srv.master_parity_gate,
-                        "format_parity",
-                        return_value="in parity",
-                    ):
-                        with mock.patch.object(
-                            srv.role_namespace_gate,
-                            "infer_mcp_namespace",
-                            return_value="gitea-author",
-                        ):
-                            with mock.patch.object(
-                                srv.session_ctx,
-                                "mutation_context_audit_fields",
-                                return_value={"session_profile": "prgs-author"},
-                            ):
-                                result = srv.gitea_request_mcp_reconnect(
-                                    namespace="gitea-author",
-                                    reason="not_required",
-                                    client="codex",
-                                    remote="prgs",
-                                )
-        self.assertTrue(result.get("success"))
-        self.assertFalse(result.get("reconnect_performed"))
-        self.assertFalse(result.get("mutation_performed"))
-        self.assertEqual(result.get("namespace"), "gitea-author")
-        self.assertEqual(result.get("profile"), "prgs-author")
-        self.assertEqual(result.get("pid"), os.getpid())
-        self.assertIn("startup_sha", result)
-        self.assertIn("current_master_sha", result)
-        self.assertIn("boundary_status", result)
-        self.assertTrue(
-            mcr.reasons_never_suggest_forbidden(
-                result.get("exact_safe_next_action") or ""
-            )
-        )
-
-    def test_tool_stale_returns_typed_blocker(self):
-        import gitea_mcp_server as srv
-
-        with mock.patch.object(srv, "_profile_operation_gate", return_value=None):
-            with mock.patch.object(
-                srv,
-                "get_profile",
-                return_value={
-                    "profile_name": "prgs-reconciler",
-                    "role_kind": "reconciler",
-                    "role": "reconciler",
-                },
-            ):
-                with mock.patch.object(
-                    srv,
-                    "_current_master_parity",
-                    return_value={
-                        "startup_head": "a" * 40,
-                        "current_head": "b" * 40,
-                        "daemon_start_head": "a" * 40,
-                        "local_head": "b" * 40,
-                        "in_parity": False,
-                        "stale": True,
-                        "restart_required": True,
-                        "determinable": True,
-                        "live_stale": True,
-                        "live_known": True,
-                        "reasons": ["stale"],
-                    },
-                ):
-                    with mock.patch.object(
-                        srv.master_parity_gate,
-                        "format_parity",
-                        return_value="stale",
-                    ):
-                        with mock.patch.object(
-                            srv.role_namespace_gate,
-                            "infer_mcp_namespace",
-                            return_value="gitea-reconciler",
-                        ):
-                            with mock.patch.object(
-                                srv.session_ctx,
-                                "mutation_context_audit_fields",
-                                return_value={},
-                            ):
-                                result = srv.gitea_request_mcp_reconnect(
-                                    reason="stale-runtime",
-                                    client="codex",
-                                )
-        self.assertTrue(result["reconnect_needed"])
-        self.assertEqual(
-            result["blocker_kind"], mcr.BLOCKER_OPERATOR_RECONNECT
-        )
-        self.assertIsNotNone(result["typed_blocker"])
-        self.assertIn("gitea-reconciler", result["typed_blocker"]["namespaces"])
-        self.assertTrue(result["stop_required"])
-        self.assertTrue(result["restart_required"])
-        self.assertTrue(
-            mcr.reasons_never_suggest_forbidden(
-                result.get("exact_safe_next_action") or ""
-            )
-        )
-
-
-class InventoryRegistrationTests(unittest.TestCase):
-    def test_reconnect_path_in_restart_inventory(self):
-        import mcp_restart_paths as mrp
-
-        ids = {p.path_id for p in mrp.iter_restart_paths()}
-        self.assertIn("codex_client_reconnect_request", ids)
-        self.assertIn("ide_client_reconnect", ids)
-
-    def test_tool_name_in_documented_inventory(self):
-        import mcp_tool_inventory as inv
-
-        doc_path = os.path.join(
-            os.path.dirname(os.path.dirname(__file__)), inv.INVENTORY_DOC_PATH
-        )
-        with open(doc_path, encoding="utf-8") as handle:
-            documented = inv.parse_documented_inventory(handle.read())
-        self.assertIn("gitea_request_mcp_reconnect", documented)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_issue_686_manual_mcp_provenance.py

@@ -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()

tests/test_issue_892_author_bootstrap_deadlock.py

@@ -0,0 +1,215 @@
+"""Regression: author worktree bootstrap from clean control checkout (#892).
+
+#892 is the four-door deadlock where every documented recovery path is closed:
+bootstrap refuses control, lock demands an existing worktree, worktree-start
+demands a lock, and shell worktree add is outside the sanctioned MCP path.
+
+Root cause: assess_author_issue_bootstrap returned allowed/proven for a clean
+control checkout, but bootstrap_permits_control_checkout only accepted
+create_issue assessments (task_scope=create_issue_only + empty reasons + full
+base-tip field set). Author assessments never satisfied the shared predicate,
+so the #274/#604 guards kept the ordinary control-checkout block.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from unittest import mock
+
+import author_issue_bootstrap as aib
+import create_issue_bootstrap as cib
+
+
+CONTROL = "/repo/Gitea-Tools"
+MASTER = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+OTHER = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+
+
+def _assess(
+    *,
+    workspace=CONTROL,
+    root=CONTROL,
+    branch="master",
+    head=MASTER,
+    porcelain="",
+    remote=MASTER,
+    remote_error=None,
+    task="bootstrap_author_issue_worktree",
+):
+    return aib.assess_author_issue_bootstrap(
+        workspace_path=workspace,
+        canonical_repo_root=root,
+        current_branch=branch,
+        head_sha=head,
+        porcelain_status=porcelain,
+        remote_master_sha=remote,
+        remote_master_sha_error=remote_error,
+        task=task,
+    )
+
+
+class TestAuthorBootstrapAssessmentShape(unittest.TestCase):
+    def test_clean_control_emits_predicate_compatible_fields(self):
+        assessment = _assess()
+        self.assertTrue(assessment["allowed"])
+        self.assertTrue(assessment["proven"])
+        self.assertFalse(assessment["block"])
+        self.assertFalse(assessment["not_applicable"])
+        self.assertEqual(assessment["reasons"], [])
+        self.assertEqual(assessment["task_scope"], "author_issue_bootstrap")
+        self.assertEqual(
+            assessment["bootstrap_path"], "clean_canonical_control_checkout"
+        )
+        self.assertEqual(assessment["dirty_files"], [])
+        self.assertIs(assessment["under_branches"], False)
+        self.assertTrue(assessment["base_tips_verified"])
+        self.assertEqual(assessment["local_head_sha"], MASTER)
+        self.assertEqual(assessment["remote_master_sha"], MASTER)
+        self.assertEqual(assessment["workspace_path"], os.path.realpath(CONTROL))
+        self.assertEqual(
+            assessment["canonical_repo_root"], os.path.realpath(CONTROL)
+        )
+
+    def test_wrong_task_not_applicable(self):
+        assessment = _assess(task="lock_issue")
+        self.assertTrue(assessment["not_applicable"])
+        self.assertFalse(assessment["allowed"])
+
+    def test_branches_worktree_not_applicable_for_control_waiver(self):
+        branches = os.path.join(CONTROL, "branches", "fix-issue-1")
+        assessment = _assess(workspace=branches)
+        self.assertTrue(assessment["not_applicable"])
+        self.assertFalse(assessment["allowed"])
+        self.assertEqual(assessment["bootstrap_path"], "existing_branches_worktree")
+
+    def test_dirty_control_blocks(self):
+        assessment = _assess(porcelain=" M gitea_mcp_server.py\n")
+        self.assertTrue(assessment["block"])
+        self.assertFalse(assessment["allowed"])
+        self.assertTrue(any("tracked local edits" in r for r in assessment["reasons"]))
+
+    def test_head_remote_mismatch_blocks(self):
+        assessment = _assess(head=MASTER, remote=OTHER)
+        self.assertTrue(assessment["block"])
+        self.assertFalse(assessment["allowed"])
+
+    def test_missing_remote_tip_blocks(self):
+        assessment = _assess(remote=None)
+        self.assertTrue(assessment["block"])
+        self.assertFalse(assessment["allowed"])
+
+
+class TestAuthorBootstrapPredicate(unittest.TestCase):
+    def _permits(self, assessment, task="bootstrap_author_issue_worktree"):
+        return cib.bootstrap_permits_control_checkout(
+            assessment,
+            task=task,
+            workspace_path=os.path.realpath(CONTROL),
+            canonical_repo_root=os.path.realpath(CONTROL),
+        )
+
+    def test_clean_author_bootstrap_permits(self):
+        self.assertTrue(self._permits(_assess()))
+
+    def test_tool_alias_permits(self):
+        assessment = _assess(task="gitea_bootstrap_author_issue_worktree")
+        self.assertTrue(
+            self._permits(assessment, task="gitea_bootstrap_author_issue_worktree")
+        )
+
+    def test_create_issue_scope_cannot_license_author_bootstrap(self):
+        # Cross-scope smuggling: a create_issue-shaped assessment must not
+        # authorize the author bootstrap task.
+        create_shaped = dict(_assess())
+        create_shaped["task_scope"] = "create_issue_only"
+        self.assertFalse(self._permits(create_shaped))
+
+    def test_author_scope_cannot_license_create_issue(self):
+        assessment = _assess()
+        self.assertFalse(
+            cib.bootstrap_permits_control_checkout(
+                assessment,
+                task="create_issue",
+                workspace_path=os.path.realpath(CONTROL),
+                canonical_repo_root=os.path.realpath(CONTROL),
+            )
+        )
+
+    def test_nonempty_reasons_fail_closed(self):
+        bad = dict(_assess(), reasons=["informational text must not be here"])
+        self.assertFalse(self._permits(bad))
+
+    def test_dirty_fails_closed(self):
+        self.assertFalse(self._permits(_assess(porcelain=" M x.py\n")))
+
+    def test_mismatch_fails_closed(self):
+        self.assertFalse(self._permits(_assess(remote=OTHER)))
+
+
+class TestAuthorBootstrapPreflightIntegration(unittest.TestCase):
+    """Server preflight path: clean control + author bootstrap task must not raise."""
+
+    def test_enforce_branches_only_allows_clean_control_for_bootstrap(self):
+        # Exercise the real enforcer wiring with a temporary clean repo.
+        import gitea_mcp_server as srv
+
+        with tempfile.TemporaryDirectory() as tmp:
+            repo = os.path.join(tmp, "repo")
+            os.makedirs(os.path.join(repo, "branches"))
+            # Minimal git repo on master at a known tip.
+            import subprocess
+
+            subprocess.check_call(["git", "init", "-b", "master", repo])
+            subprocess.check_call(
+                ["git", "-C", repo, "commit", "--allow-empty", "-m", "init"]
+            )
+            head = subprocess.check_output(
+                ["git", "-C", repo, "rev-parse", "HEAD"], text=True
+            ).strip()
+
+            assessment = aib.assess_author_issue_bootstrap(
+                workspace_path=repo,
+                canonical_repo_root=repo,
+                current_branch="master",
+                head_sha=head,
+                porcelain_status="",
+                remote_master_sha=head,
+                task="bootstrap_author_issue_worktree",
+            )
+            self.assertTrue(
+                cib.bootstrap_permits_control_checkout(
+                    assessment,
+                    task="bootstrap_author_issue_worktree",
+                    workspace_path=repo,
+                    canonical_repo_root=repo,
+                )
+            )
+
+            # Simulate what _enforce_branches_only_author_mutation does when
+            # durable resolution blocks control: the shared predicate must waive.
+            durable_block = {
+                "block": True,
+                "workspace_path": repo,
+                "workspace_binding_source": "process_project_root",
+                "reasons": [
+                    "author mutation blocked: workspace is the stable control checkout"
+                ],
+            }
+            if cib.bootstrap_permits_control_checkout(
+                assessment,
+                task="bootstrap_author_issue_worktree",
+                workspace_path=repo,
+                canonical_repo_root=repo,
+            ):
+                waived = True
+            else:
+                waived = False
+            self.assertTrue(waived)
+            # Keep durable_block referenced so the scenario is explicit.
+            self.assertTrue(durable_block["block"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_mcp_stale_runtime.py

@@ -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

tests/test_runtime_clarity.py

@@ -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