engineering-memory 1.11.3 → 1.11.5

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

@@ -0,0 +1,847 @@
+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 * 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';
+import { sha256 } from '../utilities/hash.js';
+import { localMutex } from '../utilities/local-mutex.js';
+import { NativeCommandRunner } from '../utilities/process.js';
+import { BridgeRecoveryError } from './recovery-error.js';
+const allocationSchema = z.object({
+    projectId: z.string().min(1),
+    repoFingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    commonDir: z.string().min(1),
+    repoRoot: z.string().min(1),
+    slot: z.number().int().min(1).nullable(),
+    managed: z.boolean(),
+    externalTaskId: z.string().min(1),
+    taskId: z.string().optional(),
+    branch: z.string().nullable(),
+    baseCommit: z
+        .string()
+        .regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/)
+        .nullable(),
+    owner: z
+        .object({
+        id: z.string().uuid(),
+        pid: z.number().int().positive(),
+        generation: z.string().uuid(),
+        startedAt: z.string().optional(),
+    })
+        .nullable(),
+    generation: z.string().uuid(),
+    lastActivityAt: z.number().finite(),
+    phase: z.enum(['creating', 'working', 'paused', 'delivery', 'released', 'quarantined']),
+    pendingDelivery: z.boolean(),
+    reason: z.string().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 class WorktreePool {
+    stateRoot;
+    ownerId;
+    runner;
+    git;
+    now;
+    alive;
+    registryPath;
+    startTimes = new Map();
+    ownStart;
+    documents;
+    before = new Map();
+    pendingWork;
+    constructor(stateRoot, options = {}) {
+        this.stateRoot = stateRoot;
+        this.ownerId = options.ownerId ?? randomUUID();
+        this.runner = options.runner ?? new NativeCommandRunner();
+        this.git = new GitInspector(this.runner);
+        this.now = options.now ?? Date.now;
+        this.alive = options.processAlive ?? processAlive;
+        this.documents = options.documentsRoot;
+        this.pendingWork = options.pendingWork ?? (async () => false);
+        this.registryPath = join(stateRoot, 'worktree-pool.json');
+    }
+    async allocate(input, policy) {
+        if (input.branch) {
+            try {
+                await this.git.validateBranch(input.repoRoot, input.branch);
+            }
+            catch {
+                throw new BridgeRecoveryError('Choose a valid literal Git branch name of at most 255 characters. Retry task.branch with the corrected name; no allocation was recorded.', 'task.branch');
+            }
+        }
+        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' ? '\\' : '/')));
+                if (orphan)
+                    throw refuse('Existing managed Git worktrees have no project index. Run worktree.reconcile before allocating more directories.');
+            }
+            const project = await this.project(registry, input.projectId, input.projectName);
+            let entry = project.entries.find((e) => e.externalTaskId === input.externalTaskId && e.phase !== 'released');
+            if (entry) {
+                this.requireSameClone(entry, commonDir);
+                if (entry.branch !== input.branch)
+                    throw refuse('This task already owns a different branch. Resume its recorded worktree.');
+                if (entry.phase === 'quarantined' && input.resume) {
+                    if (entry.owner && (await this.ownerAlive(entry.owner)))
+                        throw refuse('Stop or pause the original owner before resuming a recovered registry entry.');
+                    await this.assertIdentity(entry);
+                    entry.phase = 'paused';
+                    entry.pendingDelivery = true;
+                    delete entry.reason;
+                }
+                await this.requireTakeover(entry);
+                await this.repairCreating(entry);
+                if (!(await pathExists(entry.repoRoot))) {
+                    if (!entry.managed || (!input.resume && entry.phase !== 'creating'))
+                        throw refuse('The task worktree is missing. Resume with its recorded branch, or reconcile the moved Git worktree.');
+                    const paths = await this.gitPaths(input.repoRoot);
+                    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);
+                        if (await pathExists(entry.repoRoot))
+                            throw refuse('The missing worktree reappeared; reconcile before recovery.');
+                        await this.command(input.repoRoot, ['worktree', 'remove', entry.repoRoot]);
+                    }
+                    await this.git.createWorktree(input.repoRoot, entry.branch, entry.repoRoot, entry.baseCommit ?? undefined);
+                }
+                await this.assertIdentity(entry);
+                return await this.claim(registry, entry);
+            }
+            if (input.keepCurrent) {
+                const current = await this.git.sourceIdentity(input.repoRoot);
+                if ((current?.sourceCommit ?? null) !== input.baseCommit)
+                    throw refuse('HEAD changed after the current-branch choice. Review a fresh task.branch decision.');
+                const root = await this.git.findRoot(input.repoRoot);
+                entry = project.entries.find((e) => key(e.repoRoot) === key(root));
+                if (entry && entry.phase !== 'released')
+                    throw refuse('This checkout is reserved for another task. Choose a new branch in an isolated worktree.');
+                const reservation = await this.git.branchStore(root).read();
+                if (reservation && reservation.decision.externalTaskId !== input.externalTaskId)
+                    throw refuse('A legacy task reservation owns this checkout. Resume it or choose an isolated worktree.');
+                entry = await this.entry(input, commonDir, root, null, false);
+                project.entries = project.entries.filter((e) => key(e.repoRoot) !== key(root));
+                project.entries.push(entry);
+                await this.save(registry);
+                await this.reserve(entry);
+                entry.phase = 'working';
+                await this.save(registry);
+                return structuredClone(entry);
+            }
+            if (!input.branch)
+                throw refuse('A managed worktree requires the chosen new task branch.');
+            if (!input.baseCommit)
+                throw new BridgeRecoveryError('This repository has no committed base yet. For its initial scaffold, choose keepCurrent through task.branch in the unowned prepared repository; subsequent new branches use isolated worktrees.', 'task.branch');
+            if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(input.baseCommit) ||
+                (await this.git.sourceIdentity(input.repoRoot, input.baseCommit))?.sourceCommit !==
+                    input.baseCommit)
+                throw new BridgeRecoveryError('The chosen base commit is unavailable in this clone. Make a fresh task.branch source choice; no allocation was recorded.', 'task.branch');
+            if (!input.resume && (await this.git.branchExists(input.repoRoot, input.branch)))
+                throw refuse('That branch already exists. Resume its recorded task or choose a new branch name; the selected base was not substituted.');
+            const checkout = (await this.gitPaths(input.repoRoot)).find((p) => p.branch === input.branch);
+            if (checkout)
+                throw refuse('This branch already has a checkout. Resume its task instead of creating or resetting the branch.');
+            let reusable;
+            for (const candidate of project.entries
+                .filter((e) => e.managed && e.commonDir === commonDir)
+                .sort((a, b) => a.slot - b.slot)) {
+                if (candidate.pendingDelivery ||
+                    ['creating', 'quarantined'].includes(candidate.phase) ||
+                    (candidate.owner && (await this.ownerAlive(candidate.owner))))
+                    continue;
+                const view = await this.view(candidate, policy);
+                if (view.activity === 'available') {
+                    reusable = candidate;
+                    break;
+                }
+            }
+            entry = reusable;
+            if (entry) {
+                const old = structuredClone(entry);
+                await this.releaseReservation(old);
+                const next = await this.entry(input, commonDir, old.repoRoot, old.slot, true);
+                project.entries[project.entries.indexOf(entry)] = next;
+                entry = next;
+                await this.save(registry);
+                await this.reserve(entry);
+                await this.checkout(entry);
+            }
+            else {
+                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);
+                while (project.entries.some((e) => e.slot === slot) ||
+                    (await pathExists(join(root, project.folder + '-worktree' + slot))))
+                    slot++;
+                const path = join(root, project.folder + '-worktree' + slot);
+                await assertManagedPath(root, path, true);
+                entry = await this.entry(input, commonDir, path, slot, true);
+                project.entries.push(entry);
+                await this.save(registry);
+                await this.git.createWorktree(input.repoRoot, input.branch, path, input.baseCommit);
+            }
+            await this.reserve(entry);
+            entry.phase = 'working';
+            await this.save(registry);
+            return structuredClone(entry);
+        });
+    }
+    async list(projectId, policy) {
+        return this.transaction(async (registry) => {
+            const result = [];
+            for (const entry of registry.projects[projectId]?.entries ?? [])
+                result.push(await this.view(entry, policy));
+            return result;
+        });
+    }
+    async forTask(taskId) {
+        return this.transaction(async (registry) => structuredClone(Object.values(registry.projects)
+            .flatMap((p) => p.entries)
+            .find((e) => e.taskId === taskId && e.phase !== 'released') ?? null));
+    }
+    async forPath(projectId, repoRoot) {
+        return this.transaction(async (registry) => structuredClone(registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot)) ??
+            null));
+    }
+    async validateCommit(projectId, taskId, repoRoot, generation) {
+        return this.transaction(async (registry) => {
+            const entry = registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot));
+            if (!entry && !generation)
+                return;
+            if (!entry ||
+                entry.taskId !== taskId ||
+                entry.generation !== generation ||
+                entry.phase !== 'delivery')
+                throw refuse('The verification belongs to a previous or paused worktree owner. Resume and verify this task before committing.');
+            await this.assertIdentity(entry);
+        });
+    }
+    async find(projectId, externalTaskId, repoRoot) {
+        const commonDir = await this.commonDirectory(repoRoot);
+        return this.transaction(async (registry) => {
+            const entry = registry.projects[projectId]?.entries.find((e) => e.externalTaskId === externalTaskId && e.phase !== 'released');
+            if (entry)
+                this.requireSameClone(entry, commonDir);
+            return structuredClone(entry ?? null);
+        });
+    }
+    async assertOwnership(projectId, repoRoot, generation, touch = true) {
+        return this.transaction(async (registry) => {
+            const entry = this.owned(registry, projectId, repoRoot, generation);
+            await this.assertIdentity(entry);
+            if (touch) {
+                entry.lastActivityAt = this.now();
+                await this.save(registry);
+            }
+            return structuredClone(entry);
+        });
+    }
+    async bind(projectId, repoRoot, generation, taskId) {
+        return this.transaction(async (registry) => {
+            const entry = this.owned(registry, projectId, repoRoot, generation);
+            if (entry.taskId && entry.taskId !== taskId)
+                throw refuse('This worktree is already bound to a different task.');
+            entry.taskId = taskId;
+            await this.git.branchStore(repoRoot).bind(projectId, entry.externalTaskId, taskId);
+            entry.phase = 'working';
+            entry.lastActivityAt = this.now();
+            await this.save(registry);
+        });
+    }
+    async pause(projectId, repoRoot, generation) {
+        return this.transaction(async (registry) => {
+            const entry = this.owned(registry, projectId, repoRoot, generation);
+            entry.phase = 'paused';
+            entry.owner = null;
+            entry.generation = randomUUID();
+            await this.save(registry);
+        });
+    }
+    async delivery(projectId, repoRoot, generation) {
+        return this.transaction(async (registry) => {
+            const entry = this.owned(registry, projectId, repoRoot, generation);
+            entry.phase = 'delivery';
+            entry.pendingDelivery = true;
+            await this.save(registry);
+        });
+    }
+    async release(projectId, repoRoot, generation, delivered) {
+        return this.transaction(async (registry) => {
+            const entry = this.owned(registry, projectId, repoRoot, generation);
+            const reasons = await this.fileProtection(entry);
+            if (reasons.length)
+                throw refuse('The worktree is protected: ' +
+                    reasons.join(', ') +
+                    '. Finish or preserve the work before release.');
+            if (entry.pendingDelivery && !delivered)
+                throw refuse('Delivery is pending. Complete delivery before safely releasing this worktree.');
+            await this.releaseReservation(entry);
+            entry.pendingDelivery = false;
+            entry.phase = 'released';
+            entry.owner = null;
+            entry.generation = randomUUID();
+            await this.save(registry);
+        });
+    }
+    async reconcile(projectId, repoRoot, policy) {
+        await this.restoreRegistry();
+        const commonDir = await this.commonDirectory(repoRoot);
+        await this.transaction(async (registry) => {
+            let project = registry.projects[projectId];
+            if (!project) {
+                const locations = await this.gitPaths(repoRoot);
+                for (const location of locations) {
+                    if (!(await pathExists(location.path)))
+                        continue;
+                    const reservation = await this.git.branchStore(location.path).read();
+                    if (reservation?.decision.projectId !== projectId)
+                        continue;
+                    const folder = dirname(dirname(location.path)).split(/[\\/]/).pop();
+                    const expected = join(await this.documentsDirectory(), 'engineeringmemory', folder, 'worktrees');
+                    if (key(dirname(location.path)) !== key(expected))
+                        continue;
+                    registry.projects[projectId] = { folder, entries: [] };
+                    break;
+                }
+            }
+            const recoveredProject = registry.projects[projectId];
+            if (!recoveredProject)
+                return;
+            project = recoveredProject;
+            const locations = await this.gitPaths(repoRoot);
+            for (const entry of project.entries.filter((e) => e.commonDir === commonDir)) {
+                if (entry.owner && entry.owner.id !== this.ownerId && (await this.ownerAlive(entry.owner)))
+                    continue;
+                if (await pathExists(entry.repoRoot))
+                    continue;
+                const moved = locations.find((p) => p.branch === entry.branch && key(p.path) !== key(entry.repoRoot));
+                if (moved && (await pathExists(moved.path))) {
+                    const reservation = await this.git.branchStore(moved.path).read();
+                    if (reservation?.decision.projectId === projectId &&
+                        reservation.decision.externalTaskId === entry.externalTaskId) {
+                        entry.repoRoot = await canonicalPath(moved.path);
+                        entry.managed = false; // a user-moved directory is never returned to the automatic pool
+                        entry.slot = null;
+                        entry.owner = null;
+                        entry.generation = randomUUID();
+                        entry.phase = 'paused';
+                    }
+                }
+            }
+            for (const location of locations) {
+                if (project.entries.some((e) => key(e.repoRoot) === key(location.path)))
+                    continue;
+                const parent = dirname(location.path);
+                if (dirname(parent)
+                    .split(/[\\\\/]/)
+                    .pop() !== project.folder ||
+                    parent.split(/[\\\\/]/).pop() !== 'worktrees')
+                    continue;
+                const reservation = await this.git.branchStore(location.path).read();
+                if (reservation?.decision.projectId !== projectId)
+                    continue;
+                const source = await this.git.sourceIdentity(location.path);
+                const slotText = location.path
+                    .split(/[\\\\/]/)
+                    .pop()
+                    ?.match(/-worktree([0-9]+)$/)?.[1];
+                if (!source || !slotText)
+                    continue;
+                project.entries.push({
+                    projectId,
+                    repoFingerprint: await this.git.fingerprint(repoRoot),
+                    commonDir,
+                    repoRoot: await canonicalPath(location.path),
+                    slot: Number(slotText),
+                    managed: true,
+                    externalTaskId: reservation.decision.externalTaskId,
+                    taskId: reservation.decision.taskId,
+                    branch: reservation.decision.branch,
+                    baseCommit: source.sourceCommit,
+                    owner: null,
+                    generation: randomUUID(),
+                    lastActivityAt: 0,
+                    phase: 'quarantined',
+                    pendingDelivery: true,
+                    reason: 'Recovered a Git reservation missing from the registry. Restore its original task source and delivery state before reuse.',
+                });
+            }
+            for (const entry of project.entries.filter((e) => e.commonDir === commonDir)) {
+                if (entry.owner && (await this.ownerAlive(entry.owner)) && entry.owner.id !== this.ownerId)
+                    continue;
+                try {
+                    await this.repairCreating(entry);
+                    if (await pathExists(entry.repoRoot))
+                        await this.assertIdentity(entry);
+                }
+                catch {
+                    entry.phase = 'quarantined';
+                    entry.reason =
+                        'Git and registry disagree. Inspect worktree.list and repair the recorded Git worktree without deleting files.';
+                }
+            }
+            await this.save(registry);
+        });
+        return this.list(projectId, policy);
+    }
+    async entry(input, commonDir, repoRoot, slot, managed) {
+        const generation = randomUUID();
+        return {
+            projectId: input.projectId,
+            repoFingerprint: input.repoFingerprint,
+            commonDir,
+            repoRoot,
+            slot,
+            managed,
+            externalTaskId: input.externalTaskId,
+            branch: input.branch,
+            baseCommit: input.baseCommit,
+            generation,
+            owner: {
+                id: this.ownerId,
+                pid: process.pid,
+                generation,
+                ...((await this.ownerStart()) ? { startedAt: (await this.ownerStart()) } : {}),
+            },
+            lastActivityAt: this.now(),
+            phase: 'creating',
+            pendingDelivery: false,
+        };
+    }
+    async claim(registry, entry) {
+        if (entry.owner?.id !== this.ownerId) {
+            entry.generation = randomUUID();
+            entry.owner = {
+                id: this.ownerId,
+                pid: process.pid,
+                generation: entry.generation,
+                ...((await this.ownerStart()) ? { startedAt: (await this.ownerStart()) } : {}),
+            };
+        }
+        if (entry.phase === 'paused')
+            entry.phase = 'working';
+        entry.lastActivityAt = this.now();
+        await this.reserve(entry);
+        await this.save(registry);
+        return structuredClone(entry);
+    }
+    requireSameClone(entry, commonDir) {
+        if (entry.commonDir !== commonDir)
+            throw new BridgeRecoveryError('This task already has a recorded worktree in another clone. Resume with repoRoot ' +
+                entry.repoRoot +
+                '; no second checkout was allocated.', entry.taskId ? 'session.resume' : 'task.branch');
+    }
+    async requireTakeover(entry) {
+        if (entry.phase === 'quarantined')
+            throw refuse(entry.reason ?? 'The worktree requires reconciliation.');
+        if (entry.owner && entry.owner.id !== this.ownerId && (await this.ownerAlive(entry.owner)))
+            throw refuse('Another live client owns this task. Pause it there before resuming here; inactivity alone does not transfer ownership.');
+    }
+    owned(registry, projectId, repoRoot, generation) {
+        const entry = registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot));
+        if (!entry ||
+            !entry.owner ||
+            entry.generation !== generation ||
+            entry.owner.id !== this.ownerId ||
+            ['paused', 'released', 'quarantined'].includes(entry.phase))
+            throw refuse('Worktree ownership has changed or was paused. Resume the task and use its returned repoRoot before any further write.');
+        return entry;
+    }
+    async reserve(entry) {
+        await this.git.branchStore(entry.repoRoot).reserve({
+            projectId: entry.projectId,
+            externalTaskId: entry.externalTaskId,
+            branch: entry.branch,
+            ...(entry.taskId ? { taskId: entry.taskId } : {}),
+        });
+    }
+    async releaseReservation(entry) {
+        const store = this.git.branchStore(entry.repoRoot);
+        if (entry.taskId)
+            await store.release(entry.taskId);
+        else
+            await store.cancelUnopened(entry.projectId, entry.externalTaskId);
+    }
+    async checkout(entry) {
+        const existing = await this.git.sourceIdentity(entry.repoRoot, 'refs/heads/' + entry.branch);
+        const args = existing
+            ? ['switch', '--no-overwrite-ignore', '--', entry.branch]
+            : ['switch', '--no-overwrite-ignore', '--no-track', '-c', entry.branch, entry.baseCommit];
+        const result = await this.runner.run('git', args, { cwd: entry.repoRoot });
+        if (result.exitCode !== 0)
+            throw refuse('Git could not select the task branch. Reconcile the interrupted allocation; no reset was attempted.');
+    }
+    async repairCreating(entry) {
+        if (entry.phase !== 'creating' || !(await pathExists(entry.repoRoot)))
+            return;
+        const common = await this.commonDirectory(entry.repoRoot);
+        if (common !== entry.commonDir)
+            throw refuse('The worktree directory belongs to another clone.');
+        if ((await this.git.currentBranch(entry.repoRoot)) !== entry.branch) {
+            if ((await this.fileProtection(entry, true)).length)
+                throw refuse('An interrupted checkout contains protected work.');
+            await this.checkout(entry);
+        }
+        await this.reserve(entry);
+        entry.phase = 'working';
+    }
+    async assertIdentity(entry, allowBranchChange = false) {
+        if (key(await this.git.findRoot(entry.repoRoot)) !== key(await canonicalPath(entry.repoRoot)) ||
+            (await this.commonDirectory(entry.repoRoot)) !== entry.commonDir ||
+            (!allowBranchChange && (await this.git.currentBranch(entry.repoRoot)) !== entry.branch))
+            throw refuse('The worktree Git identity changed. Reconcile it before continuing; the task was not moved or reset.');
+        const reservation = await this.git.branchStore(entry.repoRoot).read();
+        if (reservation &&
+            (reservation.decision.projectId !== entry.projectId ||
+                reservation.decision.externalTaskId !== entry.externalTaskId))
+            throw refuse('Another task or legacy client reserved this checkout. Resume the recorded task.');
+    }
+    async fileProtection(entry, allowBranchChange = false) {
+        if (!(await pathExists(entry.repoRoot)))
+            return ['worktree directory missing'];
+        try {
+            await this.assertIdentity(entry, allowBranchChange);
+        }
+        catch {
+            return ['Git identity or reservation changed or unreadable; reconcile this checkout'];
+        }
+        const status = await this.runner.run('git', ['status', '--porcelain=v1', '--untracked-files=all'], { cwd: entry.repoRoot });
+        const reasons = [];
+        const reservation = await this.git.branchStore(entry.repoRoot).read();
+        if (reservation &&
+            (reservation.decision.projectId !== entry.projectId ||
+                reservation.decision.externalTaskId !== entry.externalTaskId))
+            reasons.push('another client or legacy task reserved this checkout');
+        if (await this.pendingWork(entry))
+            reasons.push('task delivery or intent pending');
+        if (status.exitCode !== 0 || status.stdout.trim())
+            reasons.push('uncommitted, staged or untracked files');
+        const gitDir = await this.command(entry.repoRoot, ['rev-parse', '--absolute-git-dir']);
+        for (const marker of [
+            'MERGE_HEAD',
+            'CHERRY_PICK_HEAD',
+            'REVERT_HEAD',
+            'BISECT_LOG',
+            'rebase-merge',
+            'rebase-apply',
+            'index.lock',
+            'locked',
+        ])
+            if (await pathExists(join(gitDir, marker)))
+                reasons.push('unfinished Git operation: ' + marker);
+        return reasons;
+    }
+    async view(entry, policy) {
+        const reasons = await this.fileProtection(entry);
+        if (entry.phase === 'creating' || entry.phase === 'quarantined')
+            reasons.push(entry.reason ?? 'allocation requires reconciliation');
+        if (entry.pendingDelivery)
+            reasons.push('delivery pending');
+        if (entry.owner && (await this.ownerAlive(entry.owner)))
+            reasons.push('owner process still running');
+        const age = this.now() - entry.lastActivityAt;
+        const active = entry.owner !== null &&
+            (await this.ownerAlive(entry.owner)) &&
+            age >= 0 &&
+            age < policy.inactivitySeconds * 1000 &&
+            entry.phase === 'working';
+        return {
+            ...structuredClone(entry),
+            activity: active ? 'active' : reasons.length ? 'inactive_protected' : 'available',
+            reasons,
+        };
+    }
+    async project(registry, projectId, projectName) {
+        if (registry.projects[projectId])
+            return registry.projects[projectId];
+        let folder = safeSegment(projectName)
+            .replace(/[. ]+$/, '')
+            .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))))
+            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.');
+        return (registry.projects[projectId] = { folder, entries: [] });
+    }
+    async commonDirectory(repoRoot) {
+        return key(await canonicalPath(await this.command(repoRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir'])));
+    }
+    async command(repoRoot, args) {
+        const result = await this.runner.run('git', args, { cwd: repoRoot });
+        if (result.exitCode !== 0)
+            throw refuse('Git metadata could not be read. Reconcile the repository before allocating or resuming.');
+        return result.stdout.trim();
+    }
+    async gitPaths(repoRoot) {
+        const output = await this.command(repoRoot, ['worktree', 'list', '--porcelain', '-z']);
+        return output
+            .split('\0\0')
+            .filter(Boolean)
+            .map((block) => {
+            const fields = block.split('\0');
+            return {
+                path: fields.find((f) => f.startsWith('worktree '))?.slice(9) ?? '',
+                branch: fields.find((f) => f.startsWith('branch refs/heads/'))?.slice(18) ?? null,
+            };
+        });
+    }
+    ownerStart() {
+        return (this.ownStart ??= this.processStart(process.pid));
+    }
+    async ownerAlive(owner) {
+        if (!this.alive(owner.pid))
+            return false;
+        if (!owner.startedAt)
+            return true; // unknown legacy identity is protected, not guessed dead
+        const cached = this.startTimes.get(owner.pid);
+        let current = cached?.value;
+        const age = cached ? Date.now() - cached.checkedAt : Infinity;
+        if (!cached || age < 0 || age > 15000) {
+            current = await this.processStart(owner.pid);
+            this.startTimes.set(owner.pid, { checkedAt: Date.now(), value: current });
+        }
+        return !current || current === owner.startedAt;
+    }
+    async processStart(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            return null;
+        try {
+            if (process.platform === 'linux') {
+                const stat = await readFile('/proc/' + pid + '/stat', 'utf8');
+                return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] ?? null;
+            }
+            const result = process.platform === 'win32'
+                ? await this.runner.run('powershell.exe', [
+                    '-NoProfile',
+                    '-NonInteractive',
+                    '-Command',
+                    '[System.Diagnostics.Process]::GetProcessById(' +
+                        pid +
+                        ').StartTime.ToUniversalTime().Ticks',
+                ], {})
+                : await this.runner.run('ps', ['-p', String(pid), '-o', 'lstart='], {});
+            return result.exitCode === 0 && result.stdout.trim() ? result.stdout.trim() : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async documentsDirectory() {
+        if (this.documents)
+            return resolve(this.documents);
+        if (process.platform === 'win32') {
+            const result = await this.runner.run('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                "[Environment]::GetFolderPath('MyDocuments')",
+            ], {});
+            if (result.exitCode !== 0 || !result.stdout.trim())
+                throw refuse('The Windows Documents folder could not be resolved.');
+            this.documents = result.stdout.trim();
+        }
+        else if (process.platform === 'linux') {
+            const result = await this.runner.run('xdg-user-dir', ['DOCUMENTS'], {}).catch(() => null);
+            this.documents =
+                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);
+    }
+    async transaction(work) {
+        await mkdir(this.stateRoot, { recursive: true });
+        return localMutex(key(await canonicalPath(this.stateRoot)), async () => {
+            if (await pathExists(this.registryPath + '.pending'))
+                await this.restoreRecords();
+            let registry;
+            try {
+                registry = await readJson(this.registryPath, this.stateRoot);
+            }
+            catch {
+                throw refuse('The local registry is damaged. worktree.reconcile must restore a validated backup before allocation; existing files are protected.');
+            }
+            if (!registry) {
+                if ((await pathExists(this.registryPath + '.previous')) ||
+                    (await pathExists(join(this.stateRoot, 'worktree-records'))))
+                    throw refuse('The registry is missing but its backup exists. Restore it through worktree.reconcile before allocating.');
+                registry = { schemaVersion: 1, projects: {} };
+            }
+            await this.validateRegistry(registry);
+            this.before = new Map(Object.values(registry.projects).flatMap((project) => project.entries.map((entry) => [
+                key(entry.repoRoot),
+                JSON.stringify({ folder: project.folder, entry }),
+            ])));
+            return work(registry);
+        });
+    }
+    async validateRegistry(registry) {
+        if (!registrySchema.safeParse(registry).success)
+            throw refuse('The local registry schema is invalid. Reconcile it before allocating.');
+        for (const project of Object.values(registry.projects))
+            if (!Array.isArray(project.entries) || typeof project.folder !== 'string')
+                throw refuse('The local project registry is invalid. Existing worktrees remain protected.');
+        for (const [projectId, project] of Object.entries(registry.projects)) {
+            const paths = new Set();
+            for (const entry of project.entries) {
+                if (entry.projectId !== projectId ||
+                    paths.has(key(entry.repoRoot)) ||
+                    (entry.owner && entry.owner.generation !== entry.generation))
+                    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);
+                    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);
+                }
+            }
+        }
+    }
+    async restoreRegistry() {
+        await mkdir(this.stateRoot, { recursive: true });
+        await localMutex(key(await canonicalPath(this.stateRoot)), async () => {
+            let current;
+            try {
+                current = await readJson(this.registryPath, this.stateRoot);
+            }
+            catch {
+                current = undefined;
+            }
+            if (registrySchema.safeParse(current).success &&
+                !(await pathExists(this.registryPath + '.pending')))
+                return;
+            if (await this.restoreRecords())
+                return;
+            let previous;
+            try {
+                previous = await readJson(this.registryPath + '.previous', this.stateRoot);
+            }
+            catch {
+                previous = undefined;
+            }
+            if (!current && !previous && !(await pathExists(this.registryPath)))
+                return;
+            const restored = registrySchema.safeParse(previous);
+            if (!restored.success)
+                throw refuse('No valid registry backup exists. Preserve the directories and restore the local registry backup; automatic allocation remains disabled.');
+            for (const project of Object.values(restored.data.projects))
+                for (const entry of project.entries) {
+                    entry.phase = 'quarantined';
+                    entry.reason =
+                        'Registry recovered from backup. The original owner must be stopped and the task explicitly resumed after checking Git and delivery state.';
+                }
+            await atomicWrite(this.registryPath, JSON.stringify(restored.data) + '\n', this.stateRoot);
+        });
+    }
+    async restoreRecords() {
+        if (await pathExists(this.registryPath + '.pending')) {
+            let raw;
+            try {
+                raw = await readJson(this.registryPath + '.pending', this.stateRoot);
+            }
+            catch {
+                throw refuse('The pending allocation transaction is damaged. Restore its local backup before reconciliation; existing directories remain protected.');
+            }
+            if (raw !== 1) {
+                const parsed = registrySchema.safeParse(raw);
+                if (!parsed.success)
+                    throw refuse('The pending allocation transaction is invalid. Restore its local backup before reconciliation.');
+                const registry = parsed.data;
+                await this.validateRegistry(registry);
+                await this.writeRecords(registry, true);
+                await atomicWrite(this.registryPath, JSON.stringify(registry) + '\n', this.stateRoot);
+                await removeFile(this.registryPath + '.pending', this.stateRoot);
+                return true;
+            }
+        }
+        const root = join(this.stateRoot, 'worktree-records');
+        if (!(await pathExists(root)))
+            return false;
+        const registry = { schemaVersion: 1, projects: {} };
+        const files = (await readdir(root)).filter((name) => /^[a-f0-9]{64}\.json$/.test(name));
+        if (!files.length)
+            return false;
+        for (const name of files) {
+            const raw = await readJson(join(root, name), this.stateRoot);
+            if (!raw ||
+                !/^[a-zA-Z0-9._-]+$/.test(raw.folder) ||
+                !allocationSchema.safeParse(raw.entry).success ||
+                sha256(key(raw.entry.repoRoot)) + '.json' !== name)
+                throw refuse('An allocation recovery record is damaged. Restore that local record from backup before reconciliation; no directory is reusable from incomplete evidence.');
+            const project = (registry.projects[raw.entry.projectId] ??= {
+                folder: raw.folder,
+                entries: [],
+            });
+            if (project.folder !== raw.folder)
+                throw refuse('Recovery records disagree on the project folder. Restore the matching local backup.');
+            project.entries.push(raw.entry);
+        }
+        await this.validateRegistry(registry);
+        await atomicWrite(this.registryPath, JSON.stringify(registry) + '\n', this.stateRoot);
+        await removeFile(this.registryPath + '.pending', this.stateRoot);
+        return true;
+    }
+    async writeRecords(registry, replay = false) {
+        const root = join(this.stateRoot, 'worktree-records');
+        await ensureManagedDirectory(this.stateRoot, root);
+        const current = new Set();
+        for (const project of Object.values(registry.projects))
+            for (const entry of project.entries) {
+                const name = sha256(key(entry.repoRoot)) + '.json';
+                current.add(name);
+                const content = JSON.stringify({ folder: project.folder, entry });
+                if (replay || this.before.get(key(entry.repoRoot)) !== content)
+                    await atomicWrite(join(root, name), content + '\n', this.stateRoot);
+            }
+        const previous = replay
+            ? (await readdir(root)).filter((name) => /^[a-f0-9]{64}\.json$/.test(name))
+            : [...this.before.keys()].map((path) => sha256(path) + '.json');
+        for (const name of previous)
+            if (!current.has(name))
+                await removeFile(join(root, name), this.stateRoot);
+    }
+    async save(registry) {
+        await this.validateRegistry(registry);
+        await atomicWrite(this.registryPath + '.pending', JSON.stringify(registry) + '\n', this.stateRoot);
+        await this.writeRecords(registry);
+        if (await pathExists(this.registryPath))
+            await atomicWrite(this.registryPath + '.previous', await readFile(this.registryPath), this.stateRoot);
+        await atomicWrite(this.registryPath, JSON.stringify(registry) + '\n', this.stateRoot);
+        await removeFile(this.registryPath + '.pending', this.stateRoot);
+        this.before = new Map(Object.values(registry.projects).flatMap((p) => p.entries.map((e) => [key(e.repoRoot), JSON.stringify({ folder: p.folder, entry: e })])));
+    }
+}
+function key(path) {
+    return process.platform === 'win32' ? resolve(path).toLowerCase() : resolve(path);
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function refuse(message) {
+    return new BridgeRecoveryError(message, 'worktree.reconcile');
+}
+//# sourceMappingURL=worktree-pool.js.map