engineering-memory 1.11.9 → 1.11.11

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

@@ -39,6 +39,9 @@ const allocationSchema = z.object({
     reason: z.string().optional(),
     root: z.string().optional(),
     layout: z.union([z.literal(1), z.literal(2)]).optional(),
+    deliveryOutcome: z.enum(['delivered', 'cancelled']).optional(),
+    cancelledAt: z.string().optional(),
+    preservedRef: z.string().optional(),
 });
 const registrySchema = z.object({
     schemaVersion: z.literal(1),
@@ -149,11 +152,11 @@ export class WorktreePool {
                     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.');
+                const holder = entry && entry.phase !== 'released'
+                    ? entry.externalTaskId
+                    : (await this.git.branchStore(root).read())?.decision.externalTaskId;
+                if (holder && holder !== input.externalTaskId)
+                    throw new BridgeRecoveryError(`Task ${holder} holds this checkout. Continue that task, or call task.branch with a new decisionAttempt and choose a new branch: its question offers a separate worktree, and this folder too when it is clean and ${holder} can move out.`, 'task.branch');
                 entry = await this.entry(input, commonDir, root, null, false);
                 project.entries = project.entries.filter((e) => key(e.repoRoot) !== key(root));
                 project.entries.push(entry);
@@ -176,11 +179,41 @@ export class WorktreePool {
             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.');
+            if (input.inPlace) {
+                const root = await this.git.findRoot(input.repoRoot);
+                const held = project.entries.find((e) => key(e.repoRoot) === key(root) && e.phase !== 'released');
+                if (held)
+                    throw new BridgeRecoveryError(`Task ${held.externalTaskId} still holds this folder in the worktree pool. Call task.branch with a new decisionAttempt and open the new task in a separate worktree; the folder stayed on its branch.`, 'task.branch');
+                entry = await this.entry(input, commonDir, root, null, false);
+                const reasons = await this.fileProtection(entry, true);
+                if (reasons.length)
+                    throw new BridgeRecoveryError('A new branch cannot start in this folder: ' +
+                        reasons.join(', ') +
+                        '. Call task.branch with a new decisionAttempt and open the task in a separate worktree; the folder stayed on its branch.', 'task.branch');
+                project.entries = project.entries.filter((e) => key(e.repoRoot) !== key(root));
+                project.entries.push(entry);
+                await this.save(registry);
+                await this.reserve(entry);
+                try {
+                    await this.checkout(entry);
+                }
+                catch {
+                    await this.git.branchStore(root).cancelUnopened(entry.projectId, entry.externalTaskId);
+                    project.entries = project.entries.filter((e) => e !== entry);
+                    await this.save(registry);
+                    throw new BridgeRecoveryError('Git could not switch this folder to the new branch, so the folder was left as it was. Call task.branch with a new decisionAttempt and open the task in a separate worktree.', 'task.branch');
+                }
+                entry.phase = 'working';
+                await this.save(registry);
+                return structuredClone(entry);
+            }
             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 && key(e.root ?? legacyRoot) === activeRoot)
+                .filter((e) => e.managed &&
+                e.commonDir === commonDir &&
+                !this.outsideActiveRoot(e, activeRoot, legacyRoot))
                 .sort((a, b) => a.slot - b.slot)) {
                 if (candidate.pendingDelivery ||
                     ['creating', 'quarantined'].includes(candidate.phase) ||
@@ -204,13 +237,14 @@ export class WorktreePool {
                 await this.checkout(entry);
             }
             else {
-                if (project.entries.filter((e) => e.managed).length >= policy.maxWorktrees)
+                if (project.entries.filter((e) => e.managed &&
+                    !(e.phase === 'released' && this.outsideActiveRoot(e, activeRoot, legacyRoot))).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 active = await this.documentsDirectory();
                 const root = projectDirectory(active, project.folder, 2);
                 await ensureManagedDirectory(active, root);
-                while (project.entries.some((e) => e.slot === slot) ||
+                while (project.entries.some((e) => e.slot === slot && (e.layout ?? 1) === 2 && key(e.root ?? legacyRoot) === activeRoot) ||
                     (await pathExists(join(root, worktreeName(project.folder, slot, 2)))))
                     slot++;
                 const path = join(root, worktreeName(project.folder, slot, 2));
@@ -249,6 +283,10 @@ export class WorktreePool {
         return this.transaction(async (registry) => structuredClone(registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot)) ??
             null));
     }
+    async forSlug(projectId, externalTaskId) {
+        return this.transaction(async (registry) => structuredClone(registry.projects[projectId]?.entries.find((e) => e.externalTaskId === externalTaskId) ??
+            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));
@@ -311,24 +349,146 @@ export class WorktreePool {
             await this.save(registry);
         });
     }
-    async release(projectId, repoRoot, generation, delivered) {
+    async release(projectId, repoRoot, generation, deliveryOutcome) {
         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();
+            const entry = await this.deliveryOwned(registry, projectId, repoRoot, generation);
+            if (entry.pendingDelivery && !deliveryOutcome)
+                throw new BridgeRecoveryError('Delivery is pending. Ask the user whether it was delivered, then call worktree.release with deliveryOutcome delivered, or cancelled when they decided not to deliver.', 'worktree.release');
+            if (entry.managed) {
+                const reasons = await this.fileProtection(entry);
+                if (reasons.length)
+                    throw protectedRefusal(reasons, 'Finish the work, or when the user decided not to deliver it call worktree.release with deliveryOutcome cancelled to save the changes before release.');
+            }
+            if (deliveryOutcome)
+                entry.deliveryOutcome = deliveryOutcome;
+            await this.releaseEntry(registry, entry);
+        });
+    }
+    async cancelDelivery(projectId, repoRoot, generation, choice) {
+        return this.transaction(async (registry) => {
+            const entry = await this.deliveryOwned(registry, projectId, repoRoot, generation);
+            if (!entry.pendingDelivery)
+                throw new BridgeRecoveryError('This worktree is not waiting for delivery, so there is no delivery to cancel. Release it with worktree.release.', 'worktree.release');
+            if (choice === 'keep') {
+                entry.deliveryOutcome = 'cancelled';
+                entry.cancelledAt = new Date(this.now()).toISOString();
+                entry.phase = 'paused';
+                entry.pendingDelivery = false;
+                entry.owner = null;
+                entry.generation = randomUUID();
+                await this.save(registry);
+                return { choice };
+            }
+            let preservedRef;
+            if (entry.managed) {
+                const reasons = (await this.fileProtection(entry)).filter((reason) => choice !== 'save_and_release' || reason !== changedFiles);
+                if (reasons.length)
+                    throw protectedRefusal(reasons, 'Nothing in the folder was changed. Once that is settled call worktree.release with deliveryOutcome cancelled again; it asks about the folder as it is now, and keeping the folder is always possible.');
+                if (choice === 'save_and_release') {
+                    const saved = await this.snapshot(entry);
+                    preservedRef = entry.preservedRef = saved.ref;
+                    await this.save(registry);
+                    await this.cleanSnapshot(entry, saved);
+                }
+            }
+            entry.deliveryOutcome = 'cancelled';
+            entry.cancelledAt = new Date(this.now()).toISOString();
+            await this.releaseEntry(registry, entry);
+            return preservedRef
+                ? { choice, preservedRef, restoreCommand: restoreCommand(preservedRef) }
+                : { choice };
+        });
+    }
+    async ownedElsewhere(entry) {
+        return Boolean(entry.owner && entry.owner.id !== this.ownerId && (await this.ownerAlive(entry.owner)));
+    }
+    async moveOut(projectId, repoRoot, generation, oid) {
+        await this.transaction(async (registry) => {
+            const project = registry.projects[projectId];
+            const entry = project?.entries.find((e) => key(e.repoRoot) === key(repoRoot));
+            if (!project ||
+                !entry ||
+                entry.managed ||
+                entry.phase === 'released' ||
+                entry.generation !== generation)
+                throw new BridgeRecoveryError('The task recorded in this folder changed after it was looked at. Call task.branch again; its question shows which task holds the folder now.', 'task.branch');
+            if (await this.ownedElsewhere(entry))
+                throw new BridgeRecoveryError(`Task ${entry.externalTaskId} is still running in another client in this folder. Pause it there with task.pause, or call task.branch again and open the new task in a separate worktree; the folder was left as it is.`, 'task.branch');
+            if (entry.pendingDelivery)
+                throw new BridgeRecoveryError(`Task ${entry.externalTaskId} closed with delivery still pending in this folder. Resume it here and call worktree.release with deliveryOutcome delivered or cancelled to settle it, or call task.branch again and open the new task in a separate worktree; the folder was left as it is.`, 'worktree.release');
+            if (oid)
+                await this.git.branchStore(entry.repoRoot).detach({
+                    projectId,
+                    externalTaskId: entry.externalTaskId,
+                    branch: entry.branch,
+                    ...(entry.taskId ? { taskId: entry.taskId } : {}),
+                }, oid);
+            else
+                await this.releaseReservation(entry);
+            project.entries = project.entries.filter((e) => e !== entry);
             await this.save(registry);
         });
     }
+    async retire(projectId, repoRoot, path, generation) {
+        const commonDir = await this.commonDirectory(repoRoot);
+        const activeRoot = key(await this.documentsDirectory());
+        const legacyRoot = await this.legacyDocumentsDirectory();
+        await this.transaction(async (registry) => {
+            const project = registry.projects[projectId];
+            const entry = project?.entries.find((e) => key(e.repoRoot) === key(path));
+            if (!project ||
+                !entry ||
+                entry.generation !== generation ||
+                entry.phase !== 'released' ||
+                entry.commonDir !== commonDir ||
+                !this.outsideActiveRoot(entry, activeRoot, legacyRoot))
+                throw refuse('This folder is no longer the same retired slot. List the worktrees again before removing it.');
+            if (await pathExists(entry.repoRoot)) {
+                const reasons = await this.fileProtection(entry);
+                if (reasons.length)
+                    throw refuse('The retired folder is protected: ' +
+                        reasons.join(', ') +
+                        '. It stays listed as retired and is never reused; nothing was removed.');
+                const removed = await this.runner.run('git', ['worktree', 'remove', entry.repoRoot], {
+                    cwd: repoRoot,
+                });
+                if (removed.exitCode !== 0)
+                    throw refuse('Git refused to remove the retired folder: ' +
+                        removed.stderr.trim() +
+                        '. It stays listed as retired and is never reused; nothing was removed.');
+            }
+            project.entries = project.entries.filter((e) => e !== entry);
+            await this.save(registry);
+        });
+    }
+    async forgetUnreadable(projectId, externalTaskId, generation) {
+        return this.transaction(async (registry) => {
+            const project = registry.projects[projectId];
+            const entry = project?.entries.find((e) => e.externalTaskId === externalTaskId && e.generation === generation);
+            if (!project || !entry)
+                throw refuse('This is no longer the same registry entry for that task. List the checkouts again with worktree.list before forgetting one.');
+            if (await this.ownedElsewhere(entry))
+                throw refuse('Another live client still owns this task. Stop or pause it there first; worktree.list shows the checkout meanwhile.');
+            if (!(await this.unreadable(entry)))
+                throw new BridgeRecoveryError('This checkout can still be read as a Git worktree, so it is not forgotten. Settle its delivery and free it with worktree.release.', 'worktree.release');
+            project.entries = project.entries.filter((e) => e !== entry);
+            await this.save(registry);
+            return structuredClone(entry);
+        });
+    }
+    async unreadable(entry) {
+        if (!(await pathExists(entry.repoRoot)))
+            return true;
+        try {
+            if (key(await this.git.findRoot(entry.repoRoot)) !== key(await canonicalPath(entry.repoRoot)))
+                return true;
+            await this.commonDirectory(entry.repoRoot);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    }
     async releaseUnowned(projectId, repoRoot, generation, sourceCommit) {
         await this.transaction(async (registry) => {
             const entry = registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot));
@@ -400,6 +560,9 @@ export class WorktreePool {
             if (!recoveredProject)
                 return;
             project = recoveredProject;
+            const activeRootKey = key(await this.documentsDirectory());
+            const legacyRootDir = await this.legacyDocumentsDirectory();
+            await this.preloadOwnerStarts(project.entries.filter((entry) => entry.owner).map((entry) => entry.owner.pid));
             for (const entry of project.entries.filter((e) => !discoverOnly && e.commonDir === commonDir)) {
                 if (entry.owner && entry.owner.id !== this.ownerId && (await this.ownerAlive(entry.owner)))
                     continue;
@@ -456,6 +619,9 @@ export class WorktreePool {
             for (const entry of project.entries.filter((e) => !discoverOnly && e.commonDir === commonDir)) {
                 if (entry.owner && (await this.ownerAlive(entry.owner)) && entry.owner.id !== this.ownerId)
                     continue;
+                if (entry.phase === 'released' &&
+                    this.outsideActiveRoot(entry, activeRootKey, legacyRootDir))
+                    continue;
                 try {
                     if (entry.recoveredWithoutReservation &&
                         !entry.owner &&
@@ -548,6 +714,105 @@ export class WorktreePool {
             throw refuse('Worktree ownership has changed or was paused. Resume the task and use its returned repoRoot before any further write.');
         return entry;
     }
+    async deliveryOwned(registry, projectId, repoRoot, generation) {
+        const entry = registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot));
+        if (!entry ||
+            entry.phase !== 'delivery' ||
+            entry.generation !== generation ||
+            entry.owner?.id === this.ownerId)
+            return this.owned(registry, projectId, repoRoot, generation);
+        await this.requireTakeover(entry);
+        await this.assertIdentity(entry);
+        entry.owner = {
+            id: this.ownerId,
+            pid: process.pid,
+            generation,
+            ...((await this.ownerStart()) ? { startedAt: (await this.ownerStart()) } : {}),
+        };
+        return entry;
+    }
+    async releaseEntry(registry, entry) {
+        await this.releaseReservation(entry);
+        if (entry.managed) {
+            entry.pendingDelivery = false;
+            entry.phase = 'released';
+            entry.owner = null;
+            entry.generation = randomUUID();
+        }
+        else {
+            const project = registry.projects[entry.projectId];
+            project.entries = project.entries.filter((e) => e !== entry);
+        }
+        await this.save(registry);
+    }
+    async snapshot(entry) {
+        const gitDir = await this.command(entry.repoRoot, ['rev-parse', '--absolute-git-dir']);
+        const saved = 'refs/engineering-memory/preserved/' +
+            entry.externalTaskId.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+/, '') +
+            '/' +
+            entry.generation;
+        let ref = saved;
+        for (let attempt = 2; (await this.runner.run('git', ['rev-parse', '--verify', '--quiet', ref], {
+            cwd: entry.repoRoot,
+        })).exitCode === 0; attempt++)
+            ref = saved + '-' + attempt;
+        const index = join(gitDir, 'engineering-memory-preserve-' + randomUUID());
+        const env = {
+            GIT_INDEX_FILE: index,
+            GIT_AUTHOR_NAME: 'Engineering Memory',
+            GIT_AUTHOR_EMAIL: 'engineering-memory@example.invalid',
+            GIT_COMMITTER_NAME: 'Engineering Memory',
+            GIT_COMMITTER_EMAIL: 'engineering-memory@example.invalid',
+        };
+        const git = async (args, options = {}) => {
+            const result = await this.runner.run('git', args, { cwd: entry.repoRoot, ...options });
+            if (result.exitCode !== 0)
+                throw new BridgeRecoveryError('The changes could not be saved (' +
+                    (result.stderr.trim() || 'git ' + args[0]) +
+                    '). The folder was left as it was: keep it, or fix the Git error and call worktree.release with deliveryOutcome cancelled again.', 'worktree.release');
+            return result.stdout;
+        };
+        let untracked;
+        try {
+            await git(['read-tree', 'HEAD'], { env });
+            await git(['add', '-A', '--', '.'], { env });
+            const tree = (await git(['write-tree'], { env })).trim();
+            const commit = (await git([
+                'commit-tree',
+                tree,
+                '-p',
+                'HEAD',
+                '-m',
+                'Changes kept when delivery of ' + entry.externalTaskId + ' was cancelled',
+            ], { env })).trim();
+            await git(['diff', '--quiet', commit, '--'], { env });
+            untracked = (await git(['ls-files', '--others', '--exclude-standard', '-z']))
+                .split('\0')
+                .filter(Boolean);
+            const snapshot = new Set((await git(['ls-tree', '-r', '--name-only', '-z', commit])).split('\0').filter(Boolean));
+            if (untracked.some((path) => !snapshot.has(path)))
+                throw new BridgeRecoveryError('Not every untracked file reached the saved changes. Keep the folder; nothing was changed.', 'worktree.release');
+            await git(['update-ref', ref, commit, '0'.repeat(commit.length)]);
+        }
+        finally {
+            await removeFile(index);
+        }
+        return { ref, untracked };
+    }
+    async cleanSnapshot(entry, saved) {
+        const refused = (problem) => new BridgeRecoveryError(`The changes are saved in ${saved.ref}, but ${problem}. Nothing is lost: \`${restoreCommand(saved.ref)}\` brings them back. Call worktree.release with deliveryOutcome cancelled again; it asks about the folder as it is now.`, 'worktree.release');
+        const clean = async (args) => {
+            const result = await this.runner.run('git', args, { cwd: entry.repoRoot });
+            if (result.exitCode !== 0)
+                throw refused(`Git could not clean the folder (${result.stderr.trim() || 'git ' + args[0]})`);
+        };
+        await clean(['restore', '--source=HEAD', '--staged', '--worktree', '--', '.']);
+        for (let i = 0; i < saved.untracked.length; i += 100)
+            await clean(['clean', '-f', '-d', '--', ...saved.untracked.slice(i, i + 100)]);
+        const reasons = await this.fileProtection(entry);
+        if (reasons.length)
+            throw refused('the folder is still protected: ' + reasons.join(', '));
+    }
     async reserve(entry) {
         await this.git.branchStore(entry.repoRoot).reserve({
             projectId: entry.projectId,
@@ -599,12 +864,12 @@ export class WorktreePool {
     }
     async fileProtection(entry, allowBranchChange = false) {
         if (!(await pathExists(entry.repoRoot)))
-            return ['worktree directory missing'];
+            return [missingDirectory];
         try {
             await this.assertIdentity(entry, allowBranchChange);
         }
         catch {
-            return ['Git identity or reservation changed or unreadable; reconcile this checkout'];
+            return [(await this.unreadable(entry)) ? unreadableGit : changedIdentity];
         }
         const status = await this.runner.run('git', ['status', '--porcelain=v1', '--untracked-files=all'], { cwd: entry.repoRoot });
         const reasons = [];
@@ -614,9 +879,9 @@ export class WorktreePool {
                 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');
+            reasons.push(pendingTaskWork);
         if (status.exitCode !== 0 || status.stdout.trim())
-            reasons.push('uncommitted, staged or untracked files');
+            reasons.push(changedFiles);
         const gitDir = await this.command(entry.repoRoot, ['rev-parse', '--absolute-git-dir']);
         for (const marker of [
             'MERGE_HEAD',
@@ -632,12 +897,32 @@ export class WorktreePool {
                 reasons.push('unfinished Git operation: ' + marker);
         return reasons;
     }
+    outsideActiveRoot(entry, activeRoot, legacyRoot) {
+        return entry.managed && key(entry.root ?? legacyRoot) !== activeRoot;
+    }
     async view(entry, policy) {
+        const activeRoot = await this.documentsDirectory();
+        const outside = this.outsideActiveRoot(entry, key(activeRoot), await this.legacyDocumentsDirectory());
+        if (outside && entry.phase === 'released')
+            return {
+                ...structuredClone(entry),
+                activity: 'retired',
+                reasons: [
+                    'outside the managed root ' + managedBase(activeRoot, 2) + '; not reused',
+                    ...((await pathExists(entry.repoRoot)) ? [] : [missingDirectory]),
+                ],
+            };
         const reasons = await this.fileProtection(entry);
+        if (outside)
+            reasons.push('legacy location: retires after its current task');
+        if (!entry.managed && entry.phase !== 'released')
+            reasons.push('the user’s own folder: the pool never reuses it');
         if (entry.phase === 'creating' || entry.phase === 'quarantined')
             reasons.push(entry.reason ?? 'allocation requires reconciliation');
         if (entry.pendingDelivery)
             reasons.push('delivery pending');
+        if (entry.deliveryOutcome === 'cancelled' && reasons.includes(changedFiles))
+            reasons.push('changes kept after cancelled delivery');
         if (entry.owner && (await this.ownerAlive(entry.owner)))
             reasons.push('owner process still running');
         const age = this.now() - entry.lastActivityAt;
@@ -707,6 +992,53 @@ export class WorktreePool {
         }
         return !current || current === owner.startedAt;
     }
+    async preloadOwnerStarts(pids) {
+        const now = Date.now();
+        const candidates = [...new Set(pids)].filter((pid) => {
+            if (!Number.isSafeInteger(pid) || pid <= 0 || !this.alive(pid))
+                return false;
+            const cached = this.startTimes.get(pid);
+            const age = cached ? now - cached.checkedAt : Infinity;
+            return !cached || age < 0 || age > 15000;
+        });
+        if (!candidates.length || process.platform === 'linux')
+            return;
+        const found = new Map();
+        try {
+            if (process.platform === 'win32') {
+                const result = await this.runner.run('powershell.exe', [
+                    '-NoProfile',
+                    '-NonInteractive',
+                    '-Command',
+                    'Get-Process -Id ' +
+                        candidates.join(',') +
+                        ' -ErrorAction SilentlyContinue | ForEach-Object { "$($_.Id)=$($_.StartTime.ToUniversalTime().Ticks)" }',
+                ], {});
+                if (result.exitCode === 0) {
+                    for (const line of result.stdout.split(/\r?\n/)) {
+                        const match = /^(\d+)=(\d+)$/.exec(line.trim());
+                        if (match)
+                            found.set(Number(match[1]), match[2]);
+                    }
+                }
+            }
+            else {
+                const result = await this.runner.run('ps', ['-o', 'pid=,lstart=', '-p', candidates.join(',')], {});
+                if (result.exitCode === 0) {
+                    for (const line of result.stdout.split(/\r?\n/)) {
+                        const match = /^\s*(\d+)\s+(.+)$/.exec(line.replace(/\r$/, ''));
+                        if (match)
+                            found.set(Number(match[1]), match[2].trim());
+                    }
+                }
+            }
+        }
+        catch {
+            return;
+        }
+        for (const pid of candidates)
+            this.startTimes.set(pid, { checkedAt: now, value: found.get(pid) ?? null });
+    }
     async processStart(pid) {
         if (!Number.isSafeInteger(pid) || pid <= 0)
             return null;
@@ -1012,6 +1344,22 @@ function processAlive(pid) {
         return error.code === 'EPERM';
     }
 }
+const changedFiles = 'uncommitted, staged or untracked files';
+const pendingTaskWork = 'task delivery or intent pending';
+const missingDirectory = 'worktree directory missing';
+const changedIdentity = 'Git identity or reservation changed; reconcile this checkout';
+const unreadableGit = 'Git metadata missing or unreadable; this folder is no longer a checkout';
+export function unreadableWorktree(view) {
+    return view.reasons.includes(missingDirectory) || view.reasons.includes(unreadableGit);
+}
+function protectedRefusal(reasons, next) {
+    if (reasons.every((reason) => reason === pendingTaskWork))
+        return new BridgeRecoveryError('Engineering Memory still holds an undelivered record for this task: a checkpoint, correction or close waiting in its local outbox, or an unfinished verification or close. The folder was left as it is. Settle it with task.resolve_pending_delivery (session.resume finishes an interrupted verification or close), then call worktree.release again.', 'task.resolve_pending_delivery');
+    return new BridgeRecoveryError('The worktree is protected: ' + reasons.join(', ') + '. ' + next, 'worktree.release');
+}
+function restoreCommand(ref) {
+    return `git restore --source=${ref} --worktree -- .`;
+}
 function refuse(message) {
     return new BridgeRecoveryError(message, 'worktree.reconcile');
 }

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

@@ -4,6 +4,7 @@ export class NativeCommandRunner {
         return await new Promise((resolvePromise, reject) => {
             const child = spawn(command, args, {
                 cwd: options.cwd,
+                ...(options.env ? { env: { ...process.env, ...options.env } } : {}),
                 shell: false,
                 windowsHide: true,
                 stdio: ['pipe', 'pipe', 'pipe'],

package/skill/SKILL.md

@@ -25,9 +25,9 @@ Do not block independent task work on `memory.propose_revision` drafting, submis
 6. Use the returned context pack as the engineering authority for the task. Use `memory.query` only for targeted missing context, and `memory.history` to read why the records you are changing became what they are before you design against them.
 7. Record phase, correction, validation, and handoff checkpoints at the required moments. Declare the task's discretionary decisions on the validation-before checkpoint, and when a task repeats a shape, have the first unit reviewed before writing the rest.
 8. For a write task, reconcile every changed screen and component. Propose revisions when semantics changed; otherwise record an explicit no-semantic-memory-change reconciliation.
-9. Before validation, read the changed code back against the rules that govern it and record `task.self_review`. Verification refuses without a review of the current diff, and any later edit requires reviewing again.
-10. Run `task.verify` before claiming completion. Write tasks verify the exact Git diff, active lease, and structured command-bound validation evidence. Read-only tasks verify that the current Git diff hash still equals the baseline captured at bootstrap, plus the required discovery, validation, handoff, pinned-context, and synchronization evidence. Run `task.close` only after verification succeeds. The pre-commit gate must confirm the closed task online; a local verification receipt is insufficient.
-11. After closing a task, ask the delivery question every time — commit, commit and push, or either of those with a draft or ready pull request onto a base branch the user names — and do only what they choose. Once a pull request exists, check whether it merges cleanly and ask before resolving a conflict.
+9. Before validation, read each changed file back against the rules `context.prepare_change` returned for it in `governingRules`, and record `task.self_review` with one entry per changed file naming each of those rules as `follows`, `fixed` or `user_accepted_deviation`. A deviation counts only after the user approves it in the rule-deviation question the bridge asks; matching existing code is not an outcome. Verification refuses without a review of the current diff, and any later edit requires reviewing again.
+10. Run `task.verify` before claiming completion. Write tasks verify the exact Git diff, active lease, and structured command-bound validation evidence. Read-only tasks verify that the current Git diff hash still equals the baseline captured at bootstrap, plus the required discovery, validation, handoff, pinned-context, and synchronization evidence. Run `task.close` only after verification succeeds. Where the pre-commit hook was installed, it confirms the closed task online; a local verification receipt is insufficient. Without the hook nothing checks the commit, so never claim a hook confirmed closure.
+11. After closing a task, settle the delivery question — commit, commit and push, or either of those with a draft or ready pull request onto a base branch the user names — naming the branch, remote and URL the close returned, and do only what they choose. A choice the user already made in their own message is the answer; do not ask it again. When the host's reviewer denies a push or pull request they chose, never use an Engineering Memory form or a typed phrase to get past it; follow the Delivery section of questionnaires.md. Once a pull request exists, check whether it merges cleanly and ask before resolving a conflict.
 12. Never commit, push, publish, deploy, approve a permanent memory revision, or overwrite an existing Git hook without explicit user authorization.
 13. Never store tokens, passwords, client secrets, raw headers, raw payloads, customer data, or PII in tool inputs, journals, memory, logs, or generated documentation.