Use schema options for session permission mode

[julianknutsen]

Supersedes #1931.

Summary

• Adds POST /v0/city/{cityName}/session/{id}/permission-mode using existing schema options / template_overrides persistence.
• Keeps permission_mode durable until changed again; no live process permission mutation system.
• Validates permission_mode against the resolved provider options_schema before persisting.
• Rejects running, active, awake, creating, draining, quarantined, and recent-wake sessions so changes apply only before the next launch.
• Adds legacy /v0/session/{id}/permission-mode parity with X-GC-Request and X-GC-Index.
• Resolves provider/agent collisions from existing metadata and persisted provider/template data; does not persist real_world_app_session_kind.
• Updates OpenAPI, generated clients, dashboard generated types, and docs.

Verification

• .githooks/pre-commit passed, including lint, generated docs/schema checks, go vet ./..., and observable go test ./....
• make dashboard-check passed.
• Targeted regression tests passed for permission-mode updates, legacy route parity, durable overrides, runtime replay, and provider/agent collision handling.
• $review-pr dual-model loop passed with zero blockers and zero majors in both Claude and Codex lanes after fixes.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
gascityinc-5c0069dd	🟢 Ready	View Preview	May 13, 2026, 8:16 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[csells]

lgtm

[quad341]

@julianknutsen — first, thank you. This is genuinely excellent work and we want to ship it. Replacing the persisted real_world_app_session_kind discriminator with the metadata-derived UseAgentTemplateForProviderResolution helper (with the legacy reader keeping old beads working) untangles a real class of provider/agent collision bugs, and the truth-table tests in internal/session/provider_resolution_test.go plus the wake-in-flight grace boundary tests are exactly the shape we want. @csells's approval still stands.

The only thing in the way is the CONFLICTING merge state, and I tried to take that on my side and my automation tapped out — almost certainly because of the scope of the regeneration step, not anything about your code. Rather than make you wait while I rework the maintainer-side tooling, could you do one rebase pass and let it ride?

Concretely, the one thing I need:

1. Rebase fix/pr1931-schema-options onto fresh main.
2. Regenerate the conflicted artifacts rather than hand-merging them:
   • cmd/gc/dashboard/web/src/generated/{index.ts,schema.d.ts,sdk.gen.ts,types.gen.ts} — via make dashboard-check.
   • docs/schema/openapi.json, docs/schema/openapi.txt, internal/api/openapi.json, internal/api/genclient/client_gen.go — via the OpenAPI/genclient regeneration step from the Huma source of truth.
   • docs/reference/cli.md — via the doc-generation step.
3. For the non-generated conflicts (handler_sessions.go, session_runtime.go, handler_session_create.go, cmd_session.go, worker_handle.go), keep your helper-based call patterns — those are the substantive contribution and they're right.
4. Push. I'll re-verify with .githooks/pre-commit + make dashboard-check + the targeted Go tests, clear the stale status/review-failed label (the dispatched-suite rows are SKIPPED, not failed), and merge. No additional review needed — this is just the rebase.

If the rebase turns up anything ambiguous in the non-generated files, ping me and I'll dig in directly. And again — really nice work on this one, especially the boundary coverage around the wake grace. Sorry for the round-trip.

Review coverage:

• completed: claude codex
• unavailable: qwen