Resolve orchestrator state from canonical data root

Context

The Sandman / Golden Path follow-up surfaced a false diagnostic path: peer checkouts can read an empty clone-local .neo-ai-data/orchestrator-daemon/ while the real running orchestrator writes state and logs under the canonical data root.

This made the initial investigation look like golden-path had not run hourly. Source and state evidence showed a narrower reality: the orchestrator golden-path task is hourly by default, and the canonical root state can record a successful run while a non-canonical checkout's local .neo-ai-data/orchestrator-daemon/ is empty or stale.

Live latest-open sweep: checked latest 20 open issues at 2026-06-24T17:35:39Z; no equivalent open issue found. A2A in-flight sweep: checked latest 30 messages at 2026-06-24T17:35:39Z; no overlapping active claim found.

Release classification: boardless (Agent OS substrate hardening; not a release-board gate by itself).

The Problem

ai/scripts/migrations/bootstrapWorktree.mjs intentionally blocklists orchestrator-daemon from .neo-ai-data symlink unification:

export const DATA_SUBDIRS_BLOCKLIST = ['concepts', 'orchestrator-daemon', 'embed-daemon'];

That exclusion was not random. Prior work around #13542 / #13545 identified a real trap: sharing orchestrator-daemon.pid across clones can make multiple clone-local orchestrators terminate each other via singleton enforcement. So blindly symlinking the whole directory is unsafe.

But the current operational invariant is also real: the canonical root owns the running orchestrator state/log. Peer diagnostics, harness checks, and Sandman freshness checks must read that root SSOT. Reading clone-local .neo-ai-data/orchestrator-daemon/ creates false stale/empty diagnostics and sends agents down the wrong lane.

The Architectural Reality

• #12065 establishes the orchestrator-daemon as the canonical writer for the REM / Golden Path handoff pipeline.
• #11548 operationalized resources/content/sandman_handoff.md as a canonical single-file handoff substrate, but it does not solve daemon state/log discovery.
• #12417 introduced the broader NEO_AI_DATA_ROOT direction for shared Agent OS runtime data, including orchestrator state, but the current bootstrap blocklist and diagnostic habits still permit clone-local reads.
• #13542 / #13545 captured the safety trap: daemon PID directories are not equivalent to wake-daemon or memory-wal; sharing process-control files can create cross-clone daemon interference.
• Current source evidence: ai/config.mjs sets orchestrator.intervals.goldenPathMs to HOUR_MS, ai/daemons/orchestrator/scheduling/registry.mjs defines a separate golden-path task, and pipeline.mjs dispatches it through GoldenPathSynthesizer.synthesizeGoldenPath().

The Fix

Add a narrow canonical-state resolution path for orchestrator diagnostics and peer harness checks without regressing the daemon PID safety guard.

The implementation should choose the smallest safe substrate, likely one of:

1. A helper that resolves the canonical orchestrator state/log directory from NEO_AI_DATA_ROOT / canonical root configuration and falls back to the local path only when no canonical root is configured.
2. Bootstrap guidance that keeps orchestrator-daemon blocklisted for process-control safety but explicitly documents that diagnostics must read the canonical root state/log.
3. Tests or diagnostics proving a non-canonical checkout does not treat an empty local .neo-ai-data/orchestrator-daemon/ as authoritative when a canonical root exists.

Do not symlink the whole orchestrator-daemon directory unless the implementation also proves root-only daemon ownership and prevents cross-clone PID/lock interference.

Contract Ledger Matrix

Acceptance Criteria

• A non-canonical checkout can resolve the canonical orchestrator state/log source for diagnostics when a canonical data root is configured.
• Diagnostics do not report golden-path stale solely because clone-local .neo-ai-data/orchestrator-daemon/ is empty.
• orchestrator-daemon is not blindly symlinked in a way that shares pid/process-control files across clone-local orchestrator instances.
• The effective state/log source path is visible in diagnostic output or documented verification steps.
• Tests cover canonical-root-present vs canonical-root-absent behavior.
• Documentation/JSDoc preserves the #13542/#13545 safety rationale while explaining the canonical-read path.

Out of Scope

• Reworking the hourly golden-path scheduler itself.
• Reopening manual runSandman as a normal agent action.
• Symlinking resources/content/ as a parent directory.
• Changing the generated handoff content limits from #13956/#13957.
• Any fix that requires multiple orchestrators to coordinate through one shared pid file.

Avoided Traps

• Trap: symlink the whole orchestrator-daemon directory because other .neo-ai-data children are symlinked. Rejected: prior V-B-A found cross-clone SIGTERM risk.
• Trap: trust the clone-local daemon-state directory because it exists. Rejected: an empty local directory can be stale observer state, not the running daemon state.
• Trap: conclude golden-path did not run hourly from a stale peer checkout. Rejected: #13755 already records this exact correction class.

Related

Parent: #13755

Related: #12065, #11548, #12417, #13542

Origin Session ID: cd4ef6e5-e52d-475f-a8b1-a9b781c5c91d

Handoff Retrieval Hint: orchestrator-daemon root SSOT blocklist canonical state log golden-path stale peer checkout