ADR: stable control runtime vs dev runtime for Gitea MCP #615

New Issue

2026-07-09T19:15:45-05:00

jcwalker3 commented

2026-07-09 19:15:45 -05:00

Problem

Author/reviewer/merger/reconciler sessions have historically restarted, killed, or relaunched the Gitea MCP server from development worktrees, or edited the stable runtime checkout. That destabilizes the control plane used for real Gitea mutations and causes EOF, stale-runtime, and mixed-identity failures mid-workflow.

Goal

Establish a durable stable control runtime vs dev runtime policy:

Real workflow mutations use only the stable control runtime.
MCP server development and testing happens in isolated branches/ worktrees and optional dev/test MCP runtimes.
Promotion into the stable runtime is an explicit operator/release-manager action with recorded proof and rollback.

Policy (normative)

Stable control runtime

The Gitea MCP server used for real workflow mutations is the stable control runtime.

Forbidden for normal author / reviewer / merger / reconciler sessions

Kill the running MCP server process
Restart the MCP server process
Relaunch MCP from a development worktree
Edit files in the stable runtime checkout
Use an experimental/dev MCP server for real Gitea mutations

Development / testing

Develop and test MCP server code in isolated branches/ worktrees
When needed, use a separate dev/test MCP runtime (never the stable control runtime identity for production mutations)

Promotion (operator / release-manager only)

Promotion to the stable control runtime must record:

previous runtime SHA
promoted runtime SHA
source branch/PR
restart/reload method
health check proof
identity/profile proof
workspace/root proof
mutation capability proof
rollback instructions

Unhealthy stable runtime

If the stable MCP runtime is unhealthy, normal PR/review/merge work must stop until the runtime is restored or a controlled promotion/rollback completes.

Related docs

docs/mcp-namespace-health.md (#543) — client-namespace health; no PID kill for EOF recovery
docs/mcp-namespace-eof-recovery.md — reconnect-only recovery
docs/mcp-daemon-import-guard.md (#558) — sanctioned daemon only
docs/bootstrap-review-path.md (#557) — narrow controller bootstrap when live runtime cannot review itself
ADR allocator/control-plane observability (PR #614 / #613)

Acceptance criteria

ADR exists under docs/architecture/ documenting this policy.
Operator guide / runbooks cross-link the ADR.
Normal sessions do not kill/restart/relaunch stable MCP or edit stable checkout.
Promotion checklist fields are documented and used for real promotions.
Unhealthy runtime → stop mutation workflows (fail closed).

Labels

workflow-hardening, mcp-health, stale-runtime, safety, documentation, type:guardrail, status:ready

## Problem Author/reviewer/merger/reconciler sessions have historically restarted, killed, or relaunched the Gitea MCP server from development worktrees, or edited the stable runtime checkout. That destabilizes the control plane used for real Gitea mutations and causes EOF, stale-runtime, and mixed-identity failures mid-workflow. ## Goal Establish a durable **stable control runtime vs dev runtime** policy: * Real workflow mutations use only the **stable control runtime**. * MCP server development and testing happens in isolated `branches/` worktrees and optional **dev/test** MCP runtimes. * Promotion into the stable runtime is an explicit operator/release-manager action with recorded proof and rollback. ## Policy (normative) ### Stable control runtime The Gitea MCP server used for real workflow mutations is the stable control runtime. ### Forbidden for normal author / reviewer / merger / reconciler sessions * Kill the running MCP server process * Restart the MCP server process * Relaunch MCP from a development worktree * Edit files in the stable runtime checkout * Use an experimental/dev MCP server for real Gitea mutations ### Development / testing * Develop and test MCP server code in isolated `branches/` worktrees * When needed, use a **separate** dev/test MCP runtime (never the stable control runtime identity for production mutations) ### Promotion (operator / release-manager only) Promotion to the stable control runtime must record: * previous runtime SHA * promoted runtime SHA * source branch/PR * restart/reload method * health check proof * identity/profile proof * workspace/root proof * mutation capability proof * rollback instructions ### Unhealthy stable runtime If the stable MCP runtime is unhealthy, **normal PR/review/merge work must stop** until the runtime is restored or a controlled promotion/rollback completes. ## Related docs * `docs/mcp-namespace-health.md` (#543) — client-namespace health; no PID kill for EOF recovery * `docs/mcp-namespace-eof-recovery.md` — reconnect-only recovery * `docs/mcp-daemon-import-guard.md` (#558) — sanctioned daemon only * `docs/bootstrap-review-path.md` (#557) — narrow controller bootstrap when live runtime cannot review itself * ADR allocator/control-plane observability (PR #614 / #613) ## Acceptance criteria 1. ADR exists under `docs/architecture/` documenting this policy. 2. Operator guide / runbooks cross-link the ADR. 3. Normal sessions do not kill/restart/relaunch stable MCP or edit stable checkout. 4. Promotion checklist fields are documented and used for real promotions. 5. Unhealthy runtime → stop mutation workflows (fail closed). ## Labels workflow-hardening, mcp-health, stale-runtime, safety, documentation, type:guardrail, status:ready

jcwalker3 added the documentation status:ready safety mcp-health stale-runtime type:guardrail workflow-hardening labels 2026-07-09 19:16:41 -05:00

jcwalker3 referenced this issue from a commit

2026-07-09 19:17:02 -05:00

docs: ADR for stable MCP control runtime vs dev runtime

jcwalker3 referenced this issue

2026-07-09 19:17:14 -05:00

docs: ADR for stable MCP control runtime vs dev runtime (#615) #616

jcwalker3 commented

2026-07-09 20:52:45 -05:00

Canonical Issue State

STATE: open — ADR tracker; enforcement-layer acceptance criteria being added
WHO_IS_NEXT: author
NEXT_ACTION: Implement #615 runtime mode/SHA reporting and fail-closed mutation gates
NEXT_PROMPT:

Implement issue #615 enforcement layer: add runtime mode (stable-control | dev-test | unknown) plus git SHA reporting to runtime context/health checks; add fail-closed mutation gates for dev-test-targeting-production, unknown runtime, dirty stable checkout, dev-worktree-launched runtime, unsafe process-root/workspace alignment, and post-flap namespaces not yet re-proven; require per-namespace post-transport-flap reproving; add the tests, the promotion runbook/helper, and the canonical [THREAD STATE LEDGER] examples per acceptance criteria items 6-11.

WHAT_HAPPENED: Runtime enforcement + proof requirements surfaced by the 2026-07-09 transport flap (#584) appended to the #615 ADR tracker.
WHY: The ADR/policy alone (#615) lacks runtime enforcement and proof requirements; the flap showed all gitea-* namespaces drop together and that author proof does not prove the other namespaces.
RELATED_PRS: none
BLOCKERS: none
VALIDATION: 2026-07-09 clean-binding proof recorded on #584 comment 9115
LAST_UPDATED_BY: prgs-author (jcwalker3)

[THREAD STATE LEDGER] Issue #615 — enforcement-layer acceptance criteria added

What is true now:

Issue state: open
Server-side decision state: server-side state changed
Local verdict/state: no server-side state changed before this comment
Latest known validation: 2026-07-09 clean-binding proof recorded on #584 comment 9115

What changed:

enforcement-layer acceptance criteria appended to the #615 ADR tracker

What is blocked:

Blocker classification: no blocker

Who/what acts next:

Next actor: author
Required action: implement #615 runtime mode/SHA reporting and mutation gates
Do not do: open a new tracker — #615 is canonical
Resume from: issue #615 body, acceptance criteria items 6-11

Missing acceptance criteria — enforcement layer (from live incident 2026-07-09)

#615 covers the ADR/policy. Adding the runtime enforcement + proof requirements
surfaced by the mid-session transport flap tracked on #584. In that incident,
all gitea-* tools dropped and self-recovered. Workspace binding was clean
before the drop, so the observed failure was not a stale process-root defect;
it was a transport/stale-runtime fault.

Add to runtime context / health checks

Report:

runtime mode: stable-control | dev-test | unknown
runtime git SHA
runtime branch
runtime checkout path
MCP process root
active task workspace
repo/org binding
profile
authenticated identity
dirty files
workspace alignment
whether real mutations are allowed

Add mutation gates — fail closed when

runtime mode is dev-test and target is the real production repo
runtime mode is unknown
stable runtime checkout is dirty
stable runtime process was launched from a development worktree
process-root/workspace alignment is unsafe
transport recently dropped and the namespace has not been re-proven

Add post-transport-flap proof

After any MCP transport flap or daemon restart, each namespace must be independently re-proven before mutation:

author
reviewer
merger
reconciler

Required proof per namespace:

whoami
runtime context
capability resolve immediately before mutation
mutate only if no reconnect/restart/stale-runtime gate is reported

Author proof alone must not be described as global MCP reliability proof.

Extend acceptance criteria

Runtime mode and SHA reporting implemented.
Mutation gates added for dev-test, unknown, dirty stable runtime, unsafe process-root/workspace alignment, and dev-worktree-launched runtimes.
Per-namespace post-flap reproving required.
Tests added for:
- stable healthy runtime allows real mutations
- dev/test runtime blocks real production mutations
- unknown runtime blocks mutations
- normal workflow cannot restart stable MCP
- transport recovery requires namespace-specific reproving
- author proof does not imply reviewer/merger/reconciler proof
- promotion records previous and promoted SHAs
Explicit promotion runbook/helper added.
Canonical [THREAD STATE LEDGER] examples added for:

runtime healthy
transport flap recovered
namespace not yet re-proven
promotion completed
rollback required

Link

Transport-flap symptom tracker: #584.

See #584 comment 9115 for the 2026-07-09 clean-binding proof.

## Canonical Issue State STATE: open — ADR tracker; enforcement-layer acceptance criteria being added WHO_IS_NEXT: author NEXT_ACTION: Implement #615 runtime mode/SHA reporting and fail-closed mutation gates NEXT_PROMPT: ```text Implement issue #615 enforcement layer: add runtime mode (stable-control | dev-test | unknown) plus git SHA reporting to runtime context/health checks; add fail-closed mutation gates for dev-test-targeting-production, unknown runtime, dirty stable checkout, dev-worktree-launched runtime, unsafe process-root/workspace alignment, and post-flap namespaces not yet re-proven; require per-namespace post-transport-flap reproving; add the tests, the promotion runbook/helper, and the canonical [THREAD STATE LEDGER] examples per acceptance criteria items 6-11. ``` WHAT_HAPPENED: Runtime enforcement + proof requirements surfaced by the 2026-07-09 transport flap (#584) appended to the #615 ADR tracker. WHY: The ADR/policy alone (#615) lacks runtime enforcement and proof requirements; the flap showed all gitea-* namespaces drop together and that author proof does not prove the other namespaces. RELATED_PRS: none BLOCKERS: none VALIDATION: 2026-07-09 clean-binding proof recorded on #584 comment 9115 LAST_UPDATED_BY: prgs-author (jcwalker3) [THREAD STATE LEDGER] Issue #615 — enforcement-layer acceptance criteria added What is true now: - Issue state: open - Server-side decision state: server-side state changed - Local verdict/state: no server-side state changed before this comment - Latest known validation: 2026-07-09 clean-binding proof recorded on #584 comment 9115 What changed: - enforcement-layer acceptance criteria appended to the #615 ADR tracker What is blocked: - Blocker classification: no blocker Who/what acts next: - Next actor: author - Required action: implement #615 runtime mode/SHA reporting and mutation gates - Do not do: open a new tracker — #615 is canonical - Resume from: issue #615 body, acceptance criteria items 6-11 --- ## Missing acceptance criteria — enforcement layer (from live incident 2026-07-09) #615 covers the ADR/policy. Adding the runtime enforcement + proof requirements surfaced by the mid-session transport flap tracked on #584. In that incident, all `gitea-*` tools dropped and self-recovered. Workspace binding was clean before the drop, so the observed failure was not a stale process-root defect; it was a transport/stale-runtime fault. ### Add to runtime context / health checks Report: - runtime mode: `stable-control` | `dev-test` | `unknown` - runtime git SHA - runtime branch - runtime checkout path - MCP process root - active task workspace - repo/org binding - profile - authenticated identity - dirty files - workspace alignment - whether real mutations are allowed ### Add mutation gates — fail closed when - runtime mode is `dev-test` and target is the real production repo - runtime mode is `unknown` - stable runtime checkout is dirty - stable runtime process was launched from a development worktree - process-root/workspace alignment is unsafe - transport recently dropped and the namespace has not been re-proven ### Add post-transport-flap proof After any MCP transport flap or daemon restart, each namespace must be independently re-proven before mutation: - author - reviewer - merger - reconciler Required proof per namespace: 1. `whoami` 2. runtime context 3. capability resolve immediately before mutation 4. mutate only if no reconnect/restart/stale-runtime gate is reported Author proof alone must not be described as global MCP reliability proof. ### Extend acceptance criteria 6. Runtime mode and SHA reporting implemented. 7. Mutation gates added for dev-test, unknown, dirty stable runtime, unsafe process-root/workspace alignment, and dev-worktree-launched runtimes. 8. Per-namespace post-flap reproving required. 9. Tests added for: - stable healthy runtime allows real mutations - dev/test runtime blocks real production mutations - unknown runtime blocks mutations - normal workflow cannot restart stable MCP - transport recovery requires namespace-specific reproving - author proof does not imply reviewer/merger/reconciler proof - promotion records previous and promoted SHAs 10. Explicit promotion runbook/helper added. 11. Canonical `[THREAD STATE LEDGER]` examples added for: - runtime healthy - transport flap recovered - namespace not yet re-proven - promotion completed - rollback required ### Link Transport-flap symptom tracker: #584. See #584 comment 9115 for the 2026-07-09 clean-binding proof.

jcwalker3 referenced this issue

2026-07-09 21:16:58 -05:00

Auto-mode classifier must not count pre-API validator rejections as mutation budget #617

jcwalker3 referenced this issue

2026-07-10 11:57:35 -05:00

Enforce autonomous canonical handoffs and dependency-aware concurrent task orchestration #628

jcwalker3 referenced this issue

2026-07-10 14:47:20 -05:00

Product vision: MCP Control Plane Web Console (canonical) #652

jcwalker3 referenced this issue

2026-07-10 15:33:26 -05:00

Design rolling-restart and high-availability MCP architecture #668