Orchestrator daemon refactor left stale path references

Context

First-real-world cloud-deployment exercise (external operator authoring an ai/deploy-canonical-mirror compose stack) surfaced that PR #11844 (Sub 8: Orchestrator-cluster co-location ai/scripts/orchestrator-daemon.mjs → ai/daemons/orchestrator/daemon.mjs) merged with three stale references to the pre-refactor entrypoint path. Tests pass and CI is green for the canonical neo checkout, but the cloud-profile container build is currently unbuildable from ai/deploy/docker-compose.yml as-published, and post-crash self-recovery of the running daemon is broken under the new filename.

The drift is mechanical follow-up, not architectural — ai/daemons/orchestrator/ is the correct location per ADR 0014 implementation. The fix is path-aligning the three downstream consumers.

The Problem

PR #11844 relocated the orchestrator daemon and made Orchestrator.mjs / daemon.mjs substantially lighter. Three references to the pre-refactor path ai/scripts/orchestrator-daemon.mjs were not updated:

1. Compose entrypoint — ai/deploy/docker-compose.yml:137 passes SERVICE_ENTRYPOINT: ai/scripts/orchestrator-daemon.mjs to the canonical ai/deploy/Dockerfile. The build stage proceeds (Dockerfile does not stat the path), but the resulting container CMD references a non-existent file, so the orchestrator service is unbuildable end-to-end under --profile cloud. Verified empirically against dev HEAD (test -f ai/scripts/orchestrator-daemon.mjs returns false).

2. Self-detection regex — ai/daemons/orchestrator/daemon.mjs:98 reads if (cmd.includes('orchestrator-daemon.mjs')) for stale-PID detection during crash recovery. The new entrypoint filename is daemon.mjs, so a crash-recovered process whose cmd line contains only daemon.mjs will fail self-detection. Tests do not exercise the crash-recovery path against the new filename (CI green is consistent with this gap).

3. JSDoc @module paths — ai/daemons/orchestrator/daemon.mjs:2 cites @module ai/scripts/orchestrator-daemon; Orchestrator.mjs:108,150 JSDoc prose cites ai/scripts/orchestrator-daemon.mjs in @see and inline-prose form. Documentation drift only — not a build break — but mis-routes any future reader following the @module path.

The Architectural Reality

Affected files (verified at dev HEAD):

• ai/deploy/docker-compose.yml:137 — build arg.
• ai/daemons/orchestrator/daemon.mjs:2 — module-level JSDoc.
• ai/daemons/orchestrator/daemon.mjs:36-37 — DAEMON_DATA_DIR + PID_FILE derivation is correct (writes to .neo-ai-data/orchestrator-daemon/, preserves the existing data-dir contract).
• ai/daemons/orchestrator/daemon.mjs:98 — self-detection regex.
• ai/daemons/orchestrator/Orchestrator.mjs:2,108,150 — module + class-level JSDoc references.

The .neo-ai-data/orchestrator-daemon/state.json path used by the canonical healthcheck in docker-compose.yml:179 is still correct — the data-dir contract was preserved by the refactor; only the entry-point filename moved.

The Fix

1. ai/deploy/docker-compose.yml:137: replace SERVICE_ENTRYPOINT: ai/scripts/orchestrator-daemon.mjs with SERVICE_ENTRYPOINT: ai/daemons/orchestrator/daemon.mjs.

2. ai/daemons/orchestrator/daemon.mjs:98: update the self-detect regex to match the new filename. Recommend matching the path-tail ai/daemons/orchestrator/daemon.mjs (more specific than bare daemon.mjs, which would collide with sibling daemons under ai/daemons/{bridge,kb-gc,kb-reconciliation,kb-alerting}/).

3. ai/daemons/orchestrator/{daemon,Orchestrator}.mjs JSDoc: replace ai/scripts/orchestrator-daemon / .mjs with ai/daemons/orchestrator/daemon / .mjs at the cited lines.

Contract Ledger

Decision Record impact

aligned-with ADR 0014 — implementation cleanup under existing authority. No ADR successor risk; ADR 0014 already describes the post-refactor topology.

Acceptance Criteria

• ai/deploy/docker-compose.yml:137 SERVICE_ENTRYPOINT points at ai/daemons/orchestrator/daemon.mjs.
• ai/daemons/orchestrator/daemon.mjs:98 self-detection matches the new filename without colliding with sibling daemons.
• ai/daemons/orchestrator/daemon.mjs:2 @module cites ai/daemons/orchestrator/daemon.
• ai/daemons/orchestrator/Orchestrator.mjs:2,108,150 JSDoc references cite ai/daemons/orchestrator/daemon.mjs.
• docker compose -f ai/deploy/docker-compose.yml --profile cloud build succeeds against dev HEAD (regression guard for the entrypoint fix).
• Unit spec exists for the self-detect path under the new filename (regression guard for the self-detect fix).
• No other repo-wide grep matches for ai/scripts/orchestrator-daemon remain (post-merge-only check).

Out of Scope

• Changes to the post-refactor data-dir contract (.neo-ai-data/orchestrator-daemon/) — preserved intentionally by #11844.
• Sibling-daemon JSDoc audits (ai/daemons/{bridge,kb-gc,kb-reconciliation,kb-alerting}/). Likely warrant the same sweep; file as a separate sub if confirmed.
• Cloud-profile compose changes beyond the entrypoint path (resource limits, healthcheck cadence, profile gating, etc.).

Avoided Traps

• Splitting into three tickets per stale surface — rejected; all three stem from the same mv semantics and a single agent can address them in one PR.
• Generic bare daemon.mjs regex in the self-detect — rejected for collision risk with ai/daemons/{bridge,kb-gc,kb-reconciliation,kb-alerting}/daemon.mjs.

Related

• PR #11844 (originating refactor — orchestrator-cluster co-location).
• PR #11849 (dev merge of #11844).
• ADR 0014 (cloud-deployment topology — substrate authority).
• Sibling sub-daemon refactor #11845 (potentially affected by analogous drift — sweep recommended).

Handoff Retrieval Hints

• Git anchor: git log --oneline 6cc917980 f81d18968 -- ai/daemons/orchestrator/ brackets the #11844 merge.
• Semantic query: "orchestrator daemon co-location stale path references" / "docker-compose SERVICE_ENTRYPOINT orchestrator".
• Grep: grep -rn 'ai/scripts/orchestrator-daemon' ai/ learn/ enumerates current matches; the ticket targets driving this to zero.