📝 docs: add complete Spark operator handbook - #72
Merged
Conversation
This was referenced Jul 30, 2026
zrr1999
force-pushed
the
codex/runtime-operator-handbook
branch
from
July 30, 2026 13:15
7d31119 to
2e6a259
Compare
zrr1999
marked this pull request as ready for review
July 30, 2026 13:21
zrr1999
added a commit
that referenced
this pull request
Jul 31, 2026
## Summary - finalize the Cockpit workspace already leased to a registered runtime binding instead of inserting a duplicate - keep the finalized Cockpit profile name and slug stable while the daemon continues to own local path and binding display identity - redirect workspace creation through the canonical persisted slug - cover idempotent finalization and post-heartbeat identity ownership ## Problem reproduced The first-run flow created a placeholder workspace during daemon registration, then tried to create a second workspace for the same runtime binding. Cockpit rejected the final step with `Runtime workspace binding already belongs to another Cockpit workspace`. ## Validation - isolated end-to-end daemon + Cockpit registration and finalization - final database: 1 workspace, 1 profile source, 1 active lease, 1 runtime binding - `pnpm --filter @zendev-lab/spark-cockpit-coordination run test` (136 tests) - Cockpit suite (634 tests) - `pnpm run check` - `pnpm run smoke` ## Stack 1. this PR 2. #71 CLI safety and diagnostics 3. #72 operator handbook
zrr1999
added a commit
that referenced
this pull request
Jul 31, 2026
## Summary - intercept nested help flags before daemon or Cockpit commands can mutate state - add focused Cockpit Web help for `spark cockpit web ...` - render direct CLI failures as concise text or a stable JSON error envelope instead of a stack trace - stop option parsing at `--` so literal prompt content keeps its meaning - make concurrent source CLI builds synchronize daemon migrations without directory replacement races ## Problems reproduced - `spark doctor --help` ran doctor instead of showing help - `spark cockpit web start --help` started a real background Cockpit - a rejected `spark daemon submit --json` printed a TypeScript stack trace - concurrent source CLI invocations raced on `dist/migrations` with `EEXIST` / `ENOTEMPTY` ## Validation - focused daemon and Cockpit CLI suites (70 tests) - isolated `SPARK_HOME`: nested help created no files and no Cockpit PID - rejected provider submission returns `action=error`, `code=cli_error`, and an actionable message - 8 concurrent daemon CLI builds; generated migrations exactly match the source directory - `pnpm run check` - `pnpm run smoke` ## Stack 1. #70 workspace finalization 2. this PR 3. #72 operator handbook
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Evidence behind the guide
The flow was exercised against an isolated source build: daemon start/status, Cockpit background service, first workspace registration, workspace finalization, session creation and Cockpit projection, unauthenticated-model behavior, nested help, and shutdown diagnostics.
Validation
pnpm run checkpnpm run smokeStack