@cleocode/core 2026.9.19 → 2026.9.21

package/dist/nexus/path-map.js

@@ -1,87 +1,623 @@
 /**
- * Device-local project path map (`nexus_project_paths`).
+ * Project locations (`nexus_project_locations`) — every place a project has
+ * been seen, on every device.
  *
- * The registry row is keyed by the immutable `project_id` (ADR-094), so its
- * `project_path` names one checkout — the one encountered most recently. The
- * path map records EVERY checkout of a project on this device, keyed by path,
- * so two checkouts of one project coexist instead of fighting over one row.
+ * The registry is keyed by the immutable `project_id` alone (ADR-094 ·
+ * T12469); its `project_path` names only the checkout encountered most
+ * recently. This table records every checkout as one row per
+ * `(project_id, device_id, path)`, so two checkouts of one project coexist and
+ * the same project on two devices keeps one registry row.
+ *
+ * Rows are never deleted because a directory vanished. When a project is
+ * recorded, this device's other `live` locations of it whose directory is gone
+ * move to `missing`; a location whose path now holds a different project moves
+ * to `superseded`. History therefore survives for consumers that need former
+ * paths (legacy path-derived credential candidates, T12475).
  *
  * Every writer that records a checkout in the registry records it here in the
  * same transaction: encounter registration, `nexusRegister`, `nexusReconcile`
- * and `nexusMoveProject`. Rows whose directory is gone are pruned when their
- * project is next recorded, so a move leaves one checkout, not two.
+ * and `nexusMoveProject`. Only an explicit unregister or clean removes rows.
+ *
+ * ## Compatibility with older binaries sharing the global store
+ *
+ * Older binaries still read the registry by path (`WHERE project_path = ?
+ * LIMIT 1`, and an owner filter of path OR hash OR id). Two registry rows at
+ * one path would make them pick a stale row and fail (`E_PROJECT_ID_DRIFT`,
+ * identity conflicts). So when a path changes hands, the previous holder's
+ * registry row is re-homed in the same transaction ({@link rehomeDisplacedRows}):
+ * to its most recent other live location on this device, or, if it has none,
+ * to the non-path sentinel {@link supersededRegistryPath} — which no path
+ * lookup can match. At most one registry row ever names a real path.
+ *
+ * The legacy `nexus_project_paths` map is dual-written (upsert only) for one
+ * release so older binaries keep reading a current map; drop it with a later
+ * migration once those binaries are gone.
  *
  * @task T12354
+ * @task T12469
+ */
+import { existsSync, lstatSync, readdirSync } from 'node:fs';
+import { lstat, readdir } from 'node:fs/promises';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { canonicalizePath, readDeclaredProjectIdentity } from '@cleocode/paths';
+import { and, desc, eq, inArray, ne } from 'drizzle-orm';
+import { getStableDeviceId } from '../llm/stable-device-id.js';
+import { projectLocations, projectPaths, projectRegistry } from '../store/schema/nexus-schema.js';
+import { generateProjectHash } from './hash.js';
+import { withinBudget } from './projects-scan.js';
+import { registryStorePath } from './registry-hygiene.js';
+/**
+ * Device id carried by rows the T12469 migration backfilled. SQL cannot read
+ * the device id, and the global store is device-local, so every such row
+ * belongs to this device; {@link adoptLocalDeviceRows} re-keys them.
+ */
+export const LOCAL_DEVICE_SENTINEL = 'local';
+/**
+ * Key of a {@link ProjectCheckoutRecord.probed} entry.
+ *
+ * @param projectId - Project the holding was probed for.
+ * @param path - Probed path.
+ * @returns The map key.
+ *
+ * @example
+ * ```ts
+ * probed.set(holdingKey(id, path), await probeProjectHolding(path, id, 2000));
+ * ```
+ */
+export function holdingKey(projectId, path) {
+    return `${projectId}\u0000${path}`;
+}
+/**
+ * Return this device's stable id — the persisted `<cleoHome>/device-id`
+ * (T9321). Reused rather than minting a second device identity.
+ *
+ * @returns Opaque stable device id.
+ */
+export function currentDeviceId() {
+    return getStableDeviceId();
+}
+/** Prefix of the registry `project_path` sentinel for a row with no live location. */
+export const SUPERSEDED_PATH_PREFIX = 'superseded:';
+/**
+ * Registry `project_path` for a project whose last checkout now holds another
+ * project and which has no other live location. Not an absolute path, so no
+ * path lookup (current or older binary) can match it; unique per id.
+ *
+ * @param projectId - Immutable project id.
+ * @returns `superseded:<projectId>`.
+ */
+export function supersededRegistryPath(projectId) {
+    return `${SUPERSEDED_PATH_PREFIX}${projectId}`;
+}
+/**
+ * Whether a registry `project_path` is the {@link supersededRegistryPath} sentinel.
+ *
+ * @param projectPath - Stored registry path.
+ * @returns `true` for the sentinel.
+ */
+export function isSupersededRegistryPath(projectPath) {
+    return projectPath.startsWith(SUPERSEDED_PATH_PREFIX);
+}
+/**
+ * Whether `path` still holds `projectId`:
+ *
+ * - `no` — PROVABLY not: `.cleo/` is absent (ENOENT / ENOTDIR), or it
+ *   declares a different id. A directory the project was moved or rerooted
+ *   out of (or whose `.cleo/` was moved back out by hand).
+ * - `unknown` — cannot tell (EACCES, EPERM, EIO, …). A checkout made
+ *   unreadable by `chmod 000` is NOT gone; treating it as vanished would let a
+ *   same-nonce backup copy take its registry row (T12558 round 4).
+ * - `yes` — `.cleo/` is there and declares this id (or nothing).
+ */
+export function projectHolding(path, projectId) {
+    const cleoDir = join(path, '.cleo');
+    try {
+        lstatSync(cleoDir);
+        readdirSync(cleoDir);
+    }
+    catch (error) {
+        const code = error.code;
+        return code === 'ENOENT' || code === 'ENOTDIR' ? 'no' : 'unknown';
+    }
+    const declared = readDeclaredProjectIdentity(path);
+    return declared === null || declared.projectId === projectId ? 'yes' : 'no';
+}
+/**
+ * {@link projectHolding} with a time budget, for machine-wide scans
+ * (T12471): a hung mount answers `unknown` after `timeoutMs` instead of
+ * stalling the caller. Same tri-state rules — only ENOENT/ENOTDIR prove the
+ * project gone.
+ *
+ * @param path - Checkout root to probe.
+ * @param projectId - Id the checkout should hold.
+ * @param timeoutMs - Budget for the directory probe.
+ * @returns `yes`, `no`, or `unknown` (unreadable or timed out).
+ *
+ * @example
+ * ```ts
+ * if ((await probeProjectHolding(row.projectPath, row.projectId, 2000)) === 'no') markGone(row);
+ * ```
+ */
+export async function probeProjectHolding(path, projectId, timeoutMs) {
+    const cleoDir = join(path, '.cleo');
+    const probe = async () => {
+        try {
+            await lstat(cleoDir);
+            await readdir(cleoDir);
+            return null;
+        }
+        catch (error) {
+            const code = error.code;
+            return code === 'ENOENT' || code === 'ENOTDIR' ? 'no' : 'unknown';
+        }
+    };
+    const settled = await withinBudget(probe(), timeoutMs);
+    if (settled === 'timeout')
+        return 'unknown';
+    if (settled !== null)
+        return settled;
+    const declared = readDeclaredProjectIdentity(path);
+    return declared === null || declared.projectId === projectId ? 'yes' : 'no';
+}
+/** `true` when `inner` is strictly inside `outer`, compared through symlinks. */
+function isStrictlyInside(outer, inner) {
+    const rel = relative(canonicalizePath(outer), canonicalizePath(inner));
+    return rel.length > 0 && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/** Primary-key predicate for one location row. */
+function locationKey(projectId, deviceId, path) {
+    return and(eq(projectLocations.projectId, projectId), eq(projectLocations.deviceId, deviceId), eq(projectLocations.path, path));
+}
+/**
+ * Re-key migration-backfilled rows (device id {@link LOCAL_DEVICE_SENTINEL})
+ * to `deviceId`, merging with any row already recorded under the real id.
+ *
+ * @param db - Registry handle or transaction.
+ * @param deviceId - This device's stable id.
+ * @returns Number of sentinel rows adopted.
  */
-import { existsSync } from 'node:fs';
-import { and, desc, eq, ne } from 'drizzle-orm';
-import { projectPaths } from '../store/schema/nexus-schema.js';
+export function adoptLocalDeviceRows(db, deviceId) {
+    if (deviceId === LOCAL_DEVICE_SENTINEL)
+        return 0;
+    const sentinelRows = db
+        .select()
+        .from(projectLocations)
+        .where(eq(projectLocations.deviceId, LOCAL_DEVICE_SENTINEL))
+        .all();
+    for (const row of sentinelRows) {
+        const existing = db
+            .select()
+            .from(projectLocations)
+            .where(locationKey(row.projectId, deviceId, row.path))
+            .get();
+        if (existing) {
+            db.update(projectLocations)
+                .set({
+                firstSeen: existing.firstSeen < row.firstSeen ? existing.firstSeen : row.firstSeen,
+                lastSeen: existing.lastSeen > row.lastSeen ? existing.lastSeen : row.lastSeen,
+            })
+                .where(locationKey(row.projectId, deviceId, row.path))
+                .run();
+        }
+        else {
+            db.insert(projectLocations)
+                .values({ ...row, deviceId })
+                .run();
+        }
+        db.delete(projectLocations)
+            .where(locationKey(row.projectId, LOCAL_DEVICE_SENTINEL, row.path))
+            .run();
+    }
+    return sentinelRows.length;
+}
 /**
- * Record a checkout in the path map and prune this project's vanished paths.
+ * Record a checkout as a `live` location, supersede other projects' claims on
+ * the same path, and mark this project's vanished paths on this device
+ * `missing`. Nothing is deleted.
  *
- * A path belongs to exactly one project, so recording it re-points a row that
- * previously named another project. Runs synchronously so it composes with the
- * registry writers' immediate transactions.
+ * Runs synchronously so it composes with the registry writers' immediate
+ * transactions.
  *
  * @param db - Registry handle or transaction.
  * @param record - The checkout encountered.
- * @returns Number of vanished checkouts pruned for this project.
+ * @returns Counts of rows moved to `missing` and `superseded`.
  */
 export function recordProjectCheckout(db, record) {
-    db.insert(projectPaths)
+    const deviceId = record.deviceId ?? currentDeviceId();
+    adoptLocalDeviceRows(db, deviceId);
+    const evidence = confirmedColumns(record);
+    db.insert(projectLocations)
         .values({
-        projectPath: record.projectPath,
         projectId: record.projectId,
-        projectHash: record.projectHash,
+        deviceId,
+        path: record.projectPath,
         firstSeen: record.now,
         lastSeen: record.now,
+        state: 'live',
+        ...evidence,
     })
         .onConflictDoUpdate({
-        target: projectPaths.projectPath,
-        set: { projectId: record.projectId, projectHash: record.projectHash, lastSeen: record.now },
+        target: [projectLocations.projectId, projectLocations.deviceId, projectLocations.path],
+        set: { lastSeen: record.now, state: 'live', ...evidence },
     })
         .run();
+    // A path holds one project at a time: other projects' claims on it end.
+    const superseded = Number(db
+        .update(projectLocations)
+        .set({ state: 'superseded' })
+        .where(and(eq(projectLocations.deviceId, deviceId), eq(projectLocations.path, record.projectPath), ne(projectLocations.projectId, record.projectId), ne(projectLocations.state, 'superseded')))
+        .run().changes);
     const siblings = db
-        .select({ projectPath: projectPaths.projectPath })
-        .from(projectPaths)
-        .where(and(eq(projectPaths.projectId, record.projectId), ne(projectPaths.projectPath, record.projectPath)))
+        .select({ path: projectLocations.path })
+        .from(projectLocations)
+        .where(and(eq(projectLocations.projectId, record.projectId), eq(projectLocations.deviceId, deviceId), eq(projectLocations.state, 'live'), ne(projectLocations.path, record.projectPath)))
         .all();
-    let pruned = 0;
+    let markedMissing = 0;
     for (const sibling of siblings) {
-        if (existsSync(sibling.projectPath))
+        // Only a PROVABLY vanished location is marked missing; an unreadable one
+        // (`unknown`) keeps its state.
+        const holding = record.probed?.get(holdingKey(record.projectId, sibling.path)) ??
+            projectHolding(sibling.path, record.projectId);
+        if (holding !== 'no')
             continue;
-        db.delete(projectPaths).where(eq(projectPaths.projectPath, sibling.projectPath)).run();
-        pruned++;
+        db.update(projectLocations)
+            .set({ state: 'missing' })
+            .where(locationKey(record.projectId, deviceId, sibling.path))
+            .run();
+        markedMissing++;
+    }
+    rehomeDisplacedRows(db, record.projectId, record.projectPath, deviceId, record.probed);
+    // Legacy path map, dual-written for older binaries (upsert only; see header).
+    db.insert(projectPaths)
+        .values({
+        projectPath: record.projectPath,
+        projectId: record.projectId,
+        projectHash: record.projectHash ?? generateProjectHash(record.projectPath),
+        firstSeen: record.now,
+        lastSeen: record.now,
+    })
+        .onConflictDoUpdate({
+        target: projectPaths.projectPath,
+        set: {
+            projectId: record.projectId,
+            projectHash: record.projectHash ?? generateProjectHash(record.projectPath),
+            lastSeen: record.now,
+        },
+    })
+        .run();
+    return { markedMissing, superseded };
+}
+/** The non-null displayed-evidence fields of a record, as location columns. */
+function evidenceColumns(evidence) {
+    return {
+        ...(evidence?.gitRootCommit ? { gitRootCommit: evidence.gitRootCommit } : {}),
+        ...(evidence?.gitRemote ? { gitRemote: evidence.gitRemote } : {}),
+    };
+}
+/** A confirmed record's evidence plus its nonce, as location columns. */
+function confirmedColumns(record) {
+    return {
+        ...evidenceColumns(record.evidence),
+        ...(record.checkoutNonce ? { checkoutNonce: record.checkoutNonce } : {}),
+    };
+}
+/**
+ * Decide how an encounter may bind a checkout (see {@link EncounterBinding}).
+ *
+ * @param db - Registry handle or transaction.
+ * @param record - The encountered checkout and its evidence.
+ * @returns The permitted binding.
+ *
+ * @example
+ * ```ts
+ * const binding = decideEncounterBinding(tx, { projectId, projectPath, now, evidence });
+ * ```
+ */
+export function decideEncounterBinding(db, record) {
+    const deviceId = record.deviceId ?? currentDeviceId();
+    const row = db
+        .select({ projectPath: projectRegistry.projectPath })
+        .from(projectRegistry)
+        .where(eq(projectRegistry.projectId, record.projectId))
+        .get();
+    if (!row || row.projectPath === record.projectPath)
+        return 'bind';
+    const here = db
+        .select({ state: projectLocations.state, checkoutNonce: projectLocations.checkoutNonce })
+        .from(projectLocations)
+        .where(and(eq(projectLocations.projectId, record.projectId), inArray(projectLocations.deviceId, [deviceId, LOCAL_DEVICE_SENTINEL]), eq(projectLocations.path, record.projectPath)))
+        .all();
+    if (here.some((location) => location.state === 'live'))
+        return 'refresh';
+    const oldPath = row.projectPath;
+    if (isSupersededRegistryPath(oldPath))
+        return 'candidate';
+    // Proof of a move is the checkout's NONCE alone (T12470): local, untracked
+    // state that a real `mv` or a restore of `.cleo/` carries and a clone
+    // cannot have. Root commit and remote are forgeable (a clone shares them, a
+    // bare `git init` can add any remote, `refs/replace` fakes a root commit),
+    // so they are displayed evidence only and never promote.
+    const nonce = record.checkoutNonce ?? null;
+    const previous = () => db
+        .select({ checkoutNonce: projectLocations.checkoutNonce })
+        .from(projectLocations)
+        .where(and(eq(projectLocations.projectId, record.projectId), inArray(projectLocations.deviceId, [deviceId, LOCAL_DEVICE_SENTINEL]), eq(projectLocations.path, oldPath)))
+        .all();
+    // The old path still holding the project (not merely existing — a reroot
+    // undone by hand leaves the child directory behind, empty of `.cleo/`), or
+    // being unreadable, means this is a second checkout, not a move.
+    if (projectHolding(oldPath, record.projectId) !== 'no') {
+        // T12558 round 4: the ORIGINAL checkout coming back. It was once
+        // confirmed here (only a confirmed location records a nonce — candidates
+        // never do), it still carries that nonce, and the current holder's nonce
+        // differs — so the holder is not a copy of it. Hand the row back rather
+        // than leave the original stuck behind a stranger.
+        if (nonce !== null &&
+            here.some((location) => location.checkoutNonce === nonce) &&
+            !previous().some((location) => location.checkoutNonce === nonce)) {
+            return 'promote';
+        }
+        return 'candidate';
+    }
+    if (nonce === null)
+        return 'candidate';
+    return previous().some((location) => location.checkoutNonce === nonce) ? 'promote' : 'candidate';
+}
+/**
+ * Record an UNCONFIRMED location of a project (T12470): the checkout declares
+ * the id, but nothing has confirmed it. The registry row, its path and its
+ * permissions are not touched, and no other project's claim on the path ends.
+ * A location that is already `live` stays `live`.
+ *
+ * @param db - Registry handle or transaction.
+ * @param record - The encountered checkout.
+ * @returns `true` when the candidate was recorded for the first time.
+ *
+ * @example
+ * ```ts
+ * recordCandidateLocation(tx, { projectId, projectPath, now, evidence });
+ * ```
+ */
+export function recordCandidateLocation(db, record) {
+    const deviceId = record.deviceId ?? currentDeviceId();
+    adoptLocalDeviceRows(db, deviceId);
+    const key = locationKey(record.projectId, deviceId, record.projectPath);
+    const existing = db
+        .select({ state: projectLocations.state })
+        .from(projectLocations)
+        .where(key)
+        .get();
+    const evidence = evidenceColumns(record.evidence);
+    if (!existing) {
+        db.insert(projectLocations)
+            .values({
+            projectId: record.projectId,
+            deviceId,
+            path: record.projectPath,
+            firstSeen: record.now,
+            lastSeen: record.now,
+            state: 'candidate',
+            ...evidence,
+        })
+            .run();
+        return true;
+    }
+    // T12558: a `missing` location the project was explicitly moved AWAY from
+    // (reroot/move demoted it) stays `missing` while the project is live at
+    // another existing path on this device. A `git checkout -- .` at the old
+    // root restores the tracked id and makes every command an encounter here;
+    // flipping the row to `candidate` would disarm the store guard that refuses
+    // to create an empty store at a relocated root.
+    // Round 4: only in REROOT geometry (the live location is strictly inside
+    // this path) and only for a nonce-less encounter (restored tracked files —
+    // a real checkout carries its untracked nonce). Anywhere else a path that
+    // holds the project is a `candidate`, never stuck at `missing`.
+    const keepMissing = existing.state === 'missing' &&
+        (record.checkoutNonce ?? null) === null &&
+        hasOtherLiveLocation(db, record, deviceId);
+    db.update(projectLocations)
+        .set({
+        lastSeen: record.now,
+        ...(existing.state === 'live' || keepMissing ? {} : { state: 'candidate' }),
+        ...evidence,
+    })
+        .where(key)
+        .run();
+    return false;
+}
+/**
+ * Whether `record.projectId` has a `live` location on this device STRICTLY
+ * INSIDE this path (the project was rerooted into it) that still PROVES it
+ * holds the project — the directory declares the same id. Mere existence is not enough: after a reroot is undone by hand
+ * the child directory still exists but no longer holds `.cleo/`, and the old
+ * root must then be able to become a location again (T12558 round 3).
+ */
+function hasOtherLiveLocation(db, record, deviceId) {
+    return db
+        .select({ path: projectLocations.path })
+        .from(projectLocations)
+        .where(and(eq(projectLocations.projectId, record.projectId), eq(projectLocations.deviceId, deviceId), eq(projectLocations.state, 'live'), ne(projectLocations.path, record.projectPath)))
+        .all()
+        .some((location) => isStrictlyInside(record.projectPath, location.path) &&
+        existsSync(location.path) &&
+        readDeclaredProjectIdentity(location.path)?.projectId === record.projectId);
+}
+/**
+ * Demote a location this device no longer treats as the project's home
+ * (T12556 · T12558). `cleo project move` leaves the source tree behind as a
+ * `candidate` (it still declares the id but is no longer confirmed);
+ * `cleo project reroot` leaves the old root with no `.cleo/` at all, so it is
+ * `missing`. A location that was never recorded is recorded in that state so
+ * the history is complete. The registry row is not touched.
+ *
+ * @param db - Registry handle or transaction.
+ * @param record - The location to demote.
+ * @param state - `candidate` (still declares the id) or `missing` (does not).
+ *
+ * @example
+ * ```ts
+ * demoteProjectLocation(tx, { projectId, projectPath: oldRoot, now }, 'missing');
+ * ```
+ */
+export function demoteProjectLocation(db, record, state) {
+    const deviceId = record.deviceId ?? currentDeviceId();
+    adoptLocalDeviceRows(db, deviceId);
+    db.insert(projectLocations)
+        .values({
+        projectId: record.projectId,
+        deviceId,
+        path: record.projectPath,
+        firstSeen: record.now,
+        lastSeen: record.now,
+        state,
+    })
+        .onConflictDoUpdate({
+        target: [projectLocations.projectId, projectLocations.deviceId, projectLocations.path],
+        set: { state },
+    })
+        .run();
+}
+/**
+ * Refresh an already-confirmed location without repointing the registry row.
+ *
+ * @param db - Registry handle or transaction.
+ * @param record - The encountered checkout.
+ */
+export function touchProjectLocation(db, record) {
+    const deviceId = record.deviceId ?? currentDeviceId();
+    adoptLocalDeviceRows(db, deviceId);
+    db.update(projectLocations)
+        .set({ lastSeen: record.now, ...confirmedColumns(record) })
+        .where(locationKey(record.projectId, deviceId, record.projectPath))
+        .run();
+}
+/**
+ * Explicitly confirm a checkout as a project's live location and point the
+ * registry row at it (T12470) — the promotion path for a `candidate` used by
+ * `cleo doctor project-identity --resolve`. Permissions stay on the row.
+ *
+ * @param db - Registry handle or transaction.
+ * @param record - The checkout to confirm.
+ * @returns `false` when the project has no registry row to point.
+ *
+ * @example
+ * ```ts
+ * confirmProjectLocation(tx, { projectId, projectPath, now, evidence });
+ * ```
+ */
+export function confirmProjectLocation(db, record) {
+    const row = db
+        .select({ projectId: projectRegistry.projectId })
+        .from(projectRegistry)
+        .where(eq(projectRegistry.projectId, record.projectId))
+        .get();
+    if (!row)
+        return false;
+    db.update(projectRegistry)
+        .set({
+        projectPath: record.projectPath,
+        projectHash: generateProjectHash(record.projectPath),
+        lastSeen: record.now,
+        brainDbPath: registryStorePath(record.projectPath),
+        tasksDbPath: registryStorePath(record.projectPath),
+    })
+        .where(eq(projectRegistry.projectId, record.projectId))
+        .run();
+    recordProjectCheckout(db, record);
+    return true;
+}
+/**
+ * Keep at most one registry row per real path: move every OTHER project's
+ * registry row that still names `projectPath` to that project's most recent
+ * other live location on this device, or to its
+ * {@link supersededRegistryPath} sentinel when it has none.
+ *
+ * @param db - Registry handle or transaction.
+ * @param projectId - The project that now holds `projectPath`.
+ * @param projectPath - The path that changed hands.
+ * @param deviceId - This device's stable id.
+ * @param probed - Holdings probed before the transaction ({@link holdingKey}).
+ * @returns Number of registry rows re-homed.
+ */
+export function rehomeDisplacedRows(db, projectId, projectPath, deviceId, probed) {
+    const displaced = db
+        .select({ projectId: projectRegistry.projectId })
+        .from(projectRegistry)
+        .where(and(eq(projectRegistry.projectPath, projectPath), ne(projectRegistry.projectId, projectId)))
+        .all();
+    for (const row of displaced) {
+        const candidates = db
+            .select({ path: projectLocations.path })
+            .from(projectLocations)
+            .where(and(eq(projectLocations.projectId, row.projectId), eq(projectLocations.deviceId, deviceId), eq(projectLocations.state, 'live'), ne(projectLocations.path, projectPath)))
+            .orderBy(desc(projectLocations.lastSeen))
+            .all();
+        // A candidate must exist on disk and not already name another registry row.
+        // A pre-probed holding answers without touching the filesystem (T12471):
+        // only a location that still holds the displaced project may take its row.
+        const present = (path) => {
+            const holding = probed?.get(holdingKey(row.projectId, path));
+            return holding === undefined ? existsSync(path) : holding === 'yes';
+        };
+        const home = candidates.find((c) => present(c.path) &&
+            db
+                .select({ projectId: projectRegistry.projectId })
+                .from(projectRegistry)
+                .where(eq(projectRegistry.projectPath, c.path))
+                .all().length === 0)?.path;
+        const nextPath = home ?? supersededRegistryPath(row.projectId);
+        db.update(projectRegistry)
+            .set({
+            projectPath: nextPath,
+            projectHash: generateProjectHash(nextPath),
+            brainDbPath: home ? registryStorePath(home) : null,
+            tasksDbPath: home ? registryStorePath(home) : null,
+        })
+            .where(eq(projectRegistry.projectId, row.projectId))
+            .run();
     }
-    return pruned;
+    return displaced.length;
 }
 /**
- * List every recorded checkout of a project on this device, newest first.
+ * List every recorded location of a project, newest first.
  *
  * @param projectId - Immutable project id.
- * @returns Checkouts with an `exists` flag; a vanished one stays listed until
- *   the project is next recorded.
+ * @param opts - `allDevices: true` includes other devices' locations; by
+ *   default only this device's are listed.
+ * @returns Locations with their state and an `exists` flag (checked only for
+ *   this device's rows; `false` for another device's).
  * @example
  * ```ts
  * const checkouts = await listProjectCheckouts(projectId);
+ * const live = checkouts.filter((c) => c.state === 'live');
  * ```
  */
-export async function listProjectCheckouts(projectId) {
+export async function listProjectCheckouts(projectId, opts = {}) {
     const { getNexusRegistryDb } = await import('../store/nexus-sqlite.js');
     const { getCleoHome } = await import('../paths.js');
     const db = await getNexusRegistryDb(getCleoHome());
-    return db
+    const deviceId = currentDeviceId();
+    const out = [];
+    for (const row of db
         .select()
-        .from(projectPaths)
-        .where(eq(projectPaths.projectId, projectId))
-        .orderBy(desc(projectPaths.lastSeen))
-        .all()
-        .map((row) => ({
-        projectPath: row.projectPath,
-        projectHash: row.projectHash,
-        firstSeen: row.firstSeen,
-        lastSeen: row.lastSeen,
-        exists: existsSync(row.projectPath),
-    }));
+        .from(projectLocations)
+        .where(eq(projectLocations.projectId, projectId))
+        .orderBy(desc(projectLocations.lastSeen))
+        .all()) {
+        // Migration-backfilled rows are this device's until adopted.
+        const local = row.deviceId === deviceId || row.deviceId === LOCAL_DEVICE_SENTINEL;
+        if (!local && !opts.allDevices)
+            continue;
+        out.push({
+            projectPath: row.path,
+            projectHash: generateProjectHash(row.path),
+            firstSeen: row.firstSeen,
+            lastSeen: row.lastSeen,
+            exists: local && existsSync(row.path),
+            deviceId: local ? deviceId : row.deviceId,
+            state: row.state,
+        });
+    }
+    return out;
 }
 //# sourceMappingURL=path-map.js.map