engineering-memory 1.11.7 → 1.11.9

package/runtime/dist/src/runtime/worktree-pool.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import * as z from 'zod/v4';
 import { GitInspector } from '../git/git-inspector.js';
 import { atomicWrite, assertManagedPath, canonicalPath, ensureManagedDirectory, pathExists, readJson, removeFile, safeSegment, } from '../utilities/files.js';
@@ -37,11 +37,29 @@ const allocationSchema = z.object({
     pendingDelivery: z.boolean(),
     recoveredWithoutReservation: z.boolean().optional(),
     reason: z.string().optional(),
+    root: z.string().optional(),
+    layout: z.union([z.literal(1), z.literal(2)]).optional(),
 });
 const registrySchema = z.object({
     schemaVersion: z.literal(1),
     projects: z.record(z.string(), z.object({ folder: z.string().regex(/^[a-zA-Z0-9._-]+$/), entries: z.array(allocationSchema) })),
 });
+export function managedBase(root, layout) {
+    return layout === 1
+        ? join(root, 'engineeringmemory')
+        : join(root, 'engineering_memory', 'worktrees');
+}
+function projectDirectory(root, folder, layout) {
+    return layout === 1
+        ? join(root, 'engineeringmemory', folder, 'worktrees')
+        : join(root, 'engineering_memory', 'worktrees', folder);
+}
+function worktreeName(folder, slot, layout) {
+    return folder + (layout === 1 ? '-worktree' : '_worktree') + slot;
+}
+function managedPath(root, folder, slot, layout) {
+    return join(projectDirectory(root, folder, layout), worktreeName(folder, slot, layout));
+}
 export class WorktreePool {
     stateRoot;
     ownerId;
@@ -53,6 +71,9 @@ export class WorktreePool {
     startTimes = new Map();
     ownStart;
     documents;
+    legacyDocuments;
+    overrideDocuments;
+    overrideProblem;
     before = new Map();
     pendingWork;
     constructor(stateRoot, options = {}) {
@@ -63,6 +84,7 @@ export class WorktreePool {
         this.now = options.now ?? Date.now;
         this.alive = options.processAlive ?? processAlive;
         this.documents = options.documentsRoot;
+        this.legacyDocuments = options.legacyDocumentsRoot ?? options.documentsRoot;
         this.pendingWork = options.pendingWork ?? (async () => false);
         this.registryPath = join(stateRoot, 'worktree-pool.json');
     }
@@ -79,8 +101,12 @@ export class WorktreePool {
         const commonDir = await this.commonDirectory(input.repoRoot);
         return this.transaction(async (registry) => {
             if (!registry.projects[input.projectId]) {
-                const managedRoot = key(join(await this.documentsDirectory(), 'engineeringmemory'));
-                const orphan = (await this.gitPaths(input.repoRoot)).find((p) => key(p.path).startsWith(managedRoot + (process.platform === 'win32' ? '\\' : '/')));
+                const separator = process.platform === 'win32' ? '\\' : '/';
+                const bases = [];
+                for (const root of await this.scanRoots())
+                    for (const layout of [1, 2])
+                        bases.push(key(managedBase(root, layout)) + separator);
+                const orphan = (await this.gitPaths(input.repoRoot)).find((p) => bases.some((base) => key(p.path).startsWith(base)));
                 if (orphan)
                     throw refuse('Existing managed Git worktrees have no project index. Run worktree.reconcile before allocating more directories.');
             }
@@ -107,7 +133,7 @@ export class WorktreePool {
                     if (paths.some((p) => p.branch === entry.branch && key(p.path) !== key(entry.repoRoot)))
                         throw refuse('The recorded branch is checked out at another location. Reconcile the moved worktree before resuming.');
                     if (paths.some((p) => key(p.path) === key(entry.repoRoot))) {
-                        await assertManagedPath(await this.documentsDirectory(), entry.repoRoot, true);
+                        await assertManagedPath(entry.root ?? (await this.legacyDocumentsDirectory()), entry.repoRoot, true);
                         if (await pathExists(entry.repoRoot))
                             throw refuse('The missing worktree reappeared; reconcile before recovery.');
                         await this.command(input.repoRoot, ['worktree', 'remove', entry.repoRoot]);
@@ -151,8 +177,10 @@ export class WorktreePool {
             if (checkout)
                 throw refuse('This branch already has a checkout. Resume its task instead of creating or resetting the branch.');
             let reusable;
+            const activeRoot = key(await this.documentsDirectory());
+            const legacyRoot = await this.legacyDocumentsDirectory();
             for (const candidate of project.entries
-                .filter((e) => e.managed && e.commonDir === commonDir)
+                .filter((e) => e.managed && e.commonDir === commonDir && key(e.root ?? legacyRoot) === activeRoot)
                 .sort((a, b) => a.slot - b.slot)) {
                 if (candidate.pendingDelivery ||
                     ['creating', 'quarantined'].includes(candidate.phase) ||
@@ -168,7 +196,7 @@ export class WorktreePool {
             if (entry) {
                 const old = structuredClone(entry);
                 await this.releaseReservation(old);
-                const next = await this.entry(input, commonDir, old.repoRoot, old.slot, true);
+                const next = await this.entry(input, commonDir, old.repoRoot, old.slot, true, old.root ?? (await this.legacyDocumentsDirectory()), old.layout ?? 1);
                 project.entries[project.entries.indexOf(entry)] = next;
                 entry = next;
                 await this.save(registry);
@@ -179,14 +207,15 @@ export class WorktreePool {
                 if (project.entries.filter((e) => e.managed).length >= policy.maxWorktrees)
                     throw refuse('The managed worktree limit is full. worktree.list explains protected directories; finish delivery or safely release a clean task. No files were deleted.');
                 let slot = 1;
-                const root = join(await this.documentsDirectory(), 'engineeringmemory', project.folder, 'worktrees');
-                await ensureManagedDirectory(await this.documentsDirectory(), root);
+                const active = await this.documentsDirectory();
+                const root = projectDirectory(active, project.folder, 2);
+                await ensureManagedDirectory(active, root);
                 while (project.entries.some((e) => e.slot === slot) ||
-                    (await pathExists(join(root, project.folder + '-worktree' + slot))))
+                    (await pathExists(join(root, worktreeName(project.folder, slot, 2)))))
                     slot++;
-                const path = join(root, project.folder + '-worktree' + slot);
+                const path = join(root, worktreeName(project.folder, slot, 2));
                 await assertManagedPath(root, path, true);
-                entry = await this.entry(input, commonDir, path, slot, true);
+                entry = await this.entry(input, commonDir, path, slot, true, await this.documentsDirectory(), 2);
                 project.entries.push(entry);
                 await this.save(registry);
                 await this.git.createWorktree(input.repoRoot, input.branch, path, input.baseCommit);
@@ -210,6 +239,12 @@ export class WorktreePool {
             .flatMap((p) => p.entries)
             .find((e) => e.taskId === taskId && e.phase !== 'released') ?? null));
     }
+    owns(entry) {
+        return (entry.phase !== 'released' &&
+            entry.owner !== null &&
+            entry.owner.id === this.ownerId &&
+            entry.owner.pid === process.pid);
+    }
     async forPath(projectId, repoRoot) {
         return this.transaction(async (registry) => structuredClone(registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot)) ??
             null));
@@ -326,24 +361,19 @@ export class WorktreePool {
             let project = registry.projects[projectId];
             const locations = await this.gitPaths(repoRoot);
             const candidates = [];
-            const managedRoot = join(await this.documentsDirectory(), 'engineeringmemory');
+            const managedRoots = await this.scanRoots();
             for (const location of locations) {
                 if (project?.entries.some((entry) => key(entry.repoRoot) === key(location.path)))
                     continue;
                 if (!(await pathExists(location.path)))
                     continue;
                 const parent = dirname(location.path);
-                const folder = dirname(parent).split(/[\\/]/).pop();
                 const name = location.path.split(/[\\/]/).pop();
-                if (key(parent) !== key(join(managedRoot, folder, 'worktrees')))
-                    continue;
-                const prefix = folder + '-worktree';
-                const slot = Number(name.slice(prefix.length));
-                if (!name.startsWith(prefix) ||
-                    !Number.isSafeInteger(slot) ||
-                    slot < 1 ||
-                    name !== prefix + slot)
+                const placement = this.placement(managedRoots, parent, name);
+                if (!placement)
                     continue;
+                const { documents, folder, slot, layout } = placement;
+                const managedRoot = managedBase(documents, layout);
                 try {
                     await assertManagedPath(managedRoot, location.path, false);
                     if ((await this.commonDirectory(location.path)) !== commonDir)
@@ -357,7 +387,7 @@ export class WorktreePool {
                     continue;
                 if (Object.entries(registry.projects).some(([id, value]) => id !== projectId && key(value.folder) === key(folder)))
                     continue;
-                candidates.push({ path: location.path, folder, slot });
+                candidates.push({ path: location.path, folder, slot, root: documents, layout });
             }
             if (!project) {
                 const folders = [...new Set(candidates.map((candidate) => candidate.folder))];
@@ -405,6 +435,8 @@ export class WorktreePool {
                     repoRoot: await canonicalPath(location.path),
                     slot: location.slot,
                     managed: true,
+                    root: resolve(location.root),
+                    layout: location.layout,
                     externalTaskId: reservation?.decision.externalTaskId ??
                         'unregistered-' + sha256(key(location.path)).slice(0, 20),
                     taskId: reservation?.decision.taskId,
@@ -451,9 +483,11 @@ export class WorktreePool {
         });
         return discoverOnly ? [] : this.list(projectId, policy);
     }
-    async entry(input, commonDir, repoRoot, slot, managed) {
+    async entry(input, commonDir, repoRoot, slot, managed, root, layout) {
         const generation = randomUUID();
         return {
+            ...(root ? { root: resolve(root) } : {}),
+            ...(layout ? { layout } : {}),
             projectId: input.projectId,
             repoFingerprint: input.repoFingerprint,
             commonDir,
@@ -626,9 +660,9 @@ export class WorktreePool {
             .slice(0, 70);
         if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(folder))
             folder = 'project-' + folder;
-        const root = join(await this.documentsDirectory(), 'engineeringmemory');
         if (Object.values(registry.projects).some((p) => key(p.folder) === key(folder)) ||
-            (await pathExists(join(root, folder))))
+            (await pathExists(projectDirectory(await this.documentsDirectory(), folder, 2))) ||
+            (await pathExists(join(managedBase(await this.legacyDocumentsDirectory(), 1), folder))))
             folder += '-' + sha256(projectId).slice(0, 8);
         if (Object.values(registry.projects).some((p) => key(p.folder) === key(folder)))
             throw refuse('The managed project folder identity conflicts with another project.');
@@ -697,9 +731,87 @@ export class WorktreePool {
             return null;
         }
     }
+    async managedRoot() {
+        const root = managedBase(await this.documentsDirectory(), 2);
+        return {
+            root,
+            override: join(this.stateRoot, 'worktree-root.json'),
+            synced: /onedrive|dropbox|icloud|mobile documents|google\s?drive/i.test(root),
+            ...(this.overrideProblem ? { problem: this.overrideProblem } : {}),
+        };
+    }
     async documentsDirectory() {
+        if (this.overrideDocuments)
+            return this.overrideDocuments;
+        const overridePath = join(this.stateRoot, 'worktree-root.json');
+        this.overrideProblem = undefined;
+        let override = null;
+        try {
+            override = await readJson(overridePath);
+        }
+        catch (error) {
+            this.overrideProblem = `${overridePath} could not be read and is ignored: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        if (override && typeof override.root === 'string' && isAbsolute(override.root)) {
+            try {
+                await mkdir(override.root, { recursive: true }).catch((error) => {
+                    if (!['EEXIST', 'EPERM'].includes(error.code ?? ''))
+                        throw error;
+                });
+                this.overrideDocuments = resolve(override.root);
+                return this.overrideDocuments;
+            }
+            catch (error) {
+                this.overrideProblem = `${overridePath} names ${override.root}, which could not be created and is ignored: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        else if (override) {
+            this.overrideProblem = `${overridePath} must contain {"root": "<absolute directory>"} and is ignored.`;
+        }
+        return this.defaultDocumentsDirectory();
+    }
+    async defaultDocumentsDirectory() {
         if (this.documents)
             return resolve(this.documents);
+        this.documents =
+            process.platform === 'win32' ? (process.env.SystemDrive ?? 'C:') + '\\' : homedir();
+        return resolve(this.documents);
+    }
+    async scanRoots() {
+        return [
+            ...new Map([
+                await this.documentsDirectory(),
+                await this.defaultDocumentsDirectory(),
+                await this.legacyDocumentsDirectory(),
+            ].map((root) => [key(root), root])).values(),
+        ];
+    }
+    placement(roots, parent, name) {
+        for (const documents of roots) {
+            const parentName = parent.split(/[\\/]/).pop() ?? '';
+            const grandParent = dirname(parent);
+            const legacyFolder = grandParent.split(/[\\/]/).pop() ?? '';
+            const attempts = [
+                { folder: parentName, layout: 2 },
+                { folder: legacyFolder, layout: 1 },
+            ];
+            for (const { folder, layout } of attempts) {
+                if (!folder || key(parent) !== key(projectDirectory(documents, folder, layout)))
+                    continue;
+                const prefix = folder + (layout === 1 ? '-worktree' : '_worktree');
+                const slot = Number(name.slice(prefix.length));
+                if (name.startsWith(prefix) &&
+                    Number.isSafeInteger(slot) &&
+                    slot >= 1 &&
+                    name === prefix + slot)
+                    return { documents, folder, slot, layout };
+            }
+        }
+        return null;
+    }
+    async legacyDocumentsDirectory() {
+        if (this.legacyDocuments)
+            return resolve(this.legacyDocuments);
         if (process.platform === 'win32') {
             const result = await this.runner.run('powershell.exe', [
                 '-NoProfile',
@@ -709,19 +821,18 @@ export class WorktreePool {
             ], {});
             if (result.exitCode !== 0 || !result.stdout.trim())
                 throw refuse('The Windows Documents folder could not be resolved.');
-            this.documents = result.stdout.trim();
+            this.legacyDocuments = result.stdout.trim();
         }
         else if (process.platform === 'linux') {
             const result = await this.runner.run('xdg-user-dir', ['DOCUMENTS'], {}).catch(() => null);
-            this.documents =
+            this.legacyDocuments =
                 result?.exitCode === 0 && result.stdout.trim()
                     ? result.stdout.trim()
                     : join(homedir(), 'Documents');
         }
         else
-            this.documents = join(homedir(), 'Documents');
-        await mkdir(this.documents, { recursive: true });
-        return resolve(this.documents);
+            this.legacyDocuments = join(homedir(), 'Documents');
+        return resolve(this.legacyDocuments);
     }
     async transaction(work) {
         await mkdir(this.stateRoot, { recursive: true });
@@ -764,8 +875,10 @@ export class WorktreePool {
                     throw refuse('The registry contains conflicting task ownership. Restore a validated backup with worktree.reconcile.');
                 paths.add(key(entry.repoRoot));
                 if (entry.managed) {
-                    const documents = await this.documentsDirectory();
-                    const expected = join(documents, 'engineeringmemory', project.folder, 'worktrees', project.folder + '-worktree' + entry.slot);
+                    const documents = entry.root ?? (await this.legacyDocumentsDirectory());
+                    const expected = entry.slot
+                        ? managedPath(documents, project.folder, entry.slot, entry.layout ?? 1)
+                        : '';
                     if (!entry.slot || key(entry.repoRoot) !== key(expected))
                         throw refuse('A managed worktree path does not match its project Documents directory. Reconcile before continuing.');
                     await assertManagedPath(documents, entry.repoRoot, true);

package/runtime/dist/src/utilities/files.js

@@ -118,7 +118,10 @@ export async function assertManagedPath(root, target, allowMissingTarget) {
 export async function ensureManagedDirectory(root, directory) {
     const resolvedRoot = resolve(root);
     const resolvedDirectory = ensureWithinRoot(resolvedRoot, directory);
-    await mkdir(resolvedRoot, { recursive: true });
+    await mkdir(resolvedRoot, { recursive: true }).catch((error) => {
+        if (!isNodeError(error) || !['EEXIST', 'EPERM'].includes(error.code ?? ''))
+            throw error;
+    });
     const rootStat = await lstat(resolvedRoot);
     if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
         throw new Error(`Managed root must be a real directory: ${resolvedRoot}`);

package/skill/references/lifecycle.md

@@ -14,7 +14,7 @@ Before a new write or scaffold task, read `session.entry` and the project Git pr
 
 Call `task.branch` with the stable `externalTaskId` and `repoRoot`. Its native forms show configured branch names, the current commit, another branch, and the explicit keep-current option. New branches always use a separate managed worktree. Configured remote bases are fetched and their exact commits pinned; after a fetch failure select an explicit local source through a new native decision, never silently use a cached branch. Existing task decisions survive retries and restarts. Resume their recorded branch rather than recreating or resetting it.
 
-Use the returned `repoRoot` for **every** file read/write, terminal, context, validation and Git/delivery operation. The user-local pool is shared by Codex and Claude. Managed directories live in the OS Documents folder under `engineeringmemory/<stable-project-folder>/worktrees/<folder>-worktreeN`; do not supply arbitrary `worktreePath` values or create ad-hoc siblings. Independent clones cannot reuse each other's worktrees. `worktree.list` explains which slots are active, inactive but protected, or safely reusable. The versioned backend policy defaults to 50 directories per project/computer, 30-second heartbeats and 10-minute inactivity. Protected inactive directories still count toward the limit. Only a global admin changes `worktree.set_policy`; it is not an environment setting.
+Use the returned `repoRoot` for **every** file read/write, terminal, context, validation and Git/delivery operation. The user-local pool is shared by Codex and Claude. Managed directories live under `engineering_memory/worktrees/<stable-project-folder>/<folder>_worktreeN`, at the root of the system drive on Windows (`C:\engineering_memory\worktrees\...`) and in the home directory elsewhere, or under the absolute directory named by `worktree-root.json` in the user-level API state directory when that file exists; `worktree.list` reports the effective root, and worktrees created by earlier clients under the Documents folder keep working where they are. Do not supply arbitrary `worktreePath` values or create ad-hoc siblings. Independent clones cannot reuse each other's worktrees. `worktree.list` explains which slots are active, inactive but protected, or safely reusable. The versioned backend policy defaults to 50 directories per project/computer, 30-second heartbeats and 10-minute inactivity. Protected inactive directories still count toward the limit. Only a global admin changes `worktree.set_policy`; it is not an environment setting.
 
 Renew `task.heartbeat` using the exact returned task, path and ownership generation during actual work and at approximately the cached heartbeat interval during long local commands. The bridge renews while its own task operation is running. Never run a perpetual heartbeat for an idle chat or MCP process. Inactivity never authorizes takeover of a live owner or deletion of files. Before writing after interruption, use `session.resume`; follow any returned worktree redirect and resume there. A stale generation cannot renew, release, verify or commit another owner's work.