Muse ↔ GitHub history reconciliation — June 2026

Status: COMPLETE — Muse main is canonical again, GitHub main and Muse main hold the identical tree, and the muse-mirror workflow is safe to use.

Simple summary: for a few days the project had two slightly different "latest versions" — the one tracked by Muse (our canonical history) and the one on GitHub (where two emergency fixes had to ship directly to production). This document records how the two were brought back to a single identical version, with the GitHub-only emergency work imported into Muse so nothing was lost.

Technical summary: GitHub main had four changes absent from Muse (8ae04be RBAC proposal-approval fix + companion app phases 1-6 + MCP OAuth C3/C5 hardening; d5cfe77 AGENTS.md muse-mirror mandate; PR #229 hosted MCP discovery timeout hotfix; PR #230 frontmatter normalization hotfix). Muse main had one commit absent from GitHub's local clone (6f47d53a, hosted discovery fix) — which turned out to be byte-identical to PR #229's content. origin/main was verified to be a strict superset of the Muse working tree, so reconciliation was a content import of origin/main into Muse, committed as one reconciliation commit, then mirrored back through the standard muse-mirror PR.

Why this was shelved, and why it is now resolved

On 2026-06-08, two hotfixes had to ship straight from GitHub main to production (Netlify gateway/bridge). The standing instruction was: do not run muse-mirror until reconciled, because mirroring the then-current Muse snapshot would have deleted the GitHub-only companion/native-OAuth files and their test suites from production. Those hotfixes shipped; this reconciliation closes the gap.

Divergence inventory (evidence captured 2026-06-10)

State before reconciliation:

The 107 "deletions" were divergence artifacts, not uncommitted work: companion app libs (lib/companion-*.mjs, lib/model-runtime-lane.mjs), native OAuth provider (hub/gateway/native-oauth-provider.mjs, native-as-store.mjs), companion design docs (docs/COMPANION-APP-*.md), and the seven-tier test suites for companion, native-oauth-c1-c6, proposal-approve-rbac-fix, model-runtime-lane, derived-artifact-storage, and llm-complete-openrouter.

Findings that shaped the resolution

1. The MCP discovery "overlap hazard" was already resolved upstream

Muse 6f47d53a and GitHub PR #229 were suspected to be independent implementations of the same hosted MCP discovery fix. Byte-level comparison showed they are the same implementation: hub/bridge/server.mjs, hub/gateway/mcp-proxy.mjs, test/bridge-hosted-context-settings.test.mjs, test/gateway-settings-hosted-vault-filter.test.mjs, and test/mcp-gateway-proxy.test.mjs all diff zero between the Muse working tree and origin/main. One implementation; nothing to delete. This also means the Muse-only hosted-context settings endpoint (GET /api/v1/hosted-context/settings) and gateway delegated vault filtering were already in production via PR #229.

2. OpenRouter/chat-provider was never deliberately removed in Muse

muse log --all shows the OpenRouter/chat-provider work lives on the unmerged Muse branch feat/companion-design-openrouter-lane (commits 3b70a5eb, 7c3a895f, branched from f4def6a1). It reached GitHub main when that branch was mirrored as ca1f023 (PR #227). Muse main never contained it, so there is no deliberate Muse removal commit. Per the reconciliation rule ("keep the Muse-side removal only if a deliberate Muse commit confirms it"), the OpenRouter/chat-provider code was restored from GitHub.

FLAGGED FOR SEPARATE DECISION: the OpenRouter/chat-provider lane is now in Muse canonical history via the reconciliation commit, but the owner has not explicitly merged feat/companion-design-openrouter-lane into Muse main. If removal is wanted, it must be its own documented Muse commit through the normal flow.

3. origin/main is a strict superset of Muse main

All 99 working-tree-only lines were individually inspected. Each is an older shape that origin/main superseded:

Conclusion: importing origin/main's tree loses zero unique Muse work.

Conflict resolutions (as planned, with outcomes)

What was done

1. git fetch origin; recorded the full divergence inventory before changing anything.
2. git checkout origin/main -- . — imported the GitHub-only content into the working tree. Verified git diff origin/main is empty (tree identity).
3. Ran the full test suite (npm test, includes the restored seven-tier companion / native-oauth / RBAC / openrouter suites) — all green.
4. Muse reconciliation commit on main importing the GitHub-direct history, including this document.
5. Local git main fast-forwarded to origin/main (git reset --mixed; pointer-only, no content change, no history rewrite).
6. Mirrored Muse main → GitHub via the standard muse-mirror branch + PR (this document is the only file-level delta on the GitHub side, shipped in the same PR as the Muse code import it records).
7. Verified GitHub main tree == Muse main snapshot (empty diff).

Seven-tier coverage for the merged surface

The merged hosted-context + restored-RBAC/OAuth surface is covered by restored and existing suites, all green in step 3:

• Unit / Integration / E2E / Stress / Data-integrity / Performance / Security: test/proposal-approve-rbac-fix-*.test.mjs (7 tiers, RBAC fallback decision paths), test/native-oauth-c1-c6-*.test.mjs (7 tiers, code-exchange validation, iss, redirect_uri mismatch, sessionless MCP rejection), test/companion-*-{unit,integration,e2e,stress,data-integrity,performance,security}.test.mjs, test/llm-complete-openrouter-*.test.mjs (7 tiers), test/derived-artifact-storage-*.test.mjs (7 tiers), test/model-runtime-lane-*.test.mjs (7 tiers).
• Hosted-context settings + vault filtering: test/bridge-hosted-context-settings.test.mjs, test/gateway-settings-hosted-vault-filter.test.mjs (allowlist never widens; 403 → empty allowlist; forged X-User-Id rejected; no canister enumeration with explicit delegated IDs; 60s-cache budget), test/mcp-gateway-proxy.test.mjs.
• Frontmatter normalization: test/gateway-hosted-notes-frontmatter.test.mjs.

Current operating procedure (unchanged, now unblocked)

1. Develop on a Muse feature branch; merge to Muse main after tests are green.
2. Mirror every Muse main merge to GitHub via the muse-mirror branch + PR (mandated in AGENTS.md; never push directly to GitHub main).
3. Deploy follows GitHub main (Netlify).

Do not reopen this reconciliation unless a future status check proves Muse main and GitHub main have diverged again.

Exit criteria

• [x] muse status clean after the reconciliation commit.
• [x] git status clean; local main == origin/main.
• [x] GitHub main tree == Muse main snapshot (empty file-level diff).
• [x] Full suite green on the reconciled tree.
• [x] Production verified (live probes, 2026-06-10): gateway healthy; GET /api/v1/hosted-context/settings live and 401s both unauthenticated and forged X-User-Id requests; OAuth discovery serves the canonical issuer; token exchange rejects malformed requests (400 invalid_request); sessionless MCP non-initialize rejected (-32600 / 401). The redirect_uri-mismatch and delegated-vault-visibility paths require valid credentials to probe live; they are verified by the green native-oauth-c1-c6-security and gateway-settings-hosted-vault-filter suites against the identical tree that is deployed.
• [x] This document merged with the code in the same PR.

Related documents

• docs/COMPANION-APP-OAUTH-SERVERSIDE-GATE.md — C1–C6 OAuth hardening contract (C3/C5 shipped).
• docs/COMPANION-APP-PHASE-*.md — companion app phases 1-6 (restored to Muse canonical).
• docs/HUB-API.md — frontmatter normalization contract (PR #230).
• Scooling docs/GITHUB-MIRROR-RECONCILIATION-FOLLOWUP.md — the model for this record.