docs: plan workspace enrollment authority repair

[jbeda]

Plan / Interface

Relates to #1740.

This plan records the authority repair contract before implementation:

• persist a bounded, presence-bearing private ledger of dynamically installed broker registration keys;
• replace only that bundle while retaining all other carried authority;
• fail a broker/non-broker registration-key collision as one terminal, no-partial enrollment;
• retain already-corrupted legacy snapshots without heuristic repair and require a fresh session for corrected behavior.

It proposes ADR 0358, which supersedes only ADR 0335's no-refresh-specific-persisted-state clause.

Verification

• bash .claude/skills/to-acceptance-plan/scripts/check-acceptance-plan.sh docs/acceptance/workspace-enrollment-authority.md
• bash .claude/skills/to-acceptance-plan/scripts/check-acceptance-plan-test.sh
• task docs

The plan requires human merge before /plan-orchestrate implements it.

Revisions

• Rebased onto main after feat(mcp): reconcile sources and refresh session tools #1673 (direct MCP source reconciliation, ADR 0355). The ADR is renumbered from 0350 to 0358 because main now has its own ADRs 0350-0357.
• The plan names direct MCP refresh (RefreshMcpSources / Session.GrantToolAuthority) as a separate add-only path that refuses broker-bound sessions, adds AC1.5 pinning that refusal, and the ADR records why ADR 0355's union-and-availability model is rejected for broker keys.
• 2026-09-23 review amendments (recorded under Human decisions): authority and ledger set together with absent-by-default provenance, excluded keys retained in the ledger, collision refusal on every engine build, and pending enrollment cleared on collision.
• Implementation is stacked in fix(enrollment): preserve workspace enrollment authority #1809.
• Review feedback (JAORMX): AC3.1, the collision-cleanup decision, and ADR decision 5 now separate clearing the pending enrollment from the session being usable (an incoming-key collision leaves it usable; a recorded-key collision keeps engine builds refused until the configuration is corrected). The older-binary re-save caveat is removed: no upgrade compatibility work is required, and sessions without provenance are refused with a fresh-session error.

[jbeda]

Open design question: runtime-only vs durable broker provenance

The implementation does not restore tool implementations from a session snapshot. On run entry it reconstructs an engine from current server composition. For ordinary tools that is sufficient.

Broker tools are intentionally different after a process restart: rehydrateSession rebuilds the per-session engine in exact-tools mode with no broker tools. It does not attach, rebind, rediscover, or enroll ToolHive on an ordinary prompt. The persisted binding and authority names are inert until the owner explicitly invokes workspace enrollment again. See internal/adapter/server/service.go (rehydrateSession) and internal/adapter/server/workspace_enrollment_test.go (post-restart ordinary run vs explicit refresh).

That creates two possible scopes for #1740:

1. In-process / initial enrollment fix only. Preserve the pre-enrollment authority and track the installed broker bundle only in the live attachment or session-engine state. This fixes the clobbering regression without a new snapshot field. After a process restart, a later explicit enrollment can install fresh broker wrappers, but the system cannot precisely remove old broker capability names while preserving unrelated authority and deliberate attenuation.

2. Exact replacement across restart. Persist a narrow, bounded, presence-bearing set of dynamic broker registration keys. On explicit re-enrollment after restart, remove only that old broker set and add the newly registered one. This supports exact replacement but adds durable provenance and requires an ADR-level decision.

The existing plan/ADR currently assumes option 2. That should not be merged until we decide whether same-session exact replacement after a broker/process restart is required. If it is not, the plan should be narrowed to option 1 and the durable provenance ADR removed.

Related edge case: a broker/non-broker duplicate registration key must either be rejected as a whole-bundle enrollment failure or receive a specified precedence rule. Namespacing makes this unusual, but it is possible when two sources expose the same mcp__<server>__<tool> key.

[JAORMX]

The approach looks good: track the broker-installed keys, replace only that bundle, and preserve unrelated authority and existing exclusions.

Two non-blocking notes:

• Please distinguish clearing the pending enrollment from making the session usable again. An incoming-tool collision can leave the prior session usable, but a conflict involving a recorded broker key still held in authority blocks engine construction until the configuration is corrected. AC3.1's “session accepts prompts again” wording should reflect that distinction.
• We’re moving fast and don’t need upgrade compatibility or migration work here. Refusing enrollment for sessions without provenance and requiring a fresh session is acceptable; a basic actionable error is enough.

Approving the plan. This review does not cover the implementation in #1809.

[jhrozek]

Thanks, Joe. We went with option 2: exact replacement across restart, using durable provenance.

Option 1 fixes the clobbering, but only until the process restarts. After a restart, a new enrollment has no record of which authority entries were broker tools. It can then either keep the old broker names (they go stale and may later match a different tool) or drop authority it can't identify. Clear and fork have the same gap. Their successors carry the authority but not the knowledge of which names came from the broker.

The plan (now ADR 0358 after renumbering on rebase) keeps the durable part small:

• The session stores only broker registration keys, capped at 256 keys and 32 KiB, with a presence bit. No endpoints, OAuth state, or runtime handles.
• A restart still rebuilds without broker tools. As you described, an ordinary prompt never attaches, rebinds, or enrolls. The ledger only lets a later explicit enrollment remove exactly the old broker keys.
• Sessions without a recorded ledger are refused at enrollment with "create a fresh session". There is no migration or repair.

On the duplicate-key edge case: a collision between a broker tool and a non-broker tool rejects the whole enrollment. There is no precedence rule. The error names only the conflicting key, and the pending enrollment is cleared.

JAORMX approved the plan with that scope. The implementation is in #1809, stacked on this PR.