spec(control-plane): add workspace init and state persistence specs

[jsell-rh]

Summary

• Add workspace-init.spec.md — specifies the init container pattern for repo cloning, S3 state hydration, workflow cloning, and credential fetch before the runner starts
• Add state-persistence.spec.md — specifies the state-sync sidecar for periodic S3 workspace backup, git bundle backups, and graceful shutdown
• Update control-plane.spec.md with cross-references and REPOS_JSON in the env var table

Context

Supersedes draft PR #1477 which targeted the old file location (docs/internal/design/) before the spec reorg in #1488. Both capabilities exist in the operator but are completely missing from the CP path — sessions created via the new API have empty repo directories and no state persistence.

Key design decisions made during drafting:

• Init container auth: CP token endpoint via SA token (not BOT_TOKEN); hydrate.sh needs updating to support AMBIENT_CP_TOKEN_URL with BOT_TOKEN fallback for operator compat
• Init container presence: conditional (only when repos or S3 configured), not always-on like the operator
• Git credentials: fetched at runtime by hydrate.sh from the backend API, not pre-injected as env vars
• Workflow fields: resolved from Workflow resource via session.WorkflowID, not stored on session model directly

Verified against operator implementation (sessions.go:944-1015, hydrate.sh, sync.sh) through two rounds of parallel critic passes (schema, RBAC, terminology, operator parity).

Test plan

• Review workspace-init.spec.md against operator init container in reconcileSpecReposWithPatch
• Review state-persistence.spec.md against operator sidecar in sessions.go:1376-1419
• Verify cross-references from control-plane.spec.md resolve correctly
• Confirm no contradictions with CP Token Endpoint section in monolith

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Enhanced control-plane specification documents with detailed workspace initialization, state persistence patterns, and session management behavior definitions.

[netlify]

✅ Deploy Preview for cheerful-kitten-f556a0 ready!

Name	Link
🔨 Latest commit	bbd5f85
🔍 Latest deploy log	https://app.netlify.com/projects/cheerful-kitten-f556a0/deploys/69fcde343446880008d662b8
😎 Deploy Preview	https://deploy-preview-1526--cheerful-kitten-f556a0.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: a0046f9c-0e6d-4407-a69d-a5f8851d7d28

📥 Commits

Reviewing files that changed from the base of the PR and between a32da5f and bbd5f85.

📒 Files selected for processing (3)

• specs/control-plane/control-plane.spec.md
• specs/control-plane/state-persistence.spec.md
• specs/control-plane/workspace-init.spec.md

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

---

📝 Walkthrough

Walkthrough

This PR adds and updates control-plane specification documents defining workspace initialization and state persistence behavior. Three files are modified: the main control-plane spec is updated with references to these workflows, and two new detailed specs define init-container-based workspace provisioning and optional sidecar-based S3 state persistence. All features are marked as not yet implemented in the control plane.

Changes

Control Plane Workspace and State Specification

Layer / File(s)	Summary
Specification Framework specs/control-plane/control-plane.spec.md	Adds "Workspace Initialization and State Persistence" section clarifying that CP does not implement these behaviors; extends environment variable table to include REPOS_JSON with stopgap and intended init-container usage notes.
Workspace Initialization Details specs/control-plane/workspace-init.spec.md	Defines init-hydrate init-container requirements: conditional creation based on repos or S3 config, environment variables, token auth via CP endpoint, repo normalization to REPOS_JSON, S3 hydration phases, workflow cloning, and security context. Marked not implemented.
State Persistence Details specs/control-plane/state-persistence.spec.md	Specifies optional state-sync sidecar behavior: S3 workspace uploads (excluding /workspace/repos/), git bundle backups, metadata.json generation, checksum-based change detection, MAX_SYNC_SIZE handling, graceful shutdown sync, and required environment variables. Marked not implemented.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jsell/spec/cp-workspace-init-v2

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch jsell/spec/cp-workspace-init-v2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}