design

Design Index

Front door for all architecture/design material. Two kinds of documents live here:

• Reference — the target design pack and the as-built review (the "what we want" and "what we have").
• Proposed plan sets — gap-closing designs, each paired with an executable task tracker in .sisyphus/plans/.

Convention: each proposed set is a folder with README.md (front door: state, gap matrix, roadmap, decisions) + target-architecture.md (schemas/contracts), and an executable Sisyphus plan under .sisyphus/plans/.

Reading order

1. background-agent-platform/ — the canonical target design pack (multi-tenant background coding agents). Start at its README.md / 00-overview/executive-summary.md. Everything else is measured against this.
2. agent-architecture-review/ — the as-built review: what diverges from the pack, with code-anchored evidence. Start at final-report.md, then gaps-and-risks.md and recommended-next-slices.md.
3. The proposed plan sets below — each closes a specific cluster of the gaps the review found.

Design sets

Set	What it covers	Status	Entry point	Sisyphus plan
background-agent-platform/	Target design pack (architecture, API keys, secrets/BYOK, sandboxes, environments, data models, security, evals, roadmap)	Reference	README.md	—
agent-architecture-review/	As-built review vs the pack: gaps, risks, recommended slices	Reference	final-report.md	—
security-designs/	GitHub org→repo entitlement + least-privilege API-key scopes (multi-tenant security must-fixes)	Proposed (design-only; awaiting sign-off)	README.md	— (rollout in-set)
secrets-and-environments/	Full secret scope hierarchy (org→team→user→repo→environment→run), Teams in Better Auth, RBAC wiring, secret versioning/policies, environment entity	Proposed	README.md	.sisyphus/plans/secrets-and-environments-scoping-plan.md
sandboxes-and-snapshots/	Swappable sandbox providers (SandboxProvider + AgentRunContract) and robust snapshot capture/restore/retention + lifecycle hardening	Proposed	README.md	.sisyphus/plans/sandboxes-and-snapshots-plan.md
agent-workspace-ui/	User-facing coding-agent workspace UI: Cursor/Claude Code-style chat workspace with streaming tool cards, runtime adapters, event model, and multi-panel layout	Proposed (design-only)	README.md	—

How the sets relate

• The pack is the target; the review is the gap analysis; the four proposed sets each take a gap cluster: security-designs (credential/repo entitlement), secrets-and-environments (the scope hierarchy + identity), sandboxes-and-snapshots (the data plane), and agent-workspace-ui (the user-facing frontend layer).
• The agent-workspace-ui set is the user-facing layer that sits on top of all the backend sets. It owns the event model, runtime abstraction, component tree, and interaction flows. It references the backend contract types (RunRow, StreamEvent, EnvironmentProfile) defined in the SDK but does not depend on any specific backend implementation — the ChatModelAdapter seam isolates the UI from the data plane.
• They share dependencies — e.g. AgentRunContract.environment references the environment_profiles entity from secrets-and-environments; run-scoped secrets and the BYOK gateway attach to the run-token work referenced from sandboxes-and-snapshots and the review's slices; and the workspace UI's run states align with the sandbox lifecycle from background-agent-platform.

Coordination (active work)

.sisyphus/boulder.json tracks the currently-executing plan (multi-tenant-backend-confidence-plan). src/do/session-do.ts is the most contended file across the active plan and the two proposed plan sets that touch the spawn path — each proposed set's README has a "Coordination" section with the required merge order. Read it before starting execution.