@noesis-brain/mcp-server 2.1.5 → 2.5.0

package/dist/tools/index.d.ts

@@ -49,12 +49,7 @@ type CloudNoteRow = {
 };
 /** Adapt a by-relative Note (+ its hash from the root hash map) into CloudNoteRow. */
 export declare function adaptCloudNote(n: Note, relativePath: string, hash: string): CloudNoteRow;
-/**
- * Sync specific files by path (single-file or multi-file sync mode)
- * @param force - If true, bypass hash check and always re-sync (useful for metadata regeneration)
- * @param regenerateMetadata - If true, backend AI regenerates all metadata fields, overwriting existing values
- */
-export declare function syncSpecificFiles(filePaths: string[], dryRun: boolean, client: NoesisClient, force?: boolean, regenerateMetadata?: boolean): Promise<{
+export declare function syncSpecificFiles(filePaths: string[], dryRun: boolean, client: NoesisClient, force?: boolean, regenerateMetadata?: boolean, stampSession?: 'auto' | 'always' | 'never', sessionId?: string): Promise<{
     content: Array<{
         type: 'text';
         text: string;

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,YAAY,EAAyC,KAAK,IAAI,EAA2D,MAAM,wBAAwB,CAAC;AAsIjK;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAejD;AAqBD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CA64F7E;AA0DD;;;;GAIG;AACH,KAAK,YAAY,GAAG;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAYxF;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EAAE,EACnB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,YAAY,EACpB,KAAK,GAAE,OAAe,EACtB,kBAAkB,GAAE,OAAe,GAClC,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAigBhF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAI9F;AA8ED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACrE,MAAM,CAkFR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,CAqBA;AA4SD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAY/E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,YAAY,EAAyC,KAAK,IAAI,EAA2D,MAAM,wBAAwB,CAAC;AAwIjK;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAejD;AAqBD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAk/F7E;AA0DD;;;;GAIG;AACH,KAAK,YAAY,GAAG;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAYxF;AA0CD,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EAAE,EACnB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,YAAY,EACpB,KAAK,GAAE,OAAe,EACtB,kBAAkB,GAAE,OAAe,EACnC,YAAY,GAAE,MAAM,GAAG,QAAQ,GAAG,OAAgB,EAClD,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CA6gBhF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAI9F;AA8ED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACrE,MAAM,CAkFR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,CAqBA;AA4SD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAY/E"}

package/dist/tools/index.js

@@ -11,6 +11,8 @@ import { parseNoteReference, resolvePathReference, rootLocalBase } from '../reso
 import { formatRootsList } from '../resolve/rootsFormat.js';
 import { initEmbeddingService, generateEmbedding, generateEmbeddingsBatch } from '../services/embedding.js';
 import { SyncStateManager, determineSyncDirection } from './SyncStateManager.js';
+import { currentSessionRef, upsertSessionFrontmatter } from './claudeSessions.js';
+import { buildIndex, matchSessions } from './sessionIndex.js';
 import { registerNaviTools } from './navis.js';
 import { registerBacklogTools } from './backlog.js';
 import { registerExamTools } from './exam.js';
@@ -934,6 +936,77 @@ export function registerTools(server, services) {
                 }]
         };
     });
+    // Register find_claude_sessions_for_note tool
+    server.tool('find_claude_sessions_for_note', "Recover which Claude Code sessions worked on a note, by scanning this machine's session transcripts for mentions of the note's path. Returns each session's id, folder and last-active time, plus a ready-to-run `claude --resume` command. Use this to backfill notes that predate automatic session stamping, or whenever the user asks 'which session wrote this note / can I resume it'. READ-ONLY by default (plan-mode safe): it only writes when apply is true, which stamps the results into the note's `claude_sessions:` frontmatter. Results are cached in an incremental index, so the first run is the slow one.", {
+        note: z.string().describe('Absolute path to the note (.md) on this machine. A relative path or bare filename also works but matches more weakly.'),
+        since: z.string().optional().describe('ISO date; ignore transcripts older than this. Defaults to 90 days ago — widen it to search further back.'),
+        apply: z.boolean().optional().describe("Write the matches into the note's `claude_sessions:` frontmatter (default: false). Leave false in plan mode."),
+        timeBudgetMs: z.number().optional().describe('Stop indexing after this many ms and report partial progress (default: 20000). Re-run to continue where it stopped.')
+    }, async (args) => {
+        const { note, since, apply = false, timeBudgetMs } = args;
+        const notePath = expandHome(note);
+        const absolutePath = path.isAbsolute(notePath) ? normalizePath(notePath) : undefined;
+        const defaultSince = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
+        const sinceDate = since ? new Date(since) : defaultSince;
+        const build = await buildIndex({
+            since: Number.isNaN(sinceDate.getTime()) ? defaultSince : sinceDate,
+            timeBudgetMs,
+        });
+        const matches = matchSessions(build.index, {
+            absolutePath,
+            relativePath: absolutePath ? undefined : normalizePath(notePath),
+        });
+        const lines = [];
+        lines.push(`**Claude Code sessions for** \`${normalizePath(notePath)}\``);
+        lines.push('');
+        lines.push(`Indexed ${build.scanned} new + ${build.reused} cached of ${build.total} transcripts` +
+            (build.skippedOld > 0 ? ` (${build.skippedOld} older than the cutoff)` : '') + '.');
+        if (build.truncated) {
+            lines.push('');
+            lines.push('⚠️ Time budget reached — the index is partial. Re-run to continue where it stopped.');
+        }
+        lines.push('');
+        if (matches.length === 0) {
+            lines.push('No sessions mention this note.');
+            lines.push('');
+            lines.push('That is expected when the work happened on another machine (transcripts are local), ' +
+                'longer ago than the cutoff, or before this note had its current path.');
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        for (const m of matches) {
+            const when = m.last_active ? m.last_active.replace('T', ' ').replace(/\..*$/, ' UTC') : 'unknown';
+            lines.push(`- **${m.title || `Session ${m.id.slice(0, 8)}`}** — ${when}` +
+                (m.confidence !== 'absolute' ? `  _(${m.confidence} match — weaker)_` : ''));
+            lines.push(`  \`cd "${m.cwd}" && claude --resume ${m.id}\``);
+        }
+        if (apply) {
+            try {
+                const content = fs.readFileSync(notePath, 'utf-8');
+                let updated = content;
+                // Oldest first so the newest ends up at the head of the list after each merge.
+                for (const m of [...matches].reverse()) {
+                    if (!m.cwd)
+                        continue;
+                    const { confidence, ...ref } = m;
+                    updated = upsertSessionFrontmatter(updated, ref);
+                }
+                if (updated !== content) {
+                    fs.writeFileSync(notePath, updated, 'utf-8');
+                    lines.push('', `✅ Wrote ${matches.length} session(s) into the note's frontmatter. Run \`sync_notes\` to push it.`);
+                }
+                else {
+                    lines.push('', 'Note frontmatter already lists these sessions — nothing to write.');
+                }
+            }
+            catch (e) {
+                lines.push('', `⚠️ Could not update the note: ${e.message}`);
+            }
+        }
+        else {
+            lines.push('', '_Read-only. Pass `apply: true` to write these into the note\'s frontmatter._');
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
     // Register list_edited_online_notes tool
     server.tool('list_edited_online_notes', 'List notes that were edited via the Noesis web UI (Quick Fix) and have pending local sync. For each note, reports whether the local file is unchanged (safe to pull), also_modified (conflict-cascade will run), or not_on_disk. Use this before running sync_notes to preview what will happen.', {
         root_id: z.number().optional().describe('Filter to a specific root ID (optional; omit to list all roots)')
@@ -1011,9 +1084,14 @@ export function registerTools(server, services) {
         dryRun: z.boolean().optional().describe('Preview changes without syncing (default: false)'),
         force: z.boolean().optional().describe('Force re-sync even if file hash is unchanged. Useful for regenerating AI metadata on existing files (default: false)'),
         regenerateMetadata: z.boolean().optional().describe('Regenerate all metadata using AI, overwriting existing values. Use when you want AI to improve/replace current title, description, and keywords (default: false)'),
-        moveNewToNoesis: z.boolean().optional().describe('Move new local-only files to .noesis folder before syncing. Keeps ad-hoc notes separate from project files (default: false)')
+        moveNewToNoesis: z.boolean().optional().describe('Move new local-only files to .noesis folder before syncing. Keeps ad-hoc notes separate from project files (default: false)'),
+        stampSession: z.enum(['auto', 'always', 'never']).optional().describe("Record the calling Claude Code session (id + folder + last-active) in the note's `claude_sessions:` frontmatter, so the note can be traced back to the conversation that wrote it and resumed with `claude --resume`. 'auto' (default) stamps only on a real push; 'never' disables it; 'always' stamps even an otherwise-unchanged file, which turns that sync into a push."),
+        sessionId: z.string().optional().describe('Override the session id to record. Defaults to CLAUDE_CODE_SESSION_ID, which Claude Code injects into every MCP server it spawns. Use this only when that value is known to be wrong — e.g. after /clear, which rotates the id without respawning the MCP server.')
     }, async (args) => {
-        const { root, files, dryRun = false, force = false, regenerateMetadata = false, moveNewToNoesis = false } = args;
+        const { root, files, dryRun = false, force = false, regenerateMetadata = false, moveNewToNoesis = false, stampSession = 'auto', sessionId } = args;
+        // Resolved once per sync run, not per file: two bounded transcript reads (~300 KB total).
+        const resolvedSession = stampSession === 'never' ? null : currentSessionRef(sessionId);
+        const sessionRef = resolvedSession?.ref ?? null;
         // Get roots for sync
         let roots = await client.getRootsForSync();
         // If no roots configured, try auto-detection from CWD
@@ -1085,7 +1163,7 @@ export function registerTools(server, services) {
         }
         // Handle specific files sync mode (push-only for specific files)
         if (files && files.length > 0) {
-            return await syncSpecificFiles(files, dryRun, client, force, regenerateMetadata);
+            return await syncSpecificFiles(files, dryRun, client, force, regenerateMetadata, stampSession, sessionId);
         }
         // Filter to specific root if requested
         const rootsToSync = root
@@ -1252,9 +1330,10 @@ export function registerTools(server, services) {
                         }
                         else {
                             const metadata = parseYamlFrontmatter(localFile.content);
-                            await client.upsertNote(localFile, metadata, { force, regenerateMetadata });
-                            if (localFile.hash)
-                                stateMgr.setBaseline(relativePath, { hash: localFile.hash, lastSyncedAt: new Date().toISOString() }, localFile.content);
+                            const s = stampForPush(localFile.path || path.join(syncRoot.path, relativePath), localFile.content, localFile.hash || '', localFile.size, localFile.mtime, sessionRef, dryRun);
+                            await client.upsertNote({ ...localFile, content: s.content, hash: s.hash }, metadata, { force, regenerateMetadata });
+                            if (s.hash)
+                                stateMgr.setBaseline(relativePath, { hash: s.hash, lastSyncedAt: new Date().toISOString() }, s.content);
                             result.details.push({ file: relativePath, action: 'pushed_create' });
                             result.pushed.created++;
                         }
@@ -1399,17 +1478,19 @@ export function registerTools(server, services) {
                                     }
                                     else {
                                         const enrichedHash = NoesisClient.computeHash(enrichedContent);
+                                        const localPath = path.join(syncRoot.path, relativePath);
+                                        // Stamp AFTER updateFrontmatter — see the per-file branch for why.
+                                        const s = stampForPush(localPath, enrichedContent, enrichedHash, localFile.size, localFile.mtime, sessionRef, dryRun);
                                         const mergedFile = {
                                             ...localFile,
-                                            content: enrichedContent,
-                                            hash: enrichedHash
+                                            content: s.content,
+                                            hash: s.hash
                                         };
                                         // preserveMetadata=true: keep cloud's AI-generated title/description/keywords
                                         await client.upsertNote(mergedFile, metadata, { force: true, regenerateMetadata, preserveMetadata: true });
                                         // Write enriched content back to local file
-                                        const localPath = path.join(syncRoot.path, relativePath);
-                                        fs.writeFileSync(localPath, enrichedContent, 'utf-8');
-                                        stateMgr.setBaseline(relativePath, { hash: enrichedHash, lastSyncedAt: new Date().toISOString() }, enrichedContent);
+                                        fs.writeFileSync(localPath, s.content, 'utf-8');
+                                        stateMgr.setBaseline(relativePath, { hash: s.hash, lastSyncedAt: new Date().toISOString() }, s.content);
                                         result.details.push({ file: relativePath, action: 'pushed_update', reason: 'merged' });
                                         result.pushed.updated++;
                                     }
@@ -1838,21 +1919,24 @@ export function registerTools(server, services) {
     /**
      * Update document relations (bidirectional)
      */
-    server.tool('update_relations', 'Update document relations. Without relations: returns note + other notes for analysis. With relations: updates and creates inverse relations.', {
+    server.tool('update_relations', "Update document relations. Without `relations`: returns the note, its CURRENT relations, and other notes for analysis. With `relations`: REPLACES the note's entire relation set — send the complete desired set, not just additions, or the omitted ones are deleted. Read the current set first (`get_note`, or this tool with no `relations`) and union your additions into it. Relations are stored one-way on this note; the app derives backlinks, so no inverse is written on the target.", {
         note_id: z.number().describe('The note ID to update relations for'),
         relations: z.array(z.object({
-            type: z.enum(['references', 'implements', 'extends', 'supersedes']).describe('Relation type'),
+            // Mirrors SUGGESTABLE_RELATION_TYPES in the backend
+            // (src/backend/services/aiTasks/relations/infer.ts) — the source of truth for what
+            // the app stores. 'related' is what the web UI and POST /:id/relations/accept write;
+            // omitting it here made an MCP write silently destroy links it could not recreate.
+            type: z.enum(['related', 'references', 'implements', 'extends', 'supersedes']).describe('Relation type'),
             target_id: z.number().describe('Target note ID'),
             context: z.string().optional().describe('Optional context explaining the relation')
-        })).optional().describe('Relations to set (omit to get notes for analysis)')
+        })).optional().describe('The COMPLETE relation set to store (omit to get notes for analysis)')
     }, async (args) => {
         const { note_id, relations } = args;
         // If relations provided, update them
         if (relations !== undefined) {
             const result = await client.updateRelations(note_id, relations);
-            let message = `✅ Updated relations for note ${note_id}\n\n`;
-            message += `- Relations set: ${relations.length}\n`;
-            message += `- Inverse relations created: ${result.inversesCreated}\n\n`;
+            let message = `✅ Replaced the relation set for note ${note_id}\n\n`;
+            message += `- Relations now stored: ${result.updated}\n\n`;
             if (relations.length > 0) {
                 message += `**Relations:**\n`;
                 for (const rel of relations) {
@@ -1917,12 +2001,14 @@ export function registerTools(server, services) {
         return { content: [{ type: 'text', text: message }] };
     });
     // Register get_relation_graph tool
-    server.tool('get_relation_graph', 'Traverse the relation graph from a starting note, following relation links up to N hops deep. Returns all reachable notes with their depth and the relation that led to them.', {
+    server.tool('get_relation_graph', 'Traverse the relation graph from a starting note up to N hops deep, in BOTH directions — notes this one links to AND notes that link to it. Returns every reachable note with its depth and one relation that led to it. An empty result means the note genuinely has no neighbours, not merely that it links to nothing.', {
         note_id: z.number().describe('Starting note ID'),
-        depth: z.number().min(1).max(4).optional().describe('Maximum traversal depth (default: 2, max: 4)')
+        // Bounded by MAX_DEPTH in the backend's services/graphService.ts. Advertising 4 while
+        // the server clamped to 3 would have been a silently broken promise.
+        depth: z.number().min(1).max(3).optional().describe('Maximum traversal depth (default: 2, max: 3)')
     }, async (args) => {
         const { note_id, depth = 2 } = args;
-        const results = await client.getRelationGraph(note_id, Math.min(Math.max(depth, 1), 4));
+        const results = await client.getRelationGraph(note_id, Math.min(Math.max(depth, 1), 3));
         if (results.length === 0) {
             return {
                 content: [{
@@ -1944,7 +2030,10 @@ export function registerTools(server, services) {
             output += `\n--- Depth ${d} ---\n`;
             for (const n of notes) {
                 const desc = n.description ? `\n  ${n.description.substring(0, 120)}${n.description.length > 120 ? '...' : ''}` : '';
-                output += `- **${n.title}** [ID: ${n.id}] via ${n.relation_type} from note ${n.from_id}\n  ${n.file_path}${desc}\n`;
+                // from_id/relation_type name ONE of possibly several edges; a node can be reached
+                // by more than one, so treat the attribution as a hint and never assume it exists.
+                const via = n.relation_type && n.from_id ? ` via ${n.relation_type} from note ${n.from_id}` : '';
+                output += `- **${n.title}** [ID: ${n.id}]${via}\n  ${n.file_path ?? '(path unavailable)'}${desc}\n`;
             }
         }
         return {
@@ -2730,7 +2819,39 @@ export function adaptCloudNote(n, relativePath, hash) {
  * @param force - If true, bypass hash check and always re-sync (useful for metadata regeneration)
  * @param regenerateMetadata - If true, backend AI regenerates all metadata fields, overwriting existing values
  */
-export async function syncSpecificFiles(filePaths, dryRun, client, force = false, regenerateMetadata = false) {
+/**
+ * Stamp the calling Claude Code session into a note that is about to be PUSHED, writing the
+ * result back to disk so local, cloud and the sync baseline all agree on the same bytes.
+ *
+ * Returns the caller's values unchanged — and touches nothing — when the stamp is a no-op, which
+ * is the common case: `upsertSessionFrontmatter` returns the original string unless this session
+ * is new to the note or its last_active has moved by more than a few minutes. That guard is what
+ * keeps a repeat sync from turning "skipped (unchanged)" into a full push plus a version snapshot.
+ */
+function stampForPush(filePath, content, hash, size, mtime, ref, dryRun) {
+    // Callers that already hold real stat values pass them through untouched on the no-op path;
+    // the full-root callers do not use size/mtime from the result, so a stat here is the only
+    // place they would ever be needed.
+    const passthrough = () => ({
+        content,
+        hash,
+        size: size ?? Buffer.byteLength(content, 'utf-8'),
+        mtime: mtime ?? new Date(),
+    });
+    if (!ref || dryRun)
+        return passthrough();
+    const stamped = upsertSessionFrontmatter(content, ref);
+    if (stamped === content)
+        return passthrough();
+    fs.writeFileSync(filePath, stamped, 'utf-8');
+    const st = fs.statSync(filePath);
+    return { content: stamped, hash: NoesisClient.computeHash(stamped), size: st.size, mtime: st.mtime };
+}
+export async function syncSpecificFiles(filePaths, dryRun, client, force = false, regenerateMetadata = false, stampSession = 'auto', sessionId) {
+    // Resolved once per sync run: ~300 KB of bounded transcript reads, not once per file.
+    const resolved = stampSession === 'never' ? null : currentSessionRef(sessionId);
+    const sessionRef = resolved?.ref ?? null;
+    const sessionNote = resolved?.note;
     // Use bidirectional sync result type
     const result = {
         pushed: { created: 0, updated: 0 },
@@ -2892,19 +3013,20 @@ export async function syncSpecificFiles(filePaths, dryRun, client, force = false
                 }
                 else {
                     const project = detectProjectForFile(normalizedPath, matchingRoot.path);
+                    const s = stampForPush(normalizedPath, localContent, localHash, stats.size, stats.mtime, sessionRef, dryRun);
                     const localFile = {
                         path: normalizedPath,
                         relativePath,
-                        content: localContent,
-                        hash: localHash,
-                        mtime: stats.mtime,
-                        size: stats.size,
+                        content: s.content,
+                        hash: s.hash,
+                        mtime: s.mtime,
+                        size: s.size,
                         rootId: matchingRoot.id,
                         rootName: matchingRoot.name,
                         project
                     };
                     await client.upsertNote(localFile, localMetadata, { force, regenerateMetadata });
-                    stateMgr.setBaseline(relativePath, { hash: localHash, lastSyncedAt: new Date().toISOString() }, localContent);
+                    stateMgr.setBaseline(relativePath, { hash: s.hash, lastSyncedAt: new Date().toISOString() }, s.content);
                     result.details.push({ file: relativePath, action: 'pushed_create' });
                     result.pushed.created++;
                     affectedRoots.add(matchingRoot.id);
@@ -2957,13 +3079,14 @@ export async function syncSpecificFiles(filePaths, dryRun, client, force = false
                         }
                         else {
                             const project = detectProjectForFile(normalizedPath, matchingRoot.path);
+                            const s = stampForPush(normalizedPath, localContent, localHash, stats.size, stats.mtime, sessionRef, dryRun);
                             const localFile = {
                                 path: normalizedPath,
                                 relativePath,
-                                content: localContent,
-                                hash: localHash,
-                                mtime: stats.mtime,
-                                size: stats.size,
+                                content: s.content,
+                                hash: s.hash,
+                                mtime: s.mtime,
+                                size: s.size,
                                 rootId: matchingRoot.id,
                                 rootName: matchingRoot.name,
                                 project
@@ -3069,13 +3192,17 @@ export async function syncSpecificFiles(filePaths, dryRun, client, force = false
                         }
                         else {
                             const enrichedHash = NoesisClient.computeHash(enrichedContent);
+                            // Stamp AFTER updateFrontmatter, never before: updateFrontmatter rewrites the
+                            // frontmatter line-by-line and ends by dropping blank lines, so running it over a
+                            // freshly-stamped block would reflow work we just did.
+                            const s = stampForPush(normalizedPath, enrichedContent, enrichedHash, stats.size, stats.mtime, sessionRef, dryRun);
                             const localFile = {
                                 path: normalizedPath,
                                 relativePath,
-                                content: enrichedContent,
-                                hash: enrichedHash,
-                                mtime: stats.mtime,
-                                size: stats.size,
+                                content: s.content,
+                                hash: s.hash,
+                                mtime: s.mtime,
+                                size: s.size,
                                 rootId: matchingRoot.id,
                                 rootName: matchingRoot.name,
                                 project
@@ -3083,8 +3210,10 @@ export async function syncSpecificFiles(filePaths, dryRun, client, force = false
                             // preserveMetadata=true: keep cloud's AI-generated title/description/keywords
                             await client.upsertNote(localFile, localMetadata, { force: true, regenerateMetadata, preserveMetadata: true });
                             // Write enriched content back to local file
-                            fs.writeFileSync(normalizedPath, enrichedContent, 'utf-8');
-                            stateMgr.setBaseline(relativePath, { hash: enrichedHash, lastSyncedAt: new Date().toISOString() }, enrichedContent);
+                            fs.writeFileSync(normalizedPath, s.content, 'utf-8');
+                            // Baseline must be the STAMPED bytes — the ones now on disk. Recording the
+                            // pre-stamp content here would make the next sync see a phantom local edit.
+                            stateMgr.setBaseline(relativePath, { hash: s.hash, lastSyncedAt: new Date().toISOString() }, s.content);
                             result.details.push({ file: relativePath, action: 'pushed_update', reason: 'merged' });
                             result.pushed.updated++;
                             affectedRoots.add(matchingRoot.id);