engineering-memory 1.8.0 → 1.10.0

package/runtime/dist/src/runtime/api-client.js

@@ -32,6 +32,7 @@ export const backendRecoveryOperationNames = [
     'task.verify',
     'task.close',
     'task.abandon',
+    'task.branch',
     'task.resolve_pending_delivery',
 ];
 const backendRecoveryOperations = new Set(backendRecoveryOperationNames);

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

@@ -67,7 +67,7 @@ export class BridgeService {
             const recoveredDeliveries = await this.recoverJournalOutbox();
             const outbox = await this.flushOutbox();
             let projectId = repository.projectId;
-            if (!repository.markerPath) {
+            if (!repository.bindingPath) {
                 const resolved = await this.dependencies.client.request(endpoints.projectResolve, {
                     method: 'POST',
                     body: { repoFingerprint: repository.repoFingerprint },
@@ -88,8 +88,13 @@ export class BridgeService {
                 });
             }
             if (!projectId) {
-                throw refuse('This repository has a marker that names no project, so there is nothing to bootstrap against.', 'project.resolve');
+                throw refuse('This repository has no selected project. Select its project before bootstrapping.', 'project.resolve');
             }
+            const bootstrapMode = persistedBootstrap.mode ?? 'write';
+            const decision = bootstrapMode === 'read_only'
+                ? null
+                : await this.requireBranchDecision(repository, input.externalTaskId);
+            const branch = decision?.branch;
             const checkpointId = deterministicUuid('session.bootstrap', projectId, repository.repoFingerprint, input.externalTaskId);
             const response = await this.dependencies.client.request(endpoints.sessionBootstrap, {
                 method: 'POST',
@@ -106,6 +111,7 @@ export class BridgeService {
                     ...(input.mode === 'read_only'
                         ? { baselineDiffHash: repository.git.worktreeHash }
                         : {}),
+                    ...(decision ? { branch } : {}),
                     checkpointIdempotencyKey: checkpointId,
                     knownRevisions: persistedBootstrap.knownRevisions,
                 }),
@@ -127,11 +133,20 @@ export class BridgeService {
                 !isIsoTimestamp(checkpointPayload.createdAt)) {
                 throw refuse('The backend opened the session without the checkpoint the task is anchored to.', 'session.bootstrap');
             }
+            if (decision)
+                await this.dependencies.repositories.git
+                    .branchStore(repository.repoRoot)
+                    .bind(projectId, input.externalTaskId, task.id);
             const pointer = {
                 repoFingerprint: repository.repoFingerprint,
                 projectId,
                 taskId: task.id,
                 taskSlug: input.externalTaskId,
+                worktreeId: sha256(repository.repoRoot),
+                ...(decision
+                    ? { branch: typeof task.branch === 'string' ? task.branch : decision.branch }
+                    : {}),
+                mode: normalizeTaskMode(task.mode),
                 sessionId: session.id,
                 lastSequence: numericSequence(task.lastSequence),
                 taskVersion: numericTaskVersion(task.lockVersion),
@@ -256,6 +271,12 @@ export class BridgeService {
                 backendSession.id !== sessionId) {
                 throw refuse('The backend resumed the session without the task it belongs to.', 'session.resume');
             }
+            await this.assertTaskWorktree(repository, backendTask, pointer);
+            if (backendTask.status === 'closed' || backendTask.status === 'abandoned') {
+                await this.dependencies.repositories.git
+                    .branchStore(repository.repoRoot)
+                    .release(backendTask.id);
+            }
             let localJournal = await this.dependencies.journal.load(projectId, taskSlug);
             let pendingOutbox = await this.dependencies.outbox.list();
             const responseSource = this.dependencies.client.getResponseSource(response);
@@ -365,6 +386,13 @@ export class BridgeService {
                     projectId,
                     taskId: backendTask.id,
                     taskSlug,
+                    worktreeId: pointer?.worktreeId ?? sha256(repository.repoRoot),
+                    ...(typeof backendTask.branch === 'string'
+                        ? { branch: backendTask.branch }
+                        : pointer?.branch !== undefined
+                            ? { branch: pointer.branch }
+                            : {}),
+                    mode: normalizeTaskMode(backendTask.mode),
                     sessionId,
                     lastSequence: resumedLastSequence,
                     taskVersion: resumedTaskVersion,
@@ -443,6 +471,10 @@ export class BridgeService {
                 ...input.changedPaths,
             ]);
             const baselineDiffHash = activeBaseline?.diffHash ?? repository.git.diffHash;
+            const decision = pointer &&
+                (input.transitionToWrite || (pointer.branch !== undefined && pointer.mode !== 'read_only'))
+                ? await this.requireBranchDecision(repository, pointer.taskSlug)
+                : null;
             let transitionTaskVersion;
             if (input.transitionToWrite) {
                 if (!pointer || pointer.sessionId !== input.sessionId) {
@@ -455,6 +487,7 @@ export class BridgeService {
                 sessionId: input.sessionId,
                 changedPaths,
                 baselineDiffHash,
+                ...(decision ? { branch: decision.branch } : {}),
                 ...(input.transitionToWrite
                     ? { transitionToWrite: true, expectedTaskVersion: transitionTaskVersion }
                     : {}),
@@ -501,6 +534,17 @@ export class BridgeService {
                 : undefined);
             const preparedPointer = await this.dependencies.activeContexts.loadForSession(repository.repoFingerprint, input.sessionId);
             if (preparedPointer) {
+                if (decision) {
+                    await this.dependencies.repositories.git
+                        .branchStore(repository.repoRoot)
+                        .bind(preparedPointer.projectId, preparedPointer.taskSlug, preparedPointer.taskId);
+                    await this.dependencies.activeContexts.save({
+                        ...preparedPointer,
+                        worktreeId: sha256(repository.repoRoot),
+                        branch: typeof preparedTask?.branch === 'string' ? preparedTask.branch : decision.branch,
+                        mode: 'write',
+                    });
+                }
                 const preparedData = objectValue(response.data);
                 await this.seedResumeSnapshot(preparedPointer, {
                     ...objectOrEmpty(response.data),
@@ -1010,6 +1054,7 @@ export class BridgeService {
                     });
                 }
                 const taskMode = normalizeTaskMode(snapshotTask.mode);
+                await this.assertTaskWorktree(repository, snapshotTask, pointer);
                 const resourceDiscoveryPolicy = readResourceDiscoveryPolicy(snapshot, activeLease);
                 const validations = normalizePersistentInput(input.validations, repository.repoRoot);
                 if (taskMode === 'read_only') {
@@ -1072,6 +1117,11 @@ export class BridgeService {
                     changedPaths: taskMode === 'read_only' ? [] : taskChangedPaths,
                     pathChanges: pathChangeManifest,
                     diffHash: repository.git.diffHash,
+                    ...(taskMode !== 'read_only'
+                        ? {
+                            branch: await this.dependencies.repositories.git.currentBranch(repository.repoRoot),
+                        }
+                        : {}),
                     ...(taskMode === 'read_only' ? { worktreeHash: repository.git.worktreeHash } : {}),
                     validations,
                     pendingOutboxCount,
@@ -1105,6 +1155,9 @@ export class BridgeService {
                         repoFingerprint: repository.repoFingerprint,
                         repoRoot: repository.repoRoot,
                         diffHash: repository.git.diffHash,
+                        branch: typeof snapshotTask.branch === 'string'
+                            ? snapshotTask.branch
+                            : (pointer.branch ?? null),
                         taskVersion,
                         taskChanges,
                     });
@@ -1148,11 +1201,17 @@ export class BridgeService {
                 const taskChanges = pointer.changeBaseline
                     ? manifestDelta(pointer.changeBaseline.changedPaths, repository.git.changedPaths)
                     : [];
+                await this.assertTaskWorktree(repository, task, pointer);
                 const closeBody = {
                     taskId: input.taskId,
                     sessionId: pointer.sessionId,
                     expectedTaskVersion: numericTaskVersion(task.lockVersion),
                     diffHash: repository.git.diffHash,
+                    ...(normalizeTaskMode(task.mode) !== 'read_only'
+                        ? {
+                            branch: await this.dependencies.repositories.git.currentBranch(repository.repoRoot),
+                        }
+                        : {}),
                 };
                 await this.dependencies.activeContexts.setCloseIntent(repository.repoFingerprint, {
                     body: closeBody,
@@ -1162,6 +1221,109 @@ export class BridgeService {
             });
         });
     }
+    async taskBranch(input) {
+        return await this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
+            const authentication = await this.dependencies.browserAuth.ensureAuthenticated();
+            if (authentication)
+                return asJsonValue({ authentication });
+            if (!repository.projectId)
+                throw refuse('Resolve the project before choosing its task branch.', 'project.resolve');
+            if (!input.externalTaskId ||
+                input.externalTaskId.length > 160 ||
+                /[\r\n]/.test(input.externalTaskId))
+                throw refuse('Pass the exact externalTaskId of the task whose branch question was answered.', 'task.branch');
+            if (Boolean(input.name) === (input.keepCurrent === true) ||
+                (input.worktreePath && !input.name))
+                throw refuse('Choose exactly one branch name or keepCurrent. A separate worktree also needs a branch name.', 'task.branch');
+            assertSafeToPersist(cleanJson({ externalTaskId: input.externalTaskId, name: input.name }));
+            const git = this.dependencies.repositories.git;
+            let target = repository;
+            try {
+                if (input.name)
+                    await git.validateBranch(repository.repoRoot, input.name);
+                if (input.worktreePath && input.name) {
+                    const targetRoot = await git.createWorktree(repository.repoRoot, input.name, input.worktreePath);
+                    target = await this.dependencies.repositories.resolve(targetRoot);
+                    if (target.projectId && target.projectId !== repository.projectId)
+                        throw refuse('The target worktree belongs to a different Engineering Memory project. Choose another worktreePath.', 'task.branch');
+                    if (!target.bindingPath || target.repoFingerprint !== repository.repoFingerprint)
+                        throw refuse('The worktree did not inherit the selected local project binding.', 'project.resolve');
+                }
+                const branch = input.name ?? (await git.currentBranch(target.repoRoot));
+                const store = git.branchStore(target.repoRoot);
+                await store.reserve({
+                    projectId: repository.projectId,
+                    externalTaskId: input.externalTaskId,
+                    branch,
+                });
+                if (input.name && (await git.currentBranch(target.repoRoot)) !== input.name) {
+                    try {
+                        if (await git.branchExists(target.repoRoot, input.name))
+                            await git.switchBranch(target.repoRoot, input.name);
+                        else
+                            await git.createBranch(target.repoRoot, input.name);
+                    }
+                    catch (error) {
+                        if ((await git.currentBranch(target.repoRoot)) !== input.name) {
+                            await store.cancelUnopened(repository.projectId, input.externalTaskId);
+                            throw error;
+                        }
+                    }
+                }
+                return asJsonValue({
+                    branch,
+                    kept: input.keepCurrent === true,
+                    repoRoot: target.repoRoot,
+                    externalTaskId: input.externalTaskId,
+                    nextAction: 'Use this repoRoot for session.bootstrap and every subsequent command for this task. The decision survives retries and restarts.',
+                });
+            }
+            catch (error) {
+                if (error instanceof BridgeRecoveryError)
+                    throw error;
+                throw refuse(`${error instanceof Error ? error.message : String(error)} Retry task.branch for the selected task; use worktreePath to leave a busy or dirty checkout intact.`, 'task.branch');
+            }
+        });
+    }
+    async requireBranchDecision(repository, externalTaskId) {
+        const git = this.dependencies.repositories.git;
+        const store = git.branchStore(repository.repoRoot);
+        let record = await store.read();
+        if (!record) {
+            const pointer = await this.dependencies.activeContexts.loadForSlug(repository.repoFingerprint, externalTaskId);
+            if (pointer?.worktreeId === sha256(repository.repoRoot) &&
+                pointer.mode !== 'read_only' &&
+                pointer.branch !== undefined) {
+                await store.reserve({
+                    projectId: pointer.projectId,
+                    externalTaskId,
+                    branch: pointer.branch,
+                    taskId: pointer.taskId,
+                });
+                record = await store.read();
+            }
+        }
+        if (!record)
+            throw refuse(`Ask the branch question through the native questionnaire for task ${externalTaskId}, then call task.branch with that externalTaskId and a name or keepCurrent. For parallel work choose a separate worktreePath.`, 'task.branch');
+        if (record.decision.projectId !== repository.projectId ||
+            record.decision.externalTaskId !== externalTaskId)
+            throw refuse(`This worktree belongs to task ${record.decision.externalTaskId}. Use task.branch with worktreePath for ${externalTaskId}, then bootstrap in the returned directory.`, 'task.branch');
+        const branch = await git.currentBranch(repository.repoRoot);
+        if (branch !== record.decision.branch)
+            throw refuse(`Task ${externalTaskId} selected ${record.decision.branch ?? 'detached HEAD'}, but this worktree is on ${branch ?? 'detached HEAD'}. Return to the selected branch with task.branch.`, 'task.branch');
+        return record.decision;
+    }
+    async assertTaskWorktree(repository, task, pointer) {
+        if (normalizeTaskMode(task.mode) === 'read_only')
+            return;
+        if (pointer?.worktreeId && pointer.worktreeId !== sha256(repository.repoRoot))
+            throw refuse('This task belongs to a different worktree. Resume and run its commands in the worktree selected for this task.', 'session.resume');
+        const recorded = typeof task.branch === 'string' ? task.branch : pointer?.branch;
+        const current = await this.dependencies.repositories.git.currentBranch(repository.repoRoot);
+        if (recorded && current !== recorded)
+            throw refuse(`This task selected ${recorded}. Call task.branch with externalTaskId ${pointer?.taskSlug ?? String(task.externalTaskId)} and name ${recorded} before continuing.`, 'task.branch');
+    }
     async taskAbandon(input) {
         return await this.execute(async () => {
             return await this.taskExclusive(input.taskId, async () => {
@@ -1174,6 +1336,9 @@ export class BridgeService {
                 if (!abandoned || abandoned.abandoned !== true) {
                     throw refuse('The backend did not record the abandonment, so the task is still open.', 'session.resume');
                 }
+                await this.dependencies.repositories.git
+                    .branchStore(repository.repoRoot)
+                    .release(input.taskId);
                 const forgotten = await this.dependencies.activeContexts.forget(repository.repoFingerprint, input.taskId);
                 await this.dependencies.gate.invalidateTask(input.taskId);
                 return asJsonValue({
@@ -1223,8 +1388,8 @@ export class BridgeService {
                 readDiscoveryUnits(policy).length === 0) {
                 throw refuse('Project setup response is not policy-ready', 'project.setup');
             }
-            const markerPath = await this.dependencies.repositories.writeMarker(repository.repoRoot, project.id);
-            return asJsonValue({ ...data, markerPath });
+            const bindingPath = await this.dependencies.repositories.writeBinding(repository.repoRoot, project.id);
+            return asJsonValue({ ...data, marker: null, markerPath: null, bindingPath });
         });
     }
     async projectMemberAdd(input) {
@@ -1325,6 +1490,77 @@ export class BridgeService {
             return asJsonValue({ workItem: response.data });
         });
     }
+    async workItemCreate(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.workItemList(input.projectId), { method: 'POST', body: cleanJson(input.data) });
+            return asJsonValue(response.data);
+        });
+    }
+    async workItemUpdate(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.workItemGet(input.projectId, input.workItemId), { method: 'PATCH', body: cleanJson(input.data) });
+            return asJsonValue(response.data);
+        });
+    }
+    async workItemArchive(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.workItemGet(input.projectId, input.workItemId), { method: 'DELETE', body: cleanJson({ expectedVersion: input.expectedVersion }) });
+            return asJsonValue(response.data);
+        });
+    }
+    async workItemRestore(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.workItemRestore(input.projectId, input.workItemId), { method: 'POST', body: cleanJson({ expectedVersion: input.expectedVersion }) });
+            return asJsonValue(response.data);
+        });
+    }
+    async workItemRecordTest(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.workItemTests(input.projectId, input.workItemId), { method: 'POST', body: cleanJson(input.data) });
+            return asJsonValue(response.data);
+        });
+    }
+    async workItemConfirmPlan(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.workItemPlan(input.projectId, input.workItemId), { method: 'PUT', body: cleanJson(input.data) });
+            return asJsonValue(response.data);
+        });
+    }
+    async projectUpdate(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectUpdate(input.projectId), { method: 'PATCH', body: cleanJson(input.data) });
+            return asJsonValue(response.data);
+        });
+    }
+    async workItemRuns(input) {
+        return this.execute(async () => {
+            const query = new URLSearchParams({
+                offset: String(input.offset ?? 0),
+                limit: String(input.limit ?? 50),
+            });
+            const response = await this.dependencies.client.request(`${endpoints.workItemRuns(input.projectId, input.workItemId)}?${query}`);
+            return asJsonValue(response.data);
+        });
+    }
+    async workItemTestResults(input) {
+        return this.execute(async () => {
+            const query = new URLSearchParams({
+                offset: String(input.offset ?? 0),
+                limit: String(input.limit ?? 50),
+            });
+            const response = await this.dependencies.client.request(`${endpoints.workItemTests(input.projectId, input.workItemId)}?${query}`);
+            return asJsonValue(response.data);
+        });
+    }
+    async workItemPlan(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.workItemPlan(input.projectId, input.workItemId));
+            return asJsonValue({
+                ...objectOrEmpty(response.data),
+                nextAction: 'Read the current and authorized linked project contracts. Decide whether web, mobile, backend or multiple projects need changes. If additional scope is needed, explain why and obtain the native questionnaire answer before work_item.confirm_plan. Reuse an already confirmed scope and shared branch; each repository has its own worktree and task lifecycle.',
+            });
+        });
+    }
     async architecturePlan(input) {
         return await this.execute(async () => {
             const body = cleanJson(input);
@@ -1373,6 +1609,15 @@ export class BridgeService {
             return asJsonValue({ application: response.data });
         });
     }
+    async organizationUpdate(input) {
+        return this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.organizationUpdate(input.organizationId), {
+                method: 'PATCH',
+                body: cleanJson({ name: input.name, expectedName: input.expectedName }),
+            });
+            return asJsonValue(response.data);
+        });
+    }
     async organizationCreate(input) {
         return await this.execute(async () => {
             const response = await this.dependencies.client.request(endpoints.organizationCreate, { method: 'POST', body: cleanJson(input) });
@@ -1446,17 +1691,14 @@ export class BridgeService {
                 if (!project || project.id !== input.projectId) {
                     throw refuse('Project bind response does not match the selected project', 'project.resolve');
                 }
-                const markerPath = await this.dependencies.repositories.writeMarker(repository.repoRoot, input.projectId);
+                const bindingPath = await this.dependencies.repositories.writeBinding(repository.repoRoot, input.projectId);
                 return asJsonValue({
                     resolved: true,
                     bound: true,
                     project,
-                    markerPath,
-                    repository: publicRepository({
-                        ...repository,
-                        markerPath,
-                        projectId: input.projectId,
-                    }),
+                    markerPath: null,
+                    bindingPath,
+                    repository: publicRepository(await this.dependencies.repositories.resolve(repository.repoRoot)),
                     selectionRequired: false,
                 });
             }
@@ -1501,11 +1743,11 @@ export class BridgeService {
             }
             const decision = await this.dependencies.repositoryDecisions.load(repository.repoFingerprint);
             const authenticated = authentication.authenticated === true;
-            const state = decision?.state ?? (repository.projectId ? 'bound' : 'none');
+            const state = decision?.state === 'disabled' ? 'disabled' : repository.bindingPath ? 'bound' : 'none';
             const client = await this.clientUpdate(authenticated);
             const shipped = objectValue(objectValue(client)?.shippedKnowledge);
             const incomplete = shipped && (shipped.failure !== null || Number(shipped.live) < Number(shipped.expected));
-            const projectId = repository.projectId ?? decision?.projectId ?? null;
+            const projectId = repository.projectId;
             const liveTasks = authenticated && state === 'bound'
                 ? (await this.dependencies.activeContexts.list(repository.repoFingerprint)).map(describePointer)
                 : [];
@@ -2072,6 +2314,7 @@ export class BridgeService {
             repoFingerprint: pointer.repoFingerprint,
             repoRoot: repository.repoRoot,
             diffHash: repository.git.diffHash,
+            branch: typeof backendTask?.branch === 'string' ? backendTask.branch : (pointer.branch ?? null),
             taskVersion,
             taskChanges: intent.taskChanges,
         });
@@ -2100,6 +2343,9 @@ export class BridgeService {
     }
     async deliverCloseIntent(repository, body, taskChanges, recoveredAfterResponseLoss) {
         const touchedContract = taskChanges.some((change) => /\.controller\.[tj]s$/.test(change.path));
+        const currentBranch = await this.dependencies.repositories.git.currentBranch(repository.repoRoot);
+        if (typeof body.branch === 'string' && body.branch !== currentBranch)
+            throw refuse(`Return to the branch ${body.branch} recorded in this close request before retrying.`, 'task.branch');
         let response;
         try {
             response = await this.dependencies.client.request(endpoints.taskClose, {
@@ -2125,11 +2371,19 @@ export class BridgeService {
             repoFingerprint: repository.repoFingerprint,
             repoRoot: repository.repoRoot,
             diffHash: String(body.diffHash),
+            branch: typeof closedTask.branch === 'string'
+                ? closedTask.branch
+                : typeof body.branch === 'string'
+                    ? body.branch
+                    : null,
             taskClosed: true,
             taskVersion: closedTaskVersion,
             taskChanges,
         });
         await this.dependencies.activeContexts.clearCloseIntent(repository.repoFingerprint, String(body.taskId));
+        await this.dependencies.repositories.git
+            .branchStore(repository.repoRoot)
+            .release(String(body.taskId));
         return asJsonValue({
             ...closedTask,
             repository: publicRepository(repository),
@@ -2363,6 +2617,7 @@ function publicRepository(repository) {
     return asJsonValue({
         repoRoot: repository.repoRoot,
         markerPath: repository.markerPath,
+        bindingPath: repository.bindingPath,
         projectId: repository.projectId,
         schemaVersion: repository.schemaVersion,
         repoFingerprint: repository.repoFingerprint,

package/runtime/dist/src/runtime/task-branch-store.js

@@ -0,0 +1,111 @@
+import { NativeCommandRunner } from '../utilities/process.js';
+import { assertSafeToPersist } from './offline-outbox.js';
+import { BridgeRecoveryError } from './recovery-error.js';
+const decisionRef = 'refs/worktree/engineering-memory-task';
+export class TaskBranchStore {
+    repoRoot;
+    runner;
+    constructor(repoRoot, runner = new NativeCommandRunner()) {
+        this.repoRoot = repoRoot;
+        this.runner = runner;
+    }
+    async read() {
+        const reference = await this.runner.run('git', ['rev-parse', '--verify', '--quiet', decisionRef], { cwd: this.repoRoot });
+        if (reference.exitCode === 1)
+            return null;
+        if (reference.exitCode !== 0)
+            throw new BridgeRecoveryError('Git could not read the worktree task reservation. Retry the branch operation.', 'task.branch');
+        const oid = reference.stdout.trim();
+        const blob = await this.runner.run('git', ['cat-file', 'blob', oid], { cwd: this.repoRoot });
+        if (blob.exitCode !== 0)
+            throw new BridgeRecoveryError('Git could not read the recorded branch decision. Retry the branch operation.', 'task.branch');
+        let decision;
+        try {
+            decision = JSON.parse(blob.stdout);
+        }
+        catch {
+            throw new BridgeRecoveryError('The worktree branch record is invalid. Use a separate worktree to continue this task.', 'task.branch');
+        }
+        if (!decision)
+            throw new BridgeRecoveryError('The worktree branch record is invalid. Use a separate worktree to continue this task.', 'task.branch');
+        if (typeof decision.projectId !== 'string' ||
+            typeof decision.externalTaskId !== 'string' ||
+            !(decision.branch === null || typeof decision.branch === 'string')) {
+            throw new BridgeRecoveryError('The worktree branch record is invalid. Use a separate worktree to continue this task.', 'task.branch');
+        }
+        return { oid, decision };
+    }
+    async reserve(decision) {
+        assertSafeToPersist({ ...decision });
+        const existing = await this.read();
+        if (existing) {
+            this.assertSame(existing.decision, decision);
+            return;
+        }
+        const oid = await this.hash(decision);
+        const written = await this.runner.run('git', ['update-ref', '--no-deref', decisionRef, oid, '0'.repeat(oid.length)], { cwd: this.repoRoot });
+        if (written.exitCode !== 0) {
+            const winner = await this.read();
+            if (winner) {
+                this.assertSame(winner.decision, decision);
+                return;
+            }
+            throw new BridgeRecoveryError('Another branch operation is in progress. Retry the same task.branch operation.', 'task.branch');
+        }
+    }
+    async bind(projectId, externalTaskId, taskId) {
+        const current = await this.read();
+        if (!current ||
+            current.decision.projectId !== projectId ||
+            current.decision.externalTaskId !== externalTaskId)
+            throw new BridgeRecoveryError('The worktree reservation changed while opening the task. Resume it before editing.', 'session.resume');
+        if (current.decision.taskId === taskId)
+            return;
+        const oid = await this.hash({ ...current.decision, taskId });
+        const result = await this.runner.run('git', ['update-ref', '--no-deref', decisionRef, oid, current.oid], { cwd: this.repoRoot });
+        if (result.exitCode !== 0) {
+            const latest = await this.read();
+            if (latest?.decision.taskId !== taskId)
+                throw new BridgeRecoveryError('The worktree reservation changed while opening the task. Resume it before editing.', 'session.resume');
+        }
+    }
+    async cancelUnopened(projectId, externalTaskId) {
+        const current = await this.read();
+        if (!current ||
+            current.decision.taskId ||
+            current.decision.projectId !== projectId ||
+            current.decision.externalTaskId !== externalTaskId)
+            return;
+        const result = await this.runner.run('git', ['update-ref', '--no-deref', '-d', decisionRef, current.oid], { cwd: this.repoRoot });
+        if (result.exitCode !== 0 && (await this.read())?.oid === current.oid)
+            throw new BridgeRecoveryError('The failed branch operation could not release its reservation. Retry task.branch with the same task identifier.', 'task.branch');
+    }
+    async release(taskId) {
+        const current = await this.read();
+        if (!current || current.decision.taskId !== taskId)
+            return;
+        const result = await this.runner.run('git', ['update-ref', '--no-deref', '-d', decisionRef, current.oid], { cwd: this.repoRoot });
+        if (result.exitCode !== 0 && (await this.read())?.decision.taskId === taskId) {
+            throw new BridgeRecoveryError('The task has finished but its worktree reservation could not be released. Resume the task to retry cleanup.', 'session.resume');
+        }
+    }
+    assertSame(current, requested) {
+        if (current.projectId !== requested.projectId ||
+            current.externalTaskId !== requested.externalTaskId) {
+            throw new BridgeRecoveryError(`This worktree belongs to task ${current.externalTaskId}. Resume that task, or call task.branch with worktreePath and a branch name for the new task.`, 'task.branch');
+        }
+        if (current.branch !== requested.branch) {
+            throw new BridgeRecoveryError(`This task selected ${current.branch ?? 'detached HEAD'}. Return to that branch before continuing.`, 'task.branch');
+        }
+    }
+    async hash(decision) {
+        const result = await this.runner.run('git', ['hash-object', '-w', '--stdin'], {
+            cwd: this.repoRoot,
+            input: JSON.stringify(decision),
+        });
+        if (result.exitCode !== 0)
+            throw new BridgeRecoveryError('Git could not save the branch decision. Retry the same branch operation.', 'task.branch');
+        return result.stdout.trim();
+    }
+}
+//# sourceMappingURL=task-branch-store.js.map

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: engineering-memory
-description: Enforces the Engineering Memory lifecycle for Codex and Claude in repositories bound by .engineering-memory/project.json. Use before answering anything about a bound repository, including a question about what it has or where its design lives, and for every planning, implementation, review, diagnosis, rework, Figma, component, screen, service, model, navigation, localization, storage, validation, or Git task in one.
+description: Enforces the Engineering Memory lifecycle for Codex and Claude in repositories bound in user-local Engineering Memory state. Use before answering anything about a bound repository, including a question about what it has or where its design lives, and for every planning, implementation, review, diagnosis, rework, Figma, component, screen, service, model, navigation, localization, storage, validation, or Git task in one.
 ---
 
 # Engineering Memory
@@ -11,7 +11,9 @@ Read [lifecycle.md](references/lifecycle.md) before acting in a bound repository
 
 Mandatory behavior:
 
-1. Locate `.engineering-memory/project.json` from the working directory toward the repository root. When it exists, the project's knowledge is in the backend and not in the working tree, so answer nothing about the project before bootstrapping — a file search that finds no design link, no screen record and no rule is reporting what the repository lacks, not what the project knows.
+Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. In Codex use request_user_input when available; in Claude use AskUserQuestion. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. Existing answers remain valid through retries and handoffs.
+
+1. Discover the repository binding through `session.entry`. Bindings live in the user-level Engineering Memory state directory, outside the repository and installed runtime. No project settings file is required. For a bound repository, the project's knowledge is in the backend, so answer nothing about it before bootstrapping; the absence of local design files or records says nothing about its stored knowledge.
 2. Call `session.entry` before answering anything in a repository, and act on what it reports before the message itself: sign in when it says so, ask for organization and project when nothing has been decided, and stay completely silent about Engineering Memory in a repository where the user switched it off. Record every one of those answers with `session.set_decision`, and only ever from something the user actually said.
 3. Before planning or editing, call `session.bootstrap`. After compaction, a new chat, interruption, or handoff, call `session.resume` first.
 4. Open the task in `read_only` mode for review, diagnosis, planning, or reporting that does not authorize writes; use `scaffold` mode only to apply organization architecture templates to a new project; otherwise use `write` mode. Do read-only discovery, then record the discovery checkpoint.
@@ -25,6 +27,6 @@ Mandatory behavior:
 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.
 
-If the repository is unbound, do not silently create or attach a project. Use the native questionnaire workflow. If the user selects task-only skip, do not create a marker or memory records.
+If the repository is unbound, do not silently create or attach a project. Use the native questionnaire workflow. If the user selects task-only skip, do not create a binding or memory records.
 
 If the backend is unavailable, use only an unexpired bridge-provided cached context. Checkpoints may enter the local outbox, but verification, task close, and commit remain blocked until synchronization succeeds.