engineering-memory 1.6.1 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "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/runtime/bridge-service.js

@@ -390,7 +390,7 @@ export class BridgeService {
             const pendingOutbox = await this.dependencies.outbox.list();
             const pointer = await this.dependencies.activeContexts.load(repository.repoFingerprint);
             if (pointer?.verificationIntent || pointer?.closeIntent) {
-                throw new Error('Pending lifecycle intent must be recovered before preparing changes');
+                throw refuse('A verification or close intent from an earlier session is still unsettled, so a new lease would be taken against the wrong state.', 'session.resume');
             }
             const conflicts = [
                 ...(pointer?.resumeConflicts ?? []),
@@ -422,7 +422,7 @@ export class BridgeService {
             let transitionTaskVersion;
             if (input.transitionToWrite) {
                 if (!pointer || pointer.sessionId !== input.sessionId) {
-                    throw new Error('Read-only transition requires the active repository session');
+                    throw refuse('A read-only task can only become a write task from the session that owns it.', 'session.resume');
                 }
                 const refreshed = await this.activeTaskSnapshot(pointer.taskId, pointer.projectId, repository.repoRoot);
                 transitionTaskVersion = refreshed.taskVersion;
@@ -976,7 +976,7 @@ export class BridgeService {
                 const snapshotTask = objectValue(snapshot?.task);
                 const activeLease = objectValue(snapshot?.activeLease);
                 if (!snapshotTask || snapshotTask.id !== input.taskId) {
-                    throw new Error('Current backend task snapshot does not match verification');
+                    throw refuse('The backend is holding a different task than the one being verified.', 'session.resume');
                 }
                 const recoveredVerification = await this.retryVerificationRecovery(repository, pointer, snapshot);
                 if (recoveredVerification) {
@@ -990,7 +990,7 @@ export class BridgeService {
                 const validations = normalizePersistentInput(input.validations, repository.repoRoot);
                 if (taskMode === 'read_only') {
                     if (input.leaseId || input.changedPaths?.length) {
-                        throw new Error('Read-only task verification does not accept a lease or changed paths');
+                        throw refuse('This task is read-only, so it has no lease and no changed paths to report.', 'task.verify');
                     }
                 }
                 else {
@@ -998,8 +998,11 @@ export class BridgeService {
                     const leaseChangedPaths = Array.isArray(activeLease?.changedPaths)
                         ? activeLease.changedPaths.filter((path) => typeof path === 'string')
                         : [];
-                    if (!baseline || activeLease?.baselineDiffHash !== baseline.diffHash) {
-                        throw new Error('Write task verification requires its locally pinned change baseline');
+                    if (!baseline) {
+                        throw refuse('This task has no local change baseline, so what it changed cannot be measured. The baseline is restored from the task record.', 'session.resume');
+                    }
+                    if (activeLease?.baselineDiffHash !== baseline.diffHash) {
+                        throw refuse(`The active lease was taken against baseline ${short(activeLease?.baselineDiffHash)} but this task started from ${short(baseline.diffHash)}, so the lease must be taken again against the task's own baseline.`, 'context.prepare_change');
                     }
                     const wholeTreeDelta = manifestDelta(baseline.changedPaths, repository.git.changedPaths);
                     const leased = new Set(normalizeChangedPaths([...baseline.leasePaths, ...leaseChangedPaths]));
@@ -1012,15 +1015,18 @@ export class BridgeService {
                     if (input.changedPaths &&
                         stableStringify(normalizeChangedPaths(input.changedPaths)) !==
                             stableStringify(taskChangedPaths)) {
-                        throw new Error('Reported changed paths do not match the actual Git manifest');
+                        throw refuse(`Reported changed paths do not match the actual Git manifest. ${describePathDisagreement(normalizeChangedPaths(input.changedPaths), taskChangedPaths)} The manifest is the difference between the tree this task started from and the tree now; report exactly what it says. A manifest that looks short means the baseline has moved, and resuming repairs it.`, 'session.resume');
+                    }
+                    if (taskChangedPaths.length === 0) {
+                        throw refuse('The manifest shows this task changed nothing. Either the work is not in the working tree, or the baseline has moved to equal it.', 'session.resume');
                     }
-                    if (taskChangedPaths.length === 0 ||
-                        !activeLease ||
-                        !input.leaseId ||
-                        activeLease.id !== input.leaseId ||
-                        !pathsContainAll(baseline.leasePaths, taskChangedPaths) ||
-                        !pathsContainAll(leaseChangedPaths, taskChangedPaths)) {
-                        throw new Error('Write task verification requires the current backend change lease');
+                    if (!activeLease || !input.leaseId || activeLease.id !== input.leaseId) {
+                        throw refuse(`Verification needs the lease the backend currently holds. It has ${short(activeLease?.id)} and you sent ${short(input.leaseId)}.`, 'context.prepare_change');
+                    }
+                    const unleased = taskChangedPaths.filter((path) => !pathsContainAll(baseline.leasePaths, [path]) ||
+                        !pathsContainAll(leaseChangedPaths, [path]));
+                    if (unleased.length > 0) {
+                        throw refuse(`These changed paths are outside the current lease: ${unleased.slice(0, 5).join(', ')}${unleased.length > 5 ? `, and ${unleased.length - 5} more` : ''}. The lease must cover every path this task changed.`, 'context.prepare_change');
                     }
                     assertNewResourceEvidence(taskChanges.flatMap((entry) => newMemoryResourceCandidate(entry, resourceDiscoveryPolicy)), input.newResources ?? []);
                 }
@@ -1113,7 +1119,7 @@ export class BridgeService {
                 const snapshot = objectValue(snapshotResponse.data);
                 const task = objectValue(snapshot?.task);
                 if (!task || task.id !== input.taskId) {
-                    throw new Error('Current backend task snapshot does not match task close');
+                    throw refuse('The backend is holding a different task than the one being closed.', 'session.resume');
                 }
                 const taskChanges = pointer.changeBaseline
                     ? manifestDelta(pointer.changeBaseline.changedPaths, repository.git.changedPaths)
@@ -1142,7 +1148,7 @@ export class BridgeService {
                 });
                 const abandoned = objectValue(response.data);
                 if (!abandoned || abandoned.abandoned !== true) {
-                    throw new Error('The backend did not abandon the task');
+                    throw refuse('The backend did not record the abandonment, so the task is still open.', 'session.resume');
                 }
                 const forgotten = await this.dependencies.activeContexts.forget(repository.repoFingerprint, input.taskId);
                 await this.dependencies.gate.invalidateTask(input.taskId);
@@ -2083,6 +2089,7 @@ export class BridgeService {
                     kind: 'bridge_error',
                     message: error instanceof Error ? error.message : 'Bridge operation failed',
                     retryable: false,
+                    ...(error instanceof RefusalError ? { recovery: error.recovery } : {}),
                 },
             };
         }
@@ -2378,6 +2385,32 @@ function isOfflineLeaseUsable(lease, sessionId, changedPaths, baselineDiffHash)
         return false;
     }
 }
+class RefusalError extends Error {
+    recovery;
+    constructor(message, recovery) {
+        super(message);
+        this.recovery = recovery;
+    }
+}
+function refuse(message, recovery) {
+    return new RefusalError(`${message} Recovery: call ${recovery}.`, recovery);
+}
+function short(value) {
+    return typeof value === 'string' && value.length > 0 ? value.slice(0, 12) : 'none';
+}
+function describePathDisagreement(reported, manifest) {
+    const inManifest = new Set(manifest);
+    const inReport = new Set(reported);
+    const missing = manifest.filter((path) => !inReport.has(path));
+    const extra = reported.filter((path) => !inManifest.has(path));
+    const sample = (paths) => paths.slice(0, 5).join(', ') + (paths.length > 5 ? `, and ${paths.length - 5} more` : '');
+    const parts = [`You reported ${reported.length}; the manifest has ${manifest.length}.`];
+    if (missing.length > 0)
+        parts.push(`Missing from your report: ${sample(missing)}.`);
+    if (extra.length > 0)
+        parts.push(`Reported but not in the manifest: ${sample(extra)}.`);
+    return parts.join(' ');
+}
 function repairChangeBaseline(local, recordedDiffHash, head) {
     if (!recordedDiffHash || local?.diffHash === recordedDiffHash)
         return undefined;