Remote-MCP 06: Redefine the master-parity mutation gate for a remote deployment #935

New Issue

2026-07-26T00:32:10-05:00

jcwalker3 commented

2026-07-26 00:32:10 -05:00

Parent epic: #929.
Depends on: #931.

Problem

gitea_assess_master_parity decides whether mutations are safe by comparing the commit the process started at against the commit currently checked out on the same disk. It reports startup_head, current_head, local_head, live_remote_head, and gates mutations on mutation_safe. The whole construct assumes the server process and the canonical checkout are the same machine, which is why advancing master on disk is what makes a running daemon stale.

On a remote host that assumption dissolves. There is no operator checkout to compare against, the process root is a deployment artifact rather than a working tree, and target_repository is already reported as unconfigured today. Left alone, the gate would either report a meaningless verdict or block every remote mutation permanently. The gate is protecting something real, that a server must not enforce security rules older than the ones that were merged, so it needs a definition that survives the move.

Scope

Restate the freshness question in terms a remote deployment can answer.

Separate the two dimensions the tool already labels: the freshness of the server implementation, and the state of the target repository. Only the server dimension may gate mutations.
For a remote deployment, define server freshness against the deployed build identity, not against a local working tree. Record the build identity at start, and compare it against the released version the deployment is expected to be running.
Define the verdict when freshness is undeterminable, and make that verdict explicit rather than incidental.
Keep the local stdio behavior exactly as it is, including the existing recovery guidance that points at a client reconnect.
Ensure the returned blocker names the correct recovery action per deployment mode. A remote operator cannot fix staleness by reconnecting an editor.
Keep the two gates independent: a green parity verdict is still not permission to mutate on its own.

Acceptance criteria

The tool reports which freshness definition it applied, and why.
Under stdio, every existing field keeps its current meaning and existing tests pass unchanged.
Under a remote deployment, freshness is computed from the deployed build identity with no dependency on a local working tree.
A stale remote deployment fails closed with a named blocker and a recovery action appropriate to a deployed service.
An undeterminable verdict is explicit and fails closed for mutations while leaving read-only operations available.
Read-only operations are never blocked by staleness, in any mode.

Verification

Tests cover, per mode: in parity, stale, and undeterminable.
A test asserts read-only operations succeed in all three states.
A test asserts the remote path performs no working-tree inspection.
Full suite compared against the recorded baseline, run from a branches/ worktree.

Non-goals

Changing how releases are versioned or tagged beyond what is needed to identify a build.
Merging the parity gate with the resolver gate. They stay independent.
Changing stdio recovery guidance.

Parent epic: #929. Depends on: #931. ## Problem `gitea_assess_master_parity` decides whether mutations are safe by comparing the commit the process started at against the commit currently checked out on the same disk. It reports `startup_head`, `current_head`, `local_head`, `live_remote_head`, and gates mutations on `mutation_safe`. The whole construct assumes the server process and the canonical checkout are the same machine, which is why advancing master on disk is what makes a running daemon stale. On a remote host that assumption dissolves. There is no operator checkout to compare against, the process root is a deployment artifact rather than a working tree, and `target_repository` is already reported as unconfigured today. Left alone, the gate would either report a meaningless verdict or block every remote mutation permanently. The gate is protecting something real, that a server must not enforce security rules older than the ones that were merged, so it needs a definition that survives the move. ## Scope Restate the freshness question in terms a remote deployment can answer. - Separate the two dimensions the tool already labels: the freshness of the server implementation, and the state of the target repository. Only the server dimension may gate mutations. - For a remote deployment, define server freshness against the deployed build identity, not against a local working tree. Record the build identity at start, and compare it against the released version the deployment is expected to be running. - Define the verdict when freshness is undeterminable, and make that verdict explicit rather than incidental. - Keep the local stdio behavior exactly as it is, including the existing recovery guidance that points at a client reconnect. - Ensure the returned blocker names the correct recovery action per deployment mode. A remote operator cannot fix staleness by reconnecting an editor. - Keep the two gates independent: a green parity verdict is still not permission to mutate on its own. ## Acceptance criteria - The tool reports which freshness definition it applied, and why. - Under stdio, every existing field keeps its current meaning and existing tests pass unchanged. - Under a remote deployment, freshness is computed from the deployed build identity with no dependency on a local working tree. - A stale remote deployment fails closed with a named blocker and a recovery action appropriate to a deployed service. - An undeterminable verdict is explicit and fails closed for mutations while leaving read-only operations available. - Read-only operations are never blocked by staleness, in any mode. ## Verification - Tests cover, per mode: in parity, stale, and undeterminable. - A test asserts read-only operations succeed in all three states. - A test asserts the remote path performs no working-tree inspection. - Full suite compared against the recorded baseline, run from a `branches/` worktree. ## Non-goals - Changing how releases are versioned or tagged beyond what is needed to identify a build. - Merging the parity gate with the resolver gate. They stay independent. - Changing stdio recovery guidance.