Operationalize Sandman handoff symlinks for active clones

Context

Operator V-B-A on 2026-05-17 surfaced that resources/content/sandman_handoff.md now exists in the canonical checkout, but the other active harness checkouts are not reliably seeing it.

This is not a greenfield bootstrap feature. Exact predecessor #10591 is closed and its implementation is present: ai/scripts/bootstrapWorktree.mjs already exports GITIGNORED_FILES_TO_LINK, includes resources/content/sandman_handoff.md, and wires symlinkGitignoredFiles() under --link-data. The remaining friction is operationalization and startup guidance: active independent clones can still be missing the symlink or can carry a stale real file from before #10591.

The Problem

The current active-clone evidence shows the failure mode #10591 was meant to prevent:

• Canonical checkout has a fresh resources/content/sandman_handoff.md runtime artifact.
• Codex checkout has no local file/symlink at that path.
• Antigravity checkout has a real file at that path, with older mtime and different hash than canonical.

That means agents can still normalize sandman_handoff.md absence/staleness during boot even though the canonical daemon output exists. The mid-session daemon-update case makes copies specifically wrong: if the daemon rewrites the canonical handoff, a copied file inside an independent clone immediately becomes stale; a symlink remains live.

The Architectural Reality

resources/content/sandman_handoff.md is gitignored and canonical-writer-owned. bootstrapWorktree.mjs correctly treats it as a gitignored single-file substrate, not tracked content and not an entire resources/content/ directory symlink.

The current substrate already encodes the right primitive:

• .gitignore ignores resources/content/sandman_handoff.md.
• ai/scripts/bootstrapWorktree.mjs documents the single-file symlink rationale and allows the file under GITIGNORED_FILES_TO_LINK.
• symlinkGitignoredFiles() is conservative: it links missing destinations, reports already-linked symlinks, skips absent canonical source, and skips real destination files with a warning instead of clobbering possible local state.

The gap is the operational/startup layer around that primitive.

The Fix

1. Update AGENTS_STARTUP.md worktree/bootstrap guidance so agents know --link-data also covers gitignored single files, specifically resources/content/sandman_handoff.md, not just .neo-ai-data/.
2. Clarify independent-clone usage: non-canonical clones must provide --canonical-root <canonical checkout> or NEO_AI_CANONICAL_ROOT before expecting the handoff symlink to exist.
3. Clarify the stale-real-file case: if an independent clone has a real resources/content/sandman_handoff.md, preserve/remove it deliberately and rerun the link step; do not copy over it and do not symlink the parent resources/content/ directory.
4. Verify the active Codex clone gets a symlink to canonical. Coordinate Antigravity remediation if outside-workspace mutation needs operator approval.
5. Do not reimplement #10591 unless V-B-A proves the current primitive fails; this ticket is about startup/operationalization first.

Contract Ledger Matrix

Acceptance Criteria

• AGENTS_STARTUP.md explicitly states that node ai/scripts/bootstrapWorktree.mjs --link-data links resources/content/sandman_handoff.md as a gitignored single-file substrate.
• AGENTS_STARTUP.md documents independent-clone usage with --canonical-root <canonical checkout> / NEO_AI_CANONICAL_ROOT for Codex and Antigravity-style sibling clones.
• AGENTS_STARTUP.md documents stale real-file remediation for resources/content/sandman_handoff.md: preserve/remove intentionally, rerun --link-data, never symlink resources/content/ as a parent directory.
• Active Codex checkout has resources/content/sandman_handoff.md as a symlink to the canonical file, verified by ls -l / readlink.
• Active Antigravity checkout remediation is either completed with operator-approved outside-workspace mutation or explicitly handed off with the exact stale-file evidence.
• No bootstrapWorktree.mjs logic changes unless V-B-A demonstrates the existing #10591 implementation does not satisfy the contract.

Out of Scope

• Rebuilding the #10591 symlinkGitignoredFiles() implementation.
• Scheduling Sandman / Golden Path runs; that belongs to the orchestrator/Sandman cadence work.
• Changing boot-time hard-refusal semantics from #11179 / #11260.
• Symlinking the parent resources/content/ directory.
• Manually editing sandman_handoff.md; it is daemon/generated runtime output.

Avoided Traps

• Trap: treat this as a missing bootstrap feature — rejected. #10591 already shipped the primitive.
• Trap: copy the file into each clone — rejected. Daemon rewrites canonical mid-session, making copies stale.
• Trap: overwrite a real local handoff file silently — rejected. bootstrapWorktree.mjs intentionally preserves real files and asks for deliberate removal.
• Trap: fold into #11260/#11179 — rejected. Those tickets cover boot-preflight semantics and are peer-assigned; this ticket covers active-clone symlink operationalization.

Related

• #10591 — closed predecessor that implemented the per-file symlink primitive.
• #11260 — related boot-preflight skill relocation, but not this operationalization slice.
• #11179 — related boot hard-refusal predicate, assigned to Gemini.
• ai/scripts/bootstrapWorktree.mjs
• AGENTS_STARTUP.md

Origin Session ID: 6e5b995a-c68e-4179-840c-a4cc48d449da

Handoff Retrieval Hint: sandman_handoff bootstrapWorktree cross-clone symlink active clone stale real file canonical-root