fix(runtime): support validated cross-repository canonical roots for dedicated namespaces #973

New Issue

2026-07-29T12:04:05-05:00

jcwalker3 commented

2026-07-29 12:04:05 -05:00

Problem Statement

A dedicated mcp-control-plane MCP namespace uses:

GITEA_CANONICAL_REPOSITORY_ROOT=/Users/jasonwalker/Development/mcp-control-plane
Its MCP installation/process root is /Users/jasonwalker/Development/Gitea-Tools
Its task worktree is registered in the mcp-control-plane Git repository under branches/.

Despite this, the runtime mutation gate reports:

workspace_roots_aligned: false
real_mutations_allowed: false
blocker_kind: runtime_mode_blocked

Evidence indicates that the alignment calculation in namespace_workspace_binding.py ("roots_aligned": canonical_root == process_root) incorrectly requires the task repository's configured canonical root to equal the Gitea-Tools installation/process root.

Furthermore, several supported dedicated-namespace configuration environment keys are missing from RECOGNIZED_GITEA_ENV_KEYS in gitea_config.py:

GITEA_CANONICAL_REPOSITORY_ROOT
GITEA_REVIEWER_WORKTREE
GITEA_MERGER_WORKTREE
GITEA_MCP_SESSION_STATE_TTL_HOURS

When set, get_unconsumed_gitea_env_overrides treats them as unsupported GITEA_* keys, populating unconsumed_gitea_env and incorrectly triggering runtime_reconnect_required.

Associated Enablement Evidence

Previously observed duplicate reviewer and merger processes are recorded as associated enablement evidence. (Daemon lifecycle repair is separate unless source inspection proves a shared root cause).

Acceptance Criteria

Separate Process Root & Canonical Root: Separate the MCP installation/process root from the task repository's canonical root.
Explicit & Validated Configuration: Allow different roots only when the task root is explicitly configured and validated.
Repository Identity Validation: Validate the configured root's repository identity and native repository binding.
Git Common-Directory Membership: Validate Git common-directory membership for task worktrees.
Worktree Registration: Require reviewer and merger worktrees to be registered and located under the configured repository's branches/ directory.
Path Normalization: Normalize paths and handle symlink identity safely.
Provenance & Session Gates: Preserve client-managed provenance, session ownership, and trusted-evidence gates.
Fail-Closed Guarantees: Fail closed for missing, nonexistent, foreign, mismatched, ambiguous, or untrusted roots.
Reject Unregistered Worktrees: Reject unregistered or unsafe worktrees.
Distinct Diagnostics: Provide distinct diagnostics for installation root, configured canonical root, active workspace, repository binding, and alignment decision.
Recognize Environment Keys: Add legitimately supported dedicated-namespace variables to RECOGNIZED_GITEA_ENV_KEYS:
- GITEA_CANONICAL_REPOSITORY_ROOT
- GITEA_REVIEWER_WORKTREE
- GITEA_MERGER_WORKTREE
- GITEA_MCP_SESSION_STATE_TTL_HOURS
Reject Unknown Keys: Continue rejecting unknown GITEA_* variables.
Prevent False Reconnects: Prevent valid recognized configuration from incorrectly triggering runtime_reconnect_required.
Preserve Same-Repository Behavior: Preserve same-repository behavior for standard single-repo setups.
Regression Tests: Add regression tests for valid and invalid same-repository and cross-repository configurations.
Reviewer Lease Regression Test: Add a production-path reviewer lease acquire/release regression test.
Post-Fix Enablement Proof:
- Require a post-fix enablement proof on mcp-control-plane PR #99 at head 08de534457dbf4d6045ffd0ddd7718dbb6c9cc7e.
- During that proof, perform exactly one native reviewer lease acquire/release cycle with no review or merge.

### Problem Statement A dedicated `mcp-control-plane` MCP namespace uses: - `GITEA_CANONICAL_REPOSITORY_ROOT=/Users/jasonwalker/Development/mcp-control-plane` - Its MCP installation/process root is `/Users/jasonwalker/Development/Gitea-Tools` - Its task worktree is registered in the `mcp-control-plane` Git repository under `branches/`. Despite this, the runtime mutation gate reports: - `workspace_roots_aligned`: false - `real_mutations_allowed`: false - `blocker_kind`: `runtime_mode_blocked` Evidence indicates that the alignment calculation in `namespace_workspace_binding.py` (`"roots_aligned": canonical_root == process_root`) incorrectly requires the task repository's configured canonical root to equal the `Gitea-Tools` installation/process root. Furthermore, several supported dedicated-namespace configuration environment keys are missing from `RECOGNIZED_GITEA_ENV_KEYS` in `gitea_config.py`: - `GITEA_CANONICAL_REPOSITORY_ROOT` - `GITEA_REVIEWER_WORKTREE` - `GITEA_MERGER_WORKTREE` - `GITEA_MCP_SESSION_STATE_TTL_HOURS` When set, `get_unconsumed_gitea_env_overrides` treats them as unsupported `GITEA_*` keys, populating `unconsumed_gitea_env` and incorrectly triggering `runtime_reconnect_required`. ### Associated Enablement Evidence Previously observed duplicate reviewer and merger processes are recorded as associated enablement evidence. (Daemon lifecycle repair is separate unless source inspection proves a shared root cause). ### Acceptance Criteria 1. **Separate Process Root & Canonical Root**: Separate the MCP installation/process root from the task repository's canonical root. 2. **Explicit & Validated Configuration**: Allow different roots only when the task root is explicitly configured and validated. 3. **Repository Identity Validation**: Validate the configured root's repository identity and native repository binding. 4. **Git Common-Directory Membership**: Validate Git common-directory membership for task worktrees. 5. **Worktree Registration**: Require reviewer and merger worktrees to be registered and located under the configured repository's `branches/` directory. 6. **Path Normalization**: Normalize paths and handle symlink identity safely. 7. **Provenance & Session Gates**: Preserve client-managed provenance, session ownership, and trusted-evidence gates. 8. **Fail-Closed Guarantees**: Fail closed for missing, nonexistent, foreign, mismatched, ambiguous, or untrusted roots. 9. **Reject Unregistered Worktrees**: Reject unregistered or unsafe worktrees. 10. **Distinct Diagnostics**: Provide distinct diagnostics for installation root, configured canonical root, active workspace, repository binding, and alignment decision. 11. **Recognize Environment Keys**: Add legitimately supported dedicated-namespace variables to `RECOGNIZED_GITEA_ENV_KEYS`: - `GITEA_CANONICAL_REPOSITORY_ROOT` - `GITEA_REVIEWER_WORKTREE` - `GITEA_MERGER_WORKTREE` - `GITEA_MCP_SESSION_STATE_TTL_HOURS` 12. **Reject Unknown Keys**: Continue rejecting unknown `GITEA_*` variables. 13. **Prevent False Reconnects**: Prevent valid recognized configuration from incorrectly triggering `runtime_reconnect_required`. 14. **Preserve Same-Repository Behavior**: Preserve same-repository behavior for standard single-repo setups. 15. **Regression Tests**: Add regression tests for valid and invalid same-repository and cross-repository configurations. 16. **Reviewer Lease Regression Test**: Add a production-path reviewer lease acquire/release regression test. 17. **Post-Fix Enablement Proof**: - Require a post-fix enablement proof on `mcp-control-plane` PR #99 at head `08de534457dbf4d6045ffd0ddd7718dbb6c9cc7e`. - During that proof, perform exactly one native reviewer lease acquire/release cycle with no review or merge.