P0: canonicalize Nexus public connector host source and block GOVERNED direct merges

[James3014]

Parent semantic contract

Cross-repo implementation owner for James3014/Nexus-new#1096.

This Issue does not create a second Nexus merge authority. Nexus-new #1096 remains the semantic/acceptance owner for the invariant:

GOVERNED -> standing grant + github_complete_pull_request -> existing exact-head/CAS merge core.

Proven source-lineage defect

The physical public Nexus connector merge sink is not owned by current James3014/devspace/main.

Fresh evidence on 2026-09-25:

• current DevSpace GitHub main: 27f69e16a4d9bb5123850c8d4457eb735c4cb868;
• running current Dev MCP build: devspace-1.0.7-89828be8, source 89828be8705913cd251b3855c6bcaa7526fa5ce2;
• neither current main nor that current runtime lineage contains nexus-gateway-proxy.ts, git-pr-merge.ts, git_merge_pull_request, or github_complete_pull_request;
• the actual public Nexus connector host source is local checkout /Users/jameschen/Workspace/nexus-devspace-mcp, branch nexus/mcp-tools-v1;
• installed package identity records source 08c3595cbdb44bd685d476703b674cc5fc30683e;
• local branch history contains 14f46b4 feat(mcp): add git_merge_pull_request protected fallback merge tool, b89ce89 feat: add canonical Nexus gateway proxy mode, and 0aa2868 feat(nexus): integrate verified host-generation completion lineage;
• local checkout origin points back to itself, and 08c3595... is not present in current James3014/devspace GitHub history.

Therefore the production-affecting connector has a local-only / non-durable source lineage. A governance fix merged only to Nexus-new or current DevSpace main can truthfully pass source CI while leaving the physical public merge sink unchanged.

Goal

Close both defects in one host implementation line:

1. make the source that builds/activates the Nexus public connector durable and traceable from an Owner-controlled GitHub source/ref;
2. physically prevent the public direct git_merge_pull_request action from merging a PR whose exact nexus.merge_lane_binding.v1 declares GOVERNED;
3. preserve github_complete_pull_request as the only public host path that may reach a GOVERNED merge after canonical Nexus standing-grant/completion validation;
4. keep the existing exact-base/head/check/CAS merge core as the sole physical merge implementation.

Required implementation semantics

• Do not add a caller-supplied boolean/string such as completion=true, internal=true, or execution_lane=... as authority; public callers must not be able to spoof completion-loop provenance.
• Public direct merge must fresh-read the exact PR binding before the merge effect.
• DIRECT_CANONICAL and DIRECT_DELEGATED remain allowed through the existing direct path when their normal exact checks pass.
• GOVERNED on the public direct sink fails closed before merge effect.
• The governed completion action may delegate to the same merge core through an internal trusted call boundary; no second merge implementation.
• Missing/malformed/unknown lane binding fails closed according to the accepted Nexus merge-lane contract.
• Keep #1095 as historical negative-control evidence; do not rewrite its authority history.

Mandatory negative control

Equivalent of Nexus-new PR #1095:

• lane: GOVERNED
• historical head: c632f1e031cd24d33d7ec2e29140562735431959
• historical base: 2115949ec83943010a9fa3672a077e0c1d8c4e06

A public direct merge request with an equivalent GOVERNED binding must be rejected before any GitHub merge call.

Source-lineage acceptance

Before claiming completion, prove:

• exact GitHub repository/ref/commit that owns the connector host source;
• package/build identity points to that durable source;
• installed/loaded public connector generation readback matches the accepted source;
• local-only nexus/mcp-tools-v1 is no longer an untracked production authority source (either migrated/adopted or explicitly retired after equivalent durable source exists).

Non-goals

• no new Planner/Router/standing-grant evaluator;
• no second merge core;
• no weakening of exact-head/CAS, required checks, or Owner confirmation;
• no retroactive authority fabrication for #1095;
• no provider/runtime architecture expansion;
• no automatic successor work.

AUTO_CHAIN=false.

Exact next gate:

D0_FREEZE_PUBLIC_CONNECTOR_CANONICAL_SOURCE_AND_SINGLE_MERGE_EFFECT_OWNER

[James3014]

D0 live ownership freeze — source-lineage defect reproduced on the actual host

Fresh physical readback from the currently loaded public Nexus connector:

{
  "name": "nexus-mcp-gateway",
  "surface_profile": "canonical_gateway_proxy",
  "tool_source": "canonical_gateway_manifest_plus_local_protected",
  "effective_tool_count": 39,
  "local_protected_tools": [
    "git_merge_pull_request",
    "github_complete_pull_request"
  ],
  "build": {
    "package_name": "@nexus-local/devspace",
    "package_version": "1.0.1-nexus.7",
    "source_commit": "08c3595cbdb44bd685d476703b674cc5fc30683e",
    "source_dirty": false,
    "build_id": "nexus-1.0.1-nexus.7-08c3595c",
    "build_manifest_sha256": "20744dd7ecbbd4db587b840542161ea4325a7bb968bb01cea10fdde2b47fcbf2"
  }
}

Current James3014/devspace/main is the generic DevSpace 1.0.7 execution plane and does not contain the Nexus proxy/merge-host modules. Therefore current DevSpace main is not the physical source owner of the public Nexus connector and must not be made one merely by copying the retired proxy architecture back into main.

D0 disposition:

DEDICATED_NEXUS_CONNECTOR_HOST_SOURCE_LINE_REQUIRED

The single physical merge-effect owner remains the existing host merge core used by both protected actions. The correction must first make the exact connector-host source durable/traceable, then patch that source so the public direct action rejects GOVERNED before effect while completion retains the same merge core.

This D0 does not publish the currently local-only source, change runtime, restart the service, or merge anything. It freezes ownership only.

Next gate:
D1_DURABLE_CONNECTOR_SOURCE_MATERIALIZATION_WITHOUT_REINTRODUCING_PROXY_INTO_DEVSPACE_MAIN

[James3014]

D1 implementation boundary — reuse Nexus trusted lane validator, do not duplicate policy

Source inspection of the loaded connector generation freezes the smallest safe host change.

Existing physical owner

src/git-pr-merge.ts::mergePullRequest() is the single exact-head/CAS merge core used by:

• public git_merge_pull_request;
• github-completion-host.ts::CompletionHostPort.casMerge().

Keep that single effect owner.

Existing canonical lane validator

Do not implement a second TypeScript interpretation of nexus.merge_lane_binding.v1.

Current Nexus-new already owns exact validation in:
scripts/ops/trusted_merge_lane_gate.py::validate_event().

It validates:

• exactly one binding block;
• schema + binding hash;
• OWNER_INLINE/direct constraints;
• tracked Task Card exact base/head bytes and SHA-256;
• task/attempt identity;
• GOVERNED invariants;
• exact Owner governed->direct rebind record/hash.

Host adapter shape

The connector host may add only a narrow adapter that:

1. extends the fresh PR observation with body;
2. constructs the fixed pull_request_target event projection from freshly observed repository/PR/base/head/body (no caller-supplied lane);
3. invokes the fixed trusted validator from the bound NEXUS_CANONICAL_SOURCE_ROOT using argv only and a bounded temporary event file;
4. parses only PASS + exact execution_lane + PR/head identity;
5. fails closed if the script/root/result is missing, stale, malformed, or identity-mismatched.

Then:

• public git_merge_pull_request requires validated lane in DIRECT_CANONICAL | DIRECT_DELEGATED;
• github_complete_pull_request/CompletionHost requires validated lane GOVERNED;
• both continue into the same mergePullRequest() physical CAS implementation.

The lane expectation is selected by the trusted host call site and is not exposed as an MCP argument. No internal=true, completion=true, or caller-provided execution_lane is permitted.

TOCTOU position

Run the lane validation against the final fresh PR/base/head observation immediately before the GitHub merge effect. Any body/base/head movement requires a fresh validation and normal check/CAS re-evaluation.

Mandatory hostile tests

• public direct + exact GOVERNED binding -> reject before transport.mergePullRequest;
• public direct + genuine OWNER_INLINE DIRECT -> existing positive path remains;
• public direct + valid governed->direct rebind -> existing trusted validator decides validity;
• malformed/duplicate/missing binding -> reject before effect;
• stale/missing trusted validator root -> reject before effect;
• completion + GOVERNED -> same CAS core remains reachable after existing standing-grant/completion validation;
• completion + DIRECT -> reject at trusted host boundary;
• caller attempts to add spoofed internal/lane fields -> cannot influence host-selected expectation.

This design reuses Nexus-new as semantic authority and leaves DevSpace/host as transport + physical-effect enforcement only.

D1 code mutation remains blocked until the local-only connector source is durably materialized; do not patch the installed package first and backfill source later.

[James3014]

D2 root-cause freeze — public proxy startup manifest is process-lifetime cached and health is false-green after inner Gateway changes

Fresh source + live evidence now proves the recurring action-surface drift mechanism.

Exact source defect

Current loaded connector source 08c3595... does this in src/server.ts:

const gatewayManifestReady =
  fetchNexusGatewayToolManifest(config).then(...)
...
mcpBoundary factory awaits the same gatewayManifestReady Promise
...
GET /healthz awaits the same gatewayManifestReady Promise
and reports ready = !manifestError

Therefore the canonical Gateway manifest is fetched exactly once per proxy process.

createNexusGatewayProxyServer(..., preparedManifest) then registers that frozen manifest into the MCP server. This is intentional static MCP registration, but there is no later manifest-identity convergence check.

Live witness

Inner Gateway:

• source: c8da43aa...
• canonical tool count: 38
• manifest revision: cb1d5c24dca9d319d6391fd9850afb7734f5cfeace1e39e3dd94ff48e8846132
• source contains nexus_owner_standing_grant_issue.

Outer public connector:

• canonical observed count: 37
• cached manifest revision: b323ce9149165f4f71ce5169520091f4ce64d63b423ffa6ee9e3a5733e0d8348
• still reports /healthz ok=true / manifest_status=verified
• public tool surface lacks nexus_owner_standing_grant_issue.

That exact mismatch reproduces the #1096 governance-bootstrap deadlock even after the inner Gateway has the required authority action.

This same failure family appeared historically in Nexus-new #842: a prior Gateway update required a manual proxy restart before the new Project Entry action became visible. The recurrence is therefore architectural, not operator error.

D2 accepted repair shape

Do not dynamically mutate the registered MCP tool map in place.

Preserve static per-process MCP registration, but make manifest convergence level-triggered:

1. retain the startup manifest identity as the registered-surface identity;
2. on /healthz (and optionally a cheap bounded readiness interval), fresh-fetch the current inner Gateway tools/list manifest identity;
3. compare fresh canonical count/revision/sha256 with the registered startup identity;
4. exact match -> healthy;
5. mismatch -> 503 fail closed with typed disposition such as:
   CANONICAL_GATEWAY_MANIFEST_DRIFT / PROXY_RESTART_REQUIRED;
6. inner manifest unreadable/malformed/collision -> existing fail-closed behavior;
7. existing service manager / launchd restart reconstructs the proxy and registers the new manifest; no dynamic tool mutation and no second registry;
8. post-restart health must prove registered identity == fresh inner identity before the public surface is healthy.

Mandatory regression

• start proxy against manifest M1 -> health 200;
• inner Gateway changes to M2 -> same process health becomes 503, never false-green M1;
• no old-only/new-only tool may be claimed healthy while identities differ;
• reconstructed proxy with M2 -> health 200 and tools/list exposes M2;
• collision with local protected tools remains fail-closed;
• inner Gateway unavailable -> fail-closed, never preserve stale healthy claim;
• OAuth/restart behavior remains explicit; no auth weakening.

This D2 belongs in the same physical host owner as D1/#1096 because both defects live in the local protected/public connector host. It creates no new Gateway deployment owner (#526 remains inner Gateway rebind/reload owner).

D1 (merge-lane enforcement) + D2 (manifest convergence) + durable source materialization are all required before #245 can claim complete.

[James3014]

D2 source merged; runtime activation is the only remaining #842 gate

Source repair is now durable on the dedicated connector-host line:

• source branch: James3014/devspace:nexus/connector-host-v1
• merged PR: fix(#245/#842): fail closed on public Gateway manifest drift #254
• merged source commit: 40ab0b50a6b1bc63dda08af879a2afbc9c23a452
• source tree: 60dd24bae0f3f57cac7df2fb0e045c28e695908d
• package: @nexus-local/devspace@1.0.1-nexus.7
• deterministic build id: nexus-1.0.1-nexus.7-40ab0b50

Proven RED -> GREEN

RED head 1a35c17d... added only the hostile M1 -> M2 health witness. Ubuntu CI reached the test and failed exactly because the old process returned HTTP 200 after the inner canonical Gateway manifest changed; expected 503.

Final Candidate ceb86630... + merge 40ab0b50...:

• Ubuntu full CI PASS;
• macOS full CI PASS;
• git diff --check PASS;
• Core mutation scope exactly src/server.ts + src/nexus-gateway-proxy.test.ts, no deletion/scope escape.

Windows CI remains unrelated baseline portability debt: the unchanged npm test script begins with POSIX export and fails before executing any tests.

D2 behavior now in source

Static per-process MCP registration remains unchanged. /healthz now fresh-fetches the canonical inner Gateway manifest and compares exact count/revision/sha256 with the startup registered identity:

• exact match -> healthy;
• drift -> 503 CANONICAL_GATEWAY_MANIFEST_DRIFT + PROXY_RESTART_REQUIRED;
• post-start manifest unavailable/malformed/collision -> fail closed;
• original startup PUBLIC_SURFACE_FAIL_CLOSED behavior remains intact.

No second tool registry, Gateway owner, Planner, Workforce, acceptance, approval, merge, release, or production authority was added.

Exact remaining gate

The source is merged but the currently loaded public connector has not yet been proven activated on this generation.

The repository-owned local activator already exists:
nexus-devspace host-generation activate
backed by src/host-generation-activation.ts, which fixes package/install root/launchd label/health URL and performs expected-old + source/tree + build + install + restart + post-health readback.

Current ChatGPT tooling cannot execute that final host effect:

• Remote Desktop Commander is quota-paused and explicitly says not to retry/reconnect;
• DevSpace host_operation_preflight proves the maintenance policy exists but rejects this connector identity before effect: Host operation client identity does not match the startup-selected owner.;
• the alternate DevSpace connector does not expose host-operation actions.

Therefore D2 is SOURCE_COMPLETE / RUNTIME_ACTIVATION_UNPROVEN, not complete.

Next exact gate:
ACTIVATE_40AB0B50_ON_COM_NEXUS_MCP_DEVSPACE_DIRECT_AND_PROVE_PUBLIC_MANIFEST_CONVERGENCE.

Do not reimplement D2 or copy the connector into generic DevSpace main.

AUTO_CHAIN=false.

[James3014]

D1 source completion + current runtime gate

D1 is now durably merged into the dedicated connector-host source line.

• D2 donor already merged: PR fix(#245/#842): fail closed on public Gateway manifest drift #254 -> nexus/connector-host-v1@40ab0b50a6b1bc63dda08af879a2afbc9c23a452
• D1 physical merge-lane enforcement: PR fix(#245): enforce Nexus merge lane at public physical sink #258 -> merge commit f68235ee1a37ba0175bba7b5fddc7e52bc759279
• exact tree: eb3e246f8172883a18f651e89bea8fec2ce56a41
• current D1 diff is four files only; the earlier accidental truncated upload was corrected in the same PR before merge.
• Ubuntu/macOS CI: typecheck/test/build/doctor PASS.
• Windows: Typecheck PASS; npm test fails before any test because the repository baseline script begins with POSIX export. This is the same pre-existing Windows failure witnessed on D2 PR fix(#245/#842): fail closed on public Gateway manifest drift #254, not a D1 regression.
• focused D1 witnesses: existing CAS core reached only after beforeMergeEffect; host-selected canonical lane adapter rejects GOVERNED before transport.mergePullRequest; public schema exposes no spoofable lane/internal/completion field.

Runtime remains not yet activated. The current ChatGPT public Nexus action catalog still lacks nexus_owner_standing_grant_issue, proving the loaded connector generation is not the merged source line yet.

A clean activation checkout exists locally at:
/Users/jameschen/Workspace/devspace-connector-host-f682-activation
bound to exact f68235ee....

Typed host activation from this MCP session is unavailable:

• dependency_sync -> current paired carrier required;
• generic host_operation_preflight -> startup-selected owner identity mismatch;
• no effect was started by either failed preflight.

Therefore maximum claim:
SOURCE_COMPLETE / RUNTIME_ACTIVATION_PENDING_OWNER_LOCAL_EFFECT.

Exact next gate:
BUILD_F682 -> HOST_GENERATION_ACTIVATE_F682 -> HEALTHZ_REGISTERED_MANIFEST_EQUALS_INNER_GATEWAY -> PUBLIC_ACTION_SURFACE_READBACK.

Do not close #245 until that runtime gate is proven.