Turnkey peer onboarding runbook: one dry-run-first script chains define → repo → identity → launch → auth handoff

Context

The peer-onboarding rail's capstone leaf (parent #13015). Its prerequisite pieces are merged: PR #14918 (#14914 — curated per-family launch templates, isolated instance homes, minimal child env, live auth status) and PR #14950 (#14916 — roster generator, including the resident's subscriptionTemplate).

The former Day-0 provisioning-script slice (#14915 / closed PRs #14919 and #14931) is satisfied by composition:

• The merged roster entry is seeded into the graph by GraphService.initAsync on Memory Core boot.
• The first real peer boot materializes the wake route through WakeSubscriptionService.bootstrap from the boot envelope.
• Fleet instance linkage remains in the Fleet registry and lifecycle owner, never duplicated into graph identity nodes.

The Fix

ai/scripts/fleet/onboardPeer.mjs is a dry-run-first, two-phase conductor. Every Fleet read/write goes through the one long-lived dev-loopback Fleet owner; separate CLI invocations never create private lifecycle/process maps.

Phase A — before the roster merge

1. Define — create the exact curated Fleet definition, or refuse an occupied id whose GitHub login/harness family differs.
2. Repo — require coordinates for a new resident; create, reuse, or reconcile metadata.repo through the owner. Never launch in the Fleet process cwd. Reject credential-bearing/control-character clone inputs, and never render the clone URL.
3. Roster ceremony — print the #14950 generator command with the concrete harness family (gpt / claude).

Operator gate: merge the roster PR, refresh origin/dev, and restart the Memory Core server.

Phase B — after the gate

4. Preflight — prove membership from origin/dev:ai/graph/identityRoots.mjs (not the current worktree) and prove the seeded graph node through a read-only query. Missing or unreachable truth is REFUSE.
5. Launch — provision and start through the long-lived Fleet owner; repeat invocations share lifecycle truth and cannot double-spawn.
6. Auth handoff — when live status says authRequired === true, print a shell-safe command using the lifecycle-resolved instance home and actual AiConfig-resolved executable. False/unknown status never guesses a command. No auth contents cross the dev-loopback DTO.

Contract Ledger

Acceptance Criteria

• One command, dry-run by default, renders the honest two-phase segment delta.
• Phase A prints a valid concrete roster-generator command; Phase B cannot unlock from an unmerged worktree entry.
• Phase B refuses until merged roster membership and the seeded graph node are both verifiable.
• --commit launches through one long-lived owner and returns live auth/home/executable status without a process-local lifecycle split.
• Login output uses the actual lifecycle-resolved binary and is shell-safe; clone secrets/control payloads never persist or render.
• No contract reimplementation: Fleet writes and process ownership stay behind existing owner surfaces.
• Pure planner plus real cross-process/default-dispatch integration and security falsifiers.
• Cross-family approval on the final exact head.

Post-Merge Validation

• [L3-deferred — operator handoff needed] Run the live Phase A → roster PR/merge → Memory Core restart → Phase B/login → first-boot sequence for the second GPT-family peer.
• [L3-deferred — operator handoff needed] Confirm the live graph reports preflight OK, then confirm an unavailable graph refuses without spawning.

Out of Scope

Cockpit Add-Peer UI (#14807) · GitHub account creation and PAT issuance (operator-owned) · naming ritual (post-boot) · engine episode opening (observation-owned).

Related

Parent: #13015 · merged rail: #14914 / PR #14918 and #14916 / PR #14950 · closed-by-composition: #14915 · UI sibling: #14807 · v13.2 cornerstone-1 (#14560 / #13448).

Origin Session ID: b956ba53-01ed-4ea6-a1e5-62969f887bc3

Retrieval Hint: query_raw_memories("turnkey peer onboarding long-lived fleet owner origin/dev graph preflight auth handoff")