Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 92 Pull Requests 13 Actions Packages Projects Releases Wiki Activity

Remote-MCP 01: Inventory every stdio- and localhost-coupled assumption in the MCP server #930

New Issue
Closed
opened 2026-07-26 00:29:18 -05:00 by jcwalker3 · 1 comment
jcwalker3 commented 2026-07-26 00:29:18 -05:00
Owner
Copy Link
Copy Source

Parent epic: #929.
Depends on: nothing. This is the first implementation-ready child of the epic.

Problem

The migration cannot be planned against guesses. gitea_mcp_server.py is roughly 23,700 lines and the stdio assumption is spread across the transport bind, the daemon provenance guard, the parity gate, the credential resolver, the worktree tools, and the lock and lease stores. Nobody currently has a list of what actually breaks when the process stops being local. Every later child in this epic needs that list to scope itself, so producing it is the blocking first step.

Scope

Produce a committed inventory document, docs/remote-mcp/coupling-inventory.md, that enumerates every place the server depends on being a local, client-spawned, stdio-attached process on the operator's machine.

For each finding record: the file and line anchor, the category, what the code assumes today, what it would observe on a remote host, and which epic child owns the fix.

Categories to cover, at minimum:

  • Transport bind. The literal bind_native_mcp_transport(transport="stdio") call and every downstream reader of the bound transport, including assess_transport_for_auth_mint.
  • Launch provenance. The GITEA_CLIENT_MANAGED check, the stdio-pipe detection, the manual-launch refusal, the duplicate-role-process peer scan, and RECOGNIZED_GITEA_ENV_KEYS.
  • Role binding. Every read of GITEA_MCP_PROFILE and anything that treats "this process" as "this role".
  • Credentials. gitea_config.resolve_token, keychain_auth, assert_keychain_access_allowed, and any other git credential fill path.
  • Runtime freshness. gitea_assess_master_parity and its startup-HEAD-versus-disk-HEAD comparison, plus every gate that consumes mutation_safe.
  • Local filesystem. Worktree bootstrap and binding, branches/ path assumptions, /tmp pointer files, and the startup conflict-marker scan that walks the install directory.
  • Durable state. Lock stores, lease stores, session state, and the control-plane database, including anything keyed on a local PID or on owner_pid_alive.

Acceptance criteria

  • docs/remote-mcp/coupling-inventory.md exists and is committed.
  • Every category above has at least one entry, or an explicit, justified statement that the category has no coupling.
  • Every entry carries a file and line anchor that resolves at the commit under review.
  • Every entry is assigned to exactly one epic child, and every child from 2 through 10 is named by at least one entry.
  • Entries are classified as one of: portable as written, needs a seam, needs a replacement, or cannot be remote.
  • A summary table counts entries per category and per classification.
  • The document states the commit it was generated against.

Verification

  • A reviewer can pick any five entries at random and confirm the line anchor and the described behavior.
  • Line anchors are checked against the reviewed commit, not against a stale local checkout.

Non-goals

  • Any change to server behavior. This child adds documentation only.
  • Choosing the remote transport, the credential provider, or the deployment target. Those are decided by later children using this inventory as input.
Parent epic: #929. Depends on: nothing. This is the first implementation-ready child of the epic. ## Problem The migration cannot be planned against guesses. `gitea_mcp_server.py` is roughly 23,700 lines and the stdio assumption is spread across the transport bind, the daemon provenance guard, the parity gate, the credential resolver, the worktree tools, and the lock and lease stores. Nobody currently has a list of what actually breaks when the process stops being local. Every later child in this epic needs that list to scope itself, so producing it is the blocking first step. ## Scope Produce a committed inventory document, `docs/remote-mcp/coupling-inventory.md`, that enumerates every place the server depends on being a local, client-spawned, stdio-attached process on the operator's machine. For each finding record: the file and line anchor, the category, what the code assumes today, what it would observe on a remote host, and which epic child owns the fix. Categories to cover, at minimum: - **Transport bind.** The literal `bind_native_mcp_transport(transport="stdio")` call and every downstream reader of the bound transport, including `assess_transport_for_auth_mint`. - **Launch provenance.** The `GITEA_CLIENT_MANAGED` check, the stdio-pipe detection, the manual-launch refusal, the duplicate-role-process peer scan, and `RECOGNIZED_GITEA_ENV_KEYS`. - **Role binding.** Every read of `GITEA_MCP_PROFILE` and anything that treats "this process" as "this role". - **Credentials.** `gitea_config.resolve_token`, `keychain_auth`, `assert_keychain_access_allowed`, and any other `git credential fill` path. - **Runtime freshness.** `gitea_assess_master_parity` and its startup-HEAD-versus-disk-HEAD comparison, plus every gate that consumes `mutation_safe`. - **Local filesystem.** Worktree bootstrap and binding, `branches/` path assumptions, `/tmp` pointer files, and the startup conflict-marker scan that walks the install directory. - **Durable state.** Lock stores, lease stores, session state, and the control-plane database, including anything keyed on a local PID or on `owner_pid_alive`. ## Acceptance criteria - `docs/remote-mcp/coupling-inventory.md` exists and is committed. - Every category above has at least one entry, or an explicit, justified statement that the category has no coupling. - Every entry carries a file and line anchor that resolves at the commit under review. - Every entry is assigned to exactly one epic child, and every child from 2 through 10 is named by at least one entry. - Entries are classified as one of: portable as written, needs a seam, needs a replacement, or cannot be remote. - A summary table counts entries per category and per classification. - The document states the commit it was generated against. ## Verification - A reviewer can pick any five entries at random and confirm the line anchor and the described behavior. - Line anchors are checked against the reviewed commit, not against a stale local checkout. ## Non-goals - Any change to server behavior. This child adds documentation only. - Choosing the remote transport, the credential provider, or the deployment target. Those are decided by later children using this inventory as input.
jcwalker3 added status:pr-open and removed status:ready labels 2026-07-26 01:10:49 -05:00
jcwalker3 commented 2026-07-26 01:24:30 -05:00
Author
Owner
Copy Link
Copy Source

Reviewer handoff — issue #930 → PR #940

[THREAD STATE LEDGER]

what is true now

  • Issue: #930 — Remote-MCP 01: Inventory every stdio- and localhost-coupled assumption in the MCP server. Child 1 of epic #929.
  • PR number: 940
  • PR title: docs(remote-mcp): inventory stdio- and localhost-coupled assumptions (#930)
  • PR head SHA (full): 97bc190fc2f6da6893cd2b6613ba5b9992d3f379
  • Head branch: docs/issue-930-remote-mcp-coupling-inventory
  • Base branch: master
  • Base head at open: 7bf4f1258451823a55b36d2157e74f8457165088
  • Inspected source commit: 7bf4f1258451823a55b36d2157e74f8457165088
  • Commits behind base: 0
  • PR state: open, mergeable, no conflicts, no status checks required
  • Issue linkage: PR body carries the literal Closes #930
  • Author identity: jcwalker3, profile prgs-author, namespace gitea-author
  • Server-side decision state: no review record of any kind exists on PR #940; reviews is empty, approval_at_current_head is false, and no reviewer or merger lease is held.
  • Local verdict/state: author-side work is complete and pushed. The author holds no review opinion and recorded none. Nothing has landed on master.

what changed

  • One commit, 97bc190fc2f6da6893cd2b6613ba5b9992d3f379, adding exactly one file:
A  docs/remote-mcp/coupling-inventory.md    (+230, -0)
  • No other file is added, edited, renamed, or deleted. No source module, test, configuration, or dependency is touched.
  • Issue #930 carried the status:pr-open label from the moment PR #940 was opened.

what is blocked

  • Blocker classification: no blocker
  • Nothing prevents review. PR #940 is open, sits 0 commits behind master, reports mergeable with no conflicts, and requires no status checks.
  • Epic children #931 through #939 are not implemented here and retain the status:blocked label, by design — they depend on this inventory landing first.

who/what acts next

  • Next actor: reviewer, using profile prgs-reviewer via the gitea-reviewer MCP namespace.
  • Required action: perform a first review of PR #940 at head 97bc190fc2f6da6893cd2b6613ba5b9992d3f379 and record a verdict through the review API.
  • Do not do: do not review, approve, or record any verdict from this author session or from the prgs-author profile; do not merge PR #940; do not amend, rebase, or force-push the head branch; do not begin implementation of #931 through #939 before this PR lands on master; do not reuse any verdict taken against a head SHA other than 97bc190fc2f6da6893cd2b6613ba5b9992d3f379.

Canonical Issue State

STATE: implementation complete on branch docs/issue-930-remote-mcp-coupling-inventory; PR #940 is in open state at head 97bc190fc2f6da6893cd2b6613ba5b9992d3f379 and is awaiting a first review verdict.

WHO_IS_NEXT: reviewer

NEXT_ACTION: review PR #940 at head 97bc190fc2f6da6893cd2b6613ba5b9992d3f379 from the prgs-reviewer profile and record a verdict via the review API.

BLOCKERS: none. Blocker classification: no blocker.

WHAT_HAPPENED: The author produced docs/remote-mcp/coupling-inventory.md, an inventory of every place the MCP server depends on being a local, client-spawned, stdio-attached process on the operator's machine. It holds 62 findings across the seven categories the issue names, carrying 69 line anchors drawn from 20 distinct source files, each anchor taken against commit 7bf4f1258451823a55b36d2157e74f8457165088. Every finding records the file and line, what the code assumes today, what the same code would observe on a remote host, a classification, and exactly one owning epic child. The work was committed as 97bc190fc2f6da6893cd2b6613ba5b9992d3f379, pushed to prgs, and opened as PR #940 against master.

WHY: Epic #929 cannot be scoped against guesses. Every later child needs the list of what actually breaks when the server process stops being local, so producing that list is the blocking first step and the sole prerequisite of #931 through #939.

VALIDATION: 62 findings. 69 line anchors confirmed to resolve. 20 distinct source files cited. All 7 required categories carry at least one finding, so no category needed a no-coupling justification. All 9 epic children #931 through #939 are each named by at least one finding, and every finding names exactly one child.

  • Category counts — transport bind 9, launch provenance 12, role binding 7, credentials 6, runtime freshness 6, local filesystem 11, durable state 11.
  • Classification counts — portable as written 5, needs a seam 16, needs a replacement 26, cannot be remote 15.
  • Per-child counts — #931 = 9, #932 = 7, #933 = 6, #934 = 9, #935 = 6, #936 = 8, #937 = 13, #938 = 2, #939 = 2.

Two mechanical checks were run against the tree before commit. First, every `file.py:NNN` reference was extracted from the document and resolved against the checked-out tree: all 69 exist, all are in range, and each cited line matches the behavior its finding describes. Second, the table rows were parsed and re-tallied independently; the computed per-category, per-classification, category-by-classification, and per-child totals all equal the values printed in the document's own summary tables.

Because this change adds one file and edits none, no pre-existing line number shifts between 7bf4f1258451823a55b36d2157e74f8457165088 and the PR head, so every anchor stays accurate at the head under review. The remote branch head and the PR head are the identical SHA 97bc190fc2f6da6893cd2b6613ba5b9992d3f379, confirmed via git ls-remote prgs refs/heads/docs/issue-930-remote-mcp-coupling-inventory.

SCOPE: documentation only. No production behavior changed. The issue's non-goals — choosing the remote transport, the credential provider, or the deployment target — are all left to later children.

RELATED_PRS: #940

LAST_UPDATED_BY: jcwalker3 (profile prgs-author, namespace gitea-author, role author)

NEXT_PROMPT:

Review PR #940 on prgs/Scaled-Tech-Consulting/Gitea-Tools.

Use the gitea-reviewer MCP namespace with profile prgs-reviewer. Call
gitea_whoami(remote="prgs") first and confirm the resolved identity is NOT
jcwalker3 — jcwalker3 authored this PR, so a verdict from that identity is
not a valid independent review. Stop without mutation if the identities match.

Pin the head before any judgement: PR #940 head must be
97bc190fc2f6da6893cd2b6613ba5b9992d3f379, base master at
7bf4f1258451823a55b36d2157e74f8457165088. Re-pin the live head and re-view
before deciding; discard any conclusion taken against a different SHA.

Confirm scope: the PR adds exactly one file,
docs/remote-mcp/coupling-inventory.md, and edits nothing else.

Apply the issue's own acceptance test: pick any five findings at random,
confirm each line anchor resolves at head 97bc190fc2f6da6893cd2b6613ba5b9992d3f379,
and confirm the cited line does what the finding claims. Check anchors against
the reviewed commit, not against a local checkout that may sit at a different
master. Then confirm all seven categories carry findings and that #931 through
#939 are each named by at least one finding.

Record the verdict through the review API. Do not merge.
## Reviewer handoff — issue #930 → PR #940 [THREAD STATE LEDGER] ### what is true now - Issue: #930 — Remote-MCP 01: Inventory every stdio- and localhost-coupled assumption in the MCP server. Child 1 of epic #929. - PR number: 940 - PR title: `docs(remote-mcp): inventory stdio- and localhost-coupled assumptions (#930)` - PR head SHA (full): `97bc190fc2f6da6893cd2b6613ba5b9992d3f379` - Head branch: `docs/issue-930-remote-mcp-coupling-inventory` - Base branch: `master` - Base head at open: `7bf4f1258451823a55b36d2157e74f8457165088` - Inspected source commit: `7bf4f1258451823a55b36d2157e74f8457165088` - Commits behind base: 0 - PR state: open, mergeable, no conflicts, no status checks required - Issue linkage: PR body carries the literal `Closes #930` - Author identity: `jcwalker3`, profile `prgs-author`, namespace `gitea-author` - Server-side decision state: no review record of any kind exists on PR #940; `reviews` is empty, `approval_at_current_head` is false, and no reviewer or merger lease is held. - Local verdict/state: author-side work is complete and pushed. The author holds no review opinion and recorded none. Nothing has landed on master. ### what changed - One commit, `97bc190fc2f6da6893cd2b6613ba5b9992d3f379`, adding exactly one file: ``` A docs/remote-mcp/coupling-inventory.md (+230, -0) ``` - No other file is added, edited, renamed, or deleted. No source module, test, configuration, or dependency is touched. - Issue #930 carried the `status:pr-open` label from the moment PR #940 was opened. ### what is blocked - Blocker classification: no blocker - Nothing prevents review. PR #940 is open, sits 0 commits behind `master`, reports mergeable with no conflicts, and requires no status checks. - Epic children #931 through #939 are not implemented here and retain the `status:blocked` label, by design — they depend on this inventory landing first. ### who/what acts next - Next actor: reviewer, using profile `prgs-reviewer` via the `gitea-reviewer` MCP namespace. - Required action: perform a first review of PR #940 at head `97bc190fc2f6da6893cd2b6613ba5b9992d3f379` and record a verdict through the review API. - Do not do: do not review, approve, or record any verdict from this author session or from the `prgs-author` profile; do not merge PR #940; do not amend, rebase, or force-push the head branch; do not begin implementation of #931 through #939 before this PR lands on master; do not reuse any verdict taken against a head SHA other than `97bc190fc2f6da6893cd2b6613ba5b9992d3f379`. ## Canonical Issue State STATE: implementation complete on branch `docs/issue-930-remote-mcp-coupling-inventory`; PR #940 is in open state at head `97bc190fc2f6da6893cd2b6613ba5b9992d3f379` and is awaiting a first review verdict. WHO_IS_NEXT: reviewer NEXT_ACTION: review PR #940 at head `97bc190fc2f6da6893cd2b6613ba5b9992d3f379` from the `prgs-reviewer` profile and record a verdict via the review API. BLOCKERS: none. Blocker classification: no blocker. WHAT_HAPPENED: The author produced `docs/remote-mcp/coupling-inventory.md`, an inventory of every place the MCP server depends on being a local, client-spawned, stdio-attached process on the operator's machine. It holds 62 findings across the seven categories the issue names, carrying 69 line anchors drawn from 20 distinct source files, each anchor taken against commit `7bf4f1258451823a55b36d2157e74f8457165088`. Every finding records the file and line, what the code assumes today, what the same code would observe on a remote host, a classification, and exactly one owning epic child. The work was committed as `97bc190fc2f6da6893cd2b6613ba5b9992d3f379`, pushed to `prgs`, and opened as PR #940 against `master`. WHY: Epic #929 cannot be scoped against guesses. Every later child needs the list of what actually breaks when the server process stops being local, so producing that list is the blocking first step and the sole prerequisite of #931 through #939. VALIDATION: 62 findings. 69 line anchors confirmed to resolve. 20 distinct source files cited. All 7 required categories carry at least one finding, so no category needed a no-coupling justification. All 9 epic children #931 through #939 are each named by at least one finding, and every finding names exactly one child. - Category counts — transport bind 9, launch provenance 12, role binding 7, credentials 6, runtime freshness 6, local filesystem 11, durable state 11. - Classification counts — portable as written 5, needs a seam 16, needs a replacement 26, cannot be remote 15. - Per-child counts — #931 = 9, #932 = 7, #933 = 6, #934 = 9, #935 = 6, #936 = 8, #937 = 13, #938 = 2, #939 = 2. Two mechanical checks were run against the tree before commit. First, every `` `file.py:NNN` `` reference was extracted from the document and resolved against the checked-out tree: all 69 exist, all are in range, and each cited line matches the behavior its finding describes. Second, the table rows were parsed and re-tallied independently; the computed per-category, per-classification, category-by-classification, and per-child totals all equal the values printed in the document's own summary tables. Because this change adds one file and edits none, no pre-existing line number shifts between `7bf4f1258451823a55b36d2157e74f8457165088` and the PR head, so every anchor stays accurate at the head under review. The remote branch head and the PR head are the identical SHA `97bc190fc2f6da6893cd2b6613ba5b9992d3f379`, confirmed via `git ls-remote prgs refs/heads/docs/issue-930-remote-mcp-coupling-inventory`. SCOPE: documentation only. No production behavior changed. The issue's non-goals — choosing the remote transport, the credential provider, or the deployment target — are all left to later children. RELATED_PRS: #940 LAST_UPDATED_BY: jcwalker3 (profile `prgs-author`, namespace `gitea-author`, role author) NEXT_PROMPT: ```text Review PR #940 on prgs/Scaled-Tech-Consulting/Gitea-Tools. Use the gitea-reviewer MCP namespace with profile prgs-reviewer. Call gitea_whoami(remote="prgs") first and confirm the resolved identity is NOT jcwalker3 — jcwalker3 authored this PR, so a verdict from that identity is not a valid independent review. Stop without mutation if the identities match. Pin the head before any judgement: PR #940 head must be 97bc190fc2f6da6893cd2b6613ba5b9992d3f379, base master at 7bf4f1258451823a55b36d2157e74f8457165088. Re-pin the live head and re-view before deciding; discard any conclusion taken against a different SHA. Confirm scope: the PR adds exactly one file, docs/remote-mcp/coupling-inventory.md, and edits nothing else. Apply the issue's own acceptance test: pick any five findings at random, confirm each line anchor resolves at head 97bc190fc2f6da6893cd2b6613ba5b9992d3f379, and confirm the cited line does what the finding claims. Check anchors against the reviewed commit, not against a local checkout that may sit at a different master. Then confirm all seven categories carry findings and that #931 through #939 are each named by at least one finding. Record the verdict through the review API. Do not merge. ```
sysadmin removed the status:pr-open label 2026-07-26 02:10:53 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
allocator
Controller-owned work allocator
 anti-stomp
Prevent concurrent LLM session stomping
 architecture
Architecture / structural design
 bug
chore
codex
OpenAI Codex client / workflow session surface
 concurrency
Concurrent session safety
 contamination
Workflow or session contamination incident
 control-plane
MCP control-plane coordination and allocation authority
 dashboard
MCP operational dashboard/queue view
 database
Internal coordination storage (SQLite/Postgres)
 design
Design / investigation, no implementation
 documentation
Docs / runbooks
 enhancement
New feature or improvement
 gitea
Gitea MCP workflow
 glitchtip
GlitchTip integration
 important
incident
Operational or process incident requiring durable audit trail
 incident-bridge
Sentry-to-Gitea incident bridging
 integration
Integration testing
 jenkins
Jenkins integration
 labels
Label taxonomy management
 leases
Lease adopt/release/expire lifecycle
 mcp
MCP server / tooling
 mcp-health
MCP namespace and runtime health
 mcp-menu
MCP menu surface
 multi-project
Work spanning multiple monitoring projects or Gitea repos
 mutating
Mutating action; requires gating
 nice-to-have
observability
Observability, metrics, traces, error reporting
 portability
Cross-platform / portability
 preflight
Shared preflight gates before mutation
 protected-branch
Protected branch / stable-branch policy concern
 queue
Work queue visibility and allocation
 read-only
Read-only, no mutation
 reconnect
MCP client reconnect/reload recovery path
 recovery
Recovery paths for stale/foreign leases
 refactor
Code refactor / restructure
 release
Release / versioning
 reliability
Reliability / failure handling
 resumable-review
Persist and resume prepared review verdicts across sessions
 reviewer
Reviewer workflow tooling
 roadmap
Roadmap / umbrella issue
 safety
Safety rails and fail-closed mutation guards
 security
Security / trust boundary
 self-hosted
Self-hosted infrastructure integration
 sentry
Sentry error monitoring integration
 stale-runtime
Stale backend daemon / runtime-vs-master parity failures
 status:blocked
Issue is blocked
 status:in-progress
Issue is being worked on
 status:pr-open
Issue has an open pull request
 status:ready
Issue is ready for work
 terminal-lock
Terminal review lock (#332) path
 testing
Tests / test coverage
 tracker
Issue tracker hygiene / meta
 type:bug
Bug or defect
 type:feature
Feature or enhancement
 type:feature
Feature or enhancement
 type:guardrail
Safety gate or guardrail
 visibility
Workflow state visibility for LLMs/operators
 workflow
Cross-tool workflow
 workflow-hardening
LLM workflow coordination hardening
 workflow-hardening
LLM workflow coordination hardening
No labels architecture control-plane design mcp read-only type:feature
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jcwalker3 sysadmin
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#930