[bompus]

Installers currently have to reconstruct writer records and daemon readiness outside CodeGraph. This adds a supported runtime-control module and SDK exports for verified identity, stop outcomes, updater reservations, bootstrap claims, release and usable project readiness.

Each reservation carries a unique generation. Acquisition, transfer and removal use the existing native mutation guard, so an old reservation cannot claim or release a successor held by the same PID. Unreadable ownership reports incomplete release. Readiness checks the hello, MCP build and actual project status, and resolves the caller's project path before sending it to a daemon with another working directory.

A bootstrap claims the reservation and runs the selected CLI in that same process. The validated coordination module must remain available separately from the executable across promotion and rollback. Live legacy writers are refused by default; an explicit cutover requires all older MCP sessions and direct or fallback writers to be quiescent. Process launch, services, artifact replacement and rollback policy remain with the installer.

Validation passed: Node24 build, 119 focused Node tests, 15 API cases under Bun, and the full suite (587 files, 7,492 passes, 39 existing skips). Hash-verified original implementations fail the release/readiness/path regressions; the corrections pass. A PID-only ownership mutation fails successor preservation. Real current and older managed CLI bootstrap probes preserve the PID across claim and CLI execution and serve the expected project from another working directory.

The focused cases cover serialized cross-process handoff, same-PID stale reservations, release read failure, usable status versus expected-condition guidance, relative project paths, build mismatch and explicit legacy cutover. The daemon lifecycle job includes these cases on Ubuntu, Windows and macOS.

README rows checked: upstream merge point, daemon replacement/runtime lifecycle, library API and historical retrieval/precision/performance measurements. The pinned upstream point and measured rows are unchanged; runtime-control documentation is added to README and the API reference.

Platform CI caught a path-alias mismatch in the fault-injection test. It now resolves the injected file through native realpath and exercises a directory alias. The test retains both release-preservation assertions and checks that the read error was injected. Native Windows Node 24 probes reproduce the short-path mismatch and confirm that native realpath matches the file path production reads. All 15 runtime-control tests pass under Node and Bun. No further model review ran because these corrections change only the test. Final lifecycle checks passed on Ubuntu, Windows and macOS. The pull request bot review completed with no findings.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository YAML (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: d0ae4a3d-f6ab-4c68-8eb0-e95ad103c3fa

📥 Commits

Reviewing files that changed from the base of the PR and between 87ccfd8 and b2beb1c.

📒 Files selected for processing (1)

• __tests__/runtime-control.test.ts

Limit details: You’ve used all 10 included reviews currently available.

---

📝 Summary

Summary by CodeRabbit

• New Features
  • Added installer controls to check daemon identity and readiness, stop runtimes, and reserve, transfer, or release writer ownership during build promotion and rollback.
  • Runtime shutdown preserves legacy daemons unless they are explicitly confirmed quiescent.
• Documentation
  • Added guidance on using installer runtime controls, coordinating writer ownership, and handling artifact swaps and rollback.

Walkthrough

The package adds runtime-control APIs for daemon identity, shutdown, writer ownership transfer, and readiness checks. It updates writer-lock handling, exports and documents the APIs, and adds tests and workflow coverage.

Changes

Installer runtime control

Layer / File(s)	Summary
Writer reservation and stop safeguards src/mcp/writer-lock.ts, src/mcp/daemon-registry.ts	Writer-lock operations now support reservations and record-identity updates. Daemon stopping can require writer-protocol support.
Runtime identity and writer handoff src/runtime-control.ts, __tests__/runtime-control.test.ts	Runtime-control functions read daemon identity, stop daemons, and reserve, claim, or release writer leases. Tests cover lease handling and shutdown outcomes.
Readiness checks and published installer API src/runtime-control.ts, __tests__/fixtures/runtime-control-daemon.cjs, __tests__/runtime-control.test.ts, src/index.ts, README.md, site/src/content/docs/reference/api.md, CHANGELOG.md, .github/workflows/daemon-lifecycle.yml	Readiness checks validate daemon identity, initialization, and status responses. Tests cover valid and invalid responses. The package exports and documents the runtime-control API, and the lifecycle workflow runs the tests.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to b2beb

The updater can transfer its reservation to the bootstrap process, which then claims the writer slot. No actionable merge-blocking risk remains.

Architecture Summary

Architecture risk: 🔵 Low · up to b2beb

The change affects 5 systems.

Changed systems: src, __tests__, CHANGELOG.md, README.md, site

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — src (service) was modified; 4 changed files map to changed impact.
• observed — tests (service) was modified; 2 changed files map to changed impact.
• observed — CHANGELOG.md (service) was modified; 1 changed file maps to changed impact.
• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in CHANGELOG.md: Adds a changelog entry documenting a supported runtime-control API for checking daemon readiness and safely transferring writer ownership during build promotion and rollback.
• observed — Modified behavior in README.md: Added documentation for the installer runtime-control API, including protocol version 1, daemon identity and readiness verification, stop outcomes, writer-slot reservation and claim during replacement bootstrap, module availability during replacement and rollback, and explicit quiescence for live legacy writers.
• observed — Modified behavior in tests/fixtures/runtime-control-daemon.cjs: Adds a daemon fixture that acquires and marks a writer lock, records process and socket metadata, serves a protocol-dependent JSON response, and releases the lock and removes the PID file on SIGTERM before exiting after server closure.
• observed — Modified behavior in site/src/content/docs/reference/api.md: The package description now includes storage primitives and installer runtime control among its exports, in addition to the CodeGraph class.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Suppressions Explained	✅ Passed	No changed line adds or broadens a lint, type-check, or compiler suppression directive. The changed-file inventory contains no lint or TypeScript configuration files. A patch-wide search found only `s…
User-Visible Changes Documented	✅ Passed	The diff adds runtime-control API exports and an internal stopDaemonAt option, but it does not add, remove, or rename a CLI command or flag, an MCP tool or tool argument, a supported language or fra…
Title check	✅ Passed	The title clearly summarizes the main change: exposing coordinated runtime promotion controls.
Description check	✅ Passed	The description explains the runtime-control APIs, their coordination requirements, and the reported validation. It is directly related to the changeset.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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