@cleocode/core 2026.9.23 → 2026.9.24

package/dist/doctor/project-identity.js

@@ -1,23 +1,30 @@
 /**
- * Inspect and resolve the portable project identity (T12353 · ADR-094).
+ * Inspect and resolve the portable project identity (T12353 · ADR-094 · T12716).
  *
- * `.cleo/project-id` is tracked and write-once. `project-info.json` holds the
- * id that local state is keyed by, and it is not tracked. T12325 made
- * `cleo init` report a disagreement between the two and keep the local id,
- * but left the operator without a way to see or fix it. This module is that
- * way:
+ * The tracked identity is `.cleo/project.json` `{schemaVersion, id, name}`
+ * (T12716), with the ADR-094 `.cleo/project-id` kept as a legacy mirror.
+ * `project-info.json` is untracked and device-local; its `projectId` is a
+ * cache of the tracked id. The tracked id always wins at runtime. This module
+ * is the ONLY place that migrates or re-keys identity files — nothing does it
+ * on open, init or upgrade:
  *
- * - {@link inspectProjectIdentity} is read-only. It classifies the pair, checks
- *   whether git actually tracks the file, and returns the exact remedy command.
- * - {@link resolveProjectIdentity} applies the remedy. For a conflict it
- *   re-keys the LOCAL side to the tracked id. The registry row's primary key
- *   and every alias pointing at the old id are updated in one registry
- *   transaction, and the old id is itself recorded as an alias. Nothing is
- *   deleted: rows elsewhere that still carry the old id (audit log, session
- *   manifest, background jobs) keep resolving through the alias table.
+ * - {@link inspectProjectIdentity} is read-only. It classifies the three
+ *   sources (project.json / project-id / project-info.json), checks whether
+ *   git actually tracks the canonical file, and returns the exact remedy.
+ * - {@link inspectProjectNameDrift} is read-only. It compares the registry's
+ *   label with the declared display name.
+ * - {@link resolveProjectIdentity} applies the remedy. A legacy project gets
+ *   `project.json` written from its `project-id` and `project-info.json` name
+ *   (no id ever changes). For a conflict it re-keys the LOCAL side to the
+ *   tracked id: the registry row's primary key and every alias pointing at the
+ *   old id are updated in one registry transaction, and the old id is itself
+ *   recorded as an alias. Nothing is deleted: rows elsewhere that still carry
+ *   the old id (audit log, session manifest, background jobs) keep resolving
+ *   through the alias table, and credentials sealed under it are re-wrapped on
+ *   their next open (`previousProjectIds`).
  *
- * The tracked file is never modified here. It is write-once, and a malformed
- * one is restored from version control, never regenerated.
+ * The id in a tracked file is never modified here. It is write-once, and a
+ * malformed file is restored from version control, never regenerated.
  *
  * T12557: `projectRoot` is a path fact, derived from the real root at runtime.
  * A persisted copy in `project-info.json` or `project-context.json` goes stale
@@ -29,13 +36,16 @@
  *
  * @task T12353
  * @task T12557
+ * @task T12716
  * @see ADR-094 — write-once portable project identity (amends ADR-013 §9)
+ * @see ADR-096 — one committed `.cleo/project.json` {id, name} (amends ADR-094)
  */
 import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { canonicalizePath, getCleoHome, isValidPortableProjectId, PORTABLE_PROJECT_ID_FILE, readDeclaredProjectIdentity, readPortableProjectId, } from '@cleocode/paths';
-import { ensurePortableProjectId } from '../scaffold/project-identity.js';
+import { canonicalizePath, getCleoHome, isValidPortableProjectId, isValidProjectDisplayName, PORTABLE_PROJECT_ID_FILE, PROJECT_MANIFEST_FILE, readDeclaredProjectIdentity, readPortableProjectId, readProjectIdFile, readProjectManifest, } from '@cleocode/paths';
+import { createProjectIdMirror, createProjectManifest, defaultProjectDisplayName, ensurePortableProjectId, } from '../scaffold/project-identity.js';
 import { detectRelocatedRoot } from '../store/relocated-store-guard.js';
 /** Command that reports identity state; the prefix of every remedy below. */
 const IDENTITY_COMMAND = 'cleo doctor project-identity';
@@ -95,9 +105,9 @@ function findDerivedFields(projectRoot) {
     }
     return found;
 }
-/** Git's view of the tracked file: `null` when this is not a git work tree. */
-function gitFileState(projectRoot) {
-    const rel = `.cleo/${PORTABLE_PROJECT_ID_FILE}`;
+/** Git's view of a tracked identity file: `null` when this is not a git work tree. */
+function gitFileState(projectRoot, file = PROJECT_MANIFEST_FILE) {
+    const rel = `.cleo/${file}`;
     const run = (args) => {
         try {
             execFileSync('git', args, { cwd: projectRoot, stdio: 'pipe', timeout: GIT_PROBE_TIMEOUT_MS });
@@ -116,7 +126,20 @@ function gitFileState(projectRoot) {
     return 'untracked';
 }
 /**
- * Classify the identity pair of a project, read-only.
+ * The name a migrated `project.json` records: the cached `displayName` (a
+ * legacy rename), else the cached `name`, when valid; else the basename.
+ */
+function migrationName(projectRoot, info) {
+    if (info && info !== 'unparseable')
+        for (const field of ['displayName', 'name', 'projectName']) {
+            const name = info.data[field];
+            if (typeof name === 'string' && isValidProjectDisplayName(name))
+                return name;
+        }
+    return defaultProjectDisplayName(projectRoot);
+}
+/**
+ * Classify the identity sources of a project, read-only.
  *
  * @param projectRoot - Absolute project root.
  * @returns The inspection with the exact remedy command.
@@ -128,26 +151,51 @@ function gitFileState(projectRoot) {
  * ```
  */
 export function inspectProjectIdentity(projectRoot) {
+    const manifest = readProjectManifest(projectRoot);
+    const legacy = readProjectIdFile(projectRoot);
     const tracked = readPortableProjectId(projectRoot);
     const info = readInfo(projectRoot);
     const trackedId = tracked.status === 'valid' ? tracked.projectId : null;
     const localId = info && info !== 'unparseable' ? info.id : null;
-    const base = { projectRoot, trackedId, localId, derivedFields: findDerivedFields(projectRoot) };
+    const manifestId = manifest.status === 'valid' ? manifest.manifest.id : null;
+    const legacyId = legacy.status === 'valid' ? legacy.projectId : null;
+    const base = {
+        projectRoot,
+        trackedId,
+        manifestId,
+        legacyId,
+        declaredName: manifest.status === 'valid' ? manifest.manifest.name : null,
+        localId,
+        derivedFields: findDerivedFields(projectRoot),
+    };
     // A CLEO root need not be a git work tree; git remedies apply only inside one.
-    let git;
-    const gitState = () => {
-        if (git === undefined)
-            git = gitFileState(projectRoot);
-        return git;
+    const gitStates = new Map();
+    const gitState = (file = PROJECT_MANIFEST_FILE) => {
+        if (!gitStates.has(file))
+            gitStates.set(file, gitFileState(projectRoot, file));
+        return gitStates.get(file) ?? null;
     };
     if (tracked.status === 'invalid') {
+        const rel = `.cleo/${tracked.file ?? PORTABLE_PROJECT_ID_FILE}`;
         return {
             ...base,
             state: 'invalid',
-            message: `.cleo/project-id is unusable (${tracked.reason}). CLEO never regenerates it.`,
+            message: `${rel} is unusable (${tracked.reason}). CLEO never regenerates it.`,
+            remedy: gitState() === null
+                ? `restore ${rel} from a backup of this project (the CLEO root is not a git work tree)`
+                : `git checkout -- ${rel}   (restore the committed file; inspect with \`git log -p -- ${rel}\`)`,
+        };
+    }
+    if (manifestId && legacy.status !== 'absent' && legacyId !== manifestId) {
+        return {
+            ...base,
+            state: 'mirror-conflict',
+            message: legacy.status === 'invalid'
+                ? `.cleo/project-id is unusable (${legacy.reason}), while .cleo/project.json declares ${manifestId}. CLEO uses ${manifestId}; builds that read only .cleo/project-id cannot.`
+                : `.cleo/project.json declares ${manifestId} but .cleo/project-id declares ${legacyId}. CLEO uses ${manifestId}; builds that read only .cleo/project-id use ${legacyId}.`,
             remedy: gitState() === null
-                ? 'restore .cleo/project-id from a backup of this project (the CLEO root is not a git work tree)'
-                : 'git checkout -- .cleo/project-id   (restore the committed id; inspect with `git log -p -- .cleo/project-id`)',
+                ? 'restore both files from a backup of this project; CLEO never rewrites a tracked id'
+                : 'inspect `git log -p -- .cleo/project.json .cleo/project-id`, then restore the edited file with `git checkout <commit> -- <file>` (CLEO never rewrites a tracked id)',
         };
     }
     if (info === undefined) {
@@ -159,7 +207,7 @@ export function inspectProjectIdentity(projectRoot) {
             return {
                 ...base,
                 state: 'not-adopted',
-                message: `.cleo/project-id declares ${relocated.projectId}, which was rerooted from here to ${relocated.movedTo} (${relocated.via}).`,
+                message: `The tracked identity declares ${relocated.projectId}, which was rerooted from here to ${relocated.movedTo} (${relocated.via}).`,
                 remedy: `cd "${relocated.movedTo}"   (the live project). A DIFFERENT project here needs a new id: \`cleo init --here --new-identity\``,
             };
         }
@@ -167,13 +215,13 @@ export function inspectProjectIdentity(projectRoot) {
             ? {
                 ...base,
                 state: 'not-adopted',
-                message: `.cleo/project-id declares ${trackedId}, but this checkout has not been initialized.`,
+                message: `The tracked identity declares ${trackedId}, but this checkout has not been initialized.`,
                 remedy: 'cleo init   (adopts the tracked id; it never mints a new one)',
             }
             : {
                 ...base,
                 state: 'uninitialized',
-                message: 'No project identity: neither .cleo/project-info.json nor .cleo/project-id exists.',
+                message: 'No project identity: none of .cleo/project.json, .cleo/project-id or .cleo/project-info.json exists.',
                 remedy: 'cleo init',
             };
     }
@@ -189,40 +237,60 @@ export function inspectProjectIdentity(projectRoot) {
         return {
             ...base,
             state: 'missing',
-            message: `.cleo/project-id is missing. The local id is ${localId}.`,
+            message: `No tracked identity: .cleo/project.json is missing. The local id is ${localId}.`,
             remedy: gitState() === null
-                ? `${IDENTITY_COMMAND} --resolve   (the CLEO root is not a git work tree; keep .cleo/project-id with the project)`
-                : `${IDENTITY_COMMAND} --resolve && git add .cleo/project-id && git commit -m "chore: track CLEO project id"`,
+                ? `${IDENTITY_COMMAND} --resolve   (the CLEO root is not a git work tree; keep .cleo/project.json with the project)`
+                : `${IDENTITY_COMMAND} --resolve && git add .cleo/project.json .cleo/project-id && git commit -m "chore: track CLEO project identity"`,
         };
     }
     if (trackedId !== localId) {
         return {
             ...base,
             state: 'conflict',
-            message: `Identity conflict: .cleo/project-id is ${trackedId}, but project-info.json is ${localId}. Two lineages; local state is still keyed by ${localId}.`,
+            message: `Identity conflict: the tracked id is ${trackedId}, but the project-info.json cache is ${localId}. Two lineages; CLEO uses ${trackedId}, while local state (registry row, aliases) is still keyed by ${localId}.`,
             remedy: `${IDENTITY_COMMAND} --resolve --dry-run   then   ${IDENTITY_COMMAND} --resolve   (re-keys local state to ${trackedId}; ${localId} stays resolvable as an alias)`,
         };
     }
+    if (!manifestId) {
+        return {
+            ...base,
+            state: 'legacy',
+            message: `Only the legacy .cleo/project-id records ${trackedId}; .cleo/project.json (id + name) does not exist yet.`,
+            remedy: gitState(PORTABLE_PROJECT_ID_FILE) === null
+                ? `${IDENTITY_COMMAND} --resolve --dry-run   then   ${IDENTITY_COMMAND} --resolve   (writes .cleo/project.json; no id changes)`
+                : `${IDENTITY_COMMAND} --resolve --dry-run   then   ${IDENTITY_COMMAND} --resolve && git add .cleo/project.json .cleo/.gitignore && git commit -m "chore: track CLEO project.json"   (no id changes)`,
+        };
+    }
+    if (!legacyId) {
+        return {
+            ...base,
+            state: 'mirror-missing',
+            message: `.cleo/project.json records ${trackedId}, but the legacy .cleo/project-id mirror is missing, so builds that read only that file cannot resolve the id.`,
+            remedy: gitState() === null
+                ? `${IDENTITY_COMMAND} --resolve   (writes the mirror)`
+                : `${IDENTITY_COMMAND} --resolve && git add .cleo/project-id && git commit -m "chore: track CLEO project-id mirror"`,
+        };
+    }
     if (gitState() === 'ignored') {
         return {
             ...base,
             state: 'ignored',
-            message: '.cleo/project-id is gitignored, so clones cannot inherit it. The .cleo/.gitignore predates ADR-094.',
-            remedy: 'cleo upgrade   (refreshes .cleo/.gitignore with `!project-id`), then git add .cleo/project-id',
+            message: '.cleo/project.json is gitignored, so clones cannot inherit it. The .cleo/.gitignore predates T12716.',
+            remedy: `${IDENTITY_COMMAND} --resolve   (adds \`!project.json\` to .cleo/.gitignore; \`cleo upgrade\` refreshes the whole file), then git add .cleo/.gitignore .cleo/project.json .cleo/project-id`,
         };
     }
-    if (gitState() === 'untracked') {
+    if (gitState() === 'untracked' || gitState(PORTABLE_PROJECT_ID_FILE) === 'untracked') {
         return {
             ...base,
             state: 'untracked',
-            message: '.cleo/project-id is not committed yet, so clones cannot inherit it.',
-            remedy: 'git add .cleo/project-id && git commit -m "chore: track CLEO project id"',
+            message: 'The tracked identity files are not committed yet, so clones cannot inherit them.',
+            remedy: 'git add .cleo/project.json .cleo/project-id && git commit -m "chore: track CLEO project identity"',
         };
     }
     return {
         ...base,
         state: 'ok',
-        message: `Project identity ${trackedId} is tracked and consistent.`,
+        message: `Project identity ${trackedId} ("${base.declaredName}") is tracked and consistent.`,
         remedy: null,
     };
 }
@@ -347,20 +415,81 @@ async function confirmCandidateCheckout(candidate, cleoHome) {
     }, { behavior: 'immediate' });
 }
 /**
- * Resolve the identity state that {@link inspectProjectIdentity} reported.
+ * If `.cleo/.gitignore` (a CLEO-managed file older than T12716) ignores
+ * `.cleo/project.json`, the surgical repair: insert `!project.json` beside
+ * `!project-id` (or append it). Nothing else in the file changes; a rule from
+ * any other ignore file is reported, never edited.
  *
- * - `missing` writes `.cleo/project-id` from the local id (create-only).
+ * @returns The step to report, or `null` when the file is not ignored.
+ */
+function allowManifestInGitignore(projectRoot, dryRun) {
+    const rel = `.cleo/${PROJECT_MANIFEST_FILE}`;
+    let source;
+    try {
+        source = execFileSync('git', ['check-ignore', '-v', '--no-index', rel], {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: GIT_PROBE_TIMEOUT_MS,
+            encoding: 'utf-8',
+        });
+    }
+    catch {
+        return null; // not ignored (exit 1), or not a git work tree
+    }
+    // `<source>:<line>:<pattern>\t<path>`; a matching `!pattern` means NOT ignored.
+    const [ignoreFile = '', , pattern = ''] = (source.split('\t')[0] ?? '').split(':');
+    if (pattern.startsWith('!'))
+        return null;
+    const cleoIgnore = join(projectRoot, '.cleo', '.gitignore');
+    if (ignoreFile !== '.cleo/.gitignore' || !existsSync(cleoIgnore)) {
+        return {
+            refused: `${rel} is ignored by ${ignoreFile || 'a gitignore rule'} (${source.trim()}). Allow it there (\`!${rel}\`), then git add ${rel}.`,
+        };
+    }
+    const step = {
+        action: 'allow-project-json',
+        detail: `add \`!${PROJECT_MANIFEST_FILE}\` to .cleo/.gitignore (it predates T12716 and ignores ${rel}); commit it with ${rel}`,
+    };
+    if (!dryRun) {
+        const lines = readFileSync(cleoIgnore, 'utf-8').split('\n');
+        const at = lines.findIndex((line) => line.trim() === `!${PORTABLE_PROJECT_ID_FILE}`);
+        if (at >= 0)
+            lines.splice(at, 0, `!${PROJECT_MANIFEST_FILE}`);
+        else
+            lines.splice(lines.at(-1) === '' ? lines.length - 1 : lines.length, 0, `!${PROJECT_MANIFEST_FILE}`);
+        writeFileSync(cleoIgnore, lines.join('\n'));
+    }
+    return step;
+}
+/**
+ * Resolve the identity state that {@link inspectProjectIdentity} reported —
+ * the ONLY migration path from the legacy files to `.cleo/project.json`
+ * (T12716); nothing migrates on open, init or upgrade.
+ *
+ * - `legacy` writes `.cleo/project.json` (create-only) from the legacy
+ *   `.cleo/project-id` id and the `project-info.json` name (else the
+ *   basename). `project-id` stays as the legacy mirror; no id changes.
+ * - `missing` writes `.cleo/project.json` and the `project-id` mirror from the
+ *   local id (create-only).
+ * - `mirror-missing` writes the legacy `.cleo/project-id` mirror (create-only).
+ * - Whenever `project.json` is (or is about to be) ignored by a pre-T12716
+ *   `.cleo/.gitignore` — including the `ignored` state — `!project.json` is
+ *   inserted there, so the file can be committed; nothing else in it changes.
  * - `info-invalid` re-runs the scaffold decision (tracked id or registry re-link).
  * - `conflict` re-keys local state to the tracked id. One registry transaction
  *   renames the row's primary key, re-points aliases and records the old id as
  *   an alias. Then `project-info.json` is rewritten, keeping the old id under
- *   `previousProjectIds`.
+ *   `previousProjectIds`, and `project.json` is written when only the legacy
+ *   file existed.
  * - In every state, persisted `projectRoot` fields are stripped first
  *   (T12557). The removed values are kept in `project-info.json`
  *   `strippedFields`. `projectHash` is never touched.
+ * - Last, a registry label that drifted from the declared name is synced
+ *   (see {@link inspectProjectNameDrift}), unless another project holds it.
  *
- * Every other state is refused with its remedy. The operation is idempotent:
- * re-running after a partial apply completes the remaining steps.
+ * Every other state (`invalid`, `mirror-conflict`, `untracked`, …) is refused
+ * with its remedy. The operation is idempotent: re-running after a partial
+ * apply completes the remaining steps.
  *
  * @param projectRoot - Absolute project root.
  * @param options - `dryRun` and registry home.
@@ -373,6 +502,42 @@ async function confirmCandidateCheckout(candidate, cleoHome) {
  * ```
  */
 export async function resolveProjectIdentity(projectRoot, options = {}) {
+    const resolution = await resolveIdentityFiles(projectRoot, options);
+    // A refusal with a remedy (invalid, mirror-conflict, …) stops here.
+    if (resolution.refused && resolution.refused !== NOTHING_TO_RESOLVE)
+        return resolution;
+    // Compare against the name project.json holds after the file steps, so a
+    // dry-run plans exactly what an apply does.
+    const writesManifest = resolution.steps.some((step) => step.action === 'write-project-json' || step.action === 'write-tracked-id');
+    // A dry-run conflict has not re-keyed yet: its row is still keyed by the
+    // cached id, while the apply compares after the re-key. Look the row up by
+    // the id it holds NOW, so both see the same row (review finding 2).
+    const rekeyPending = options.dryRun === true &&
+        resolution.steps.some((step) => step.action === 'rekey-registry-row');
+    const drift = await inspectProjectNameDrift(projectRoot, options.cleoHome, writesManifest ? migrationName(projectRoot, readInfo(projectRoot)) : undefined, rekeyPending ? (resolution.before.localId ?? undefined) : undefined);
+    if (drift.state !== 'drift' || drift.projectId === null || drift.declaredName === null)
+        return resolution;
+    const steps = [
+        ...resolution.steps,
+        {
+            action: 'sync-registry-name',
+            detail: `registry label '${drift.registryName}' -> '${drift.declaredName}' (the declared name)`,
+        },
+    ];
+    if (options.dryRun !== true) {
+        const { nexusRenameProject } = await import('../nexus/registry.js');
+        const { generateProjectHash } = await import('../nexus/hash.js');
+        const { worktreeScope } = await import('../project-scope.js');
+        const { projectId, declaredName } = drift;
+        // Scoped to the explicit root, so no ambient project owns the write.
+        await worktreeScope.run({ worktreeRoot: projectRoot, projectHash: generateProjectHash(projectRoot) }, () => nexusRenameProject(projectId, declaredName));
+    }
+    return { ...resolution, steps, refused: null };
+}
+/** Refusal text when nothing needs resolving. */
+const NOTHING_TO_RESOLVE = 'Nothing to resolve.';
+/** The file steps of {@link resolveProjectIdentity}, before the name sync. */
+async function resolveIdentityFiles(projectRoot, options) {
     const dryRun = options.dryRun === true;
     const before = inspectProjectIdentity(projectRoot);
     const steps = [];
@@ -407,20 +572,71 @@ export async function resolveProjectIdentity(projectRoot, options = {}) {
         if (!dryRun && !stripDerivedFields(projectRoot, before.derivedFields, new Date().toISOString()))
             return result('Cannot record a strip receipt: .cleo/project-info.json is missing or unreadable.');
     }
+    const name = migrationName(projectRoot, readInfo(projectRoot));
+    // A migrated or ignored project.json must be committable (T12716).
+    const allowStep = () => {
+        const allowed = allowManifestInGitignore(projectRoot, dryRun);
+        if (allowed === null)
+            return null;
+        if ('refused' in allowed)
+            return allowed.refused;
+        steps.push(allowed);
+        return null;
+    };
+    // T12716: the migration. Create-only; the id is copied, never changed.
+    const writeManifestStep = async (projectId) => {
+        steps.push({
+            action: 'write-project-json',
+            detail: `create .cleo/project.json = {id: ${projectId}, name: ${JSON.stringify(name)}} (.cleo/project-id stays as the legacy mirror; commit .cleo/project.json)`,
+        });
+        if (dryRun)
+            return null;
+        const outcome = await createProjectManifest(projectRoot, projectId, name);
+        return outcome === 'written' || outcome === 'present'
+            ? null
+            : `Cannot write .cleo/project.json (${outcome}).`;
+    };
     if (before.state === 'missing' && before.localId) {
         steps.push({
             action: 'write-tracked-id',
-            detail: `create .cleo/project-id = ${before.localId}`,
+            detail: `create .cleo/project.json = {id: ${before.localId}, name: ${JSON.stringify(name)}} and the .cleo/project-id mirror`,
         });
         if (!dryRun)
-            await ensurePortableProjectId(projectRoot, before.localId);
+            await ensurePortableProjectId(projectRoot, before.localId, name);
+        const ignored = allowStep();
+        await confirmCandidateStep();
+        return result(ignored);
+    }
+    if (before.state === 'legacy' && before.legacyId) {
+        const failed = await writeManifestStep(before.legacyId);
+        if (failed)
+            return result(failed);
+        const ignored = allowStep();
+        await confirmCandidateStep();
+        return result(ignored);
+    }
+    if (before.state === 'ignored') {
+        const ignored = allowStep();
+        await confirmCandidateStep();
+        return result(ignored);
+    }
+    if (before.state === 'mirror-missing' && before.manifestId) {
+        steps.push({
+            action: 'write-legacy-mirror',
+            detail: `create .cleo/project-id = ${before.manifestId} (for builds that read only that file; commit it)`,
+        });
+        if (!dryRun) {
+            const outcome = await createProjectIdMirror(projectRoot, before.manifestId);
+            if (outcome !== 'written' && outcome !== 'present')
+                return result(`Cannot write .cleo/project-id (${outcome}).`);
+        }
         await confirmCandidateStep();
         return result(null);
     }
     if (before.state === 'info-invalid') {
         steps.push({
             action: 'rewrite-project-info',
-            detail: 'regenerate the project-info.json id from .cleo/project-id or the registry',
+            detail: 'regenerate the project-info.json id from the tracked identity or the registry',
         });
         if (!dryRun) {
             const { ensureProjectInfo } = await import('../scaffold/ensure-config.js');
@@ -434,13 +650,14 @@ export async function resolveProjectIdentity(projectRoot, options = {}) {
     if (before.state !== 'conflict' || !before.trackedId || !before.localId) {
         if (before.remedy)
             return result(`${before.message} Remedy: ${before.remedy}`);
-        return result(steps.length > 0 ? null : 'Nothing to resolve.');
+        return result(steps.length > 0 ? null : NOTHING_TO_RESOLVE);
     }
     const oldId = before.localId;
     const newId = before.trackedId;
     const { getNexusRegistryDb } = await import('../store/nexus-sqlite.js');
-    const { projectIdAliases, projectRegistry } = await import('../store/schema/nexus-schema.js');
-    const { eq } = await import('drizzle-orm');
+    const { nexusAuditLog, projectGitState, projectIdAliases, projectLocations, projectRegistry } = await import('../store/schema/nexus-schema.js');
+    const { and, eq } = await import('drizzle-orm');
+    const { isSupersededRegistryPath, projectHolding } = await import('../nexus/path-map.js');
     const db = await getNexusRegistryDb(options.cleoHome ?? getCleoHome());
     const countRows = () => db.select().from(projectRegistry).all().length;
     const rowsBefore = countRows();
@@ -454,10 +671,25 @@ export async function resolveProjectIdentity(projectRoot, options = {}) {
         .from(projectRegistry)
         .where(eq(projectRegistry.projectId, newId))
         .get();
+    // Both ids registered: the cached id was registered before the tracked file
+    // arrived, and a later encounter registered the tracked id (review finding
+    // 5). When the cached-id row is THIS checkout, or its path no longer holds
+    // the cached id, the rows are one project: fold the cached-id row into the
+    // tracked row. Its content is kept whole in a nexus audit receipt, its
+    // locations move to the tracked id, and the cached id stays resolvable
+    // through the alias. A cached-id row still live elsewhere is a second
+    // lineage and is refused, never unregistered.
+    const merge = Boolean(oldRow && newRow);
     if (oldRow && newRow) {
-        return result(`Both ids are registered on this device: ${oldId} at ${oldRow.projectPath} and ${newId} at ${newRow.projectPath}. ` +
-            'One registry row cannot hold two paths. ' +
-            `Remedy: if ${newRow.projectPath} is gone or is a stale checkout, run \`cleo nexus unregister ${newId}\` and then re-run \`${IDENTITY_COMMAND} --resolve\`.`, { before: rowsBefore, after: rowsBefore });
+        const here = canonicalizePath(projectRoot);
+        const elsewhereLive = oldRow.projectPath !== here &&
+            !isSupersededRegistryPath(oldRow.projectPath) &&
+            projectHolding(oldRow.projectPath, oldId) !== 'no';
+        if (elsewhereLive) {
+            return result(`Both ids are registered on this device, and ${oldId} is still declared by ${oldRow.projectPath}. ` +
+                'That is a second checkout of the old lineage; nothing was changed. ' +
+                `Remedy: run \`${IDENTITY_COMMAND} --resolve --dry-run\` in "${oldRow.projectPath}" first (it adopts the tracked id there), then re-run it here.`, { before: rowsBefore, after: rowsBefore });
+        }
     }
     const newIdAlias = db
         .select()
@@ -473,7 +705,12 @@ export async function resolveProjectIdentity(projectRoot, options = {}) {
         .from(projectIdAliases)
         .where(eq(projectIdAliases.canonicalId, oldId))
         .all();
-    if (oldRow)
+    if (merge && oldRow && newRow)
+        steps.push({
+            action: 'merge-registry-row',
+            detail: `fold registry row ${oldId} (path ${oldRow.projectPath}, permissions ${oldRow.permissions}) into ${newId} (path ${newRow.projectPath} kept; stronger permissions and earlier registeredAt carried over); the whole row is kept in a nexus audit receipt and ${oldId} resolves through the alias`,
+        });
+    else if (oldRow)
         steps.push({
             action: 'rekey-registry-row',
             detail: `registry row ${oldId} -> ${newId} (path ${oldRow.projectPath} kept)`,
@@ -492,15 +729,80 @@ export async function resolveProjectIdentity(projectRoot, options = {}) {
         action: 'rewrite-project-info',
         detail: `project-info.json projectId ${oldId} -> ${newId} (previousProjectIds keeps ${oldId})`,
     });
-    if (dryRun)
-        return result(null, { before: rowsBefore, after: rowsBefore });
+    // Credentials sealed under the old id are re-wrapped eagerly, not on their
+    // next open (review finding 4). The step is the receipt: every row named.
+    const rewrapStep = async () => {
+        const { migrateProjectCredentialsAtRoot } = await import('../store/credential-transfer.js');
+        const plan = await migrateProjectCredentialsAtRoot(projectRoot, {
+            dryRun,
+            ...(options.cleoHome !== undefined && { cleoHome: options.cleoHome }),
+        });
+        if (plan.migrated.length === 0 && plan.reentry.length === 0)
+            return;
+        steps.push({
+            action: 'rewrap-credentials',
+            detail: `re-wrap ${plan.migrated.length} credential(s) under ${newId}: ${plan.migrated.map((c) => `${c.store}:${c.id}`).join(', ') || 'none'}${plan.reentry.length > 0 ? `; ${plan.reentry.length} cannot be opened and must be re-entered: ${plan.reentry.map((r) => `${r.store}:${r.id}`).join(', ')}` : ''}`,
+        });
+    };
+    if (dryRun) {
+        await rewrapStep();
+        if (!before.manifestId)
+            await writeManifestStep(newId);
+        return result(before.manifestId ? null : allowStep(), {
+            before: rowsBefore,
+            after: rowsBefore,
+        });
+    }
     const now = new Date().toISOString();
+    const foldedLocations = [projectLocations, projectGitState].flatMap((table) => db.select().from(table).where(eq(table.projectId, oldId)).all());
+    const rank = { read: 0, write: 1, execute: 2 };
+    const strongest = (a, b) => (rank[a] ?? 0) >= (rank[b] ?? 0) ? a : b;
     db.transaction((tx) => {
-        if (oldRow)
+        if (merge && oldRow && newRow) {
+            tx.insert(nexusAuditLog)
+                .values({
+                id: randomUUID(),
+                action: 'merge-identity',
+                projectHash: newRow.projectHash,
+                projectId: newId,
+                domain: 'nexus',
+                operation: 'doctor.project-identity.resolve',
+                source: 'cleo doctor project-identity --resolve',
+                success: 1,
+                detailsJson: JSON.stringify({ foldedRow: oldRow, foldedLocations, into: newId }),
+            })
+                .run();
+            tx.update(projectRegistry)
+                .set({
+                permissions: strongest(newRow.permissions, oldRow.permissions),
+                registeredAt: oldRow.registeredAt < newRow.registeredAt ? oldRow.registeredAt : newRow.registeredAt,
+            })
+                .where(eq(projectRegistry.projectId, newId))
+                .run();
+            tx.delete(projectRegistry).where(eq(projectRegistry.projectId, oldId)).run();
+        }
+        else if (oldRow)
             tx.update(projectRegistry)
                 .set({ projectId: newId })
                 .where(eq(projectRegistry.projectId, oldId))
                 .run();
+        // Per-checkout rows follow the id. A checkout the tracked id already
+        // records keeps the tracked row (earliest firstSeen carried over); the
+        // duplicate is in the receipt, so nothing is lost.
+        for (const table of [projectLocations, projectGitState]) {
+            for (const row of tx.select().from(table).where(eq(table.projectId, oldId)).all()) {
+                const at = (id) => and(eq(table.projectId, id), eq(table.deviceId, row.deviceId), eq(table.path, row.path));
+                const taken = tx.select().from(table).where(at(newId)).get();
+                if (!taken) {
+                    tx.update(table).set({ projectId: newId }).where(at(oldId)).run();
+                    continue;
+                }
+                if (table === projectLocations && 'firstSeen' in row && 'firstSeen' in taken)
+                    if (row.firstSeen < taken.firstSeen)
+                        tx.update(projectLocations).set({ firstSeen: row.firstSeen }).where(at(newId)).run();
+                tx.delete(table).where(at(oldId)).run();
+            }
+        }
         if (newIdAlias?.canonicalId === oldId)
             tx.delete(projectIdAliases).where(eq(projectIdAliases.legacyId, newId)).run();
         tx.update(projectIdAliases)
@@ -529,6 +831,117 @@ export async function resolveProjectIdentity(projectRoot, options = {}) {
             lastUpdated: now,
         });
     }
-    return result(null, { before: rowsBefore, after: countRows() });
+    await rewrapStep();
+    const manifestFailure = before.manifestId
+        ? null
+        : ((await writeManifestStep(newId)) ?? allowStep());
+    return result(manifestFailure, { before: rowsBefore, after: countRows() });
+}
+/**
+ * Compare the global registry's label for this project with the name the
+ * project declares in its committed `.cleo/project.json` (T12716), read-only.
+ * Only a committed name counts: a legacy project's cached name or basename
+ * differs per checkout, so it is never a drift source.
+ *
+ * @param projectRoot - Absolute project root.
+ * @param cleoHome - Global CLEO home whose registry is read.
+ * @param plannedName - The name `project.json` will hold once a planned
+ *   migration writes it (used by `--resolve` so its dry-run matches the apply).
+ * @param rowId - The id the registry row is keyed by right now, when it
+ *   differs from the declared id (a conflict whose re-key is only planned).
+ * @returns The drift report; an unreadable registry is `unavailable`, never `ok`.
+ *
+ * @example
+ * ```ts
+ * const drift = await inspectProjectNameDrift('/repo');
+ * if (drift.state === 'drift') console.log(drift.remedy);
+ * ```
+ * @task T12716
+ */
+export async function inspectProjectNameDrift(projectRoot, cleoHome, plannedName, rowId) {
+    const declared = readDeclaredProjectIdentity(projectRoot);
+    const declaredName = declared?.name ?? plannedName ?? null;
+    if (!declared) {
+        return {
+            state: 'undeclared',
+            projectId: null,
+            declaredName,
+            registryName: null,
+            message: 'The project declares no identity, so no registry row can be compared.',
+            remedy: 'cleo init',
+        };
+    }
+    try {
+        const { getNexusRegistryDb } = await import('../store/nexus-sqlite.js');
+        const { projectRegistry } = await import('../store/schema/nexus-schema.js');
+        const { eq } = await import('drizzle-orm');
+        if (declaredName === null) {
+            return {
+                state: 'no-declared-name',
+                projectId: declared.projectId,
+                declaredName,
+                registryName: null,
+                message: 'No .cleo/project.json yet, so the project declares no committed name.',
+                remedy: null,
+            };
+        }
+        const db = await getNexusRegistryDb(cleoHome ?? getCleoHome());
+        const row = db
+            .select({ name: projectRegistry.name })
+            .from(projectRegistry)
+            .where(eq(projectRegistry.projectId, rowId ?? declared.projectId))
+            .get();
+        const base = { projectId: declared.projectId, declaredName };
+        if (!row) {
+            return {
+                ...base,
+                state: 'not-registered',
+                registryName: null,
+                message: `No registry row for ${declared.projectId} on this device.`,
+                remedy: null,
+            };
+        }
+        if (row.name === declaredName) {
+            return {
+                ...base,
+                state: 'ok',
+                registryName: row.name,
+                message: `The registry label matches the declared name "${declaredName}".`,
+                remedy: null,
+            };
+        }
+        const holder = db
+            .select({ projectId: projectRegistry.projectId })
+            .from(projectRegistry)
+            .where(eq(projectRegistry.name, declaredName))
+            .all()
+            .find((other) => other.projectId !== (rowId ?? declared.projectId));
+        if (holder) {
+            return {
+                ...base,
+                state: 'taken',
+                registryName: row.name,
+                message: `The registry labels this project "${row.name}", but it declares "${declaredName}", which project ${holder.projectId} already uses on this device.`,
+                remedy: `cleo project rename <a-unique-name>   (here, or in the project ${holder.projectId})`,
+            };
+        }
+        return {
+            ...base,
+            state: 'drift',
+            registryName: row.name,
+            message: `The registry labels this project "${row.name}", but it declares "${declaredName}".`,
+            remedy: `${IDENTITY_COMMAND} --resolve   (syncs the registry label to the declared name)`,
+        };
+    }
+    catch (error) {
+        return {
+            state: 'unavailable',
+            projectId: declared.projectId,
+            declaredName,
+            registryName: null,
+            message: `Registry unavailable, name drift not checked: ${error instanceof Error ? error.message : String(error)}`,
+            remedy: null,
+        };
+    }
 }
 //# sourceMappingURL=project-identity.js.map