@cleocode/core 2026.9.8 → 2026.9.10

package/dist/paths.js

@@ -14,7 +14,6 @@
  * @epic T4454
  * @task T4458
  */
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
@@ -22,6 +21,9 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { E_CWD_WALKUP_FORBIDDEN, ExitCode } from '@cleocode/contracts';
 import { computeCanonicalProjectId as _computeCanonicalProjectId, getCanonicalTemplatesTildePath as _getCanonicalTemplatesTildePath, getCleoTemplatesTildePath as _getCleoTemplatesTildePath, isAbsolutePath as _isAbsolutePath, resolveProjectByCwd as _pathsResolveProjectByCwd, resolveCanonicalCleoDir as _resolveCanonicalCleoDir, } from '@cleocode/paths';
 import { CleoError } from './errors.js';
+import { _resolveMainRepoFromGitlink, captureProjectScope, getProjectRoot, validateProjectRoot, worktreeScope, } from './project-scope.js';
+export { getProjectRoot, validateProjectRoot, worktreeScope } from './project-scope.js';
+import { createOperationExecutionContext, trackBackgroundOp } from './store/background-ops.js';
 import { getPlatformPaths } from './system/platform-paths.js';
 /**
  * Lazily-resolved `node:sqlite` `DatabaseSync` constructor.
@@ -39,36 +41,9 @@ function _getDatabaseSyncCtor() {
     const mod = _require('node:sqlite');
     return mod.DatabaseSync;
 }
-/**
- * AsyncLocalStorage instance that carries the active {@link WorktreeScope}
- * for the current async execution context.
- *
- * @remarks
- * Set by the spawn adapter (or any caller that wants to redirect CLEO path
- * resolution to a worktree directory) before invoking subagent logic.
- * `getProjectRoot()` checks this store BEFORE the `CLEO_ROOT` env-var and
- * ancestor-walk, so scoped callers transparently receive the worktree root.
- *
- * Callers outside a worktree context receive `undefined` from
- * `worktreeScope.getStore()` and fall through to the existing resolution
- * order unchanged.
- *
- * @example
- * ```ts
- * import { worktreeScope } from '@cleocode/core/paths';
- *
- * worktreeScope.run(
- *   { worktreeRoot: '/path/to/worktree', projectHash: 'abc123' },
- *   async () => {
- *     const root = getProjectRoot(); // returns '/path/to/worktree'
- *   }
- * );
- * ```
- *
- * @task T380
- * @public
- */
-export const worktreeScope = new AsyncLocalStorage();
+// ============================================================================
+// Worktree Scope (T380/ADR-041 §D3)
+// ============================================================================
 /**
  * Run `fn` inside a `worktreeScope.run()` AsyncLocalStorage frame derived
  * from the `CLEO_WORKTREE_ROOT` and `CLEO_PROJECT_HASH` environment variables.
@@ -297,10 +272,16 @@ export function getCleoDir(cwd) {
  * getCleoDirAbsolute('/tmp/new-project', { bootstrap: true }); // "/tmp/new-project/.cleo"
  * ```
  *
+ * @remarks Active worktree scope takes precedence over ambient CLEO_DIR, matching
+ * resolveCleoDir. Outside a scope, absolute CLEO_DIR retains its override behavior.
  * @deprecated Migrate to {@link resolveProjectByCwd} + {@link resolveCanonicalCleoDir}
  * @task T11009
  */
 export function getCleoDirAbsolute(cwd, opts) {
+    // Captured ownership has the same precedence as the canonical resolver.
+    // Ambient overrides retain their historical behavior only outside a scope.
+    if (worktreeScope.getStore() !== undefined)
+        return resolveCleoDir(cwd);
     const cleoDir = getCleoDir();
     if (isAbsolutePath(cleoDir)) {
         return cleoDir;
@@ -350,7 +331,7 @@ export function getCleoDirAbsolute(cwd, opts) {
     // as the path authority.
     const project = _pathsResolveProjectByCwd(cwd);
     if (project !== null) {
-        // T11021: Auto-register project on first encounter (fire-and-forget).
+        // T11021: Schedule lifecycle-tracked registration against captured global ownership.
         // T11023: pass legacyUUID so it gets registered as an alias alongside
         // the canonical ID.
         // T11281: unit tests that exercise the nexus registration/reconcile contract
@@ -359,7 +340,9 @@ export function getCleoDirAbsolute(cwd, opts) {
         // test's explicit registration state. Off by default — production always
         // auto-registers on encounter.
         if (process.env['CLEO_DISABLE_PROJECT_AUTOREGISTER'] !== '1') {
-            registerProjectOnEncounter(project.projectRoot, project.legacyUUID ?? project.projectId).catch(() => { });
+            registerProjectOnEncounter(project.projectRoot, project.legacyUUID ?? project.projectId).catch((error) => {
+                process.stderr.write(`[cleo] Project encounter registration failed: ${error.message}\n`);
+            });
         }
         try {
             const projectRoot = getProjectRoot(cwd);
@@ -808,43 +791,6 @@ function _cwdHasGitAncestor(cwd) {
         current = parent;
     }
 }
-/**
- * Attempt to resolve the main git repo root from a gitlink (.git as FILE).
- * Returns the main repo path if the gitlink is valid and the main repo is a
- * CLEO project; otherwise returns `null`.
- *
- * @internal
- * @task T11034
- */
-function _resolveMainRepoFromGitlink(gitlinkDir) {
-    try {
-        const gitLinkPath = join(gitlinkDir, '.git');
-        if (!existsSync(gitLinkPath))
-            return null;
-        const stat = statSync(gitLinkPath);
-        if (!stat.isFile())
-            return null;
-        const gitLinkContent = readFileSync(gitLinkPath, 'utf-8').trim();
-        const match = gitLinkContent.match(/^gitdir:\s*(.+)$/m);
-        if (!match)
-            return null;
-        const gitdir = match[1].trim();
-        // gitdir is `<main>/.git/worktrees/<name>` → strip last 3 segments.
-        const mainRepo = dirname(dirname(dirname(gitdir)));
-        if (existsSync(join(mainRepo, '.cleo')) && validateProjectRoot(mainRepo)) {
-            return mainRepo;
-        }
-    }
-    catch {
-        // Parse error — not a valid gitlink.
-    }
-    return null;
-}
-/**
- * Module-level flag: emit the legacy-fallback warning at most once per process.
- * Prevents log spam when `validateProjectRoot` is called repeatedly in a session.
- */
-let _legacyFallbackWarned = false;
 /**
  * Module-level flag: emit the T10297 deprecation warning for
  * `getCleoDirAbsolute` at most once per process (AC4).
@@ -854,133 +800,6 @@ let _legacyFallbackWarned = false;
  * @saga T10295
  */
 let _getCleoDirAbsoluteDeprecatedWarned = false;
-/**
- * Validate that a candidate project root directory is a legitimate CLEO
- * project root and not a stray parent `.cleo/` directory that happened to
- * be found by the walk-up algorithm.
- *
- * ## Primary path (T1864 — project-info.json contract)
- *
- * A candidate is **accepted** when `.cleo/project-info.json` exists and
- * parses as JSON with a non-empty `projectId` string field.  This is the
- * canonical form written by `cleo init` and is the only form that guarantees
- * the directory is a proper CLEO project rather than a stray `.cleo/` left by
- * an old installation or a git worktree that auto-created its own `.cleo/`.
- *
- * ## Legacy fallback (backwards-compatibility)
- *
- * Projects initialized before `project-info.json` was introduced are still
- * accepted when **both** of the following are true:
- *   1. `.cleo/` exists in `candidate`
- *   2. `.git/` exists as a sibling of `.cleo/` in `candidate`
- *
- * A one-time stderr warning is emitted (guarded by `_legacyFallbackWarned`)
- * so operators know to re-run `cleo init` to upgrade the project metadata.
- *
- * **Breaking change vs. prior implementation**: bare `package.json` alone is
- * no longer sufficient.  The old check `existsSync(gitDir) || existsSync(pkgJson)`
- * accepted any Node.js package directory as a valid project root, which caused
- * the monorepo-package bug where sub-packages inside `packages/` created their
- * own empty `.cleo/` databases.
- *
- * @param candidate - Absolute path to the directory being considered as the
- *   project root (parent of the `.cleo/` directory).
- * @returns `true` when the candidate is a recognised CLEO project root.
- *
- * @example
- * ```typescript
- * // Project root with project-info.json — valid (primary path)
- * validateProjectRoot('/home/user/myproject'); // true
- *
- * // Legacy project root with .git/ but no project-info.json — valid + warning
- * validateProjectRoot('/home/user/legacy-project'); // true (+ stderr warning)
- *
- * // Stray .cleo in home dir with no markers — invalid
- * validateProjectRoot('/home/user'); // false
- * ```
- *
- * @task T1463
- * @task T1864
- */
-export function validateProjectRoot(candidate) {
-    const cleoDir = join(candidate, '.cleo');
-    if (!existsSync(cleoDir)) {
-        return false;
-    }
-    // Primary: .cleo/project-info.json with a valid projectId string.
-    // T11034 — Worktree guard: a worktree has .git as a gitlink FILE, not a
-    // directory. project-info.json is copied into worktrees for identity
-    // inheritance (T11033), but worktrees must NOT be treated as standalone
-    // project roots — path resolution must walk past them to the parent project.
-    const projectInfoPath = join(cleoDir, 'project-info.json');
-    if (existsSync(projectInfoPath)) {
-        try {
-            const raw = readFileSync(projectInfoPath, 'utf-8');
-            const parsed = JSON.parse(raw);
-            if (typeof parsed === 'object' &&
-                parsed !== null &&
-                'projectId' in parsed &&
-                typeof parsed['projectId'] === 'string' &&
-                parsed['projectId'] !== '') {
-                // T11034: Reject worktrees — .git is a gitlink FILE, not a directory.
-                // Workers should resolve through to the parent project root.
-                const gitMarker = join(candidate, '.git');
-                if (existsSync(gitMarker)) {
-                    try {
-                        if (!statSync(gitMarker).isDirectory()) {
-                            // Gitlink file (worktree) — NOT a project root.
-                            return false;
-                        }
-                    }
-                    catch {
-                        // Stat failed — treat as non-directory (reject).
-                        return false;
-                    }
-                }
-                return true;
-            }
-        }
-        catch {
-            // JSON parse error or read error — fall through to legacy check.
-        }
-    }
-    // Legacy fallback: .cleo/ + .git/ sibling (no project-info.json required).
-    // Emits a one-time warning to prompt the operator to run `cleo init`.
-    //
-    // CRITICAL (T9092): a git worktree has `.git` as a *file* (a "gitlink" pointing
-    // back to the main repo's .git/worktrees/<name> directory), NOT a directory.
-    // Accepting such candidates as project roots recreates the 2026-05-04 dead-end-DB
-    // disaster pattern: workers spawned in a worktree create rogue `.cleo/tasks.db`
-    // files isolated from the real project database. The legacy fallback MUST only
-    // accept candidates where `.git` is a true directory (a real repo root).
-    const gitDir = join(candidate, '.git');
-    if (existsSync(gitDir)) {
-        let isRealGitDir = false;
-        try {
-            const stat = statSync(gitDir);
-            isRealGitDir = stat.isDirectory();
-        }
-        catch {
-            isRealGitDir = false;
-        }
-        if (!isRealGitDir) {
-            // .git is a gitlink file (worktree marker) — NOT a project root.
-            return false;
-        }
-        if (!_legacyFallbackWarned) {
-            _legacyFallbackWarned = true;
-            // T9774: debug-only — surfaced via CLEO_DEBUG to keep stderr clean by default.
-            // Cannot use pushWarning here because paths.ts is in the import chain of
-            // output.ts (output → sessions/context-alert → paths) — circular dep.
-            if (process.env['CLEO_DEBUG']) {
-                process.stderr.write(`[cleo][debug] W_PATH_RESOLUTION: ${candidate}/.cleo/ lacks project-info.json. ` +
-                    `Run \`cleo init\` to upgrade project metadata (T1864 legacy-fallback).\n`);
-            }
-        }
-        return true;
-    }
-    return false;
-}
 /**
  * Assert that the given directory is an initialized CLEO project root,
  * throwing a `CleoError` if it is not.
@@ -1010,184 +829,6 @@ export function assertProjectInitialized(projectRoot) {
         });
     }
 }
-/**
- * Get the project root by walking ancestor directories for `.cleo/` or `.git/`.
- *
- * Stops at the **first** ancestor directory that contains either sentinel
- * directory and never drifts past it — even when multiple nested projects
- * exist above the starting directory.
- *
- * Resolution order:
- *   1. `CLEO_ROOT` env var — bypasses walk entirely (CI / test override)
- *   2. `CLEO_DIR` env var (absolute path only) — derives project root from dirname
- *   3. Walk ancestors from `cwd` (or `process.cwd()`) toward filesystem root:
- *      - `.cleo/` found with a sibling `.git/` or `package.json` → accept as root
- *      - `.cleo/` found but **no** sibling marker → skip (stray/parent `.cleo/`)
- *      - `.git/` found (without `.cleo/` sibling) → throw `E_NOT_INITIALIZED`
- *   4. Filesystem root reached without a valid root → throw `E_INVALID_PROJECT_ROOT`
- *      (if at least one `.cleo/` was skipped) or `E_NO_PROJECT` (none found)
- *
- * @param cwd - Optional starting directory; defaults to `process.cwd()`
- * @returns Absolute path to the project root directory (parent of `.cleo/`)
- * @throws {CleoError} `ExitCode.CONFIG_ERROR` (`E_NOT_INITIALIZED`) when a
- *   `.git/` is found but no `.cleo/` is present at that level.
- * @throws {CleoError} `ExitCode.CONFIG_ERROR` (`E_INVALID_PROJECT_ROOT`) when
- *   one or more `.cleo/` directories are found but none have the required sibling
- *   markers (`.git/` or `package.json`). This prevents accidental operations on
- *   the wrong project when a stray parent `.cleo/` exists higher in the filesystem.
- * @throws {CleoError} `ExitCode.NOT_FOUND` (`E_NO_PROJECT`) when neither
- *   sentinel is found in any ancestor.
- *
- * @remarks
- * `CLEO_ROOT` is an absolute-path escape hatch for environments where the
- * working directory is unrelated to the project (CI tmpdirs, monorepo scripts,
- * test harnesses). When set it is returned as-is without scanning ancestors.
- *
- * `CLEO_DIR` set to an absolute path (e.g. `/project/.cleo`) also bypasses
- * the walk: the project root is derived as its `dirname`. This preserves
- * backward compatibility for test harnesses that use `CLEO_DIR` to pin the
- * project root.
- *
- * NEVER auto-creates `.cleo/`. Project initialisation is an explicit opt-in
- * via `cleo init`.
- *
- * @example
- * ```typescript
- * // Running from packages/core inside the monorepo:
- * const root = getProjectRoot(); // "/mnt/projects/cleocode"
- * ```
- */
-export function getProjectRoot(cwd) {
-    // 0. AsyncLocalStorage worktree scope (T380/ADR-041 §D3) — checked FIRST.
-    //    When a spawn adapter wraps execution in worktreeScope.run(...), the
-    //    scoped root wins over all env-var and walk-based resolution.
-    const scope = worktreeScope.getStore();
-    if (scope !== undefined) {
-        return scope.worktreeRoot;
-    }
-    // 1. Honour CLEO_ROOT / CLEO_PROJECT_ROOT env var — bypass walk entirely.
-    //    CLEO_PROJECT_ROOT is the agent-friendly alias (T090).
-    const envRoot = process.env['CLEO_ROOT'] ?? process.env['CLEO_PROJECT_ROOT'];
-    if (envRoot) {
-        return envRoot;
-    }
-    // 2. If CLEO_DIR is an absolute path, derive the project root from it.
-    //    This preserves backward compatibility for test harnesses that set
-    //    CLEO_DIR=/some/absolute/path/.cleo to pin the project root.
-    const cleoDirEnv = process.env['CLEO_DIR'];
-    if (cleoDirEnv && isAbsolutePath(cleoDirEnv)) {
-        if (cleoDirEnv.endsWith('/.cleo') || cleoDirEnv.endsWith('\\.cleo')) {
-            return dirname(cleoDirEnv);
-        }
-        return cleoDirEnv;
-    }
-    const start = resolve(cwd ?? process.cwd());
-    let current = start;
-    // 2.5. T9092 + T11034: if `start` is inside a git worktree (i.e. has `.git` as a
-    //      gitlink FILE pointing to `<mainrepo>/.git/worktrees/<name>`), the
-    //      canonical project root is the MAIN repo, not the worktree dir.
-    //      Delegates to the shared _resolveMainRepoFromGitlink helper which
-    //      provides deterministic resolution from any worktree path.
-    const mainRepoFromStart = _resolveMainRepoFromGitlink(start);
-    if (mainRepoFromStart !== null)
-        return mainRepoFromStart;
-    // T889/T909 guard: snapshot $HOME and filesystem root sentinels.
-    //
-    // Historical bug: when `cleo` ran with `cwd=$HOME` and a stray
-    // `~/.cleo/` existed (from a prior buggy run or user mistake), the
-    // walk-up returned `$HOME` as the project root. This silently created
-    // `~/.cleo/conduit.db`, `~/.cleo/tasks.db`, etc. — diverging from the
-    // real project DBs and losing data on branch switch. See ADR-037
-    // (conduit.db is project-tier-only) and the orphan-conduit remediation.
-    //
-    // Contract: `getProjectRoot` MUST NEVER resolve to `$HOME` or `/`.
-    // If the walk would land there, treat it as "no project" rather than
-    // silently accepting a pathological root. Users who legitimately want
-    // `$HOME` as a project root must set `CLEO_ROOT=$HOME` explicitly — the
-    // env-var path above bypasses this guard, making the opt-in explicit.
-    const homeRoot = homedir();
-    // T1463/P1-7: track if we skipped any .cleo/ dirs that failed validation.
-    // Used to produce a more informative error message when every candidate
-    // was rejected by validateProjectRoot.
-    const skippedCleoDirs = [];
-    // 3. Walk ancestors toward filesystem root
-    while (true) {
-        const cleoDir = join(current, '.cleo');
-        const gitDir = join(current, '.git');
-        // T889/T909: refuse to accept $HOME or / as a project root, even if a
-        // `.cleo/` sentinel exists there. This blocks the orphan-DB vector.
-        const isDangerousRoot = current === homeRoot || current === '/' || current === '';
-        if (existsSync(cleoDir) && !isDangerousRoot) {
-            // T1463/P1-7: validate that the .cleo/ dir has the required sibling
-            // markers (.git/ or package.json) before accepting this candidate.
-            //
-            // T9092: previously the start-directory short-circuit was unconditional —
-            // `current === start` returned the candidate without running
-            // validateProjectRoot. That allowed a worktree (whose `.git` is a gitlink
-            // FILE not a directory) to be accepted as a project root if any process
-            // had previously created a stray `.cleo/` inside it. validateProjectRoot
-            // now rejects gitlink-only candidates, so we must run it on the start dir
-            // too — but only as a *gate* to walk up further, not to reject outright.
-            // If start dir validation fails, we continue walking to find the real
-            // project root (the main repo).
-            if (validateProjectRoot(current)) {
-                // Valid project root.
-                return current;
-            }
-            // Stray/rogue .cleo/ found (e.g. worktree with gitlink, or .cleo without
-            // project-info.json AND without a real .git/ sibling) — skip it and
-            // continue walking up for the canonical project root.
-            skippedCleoDirs.push(current);
-        }
-        if (existsSync(gitDir) && !isDangerousRoot) {
-            // T9092: only treat .git as a "real repo root" boundary when it is a
-            // DIRECTORY. A gitlink FILE (worktree marker) does not anchor a project
-            // root — keep walking up to find the canonical main repo.
-            let isRealGitDir = false;
-            try {
-                isRealGitDir = statSync(gitDir).isDirectory();
-            }
-            catch {
-                isRealGitDir = false;
-            }
-            if (isRealGitDir) {
-                // Real .git/ found but no .cleo/ sibling — not initialised
-                throw new CleoError(ExitCode.CONFIG_ERROR, `Run cleo init at ${current}`, {
-                    fix: `cd ${current} && cleo init`,
-                });
-            }
-            // gitlink file — attempt to resolve the main repo from it (T11034).
-            // When a worktree lives under ~/.local/share/cleo/worktrees/... and the
-            // caller is in a subdirectory (not the worktree root), the start-level
-            // gitlink check misses it. During the walk we must resolve gitlinks
-            // to ensure deterministic resolution from any worktree path.
-            const mainRepoFromWalk = _resolveMainRepoFromGitlink(current);
-            if (mainRepoFromWalk !== null)
-                return mainRepoFromWalk;
-            // gitlink we couldn't resolve — keep walking up.
-        }
-        // Move up one level
-        const parent = dirname(current);
-        if (parent === current) {
-            // Reached filesystem root without finding either sentinel
-            break;
-        }
-        current = parent;
-    }
-    // 4a. At least one .cleo/ was found but all were rejected by validateProjectRoot.
-    //     This is the "parent .cleo/ trap" scenario: a stray .cleo/ dir higher in
-    //     the filesystem lacks a .git/ or package.json sibling, so it cannot be
-    //     trusted as a project root.
-    if (skippedCleoDirs.length > 0) {
-        throw new CleoError(ExitCode.CONFIG_ERROR, `E_INVALID_PROJECT_ROOT: no .cleo with sibling .git found from ${start} (skipped: ${skippedCleoDirs.join(', ')})`, {
-            fix: `cleo init or add a .git directory alongside the .cleo dir`,
-        });
-    }
-    // 4b. No sentinel found in any ancestor
-    throw new CleoError(ExitCode.NOT_FOUND, 'Not inside a CLEO project. Run cleo init or cd to an existing project', {
-        fix: 'cleo init',
-    });
-}
 /**
  * Resolve an optional caller-provided root, falling back to canonical project root.
  *
@@ -2069,133 +1710,141 @@ function _rowToRegistryEntry(row) {
         taskCount: Number(row['taskCount'] ?? 0),
     };
 }
-/** Read project name from .cleo/project-info.json. Returns undefined on failure. */
+/** Read optional project name; malformed or unreadable existing metadata is a diagnostic. */
 function _readProjectNameFromInfo(projectRoot) {
-    try {
-        const infoPath = join(projectRoot, '.cleo', 'project-info.json');
-        if (!existsSync(infoPath))
-            return undefined;
-        const raw = readFileSync(infoPath, 'utf-8');
-        const data = JSON.parse(raw);
-        return typeof data.name === 'string' && data.name.length > 0 ? data.name : undefined;
-    }
-    catch {
+    const infoPath = join(projectRoot, '.cleo', 'project-info.json');
+    if (!existsSync(infoPath))
         return undefined;
-    }
+    const raw = readFileSync(infoPath, 'utf-8');
+    const data = JSON.parse(raw);
+    return typeof data.name === 'string' && data.name.length > 0 ? data.name : undefined;
 }
-/** Auto-register a project on first encounter (AC2, AC3, AC5, AC6). */
+/**
+ * Register an encountered project's immutable identity in its captured global registry.
+ * @param projectRoot - Explicit project ownership captured before asynchronous work.
+ * @param infoProjectId - Existing immutable project identity, never inferred from similarity.
+ * @returns Completion of the fully tracked operation, including any failure.
+ * @remarks Lazy work obeys the existing transaction/queue boundary and shares the
+ * original execution deadline. Registry writes never initialize the project graph.
+ * Cancellation is checked before the actual synchronous registry transaction commits.
+ * @example
+ * ```ts
+ * await registerProjectOnEncounter(projectRoot, projectId);
+ * ```
+ */
 export async function registerProjectOnEncounter(projectRoot, infoProjectId) {
+    const scope = captureProjectScope(projectRoot, worktreeScope.getStore());
+    const capturedHome = getCleoHome();
+    const resolvedPath = scope.worktreeRoot;
+    const projectName = _readProjectNameFromInfo(resolvedPath) || basename(resolvedPath) || 'unnamed';
+    if (!infoProjectId.trim())
+        throw new Error('Project encounter requires an existing immutable identity');
+    const ownedExecution = !scope.execution;
+    const execution = scope.execution ??
+        createOperationExecutionContext({
+            projectId: infoProjectId,
+            projectRoot: resolvedPath,
+            actor: 'project-encounter',
+            operation: 'nexus.register-encounter',
+            idempotencyKey: `${capturedHome}:${infoProjectId}:${resolvedPath}`,
+        });
     try {
-        const { canonicalProjectId: computeCanonicalId } = await import('./nexus/identity.js');
-        const { generateProjectHash } = await import('./nexus/hash.js');
-        const canonicalResult = await computeCanonicalId(projectRoot);
-        const canonicalId = canonicalResult.id;
-        // T11281 (owner directive 2026-05-29): the registry's projectId is the
-        // project's IMMUTABLE lifetime identity — assigned once, stored in
-        // .cleo/project-info.json, and carried verbatim through move / rename /
-        // export-import, no matter which nexus it registers with. The path-derived
-        // canonical id is NOT move-stable (it changes when the path changes), so it
-        // is recorded only as an ALIAS; projectHash (generateProjectHash) is the
-        // path fingerprint that updates on move. Fall back to the canonical id only
-        // when the project carries no stored id yet (first assignment / fresh init).
-        const immutableId = infoProjectId && infoProjectId.length > 0 ? infoProjectId : canonicalId;
-        const { getNexusDb } = await import('./store/nexus-sqlite.js');
-        const { eq } = await import('drizzle-orm');
-        const { projectRegistry, projectIdAliases } = await import('./store/schema/nexus-schema.js');
-        const db = await getNexusDb();
-        const existingRows = await db
-            .select()
-            .from(projectRegistry)
-            .where(eq(projectRegistry.projectId, immutableId))
-            .limit(1);
-        const now = new Date().toISOString();
-        const resolvedPath = resolve(projectRoot);
-        const projectName = _readProjectNameFromInfo(resolvedPath) || basename(projectRoot) || 'unnamed';
-        if (existingRows.length > 0) {
-            const existingPath = existingRows[0].projectPath;
-            if (existingPath !== resolvedPath) {
-                // Seamless move/rename/export-import: same immutable projectId, new
-                // path. Update the path AND the projectHash fingerprint so the dual
-                // fingerprint tracks the new location (T11281).
-                const newBrainDbPath = join(resolvedPath, '.cleo', 'brain.db');
-                const newTasksDbPath = join(resolvedPath, '.cleo', 'tasks.db');
-                await db
-                    .update(projectRegistry)
-                    .set({
-                    projectPath: resolvedPath,
-                    projectHash: generateProjectHash(resolvedPath),
-                    brainDbPath: newBrainDbPath,
-                    tasksDbPath: newTasksDbPath,
-                    lastSeen: now,
-                })
-                    .where(eq(projectRegistry.projectId, immutableId));
-            }
-            else {
-                await db
-                    .update(projectRegistry)
-                    .set({ lastSeen: now })
-                    .where(eq(projectRegistry.projectId, immutableId));
-            }
-            return;
-        }
-        // T11281: This insert follows a non-transactional select-by-projectId
-        // "not found" check above. Because the caller is a fire-and-forget
-        // `registerProjectOnEncounter(...).catch(() => {})` (paths.ts auto-register
-        // on first encounter, T11021), it can race a concurrent explicit
-        // `nexusRegister`/`registerProjectOnEncounter` for the same project: both
-        // pass the existence check, then both INSERT, and the loser throws
-        // `UNIQUE constraint failed: project_registry.project_path` (or the
-        // projectId PK). The auto-register is best-effort and idempotent by intent,
-        // so a lost race must be a silent no-op, not a thrown error. onConflictDoNothing
-        // makes the canonical-id PK and the project_path UNIQUE index both safe.
-        await db
-            .insert(projectRegistry)
-            .values({
-            projectId: immutableId,
-            // T11280: projectHash MUST be the canonical sha256-derived hash of the
-            // resolved path (matching nexusRegister/generateProjectHash), NOT the raw
-            // gitRoot path. The previous value polluted the registry with a path in
-            // the hash column, producing spurious name-collision errors when a later
-            // nexusRegister computed the real hash for the same project.
-            projectHash: generateProjectHash(resolvedPath),
-            projectPath: resolvedPath,
-            name: projectName,
-            registeredAt: now,
-            lastSeen: now,
-            healthStatus: 'unknown',
-            healthLastCheck: null,
-            permissions: 'read',
-            lastSync: now,
-            taskCount: 0,
-            labelsJson: '[]',
-            brainDbPath: join(resolvedPath, '.cleo', 'brain.db'),
-            tasksDbPath: join(resolvedPath, '.cleo', 'tasks.db'),
-            statsJson: '{}',
-        })
-            .onConflictDoNothing();
-        // Map every alternate identity token — the path-derived canonical id, the
-        // legacy base64url id, and any declared legacy aliases — to the IMMUTABLE
-        // registry id, so a lookup by ANY of them resolves to the project's lifetime
-        // row via the alias table (T11281). The immutable id is never its own alias.
-        const aliases = canonicalResult.legacyAliases ?? [];
-        const { legacyProjectId } = await import('./nexus/identity.js');
-        const directLegacy = legacyProjectId(resolvedPath);
-        const allAliases = new Set([directLegacy, canonicalId, infoProjectId, ...aliases]);
-        allAliases.delete(immutableId);
-        for (const legacyId of allAliases) {
-            try {
-                await db
-                    .insert(projectIdAliases)
-                    .values({ legacyId, canonicalId: immutableId, createdAt: now })
-                    .onConflictDoNothing();
-            }
-            catch {
-                /* best-effort */
-            }
-        }
+        const outcome = await trackBackgroundOp(() => worktreeScope.run({ ...scope, execution }, async () => {
+            const { canonicalProjectId, legacyProjectId } = await import('./nexus/identity.js');
+            const { generateProjectHash } = await import('./nexus/hash.js');
+            const canonical = await canonicalProjectId(resolvedPath, execution);
+            execution.assertActive();
+            const { getNexusRegistryDb } = await import('./store/nexus-sqlite.js');
+            const { eq, or } = await import('drizzle-orm');
+            const { projectRegistry, projectIdAliases } = await import('./store/schema/nexus-schema.js');
+            const db = await getNexusRegistryDb(capturedHome);
+            execution.assertActive();
+            const projectHash = generateProjectHash(resolvedPath);
+            const legacyAlias = legacyProjectId(resolvedPath);
+            const skippedAliases = [];
+            const aliases = new Set([legacyAlias, canonical.id, ...(canonical.legacyAliases ?? [])]);
+            aliases.delete(infoProjectId);
+            db.transaction((tx) => {
+                execution.assertActive();
+                const owners = tx
+                    .select()
+                    .from(projectRegistry)
+                    .where(or(eq(projectRegistry.projectId, infoProjectId), eq(projectRegistry.projectPath, resolvedPath), eq(projectRegistry.projectHash, projectHash)))
+                    .all();
+                if (owners.some((owner) => owner.projectId !== infoProjectId))
+                    throw new Error('Project encounter path or hash belongs to another immutable identity');
+                const now = new Date().toISOString();
+                const existing = owners.find((owner) => owner.projectId === infoProjectId);
+                if (existing) {
+                    tx.update(projectRegistry)
+                        .set({
+                        projectPath: resolvedPath,
+                        projectHash,
+                        lastSeen: now,
+                        brainDbPath: join(resolvedPath, '.cleo', 'brain.db'),
+                        tasksDbPath: join(resolvedPath, '.cleo', 'tasks.db'),
+                    })
+                        .where(eq(projectRegistry.projectId, infoProjectId))
+                        .run();
+                }
+                else {
+                    tx.insert(projectRegistry)
+                        .values({
+                        projectId: infoProjectId,
+                        projectHash,
+                        projectPath: resolvedPath,
+                        name: projectName,
+                        registeredAt: now,
+                        lastSeen: now,
+                        healthStatus: 'unknown',
+                        healthLastCheck: null,
+                        permissions: 'read',
+                        lastSync: now,
+                        taskCount: 0,
+                        labelsJson: '[]',
+                        brainDbPath: join(resolvedPath, '.cleo', 'brain.db'),
+                        tasksDbPath: join(resolvedPath, '.cleo', 'tasks.db'),
+                        statsJson: '{}',
+                    })
+                        .run();
+                }
+                for (const alias of aliases) {
+                    const owner = tx
+                        .select()
+                        .from(projectIdAliases)
+                        .where(eq(projectIdAliases.legacyId, alias))
+                        .get();
+                    const directOwner = tx
+                        .select()
+                        .from(projectRegistry)
+                        .where(eq(projectRegistry.projectId, alias))
+                        .get();
+                    if ((owner && owner.canonicalId !== infoProjectId) ||
+                        (directOwner && directOwner.projectId !== infoProjectId)) {
+                        // Match explicit registration: this old truncated token is lossy.
+                        // Preserve its existing owner; the immutable identity still registers.
+                        if (alias === legacyAlias) {
+                            skippedAliases.push(alias);
+                            continue;
+                        }
+                        throw new Error('Project encounter alias belongs to another immutable identity');
+                    }
+                    if (!owner)
+                        tx.insert(projectIdAliases)
+                            .values({ legacyId: alias, canonicalId: infoProjectId, createdAt: now })
+                            .run();
+                }
+                execution.assertActive();
+            }, { behavior: 'immediate' });
+            if (skippedAliases.length > 0)
+                process.stderr.write(`[cleo] Project encounter omitted colliding legacy alias: ${skippedAliases.join(', ')}\n`);
+        }), execution);
+        if (outcome.status === 'rejected')
+            throw outcome.reason;
     }
-    catch {
-        /* best-effort registration */
+    finally {
+        if (ownedExecution)
+            execution.close();
     }
 }
 //# sourceMappingURL=paths.js.map