docs(remote-mcp): inventory stdio- and localhost-coupled assumptions (#930) #940
Merged
sysadmin
merged 1 commits from 2026-07-26 02:10:51 -05:00
docs/issue-930-remote-mcp-coupling-inventory into master
Labels
Clear labels
allocator
anti-stomp
architecture
bug
chore
codex
concurrency
contamination
control-plane
dashboard
database
design
documentation
enhancement
gitea
glitchtip
important
incident
incident-bridge
integration
jenkins
labels
leases
mcp
mcp-health
mcp-menu
multi-project
mutating
nice-to-have
observability
portability
preflight
protected-branch
queue
read-only
reconnect
recovery
refactor
release
reliability
resumable-review
reviewer
roadmap
safety
security
self-hosted
sentry
stale-runtime
status:blocked
status:in-progress
status:pr-open
status:ready
terminal-lock
testing
tracker
type:bug
type:feature
type:feature
type:guardrail
visibility
workflow
workflow-hardening
workflow-hardening
Controller-owned work allocator
Prevent concurrent LLM session stomping
Architecture / structural design
OpenAI Codex client / workflow session surface
Concurrent session safety
Workflow or session contamination incident
MCP control-plane coordination and allocation authority
MCP operational dashboard/queue view
Internal coordination storage (SQLite/Postgres)
Design / investigation, no implementation
Docs / runbooks
New feature or improvement
Gitea MCP workflow
GlitchTip integration
Operational or process incident requiring durable audit trail
Sentry-to-Gitea incident bridging
Integration testing
Jenkins integration
Label taxonomy management
Lease adopt/release/expire lifecycle
MCP server / tooling
MCP namespace and runtime health
MCP menu surface
Work spanning multiple monitoring projects or Gitea repos
Mutating action; requires gating
Observability, metrics, traces, error reporting
Cross-platform / portability
Shared preflight gates before mutation
Protected branch / stable-branch policy concern
Work queue visibility and allocation
Read-only, no mutation
MCP client reconnect/reload recovery path
Recovery paths for stale/foreign leases
Code refactor / restructure
Release / versioning
Reliability / failure handling
Persist and resume prepared review verdicts across sessions
Reviewer workflow tooling
Roadmap / umbrella issue
Safety rails and fail-closed mutation guards
Security / trust boundary
Self-hosted infrastructure integration
Sentry error monitoring integration
Stale backend daemon / runtime-vs-master parity failures
Issue is blocked
Issue is being worked on
Issue has an open pull request
Issue is ready for work
Terminal review lock (#332) path
Tests / test coverage
Issue tracker hygiene / meta
Bug or defect
Feature or enhancement
Feature or enhancement
Safety gate or guardrail
Workflow state visibility for LLMs/operators
Cross-tool workflow
LLM workflow coordination hardening
LLM workflow coordination hardening
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Scaled-Tech-Consulting/Gitea-Tools#940
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Summary
Adds
docs/remote-mcp/coupling-inventory.md, the blocking first child of epic #929. It enumerates every placegitea_mcp_server.pyand its supporting modules depend on being a local, client-spawned, stdio-attached process on the operator's machine.Documentation only. No server behavior changes. One new file; no existing file is edited.
Closes #930
What is in the document
62 entries across the seven categories the issue requires:
No category is empty, so no "no coupling here" justification was needed.
Classification split:
Ownership — every child from #931 through #939 is named by at least one entry, and every entry names exactly one child:
Acceptance criteria
docs/remote-mcp/coupling-inventory.mdexists and is committed.7bf4f1258451823a55b36d2157e74f8457165088.Verification performed
Two mechanical checks were run against the worktree before commit:
file:linereferences in the document were extracted and resolved against the checked-out tree. Every one exists, is in range, and the line it points at matches the behavior the entry describes. 20 distinct source files are cited.Line anchors were taken against
7bf4f1258451and remain valid at this branch head, because this change adds a file and edits none, so no existing line number shifts.A reviewer checking the acceptance criterion "pick any five entries at random and confirm the line anchor and the described behavior" can do so directly against this branch head.
Out of scope
Per the issue's non-goals, this PR does not change server behavior and does not choose the remote transport, the credential provider, or the deployment target. #931 through #939 are not implemented here.
repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #940
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 64159-b80998ea9c86
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-930-coupling-inventory
phase: claimed
candidate_head: none
target_branch: master
target_branch_sha: none
last_activity: 2026-07-26T06:48:29Z
expires_at: 2026-07-26T06:58:29Z
blocker: none
repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #940
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 64159-b80998ea9c86
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-930-coupling-inventory
phase: validating
candidate_head:
97bc190fc2target_branch: master
target_branch_sha:
7bf4f12584last_activity: 2026-07-26T06:57:54Z
expires_at: 2026-07-26T07:07:54Z
blocker: none
NATIVE_REVIEW_PROOF: transport=native_mcp; entrypoint=mcp_server; entrypoint_path=/Users/jasonwalker/Development/Gitea-Tools/gitea_mcp_server.py; pid=64159; phase=transport_bound; mode=production; token_fingerprint=0f93de51538b56e4; lease_session=64159-b80998ea9c86; lease_comment=17325; phase_heartbeat_comment=17326; workflow_hash=263d0a6cb8a6; final_report_schema_hash=b6c65affc336; boundary_status=clean
Canonical PR State
STATE: PR #940 is in open state at head
97bc190fc2f6da6893cd2b6613ba5b9992d3f379, sits 0 commits behindmaster, reports mergeable with no conflicts, and now carries one formal review verdict of APPROVE recorded at that exact head.WHO_IS_NEXT: merger
NEXT_ACTION: merge PR #940 into
masterfrom the merger role after re-confirming, viagitea_assess_pr_sync_status, thatapproval_at_current_headis true for97bc190fc2f6da6893cd2b6613ba5b9992d3f379.NEXT_PROMPT:
WHAT_HAPPENED: The reviewer independently re-derived every claim in this PR rather than accepting the author handoff. The head was read from the server-side ref
refs/pull/940/headand matchedgit ls-remoteon the branch. The diff against base contains exactly one added file,docs/remote-mcp/coupling-inventory.md, 230 insertions and 0 deletions, in one commit, touching no production code, test, configuration, or dependency. All 69 file-and-line anchors in the document were extracted and resolved against blobs read from commit7bf4f1258451823a55b36d2157e74f8457165088withgit show, not against a working tree: 69 of 69 resolve, 0 failures. Every anchor was then re-resolved at the PR head and compared byte for byte, with 0 differences, confirming the document's no-line-shift claim. Entry rows were reparsed and re-tallied independently of the document's own summary tables, and every printed total matched. Twelve entries were opened in source and compared against their prose, including all five entries classified portable as written, since a wrong portable call would tell a child that no work is needed.WHY: Issue #930 is the blocking first child of epic #929, and its output is the scoping input for #931 through #939. A wrong anchor or a wrong classification in this document would silently mis-scope every later child, so the reviewer's job was to re-derive the mechanical claims rather than trust them.
ISSUE: #930, linked by the literal
Closes #930in the PR body.HEAD_SHA:
97bc190fc2f6da6893cd2b6613ba5b9992d3f379REVIEW_STATUS: APPROVE, recorded by
sysadmin(user_id 4, profileprgs-reviewer) at head97bc190fc2f6da6893cd2b6613ba5b9992d3f379. The PR author isjcwalker3(user_id 1), a distinct identity, so reviewer independence is satisfied. No prior review existed at this head;reviewswas empty before this verdict.MERGE_READY: true at head
97bc190fc2f6da6893cd2b6613ba5b9992d3f379— open state, 0 commits behind base, mergeable true, no conflicts, no status checks required by branch protection. The merger must still re-confirmapproval_at_current_headimmediately before merging, because this verdict is head-scoped.BLOCKERS: none. Blocker classification: no blocker. No actionable finding was raised and nothing rises to a change request.
VALIDATION: 62 entries, 62 unique IDs, 0 duplicates. 69 of 69 anchors resolve at the inspected commit
7bf4f1258451823a55b36d2157e74f8457165088, across 20 distinct source files, with 0 anchors differing at the PR head. Category counts — transport bind 9, launch provenance 12, role binding 7, credentials 6, runtime freshness 6, local filesystem 11, durable state 11; all 7 required categories carry at least one entry, so no no-coupling justification was required. Classification counts — portable as written 5, needs a seam 16, needs a replacement 26, cannot be remote 15; the vocabulary contains only the four permitted values. Per-child counts — #931 = 9, #932 = 7, #933 = 6, #934 = 9, #935 = 6, #936 = 8, #937 = 13, #938 = 2, #939 = 2; all nine children are named and every row names exactly one child. Document structure lints clean: 12 table blocks, no malformed rows, consistent column counts, no tabs, no trailing whitespace, terminating newline present. The document states the exact inspected commit. Dry-run gate returnedwould_perform: truewithauthenticated_user: sysadminandpr_author: jcwalker3.LAST_UPDATED_BY: sysadmin / prgs-reviewer
Substantive review notes
Two classification calls were checked closely, because an error in either would misdirect a downstream child:
sentry_incident_bridge.py:190as portable as written. Correct —resolve_tokenreadsENV_AUTH_TOKENfrom an injected mapping and its docstring states "from env only". There is no keychain fallback, so the portable call holds.master_parity_gate.pykeys its cache on(root, remote, branch)and shellsgit -C <root> ls-remote, so the probe really is bound to the operator's path.Two candidate omissions were chased and then dismissed on inspection rather than filed as findings:
gitea_auth.py:743mentionsGITEA_MCP_PROFILEonly inside a docstring, andmcp_namespace_health.py:55lists it in aSAFE_ENV_KEYSredaction allowlist. Neither binds a role, so excluding both from the role-binding category is correct.Each category's named sub-requirements from the issue are covered: the literal stdio bind and its downstream readers including
assess_transport_for_auth_mint; theGITEA_CLIENT_MANAGEDcheck, TTY detection, manual-launch refusal, duplicate-role peer scan, andRECOGNIZED_GITEA_ENV_KEYS;GITEA_MCP_PROFILEreads and process-as-role treatment;resolve_token,keychain_auth, andassert_keychain_access_allowed; the startup-HEAD versus disk-HEAD comparison and themutation_safeconsumers; worktree bootstrap and binding,branches/path assumptions,/tmppointer files, and the startup conflict-marker scan; lock, lease, session, and control-plane stores including PID-keyed andowner_pid_alivestate.One non-blocking observation, recorded for the children rather than for this PR: the document's closing caveat about non-exhaustiveness is scoped to the
branches/path pattern specifically. The same caution applies to any grep-derived category, so #932 and #934 should re-scan rather than treat their entry lists as closed sets. This affects no acceptance criterion and requires no change here.Reviewer mutations in this run: one lease acquisition (comment 17325), one lease phase heartbeat (comment 17326), one final-decision mark, and this one formal review. No file edits, no commits, no pushes, no merge.
repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #940
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 64159-b80998ea9c86
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-930-coupling-inventory
phase: released
candidate_head:
97bc190fc2target_branch: master
target_branch_sha:
7bf4f12584last_activity: 2026-07-26T07:02:33Z
expires_at: 2026-07-26T07:12:33Z
blocker: manual-release
repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #940
issue: none
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 64189-0fcfcd2bab20
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-930-coupling-inventory
phase: claimed
candidate_head:
97bc190fc2target_branch: master
target_branch_sha: none
last_activity: 2026-07-26T07:08:48Z
expires_at: 2026-07-26T07:18:48Z
blocker: none
Stale #332 review-decision lock cleanup (#594)
Status: APPLIED
sysadminprgs-merger2026-07-26T07:10:54.571071+00:00approveon PR docs(remote-mcp): inventory stdio- and localhost-coupled assumptions (#930) (#940)closed(merged=True)6a56260768ad2f69b773a8b7ab8d460ce821c9144prgs-reviewerManual deletion of session-state files is not the workflow.
This path only clears a lock when the referenced PR is merged/closed.