engineering-memory 1.6.3 → 1.7.0

package/bin/engineering-memory.mjs

@@ -69,6 +69,9 @@ async function main(argumentList) {
       skillSource,
       '--bridge-runtime-source',
       staged,
+      ...(rest.includes('--client-version')
+        ? []
+        : ['--client-version', await publishedVersion()]),
     ]);
   } finally {
     await rm(staged, { recursive: true, force: true });

package/bin/entry-point.test.mjs

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import test from 'node:test';
+
+const entryPoint = new URL('./engineering-memory.mjs', import.meta.url);
+const manifest = new URL('../package.json', import.meta.url);
+
+test('the published entry point tells the installer which version it is', async () => {
+  const source = await readFile(entryPoint, 'utf8');
+
+  assert.match(
+    source,
+    /'--client-version',\s*await publishedVersion\(\)/,
+    'The installer is never told the version, so every install reports itself as unknown and no update is ever offered',
+  );
+});
+
+test('the published entry point tells the installer which backend it was built for', async () => {
+  const source = await readFile(entryPoint, 'utf8');
+
+  assert.match(source, /'--api-url',\s*await publishedApiUrl\(\)/);
+});
+
+test('the manifest carries a version the entry point can stamp', async () => {
+  const declared = JSON.parse(await readFile(manifest, 'utf8'));
+
+  assert.match(String(declared.version), /^\d+\.\d+\.\d+$/);
+  assert.equal(declared.name, 'engineering-memory');
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "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/git/git-inspector.js

@@ -24,12 +24,22 @@ export class GitInspector {
             this.gitValue(repoRoot, ['config', '--get', 'remote.origin.url']),
             this.gitValue(repoRoot, ['rev-list', '--max-parents=0', 'HEAD']),
         ]);
-        const canonicalRoot = await canonicalPath(repoRoot);
         const identity = remote
             ? `${canonicalRemoteIdentity(remote)}\n${firstCommit ?? ''}`
-            : `${canonicalRoot.toLowerCase()}\n${firstCommit ?? ''}`;
+            : `${(await this.mainWorktree(repoRoot)).toLowerCase()}\n${firstCommit ?? ''}`;
         return sha256(identity);
     }
+    async mainWorktree(repoRoot) {
+        const commonDirectory = await this.gitValue(repoRoot, [
+            'rev-parse',
+            '--path-format=absolute',
+            '--git-common-dir',
+        ]);
+        if (!commonDirectory) {
+            return await canonicalPath(repoRoot);
+        }
+        return await canonicalPath(resolve(commonDirectory, '..'));
+    }
     async manifest(repoRoot) {
         const root = await this.findRoot(repoRoot);
         const head = await this.gitValue(root, ['rev-parse', 'HEAD']);

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

@@ -91,7 +91,7 @@ const discoverableKindNames = [
 ];
 const reconciliationEntry = z.object({
     resourceId: z.string().min(1),
-    type: z.enum(['approved_revision', 'no_semantic_memory_change']),
+    type: z.enum(['approved_revision', 'no_semantic_memory_change', 'scaffold_applied']),
     proposalId: z.string().optional(),
     revisionId: z.string().optional(),
     reason: z.string().optional(),
@@ -130,6 +130,7 @@ export function registerEngineeringMemoryTools(server, service) {
             externalTaskId: z.string().min(2),
             objective: z.string().min(2),
             taskKind: z.string().min(2),
+            workItemKey: z.string().min(1).optional(),
             mode: z.enum(['write', 'read_only', 'scaffold']).optional(),
             knownRevisions: z.record(z.string(), z.number().int().min(0)).optional(),
         }),
@@ -287,7 +288,9 @@ export function registerEngineeringMemoryTools(server, service) {
             taskId: z.string().min(1),
             entries: z.array(reconciliationEntry).min(1).max(50).optional(),
             resourceId: z.string().min(1).optional(),
-            type: z.enum(['approved_revision', 'no_semantic_memory_change']).optional(),
+            type: z
+                .enum(['approved_revision', 'no_semantic_memory_change', 'scaffold_applied'])
+                .optional(),
             proposalId: z.string().optional(),
             revisionId: z.string().optional(),
             reason: z.string().optional(),
@@ -326,6 +329,12 @@ export function registerEngineeringMemoryTools(server, service) {
                         message: 'No-semantic-change reconciliation requires a reason of at least 8 characters',
                     });
                 }
+                if (entry.type === 'scaffold_applied' && (!entry.reason || entry.reason.length < 8)) {
+                    context.addIssue({
+                        code: 'custom',
+                        message: 'Scaffold-applied reconciliation requires a reason of at least 8 characters',
+                    });
+                }
             }
         }),
     }, async (input) => toolResult(await service.taskReconcile(input)));

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

@@ -13,12 +13,14 @@ export class ApiResponseError extends Error {
     code;
     retryable;
     envelope;
-    constructor(message, httpStatus, code, retryable, envelope) {
+    recovery;
+    constructor(message, httpStatus, code, retryable, envelope, recovery = null) {
         super(message);
         this.httpStatus = httpStatus;
         this.code = code;
         this.retryable = retryable;
         this.envelope = envelope;
+        this.recovery = recovery;
         this.name = 'ApiResponseError';
     }
 }
@@ -106,7 +108,9 @@ export class ApiClient {
                 this.responseSources.set(cached.value, 'stale_cache');
                 return cached.value;
             }
-            throw new ApiResponseError(envelope.errorModel?.text ?? envelope.message ?? `Backend returned ${response.status}`, response.status, envelope.errorModel?.code ?? null, response.status === 408 || response.status === 429 || response.status >= 500, envelope);
+            const recovery = envelope.errorModel?.recovery ?? null;
+            const refusal = envelope.errorModel?.text ?? envelope.message ?? `Backend returned ${response.status}`;
+            throw new ApiResponseError(recovery ? `${refusal} Recovery: call ${recovery}.` : refusal, response.status, envelope.errorModel?.code ?? null, response.status === 408 || response.status === 429 || response.status >= 500, envelope, recovery);
         }
         if (request.cacheKey) {
             await this.options.cache.set(cacheKey, response.headers.get('etag'), envelope);

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

@@ -53,6 +53,7 @@ export class BridgeService {
                 externalTaskId: input.externalTaskId,
                 objective: input.objective,
                 taskKind: input.taskKind,
+                workItemKey: input.workItemKey,
                 mode: input.mode,
                 knownRevisions: input.knownRevisions,
             }, repository.repoRoot);
@@ -81,7 +82,7 @@ export class BridgeService {
                 });
             }
             if (!projectId) {
-                throw new Error('Repository marker does not contain a project binding');
+                throw refuse('This repository has a marker that names no project, so there is nothing to bootstrap against.', 'project.resolve');
             }
             const checkpointId = deterministicUuid('session.bootstrap', projectId, repository.repoFingerprint, input.externalTaskId);
             const response = await this.dependencies.client.request(endpoints.sessionBootstrap, {
@@ -92,6 +93,7 @@ export class BridgeService {
                     externalTaskId: persistedBootstrap.externalTaskId,
                     objective: persistedBootstrap.objective,
                     taskKind: persistedBootstrap.taskKind,
+                    workItemKey: persistedBootstrap.workItemKey,
                     mode: persistedBootstrap.mode ?? 'write',
                     repoFingerprint: repository.repoFingerprint,
                     ...(input.mode === 'read_only'
@@ -116,7 +118,7 @@ export class BridgeService {
                 checkpointEvent.idempotencyKey !== checkpointId ||
                 typeof checkpointPayload?.createdAt !== 'string' ||
                 !isIsoTimestamp(checkpointPayload.createdAt)) {
-                throw new Error('Session bootstrap response is missing canonical checkpoint data');
+                throw refuse('The backend opened the session without the checkpoint the task is anchored to.', 'session.bootstrap');
             }
             const pointer = {
                 repoFingerprint: repository.repoFingerprint,
@@ -200,14 +202,14 @@ export class BridgeService {
             const taskSlug = input.taskSlug ?? pointer?.taskSlug;
             const sessionId = input.sessionId ?? pointer?.sessionId;
             if (!projectId || !taskSlug || !sessionId) {
-                throw new Error('No active Engineering Memory task is available for this repository');
+                throw refuse('This repository has no live task to resume.', 'session.bootstrap');
             }
             if ((pointer &&
                 (pointer.projectId !== projectId ||
                     pointer.taskSlug !== taskSlug ||
                     pointer.sessionId !== sessionId)) ||
                 (repository.projectId && repository.projectId !== projectId)) {
-                throw new Error('Active task pointer does not match the repository project binding');
+                throw refuse('The live task belongs to a different project than the one this repository is bound to.', 'project.resolve');
             }
             if (pointer?.closeIntent) {
                 const recoveredClose = await this.retryCloseIntent(repository, pointer);
@@ -245,7 +247,7 @@ export class BridgeService {
                 typeof backendTask.id !== 'string' ||
                 typeof backendSession.id !== 'string' ||
                 backendSession.id !== sessionId) {
-                throw new Error('Session resume response is missing the active task snapshot');
+                throw refuse('The backend resumed the session without the task it belongs to.', 'session.resume');
             }
             let localJournal = await this.dependencies.journal.load(projectId, taskSlug);
             let pendingOutbox = await this.dependencies.outbox.list();
@@ -545,11 +547,11 @@ export class BridgeService {
                 .map((entry) => objectValue(entry))
                 .find((entry) => entry?.projectId === input.projectId);
             if (!project) {
-                throw new Error('That project has no repository address recorded, or this account is not a member of it. An organization owner records the address.');
+                throw refuse('That project has no repository address recorded, or this account is not a member of it. An organization owner records the address.', 'project.list');
             }
             const result = await this.dependencies.repositories.git.clone(String(project.repositoryUrl), input.targetPath);
             if (!result.cloned) {
-                throw new Error(`The repository could not be cloned: ${result.reason}. Engineering Memory never handles Git credentials, so this is between the developer's own Git configuration and the host.`);
+                throw refuse(`The repository could not be cloned: ${result.reason}. Engineering Memory never handles Git credentials, so this is between the developer's own Git configuration and the host.`, 'project.clone');
             }
             return asJsonValue({
                 cloned: true,
@@ -834,7 +836,7 @@ export class BridgeService {
         return await this.execute(async () => {
             const entry = await this.dependencies.outbox.get(input.outboxId);
             if (!entry) {
-                throw new Error('Pending delivery could not be found');
+                throw refuse('There is no pending delivery under that identifier.', 'session.resume');
             }
             const metadata = {
                 id: entry.id,
@@ -866,7 +868,7 @@ export class BridgeService {
                 return asJsonValue({ discarded: true, taskId, pendingDelivery: metadata });
             }
             if (!entry.lastError?.startsWith('api_409_')) {
-                throw new Error('Only a confirmed backend version conflict can be rebased');
+                throw refuse('This delivery did not fail on a version conflict, so rebasing it is not the repair.', 'session.resume');
             }
             if (entry.journalRef) {
                 const taskSnapshot = await this.refreshTaskPointer(taskId, entry.journalRef.projectId);
@@ -883,7 +885,7 @@ export class BridgeService {
                 });
             }
             if (entry.operation !== 'memory.propose_revision' || !taskId) {
-                throw new Error('This delivery cannot be safely rebased and must be discarded or retried');
+                throw refuse('This delivery cannot be rebased safely; discard it or retry it as it stands.', 'task.resolve_pending_delivery');
             }
             if (!input.proposalRebaseApproved || input.confirmedBaseRevision === undefined) {
                 return asJsonValue({
@@ -897,7 +899,7 @@ export class BridgeService {
             const projectId = typeof proposal?.projectId === 'string' ? proposal.projectId : null;
             const queuedBaseRevision = proposal?.baseRevision;
             if (!projectId || typeof queuedBaseRevision !== 'number') {
-                throw new Error('Queued proposal cannot establish its project revision contract');
+                throw refuse('The queued proposal does not carry the revision it was written against.', 'memory.propose_revision');
             }
             if (queuedBaseRevision !== input.confirmedBaseRevision) {
                 return asJsonValue({
@@ -918,7 +920,7 @@ export class BridgeService {
             const refreshData = objectValue(refreshed.data);
             const refreshedTask = objectValue(refreshData?.task);
             if (!refreshedTask || refreshedTask.id !== taskId) {
-                throw new Error('Context refresh did not return the queued proposal task');
+                throw refuse('The refresh did not return the task this queued proposal belongs to.', 'session.resume');
             }
             const expectedTaskVersion = numericTaskVersion(refreshedTask.lockVersion);
             const rebasedBody = cleanJson({ ...proposal, expectedTaskVersion });
@@ -1189,7 +1191,7 @@ export class BridgeService {
                 initialProjectProfile: input.initialProjectProfile,
             });
             if ('resourceDiscovery' in input.initialProjectProfile.metadata) {
-                throw new Error('Project setup metadata cannot override canonical resource discovery');
+                throw refuse('Project setup metadata cannot override canonical resource discovery', 'project.setup');
             }
             const persistentBody = normalizeRepositoryPaths(body, repository.repoRoot);
             assertSafeToPersist(persistentBody);
@@ -1212,7 +1214,7 @@ export class BridgeService {
                 !marker ||
                 marker.projectId !== project.id ||
                 readDiscoveryUnits(policy).length === 0) {
-                throw new Error('Project setup response is not policy-ready');
+                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 });
@@ -1272,7 +1274,7 @@ export class BridgeService {
             const files = await Promise.all(input.files.map(async (file) => {
                 const hash = await hashWorkingTreeFile(repository.repoRoot, file.path);
                 if (!hash) {
-                    throw new Error(`Applied template file is not readable: ${file.path}`);
+                    throw refuse(`Applied template file is not readable: ${file.path}`, 'architecture.record_application');
                 }
                 return { templatePath: file.templatePath, path: file.path, sha256: hash };
             }));
@@ -1332,7 +1334,7 @@ export class BridgeService {
                 });
                 const project = objectValue(response.data);
                 if (!project || project.id !== input.projectId) {
-                    throw new Error('Project bind response does not match the selected project');
+                    throw refuse('Project bind response does not match the selected project', 'project.resolve');
                 }
                 const markerPath = await this.dependencies.repositories.writeMarker(repository.repoRoot, input.projectId);
                 return asJsonValue({
@@ -1589,7 +1591,7 @@ export class BridgeService {
                     (entry.operation === 'task.checkpoint' || entry.operation === 'task.record_correction'));
                 const blockedEntry = taskEntries.find((entry) => entry.lastError && entry.lastError !== 'backend_unavailable');
                 if (blockedEntry && blockedEntry.idempotencyKey !== idempotencyKey) {
-                    throw new Error('A blocked task delivery must be explicitly resolved before checkpointing');
+                    throw refuse('A blocked task delivery must be explicitly resolved before checkpointing', 'task.resolve_pending_delivery');
                 }
                 const existingExpected = pendingJournal
                     ? expectedTaskVersionFromBody(pendingJournal.body)
@@ -1605,7 +1607,7 @@ export class BridgeService {
                     correction,
                 });
                 if (!staged.delivery) {
-                    throw new Error('Task journal delivery was not materialized');
+                    throw refuse('Task journal delivery was not materialized', 'task.resolve_pending_delivery');
                 }
                 const queued = await this.dependencies.outbox.enqueue({
                     operation: staged.delivery.operation,
@@ -1760,10 +1762,10 @@ export class BridgeService {
         const pointer = await this.requireActivePointer(repository.repoFingerprint, taskId);
         if ((projectId && pointer.projectId !== projectId) ||
             (repository.projectId && pointer.projectId !== repository.projectId)) {
-            throw new Error('Active task snapshot does not match the repository project');
+            throw refuse('Active task snapshot does not match the repository project', 'session.resume');
         }
         if ((await this.dependencies.outbox.list()).some((entry) => taskIdFromDeliverySafe(entry) === taskId)) {
-            throw new Error('Pending task deliveries must be resolved before using the task snapshot');
+            throw refuse('Pending task deliveries must be resolved before using the task snapshot', 'task.resolve_pending_delivery');
         }
         const response = await this.dependencies.client.request(endpoints.sessionResume, {
             method: 'POST',
@@ -1776,7 +1778,7 @@ export class BridgeService {
         const backend = objectValue(response.data);
         const task = objectValue(backend?.task);
         if (!task || task.id !== taskId || backend?.requiresContextRefresh === true) {
-            throw new Error('Backend task snapshot is stale or does not match the active task');
+            throw refuse('Backend task snapshot is stale or does not match the active task', 'session.resume');
         }
         const refreshed = {
             ...pointer,
@@ -1799,7 +1801,7 @@ export class BridgeService {
         const backend = objectValue(response.data);
         const task = objectValue(backend?.task);
         if (!task || task.id !== taskId || backend?.requiresContextRefresh === true) {
-            throw new Error('Backend task snapshot is stale or does not match the pending delivery');
+            throw refuse('Backend task snapshot is stale or does not match the pending delivery', 'session.resume');
         }
         const refreshed = {
             ...pointer,
@@ -1818,7 +1820,7 @@ export class BridgeService {
             pointer.taskId !== taskId ||
             (blockingConflicts?.length ?? 0) > 0 ||
             lifecycleIntentBlocked) {
-            throw new Error('A clean active task snapshot is required for this operation');
+            throw refuse('A clean active task snapshot is required for this operation', 'session.resume');
         }
         return pointer;
     }
@@ -1847,7 +1849,7 @@ export class BridgeService {
             backendTask.projectId !== pointer.projectId ||
             backendSession?.id !== pointer.sessionId ||
             body.pendingOutboxCount !== 0) {
-            throw new Error('Verification recovery does not match the durable verification intent');
+            throw refuse('Verification recovery does not match the durable verification intent', 'session.resume');
         }
         if (recovery) {
             const recoveryTaskVersion = numericTaskVersion(recovery.taskVersion);
@@ -1855,12 +1857,12 @@ export class BridgeService {
                 recovery.mode !== intent.mode ||
                 (recoveryTaskVersion !== expectedTaskVersion &&
                     recoveryTaskVersion !== expectedTaskVersion + 1)) {
-                throw new Error('Verification recovery does not match the verified backend task');
+                throw refuse('Verification recovery does not match the verified backend task', 'session.resume');
             }
         }
         else if (numericTaskVersion(backendTask.lockVersion) !== expectedTaskVersion ||
             normalizeTaskMode(backendTask.mode) !== intent.mode) {
-            throw new Error('Open backend task does not match the durable verification intent');
+            throw refuse('Open backend task does not match the durable verification intent', 'session.resume');
         }
         const currentTaskChanges = intent.mode !== 'read_only'
             ? pointer.changeBaseline
@@ -1868,7 +1870,7 @@ export class BridgeService {
                 : null
             : [];
         if (!currentTaskChanges) {
-            throw new Error('Verification recovery is missing its locally pinned baseline');
+            throw refuse('Verification recovery is missing its locally pinned baseline', 'session.resume');
         }
         const currentChangedPaths = currentTaskChanges.map((entry) => entry.path).sort();
         const currentPathChanges = intent.mode === 'read_only'
@@ -1878,7 +1880,7 @@ export class BridgeService {
             stableStringify(body.pathChanges ?? null) !== stableStringify(currentPathChanges) ||
             stableStringify(intent.taskChanges.map(changedPathIdentity)) !==
                 stableStringify(currentTaskChanges.map(changedPathIdentity))) {
-            throw new Error('Current Git state does not match the durable verification intent');
+            throw refuse('Current Git state does not match the durable verification intent', 'session.resume');
         }
         if (intent.mode !== 'read_only') {
             const retryLease = recovery
@@ -1894,13 +1896,13 @@ export class BridgeService {
                 retryLease.baselineDiffHash !== body.baselineDiffHash ||
                 body.baselineDiffHash !== pointer.changeBaseline?.diffHash ||
                 !pathsContainAll(retryLeasePaths, currentChangedPaths)) {
-                throw new Error('Backend lease does not match the durable verification intent');
+                throw refuse('Backend lease does not match the durable verification intent', 'context.prepare_change');
             }
         }
         else if (currentChangedPaths.length !== 0 ||
             body.leaseId !== undefined ||
             body.baselineDiffHash !== undefined) {
-            throw new Error('Read-only verification recovery contains a write lease');
+            throw refuse('Read-only verification recovery contains a write lease', 'task.verify');
         }
         let response;
         try {
@@ -1918,7 +1920,7 @@ export class BridgeService {
         const responseData = objectValue(response.data);
         if (responseData?.verified !== true || responseData.diffHash !== body.diffHash) {
             await this.dependencies.activeContexts.clearVerificationIntent(repository.repoFingerprint, pointer.taskId);
-            throw new Error('Verification retry did not confirm the durable verification intent');
+            throw refuse('Verification retry did not confirm the durable verification intent', 'session.resume');
         }
         const taskVersion = numericTaskVersion(responseData.taskVersion);
         await this.dependencies.gate.record({
@@ -1937,7 +1939,7 @@ export class BridgeService {
     async retryCloseIntent(repository, pointer) {
         const intent = pointer.closeIntent;
         if (!intent) {
-            throw new Error('Durable close intent is unavailable');
+            throw refuse('Durable close intent is unavailable', 'session.resume');
         }
         const body = intent.body;
         const currentTaskChanges = pointer.changeBaseline
@@ -1949,7 +1951,7 @@ export class BridgeService {
             pointer.sessionId !== body.sessionId ||
             stableStringify(intent.taskChanges.map(changedPathIdentity)) !==
                 stableStringify(currentTaskChanges.map(changedPathIdentity))) {
-            throw new Error('Current state does not match the durable close intent');
+            throw refuse('Current state does not match the durable close intent', 'session.resume');
         }
         return await this.deliverCloseIntent(repository, body, intent.taskChanges, true);
     }
@@ -1971,7 +1973,7 @@ export class BridgeService {
         const closedTask = objectValue(response.data);
         if (closedTask?.closed !== true) {
             await this.dependencies.activeContexts.clearCloseIntent(repository.repoFingerprint, String(body.taskId));
-            throw new Error('Task close response does not confirm task closure');
+            throw refuse('Task close response does not confirm task closure', 'session.resume');
         }
         const closedTaskVersion = numericTaskVersion(closedTask.taskVersion);
         await this.dependencies.gate.record({
@@ -2040,13 +2042,13 @@ export class BridgeService {
             })()
             : await this.dependencies.activeContexts.findByTaskId(input.taskId, input.projectId, false);
         if (pointer.resumeConflicts.some((conflict) => !isOfflineDevelopmentWarning(conflict))) {
-            throw new Error('A clean active task snapshot is required for checkpointing');
+            throw refuse('A clean active task snapshot is required for checkpointing', 'session.resume');
         }
         if (pointer.verificationIntent || pointer.closeIntent) {
-            throw new Error('A clean active task snapshot is required for checkpointing');
+            throw refuse('A clean active task snapshot is required for checkpointing', 'session.resume');
         }
         if (pointer.taskSlug.toLowerCase() !== input.taskSlug.toLowerCase()) {
-            throw new Error(`Checkpoint task slug ${input.taskSlug} does not match the active task ${pointer.taskSlug}`);
+            throw refuse(`Checkpoint task slug ${input.taskSlug} does not match the active task ${pointer.taskSlug}`, 'session.resume');
         }
         return pointer;
     }
@@ -2095,6 +2097,7 @@ export class BridgeService {
                         message: error.message,
                         code: error.code ?? error.httpStatus,
                         retryable: error.retryable,
+                        ...(error.recovery ? { recovery: error.recovery } : {}),
                     },
                 };
             }
@@ -2117,7 +2120,7 @@ function normalizeChangedPaths(paths) {
             path.startsWith('/') ||
             /^[A-Za-z]:\//.test(path) ||
             path.split('/').includes('..')) {
-            throw new Error(`Changed path must be repository-relative: ${path}`);
+            throw refuse(`Changed path must be repository-relative: ${path}`, 'context.prepare_change');
         }
     }
     return [...new Set(normalized)].sort();
@@ -2172,7 +2175,7 @@ function semanticGitStatus(status) {
 function semanticPathStatus(status) {
     const semantic = semanticGitStatus(status);
     if (!['A', 'R', 'C', 'M', 'D', 'T', 'U'].includes(semantic)) {
-        throw new Error(`Unsupported semantic Git status: ${status}`);
+        throw refuse(`Unsupported semantic Git status: ${status}`, 'task.verify');
     }
     return semantic;
 }
@@ -2342,6 +2345,7 @@ function publicError(error) {
             httpStatus: error.httpStatus,
             code: error.code,
             retryable: error.retryable,
+            ...(error.recovery ? { recovery: error.recovery } : {}),
         });
     }
     return asJsonValue({
@@ -2356,7 +2360,7 @@ function isBackendUnavailableError(error) {
 function numericSequence(value) {
     const sequence = typeof value === 'number' ? value : Number(value ?? 0);
     if (!Number.isSafeInteger(sequence) || sequence < 0) {
-        throw new Error('Backend task sequence is invalid');
+        throw refuse('Backend task sequence is invalid', 'session.resume');
     }
     return sequence;
 }
@@ -2367,7 +2371,7 @@ function isIsoTimestamp(value) {
 function numericTaskVersion(value) {
     const version = typeof value === 'number' ? value : Number(value);
     if (!Number.isSafeInteger(version) || version < 1) {
-        throw new Error('Backend task version is invalid');
+        throw refuse('Backend task version is invalid', 'session.resume');
     }
     return version;
 }
@@ -2385,7 +2389,7 @@ function validateOfflineLease(value, sessionId, changedPaths, baselineDiffHash)
         stableStringify(normalizeChangedPaths(leasePaths)) !== stableStringify(changedPaths) ||
         !Number.isFinite(expiresAt) ||
         expiresAt <= Date.now()) {
-        throw new Error('Cached change lease is missing, expired or does not match the current Git state');
+        throw refuse('Cached change lease is missing, expired or does not match the current Git state', 'context.prepare_change');
     }
 }
 function isOfflineLeaseUsable(lease, sessionId, changedPaths, baselineDiffHash) {
@@ -2450,7 +2454,7 @@ function isOfflineDevelopmentWarning(value) {
 function taskIdFromDelivery(value) {
     const body = objectValue(value);
     if (!body || typeof body.taskId !== 'string') {
-        throw new Error('Pending task delivery does not contain a task identifier');
+        throw refuse('Pending task delivery does not contain a task identifier', 'task.resolve_pending_delivery');
     }
     return body.taskId;
 }
@@ -2511,7 +2515,7 @@ export function newMemoryResourceCandidate(entry, policy) {
     if (policy) {
         const matched = policy.units.filter((unit) => unit.patterns.some((pattern) => globMatches(entry.path, pattern)));
         if (matched.length > 1) {
-            throw new Error(`Resource discovery policy is ambiguous for path: ${entry.path}`);
+            throw refuse(`Resource discovery policy is ambiguous for path: ${entry.path}`, 'memory.propose_revision');
         }
         return matched[0] ? [{ path: entry.path, kind: matched[0].kind }] : [];
     }
@@ -2565,7 +2569,7 @@ function readResourceDiscoveryPolicy(snapshot, activeLease) {
     }
     const units = readDiscoveryUnits(discovery);
     if (units.length === 0) {
-        throw new Error('Pinned resource discovery policy is incomplete');
+        throw refuse('Pinned resource discovery policy is incomplete', 'context.refresh');
     }
     return { units };
 }
@@ -2602,7 +2606,7 @@ function globMatches(path, pattern) {
         normalizedPattern.startsWith('/') ||
         /^[A-Za-z]:\//.test(normalizedPattern) ||
         normalizedPattern.split('/').includes('..')) {
-        throw new Error(`Resource discovery pattern is unsafe: ${pattern}`);
+        throw refuse(`Resource discovery pattern is unsafe: ${pattern}`, 'memory.propose_revision');
     }
     return minimatch(path.replace(/\\/g, '/'), normalizedPattern, { dot: true });
 }
@@ -2612,10 +2616,10 @@ function assertNewResourceEvidence(candidates, evidence) {
         path: normalizeChangedPaths([entry.path])[0],
     }));
     if (normalizedEvidence.some((entry) => entry.resourceKey.trim().length < 2)) {
-        throw new Error('New resource evidence requires a memory resource key');
+        throw refuse('New resource evidence requires a memory resource key', 'memory.propose_revision');
     }
     if (new Set(normalizedEvidence.map((entry) => entry.path)).size !== normalizedEvidence.length) {
-        throw new Error('New resource evidence contains duplicate paths');
+        throw refuse('New resource evidence contains duplicate paths', 'task.verify');
     }
     const expected = [...candidates].sort((left, right) => left.path.localeCompare(right.path));
     const actual = normalizedEvidence
@@ -2634,27 +2638,27 @@ function assertNewResourceEvidence(candidates, evidence) {
             missing.length ? `missing evidence for ${missing.join(', ')}` : '',
             extra.length ? `evidence for paths the policy does not classify: ${extra.join(', ')}` : '',
         ].filter(Boolean);
-        throw new Error(`New screen or shared component paths require exact memory reconciliation. ${details.length ? details.join('; ') : 'The kinds do not match the project discovery policy.'}`);
+        throw refuse(`New screen or shared component paths require exact memory reconciliation. ${details.length ? details.join('; ') : 'The kinds do not match the project discovery policy.'}`, 'task.verify');
     }
 }
 function assertValidationEvidence(validations) {
     if (validations.length === 0) {
-        throw new Error('Validation evidence is required');
+        throw refuse('Validation evidence is required', 'task.verify');
     }
     const allowed = new Set(validationIds);
     const seen = new Set();
     for (const validation of validations) {
         if (!allowed.has(validation.validationId)) {
-            throw new Error(`Unknown validation evidence: ${validation.validationId}`);
+            throw refuse(`Unknown validation evidence: ${validation.validationId}`, 'task.verify');
         }
         if (seen.has(validation.validationId)) {
-            throw new Error(`Duplicate validation evidence: ${validation.validationId}`);
+            throw refuse(`Duplicate validation evidence: ${validation.validationId}`, 'task.verify');
         }
         if (!validation.command.trim()) {
-            throw new Error(`Validation command is required: ${validation.validationId}`);
+            throw refuse(`Validation command is required: ${validation.validationId}`, 'task.verify');
         }
         if (!/^[0-9a-f]{64}$/.test(validation.outputHash)) {
-            throw new Error(`Validation output hash is invalid: ${validation.validationId}`);
+            throw refuse(`Validation output hash is invalid: ${validation.validationId}`, 'task.verify');
         }
         seen.add(validation.validationId);
     }

package/skill/references/lifecycle.md

@@ -10,6 +10,8 @@ For a bound repository, call `session.bootstrap` before producing a plan or chan
 
 Before the first edit of a write task, settle the branch. Ask the user through the native questionnaire whether to open a branch for this task and which name to use, offering the convention the returned rules carry. Do this once, at the start, not at commit time — the commit gate runs long after the work is written, and by then the wrong branch has already cost something. A read-only task never creates a branch.
 
+Two tasks in one repository need two branches, and one working tree can only have one checked out. A second checkout is what `git worktree` is for: `git worktree add ../<repo>-<task> -b <branch>` gives the task its own directory and its own branch against the same repository, and the chat for that task runs there. Engineering Memory treats them as one project — the fingerprint comes from the repository, not the directory — while each task measures only what changed in its own tree. Offer this when a task starts in a repository that already has a live task, and never ask somebody to switch branches in a tree another task is using.
+
 A repository holds as many tasks as the people working in it. Never treat somebody else's unfinished task as a reason this one cannot proceed: no task waits on another task's review, reconciliation, verification or close, and nothing that is already verified or closed is undone by what happens elsewhere. When `session.resume` reports more than one live task for this repository, it lists them and the right move is to ask the user which one this is, never to guess and never to adopt the one that happens to be most recent.
 
 A task nobody is going to finish is abandoned rather than inherited. Ask the user first, then call `task.abandon` with the task ID and their reason: it records the task as abandoned, withdraws the proposals it left waiting for review, releases its lease and session, and removes its local pointer. It changes nothing about any other task. Never abandon a task on your own judgement, and never abandon one to get past an error in your own.

package/skill/references/questionnaires.md

@@ -60,7 +60,7 @@ Ask for the registered email and intended role. Show owner, maintainer, member,
 
 ## Branch
 
-At the start of a write task, before the first edit, ask whether to open a branch for it and confirm the name. Offer the convention the returned engineering rules state, the current branch as the alternative, and let the user name something else. Never create a branch during read-only analysis, and never create one without asking.
+At the start of a write task, before the first edit, ask whether to open a branch for it and confirm the name. Offer the convention the returned engineering rules state, the current branch as the alternative, and let the user name something else. Never create a branch during read-only analysis, and never create one without asking. When the repository already has another live task, add a third option — a separate worktree for this one — and say what it means: its own directory, its own branch, the same project, and the other task's tree left alone.
 
 ## Flow Entry and Exit