engineering-memory 1.11.5 → 1.11.6

package/dispatcher/sections.mjs

@@ -19,7 +19,7 @@ Never answer a question about a bound repository from the working tree alone. Wh
 
 After compaction, a new chat, interruption, or handoff, call \`session.resume\` before continuing.
 
-Before a new write/scaffold task, use \`task.branch\` for native base selection and automatic worktree allocation. Run all commands from its returned \`repoRoot\`. Renew \`task.heartbeat\` during actual work, use \`task.pause\` on handoff, and resume before writing again. Inactivity never permits force checkout or cleanup. Keep closed worktrees until authorized delivery completes. Ask only unanswered shared branch preferences when \`session.entry\` says the user can manage them; otherwise choose a task-specific base.
+Before a new write/scaffold task, inspect \`worktree.list\` first, then use \`task.branch\` for native base selection and pool allocation. A separate worktree does not necessarily mean a new directory: reuse a safely available slot before creating another. Never invent the next numbered path. Reconcile protected legacy entries through the native recovery flow; clean files alone do not establish that the old agent and delivery have finished. Run all commands from its returned \`repoRoot\`. Renew \`task.heartbeat\` during actual work, use \`task.pause\` on handoff, and resume before writing again. Inactivity never permits force checkout or cleanup. Keep closed worktrees until authorized delivery completes. Ask only unanswered shared branch preferences when \`session.entry\` says the user can manage them; otherwise choose a task-specific base.
 
 Do not edit until the skill lifecycle has completed discovery, its checkpoint, and \`context.prepare_change\`. Do not claim completion until \`task.verify\` succeeds.
 

package/package.json

@@ -1,29 +1,29 @@
-{
-  "name": "engineering-memory",
-  "version": "1.11.5",
-  "description": "Installs the Engineering Memory skill and its local MCP bridge. Sign in after installing; your organization and project are resolved from your account.",
-  "license": "UNLICENSED",
-  "type": "module",
-  "engines": {
-    "node": ">=20"
-  },
-  "bin": {
-    "engineering-memory": "bin/engineering-memory.mjs"
-  },
-  "files": [
-    "bin",
-    "dispatcher",
-    "lib",
-    "install",
-    "skill",
-    "runtime"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0",
-    "minimatch": "10.2.6",
-    "zod": "4.4.3"
-  },
-  "engineeringMemory": {
-    "apiUrl": "https://coral-app-zqmj6.ondigitalocean.app"
-  }
-}
+{
+  "name": "engineering-memory",
+  "version": "1.11.6",
+  "description": "Installs the Engineering Memory skill and its local MCP bridge. Sign in after installing; your organization and project are resolved from your account.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "engineering-memory": "bin/engineering-memory.mjs"
+  },
+  "files": [
+    "bin",
+    "dispatcher",
+    "lib",
+    "install",
+    "skill",
+    "runtime"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "minimatch": "10.2.6",
+    "zod": "4.4.3"
+  },
+  "engineeringMemory": {
+    "apiUrl": "https://coral-app-zqmj6.ondigitalocean.app"
+  }
+}

package/runtime/dist/src/mcp/worktree-tools.js

@@ -338,13 +338,76 @@ export function registerWorktreeTools(server, service) {
         delivered: z.boolean().optional(),
     });
     server.registerTool('worktree.list', {
-        description: 'List task checkouts, activity and reasons each directory is protected.',
+        description: 'Discover existing managed Git checkouts and list activity and protection reasons before allocating another folder. Unregistered legacy checkouts remain protected until explicitly reconciled.',
         inputSchema: locationSchema,
     }, async (input) => output(await service.worktreeOperation('list', input)));
     server.registerTool('worktree.reconcile', {
-        description: 'Reconcile Git with the local registry and recover interrupted allocations or a validated backup, without deleting files or resetting branches.',
-        inputSchema: locationSchema,
-    }, async (input) => output(await service.worktreeOperation('reconcile', input)));
+        description: 'Reconcile Git with the local registry, including unregistered legacy checkouts. Use releaseUnowned only on a selected unreserved recovered checkout after prior work has finished; a native source-bound confirmation and fresh safety checks precede reuse. Never delete files or reset branches.',
+        inputSchema: z.strictObject({
+            repoRoot: repo,
+            releaseUnowned: z.boolean().optional(),
+            decisionAttempt: z.number().int().min(0).default(0),
+            language: z.enum(['tr', 'en']).default('en'),
+        }),
+    }, async (input, context) => {
+        const inspection = await service.worktreeOperation('reconcile', input);
+        if (!inspection.ok || !input.releaseUnowned)
+            return output(inspection);
+        const data = inspection.data;
+        const entry = data.selected;
+        if (!entry?.recoveredWithoutReservation || !entry.baseCommit)
+            return output({
+                ok: false,
+                error: {
+                    kind: 'bridge_error',
+                    retryable: false,
+                    recovery: 'worktree.reconcile',
+                    message: 'Select an unregistered, unreserved checkout from worktree.list. Existing task ownership cannot be released by this recovery.',
+                },
+            });
+        const digest = sha256(stableStringify({
+            projectId: entry.projectId,
+            repoRoot: entry.repoRoot,
+            generation: entry.generation,
+            sourceCommit: entry.baseCommit,
+            decisionAttempt: input.decisionAttempt,
+        }));
+        const questionnaireId = 'worktree-release-unowned-' + digest;
+        const form = await askQuestionnaire(server, service, {
+            repoRoot: input.repoRoot,
+            questionnaireId,
+            language: input.language,
+            allowFreeText: false,
+            message: input.language === 'tr'
+                ? 'Bu eski çalışma klasörünün önceki sahiplik kaydı yok. Önceki ajan burada artık çalışmıyor ve teslim tamamlandıysa, temiz klasörü yeniden kullanılabilir yapalım mı? Dosyalar ve branch silinmeyecek.'
+                : 'This legacy checkout has no prior ownership record. If the previous agent has stopped and delivery is complete, make the clean checkout reusable? No files or branches will be deleted.',
+            options: [
+                {
+                    id: 'release_unowned',
+                    label: input.language === 'tr'
+                        ? 'Önceki iş bitti; güvenli kontrollerden sonra kullanılabilir yap'
+                        : 'Prior work finished; release after safety checks',
+                },
+                {
+                    id: 'preserve',
+                    label: input.language === 'tr' ? 'Korumaya devam et' : 'Keep protected',
+                },
+            ],
+        }, context);
+        const decision = await service.questionnaireResume({
+            repoRoot: input.repoRoot,
+            questionnaireId,
+        });
+        if (decision.status !== 'answered' || decision.answer?.choice !== 'release_unowned')
+            return form;
+        return output(await service.worktreeOperation('release_unowned', {
+            repoRoot: input.repoRoot,
+            generation: entry.generation,
+            sourceCommit: entry.baseCommit,
+            decisionAttempt: input.decisionAttempt,
+            decisionId: questionnaireId,
+        }));
+    });
     server.registerTool('task.heartbeat', {
         description: 'Renew this exact task ownership during real activity. Never run an idle timer to keep an abandoned task active.',
         inputSchema: ownershipSchema,

package/runtime/dist/src/runtime/bridge-service.js

@@ -1870,12 +1870,33 @@ export class BridgeService {
             const pool = this.dependencies.worktreePool;
             if (!projectId || !pool)
                 throw refuse('Resolve the project with a pool-capable client.', 'project.resolve');
-            if (operation === 'list')
-                return asJsonValue({ items: await pool.list(projectId, await this.poolPolicy()) });
-            if (operation === 'reconcile')
+            if (operation === 'list' || operation === 'reconcile')
                 return asJsonValue({
                     items: await pool.reconcile(projectId, repository.repoRoot, await this.poolPolicy()),
+                    selected: await pool.forPath(projectId, repository.repoRoot),
                 });
+            if (operation === 'release_unowned') {
+                const entry = await pool.forPath(projectId, repository.repoRoot);
+                if (!entry || !input.sourceCommit || !input.generation || !input.decisionId)
+                    throw refuse('Inspect the recovered checkout with worktree.reconcile before confirming its release.', 'worktree.reconcile');
+                const digest = sha256(stableStringify({
+                    projectId,
+                    repoRoot: entry.repoRoot,
+                    generation: input.generation,
+                    sourceCommit: input.sourceCommit,
+                    decisionAttempt: input.decisionAttempt ?? 0,
+                }));
+                if (input.decisionId !== 'worktree-release-unowned-' + digest)
+                    throw refuse('The availability decision does not match this checkout and source. Repeat worktree.reconcile.', 'worktree.reconcile');
+                const decision = await this.questionnaireResume({
+                    repoRoot: repository.repoRoot,
+                    questionnaireId: input.decisionId,
+                });
+                if (decision.status !== 'answered' || decision.answer?.choice !== 'release_unowned')
+                    throw refuse('Confirm that prior work and delivery have finished in the native worktree.reconcile form.', 'worktree.reconcile');
+                await pool.releaseUnowned(projectId, repository.repoRoot, input.generation, input.sourceCommit);
+                return asJsonValue({ operation, complete: true, repoRoot: repository.repoRoot });
+            }
             const entry = await pool.forPath(projectId, repository.repoRoot);
             if (!entry ||
                 entry.externalTaskId !== input.externalTaskId ||

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

@@ -35,6 +35,7 @@ const allocationSchema = z.object({
     lastActivityAt: z.number().finite(),
     phase: z.enum(['creating', 'working', 'paused', 'delivery', 'released', 'quarantined']),
     pendingDelivery: z.boolean(),
+    recoveredWithoutReservation: z.boolean().optional(),
     reason: z.string().optional(),
 });
 const registrySchema = z.object({
@@ -74,6 +75,7 @@ export class WorktreePool {
                 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');
             }
         }
+        await this.reconcile(input.projectId, input.repoRoot, policy, true);
         const commonDir = await this.commonDirectory(input.repoRoot);
         return this.transaction(async (registry) => {
             if (!registry.projects[input.projectId]) {
@@ -292,33 +294,83 @@ export class WorktreePool {
             await this.save(registry);
         });
     }
-    async reconcile(projectId, repoRoot, policy) {
+    async releaseUnowned(projectId, repoRoot, generation, sourceCommit) {
+        await this.transaction(async (registry) => {
+            const entry = registry.projects[projectId]?.entries.find((e) => key(e.repoRoot) === key(repoRoot));
+            if (!entry ||
+                entry.generation !== generation ||
+                !entry.recoveredWithoutReservation ||
+                entry.phase !== 'quarantined' ||
+                entry.owner ||
+                entry.taskId ||
+                (await this.git.branchStore(repoRoot).read()))
+                throw refuse('This is not the same unowned recovered checkout. List and reconcile its current ownership before release.');
+            if ((await this.git.sourceIdentity(repoRoot))?.sourceCommit !== sourceCommit ||
+                entry.baseCommit !== sourceCommit)
+                throw refuse('The recovered checkout source changed. Inspect it again before confirming availability.');
+            const reasons = await this.fileProtection(entry);
+            if (reasons.length)
+                throw refuse('The recovered checkout is protected: ' + reasons.join(', '));
+            entry.phase = 'released';
+            entry.pendingDelivery = false;
+            entry.recoveredWithoutReservation = false;
+            entry.generation = randomUUID();
+            delete entry.reason;
+            await this.save(registry);
+        });
+    }
+    async reconcile(projectId, repoRoot, policy, discoverOnly = false) {
         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))
+            const locations = await this.gitPaths(repoRoot);
+            const candidates = [];
+            const managedRoot = join(await this.documentsDirectory(), 'engineeringmemory');
+            for (const location of locations) {
+                if (project?.entries.some((entry) => key(entry.repoRoot) === key(location.path)))
+                    continue;
+                if (!(await pathExists(location.path)))
+                    continue;
+                const parent = dirname(location.path);
+                const folder = dirname(parent).split(/[\\/]/).pop();
+                const name = location.path.split(/[\\/]/).pop();
+                if (key(parent) !== key(join(managedRoot, folder, 'worktrees')))
+                    continue;
+                const prefix = folder + '-worktree';
+                const slot = Number(name.slice(prefix.length));
+                if (!name.startsWith(prefix) ||
+                    !Number.isSafeInteger(slot) ||
+                    slot < 1 ||
+                    name !== prefix + slot)
+                    continue;
+                try {
+                    await assertManagedPath(managedRoot, location.path, false);
+                    if ((await this.commonDirectory(location.path)) !== commonDir)
                         continue;
-                    registry.projects[projectId] = { folder, entries: [] };
-                    break;
                 }
+                catch {
+                    continue;
+                }
+                const reservation = await this.git.branchStore(location.path).read();
+                if (reservation && reservation.decision.projectId !== projectId)
+                    continue;
+                if (Object.entries(registry.projects).some(([id, value]) => id !== projectId && key(value.folder) === key(folder)))
+                    continue;
+                candidates.push({ path: location.path, folder, slot });
+            }
+            if (!project) {
+                const folders = [...new Set(candidates.map((candidate) => candidate.folder))];
+                if (folders.length > 1)
+                    throw refuse('Several managed folders belong to this clone. Restore the project index to identify its original folder before allocating a directory.');
+                if (folders.length === 1)
+                    registry.projects[projectId] = { folder: folders[0], entries: [] };
             }
             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)) {
+            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;
                 if (await pathExists(entry.repoRoot))
@@ -337,48 +389,54 @@ export class WorktreePool {
                     }
                 }
             }
-            for (const location of locations) {
+            for (const location of candidates.filter((candidate) => key(candidate.folder) === key(project.folder))) {
                 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)
+                if (reservation && 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)
+                if (!source)
                     continue;
                 project.entries.push({
                     projectId,
                     repoFingerprint: await this.git.fingerprint(repoRoot),
                     commonDir,
                     repoRoot: await canonicalPath(location.path),
-                    slot: Number(slotText),
+                    slot: location.slot,
                     managed: true,
-                    externalTaskId: reservation.decision.externalTaskId,
-                    taskId: reservation.decision.taskId,
-                    branch: reservation.decision.branch,
+                    externalTaskId: reservation?.decision.externalTaskId ??
+                        'unregistered-' + sha256(key(location.path)).slice(0, 20),
+                    taskId: reservation?.decision.taskId,
+                    branch: reservation?.decision.branch ?? (await this.git.currentBranch(location.path)),
+                    recoveredWithoutReservation: !reservation,
                     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.',
+                    reason: reservation
+                        ? 'Recovered a Git reservation missing from the registry. Restore its original task source and delivery state before reuse.'
+                        : 'Unregistered checkout: prior ownership and delivery are unknown. After prior work has finished, use worktree.reconcile with releaseUnowned through its native confirmation.',
                 });
             }
-            for (const entry of project.entries.filter((e) => e.commonDir === commonDir)) {
+            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;
                 try {
+                    if (entry.recoveredWithoutReservation &&
+                        !entry.owner &&
+                        !entry.taskId &&
+                        !(await this.git.branchStore(entry.repoRoot).read())) {
+                        const source = await this.git.sourceIdentity(entry.repoRoot);
+                        const branch = await this.git.currentBranch(entry.repoRoot);
+                        if (source && (source.sourceCommit !== entry.baseCommit || branch !== entry.branch)) {
+                            entry.baseCommit = source.sourceCommit;
+                            entry.branch = branch;
+                            entry.generation = randomUUID();
+                        }
+                    }
                     await this.repairCreating(entry);
                     if (await pathExists(entry.repoRoot))
                         await this.assertIdentity(entry);
@@ -391,7 +449,7 @@ export class WorktreePool {
             }
             await this.save(registry);
         });
-        return this.list(projectId, policy);
+        return discoverOnly ? [] : this.list(projectId, policy);
     }
     async entry(input, commonDir, repoRoot, slot, managed) {
         const generation = randomUUID();

package/skill/references/lifecycle.md

@@ -254,3 +254,43 @@ version is not automatically raised; projects opt in by starting a source-bound
 ## Offline source context
 
 An unexpired cached context pack may be used for implementation. The bridge records checkpoints in its outbox. Permanent proposal review, strict verification, task close, and Git commit require the backend and synchronization of the relevant task deliveries. An unrelated task or repository queue does not block this task; account switching and logout still require all deliveries to be resolved. Commit receipts are retained per task and worktree and still require an online attestation for the selected closed task and exact staged content.
+
+## Reuse before allocating another directory
+
+Before starting a write task, call `worktree.list` with the bound repository. It reconciles managed
+Git checkouts with local records. Then let `task.branch` choose the smallest safe slot; do not guess
+a new worktree number or create a directory yourself. Allocation also performs discovery when the
+caller omitted the listing. Old unregistered managed checkouts count toward the limit and remain
+protected because their previous ownership and delivery are unknown. A clean checkout alone is
+insufficient proof of availability.
+
+When prior work has finished, call `worktree.reconcile` on that checkout with `releaseUnowned:true`
+and the conversation language. Its native question binds the decision to the checkout, source and
+ownership generation. Cancellation leaves it protected. Git reservation, dirty files, unfinished
+Git operations and pending work are checked again before release. A changed source requires a new
+inspection and answer. This recovery never deletes files or branches or interrupts another agent.
+
+If the running client predates the pool tools, inspect `git worktree list` and the existing task
+reservations before any explicit allocation. Do not treat an unavailable tool or an empty registry
+as an empty filesystem. Preserve uncertain checkouts and report the client limitation.
+
+## Network and generation evidence
+
+`network` means tests of the changed network/contract behavior, not a connection to a live provider.
+Use local contract tests and controlled responses for the applicable success, errors, timeout,
+retry and cancellation behavior. Report the real runner command, for example
+`mvn -B -Dtest=CardDepositServiceTest test` or `./gradlew test --tests CardDepositServiceTest`;
+the class name need not contain a special keyword. Report `network` only when that suite actually
+covers the changed contract. A command match cannot establish behavioral coverage by itself.
+Source searches, static analyzers, `echo` and a successful `curl` request do not replace these tests.
+Never rename a command or invent a passing result to satisfy a category.
+
+Handwritten files under `service`/`services` do not automatically require a separate network category,
+and handwritten `model`/`models` files do not automatically require code generation. Explicit
+network paths and generated `.g.dart`/`.freezed.dart` files retain their gates. On code tasks,
+additional applicable `network` and `codegen` evidence is accepted; all submitted evidence must pass.
+Read-only validation requirements are unchanged. Test commands that explicitly skip tests cannot
+serve as test or network evidence. A live environment is a separate check when the task requires it.
+
+If the user later reconsiders a preserved legacy checkout, repeat `worktree.reconcile` with a new
+`decisionAttempt`; never reinterpret the previous preserve answer as approval.

package/skill/references/questionnaires.md

@@ -262,3 +262,16 @@ withdrawing it. Language changes never broaden the approved source, mode or prev
 Shared preferences use separate native decisions for development, production and test. Explicitly absent production/test values are answers. Members without canManage receive a task-specific branch choice, never an administrator question they cannot apply. The same task's accepted decision stays valid across Codex/Claude handoff after pause; return to session.resume and the recorded repoRoot.
 
 For task.branch and project.set_git_preferences, retries keep the same decisionAttempt (omit it on the first attempt). When the user explicitly reconsiders an answered deferral, use a new positive decisionAttempt to open a fresh native decision. Never reinterpret the old deferral as consent.
+
+## Legacy worktree availability
+
+Use `worktree.list` before deciding another directory is needed. An unregistered legacy checkout
+has unknown prior ownership and delivery, even if Git reports clean. `worktree.reconcile` with
+`releaseUnowned:true` and `language` opens the native availability question for that exact checkout,
+source commit and generation. The user confirms prior work and delivery have finished; current Git
+safety checks still decide whether reuse is possible. Cancellation or choosing to preserve does not
+release it. Resume the same form via the same operation. A changed source/generation needs a fresh
+decision, and an old answer cannot release a newly owned task.
+
+If the user later reconsiders a preserved legacy checkout, repeat `worktree.reconcile` with a new
+`decisionAttempt`; never reinterpret the previous preserve answer as approval.