engineering-memory 1.6.0 → 1.6.2

package/package.json

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

@@ -312,13 +312,19 @@ export class BridgeService {
                 resumeIdentityMatches &&
                 conflicts.every(isOfflineDevelopmentWarning) &&
                 isOfflineLeaseUsable(resumedLease, sessionId, pointer?.changeBaseline?.leasePaths ?? [], pointer?.changeBaseline?.diffHash);
-            const resumedBaseline = pointer?.taskId === backendTask.id &&
-                pointer.sessionId === sessionId &&
-                pointer.changeBaseline &&
-                (resumedLease?.baselineDiffHash === pointer.changeBaseline.diffHash ||
-                    objectValue(backend.verificationRecovery)?.diffHash === repository.git.diffHash)
+            const localBaseline = pointer?.taskId === backendTask.id && pointer.sessionId === sessionId
                 ? pointer.changeBaseline
                 : undefined;
+            const recordedBaselineDiffHash = typeof backend.changeBaselineDiffHash === 'string'
+                ? backend.changeBaselineDiffHash
+                : undefined;
+            const repairedBaseline = repairChangeBaseline(localBaseline, recordedBaselineDiffHash, repository.git.head);
+            const resumedBaseline = repairedBaseline ?? localBaseline;
+            if (recordedBaselineDiffHash &&
+                resumedBaseline &&
+                resumedBaseline.diffHash !== recordedBaselineDiffHash) {
+                conflicts.push('task_change_baseline_recaptured');
+            }
             const resumedLastSequence = responseSource === 'stale_cache' && pointer
                 ? Math.max(pointer.lastSequence, numericSequence(backendTask.lastSequence), localJournal.projection?.appliedEventIds.length ?? 0)
                 : numericSequence(backendTask.lastSequence);
@@ -384,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 ?? []),
@@ -416,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;
@@ -970,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) {
@@ -984,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 {
@@ -992,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]));
@@ -1006,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 ?? []);
                 }
@@ -1107,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)
@@ -1136,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);
@@ -2077,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 } : {}),
                 },
             };
         }
@@ -2372,6 +2385,46 @@ 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;
+    if (sha256(`${head ?? '<unborn>'}
+${stableStringify([])}
+`) !== recordedDiffHash) {
+        return undefined;
+    }
+    return {
+        diffHash: recordedDiffHash,
+        changedPaths: [],
+        leasePaths: local?.leasePaths ?? [],
+    };
+}
 function isOfflineDevelopmentWarning(value) {
     return (value === 'backend_resume_is_stale' ||
         value === 'pending_outbox_delivery' ||

package/skill/references/lifecycle.md

@@ -95,6 +95,22 @@ Where the same product has a client and a backend, they are two projects. Adopt
 then link them with `project.link` once both exist, and ask before linking rather than inferring it
 from the names.
 
+## The Task Baseline
+
+A write task's baseline is the tree it started from, and every changed path it reports is the
+difference between that tree and the current one. It is captured once, at the first change
+preparation, and it is never re-captured — a baseline taken again halfway through a task equals the
+finished work, and from then on the task reports the two or three files touched since instead of
+everything it did. Verification then refuses the true path list, and reporting the short one would
+record a task that did something it did not do.
+
+`session.resume` therefore carries the baseline through a lease going stale, expiring, or being
+replaced, and repairs one that has already drifted when the backend's record of the original can be
+proved against the current commit. When it cannot prove it, resume reports
+`task_change_baseline_recaptured`. Do not work around that conflict by reporting a shorter path
+list, and do not edit the pointer file: say what happened, and let the user decide between
+reopening the task and abandoning it.
+
 ## Change Preparation
 
 Skip change preparation for a read-only task. Do not request an edit lease, send changed paths, record `pre_edit`, or reconcile code resources in that mode. If the user later authorizes a change, call `context.prepare_change` with `transitionToWrite: true`, the bridge-owned current task version, intended paths, and current baseline diff. Continue only after the bridge returns the updated write task and lease.