feat(mcp): client/session-aware runtime ownership and provenance (#948)

Two surfaces reported different provenance for one process.
`gitea_get_runtime_context` read the live environment and reported
`client_managed`; `mcp_namespace_health.classify_namespace_probe` derived
provenance from `_safe_env_summary()`, whose `SAFE_ENV_KEYS` allowlist never
contained `GITEA_CLIENT_MANAGED`, `GITEA_MCP_CLIENT_MANAGED`, or
`GITEA_SERVER_PROVENANCE`. That lookup could only ever miss, so the health
surface was structurally incapable of returning anything but `manual_launch`.

Neither model could name which client or which session owned a runtime, so a
healthy daemon serving a second client was indistinguishable from a duplicate,
and the profile-wide duplicate scan walled the whole fleet.

Introduce `mcp_worker_identity` as the one authority, splitting two claims the
old code ran together:

* launch provenance — was this hand-launched from a terminal? Answered from the
  environment, which is legitimate because the launcher sets it. Preserves the
  #686 wall unchanged.
* session ownership — which live client session owns this runtime now? Answered
  only from a live attachment record; no environment flag can establish it.

The module provides collision-resistant worker identities
(`<llm-name>-<UTC-timestamp>-<short-sha>`), an atomic SQLite registry with
fencing epochs, heartbeat-based liveness, generation takeover that supersedes
only a non-live claimant, cohort classification, and failure scoping.

Behaviour changes:

* Registering an existing worker identity fails closed; it is never replaced,
  adopted, or merged with. The caller mints a different identity instead.
* A generation held by a live session cannot be claimed by a second one. A
  generation whose claimant is not live is taken over with a higher fencing
  epoch, so stale ownership cannot permanently strand a healthy daemon.
* A superseded session presenting an old epoch is refused and performs no write.
* Liveness comes from heartbeat freshness; a live PID cannot resurrect an
  expired record, and a dead PID withdraws liveness.
* Workers sharing a role or profile no longer trigger a profile-wide duplicate
  block, provided each carries a distinct identity. Processes with no identity
  evidence remain classified as duplicates, so the #686 wall still holds.
* Runtime failures are scoped to a worker identity or generation, never to a
  profile or the fleet.
* Reconnect guidance no longer defaults to Codex. An unidentified client gets
  host-agnostic steps; `gitea_request_mcp_reconnect(client=...)` defaults to
  resolving the client from the live attachment record.
* `resolve_bound_remote` keeps a bound namespace on its remote instead of
  falling through to the `dadeschools` library default.

Absence of proof is now reported as `unproven` rather than asserted as
`manual_launch`. Both still fail closed — `is_client_managed` is unchanged, so
nothing previously refused is now permitted — but remediation names the proof
that is actually missing instead of describing a terminal launch it cannot
evidence. The #686 test is updated for that vocabulary and keeps every
wall-preserving assertion.

Threat-model anchors and their citations in docs/remote-mcp/threat-model.md are
restamped for the line movement in gitea_mcp_server.py.

Tests: tests/test_issue_948_client_session_provenance.py adds 43 cases covering
Codex/Gemini/Antigravity/Claude attachment, same-client new session, cross-client
takeover after a session ends, two live conflicting sessions, stale records,
missing attachment proof, environment flags without attachment, mixed
generations, duplicate cohorts, the hardcoded-client regression, explicit PRGS
selection, default-remote host drift, cross-surface agreement, and fail-closed
handling without false reconnect loops. Synthetic identifiers throughout.

Full suite from a branches/ worktree: 28F/5953P/6S at head vs 28F/5910P/6S at
merge base 8eada1fb, identical failing ID sets.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01F6Vomtndpq2gSBa88Tfcwy
This commit is contained in:
2026-07-29 02:52:18 -04:00
co-authored by Claude Opus 5
parent 8eada1fbe4
commit 1dd30ecb15
8 changed files with 2491 additions and 95 deletions
+22 -22
View File
@@ -11,7 +11,7 @@
"generated_against_commit": "ca5f078d8a575ea3e2991771f8b4ea85e3dcaaa0",
"anchors": [
{
"anchor": "gitea_mcp_server.py:24864",
"anchor": "gitea_mcp_server.py:25087",
"expect": "mcp_daemon_guard.bind_native_mcp_transport()"
},
{
@@ -27,11 +27,11 @@
"expect": "def assess_transport_for_auth_mint"
},
{
"anchor": "gitea_mcp_server.py:9191",
"anchor": "gitea_mcp_server.py:9192",
"expect": "assess_transport_for_auth_mint()"
},
{
"anchor": "gitea_mcp_server.py:9440",
"anchor": "gitea_mcp_server.py:9441",
"expect": "assess_transport_for_auth_mint()"
},
{
@@ -39,31 +39,31 @@
"expect": "The transport is selected by deployment configuration"
},
{
"anchor": "gitea_mcp_server.py:15481",
"anchor": "gitea_mcp_server.py:15630",
"expect": "def _is_client_managed_process"
},
{
"anchor": "gitea_mcp_server.py:15511",
"anchor": "gitea_mcp_server.py:15644",
"expect": "def _provenance_mutation_block"
},
{
"anchor": "gitea_mcp_server.py:15519",
"anchor": "gitea_mcp_server.py:15652",
"expect": "unsupported_manual_launch"
},
{
"anchor": "gitea_mcp_server.py:19070",
"anchor": "gitea_mcp_server.py:19217",
"expect": "server_provenance"
},
{
"anchor": "gitea_mcp_server.py:21581",
"anchor": "gitea_mcp_server.py:21741",
"expect": "def _check_mcp_runtimes_diagnostics"
},
{
"anchor": "gitea_mcp_server.py:21601",
"anchor": "gitea_mcp_server.py:21761",
"expect": "\"ps\", \"-o\", \"pid,lstart,command\""
},
{
"anchor": "gitea_mcp_server.py:21645",
"anchor": "gitea_mcp_server.py:21805",
"expect": "\"ps\", \"eww\""
},
{
@@ -107,19 +107,19 @@
"expect": "def assert_keychain_access_allowed"
},
{
"anchor": "gitea_mcp_server.py:19327",
"anchor": "gitea_mcp_server.py:19487",
"expect": "def gitea_list_profiles"
},
{
"anchor": "gitea_mcp_server.py:19378",
"anchor": "gitea_mcp_server.py:19538",
"expect": "gitea_config.resolve_token(p)"
},
{
"anchor": "gitea_mcp_server.py:19691",
"anchor": "gitea_mcp_server.py:19851",
"expect": "def gitea_audit_config"
},
{
"anchor": "gitea_mcp_server.py:19713",
"anchor": "gitea_mcp_server.py:19873",
"expect": "service_summaries(config)"
},
{
@@ -135,19 +135,19 @@
"expect": "_keychain_token(auth.get(\"id\"))"
},
{
"anchor": "gitea_mcp_server.py:17776",
"anchor": "gitea_mcp_server.py:17909",
"expect": "\"jenkins-mcp\""
},
{
"anchor": "gitea_mcp_server.py:17782",
"anchor": "gitea_mcp_server.py:17915",
"expect": "external-mcp"
},
{
"anchor": "gitea_mcp_server.py:17803",
"anchor": "gitea_mcp_server.py:17936",
"expect": "\"glitchtip-mcp\""
},
{
"anchor": "gitea_mcp_server.py:17808",
"anchor": "gitea_mcp_server.py:17941",
"expect": "external-mcp"
},
{
@@ -183,7 +183,7 @@
"expect": "mutation_safe"
},
{
"anchor": "gitea_mcp_server.py:19171",
"anchor": "gitea_mcp_server.py:19331",
"expect": "def gitea_assess_master_parity"
},
{
@@ -195,11 +195,11 @@
"expect": "AUTHOR_WORKTREE_ENV"
},
{
"anchor": "gitea_mcp_server.py:2351",
"anchor": "gitea_mcp_server.py:2352",
"expect": "/tmp/gitea_issue_lock.json"
},
{
"anchor": "gitea_mcp_server.py:10956",
"anchor": "gitea_mcp_server.py:10957",
"expect": "def gitea_bootstrap_author_issue_worktree"
},
{
@@ -239,7 +239,7 @@
"expect": "os.getpid()"
},
{
"anchor": "gitea_mcp_server.py:12870",
"anchor": "gitea_mcp_server.py:12871",
"expect": "owner_pid_alive"
}
]