ui-server: acquire authorized shared reference source with bounded refresh #2429

Out of scope

No managed writable worktree publication, lifetime cleanup, new credentials policy, user-skill edits, blanket workspace exemption, provider-history mutation or new transport plugin. Do not use ambient host tokens as principal authorization.

Context

Part of #2390. The complete consolidated specification and its maintainer rulings are binding. The durable record is in draft PR #2427 at 6fc6183fe36125db1f465c9abb72eed0838d32ef (tree 212a1ec86ce0cb92bfbe254b4697c303de4ff3b1). That documentation is not product implementation or native qualification.

Code citations below were checked against 90a95123cfceb169bd2ecf7c213544db742eaed7. Recheck them when refreshing the implementation base. Preserve ROADMAP's concrete owners, deterministic CLI/host execution, unchanged brain-history accounting and append-only provider history. No policy ruling is requested by this issue.

Blocked by #2428

Sources:

• syncTransportCommand, packages/ui-server/src/brain/sync-mirror.ts:89-128: fixed host-owned credentialed transport, separate from source evaluation; it is currently brain-sync-specific and is not already a principal/repository connection registry.
• createHostBoundary, packages/ui-server/src/brain/host-boundary.ts:307-413: native input/credential/execution boundary; host-only helpers remain isolated.
• transportMounts, packages/ui-sdk/src/server/worker-launcher.ts:255-273, and workerCommand, same file:456-598, enforce the empty transport root versus worker execution envelope.
• principalManagementRoutes, packages/ui-server/src/middleware/principals.ts:66-79; local revocation at same file:168-182; reuse live principal resolution rather than cached byte presence.

Ruling — repository authority (2026-10-22)

Maintainer ruling 2026-10-22 (question, ruling): option 1, owner-managed grant records. An owner action records a grant of (brain, principal, repository prefix, named host credential). Private source is fetched only when a live grant covers the requesting principal and repository. Revoking a grant takes effect immediately, including for in-flight refreshes. A host credential existing never counts as authority. This adds an additive HTTP contract surface (CONTRACT:). The "already-authorized connection" and "connection revocation" in criteria 1–2 mean this grant and its revocation; the grant model is recorded in docs/decisions/reference-source-grants.md.

Scope

Implement the concrete host reference-source owner, using the foundation's capacity/recovery identities and existing transport/governance owners. Bind repository/revision and any existing authorized repository connection to the requesting brain/principal/profile. Implement the concrete missing authority binding in the host; do not introduce an abstract connection/provider registry or confuse the current sync token selector with authority.

Acceptance criteria

1. Public source is reusable host-wide; private source is isolated per brain/principal. Validation covers the exact repository/revision. Local principal/connection revocation blocks new grants immediately. Configurable five-minute validation is independent of source freshness. Expired or failed validation refuses a new mount even if cached/stale bytes exist; public-to-private and inaccessible revision transitions cannot leak revisions under public authority.
2. Acquire automatically through an already-authorized connection without another acquisition approval, while preserving profile/network/governance restrictions. Credentials are mounted only in the fixed transport; no repository helper/config/hook/filter or source-reading worker can evaluate with them. Host credential availability alone never grants access.
3. Request-only refresh uses five minutes since last successful refresh; no timer/background refresh. Publish a complete validated revision atomically, retain honest exact commit/time/error reporting, and return stale authorized source on refresh failure without advancing successful refresh time. With no authorized usable source, refuse.
4. Existing readers observe the new complete source on subsequent path reads. Prove the actual worker-visible directory publication/mount mechanism; replacing a root behind a bind mount is not sufficient. Allow multi-step reads to span revisions. Active readers prevent eviction, not refresh. No per-agent/turn full source copies or pinned shared-reader semantics.
5. Host-wide configurable two-operation admission; requests in the same source/domain join one operation. Private domains do not reveal activity to one another. Bound queues, wait/cancel/reply state and ownership. Independent sources progress in parallel; ordinary readers are not capped at two. Do not hold the native manager's global mutation lock for an entire network fetch.
6. Reserve foundation capacity before starting; account source/Git/checkout/staging, capacity-LRU evict only unleased eligible sources, protect worktree dependencies, and observe reclamation before retrying admission. No idle expiry. Cancellation or crash never publishes staging or releases still-owned bytes.
7. Offline Odysseus repository with more than 1,000 files is acquired outside brain content/index/capture/sync and can be inspected read-only without charging acquisition as brain-content edits. Prove resource, acquisition, capacity and independent turn limits still apply. Source service is wired to host lifecycle, not merely a mock factory.

Parent acceptance mapping

Owns #2390 criteria 2 (source-side inspection), 4 (all authority/freshness behaviors), 6 (acquisition concurrency/cancellation), and source-side portions of 5 and 8. Supported agent tool exposure is delivered by E; no closing keyword for #2390.

Failing-first/mutation targets

Expired validation plus stale checkout, principal/domain substitution, public-to-private revision, credentials visible to source evaluation, partial publish, refresh failure advancing timestamp, reader pinned after refresh, duplicate same-domain fetch, third simultaneous admitted acquisition and premature reservation release must each fail a named assertion under an appropriate restored mutation.

Verification

Use only offline Odysseus repositories and keyless native worker/storage fixtures. Record named failing-first assertions and restored mutations, actual head/base/checkout tree, toolchain and fixture identities, commands, exit codes and retained output. Source inspection, parser/unit fixtures and documentation proof do not establish actual allocation, worker, mount or backend behavior. Complete affected package/type/contract checks and required current-candidate PR proof before readiness/merge. Do not launch native or container resources without the coordinator's explicit resource slot; installation/local feedback is separately owned. A missing slot leaves runtime proof pending, not passed.

Contract impact

Additive only. Any supported configuration, CLI JSON, HTTP, SDK or tool surface added by this slice owns the relevant integration-contract component and index link in the same CONTRACT: commit, plus a minor changeset naming actual affected package manifests. Load the release skill before those edits; do not version or publish here. Keep internal host-only protocol definitions concrete and private; adding one does not authorize a generic extension interface. Update changed code citations in the same slice.