Migration Agent Name Move

Agent-name Move Helper

Conclusion: first complete the parent migration router. Use this script only for one live POSIX Agent, a new basename under the same parent, and a supported local same-volume filesystem; otherwise HOLD.

Invoke the exact self-contained script

python <exact-change_name.py> <canonical-absolute-agent-workdir> <new-basename>

The bundled source is ../../scripts/change_name.py. It remains directly runnable and self-contained: stdlib plus the compatible existing LingTai runtime used to validate its registry. It does not import a companion migration module. As demonstrated by Lingtai-AI/lingtai-kernel#1722 dogfood, an exact fetched/copied script can drive an existing compatible runtime; installing the change that supplied the script is not a prerequisite. The background supervisor continues with that exact script.

Preflight and frozen plan

Before suspension, the script requires expected Agent metadata, one fresh heartbeat, one matching process, a held lease, an executable configured runtime, an absent .suspend, an absent .change-name-incomplete, an absent destination, and a supported libc no-replace primitive. Unsupported POSIX/libc cells refuse before lifecycle side effects.

Selected JSON rejects duplicate keys and non-standard NaN/infinity. The plan snapshots the complete relevant bin/, .pth, and direct_url.json inventory. Under the acquired migration lease it fingerprints that inventory again immediately before cutover, so a new or changed in-scope binding refuses while the source remains authoritative.

Project-local runtime rewrites

Only when a venv is lexically and canonically inside this Agent, the plan rebases:

• executable regular bin/ launcher shebangs whose entire interpreter field is one existing old-root path;
• absolute path lines in site-packages .pth files; and
• local file: URLs in direct_url.json, including case-insensitive localhost, while retaining query and fragment.

A rewritten shebang—including #! and its line ending—must be at most 255 encoded bytes, conservatively below the supported Linux executable-header bound and Darwin's larger bound. An editable import from outside the venv must be covered by one exact .pth path; unsupported executable/finder bindings refuse before suspension.

An external venv receives no runtime metadata writes. If its observed import origin is inside the old Agent root, the script refuses before suspension because external metadata repair is outside this lane.

The foreground handoff, background supervisor, clean source/target probes, and gated resumed Agent use an explicit Python environment: PYTHONPATH and PYTHONHOME are absent, bytecode writes and user-site imports are disabled, and other operator environment values are preserved. Thus the accepted target origin and resumed process use the same import lane.

Narrow MCP rewrites

The plan validates the registry first. It then rebases only the complete command field in ordinary supported stdio entries:

• top-level init.json.mcp entries whose type is "stdio" or omitted; and
• validated stdio records in workdir mcp_registry.jsonl.

A matching registry record whose source is "lingtai-curated" makes its init entry activation-only; all legacy init launcher fields remain unchanged and the Agent continues to derive the launcher from its current catalog. HTTP commands, args, env, secrets, prompts, arbitrary strings, external paths, and other files or registries are never rewritten.

When one selected init object or registry line changes, decoded JSON values are preserved semantically—not byte-for-byte formatting, whitespace, or escape spelling. Duplicate keys and malformed in-scope data refuse before suspension.

Transaction and gated launch

The supervisor follows these visible phases:

1. Exclusively create .suspend with no-follow, regular mode-0600 semantics and parent fsync; wait for process, heartbeat, and lease release.
2. Hold the migration lease; exclusively create and verify the durable mode-0600 .change-name-incomplete fence; revalidate the frozen plan.
3. Publish exactly one Linux RENAME_NOREPLACE or macOS RENAME_EXCL rename and immediately fsync the shared parent. The target is authoritative from this point; no automatic move, rollback, or deletion occurs.
4. While still holding the lease and target fence, apply every planned mode-preserving atomic rewrite with file and parent-directory fsync; require the clean target probe to equal the exact planned import origin; verify immutable identity; write only .agent.json.address; remove .suspend; and prepare/check a pipe-gated child.
5. Only at that coherent prepared boundary, remove the proven fence, release the lease, send one launch byte, and require target process/identity/heartbeat liveness.

A pre-rename failure durably removes only the proven helper-created source fence; the source, possibly suspended, stays authoritative. The launch child cannot enter cli.run before the lease release and commit byte. The fence ordering prevents a normal lingtai run <new> from clearing .suspend and constructing an Agent against partial target state; it does not claim to eliminate every same-privilege process race.

Before any gate commit, a launch-setup, fence-removal, lease-release, or gate-write failure durably restores the target fence, closes the gate, and reaps the helper-owned child. Any other unproven post-rename failure likewise leaves or durably restores the fence. Post-commit liveness failure is an inspection boundary.

The normal CLI refuses any shape at .change-name-incomplete before signal cleanup, init loading, or Agent construction and never consumes it. Clearing the fence is separately authorized recovery.

Scope and acceptance boundary

The script has no Windows, network-filesystem, cross-parent, cross-volume, or whole-Project lane. It supports no copy/delete, rollback, peer rewrite, broad descriptor rewrite, integration, communication, or cleanup action.

Its success proves only the bounded filesystem, import, identity, process, and heartbeat checks above. It does not prove configured Telegram, IMAP, MCP, or any other integration health, nor the parent router's complete acceptance bundle. Run only owner-selected authorized external acceptance checks and record omitted ones as not authorized / not run; the generic script invents no channel-health protocol and performs no real-network test. On failure, follow the parent router's observed-phase table rather than retrying, restarting, repairing, clearing the fence, rolling back, or deleting without current authority.