feat(runtime): initialize and reconcile ordinary watchers

[bompus]

Ordinary watcher startup previously required an existing index and could reuse a ready watcher without requesting another reconciliation. startRuntimeWatcher now lets the elected daemon initialize a missing index at the exact requested root. It waits for a fresh reconciliation through that daemon before returning, including when reusing an existing watcher.

Initialization follows daemon election and guarded writer acquisition. Preserving CLI startup keeps the supplied root instead of resolving an uninitialized child to its indexed parent. Graph opening and refresh reject changed owner generations. Initialization failures retain partial databases and remove only the candidate's own coordination records.

The refresh uses the existing JSON-RPC connection and graph mutex. It finishes queued synthesis, rejects indexing or synthesis failures, and preserves shared daemons on caller timeout. A matching status response cannot acknowledge refresh. Legacy CLI initialization that ignores writer ownership remains outside these guards.

Build and full-suite validation passed with 7,549 tests and 39 existing skips. Golden validation passed all eight tests with no dump changes. Regression coverage includes real concurrent initializers, exact-child isolation, reused-watcher freshness, delayed and failed daemon refresh, same-PID successors, partial initialization cleanup, unreadable-file retry and pending-marker failure. The ordering test rejected a removed completion guard on detach -> watcher -> refresh; the source was restored before final checks.

The assertion-floor scanner flagged superseded missing-index rejection assertions, generalized owner-preservation assertions and an import of expect. The new cases retain the owner-preservation checks and test the selected initialization behavior. No skips or suppressions were added.

README's "About this fork" section was checked, including deferred synthesis, MCP launcher preservation and build revision behavior. README and the API and CLI site references document the guarded initialization flag and fresh reconciliation contract. The CLI reference addition addresses the documentation warning. Source logic stayed unchanged, so no further source review ran. No MCP tool schema or installer pointer changes are needed for this internal RPC. No installation, artifact promotion, managed runtime activation or release is included.

[coderabbitai]

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: 2f59efdb-862d-41eb-ba0e-e262975e5de6

📥 Commits

Reviewing files that changed from the base of the PR and between 33789df and 14d8e1d.

📒 Files selected for processing (1)

• site/src/content/docs/reference/cli.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features
  • Ordinary watcher startup can initialize a missing index when preserving existing data and providing an explicit project path.
  • Startup now waits for fresh indexing and synthesized-edge processing before reporting readiness. Reused watchers are refreshed before being considered ready.
  • The serve command supports an option to initialize an index.
• Documentation
  • Updated CLI, API, and runtime-control documentation to explain index initialization, refresh behavior, and readiness requirements.

Walkthrough

Watcher startup can initialize a missing index at the exact project root under daemon ownership. Startup and reuse request fresh reconciliation and report readiness only after file indexing, synthesized-edge processing, and ownership checks complete.

Changes

Watcher startup

Layer / File(s)	Summary
Require complete index reconciliation src/codegraph.ts, __tests__/sync-resynthesis.test.ts	sync() adds requireComplete handling. It rejects when synthesis is disabled, pending synthesis remains, indexing fails, or synthesis refresh fails. Tests cover retries, watcher indexing, unreadable files, and event sequences.
Initialize the exact project root under writer ownership src/directory.ts, src/bin/codegraph.ts, src/mcp/index.ts, src/mcp/daemon.ts, src/mcp/engine.ts, src/runtime-control.ts, __tests__/runtime-control.test.ts, site/src/content/docs/reference/api.md, site/src/content/docs/reference/cli.md	Startup adds guarded initialization for an explicit root. The daemon and engine validate index links and writer ownership. Tests cover uninitialized roots, build mismatches, concurrent starters, and ownership changes.
Refresh before reporting watcher readiness src/mcp/session.ts, src/mcp/daemon.ts, src/mcp/engine.ts, src/runtime-control.ts, __tests__/runtime-control.test.ts, README.md, CHANGELOG.md, site/src/content/docs/reference/api.md	Runtime readiness can request codegraph/refresh. The daemon validates identity and ownership around complete reconciliation, and readiness checks the refresh acknowledgement. Tests and documentation cover refresh on reuse and refresh failures.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 14d8e

No actionable merge-blocking issue is evident in the reviewed change context.

Architecture Summary

Architecture risk: 🔵 Low · up to 14d8e

The change affects 5 systems.

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

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — src (service) was modified; 8 changed files map to changed impact.
• observed — site (service) was modified; 2 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.

Before / after behavior

• observed — Modified behavior in CHANGELOG.md: Adds a changelog entry stating that ordinary watcher startup can initialize a missing project index under daemon ownership and waits for fresh file indexing and queued synthesized edges before reporting readiness.
• observed — Modified behavior in README.md: The MCP launcher handover paragraph is unchanged; it continues to describe replacement, opt-out behavior, legacy daemon handling, and version checks.
• observed — Modified behavior in README.md: The startRuntimeWatcher documentation now specifies exact-root index initialization under writer ownership and fresh reconciliation on startup, including when reusing a watcher. It waits for indexing and queued synthesized edges, and returns ready only after verifying ownership records; reconciliation failure or timeout prevents readiness. The previous text required verified writer ownership and stated that a readable index alone was insufficient, but did not describe reconciliation or index initialization.
• observed — Modified behavior in tests/runtime-control.test.ts: Adds a refreshRequests counter and resets it for each test.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: ordinary watcher startup can initialize a missing index and reconcile it.
Description check	✅ Passed	The description directly explains the startup, initialization, reconciliation, ownership safeguards, and validation changes.
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	The PR changes 14 files, but the diff adds no lint, type-check, or compiler suppression directive. It also changes no lint or TypeScript configuration file. The custom check passes.
User-Visible Changes Documented	✅ Passed	The diff adds the --initialize-index CLI flag. README.md documents the flag and its guarded initialization behavior, and site/src/content/docs/reference/cli.md documents its requirements and usa…

✨ Finishing Touches

🧪 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.}