engineering-memory 1.10.5 → 1.11.1

package/package.json

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

@@ -82,6 +82,118 @@ export class GitInspector {
     async currentBranch(repoRoot) {
         return await this.gitValue(repoRoot, ['symbolic-ref', '--short', '-q', 'HEAD']);
     }
+    async sourceIdentity(repoRoot, ref = 'HEAD') {
+        const sourceCommit = await this.gitValue(repoRoot, [
+            'rev-parse',
+            '--verify',
+            '--end-of-options',
+            `${ref}^{commit}`,
+        ]);
+        if (!sourceCommit)
+            return null;
+        const treeHash = await this.gitValue(repoRoot, [
+            'rev-parse',
+            '--verify',
+            `${sourceCommit}^{tree}`,
+        ]);
+        if (!treeHash ||
+            !/^([a-f0-9]{40}|[a-f0-9]{64})$/.test(sourceCommit) ||
+            !/^([a-f0-9]{40}|[a-f0-9]{64})$/.test(treeHash))
+            throw new Error('Git did not return an exact commit and tree identity');
+        return { sourceCommit, treeHash };
+    }
+    async committedTaskProof(repoRoot, source, changes) {
+        const result = await this.sourceIdentity(repoRoot);
+        if (!result)
+            throw new Error('The task result has not been committed');
+        const baseline = await this.sourceIdentity(repoRoot, source.sourceCommit);
+        if (!baseline ||
+            baseline.treeHash !== source.treeHash ||
+            result.sourceCommit === source.sourceCommit)
+            throw new Error('The verified task base is unavailable or differs from its recorded tree. Inspect the resulting commit with memory.sync_start.');
+        const output = await this.runner.run('git', [
+            'diff',
+            '--raw',
+            '-z',
+            '--no-abbrev',
+            '--no-renames',
+            source.sourceCommit,
+            result.sourceCommit,
+            '--',
+        ], { cwd: repoRoot });
+        if (output.exitCode !== 0)
+            throw new Error('The committed task diff could not be read');
+        const expected = new Map();
+        const deleted = new Set();
+        for (const entry of changes) {
+            const status = semanticStatus(entry.status);
+            expected.set(entry.path, {
+                path: entry.path,
+                blobOid: status === 'D' ? null : entry.blobOid,
+                mode: status === 'D' ? null : entry.mode,
+            });
+            if (status === 'R' && entry.originalPath)
+                deleted.add(entry.originalPath);
+        }
+        for (const path of deleted)
+            if (!expected.has(path))
+                expected.set(path, { path, blobOid: null, mode: null });
+        const actual = [];
+        const tokens = output.stdout.split('\0').filter(Boolean);
+        for (let i = 0; i < tokens.length;) {
+            const header = tokens[i++].split(' ');
+            const path = normalizeGitPath(tokens[i++] ?? '');
+            if (header.length !== 5 ||
+                !header[0]?.startsWith(':') ||
+                !['A', 'M', 'D'].includes(header[4]))
+                throw new Error('Unsupported committed change; inspect this source explicitly.');
+            actual.push({
+                path,
+                blobOid: header[4] === 'D' ? null : header[3],
+                mode: header[4] === 'D' ? null : header[1],
+            });
+        }
+        const order = (a, b) => a.path.localeCompare(b.path);
+        if (!expected.size ||
+            stableStringify([...expected.values()].sort(order)) !== stableStringify(actual.sort(order)))
+            throw new Error('The committed tree differs from this task verified files. Inspect the resulting source with memory.sync_start.');
+        return { ...result, baseCommit: source.sourceCommit };
+    }
+    async sourceCandidates(repoRoot) {
+        const current = await this.sourceIdentity(repoRoot);
+        const output = await this.runner.run('git', [
+            'for-each-ref',
+            '--count=51',
+            '--sort=-committerdate',
+            '--format=%(refname)',
+            'refs/heads',
+            'refs/remotes',
+            'refs/tags',
+        ], { cwd: repoRoot });
+        if (output.exitCode !== 0)
+            throw new Error('Git source references could not be read');
+        const refs = output.stdout.trim().split(/\r?\n/).filter(Boolean);
+        const candidates = [];
+        if (current)
+            candidates.push({ ref: 'HEAD', ...current, aliases: [], checkedOut: true });
+        for (const ref of refs.slice(0, 50)) {
+            const source = await this.sourceIdentity(repoRoot, ref);
+            if (!source)
+                continue;
+            const previous = candidates.find((candidate) => candidate.sourceCommit === source.sourceCommit);
+            if (previous) {
+                previous.aliases.push(ref);
+                continue;
+            }
+            candidates.push({ ref, ...source, aliases: [], checkedOut: false });
+        }
+        return {
+            candidates,
+            truncated: refs.length > 50,
+            environmentMeaning: 'unknown',
+            nextAction: 'Choose the committed sources to learn with the user through native memory.sync_start confirmations. Branch names do not establish production, testing or development roles. Start only the chosen sources; use an explicit ref for an unlisted source.',
+        };
+    }
     async defaultBranch(repoRoot) {
         const ref = await this.gitValue(repoRoot, [
             'symbolic-ref',

package/runtime/dist/src/git/verification-gate.js

@@ -26,6 +26,7 @@ export class VerificationGate {
         const worktreeId = worktreeIdentity(await this.git.findRoot(input.repoRoot));
         await writeJson(this.pathFor(input.repoFingerprint, worktreeId, input.taskId), {
             schemaVersion: 5,
+            source: input.source,
             worktreeId,
             taskId: input.taskId,
             projectId: input.projectId,
@@ -110,6 +111,19 @@ export class VerificationGate {
                 details: [receipt.branch, branch ?? 'HEAD'],
             };
         }
+        const actualSource = receipt.source ? await this.git.sourceIdentity(repoRoot) : null;
+        if (receipt.source &&
+            (!actualSource ||
+                actualSource.sourceCommit !== receipt.source.sourceCommit ||
+                actualSource.treeHash !== receipt.source.treeHash)) {
+            return {
+                allowed: false,
+                reason: 'source_commit_mismatch',
+                diffHash: manifest.diffHash,
+                taskId: receipt.taskId,
+                details: ['Return to the task source commit or start a task for the current source.'],
+            };
+        }
         if (receipt.diffHash !== manifest.diffHash) {
             return {
                 allowed: false,
@@ -144,6 +158,12 @@ export class VerificationGate {
         }
         try {
             const attestation = await this.commitGateAttestor({
+                source: actualSource
+                    ? {
+                        ...actualSource,
+                        ...(receipt.source?.linked ? { linked: receipt.source.linked } : {}),
+                    }
+                    : undefined,
                 taskId: receipt.taskId,
                 projectId: receipt.projectId,
                 repoFingerprint: receipt.repoFingerprint,
@@ -180,6 +200,29 @@ export class VerificationGate {
             taskId: receipt.taskId,
         };
     }
+    async publicationProof(repoRoot, taskId) {
+        const repository = await this.repositories.resolve(repoRoot);
+        const receipts = await this.receiptsFor(repository.repoFingerprint, worktreeIdentity(repository.repoRoot));
+        const receipt = receipts.find((candidate) => candidate.taskId === taskId &&
+            candidate.worktreeId === worktreeIdentity(repository.repoRoot));
+        if (!receipt?.source ||
+            !receipt.taskClosed ||
+            !receipt.projectId ||
+            !receipt.taskVersion ||
+            !isTaskManifest(receipt.taskChanges))
+            throw new Error('A closed source-aware task receipt is required. Otherwise inspect the resulting source with memory.sync_start.');
+        if ((await this.outbox.listForTask(taskId)).length)
+            throw new Error('Resolve this task pending deliveries before publishing its source memory.');
+        const proof = await this.git.committedTaskProof(repository.repoRoot, receipt.source, receipt.taskChanges);
+        return {
+            ...proof,
+            projectId: receipt.projectId,
+            taskId,
+            repoFingerprint: receipt.repoFingerprint,
+            expectedTaskVersion: receipt.taskVersion,
+            diffHash: receipt.diffHash,
+        };
+    }
     async invalidateTask(taskId) {
         await ensureManagedDirectory(this.root, this.root);
         const entries = await readdir(this.root, { withFileTypes: true });

package/runtime/dist/src/mcp/onboarding-tools.js

@@ -134,6 +134,30 @@ const onboardingInput = z.strictObject({
     reworkBehavior: z.enum(['preserve', 'redesign']).optional(),
 });
 export function registerOnboardingTools(server, service) {
+    server.registerTool('memory.source_targets', {
+        description: 'Read bounded Git ref candidates without assuming environment roles from their names. Confirm only the chosen committed sources with native memory.sync_start questionnaires; an explicit ref can select a source outside this preview.',
+        inputSchema: z.object({ repoRoot: z.string().optional() }),
+    }, async (input) => output(await service.memorySourceTargets(input)));
+    server.registerTool('memory.sources', {
+        description: 'Page completed immutable source memory snapshots for an accessible project, optionally filtered by repository fingerprint and treeHash. Use commit/tree identities for task context or an explicit baseSnapshotId for source inspection; never infer applicability from branch labels.',
+        inputSchema: z.object({
+            projectId: uuid,
+            afterId: uuid.optional(),
+            repoFingerprint: z
+                .string()
+                .regex(/^[a-f0-9]{64}$/)
+                .optional(),
+            treeHash: z
+                .string()
+                .regex(/^([a-f0-9]{40}|[a-f0-9]{64})$/)
+                .optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        }),
+    }, async (input) => output(await service.onboardingRequest('sources', body(input))));
+    server.registerTool('memory.publish_task', {
+        description: 'After committing a closed verified task, compare the actual committed tree with its local verification receipt and publish the task memory for that resulting source. A changed base, extra files, missing files or different blobs require memory.sync_start instead.',
+        inputSchema: z.object({ repoRoot: z.string().optional(), taskId: uuid }),
+    }, async (input) => output(await service.memoryPublishTask(input)));
     server.registerTool('project.inspect', {
         description: 'Read-only maturity evidence for missing, empty, starter or established projects. Inspect architecture, state, services, network and persistence as well as screens; recommendations never override the user. Follow with a native mode questionnaire.',
         inputSchema: z.object({ repoRoot }),
@@ -244,6 +268,7 @@ export function registerOnboardingTools(server, service) {
                 .optional()
                 .describe('Use the current conversation language: tr for Turkish, en for English. Omitted by legacy callers means English.'),
             ref: z.string().optional(),
+            baseSnapshotId: uuid.optional(),
             previousRunId: uuid.optional(),
             reworkBehavior: z.enum(['preserve', 'redesign']).optional(),
         }),
@@ -447,6 +472,7 @@ export function registerOnboardingTools(server, service) {
         inputSchema: z.object({
             ...project,
             ...page,
+            sessionId: uuid.optional(),
             includeArchived: z.boolean().optional(),
             includeLinked: z.boolean().optional(),
             kinds: z.array(kind).max(100).optional(),

package/runtime/dist/src/mcp/questionnaire-tools.js

@@ -53,12 +53,15 @@ async function present(server, service, record, repoRoot, context, preparation)
     const elicitation = capabilities?.elicitation;
     if (!elicitation || (!elicitation.form && elicitation.url !== undefined))
         return pending(record, 'native_form_unavailable');
+    const presentationNotice = /^memory-batch-[a-f0-9]{64}-[0-9]+$/.test(record.questionnaireId)
+        ? 'For an unversioned project proposal, approval updates legacy memory only. Source-aware tasks cannot read it until an inspection explicitly retains it. Check each sourceApplicabilityNotice in memory.list_proposals before approving.'
+        : undefined;
     const copy = questionnaireCopy[record.language ?? 'en'];
     return inputRequired({
         inputRequests: {
             [record.requestKey]: inputRequired.elicit({
                 mode: 'form',
-                message: `${record.message}\n\n${copy.pending}${record.allowFreeText ? copy.freeText : ''}${record.textField ? copy.storedText : ''}`,
+                message: `${record.message}${presentationNotice ? `\n\n${presentationNotice}` : ''}\n\n${copy.pending}${record.allowFreeText ? copy.freeText : ''}${record.textField ? copy.storedText : ''}`,
                 requestedSchema: {
                     type: 'object',
                     properties: {

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

@@ -74,6 +74,9 @@ export const engineeringMemoryToolNames = [
     'memory.sync_delta',
     'memory.sync_verify',
     'memory.catalog',
+    'memory.sources',
+    'memory.source_targets',
+    'memory.publish_task',
     'memory.read_revisions',
     'memory.review_batch',
     'memory.query',
@@ -248,6 +251,14 @@ export function registerEngineeringMemoryTools(server, service) {
             workItemKey: z.string().min(1).optional(),
             workItemId: z.string().uuid().optional(),
             mode: z.enum(['write', 'read_only', 'scaffold']).optional(),
+            linkedSources: z
+                .array(z.object({
+                projectId: z.string().uuid(),
+                sourceCommit: z.string().regex(/^([a-f0-9]{40}|[a-f0-9]{64})$/),
+                treeHash: z.string().regex(/^([a-f0-9]{40}|[a-f0-9]{64})$/),
+            }))
+                .max(20)
+                .optional(),
             knownRevisions: z.record(z.string(), z.number().int().min(0)).optional(),
         }),
     }, async (input) => toolResult(await service.sessionBootstrap(input)));
@@ -271,8 +282,9 @@ export function registerEngineeringMemoryTools(server, service) {
         }),
     }, async (input) => toolResult(await service.contextPrepareChange(input)));
     server.registerTool('context.refresh', {
-        description: 'Invalidate stale revision pins after an approved memory change and require a new prepare-change lease.',
+        description: 'Refresh pins within the task fixed code source after memory approval. Use the task repoRoot; source changes require a new task.',
         inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
             sessionId: z.string().min(1),
         }),
     }, async (input) => toolResult(await service.contextRefresh(input)));
@@ -302,6 +314,7 @@ export function registerEngineeringMemoryTools(server, service) {
         description: 'Create an inactive, reviewable proposal for a permanent project or organization engineering memory revision.',
         inputSchema: z.object({
             repoRoot: optionalRepoRoot,
+            sourceRunId: z.string().uuid().optional(),
             resourceId: z.string().optional(),
             projectId: z.string().min(1),
             taskId: z.string().optional(),

package/runtime/dist/src/runtime/active-context-store.js

@@ -215,6 +215,14 @@ export class ActiveContextStore {
             await this.writePointer(next);
         });
     }
+    async findBySessionId(sessionId) {
+        if (!isUuid(sessionId))
+            throw new Error('Context session identifier is invalid');
+        const matches = (await this.allPointers()).filter((pointer) => pointer.sessionId === sessionId);
+        if (matches.length > 1)
+            throw new Error('Context session has more than one active task pointer');
+        return matches[0] ?? null;
+    }
     async findByTaskId(taskId, projectId, requireClean = true) {
         const matches = (await this.allPointers()).filter((pointer) => pointer.taskId === taskId && pointer.projectId === projectId);
         if (matches.length !== 1 ||

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

@@ -21,6 +21,8 @@ export const backendRecoveryOperationNames = [
     'context.refresh',
     'context.prepare_change',
     'memory.sync_status',
+    'memory.sync_plan',
+    'memory.sync_start',
     'project.onboarding_status',
     'memory.query',
     'memory.catalog',

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

@@ -183,6 +183,9 @@ export class BridgeService {
                 throw refuse('This repository has no selected project. Select its project before bootstrapping.', 'project.resolve');
             }
             const bootstrapMode = persistedBootstrap.mode ?? 'write';
+            const source = await this.checkoutSource(repository);
+            if (source && input.linkedSources)
+                source.linked = input.linkedSources;
             const decision = bootstrapMode === 'read_only'
                 ? null
                 : await this.requireBranchDecision(repository, input.externalTaskId);
@@ -194,6 +197,7 @@ export class BridgeService {
                 body: cleanJson({
                     projectId,
                     externalTaskId: persistedBootstrap.externalTaskId,
+                    source,
                     objective: persistedBootstrap.objective,
                     taskKind: persistedBootstrap.taskKind,
                     workItemKey: persistedBootstrap.workItemKey,
@@ -234,6 +238,7 @@ export class BridgeService {
                 projectId,
                 taskId: task.id,
                 taskSlug: input.externalTaskId,
+                source: sourceFromContext(task.sourceContext),
                 worktreeId: sha256(repository.repoRoot),
                 ...(decision
                     ? { branch: typeof task.branch === 'string' ? task.branch : decision.branch }
@@ -370,15 +375,17 @@ export class BridgeService {
             const recoveredDeliveries = await this.recoverJournalOutbox(projectId, taskSlug);
             const outbox = await this.flushOutbox(pointer?.taskId);
             const afterSequence = input.afterSequence ?? 0;
+            const source = await this.checkoutSource(repository, pointer?.source);
             const response = await this.dependencies.client.request(endpoints.sessionResume, {
                 method: 'POST',
                 cacheKey: resumeCacheKey(sessionId, repository.repoFingerprint, afterSequence),
                 allowStaleOnUnavailable: true,
-                body: {
+                body: cleanJson({
                     sessionId,
                     repoFingerprint: repository.repoFingerprint,
                     afterSequence,
-                },
+                    source,
+                }),
             });
             const backend = objectValue(response.data);
             const backendTask = objectValue(backend?.task);
@@ -506,6 +513,7 @@ export class BridgeService {
                     projectId,
                     taskId: backendTask.id,
                     taskSlug,
+                    source: sourceFromContext(backendTask.sourceContext),
                     worktreeId: pointer?.worktreeId ?? sha256(repository.repoRoot),
                     ...(typeof backendTask.branch === 'string'
                         ? { branch: backendTask.branch }
@@ -610,6 +618,7 @@ export class BridgeService {
                 sessionId: input.sessionId,
                 changedPaths,
                 baselineDiffHash,
+                source: await this.checkoutSource(repository, pointer?.source),
                 ...(decision ? { branch: decision.branch } : {}),
                 ...(input.transitionToWrite
                     ? { transitionToWrite: true, expectedTaskVersion: transitionTaskVersion }
@@ -787,9 +796,24 @@ export class BridgeService {
     }
     async contextRefresh(input) {
         return await this.execute(async () => {
+            const pointer = await this.dependencies.activeContexts.findBySessionId(input.sessionId);
+            const repoRoot = input.repoRoot;
+            if (!repoRoot && pointer?.source)
+                throw refuse('Pass repoRoot to context.refresh for this source-aware session.', 'context.refresh');
+            const repository = repoRoot
+                ? await this.dependencies.repositories.resolve(repoRoot, pointer?.projectId)
+                : null;
+            if (pointer &&
+                repository &&
+                (repository.repoFingerprint !== pointer.repoFingerprint ||
+                    (pointer.worktreeId && pointer.worktreeId !== sha256(repository.repoRoot))))
+                throw refuse('Refresh this session from its own repository and worktree.', 'session.resume');
+            const source = repository
+                ? await this.checkoutSource(repository, pointer?.source)
+                : undefined;
             const response = await this.dependencies.client.request(endpoints.contextRefresh, {
                 method: 'POST',
-                body: { sessionId: input.sessionId },
+                body: cleanJson({ sessionId: input.sessionId, source }),
             });
             await this.dependencies.activeContexts.clearSessionConflict(input.sessionId, 'approved_memory_revision_requires_refresh');
             return asJsonValue({
@@ -981,6 +1005,8 @@ export class BridgeService {
                 reworkBehavior: input.reworkBehavior,
                 sourceCommit: snapshot.commit,
                 treeHash: snapshot.treeHash,
+                sourceBound: true,
+                baseSnapshotId: input.baseSnapshotId,
                 manifestHash: snapshot.manifestHash,
                 expectedFiles: snapshot.files.length,
             });
@@ -993,16 +1019,26 @@ export class BridgeService {
             if (!run || typeof run.id !== 'string')
                 throw refuse('The inspection response has no run identity.', 'memory.sync_status');
             if (run.state === 'inventory' || run.state === 'planning') {
-                for (let offset = 0; offset < snapshot.files.length; offset += 1000) {
-                    const page = cleanJson({
+                for (let offset = 0; offset < snapshot.files.length;) {
+                    const page = {
                         projectId: input.projectId,
                         runId: run.id,
-                        files: snapshot.files.slice(offset, offset + 1000),
-                    });
-                    assertSafeToPersist(page);
+                        files: [],
+                    };
+                    let bytes = Buffer.byteLength(JSON.stringify(page));
+                    while (offset < snapshot.files.length && page.files.length < 1000) {
+                        const file = snapshot.files[offset];
+                        const addedBytes = Buffer.byteLength(JSON.stringify(file)) + (page.files.length ? 1 : 0);
+                        if (page.files.length && bytes + addedBytes > 64 * 1024)
+                            break;
+                        page.files.push(file);
+                        bytes += addedBytes;
+                        offset += 1;
+                    }
+                    assertSafeToPersist(cleanJson(page));
                     await this.dependencies.client.request('/memory/sync/inventory', {
                         method: 'POST',
-                        body: page,
+                        body: cleanJson(page),
                     });
                 }
                 await this.dependencies.client.request('/memory/sync/inventory', {
@@ -1076,10 +1112,30 @@ export class BridgeService {
             }),
         };
     }
+    async memorySourceTargets(input) {
+        return this.execute(async () => {
+            const repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
+            return asJsonValue(await this.dependencies.repositories.git.sourceCandidates(repository.repoRoot));
+        });
+    }
+    async memoryPublishTask(input) {
+        return this.execute(async () => {
+            let proof;
+            try {
+                proof = await this.dependencies.gate.publicationProof(input.repoRoot ?? process.cwd(), input.taskId);
+            }
+            catch (error) {
+                throw refuse(error instanceof Error ? error.message : 'The resulting commit must be inspected.', 'memory.sync_start');
+            }
+            const response = await this.dependencies.client.request('/memory/sources/publish-task', { method: 'POST', body: proof });
+            return response.data;
+        });
+    }
     async onboardingRequest(operation, body) {
         return this.execute(async () => {
             assertSafeToPersist(body);
             const routes = {
+                sources: '/memory/sources/catalog',
                 status: '/memory/sync/status',
                 inventory: '/memory/sync/inventory',
                 plan: '/memory/sync/plan',
@@ -1347,7 +1403,10 @@ export class BridgeService {
             const pointer = await this.requireActivePointer(repository.repoFingerprint, taskId);
             const refreshed = await this.dependencies.client.request(endpoints.contextRefresh, {
                 method: 'POST',
-                body: { sessionId: pointer.sessionId },
+                body: cleanJson({
+                    sessionId: pointer.sessionId,
+                    source: await this.checkoutSource(repository, pointer.source),
+                }),
             });
             const refreshData = objectValue(refreshed.data);
             const refreshedTask = objectValue(refreshData?.task);
@@ -1419,6 +1478,7 @@ export class BridgeService {
                     body: {
                         sessionId: input.sessionId,
                         repoFingerprint: repository.repoFingerprint,
+                        source: (await this.checkoutSource(repository, pointer.source)) ?? null,
                         afterSequence: 0,
                     },
                 });
@@ -1487,6 +1547,7 @@ export class BridgeService {
                     ? []
                     : await buildPathChangeManifest(repository.repoRoot, taskChanges);
                 const verifyBody = cleanJson({
+                    source: await this.checkoutSource(repository, pointer.source),
                     taskId: input.taskId,
                     sessionId: input.sessionId,
                     expectedTaskVersion: numericTaskVersion(snapshotTask.lockVersion),
@@ -1532,6 +1593,7 @@ export class BridgeService {
                 if (responseData?.verified === true) {
                     const taskVersion = numericTaskVersion(responseData.taskVersion);
                     await this.dependencies.gate.record({
+                        source: sourceFromContext(snapshotTask.sourceContext),
                         taskId: input.taskId,
                         projectId: repository.projectId,
                         repoFingerprint: repository.repoFingerprint,
@@ -1572,6 +1634,7 @@ export class BridgeService {
                     body: {
                         sessionId: pointer.sessionId,
                         repoFingerprint: repository.repoFingerprint,
+                        source: (await this.checkoutSource(repository, pointer.source)) ?? null,
                         afterSequence: 0,
                     },
                 });
@@ -1585,6 +1648,7 @@ export class BridgeService {
                     : [];
                 await this.assertTaskWorktree(repository, task, pointer);
                 const closeBody = {
+                    source: (await this.checkoutSource(repository, pointer.source)) ?? null,
                     taskId: input.taskId,
                     sessionId: pointer.sessionId,
                     expectedTaskVersion: numericTaskVersion(task.lockVersion),
@@ -2550,6 +2614,21 @@ export class BridgeService {
         }
         return pending.length;
     }
+    async checkoutSource(repository, expected) {
+        const current = await this.dependencies.repositories.git.sourceIdentity(repository.repoRoot);
+        if (expected &&
+            (!current ||
+                current.sourceCommit !== expected.sourceCommit ||
+                current.treeHash !== expected.treeHash)) {
+            throw refuse('The checkout no longer matches this task source. Return to its commit or bootstrap a new task for the current committed source.', 'session.bootstrap');
+        }
+        if (current && repository.git.head !== current.sourceCommit) {
+            throw refuse('The Git source changed during the request. Retry session.resume with a stable checkout.', 'session.resume');
+        }
+        return current
+            ? { ...current, ...(expected?.linked ? { linked: expected.linked } : {}) }
+            : undefined;
+    }
     async activeTaskSnapshot(taskId, projectId, repoRoot) {
         const repository = await this.dependencies.repositories.resolve(repoRoot ?? process.cwd(), projectId);
         const pointer = await this.requireActivePointer(repository.repoFingerprint, taskId);
@@ -2565,6 +2644,7 @@ export class BridgeService {
             body: {
                 sessionId: pointer.sessionId,
                 repoFingerprint: repository.repoFingerprint,
+                source: (await this.checkoutSource(repository, pointer.source)) ?? null,
                 afterSequence: 0,
             },
         });
@@ -2625,6 +2705,7 @@ export class BridgeService {
         }
     }
     async retryVerificationRecovery(repository, pointer, backend) {
+        await this.checkoutSource(repository, pointer.source);
         const intent = pointer.verificationIntent;
         const recovery = objectValue(backend?.verificationRecovery);
         if (!intent) {
@@ -2717,6 +2798,7 @@ export class BridgeService {
         }
         const taskVersion = numericTaskVersion(responseData.taskVersion);
         await this.dependencies.gate.record({
+            source: sourceFromContext(body.source),
             taskId: pointer.taskId,
             projectId: pointer.projectId,
             repoFingerprint: pointer.repoFingerprint,
@@ -2750,6 +2832,7 @@ export class BridgeService {
         return await this.deliverCloseIntent(repository, body, intent.taskChanges, true);
     }
     async deliverCloseIntent(repository, body, taskChanges, recoveredAfterResponseLoss) {
+        await this.checkoutSource(repository, sourceFromContext(body.source));
         const touchedContract = taskChanges.some((change) => /\.controller\.[tj]s$/.test(change.path));
         const currentBranch = await this.dependencies.repositories.git.currentBranch(repository.repoRoot);
         if (typeof body.branch === 'string' && body.branch !== currentBranch)
@@ -2774,6 +2857,7 @@ export class BridgeService {
         }
         const closedTaskVersion = numericTaskVersion(closedTask.taskVersion);
         await this.dependencies.gate.record({
+            source: sourceFromContext(body.source),
             taskId: String(body.taskId),
             projectId: repository.projectId,
             repoFingerprint: repository.repoFingerprint,
@@ -3482,4 +3566,29 @@ function assertValidationEvidence(validations) {
         seen.add(validation.validationId);
     }
 }
+function sourceFromContext(value) {
+    const context = objectValue(value);
+    if (!context || typeof context.sourceCommit !== 'string' || typeof context.treeHash !== 'string')
+        return undefined;
+    const linked = Array.isArray(context.linked)
+        ? context.linked.map((entry) => {
+            const item = objectValue(entry);
+            if (!item ||
+                typeof item.projectId !== 'string' ||
+                typeof item.sourceCommit !== 'string' ||
+                typeof item.treeHash !== 'string')
+                throw refuse('The backend source context is incomplete. Resume this task.', 'session.resume');
+            return {
+                projectId: item.projectId,
+                sourceCommit: item.sourceCommit,
+                treeHash: item.treeHash,
+            };
+        })
+        : undefined;
+    return {
+        sourceCommit: context.sourceCommit,
+        treeHash: context.treeHash,
+        ...(linked ? { linked } : {}),
+    };
+}
 //# sourceMappingURL=bridge-service.js.map

package/runtime/dist/src/runtime/offline-outbox.js

@@ -6,6 +6,22 @@ import { sha256, stableStringify } from '../utilities/hash.js';
 const sensitiveKeyPattern = /(authorization|password|passcode|secret|token|cookie|email|phone|mobile|customer|account|user.?id|user.?name)/i;
 const emailPattern = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i;
 const phonePattern = /\+\d[\d ()-]{7,}\d/;
+const repositoryPathFields = new Set([
+    'path',
+    'paths',
+    'originalPath',
+    'changedPaths',
+    'pathPatterns',
+    'evidencePaths',
+]);
+const iosAssetScalePathPattern = /^(?:[\p{L}\p{N}_. -]+\/)*[\p{L}\p{N}_. -]+\.xcassets\/[\p{L}\p{N}_. -]+\.(?:appiconset|imageset)\/[\p{L}\p{N}_. -]+@[123]x\.(?:png|jpe?g)$/iu;
+function emailScanValue(value, key) {
+    if (!repositoryPathFields.has(key) ||
+        !iosAssetScalePathPattern.test(value) ||
+        value.split('/').some((part) => part === '.' || part === '..'))
+        return value;
+    return value.replace(/@[123]x(?=\.(?:png|jpe?g)$)/i, '');
+}
 const bearerPattern = /\bbearer\s+[a-z0-9._~-]+/i;
 const jwtPattern = /\beyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\b/;
 const privateKeyPattern = /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/;
@@ -155,7 +171,7 @@ export function assertSafeToPersist(value, key = '') {
         throw new Error(`Sensitive field cannot be persisted: ${key}`);
     }
     if (typeof value === 'string') {
-        if (emailPattern.test(value) ||
+        if (emailPattern.test(emailScanValue(value, key)) ||
             phonePattern.test(value) ||
             bearerPattern.test(value) ||
             jwtPattern.test(value) ||
@@ -199,13 +215,13 @@ export function redactForCache(value) {
         return null;
     }
 }
-function redactValue(value) {
+function redactValue(value, key = '') {
     if (typeof value === 'string') {
-        assertSafeToPersist(value);
+        assertSafeToPersist(value, key);
         return value;
     }
     if (Array.isArray(value)) {
-        return value.map((entry) => redactValue(entry));
+        return value.map((entry) => redactValue(entry, key));
     }
     if (value !== null && typeof value === 'object') {
         const result = {};
@@ -213,7 +229,7 @@ function redactValue(value) {
             if (sensitiveKeyPattern.test(key)) {
                 continue;
             }
-            result[key] = redactValue(entry);
+            result[key] = redactValue(entry, key);
         }
         return result;
     }

package/skill/references/lifecycle.md

@@ -209,6 +209,40 @@ Closing is not the end of the turn either. `task.close` returns the delivery que
 
 When a pull request has been opened, keep going: check whether it merges cleanly, report the result with the link, and if it conflicts, name the files and ask whether to resolve them. Never end the turn on a pull request whose mergeability was never checked, and never resolve a conflict without being told to.
 
-## Offline Behavior
+## Code source and memory applicability
+
+The bridge sends the checkout's committed Git commit and tree at bootstrap. Task and session
+sourceContext distinguish exact inspected memory, unknown source and legacy-unverified project
+memory. Branch names are labels; never infer an environment or choose newer project behavior from
+their spelling. Check the returned coverage before describing project behavior as known.
+
+On an opted-in project, an unknown source can open a read-only learning session but cannot start
+implementation. Use memory.source_targets and memory.sources, explain the source to the user and
+start its inspection through the native memory.sync_start form. After completion, context.refresh
+can resolve that same previously unknown code state. A different commit requires a new task and
+source selection; changing a branch name does not make memory compatible. Use the task repoRoot
+for refresh as well as resume and prepare_change.
+
+Ordinary memory reads, history, selectors, discovery and verification use the task's pinned source
+mapping. Project proposals made with taskId form that task's approved overlay; they do not alter
+its base commit or another task. Product and organization policy and all membership checks remain
+current. Select linkedSources explicitly by accessible project id, commit and tree at bootstrap;
+do not guess the counterpart's source from this repository's branch. Unselected or unknown linked
+sources are not verified endpoint contracts.
+
+After the already-authorized commit is created, call memory.publish_task with the closed task id
+and repoRoot. The bridge proves the resulting commit has the task's base parent and exactly its
+verified files, blobs, modes and deletions. Backend publication rechecks the task, current access
+and immutable source identity and atomically saves the approved overlay for the resulting commit.
+It never publishes dirty worktree contents. Repeating the same result is idempotent. If merging,
+squashing, rebasing or extra changes prevent that proof, inspect the actual resulting source with
+memory.sync_start and an explicit baseSnapshotId; never mark it compatible from ancestry alone.
+
+An interrupted verify/close retains the original source in its durable intent. Resume the same
+source; do not change the stored request to fit a different checkout. Old receipts still require
+online attestation and cannot bypass a project's source-aware requirement. Global minimum client
+version is not automatically raised; projects opt in by starting a source-bound inspection.
+
+## Offline source context
 
 An unexpired cached context pack may be used for implementation. The bridge records checkpoints in its outbox. Permanent proposal review, strict verification, task close, and Git commit require the backend and synchronization of the relevant task deliveries. An unrelated task or repository queue does not block this task; account switching and logout still require all deliveries to be resolved. Commit receipts are retained per task and worktree and still require an online attestation for the selected closed task and exact staged content.

package/skill/references/project-onboarding.md

@@ -56,6 +56,55 @@ unavailable service contracts explicit rather than inventing endpoint behavior.
 
 ## Durable deep learning
 
+Before choosing learning targets, use memory.source_targets for a bounded preview of local,
+remote-tracking and tag refs, and memory.sources to page this project's completed source snapshots.
+The preview groups aliases of the same commit and says when it is truncated. Ref names do not
+establish deployment meaning; the user need not classify them as develop/test/prod. Explain the
+checked-out source and other plausible targets, then use the native memory.sync_start confirmation
+for each source the user chose. Never scan every historical branch automatically. An explicit ref
+can choose a source outside the preview. The form pins its resolved commit even if a branch moves.
+
+New inspections are source-bound. Supply sourceRunId on their project proposals, with complete
+selectors and provenance. Approval updates only that target's proposed view; sync completion is
+what publishes the immutable mapping. Starting an inventory does not activate source enforcement.
+The first completed source-bound snapshot activates it for new tasks; already-open legacy tasks
+keep their original context through verification, close and commit. Every active prior project
+record must be retained with evidence or explicitly archived for the inspected source.
+On a first capture there is no base snapshot for unchanged references. Propose reviewed
+source-specific revisions retaining the existing content or archiving the record, using sourceRunId,
+and submit them as unit evidence. Core records must be retained. With a base snapshot, unchanged
+references are also available. A grandfathered task can still approve unversioned memory, but its
+sourceApplicabilityNotice explains that this revision will reach no source-aware task until an
+inspection explicitly retains it; an incremental inspection must include it deliberately too.
+Select baseSnapshotId explicitly when carrying inspected
+memory across a commit change. Reuse requires unchanged source and dependency evidence; it is not
+permission to copy behavior merely because one commit is an ancestor. Existing unversioned records
+remain historical material, never automatic proof for a newly selected source. No-change refreshes
+reuse revisions without manufacturing additional revision history.
+
+The source snapshot includes historical path/symbol/tag/stack selectors and archival state as well
+as revision ids. Thus learning a newer source cannot change which records an older task receives.
+Current access and security policy still apply. Missing coverage stays explicit and leads back to
+inspection rather than substituting the project's latest behavior. The same complete tree in the
+same repository/project reuses its inspected mapping even after squash, rebase or a merge only when
+the candidate mapping hashes agree. Conflicting mappings require comparing memory.sources and
+starting memory.sync_start for the exact commit with a selected baseSnapshotId; never silently pick
+the newest fallback. A task that already has an exact snapshot keeps that pin. The task
+still pins its actual commit. Different content is not covered by ancestry alone: start a delta
+inspection with previousRunId and baseSnapshotId, preserving evidenced unchanged units and reviewing
+changed/dependent ones. After a verified task closes and its result is committed, memory.publish_task
+checks its full result tree against the task manifest; the number or shape of commit parents does
+not decide publication. Extra or missing changed content requires inspection instead.
+This proof establishes file content, not who authored it or which intermediate commits produced it.
+Git inspection is performed by the local bridge. The backend does not fetch or execute Git: it
+trusts the authenticated client's source identity assertion and independently enforces task ownership,
+verified manifest identity, publication scope and current access. Do not describe that boundary as
+server-side Git verification.
+
+Use the task's explicit repoRoot with context.refresh. It never guesses the repository from the
+bridge process directory. An unknown selected linked commit can become exact after that same source
+is inspected; refresh keeps the selected identities and existing exact snapshots fixed.
+
 Adopt, refresh and the learning stage of rework do not modify application source. They inventory and
 learn the whole architecture: modules, service classes, network and API contracts, state management,
 persistence/data models/migrations, navigation, screens/components, localization, deployment,
@@ -157,3 +206,32 @@ are written by the agent in the same language; pass language for the native help
 An existing exact-request questionnaire retains its original wording and answer across updates and
 restart, including an older English form. Resume that question rather than silently replacing or
 withdrawing it. Language changes never broaden the approved source, mode or previous-run scope.
+
+## Source-specific refresh and history
+
+During refresh an existing own or optional linked unknown may become exact if unambiguous;
+conflicting mappings leave it unknown without blocking the existing read-only reader task.
+Exact snapshots remain pinned. Bootstrap still refuses an ambiguous requested source. Never
+substitute another source's records. Use memory.sources with projectId, repoFingerprint and
+treeHash to compare candidates, then inspect in that project's checkout with contributor access.
+A new task may omit an optional linked selection; this cannot change an existing task's identity.
+
+Retry memory.sync_verify after a lost response: a completed run returns its stored result and
+snapshot even if memory changed later. New work requires a new run. Source-aware project history
+contains the effective selected revision and current-task reconciliations. The depth argument
+bounds shared/legacy history; it does not widen a source-bound project's single selected revision.
+Headers include the total revision count for each authorized selected resource so the history-read
+gate still applies to rules, profiles and quality records. This count does not authorize reading
+unrelated branch revisions, reasons, objectives or reconciliations.
+
+Present sourceApplicabilityNotice from memory.list_proposals before permanent approval.
+The native exact-batch form repeats a conditional legacy-only advisory on both ask and resume,
+including restart on a host that supports native forms. It does not change saved messages,
+request keys, digests or answers. An unsupported host leaves the decision pending. The advisory
+is not a claim that every proposal in the batch is unversioned; inspect its actual notices.
+
+Current own-project authority, discipline, repository, branch, source, task version and diff remain
+required for verified delivery. Verified resume, close and commit attestation do not fetch fresh
+counterpart memory or depend on a counterpart link/membership that was revoked after verification.
+Fresh linked-source selection and work still check current access. Publishing new source memory
+with memory.publish_task is a separate operation and still requires current linked authority.