[procoduck]

What and why

v0.21.1 fixes from the post-release docs review (Part 0, items 0.1–0.4).

Migration 0051 (rolling-upgrade / rollback compatibility)

Migration 0050 made simulate_runs.effective_duration_seconds NOT NULL with no default. v0.20's CreateSimulateRun inserts only (org_id, graph, requested_duration_seconds, created_by), so a v0.20 pod could not create a sandbox run on the migrated schema (SQLSTATE 23502). That happens during a rolling upgrade and after helm rollback.

• New 0051_simulate_run_effective_nullable: DROP NOT NULL. The 1..120 CHECK stays. The down migration backfills NULLs from requested_duration_seconds, then SET NOT NULL. 0050 is not edited.
• GetSimulateRunByID, ClaimQueuedSimulateRun and CreateSimulateRun select COALESCE(effective_duration_seconds, requested_duration_seconds)::int. CompleteSimulateRun returns only id, org_id, which is all its caller reads. sqlc was regenerated. The worker and simulateRunToProto take the per-query row types, so the simulator, GetRun and MCP (which reads GetRun's proto) all get the coalesced value.
• Specs:
  • internal/store/simulate_run_effective_nullable_migration_test.go: a v0.20-shaped insert succeeds and reads back with effective = requested through Get and Claim; the CHECK still holds; the up/down round trip backfills and restores NOT NULL.
  • Worker spec: a v0.20-shaped row is sent to the simulator with the requested duration.
  • mgmtapi spec: GetRun reports effective = requested for that row.
• No proto, served-config or RBAC change.

Docs and chart notes

• UPGRADING.md 0.24.x → 0.25.0: step 6 and Rolling back no longer claim old pods ignore 0050. They now say what chart 0.25.0 does (v0.20 pods cannot start sandbox runs until all pods run v0.21) and that 0.25.1 removes this. Operators should upgrade straight to 0.25.1, and rollback works after 0051.
• NOTES.txt: the token command now uses kubectl exec -n <ns> svc/<fullname> -- shepherd token create …. deploy/ could land on a simulator or receiver pod. Pinned by a new chart_hardening spec.
• kubernetes.html 0.25/0.24 notes: run the new image's preflight against a database copy migrated with that image, or from a server pod right after the upgrade. Also notes that strict orgs reload once in two documented cases.
• README, site/index.html, collectors.html and ConnectClusterDialog now describe org-bound tokens. They are minted at Access → Agent Tokens. An app admin's token claims the cluster on the first poll. An org admin's token is served only for a cluster an app admin has already claimed. The mocked UI spec asserts the new copy.
• CHANGELOG: ### Fixed under Unreleased.

Testing

• go test ./internal/store/... ./internal/simulate/... ./internal/mgmtapi/... ./internal/mcp/... ./internal/migrations/... ./deploy/helm/...
• make lint (0 issues, guards OK)
• make web-ci, make test-ui (664 passed)
• make helm-lint, go test ./scripts/repocheck/
• make docs, make check-docs-drift, make check-docs-version
• ./scripts/build-web.sh run and internal/spa/dist/ staged (SPA copy changed)
• sqlc generate run and output committed (SQL changed; no proto change)
• full make test not run; ran the affected packages listed above

🤖 Generated with Claude Code

https://claude.ai/code/session_01TAAVzyeV4HSSNjU8xVWWtE