engineering-memory 1.6.2 → 1.6.4

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.2",
+  "version": "1.6.4",
   "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/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,
@@ -163,9 +165,16 @@ export class BridgeService {
                 return asJsonValue({ authentication, repository: publicRepository(repository) });
             }
             const live = await this.dependencies.activeContexts.list(repository.repoFingerprint);
-            let pointer = input.taskSlug
-                ? (live.find((entry) => entry.taskSlug === input.taskSlug) ?? null)
-                : await this.dependencies.activeContexts.load(repository.repoFingerprint);
+            let pointer = null;
+            if (input.taskSlug) {
+                pointer = live.find((entry) => entry.taskSlug === input.taskSlug) ?? null;
+            }
+            else if (input.sessionId) {
+                pointer = live.find((entry) => entry.sessionId === input.sessionId) ?? null;
+            }
+            else if (live.length === 1) {
+                pointer = live[0];
+            }
             if (!pointer && input.taskSlug) {
                 return asJsonValue({
                     taskChoiceRequired: true,
@@ -174,7 +183,15 @@ export class BridgeService {
                     repository: publicRepository(repository),
                 });
             }
-            if (!pointer && !input.sessionId && live.length > 1) {
+            if (!pointer && input.sessionId && live.length > 0) {
+                return asJsonValue({
+                    taskChoiceRequired: true,
+                    requestedSessionId: input.sessionId,
+                    liveTasks: live.map(describePointer),
+                    repository: publicRepository(repository),
+                });
+            }
+            if (!pointer && live.length > 1) {
                 return asJsonValue({
                     taskChoiceRequired: true,
                     liveTasks: live.map(describePointer),
@@ -185,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);
@@ -230,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();
@@ -530,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,
@@ -819,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,
@@ -851,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);
@@ -868,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({
@@ -882,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({
@@ -903,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 });
@@ -1174,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);
@@ -1197,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 });
@@ -1257,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 };
             }));
@@ -1317,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({
@@ -1574,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)
@@ -1590,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,
@@ -1745,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',
@@ -1761,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,
@@ -1784,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,
@@ -1803,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;
     }
@@ -1832,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);
@@ -1840,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
@@ -1853,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'
@@ -1863,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
@@ -1879,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 {
@@ -1903,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({
@@ -1922,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
@@ -1934,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);
     }
@@ -1956,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({
@@ -2025,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;
     }
@@ -2080,6 +2097,7 @@ export class BridgeService {
                         message: error.message,
                         code: error.code ?? error.httpStatus,
                         retryable: error.retryable,
+                        ...(error.recovery ? { recovery: error.recovery } : {}),
                     },
                 };
             }
@@ -2102,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();
@@ -2157,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;
 }
@@ -2327,6 +2345,7 @@ function publicError(error) {
             httpStatus: error.httpStatus,
             code: error.code,
             retryable: error.retryable,
+            ...(error.recovery ? { recovery: error.recovery } : {}),
         });
     }
     return asJsonValue({
@@ -2341,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;
 }
@@ -2352,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;
 }
@@ -2370,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) {
@@ -2435,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;
 }
@@ -2496,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 }] : [];
     }
@@ -2550,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 };
 }
@@ -2587,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 });
 }
@@ -2597,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
@@ -2619,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);
     }