engineering-memory 1.11.22 → 1.11.23

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

@@ -12,6 +12,7 @@ import { BridgeRecoveryError } from './recovery-error.js';
 import { planWorktreeFiles, ignoredRuntimeFiles, createWorktreeStage, stageWorktreeFiles, publishWorktreeFiles, discardStagedWorktreeFiles, } from './worktree-preparation.js';
 import { WorktreeFileIssue, WorktreeFileStatus, } from './worktree-readiness-types.js';
 import { openWorktreeInEditor, WorktreeEditorStatus } from './worktree-editor.js';
+const cancelReasons = { keep: 'kept', release: 'released', save_and_release: 'saved' };
 const allocationSchema = z.object({
     projectId: z.string().min(1),
     repoFingerprint: z.string().regex(/^[a-f0-9]{64}$/),
@@ -125,6 +126,7 @@ export class WorktreePool {
     overrideProblem;
     before = new Map();
     pendingWork;
+    onDeliveryOutcome;
     constructor(stateRoot, options = {}) {
         this.stateRoot = stateRoot;
         this.ownerId = options.ownerId ?? randomUUID();
@@ -135,6 +137,7 @@ export class WorktreePool {
         this.documents = options.documentsRoot;
         this.legacyDocuments = options.legacyDocumentsRoot ?? options.documentsRoot;
         this.pendingWork = options.pendingWork ?? (async () => false);
+        this.onDeliveryOutcome = options.onDeliveryOutcome ?? (async () => undefined);
         this.registryPath = join(stateRoot, 'worktree-pool.json');
     }
     async allocate(input, policy) {
@@ -220,11 +223,34 @@ export class WorktreePool {
                 (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)))
+            await this.settleDelivered(registry, project.entries);
+            if (!input.resume &&
+                !input.continued &&
+                (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.');
+            const alreadyHere = input.continued &&
+                input.inPlace &&
+                checkout &&
+                key(checkout.path) === key(await this.git.findRoot(input.repoRoot));
+            const holding = checkout && input.continued && !alreadyHere
+                ? project.entries.find((e) => e.managed &&
+                    e.phase === 'released' &&
+                    e.commonDir === commonDir &&
+                    key(e.repoRoot) === key(checkout.path))
+                : undefined;
+            if (checkout && !holding && !alreadyHere)
+                throw refuse(input.continued
+                    ? `Branch ${input.branch} is checked out in ${checkout.path}. Continue the task that works there, or free that folder, then call task.branch with a new decisionAttempt.`
+                    : 'This branch already has a checkout. Resume its task instead of creating or resetting the branch.');
+            if (holding) {
+                const view = await this.view(holding, policy);
+                if (view.activity !== 'available')
+                    throw refuse(`Branch ${input.branch} is checked out in the released folder ${holding.repoRoot}, which is not free (${view.reasons.join(', ')}). Settle that folder, then call task.branch with a new decisionAttempt.`);
+                await this.command(holding.repoRoot, ['switch', '--detach']);
+            }
+            if (input.continued && !alreadyHere)
+                await this.moveBranch(input.repoRoot, input.branch, input.baseCommit);
             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');
@@ -241,37 +267,44 @@ export class WorktreePool {
                 await this.save(registry);
                 await this.reserve(entry);
                 try {
+                    if (alreadyHere)
+                        await this.command(root, [
+                            'merge',
+                            '--ff-only',
+                            '--no-overwrite-ignore',
+                            input.baseCommit,
+                        ]);
                     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');
+                    throw new BridgeRecoveryError('Git could not switch this folder to the task 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);
             }
-            await this.settleDelivered(registry, project.entries);
-            let reusable;
+            let reusable = holding;
             const activeRoot = key(await this.documentsDirectory());
             const legacyRoot = await this.legacyDocumentsDirectory();
-            for (const candidate of project.entries
-                .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) ||
-                    (candidate.owner && (await this.ownerAlive(candidate.owner))))
-                    continue;
-                const view = await this.view(candidate, policy);
-                if (view.activity === 'available') {
-                    reusable = candidate;
-                    break;
+            if (!reusable)
+                for (const candidate of project.entries
+                    .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) ||
+                        (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);
@@ -565,9 +598,20 @@ export class WorktreePool {
                 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.');
             }
+            const taskId = deliveryOutcome && entry.pendingDelivery ? entry.taskId : undefined;
+            const head = taskId && (await this.git.sourceIdentity(entry.repoRoot))?.sourceCommit;
+            const pushed = Boolean(head && (await this.git.remoteRefContaining(entry.repoRoot, head)));
             if (deliveryOutcome)
                 entry.deliveryOutcome = deliveryOutcome;
             await this.releaseEntry(registry, entry);
+            if (taskId && head && head !== entry.baseCommit)
+                await this.onDeliveryOutcome({
+                    projectId,
+                    taskId,
+                    outcome: 'delivered',
+                    commit: head,
+                    pushed,
+                }).catch(() => undefined);
         });
     }
     async cancelDelivery(projectId, repoRoot, generation, choice) {
@@ -575,6 +619,16 @@ export class WorktreePool {
             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');
+            const taskId = entry.taskId;
+            const report = async () => {
+                if (taskId)
+                    await this.onDeliveryOutcome({
+                        projectId,
+                        taskId,
+                        outcome: 'cancelled',
+                        reason: cancelReasons[choice],
+                    }).catch(() => undefined);
+            };
             if (choice === 'keep') {
                 entry.deliveryOutcome = 'cancelled';
                 entry.cancelledAt = new Date(this.now()).toISOString();
@@ -583,6 +637,7 @@ export class WorktreePool {
                 entry.owner = null;
                 entry.generation = randomUUID();
                 await this.save(registry);
+                await report();
                 return { choice };
             }
             let preservedRef;
@@ -600,6 +655,7 @@ export class WorktreePool {
             entry.deliveryOutcome = 'cancelled';
             entry.cancelledAt = new Date(this.now()).toISOString();
             await this.releaseEntry(registry, entry);
+            await report();
             return preservedRef
                 ? { choice, preservedRef, restoreCommand: restoreCommand(preservedRef) }
                 : { choice };
@@ -968,6 +1024,14 @@ export class WorktreePool {
             entry.deliveredCommit = head;
             entry.deliveredRef = ref;
             await this.releaseEntry(registry, entry);
+            if (entry.taskId)
+                await this.onDeliveryOutcome({
+                    projectId: entry.projectId,
+                    taskId: entry.taskId,
+                    outcome: 'delivered',
+                    commit: head,
+                    pushed: true,
+                }).catch(() => undefined);
         }
     }
     async releaseEntry(registry, entry) {
@@ -1076,6 +1140,19 @@ export class WorktreePool {
         if (result.exitCode !== 0)
             throw refuse('Git could not select the task branch. Reconcile the interrupted allocation; no reset was attempted.');
     }
+    async moveBranch(repoRoot, branch, commit) {
+        const current = await this.git.sourceIdentity(repoRoot, 'refs/heads/' + branch);
+        if (current?.sourceCommit === commit)
+            return;
+        const result = await this.runner.run('git', [
+            'update-ref',
+            'refs/heads/' + branch,
+            commit,
+            current?.sourceCommit ?? '0'.repeat(commit.length),
+        ], { cwd: repoRoot });
+        if (result.exitCode !== 0)
+            throw refuse(`Git could not bring branch ${branch} to its newest commit. Call task.branch with a new decisionAttempt; nothing was allocated.`);
+    }
     async repairCreating(entry) {
         if (entry.phase !== 'creating' || !(await pathExists(entry.repoRoot)))
             return;

package/skill/references/lifecycle.md

@@ -40,7 +40,7 @@ Renew `task.heartbeat` using the exact returned task, path and ownership generat
 
 Use `task.pause` when work stops or is handed to another client. It preserves task state and files, invalidates the old owner, and allows safe clean directories to be reused. It is not `task.abandon`. Resume reacquires the original directory when possible or uses the retained task branch in another safe directory. `worktree.reconcile` recovers interrupted allocation and validated local ownership records against Git. Never edit the registry, force checkout, stash/reset/clean, remove branches, kill a client or delete a worktree to bypass a refusal.
 
-`task.close` retains a managed checkout while changes or delivery remain pending. After delivery, release with `deliveryOutcome:'delivered'` and the current generation. Once the task's commits are on a remote branch the pool settles the folder by itself; `worktree.release` then answers `alreadyReleased`, `session.resume` of the closed task answers `folderReleased`, and nothing further is needed. When the user decides not to deliver, call `worktree.release` with `deliveryOutcome:'cancelled'`; the product asks what happens to the folder and saves any changes to a ref. Never run `git restore` or `git clean` yourself to free a worktree, and never report a delivery that did not happen. Dirty/staged/untracked files, pending outbox/intents and unfinished Git operations prevent release. An old release cannot affect a reused directory. User-owned existing directories are never added to automatic cleanup. When the user wants to work in the main folder, they answer that in `task.branch`'s start form; when an open task holds the folder, that option names the task that would move out. A closed or abandoned task stops holding the folder by itself; a task still running in another client keeps it until it is paused there. Never edit or delete the reservation ref by hand.
+`task.close` retains a managed checkout while changes or delivery remain pending. After delivery, release with `deliveryOutcome:'delivered'` and the current generation; that release publishes the task's source memory first and reports it as `sourcePublication`. A skipped publication names its reason and never undoes the delivery. Once the task's commits are on a remote branch the pool settles the folder by itself; `worktree.release` then answers `alreadyReleased`, `session.resume` of the closed task answers `folderReleased`, and nothing further is needed. When the user decides not to deliver, call `worktree.release` with `deliveryOutcome:'cancelled'`; the product asks what happens to the folder and saves any changes to a ref. Never run `git restore` or `git clean` yourself to free a worktree, and never report a delivery that did not happen. Dirty/staged/untracked files, pending outbox/intents and unfinished Git operations prevent release. An old release cannot affect a reused directory. User-owned existing directories are never added to automatic cleanup. When the user wants to work in the main folder, they answer that in `task.branch`'s start form; when an open task holds the folder, that option names the task that would move out. A closed or abandoned task stops holding the folder by itself; a task still running in another client keeps it until it is paused there. Never edit or delete the reservation ref by hand.
 
 Read-only tasks allocate no worktree. If the user authorizes writing, settle `task.branch` for that same externalTaskId, use the allocated repoRoot, then call `context.prepare_change` with `transitionToWrite`. Its pinned source must still match; choosing a different source requires a new task, never rewriting the original task's source identity. Existing lease, discipline, source-memory, verify and commit gates remain mandatory.
 
@@ -91,6 +91,27 @@ The catalogue returns `items`, `total`, `offset` and `limit`. Page with `offset`
 
 Session entry uses the backend's actionable selection. An empty page remains empty, and a failed lookup offers no work items; never retry an unfiltered list to classify statuses locally. Reuse existing user choices. Any unresolved workflow choice must use the native questionnaire.
 
+### Starting work on a work item
+
+When a write task starts on a work item — `session.bootstrap` in write or scaffold mode, or `context.prepare_change` with `transitionToWrite` — the project's rule for the "work started" event is applied and the response carries `workStarted`. Its `nextAction` is written for you; relay it in the user's language:
+
+- `moved`: say in one line which stage the item moved from and to, for example that KAN-12 moved from Todo to InProgress.
+- `confirmation_required`: the project asks before this move. Ask the user with the native questionnaire under the task's decision mode; when they agree, call `work_item.update` with the given status slug and `expectedVersion`. A refusal for a changed version means someone moved the item meanwhile: read it again rather than retrying.
+- `unchanged` with `target_meaning_missing`: the target stage has no written meaning, and Engineering Memory never moves work into a stage it cannot explain. Mention it once; an owner can describe the stage with `work_item.describe_status`.
+- `unchanged` for any other reason: the item was already there, is past the start, or the project ignores the event. Say nothing unless asked.
+
+Only work waiting to be started moves: a stage of the new category, or the stage the project sends failed tests to. Work in progress, review, QA, parked or done is never moved back.
+
+### Work item comments
+
+Work that came back from testing carries the reason as a comment. Read `work_item.comments` before starting a round on it. A tester, product manager or developer writes a reason with `work_item.comment`; comments are permanent, so a wrong one is corrected by a new one. Keep credentials, personal data and production payloads out of them.
+
+A new round on a work item starts with `task.branch` and its `workItemId`: the branch question then offers continuing the branch its earlier rounds used, and says so when the previous round's delivery is still open, because that round's last commits may not be on origin yet. A planned item keeps its plan branch.
+
+### Delivery records
+
+Every closed write task has a delivery record that the whole project sees: whether it was answered, delivered or concluded, and by whom. `task.close` records the delivery answer there. When another member answered first, the response shows their answer; the choice made here still decides the Git action here, so tell the user both. `session.entry` lists open deliveries as `openDeliveries`: mention them in one line. For one whose `folderHere` is set, `task.close` with its `taskId` in that folder asks and performs the delivery. Any other one is answered or concluded with `task.delivery` when the user asks — for example when the files are no longer reachable ("conclude without delivery"). The worktree pool reports delivered and cancelled outcomes itself; never report a delivery by hand.
+
 ### Administration, product management and QA
 
 Administrative authority and work discipline are independent. Organization admins can manage projects, assignments, repository URLs and work items in their organization. A global admin has those rights only in organizations they actively belong to. Ordinary users need a live explicit project assignment. Active organization administrators, including a global admin with live membership in that organization, inherit contributor access to its projects without a separate project grant. Fullstack/backend/web/mobile/frontend disciplines still govern implementation, while project overrides do not grant administration.
@@ -284,8 +305,10 @@ current. Select linkedSources explicitly by accessible project id, commit and tr
 do not guess the counterpart's source from this repository's branch. Unselected or unknown linked
 sources are not verified endpoint contracts.
 
-If task.close reported sourcePublication.applicable, call memory.publish_task after the
-already-authorized commit is created, with the closed task id and repoRoot; otherwise there is
+If task.close reported sourcePublication.applicable, worktree.release with deliveryOutcome delivered
+publishes the source memory after the already-authorized commit and reports the result as
+sourcePublication. Call memory.publish_task with the closed task id and repoRoot yourself only when
+that result names a reason you can fix, or when the task has no worktree to release. Otherwise there is
 nothing to publish, for one of two distinct reasons publish_task's reason field names: a project
 with no inspected source snapshot at all has legacy-unverified coverage, while a source-aware task
 whose commit and tree were never resolved to an inspected snapshot has unknown coverage.