@cleocode/core 2026.9.20 → 2026.9.21

package/dist/project-lifecycle.js

@@ -1,5 +1,5 @@
 /**
- * Project lifecycle engine — move, rename, and re-register CLEO projects.
+ * Project lifecycle engine — move, reroot, rename, and re-register CLEO projects.
  *
  * Provides the core operations for relocating a CLEO project on disk,
  * renaming it, and reconciling the nexus registry after manual moves.
@@ -7,12 +7,19 @@
  * All functions accept explicit absolute paths — no CWD-walk-up (AC7).
  *
  * @task T11010 — T10298-1
+ * @task T12552 — dry runs are pure
+ * @task T12556 — relocations RENAME; nothing is copied, so no stale copy exists
+ * @task T12558 — `rerootProject`, child/ancestor targets refused, tombstone
  */
-import { existsSync } from 'node:fs';
-import { cp, readFile, rename, writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve as resolvePath } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { copyFile, mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve as resolvePath, sep } from 'node:path';
+import { ExitCode } from '@cleocode/contracts';
+import { canonicalizePath, computeProjectHash, readPortableProjectId, resolveWorktreeRootForHash, } from '@cleocode/paths';
+import { withStrippedFieldsReceipt } from './doctor/project-identity.js';
 import { engineError, engineSuccess } from './engine-result.js';
 import { generateProjectHash, nexusReconcile, nexusRenameProject } from './nexus/index.js';
+import { computeStableProjectHash } from './project-scope.js';
 // ── Internal helpers ─────────────────────────────────────────────────
 /**
  * Read and parse project-info.json from the given project root.
@@ -51,103 +58,650 @@ function validateAbsolutePath(label, p) {
     }
     return null; // valid
 }
-// ── Public API ───────────────────────────────────────────────────────
+// ── Relocation helpers (T12552 · T12556 · T12558) ─────────────────────
 /**
- * Move a CLEO project to a new filesystem location.
- *
- * Copies the entire project directory tree to `newPath`, updates
- * `project-info.json` with the new project root and hash, reconciles
- * the nexus registry, and returns the result.
- *
- * The original directory is NOT removed — callers should verify the
- * move succeeded before cleaning up the old location.
- *
- * @param newPath - Absolute path to the new project root location.
- * @param projectRoot - Absolute path to the current project root.
- * @returns EngineResult with {@link MoveProjectResult} on success.
- *
- * @remarks AC3: Uses fs.cp for the filesystem move. The projectId is
- *   preserved across moves; projectHash is recomputed from the new path.
+ * Top-level entries `reroot` renames into the child, in order. `.github` is
+ * included only when it holds nothing but CLEO's own init templates (see
+ * {@link isCleoOwnedGithubDir}); a parent repository's real `.github` stays.
+ */
+const REROOT_ENTRIES = ['.cleo', '.worktreeinclude', '.github'];
+/** Nearest existing ancestor of `p` (itself when it exists). */
+function nearestExisting(p) {
+    let head = resolvePath(p);
+    while (!existsSync(head)) {
+        const parent = dirname(head);
+        if (parent === head)
+            break;
+        head = parent;
+    }
+    return head;
+}
+/**
+ * Canonical form of a path whose tail may not exist yet: the nearest existing
+ * ancestor is resolved through symlinks (macOS `/tmp` → `/private/tmp`) and
+ * the missing tail is appended, so containment compares like with like.
+ */
+function canonicalTarget(p) {
+    const resolved = resolvePath(p);
+    const head = nearestExisting(resolved);
+    return join(canonicalizePath(head), relative(head, resolved));
+}
+/** `true` when `inner` is strictly inside `outer` (both canonical). */
+function isStrictlyInside(outer, inner) {
+    const rel = relative(outer, inner);
+    return rel.length > 0 && !rel.startsWith(`..${sep}`) && rel !== '..' && !rel.startsWith(sep);
+}
+/** `true` when `target` (or its nearest existing ancestor) is on `source`'s device. */
+function sameDevice(source, target) {
+    return statSync(source).dev === statSync(nearestExisting(target)).dev;
+}
+/**
+ * `E_CROSS_DEVICE`: a relocation only renames within one device. The fix says
+ * to quiesce the project first — a plain `mv` across devices is a copy, so a
+ * live writer during it tears the database exactly as the old copy did.
+ */
+function crossDeviceRefusal(source, target, command) {
+    return engineError('E_CROSS_DEVICE', `"${target}" is on another device than "${source}"; cleo only relocates by rename within one device`, {
+        exitCode: ExitCode.INVALID_INPUT,
+        fix: `First end every session (\`cleo session end\`), stop every process writing to the project, and run \`cleo backup add\`. Then: ${command}`,
+    });
+}
+/** Read `projectId` from project-info.json, or the failure to return. */
+async function readRelocatableIdentity(projectRoot) {
+    const info = await readProjectInfo(projectRoot);
+    if (!info) {
+        return engineError('E_PROJECT_INFO_MISSING', `Failed to read project-info.json at "${projectRoot}"`, { exitCode: ExitCode.CONFIG_ERROR });
+    }
+    const projectId = typeof info.projectId === 'string' ? info.projectId : '';
+    if (!projectId) {
+        return engineError('E_NO_PROJECT_ID', `project-info.json at "${projectRoot}" is missing projectId`, { fix: 'Run `cleo init` to generate a projectId', exitCode: ExitCode.CONFIG_ERROR });
+    }
+    return { projectId };
+}
+/**
+ * CLEO worktrees provisioned for the project at `projectRoot`, plus git
+ * worktrees registered in its `.git/`. Both are keyed by absolute path, so a
+ * relocation would strand them.
+ */
+async function listBoundWorktrees(projectRoot, includeGit) {
+    const found = new Set();
+    const dir = resolveWorktreeRootForHash(computeProjectHash(projectRoot));
+    if (existsSync(dir)) {
+        for (const entry of await readdir(dir))
+            found.add(`CLEO worktree ${join(dir, entry)}`);
+    }
+    const { readSentinelIndex } = await import('./worktree/sentinel-index.js');
+    for (const entry of readSentinelIndex(projectRoot)) {
+        if (existsSync(entry.path))
+            found.add(`CLEO worktree ${entry.path}`);
+    }
+    const gitWorktrees = join(projectRoot, '.git', 'worktrees');
+    if (includeGit && existsSync(gitWorktrees)) {
+        for (const entry of await readdir(gitWorktrees)) {
+            found.add(`git worktree ${join(gitWorktrees, entry)}`);
+        }
+    }
+    return [...found].sort();
+}
+/**
+ * The refusal for a relocation while something is bound to the project. The
+ * fix names the exact command for each session, bound by `CLEO_SESSION_ID` so
+ * it ends THAT session rather than the caller's (T12500).
+ */
+function blockedError(code, worktrees, activeSessions) {
+    const steps = [
+        ...activeSessions.map((id) => `CLEO_SESSION_ID=${id} cleo session end`),
+        ...(worktrees.length > 0 ? ['remove each worktree listed in details.worktrees'] : []),
+        ...(worktrees.some((w) => w.startsWith('git worktree '))
+            ? ['for a git worktree whose directory is already gone, run `git worktree prune`']
+            : []),
+    ];
+    return engineError(code, `Cannot relocate while bound: ${[...worktrees, ...activeSessions.map((s) => `active session ${s}`)].join('; ')}`, {
+        exitCode: ExitCode.CONCURRENT_MODIFICATION,
+        details: { worktrees, activeSessions },
+        fix: `${steps.join(' && ')}, then retry`,
+    });
+}
+/** Ids of active sessions in the project store at `projectRoot`. */
+async function activeSessionIds(projectRoot) {
+    const { listSessions } = await import('./store/session-store.js');
+    return (await listSessions({ active: true }, projectRoot)).map((s) => s.id);
+}
+/**
+ * Required checkpoint before a relocation: the `cleo backup add` snapshot,
+ * then COPIED to `<cleoHome>/backups/<projectId>/<backupId>/` so it does not
+ * share fate with the tree it protects.
+ */
+async function takeCheckpoint(projectRoot, projectId, kind, target) {
+    try {
+        const { createBackup } = await import('./system/backup.js');
+        const backup = await createBackup(projectRoot, {
+            type: kind,
+            note: `before cleo project ${kind} ${target}`,
+        });
+        if (!backup.files.includes('tasks.db')) {
+            throw new Error('the project database was not captured');
+        }
+        const { getCleoHome } = await import('./paths.js');
+        const outside = join(getCleoHome(), 'backups', projectId, backup.backupId);
+        await mkdir(outside, { recursive: true });
+        const names = [
+            ...backup.files.map((f) => `${f}.${backup.backupId}`),
+            `${backup.backupId}.meta.json`,
+        ];
+        for (const name of names) {
+            const src = join(backup.path, name);
+            if (existsSync(src))
+                await copyFile(src, join(outside, name));
+        }
+        return engineSuccess({ id: backup.backupId, path: outside });
+    }
+    catch (err) {
+        return engineError('E_CHECKPOINT_FAILED', `Checkpoint before ${kind} failed: ${err.message}`, { exitCode: ExitCode.FILE_ERROR, fix: 'Run `cleo backup add` to diagnose, then retry' });
+    }
+}
+/** Where the checkpoint will be written, for a plan (nothing is created). */
+async function checkpointLocation(projectId) {
+    const { getCleoHome } = await import('./paths.js');
+    return join(getCleoHome(), 'backups', projectId, '<backupId>');
+}
+/** Open the global registry (dynamic: keeps the store graph off import). */
+async function openRegistry() {
+    const { getNexusRegistryDb } = await import('./store/nexus-sqlite.js');
+    const { getCleoHome } = await import('./paths.js');
+    return getNexusRegistryDb(getCleoHome());
+}
+/**
+ * Rebind the registry to `livePath` explicitly, then demote `demotedPath` to
+ * `missing` — exactly one live location remains.
  *
- * @example
- * ```typescript
- * const result = await moveProject('/new/location/project', '/old/project');
- * if (result.success) {
- *   console.log(`Moved to ${result.data.newPath}, hash=${result.data.newProjectHash}`);
- * }
- * ```
+ * Runs with the project scope pinned to `livePath`: the nexus handle is the
+ * AMBIENT project's `cleo.db`, and the ambient root is still the caller's cwd
+ * (the old root). Opening it there would create an empty store beside the
+ * moved one.
+ */
+async function rebindRegistry(projectId, livePath, demotedPath) {
+    const { captureProjectScope, worktreeScope } = await import('./project-scope.js');
+    const scope = captureProjectScope(livePath, worktreeScope.getStore());
+    try {
+        const reconcile = await worktreeScope.run(scope, () => nexusReconcile(livePath, { forceRebind: true }));
+        const { demoteProjectLocation } = await import('./nexus/path-map.js');
+        demoteProjectLocation(await openRegistry(), { projectId, projectPath: demotedPath, now: new Date().toISOString() }, 'missing');
+        return engineSuccess(reconcile.status);
+    }
+    catch (err) {
+        return engineError('E_NEXUS_RECONCILE_FAILED', `Files were relocated to "${livePath}" but the registry rebind failed: ${err.message}`, {
+            exitCode: ExitCode.GENERAL_ERROR,
+            details: { originalError: err.message },
+            fix: `Run \`cleo nexus reconcile --force-rebind\` in ${livePath}`,
+        });
+    }
+}
+/** Every file under `dir`, relative to it. */
+async function listFiles(dir, prefix = '') {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            out.push(...(await listFiles(join(dir, entry.name), rel)));
+        else
+            out.push(rel);
+    }
+    return out;
+}
+/**
+ * `true` when `<root>/.github` holds only files byte-identical to the GitHub
+ * templates `cleo init` installs — i.e. CLEO created it, not the repository.
+ */
+async function isCleoOwnedGithubDir(root) {
+    const { getPackageRoot } = await import('./scaffold/ensure-config.js');
+    const templates = join(getPackageRoot(), 'templates', 'github');
+    const githubDir = join(root, '.github');
+    if (!existsSync(templates))
+        return false;
+    const files = await listFiles(githubDir);
+    if (files.length === 0)
+        return false;
+    for (const file of files) {
+        const template = join(templates, file);
+        if (!existsSync(template))
+            return false;
+        const [a, b] = await Promise.all([readFile(join(githubDir, file)), readFile(template)]);
+        if (!a.equals(b))
+            return false;
+    }
+    return true;
+}
+/**
+ * Split CLEO's top-level entries at `root` into those reroot moves and those
+ * it must leave, given what `childDir` already holds.
  */
-export async function moveProject(newPath, projectRoot) {
-    // AC7: Validate absolute paths
+async function rerootEntries(root, childDir) {
+    const entries = [];
+    const excluded = [];
+    const clashes = [];
+    for (const entry of REROOT_ENTRIES) {
+        if (!existsSync(join(root, entry)))
+            continue;
+        if (entry === '.github') {
+            if (!(await isCleoOwnedGithubDir(root))) {
+                excluded.push({ entry, reason: 'holds files that are not CLEO init templates' });
+            }
+            else if (existsSync(join(childDir, entry))) {
+                excluded.push({ entry, reason: 'the child already has its own .github' });
+            }
+            else {
+                entries.push(entry);
+            }
+            continue;
+        }
+        if (existsSync(join(childDir, entry)))
+            clashes.push(entry);
+        else
+            entries.push(entry);
+    }
+    return { entries, excluded, clashes };
+}
+/** Rename `entries` from `from` to `to`; on any failure put back what moved. */
+async function renameEntries(from, to, entries) {
+    const done = [];
+    try {
+        for (const entry of entries) {
+            await rename(join(from, entry), join(to, entry));
+            done.push(entry);
+        }
+    }
+    catch (err) {
+        await renameBack(from, to, done);
+        throw err;
+    }
+}
+/** Undo {@link renameEntries} for `entries` (best effort, reverse order). */
+async function renameBack(from, to, entries) {
+    for (const entry of [...entries].reverse()) {
+        await rename(join(to, entry), join(from, entry)).catch(() => undefined);
+    }
+}
+export async function moveProject(newPath, projectRoot, opts = {}) {
     const pathErr = validateAbsolutePath('newPath', newPath);
     if (pathErr)
         return pathErr;
     const rootErr = validateAbsolutePath('projectRoot', projectRoot);
     if (rootErr)
         return rootErr;
-    // Validate source exists and has project-info.json
+    newPath = resolvePath(newPath);
     if (!existsSync(join(projectRoot, '.cleo', 'project-info.json'))) {
         return engineError('E_NOT_CLEO_PROJECT', `No CLEO project found at "${projectRoot}"`, {
             fix: 'Ensure the project was initialized with `cleo init`',
+            exitCode: ExitCode.CONFIG_ERROR,
         });
     }
-    if (resolvePath(newPath) === resolvePath(projectRoot)) {
-        return engineError('E_SAME_PATH', `newPath and projectRoot resolve to the same location: "${projectRoot}"`);
+    const source = canonicalizePath(projectRoot);
+    const target = canonicalTarget(newPath);
+    if (newPath === resolvePath(projectRoot) || source === target) {
+        return engineError('E_SAME_PATH', `newPath and projectRoot resolve to the same location: "${projectRoot}"`, { exitCode: ExitCode.INVALID_INPUT });
     }
-    // Read current project info
-    const info = await readProjectInfo(projectRoot);
-    if (!info) {
-        return engineError('E_PROJECT_INFO_MISSING', `Failed to read project-info.json at "${projectRoot}"`);
+    // Refused before any IO: a directory cannot be renamed into its own subtree
+    // or onto an ancestor.
+    const targetIsFile = existsSync(newPath) && !statSync(newPath).isDirectory();
+    if (isStrictlyInside(source, target)) {
+        return engineError('E_INVALID_TARGET', `newPath "${newPath}" is inside the project at "${projectRoot}"; a project cannot move into itself`, {
+            exitCode: ExitCode.INVALID_INPUT,
+            fix: targetIsFile
+                ? 'Choose a directory outside the project tree'
+                : `To make that directory the project root, run \`cleo project reroot ${relative(source, target)}\` from ${projectRoot}`,
+        });
     }
-    const projectId = typeof info.projectId === 'string' ? info.projectId : '';
-    if (!projectId) {
-        return engineError('E_NO_PROJECT_ID', `project-info.json at "${projectRoot}" is missing projectId`, { fix: 'Run `cleo init` to generate a projectId' });
+    if (isStrictlyInside(target, source)) {
+        return engineError('E_INVALID_TARGET', `newPath "${newPath}" contains the project at "${projectRoot}"; a project cannot move onto its own ancestor`, { exitCode: ExitCode.INVALID_INPUT, fix: 'Choose a path outside the project tree' });
     }
-    // AC3: Filesystem move via copy
-    // We copy rather than rename so the caller can verify before cleanup.
-    try {
-        // Create parent dirs if needed
-        const newParent = dirname(newPath);
-        const { mkdir } = await import('node:fs/promises');
-        await mkdir(newParent, { recursive: true });
-        // Copy the project tree (exclude node_modules for performance)
-        await cp(projectRoot, newPath, {
-            recursive: true,
-            filter: (src) => {
-                // Skip node_modules and .git directories during copy (they'll be
-                // reconstructed or linked by the caller after the move).
-                const base = basename(src);
-                return base !== 'node_modules' && base !== '.git';
+    if (targetIsFile) {
+        return engineError('E_INVALID_TARGET', `newPath is an existing file: "${newPath}"`, {
+            exitCode: ExitCode.INVALID_INPUT,
+            fix: 'Choose a path that does not exist yet, or an empty directory',
+        });
+    }
+    if (existsSync(newPath) && (await readdir(newPath)).length > 0) {
+        return engineError('E_INVALID_TARGET', `newPath is not empty: "${newPath}"`, {
+            exitCode: ExitCode.INVALID_INPUT,
+            fix: 'Choose a path that does not exist yet, or an empty directory',
+        });
+    }
+    const identity = await readRelocatableIdentity(projectRoot);
+    if ('success' in identity)
+        return identity;
+    const { projectId } = identity;
+    const crossDevice = !sameDevice(projectRoot, newPath);
+    const crossDeviceError = crossDeviceRefusal(projectRoot, newPath, `mv "${projectRoot}" "${newPath}" && cd "${newPath}" && cleo nexus reconcile — the carried nonce proves the move and git stays intact`);
+    const worktrees = await listBoundWorktrees(projectRoot, true);
+    if (opts.dryRun) {
+        return engineSuccess({
+            dryRun: true,
+            kind: 'move',
+            projectId,
+            source: projectRoot,
+            target: newPath,
+            transfer: 'rename',
+            entries: ['.'],
+            excluded: [],
+            writes: [],
+            registry: {
+                action: 'rebind',
+                livePath: newPath,
+                demotedPath: projectRoot,
+                demotedState: 'missing',
+                nonce: 'carried',
             },
+            checkpoint: await checkpointLocation(projectId),
+            blockers: [
+                ...(crossDevice ? ['E_CROSS_DEVICE: the target is on another device'] : []),
+                ...worktrees,
+            ],
+            deferredChecks: ['no active session (reads the project database)'],
         });
     }
-    catch (err) {
-        return engineError('E_MOVE_FAILED', `Failed to copy project from "${projectRoot}" to "${newPath}": ${err.message}`);
+    if (crossDevice)
+        return crossDeviceError;
+    const sessions = await activeSessionIds(projectRoot);
+    if (worktrees.length > 0 || sessions.length > 0) {
+        return blockedError('E_MOVE_BLOCKED', worktrees, sessions);
     }
-    // AC3: Update project-info.json with new path and hash
-    const newProjectHash = generateProjectHash(newPath);
-    const newInfo = {
-        ...info,
-        projectRoot: newPath,
-        projectHash: newProjectHash,
-        lastUpdated: new Date().toISOString(),
-    };
-    await writeProjectInfo(newPath, newInfo);
-    // Reconcile nexus registry with the new path
-    let reconcile;
+    const checkpoint = await takeCheckpoint(projectRoot, projectId, 'move', newPath);
+    if (!checkpoint.success)
+        return checkpoint;
+    const { closeAllDatabases } = await import('./store/sqlite.js');
+    await closeAllDatabases();
     try {
-        reconcile = await nexusReconcile(newPath);
+        await mkdir(dirname(newPath), { recursive: true });
+        await rename(projectRoot, newPath);
     }
     catch (err) {
-        return engineError('E_NEXUS_RECONCILE_FAILED', `Nexus reconcile failed for "${newPath}": ${err.message}`, { details: { originalError: err.message } });
+        if (err.code === 'EXDEV')
+            return crossDeviceError;
+        return engineError('E_MOVE_FAILED', `Failed to rename "${projectRoot}" to "${newPath}": ${err.message}`, { exitCode: ExitCode.FILE_ERROR, fix: 'Nothing was moved; check permissions and retry' });
     }
+    const rebound = await rebindRegistry(projectId, newPath, projectRoot);
+    if (!rebound.success)
+        return rebound;
     return engineSuccess({
+        dryRun: false,
         projectId,
         oldPath: projectRoot,
         newPath,
-        newProjectHash,
-        reconcileStatus: reconcile.status,
+        checkpointId: checkpoint.data.id,
+        checkpointPath: checkpoint.data.path,
+        reconcileStatus: rebound.data,
+    });
+}
+/**
+ * The registry path of `projectId` when it is a strict ancestor of `childDir`
+ * that no longer holds the project — i.e. an earlier reroot renamed `.cleo/`
+ * into `childDir` and stopped before rebinding.
+ */
+async function interruptedRerootSource(projectId, childDir) {
+    const { projectRegistry } = await import('./store/schema/nexus-schema.js');
+    const { eq } = await import('drizzle-orm');
+    const row = (await openRegistry())
+        .select({ projectPath: projectRegistry.projectPath })
+        .from(projectRegistry)
+        .where(eq(projectRegistry.projectId, projectId))
+        .get();
+    const oldRoot = row?.projectPath;
+    if (!oldRoot || !existsSync(oldRoot))
+        return null;
+    if (!isStrictlyInside(canonicalizePath(oldRoot), canonicalizePath(childDir)))
+        return null;
+    return existsSync(join(oldRoot, '.cleo', 'project-info.json')) ? null : oldRoot;
+}
+/**
+ * Keep `entry` out of commits in the repository containing `root` (T12558).
+ *
+ * Asks git for the exclude file (`rev-parse --git-path info/exclude`) and for
+ * `root`'s path inside the work tree (`--show-prefix`), so it works when
+ * `root` is a subdirectory of a repository and when `.git` is a FILE (a
+ * linked worktree or a submodule). The line is anchored to that repo-relative
+ * path. Local to this checkout — nothing tracked changes. Best effort: `root`
+ * may not be in a repository, and a tombstone is validated on read anyway.
+ */
+async function excludeFromGit(root, entry) {
+    const { execFile } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const git = async (...args) => (await promisify(execFile)('git', ['-C', root, ...args], { encoding: 'utf-8' })).stdout.trim();
+    try {
+        const exclude = resolvePath(root, await git('rev-parse', '--git-path', 'info/exclude'));
+        const line = `/${await git('rev-parse', '--show-prefix')}${entry}`;
+        await mkdir(dirname(exclude), { recursive: true });
+        const current = existsSync(exclude) ? await readFile(exclude, 'utf-8') : '';
+        if (current.split(/\r?\n/).includes(line))
+            return;
+        const joiner = current.length === 0 || current.endsWith('\n') ? '' : '\n';
+        await writeFile(exclude, `${current}${joiner}${line}\n`);
+    }
+    catch {
+        // Not in a repository, or git unavailable: the tombstone is still validated on read.
+    }
+}
+/**
+ * Finish a reroot from the child: identity, tombstone, rebind. Shared by the
+ * normal path (after the rename) and a resume.
+ */
+async function completeReroot(projectId, childDir, oldRoot) {
+    const { ensurePortableProjectId } = await import('./scaffold/project-identity.js');
+    const idOutcome = await ensurePortableProjectId(childDir, projectId);
+    if (idOutcome !== 'present' && idOutcome !== 'written') {
+        throw new Error(`.cleo/project-id could not record ${projectId} (${idOutcome})`);
+    }
+    const { PROJECT_TOMBSTONE_FILE, writeProjectTombstone } = await import('./project-tombstone.js');
+    const tombstone = writeProjectTombstone(oldRoot, {
+        projectId,
+        movedTo: childDir,
+        at: new Date().toISOString(),
     });
+    await excludeFromGit(oldRoot, PROJECT_TOMBSTONE_FILE);
+    const rebound = await rebindRegistry(projectId, childDir, oldRoot);
+    if (!rebound.success)
+        return rebound;
+    return engineSuccess({ projectIdFile: idOutcome, tombstone, status: rebound.data });
+}
+export async function rerootProject(childDir, projectRoot, opts = {}) {
+    const pathErr = validateAbsolutePath('childDir', childDir);
+    if (pathErr)
+        return pathErr;
+    const rootErr = validateAbsolutePath('projectRoot', projectRoot);
+    if (rootErr)
+        return rootErr;
+    if (!existsSync(join(projectRoot, '.cleo', 'project-info.json'))) {
+        return engineError('E_NOT_CLEO_PROJECT', `No CLEO project found at "${projectRoot}"`, {
+            fix: 'Run `cleo project reroot` from inside the project',
+            exitCode: ExitCode.CONFIG_ERROR,
+        });
+    }
+    if (!existsSync(childDir) || !statSync(childDir).isDirectory()) {
+        return engineError('E_INVALID_TARGET', `childDir is not an existing directory: "${childDir}"`, {
+            exitCode: ExitCode.INVALID_INPUT,
+            fix: 'Pass an existing subdirectory of the project',
+        });
+    }
+    const identity = await readRelocatableIdentity(projectRoot);
+    if ('success' in identity)
+        return identity;
+    const { projectId } = identity;
+    const source = canonicalizePath(projectRoot);
+    const target = canonicalizePath(childDir);
+    // Resume: `.cleo/` is already in this directory and the registry still names
+    // an ancestor that no longer holds the project.
+    if (source === target) {
+        const oldRoot = await interruptedRerootSource(projectId, childDir);
+        if (!oldRoot) {
+            return engineError('E_SAME_PATH', `"${childDir}" is already the project root and no interrupted reroot was found`, {
+                exitCode: ExitCode.INVALID_INPUT,
+                fix: 'Pass a subdirectory: `cleo project reroot <childDir>`',
+            });
+        }
+        if (opts.dryRun) {
+            return engineSuccess({
+                dryRun: true,
+                kind: 'reroot',
+                projectId,
+                source: oldRoot,
+                target: childDir,
+                transfer: 'rename',
+                entries: [],
+                excluded: [],
+                writes: [join(oldRoot, '.cleo-moved.json')],
+                registry: {
+                    action: 'rebind',
+                    livePath: childDir,
+                    demotedPath: oldRoot,
+                    demotedState: 'missing',
+                    nonce: 'carried',
+                },
+                checkpoint: 'none: resuming an interrupted reroot',
+                blockers: [],
+                deferredChecks: [],
+            });
+        }
+        try {
+            const done = await completeReroot(projectId, childDir, oldRoot);
+            if (!done.success)
+                return done;
+            return engineSuccess({
+                dryRun: false,
+                projectId,
+                oldRoot,
+                newRoot: childDir,
+                resumed: true,
+                checkpointId: '',
+                checkpointPath: '',
+                renamed: [],
+                projectIdFile: done.data.projectIdFile,
+                tombstone: done.data.tombstone,
+                reconcileStatus: done.data.status,
+                notes: rerootNotes(oldRoot, childDir),
+            });
+        }
+        catch (err) {
+            return engineError('E_IDENTITY_CONFLICT', err.message, {
+                exitCode: ExitCode.CONFIG_ERROR,
+                fix: 'Run `cleo doctor project-identity --resolve`, then `cleo project reroot .` again',
+            });
+        }
+    }
+    if (!isStrictlyInside(source, target)) {
+        return engineError('E_INVALID_TARGET', `childDir "${childDir}" is not inside the project at "${projectRoot}"`, {
+            exitCode: ExitCode.INVALID_INPUT,
+            fix: `To relocate the whole project, run \`cleo project move ${childDir}\``,
+        });
+    }
+    const { entries, excluded, clashes } = await rerootEntries(projectRoot, childDir);
+    if (clashes.length > 0) {
+        return engineError('E_INVALID_TARGET', `childDir already holds ${clashes.join(', ')}: "${childDir}"`, {
+            exitCode: ExitCode.INVALID_INPUT,
+            fix: `Move ${clashes.map((c) => join(childDir, c)).join(', ')} aside first; reroot never merges or overwrites`,
+        });
+    }
+    const tracked = readPortableProjectId(projectRoot);
+    if (tracked.status === 'invalid' ||
+        (tracked.status === 'valid' && tracked.projectId !== projectId)) {
+        return engineError('E_IDENTITY_CONFLICT', `.cleo/project-id does not agree with project-info.json at "${projectRoot}"`, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            fix: 'Run `cleo doctor project-identity` and resolve it first',
+        });
+    }
+    const worktrees = await listBoundWorktrees(projectRoot, false);
+    // A child can be a mount point: then `.cleo/` cannot be renamed into it.
+    const crossDevice = !sameDevice(projectRoot, childDir);
+    const crossDeviceError = crossDeviceRefusal(projectRoot, childDir, `mv "${join(projectRoot, '.cleo')}" "${join(childDir, '.cleo')}" && cd "${childDir}" && cleo project reroot .`);
+    if (opts.dryRun) {
+        return engineSuccess({
+            dryRun: true,
+            kind: 'reroot',
+            projectId,
+            source: projectRoot,
+            target: childDir,
+            transfer: 'rename',
+            entries,
+            excluded,
+            writes: [
+                ...(tracked.status === 'absent' ? [join(childDir, '.cleo', 'project-id')] : []),
+                join(projectRoot, '.cleo-moved.json'),
+            ],
+            registry: {
+                action: 'rebind',
+                livePath: childDir,
+                demotedPath: projectRoot,
+                demotedState: 'missing',
+                nonce: 'carried',
+            },
+            checkpoint: await checkpointLocation(projectId),
+            blockers: [
+                ...(crossDevice ? ['E_CROSS_DEVICE: the child is on another device'] : []),
+                ...worktrees,
+            ],
+            deferredChecks: ['no active session (reads the project database)'],
+        });
+    }
+    if (crossDevice)
+        return crossDeviceError;
+    const sessions = await activeSessionIds(projectRoot);
+    if (worktrees.length > 0 || sessions.length > 0) {
+        return blockedError('E_REROOT_BLOCKED', worktrees, sessions);
+    }
+    const checkpoint = await takeCheckpoint(projectRoot, projectId, 'reroot', childDir);
+    if (!checkpoint.success)
+        return checkpoint;
+    const { closeAllDatabases } = await import('./store/sqlite.js');
+    await closeAllDatabases();
+    try {
+        await renameEntries(projectRoot, childDir, entries);
+    }
+    catch (err) {
+        if (err.code === 'EXDEV')
+            return crossDeviceError;
+        return engineError('E_MOVE_FAILED', `Failed to rename ${entries.join(', ')} into "${childDir}": ${err.message}`, { exitCode: ExitCode.FILE_ERROR, fix: 'Nothing was moved; check permissions and retry' });
+    }
+    let done;
+    try {
+        done = await completeReroot(projectId, childDir, projectRoot);
+    }
+    catch (err) {
+        // Identity or tombstone failed before the registry changed: undo the renames.
+        await renameBack(projectRoot, childDir, entries);
+        const { rm } = await import('node:fs/promises');
+        await rm(join(projectRoot, '.cleo-moved.json'), { force: true });
+        return engineError('E_REROOT_FAILED', `Reroot rolled back: ${err.message}`, {
+            exitCode: ExitCode.FILE_ERROR,
+            fix: 'Nothing changed. Run `cleo doctor project-identity`, then retry',
+        });
+    }
+    if (!done.success) {
+        return engineError(done.error.code, done.error.message, {
+            exitCode: done.error.exitCode,
+            details: done.error.details,
+            fix: `The files are already in ${childDir}; run \`cleo project reroot .\` there to finish`,
+        });
+    }
+    return engineSuccess({
+        dryRun: false,
+        projectId,
+        oldRoot: projectRoot,
+        newRoot: childDir,
+        resumed: false,
+        checkpointId: checkpoint.data.id,
+        checkpointPath: checkpoint.data.path,
+        renamed: entries,
+        projectIdFile: done.data.projectIdFile,
+        tombstone: done.data.tombstone,
+        reconcileStatus: done.data.status,
+        notes: rerootNotes(projectRoot, childDir),
+    });
+}
+/** Git bookkeeping a reroot leaves to the operator. */
+function rerootNotes(oldRoot, newRoot) {
+    return [
+        `Commit .cleo/project-id in the repository at ${newRoot}`,
+        `The repository at ${oldRoot} now shows .cleo/ as deleted; do not restore it (commands there refuse with E_PROJECT_MOVED)`,
+    ];
 }
 /**
  * Rename a CLEO project (updates project-info.json name and hash).
@@ -191,13 +745,23 @@ export async function renameProject(newName, projectRoot) {
     const oldName = (typeof info.name === 'string' ? info.name : '') ||
         (typeof info.projectName === 'string' ? info.projectName : '') ||
         basename(projectRoot);
-    // AC4: Update project-info.json — only name changes, path stays same
-    const newProjectHash = generateProjectHash(projectRoot);
+    // AC4: Update project-info.json — only name changes. T12557: projectHash is
+    // a write-once identity key (release ids, audit rows), so the stored value is
+    // kept byte-identical. projectRoot is a path fact and is never written back:
+    // a legacy value is dropped into the same `strippedFields` receipt that
+    // `cleo doctor project-identity --resolve` keeps.
+    const newProjectHash = typeof info.projectHash === 'string' && info.projectHash.length > 0
+        ? info.projectHash
+        : computeStableProjectHash(projectRoot);
+    const now = new Date().toISOString();
+    const kept = info.projectRoot === undefined
+        ? info
+        : withStrippedFieldsReceipt(info, [{ file: 'project-info.json', field: 'projectRoot', value: info.projectRoot }], now, true);
     const newInfo = {
-        ...info,
+        ...kept,
         name: newName.trim(),
         projectHash: newProjectHash,
-        lastUpdated: new Date().toISOString(),
+        lastUpdated: now,
     };
     await writeProjectInfo(projectRoot, newInfo);
     // AC1, AC3, AC5: Register self-alias in nexus projectIdAliases table