engineering-memory 1.11.4 → 1.11.5

package/dispatcher/sections.mjs

@@ -19,6 +19,8 @@ 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.
+
 Do not edit until the skill lifecycle has completed discovery, its checkpoint, and \`context.prepare_change\`. Do not claim completion until \`task.verify\` succeeds.
 
 Do not block independent task work on \`memory.propose_revision\` drafting, submission or approval. Follow the skill's memory-updates reference: use background agents or concurrent tools when the host permits them, and continue useful work instead of immediately waiting. Without concurrency, checkpoint the pending draft and defer submission until needed. Collect the result only at the operation that depends on it; native approval and required task verification still apply.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "1.11.4",
+  "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",

package/runtime/dist/src/config.js

@@ -26,6 +26,8 @@ export function apiStateRoot(config) {
     return join(config.stateRoot, 'origins', apiNamespaceKey(config.apiBaseUrl));
 }
 export const endpoints = {
+    projectGitPreferences: (projectId) => '/projects/' + projectId + '/git-preferences',
+    worktreePolicy: '/runtime/worktree-policy',
     auditList: '/audit',
     authRefresh: '/auth/refresh',
     authLogout: '/auth/logout',

package/runtime/dist/src/git/git-inspector.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { lstat, readFile } from 'node:fs/promises';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { assertManagedPath, canonicalPath } from '../utilities/files.js';
@@ -44,7 +45,7 @@ export class GitInspector {
         if (name.length > 255 || result.exitCode !== 0 || result.stdout.trim() !== name)
             throw new Error('Choose a valid literal Git branch name of at most 255 characters');
     }
-    async createWorktree(repoRoot, name, target) {
+    async createWorktree(repoRoot, name, target, baseCommit) {
         await this.validateBranch(repoRoot, name);
         const path = resolve(repoRoot, target);
         const present = await lstat(path).then(() => true, (error) => {
@@ -73,12 +74,50 @@ export class GitInspector {
         const exists = await this.branchExists(repoRoot, name);
         const args = exists
             ? ['worktree', 'add', '--', path, name]
-            : ['worktree', 'add', '-b', name, '--', path];
+            : [
+                'worktree',
+                'add',
+                '--no-track',
+                '-b',
+                name,
+                '--',
+                path,
+                ...(baseCommit ? [baseCommit] : []),
+            ];
         const result = await this.runner.run('git', args, { cwd: repoRoot });
         if (result.exitCode !== 0)
             throw new Error(`Git could not create the worktree: ${result.stderr.trim()}`);
         return await this.findRoot(path);
     }
+    async fetchBranchCommit(repoRoot, remote, branch) {
+        await this.validateBranch(repoRoot, branch);
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(remote))
+            throw new Error('Select a configured remote name, not a URL or credential');
+        const remotes = await this.gitValue(repoRoot, ['remote']);
+        if (!remotes?.split(/\r?\n/).includes(remote))
+            throw new Error('The selected remote is unavailable in this clone');
+        const ref = 'refs/engineering-memory/fetched-bases/' + randomUUID();
+        try {
+            const result = await this.runner.run('git', [
+                'fetch',
+                '--no-tags',
+                '--no-write-fetch-head',
+                '--refmap=',
+                '--',
+                remote,
+                'refs/heads/' + branch + ':' + ref,
+            ], { cwd: repoRoot });
+            if (result.exitCode !== 0)
+                throw new Error('The remote branch could not be fetched. Ask whether to use an explicitly selected local commit.');
+            const source = await this.sourceIdentity(repoRoot, ref);
+            if (!source)
+                throw new Error('The fetched branch has no commit');
+            return source;
+        }
+        finally {
+            await this.runner.run('git', ['update-ref', '-d', ref], { cwd: repoRoot });
+        }
+    }
     async currentBranch(repoRoot) {
         return await this.gitValue(repoRoot, ['symbolic-ref', '--short', '-q', 'HEAD']);
     }

package/runtime/dist/src/git/verification-gate.js

@@ -1,3 +1,4 @@
+import { WorktreePool } from '../runtime/worktree-pool.js';
 import { sha256 } from '../utilities/hash.js';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -8,12 +9,14 @@ export class VerificationGate {
     outbox;
     commitGateAttestor;
     root;
+    pool;
     repositories;
-    constructor(stateRoot, git, outbox, commitGateAttestor) {
+    constructor(stateRoot, git, outbox, commitGateAttestor, pool) {
         this.git = git;
         this.outbox = outbox;
         this.commitGateAttestor = commitGateAttestor;
         this.root = join(stateRoot, 'verification-gates');
+        this.pool = pool ?? new WorktreePool(stateRoot);
         this.repositories = new RepositoryResolver(git, 2, stateRoot);
     }
     async record(input) {
@@ -21,6 +24,9 @@ export class VerificationGate {
             (!Number.isSafeInteger(input.taskVersion) || (input.taskVersion ?? 0) < 1)) {
             throw new Error('Closed task verification receipt requires its backend task version');
         }
+        const allocation = input.projectId
+            ? await this.pool.forPath(input.projectId, input.repoRoot)
+            : null;
         const verifiedAt = new Date();
         const taskChanges = await this.git.taskManifest(input.repoRoot, input.taskChanges);
         const worktreeId = worktreeIdentity(await this.git.findRoot(input.repoRoot));
@@ -28,6 +34,7 @@ export class VerificationGate {
             schemaVersion: 5,
             source: input.source,
             worktreeId,
+            ...(allocation ? { worktreeGeneration: allocation.generation } : {}),
             taskId: input.taskId,
             projectId: input.projectId,
             repoFingerprint: input.repoFingerprint,
@@ -42,6 +49,23 @@ export class VerificationGate {
             branch: input.branch ?? null,
         }, this.root);
     }
+    async rebindWorktreeOwnership(repoRoot, taskId, previous, generation) {
+        const fingerprint = await this.git.fingerprint(repoRoot);
+        const identity = worktreeIdentity(await this.git.findRoot(repoRoot));
+        const path = this.pathFor(fingerprint, identity, taskId);
+        const receipt = await readJson(path, this.root);
+        if (!receipt || receipt.taskId !== taskId || receipt.worktreeGeneration !== previous)
+            return;
+        if (!receipt.projectId)
+            return;
+        const allocation = await this.pool.forPath(receipt.projectId, repoRoot);
+        if (!allocation ||
+            allocation.taskId !== taskId ||
+            allocation.generation !== generation ||
+            allocation.branch !== receipt.branch)
+            throw new Error('Resumed ownership does not match the verification receipt');
+        await writeJson(path, { ...receipt, worktreeGeneration: generation }, this.root);
+    }
     async verify(repoRoot) {
         const [repository, stagedChanges, scaffolding] = await Promise.all([
             this.repositories.resolve(repoRoot),
@@ -73,6 +97,21 @@ export class VerificationGate {
         if (!receipt) {
             return { allowed: false, reason: 'task_verify_required', diffHash: manifest.diffHash };
         }
+        try {
+            if (receipt.projectId)
+                await this.pool.validateCommit(receipt.projectId, receipt.taskId, repository.repoRoot, receipt.worktreeGeneration);
+        }
+        catch {
+            return {
+                allowed: false,
+                reason: 'worktree_ownership_changed',
+                diffHash: manifest.diffHash,
+                taskId: receipt.taskId,
+                details: [
+                    'Resume the task in its current owned worktree; stale verification cannot authorize another allocation.',
+                ],
+            };
+        }
         if ((await this.outbox.listForTask(receipt.taskId)).length > 0) {
             return {
                 allowed: false,

package/runtime/dist/src/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { WorktreePool } from './runtime/worktree-pool.js';
+import { WorktreePolicyCache } from './runtime/worktree-policy.js';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { BrowserAuthCoordinator } from './auth/browser-auth.js';
 import { createCredentialStore } from './auth/credential-store.js';
@@ -47,9 +49,21 @@ export function createBridgeService() {
     const repositoryDecisions = new RepositoryDecisionStore(stateRoot);
     const updateChoices = new UpdateChoiceStore(stateRoot);
     const shadowNotices = new ShadowNoticeStore(stateRoot);
-    const gate = new VerificationGate(stateRoot, git, outbox);
+    const worktreePool = new WorktreePool(stateRoot, {
+        pendingWork: async (entry) => {
+            if (!entry.taskId)
+                return false;
+            const pointer = await activeContexts.loadForTask(entry.repoFingerprint, entry.taskId);
+            return Boolean(pointer?.verificationIntent ||
+                pointer?.closeIntent ||
+                (await outbox.listForTask(entry.taskId)).length);
+        },
+    });
+    const gate = new VerificationGate(stateRoot, git, outbox, undefined, worktreePool);
     const principalState = new PrincipalStateGuard(stateRoot, credentials, cache, outbox, activeContexts, gate);
     return new BridgeService({
+        worktreePool,
+        worktreePolicy: new WorktreePolicyCache(stateRoot),
         client,
         credentials,
         browserAuth: new BrowserAuthCoordinator(client, credentials),

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

@@ -656,9 +656,41 @@ async function approveOnboarding(server, service, input, context, initialize) {
         processedFields.add(field);
         fields = profileFields(effectiveProfile);
     }
+    let gitPreferences;
+    if (preparation && service.managesWorktrees()) {
+        gitPreferences = {};
+        for (const role of ['development', 'production', 'test']) {
+            const response = await askQuestionnaire(server, service, {
+                ...scope,
+                questionnaireId: 'onboard-git-' + role + '-' + sha256(input.requestKey),
+                message: role === 'development'
+                    ? 'Which development branch should new task branches start from? For a new repository, choose its planned initial branch name. This choice uses the origin remote after it is connected.'
+                    : 'Which ' +
+                        role +
+                        ' branch does this project use? Choose explicitly none if there is no such branch yet; you will not be asked again.',
+                options: [
+                    { id: 'set', label: 'Use the branch named below' },
+                    ...(role === 'development'
+                        ? [{ id: 'defer', label: 'Do not start setup yet' }]
+                        : [{ id: 'none', label: 'No ' + role + ' branch yet' }]),
+                ],
+                textField: { title: 'Branch name', maxLength: 255, requiredForChoice: 'set' },
+                allowFreeText: false,
+            }, context);
+            const answer = answerData(response);
+            if (answer?.choice !== 'none' && (answer?.choice !== 'set' || !answer.text))
+                return response;
+            gitPreferences[role] = {
+                answered: true,
+                branch: answer.choice === 'none' ? null : answer.text,
+                remote: answer.choice === 'none' ? null : 'origin',
+            };
+        }
+    }
     const choice = {
         requestKey: input.requestKey,
         mode: input.mode,
+        ...(gitPreferences ? { gitPreferences } : {}),
         profile: body(onboardingInput.parse({ ...input, profile: effectiveProfile }).profile),
         ...(input.reworkBehavior ? { reworkBehavior: input.reworkBehavior } : {}),
     };
@@ -698,7 +730,13 @@ async function approveOnboarding(server, service, input, context, initialize) {
         });
     if (!saved.ok || !input.projectId)
         return output(saved);
-    return output(await service.onboardingRequest('onboarding_choose', body({ projectId: input.projectId, ...choice })));
+    return output(await service.onboardingRequest('onboarding_choose', body({
+        projectId: input.projectId,
+        requestKey: choice.requestKey,
+        mode: choice.mode,
+        profile: choice.profile,
+        reworkBehavior: choice.reworkBehavior,
+    })));
 }
 function deferredProfile(requestKey, field) {
     return output({

package/runtime/dist/src/mcp/server.js

@@ -1,3 +1,4 @@
+import { registerWorktreeTools } from './worktree-tools.js';
 import { McpServer } from '@modelcontextprotocol/server';
 import { registerOnboardingTools } from './onboarding-tools.js';
 import { registerEngineeringMemoryTools, registerQuestionnaireTools } from './tool-definitions.js';
@@ -11,6 +12,7 @@ export function createEngineeringMemoryServer(service) {
     registerEngineeringMemoryTools(server, service);
     registerQuestionnaireTools(server, service);
     registerOnboardingTools(server, service);
+    registerWorktreeTools(server, service);
     return server;
 }
 //# sourceMappingURL=server.js.map

package/runtime/dist/src/mcp/tool-definitions.js

@@ -46,6 +46,15 @@ const checkpointBase = {
     idempotencyKey: z.string().uuid().optional(),
 };
 export const engineeringMemoryToolNames = [
+    'project.git_preferences',
+    'project.set_git_preferences',
+    'worktree.policy',
+    'worktree.set_policy',
+    'worktree.list',
+    'worktree.reconcile',
+    'task.heartbeat',
+    'task.pause',
+    'worktree.release',
     'audit.list',
     'questionnaire.ask',
     'questionnaire.resume',
@@ -524,16 +533,6 @@ export function registerEngineeringMemoryTools(server, service) {
             reason: z.string().min(1).max(2000),
         }),
     }, async (input) => toolResult(await service.taskAbandon(input)));
-    server.registerTool('task.branch', {
-        description: 'Record the native questionnaire answer for the exact externalTaskId before any new write/scaffold task or read-only-to-write transition. Choose name or keepCurrent. For another task in a busy checkout supply worktreePath and name; use the returned repoRoot for all subsequent commands. Existing branches may be selected without resetting them. Decisions persist across retries and restarts.',
-        inputSchema: z.object({
-            repoRoot: optionalRepoRoot,
-            externalTaskId: z.string().min(2).max(160),
-            worktreePath: z.string().min(1).optional(),
-            name: z.string().min(1).max(255).optional(),
-            keepCurrent: z.boolean().optional(),
-        }),
-    }, async (input) => toolResult(await service.taskBranch(input)));
     server.registerTool('organization.create', {
         description: 'Create an organization the user named, with the short identifier they typed. Offer this underneath the organizations they already belong to; never invent the identifier from the name.',
         inputSchema: z.object({
@@ -567,6 +566,10 @@ export function registerEngineeringMemoryTools(server, service) {
         description: 'Create a policy-ready backend project from the native questionnaire and local repository audit, then store its binding in user-local state.',
         inputSchema: z.object({
             repoRoot: optionalRepoRoot,
+            onboardingRequestKey: z
+                .string()
+                .regex(/^[A-Za-z0-9_-]{1,80}$/)
+                .optional(),
             organizationId: z.string().uuid(),
             projectName: z.string().min(2),
             projectSlug: z.string().min(2).optional(),