Migration Guide

Migration Guide — Agent and Project Path Relocation

Conclusion: classify the request, prove exact current authority, pass every common gate, choose one lane, and then read only that lane's reference. This router and its helpers grant no authority. HOLD on any missing, stale, ambiguous, or broader-than-written fact.

1. Classify

A Project-root move normally preserves every Agent's identity, true name, and basename address. Inventory affected owners' stale references without inferring permission to rewrite them.

2. Prove authority

Before every attempt, record current human-owner authority for:

• the canonical source and target, one-Agent or whole-Project scope, and every affected runtime;
• the exact quiescence, filesystem, launch, rewrite, staging/copy when relevant, cutover, recovery, source-retention, deletion, and cleanup actions allowed;
• the acceptable recovery state and decision owner; and
• each communication proof's channel, origin, peer, and bounded content.

Reading or installing this guide, finding a helper, or passing preflight proves no permission. This guide does not itself authorize target/staging creation, stop/signal/cancellation, refresh/relaunch/CPR, config or registry edits, symlinks, credential access, communication, deletion, cleanup, retry, rollback, or repair.

3. Pass the common gates

Recheck changing facts immediately before cutover or publication:

• Source identity: canonical non-symlink source, expected structure, and exact immutable identity tuple; enumerate every in-scope Agent in a Project.
• Target/no-replace: canonical non-symlink parent and absent final target, including no symlink; never merge or replace.
• Quiescence: account for human work, collaboration, async work, and all affected runtimes. Use only authorized lifecycle actions. Bind processes to executable, cwd, parent, and start identity; prove old processes gone, heartbeats stale/withdrawn, and OS leases acquirable. A failed scan or lock file alone proves nothing.
• Filesystem: establish same-volume or cross-volume from filesystem evidence. Unknown, unsupported, or network-filesystem semantics are HOLD.
• Recovery: freeze the allowed authoritative state, evidence location, receipt boundary, and human decision owner for every phase.

Keep raw evidence private.

4. Choose one lane

For cross-volume work, copy one quiesced closed snapshot to a fresh target-volume staging sibling using the exact authorized mechanism; verify a closed byte/tree manifest, required metadata, and every identity; then publish to the absent final target with a platform-proven no-replace operation. Keep the source quiesced and retained until target-origin acceptance. Never reinterpret rename as copy-and-delete: source deletion and staging cleanup require later authority.

5. Recover from the observed phase

No relaunch, retry, rollback, refresh, repair, deletion, cleanup, or recovery message follows by implication.

6. Accept only target-origin proof

Launch only when explicitly authorized. PASS needs one coherent post-cutover bundle proving:

1. exactly the expected target-bound process/incarnation, executable, parent, and start identity, with no old-source duplicate;
2. a fresh post-cutover heartbeat and target OS lease held by that process;
3. unchanged immutable identity and intended address semantics;
4. an isolated probe from the target interpreter and cwd, without inherited old-source paths, matching sys.executable, package source files, version/HEAD, and selector tuple;
5. connected health for only affected integrations; and
6. only when authorized, the named originating-channel greeting or round trip; otherwise record not authorized / not run and send nothing.

Any mismatch or unknown is HOLD; registry presence or heartbeat alone is not acceptance.

7. Emit a compact redacted receipt

operation/scope_authority: <Agent|Project>; <redacted reference>
source_target/volume_lane: <redacted labels>; <same|cross>
quiescence/source_identity/no_replace: PASS | HOLD
cutover_phase/outcome: <label>; retained_source: yes | not applicable
target_process_heartbeat_lease: PASS | HOLD
isolated_target_import_source_identity: PASS | HOLD
affected_integrations: PASS | HOLD | not applicable
communication: verified | not authorized / not run
final: PASS | HOLD; hold_reason: <sanitized category>

Keep paths, PIDs, private identifiers, credentials, messages, and logs in the approved private context, not a shared receipt.