[0.12] Settle workspace, authentication, and storage contracts

Goal

Choose the infrastructure and trust-boundary contracts that the rest of Facility 0.12 will build against. The result should be a small set of written decisions and a working reference fixture.

Questions to settle

Document a decision for each item below:

• workspace provider and its durable storage primitive
• compute isolation needed to run Docker or Docker Compose and a headless browser
• authentication for MCP and the Facility UI
• delivery of full maintainer GitHub credentials to a workspace
• lifetime and revocation behavior for those full-capability GitHub credentials
• delivery of Claude Code and Codex credentials
• delivery of project secrets and environment variables to setup, services, and agents
• authenticated preview routing, including WebSockets and wake behavior
• behavior when a project contains several writable repositories
• backup, restore, cost reporting, and explicit deletion of retained workspaces
• whether UI edits to .agents/ create a direct commit or a pull request

All repositories connected to a project receive the same full maintainer access. The multirepository decision covers branch and pull request behavior, not a permission split.

Reference fixture

Build a disposable project used by later sub-issues. It should contain an application, an API, a database, seed data, a Compose file, one browser test, and sample .agents/ files.

Use the fixture to measure:

• time to create a workspace
• time to wake suspended compute
• whether storage reattaches to replacement compute without changing files
• whether Compose and the browser work under the chosen isolation model
• whether an authenticated user can reach the preview from outside the workspace
• active and suspended cost

The fixture may use a temporary implementation. It should leave a repeatable command and recorded results for contributors.

Decision record requirements

Write each record under apps/docs/docs/reference/decisions/. State the selected option, alternatives that were actually tested, the observed evidence, the ownership boundary, and what would make the team revisit the choice. Avoid building a provider-neutral framework beyond the WorkspaceRuntime interface needed by the epic.

Acceptance criteria

• The provider and runtime choice passes create, write, suspend, replace, reattach, and read against the fixture.
• The chosen runtime starts the full Compose fixture and runs its browser test.
• Preview authentication and routing work from a machine outside the workspace.
• MCP and UI identity map to a project maintainer with documented session and revocation behavior.
• The GitHub credential design grants full project maintainer capability to every agent and has no per-agent scoping.
• Claude Code and Codex authentication can be revoked without deleting their stored sessions.
• Storage has no destructive idle or merge timeout.
• A backup restores the fixture's untracked file and native session marker into a fresh workspace, and explicit deletion removes the source volume.
• The multirepository decision names the default repository and pull request behavior.
• The fixture and measurement commands run from a clean checkout.

Out of scope

This work does not implement the production control plane. It should answer the decisions that would otherwise force later pull requests to guess.

Start with the existing WorkspaceRuntime interface and the requirements under apps/docs/docs/reference/decisions/. Build the disposable fixture with an application, API, database, Compose file, browser test, and sample .agents/ files, then run the repeatable measurement commands from a clean checkout. Done means the written decisions record tested alternatives and evidence, and the acceptance checks pass for runtime, authentication, storage, credentials, routing, and deletion.