@parallel-cli/parallel 0.4.6 → 0.4.8

package/dist/agents/tools.js

@@ -45,6 +45,24 @@ export const TOOL_DEFINITIONS = [
             },
         },
     },
+    {
+        type: 'function',
+        function: {
+            name: 'read_many',
+            description: 'Read several known files in one tool call. Use this instead of many sequential read_file calls when the files are independent. Max 8 files.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    paths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Relative file paths to read',
+                    },
+                },
+                required: ['paths'],
+            },
+        },
+    },
     {
         type: 'function',
         function: {
@@ -91,6 +109,28 @@ export const TOOL_DEFINITIONS = [
             },
         },
     },
+    {
+        type: 'function',
+        function: {
+            name: 'inspect_project',
+            description: 'Batch read-only inspection: list files under paths and/or run several regex searches in one call. Prefer this over cascades of grep/head/tail/wc/awk for exploratory checks.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    paths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Folders or files to inspect, default ["."], max 5',
+                    },
+                    patterns: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Regex patterns to search, max 5',
+                    },
+                },
+            },
+        },
+    },
     {
         type: 'function',
         function: {
@@ -134,6 +174,32 @@ export const TOOL_DEFINITIONS = [
             },
         },
     },
+    {
+        type: 'function',
+        function: {
+            name: 'update_steps',
+            description: 'Update the visible Cursor-style task checklist. At task start create 3-6 concrete steps; during work keep exactly one active step and mark completed steps done.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    steps: {
+                        type: 'array',
+                        minItems: 1,
+                        maxItems: 6,
+                        items: {
+                            type: 'object',
+                            properties: {
+                                text: { type: 'string' },
+                                status: { type: 'string', enum: ['pending', 'active', 'done'] },
+                            },
+                            required: ['text', 'status'],
+                        },
+                    },
+                },
+                required: ['steps'],
+            },
+        },
+    },
     {
         type: 'function',
         function: {
@@ -269,6 +335,22 @@ export class ToolExecutor {
     relOf(p) {
         return path.relative(this.projectRoot, this.resolve(p)) || '.';
     }
+    rememberRead(relPath, content) {
+        this.lastRead.set(relPath, { content, revision: this.board.fileRevision(relPath) });
+    }
+    adaptationMessage(relPath, seen, current, verb = 'was modified') {
+        this.board.recordConflict(relPath);
+        const who = this.board.fileActivity.get(relPath);
+        const author = who && who.agentId !== this.agentId ? who.agentName : 'another agent or a shell command';
+        const patch = Diff.createPatch(relPath, seen.content, current, `your read version r${seen.revision}`, `current version r${this.board.fileRevision(relPath)}`, {
+            context: 2,
+        });
+        const excerpt = patch.split('\n').slice(4, 40).join('\n');
+        return (`REAL-TIME ADAPTATION: ${relPath} ${verb} by ${author} after your last read. ` +
+            `Here are THEIR changes (to KEEP, do not erase them):\n${excerpt}\n` +
+            `Call read_file on ${relPath} before editing or rewriting it, then merge your change on top of the current version. ` +
+            `If your work conflicts, send them a note.`);
+    }
     snapshotProject() {
         const snapshot = new Map();
         const walk = (dir, depth) => {
@@ -333,12 +415,16 @@ export class ToolExecutor {
                     return this.listFiles(args?.path ?? '.');
                 case 'read_file':
                     return this.readFile(args.path);
+                case 'read_many':
+                    return this.readMany(args.paths);
                 case 'write_file':
                     return this.writeFile(args.path, args.content);
                 case 'edit_file':
                     return this.editFile(args.path, args.old_string, args.new_string);
                 case 'search':
                     return this.search(args.pattern, args?.path ?? '.');
+                case 'inspect_project':
+                    return this.inspectProject(args);
                 case 'run_command':
                     return await this.runCommand(args.command);
                 case 'post_note':
@@ -347,6 +433,8 @@ export class ToolExecutor {
                 case 'update_status':
                     this.board.updateAgent(this.agentId, { currentAction: String(args.status ?? '') });
                     return 'Status updated, visible to the other agents.';
+                case 'update_steps':
+                    return this.updateSteps(args);
                 case 'ask_user':
                     return await this.askUser(args);
                 case 'load_skill':
@@ -472,6 +560,24 @@ export class ToolExecutor {
         this.board.log(this.agentId, 'tool', `🧩 skill loaded: ${skill.name}`);
         return `[SKILL: ${skill.name}] (${skill.scope})\n${skill.body}\n[END SKILL — follow these instructions for the rest of your task]`;
     }
+    updateSteps(args) {
+        const raw = Array.isArray(args.steps) ? args.steps : [];
+        const steps = raw
+            .slice(0, 6)
+            .map((s) => ({
+            text: String(s?.text ?? '').replace(/\s+/g, ' ').trim().slice(0, 100),
+            status: s?.status === 'done' || s?.status === 'active' ? s.status : 'pending',
+        }))
+            .filter((s) => s.text.length > 0);
+        if (steps.length === 0)
+            return 'ERROR: update_steps needs 1-6 non-empty steps.';
+        const activeCount = steps.filter((s) => s.status === 'active').length;
+        if (activeCount > 1)
+            return 'ERROR: update_steps must have at most one active step.';
+        this.board.updateAgent(this.agentId, { progressSteps: steps });
+        this.board.log(this.agentId, 'tool', `☑ steps ${steps.filter((s) => s.status === 'done').length}/${steps.length}`);
+        return `Visible steps updated (${steps.length} step${steps.length === 1 ? '' : 's'}).`;
+    }
     listFiles(rel) {
         const root = this.resolve(rel);
         const out = [];
@@ -511,14 +617,41 @@ export class ToolExecutor {
     }
     readFile(rel) {
         const abs = this.resolve(rel);
+        const relPath = this.relOf(rel);
         const content = fs.readFileSync(abs, 'utf8');
-        this.lastRead.set(this.relOf(rel), content);
+        this.rememberRead(relPath, content);
+        this.board.resolveConflict(relPath);
         const lines = content.split('\n');
         const numbered = lines.map((l, i) => `${String(i + 1).padStart(4)}|${l}`).join('\n');
         return numbered.length > MAX_OUTPUT
             ? numbered.slice(0, MAX_OUTPUT) + `\n... (truncated, ${lines.length} lines total)`
             : numbered;
     }
+    readMany(paths) {
+        const relPaths = Array.isArray(paths) ? paths.map((p) => String(p)).slice(0, 8) : [];
+        if (relPaths.length === 0)
+            return 'ERROR: read_many needs 1-8 paths.';
+        const chunks = [];
+        for (const rel of relPaths) {
+            try {
+                const abs = this.resolve(rel);
+                const relPath = this.relOf(rel);
+                const content = fs.readFileSync(abs, 'utf8');
+                this.rememberRead(relPath, content);
+                this.board.resolveConflict(relPath);
+                const lines = content.split('\n');
+                const numbered = lines.map((l, i) => `${String(i + 1).padStart(4)}|${l}`).join('\n');
+                const body = numbered.length > Math.floor(MAX_OUTPUT / relPaths.length)
+                    ? numbered.slice(0, Math.floor(MAX_OUTPUT / relPaths.length)) + `\n... (truncated, ${lines.length} lines total)`
+                    : numbered;
+                chunks.push(`--- ${relPath} (${lines.length} lines) ---\n${body}`);
+            }
+            catch (err) {
+                chunks.push(`--- ${rel} ---\nERROR: ${err?.message ?? String(err)}`);
+            }
+        }
+        return chunks.join('\n\n');
+    }
     /**
      * Adaptive co-editing: writing is NEVER blocked by another agent.
      * But if the file changed under you since your last read, you first get
@@ -529,33 +662,23 @@ export class ToolExecutor {
         const abs = this.resolve(rel);
         const exists = fs.existsSync(abs);
         const seen = this.lastRead.get(relPath);
+        const current = exists ? fs.readFileSync(abs, 'utf8') : '';
         if (exists) {
-            const current = fs.readFileSync(abs, 'utf8');
             if (seen === undefined) {
                 const who = this.board.fileActivity.get(relPath);
                 return (`WARNING: ${relPath} already exists${who && who.agentId !== this.agentId ? ` and agent ${who.agentName} is working on it` : ''}. ` +
                     `Read it first (read_file) so you don't erase any work, then rewrite while integrating what exists.`);
             }
-            if (current !== seen) {
-                this.lastRead.set(relPath, current); // sync view so next write passes
-                this.board.recordConflict(relPath); // repeated collisions escalate to the user
-                const who = this.board.fileActivity.get(relPath);
-                const author = who && who.agentId !== this.agentId ? who.agentName : 'another agent';
-                const patch = Diff.createPatch(relPath, seen, current, 'your read version', 'current version', {
-                    context: 2,
-                });
-                const excerpt = patch.split('\n').slice(4, 40).join('\n');
-                return (`REAL-TIME ADAPTATION: ${relPath} was modified by ${author} while you were working. ` +
-                    `Here are THEIR changes (to KEEP, do not erase them):\n${excerpt}\n` +
-                    `Your view is now synchronized. Rewrite the file by MERGING your changes with theirs ` +
-                    `(or use edit_file for targeted changes). If your work conflicts, send them a note.`);
+            if (current !== seen.content || this.board.fileRevision(relPath) !== seen.revision) {
+                return this.adaptationMessage(relPath, seen, current);
             }
         }
         fs.mkdirSync(path.dirname(abs), { recursive: true });
         fs.writeFileSync(abs, content);
-        this.lastRead.set(relPath, content);
-        const before = exists ? (seen ?? '') : '';
+        const before = exists ? current : '';
         this.board.addChange(this.agentId, relPath, before, content);
+        this.rememberRead(relPath, content);
+        this.board.resolveConflict(relPath);
         this.board.recordActivity(relPath, this.agentId, 'write');
         this.board.log(this.agentId, 'tool', `✏ write ${relPath} (${content.length}B)`);
         return `File written: ${relPath} (${content.split('\n').length} lines). The other agents see your diff in real time.`;
@@ -564,11 +687,19 @@ export class ToolExecutor {
         const relPath = this.relOf(rel);
         const abs = this.resolve(rel);
         const before = fs.readFileSync(abs, 'utf8');
+        const seen = this.lastRead.get(relPath);
+        if (seen === undefined) {
+            const who = this.board.fileActivity.get(relPath);
+            return (`WARNING: ${relPath} has not been read by you yet${who && who.agentId !== this.agentId ? ` and agent ${who.agentName} touched it recently` : ''}. ` +
+                `Call read_file first so your targeted edit is based on the current version.`);
+        }
+        if (before !== seen.content || this.board.fileRevision(relPath) !== seen.revision) {
+            return this.adaptationMessage(relPath, seen, before, 'changed');
+        }
         const count = before.split(oldStr).length - 1;
         if (count === 0) {
-            const seen = this.lastRead.get(relPath);
             const who = this.board.fileActivity.get(relPath);
-            const collided = seen !== undefined && seen !== before && who && who.agentId !== this.agentId;
+            const collided = who && who.agentId !== this.agentId;
             if (collided)
                 this.board.recordConflict(relPath);
             const hint = collided
@@ -581,8 +712,9 @@ export class ToolExecutor {
         }
         const after = before.replace(oldStr, newStr);
         fs.writeFileSync(abs, after);
-        this.lastRead.set(relPath, after);
         this.board.addChange(this.agentId, relPath, before, after);
+        this.rememberRead(relPath, after);
+        this.board.resolveConflict(relPath);
         this.board.recordActivity(relPath, this.agentId, 'edit');
         this.board.log(this.agentId, 'tool', `✏ edit ${relPath}`);
         return `File modified: ${relPath}. The other agents see your diff in real time.`;
@@ -637,6 +769,72 @@ export class ToolExecutor {
         walk(root, 0);
         return results.length > 0 ? results.join('\n') : 'No results.';
     }
+    inspectProject(args) {
+        const paths = Array.isArray(args?.paths) && args.paths.length > 0 ? args.paths.map((p) => String(p)).slice(0, 5) : ['.'];
+        const patterns = Array.isArray(args?.patterns) ? args.patterns.map((p) => String(p)).filter(Boolean).slice(0, 5) : [];
+        const files = [];
+        const matches = [];
+        const regexes = [];
+        for (const raw of patterns) {
+            try {
+                regexes.push({ raw, re: new RegExp(raw) });
+            }
+            catch {
+                matches.push(`INVALID REGEX: ${raw}`);
+            }
+        }
+        const visit = (full, depth) => {
+            if (depth > 5 || files.length > 400 || matches.length > 200)
+                return;
+            let stat;
+            try {
+                stat = fs.statSync(full);
+            }
+            catch {
+                return;
+            }
+            if (stat.isDirectory()) {
+                let entries;
+                try {
+                    entries = fs.readdirSync(full, { withFileTypes: true });
+                }
+                catch {
+                    return;
+                }
+                for (const e of entries) {
+                    if (IGNORED.has(e.name) || e.name.startsWith('.git'))
+                        continue;
+                    visit(path.join(full, e.name), depth + 1);
+                }
+                return;
+            }
+            if (!stat.isFile() || stat.size > 1_000_000)
+                return;
+            const relPath = path.relative(this.projectRoot, full);
+            files.push(`${relPath} (${stat.size}B)`);
+            if (regexes.length === 0)
+                return;
+            let content = '';
+            try {
+                content = fs.readFileSync(full, 'utf8');
+            }
+            catch {
+                return;
+            }
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length && matches.length <= 200; i++) {
+                for (const { raw, re } of regexes) {
+                    if (re.test(lines[i]))
+                        matches.push(`${raw} :: ${relPath}:${i + 1}: ${lines[i].trim().slice(0, 140)}`);
+                }
+            }
+        };
+        for (const rel of paths)
+            visit(this.resolve(rel), 0);
+        const fileBlock = files.length > 0 ? files.slice(0, 80).join('\n') : '(no files)';
+        const matchBlock = patterns.length > 0 ? (matches.length > 0 ? matches.slice(0, 120).join('\n') : 'No matches.') : '(no patterns requested)';
+        return `FILES (${files.length} found, first ${Math.min(files.length, 80)} shown)\n${fileBlock}\n\nMATCHES\n${matchBlock}`;
+    }
     async runCommand(command) {
         this.board.setAgentState(this.agentId, 'waiting', `approval: ${command.slice(0, 60)}`);
         const approved = await this.requestApproval(this.agentId, command);

package/dist/commands.js

@@ -12,6 +12,7 @@ export const COMMANDS = [
     { name: '/ask', args: '[Name:] <question> [--model=m]', descKey: 'cmd.ask', group: 'modes', aliases: ['/a'] },
     { name: '/task', args: '[Name:] <task> [--model=m] [#skill]', descKey: 'cmd.task', group: 'modes', aliases: ['/t'] },
     { name: '/plan', args: '[Name:] <task> [--model=m]', descKey: 'cmd.plan', group: 'modes', aliases: ['/p'] },
+    { name: '/review', args: '[agent|all] [prompt]', descKey: 'cmd.review', group: 'modes' },
     { name: '/issue', args: '<n>', descKey: 'cmd.issue', group: 'git' },
     { name: '/specialist', args: '<name> <task> | new <name> [global]', descKey: 'cmd.specialist', group: 'modes' },
     { name: '/specialists', args: '', descKey: 'cmd.specialists', group: 'views' },
@@ -65,9 +66,11 @@ const COMMAND_PALETTE_PRIORITY = [
     '/ask',
     '/task',
     '/plan',
+    '/review',
     '/send',
     '/focus',
     '/attach',
+    '/stop',
     '/agents',
     '/board',
     '/diff',
@@ -174,6 +177,37 @@ function soloAgent(ctl) {
     const list = [...ctl.board.agents.values()];
     return list.length === 1 ? list[0].name : null;
 }
+export function buildReviewPrompt(targetLabel, customPrompt, agents, changes, warnings) {
+    const files = [...new Set(changes.map((c) => c.path))].slice(0, 30);
+    const agentLines = agents.map((a) => `- ${a.name}${a.alias !== a.name ? ` (${a.alias})` : ''} [${a.state}] ${a.task}`).join('\n') || '- no target agent';
+    const fileLines = files.map((f) => `- ${f}`).join('\n') || '- no tracked file changes yet; inspect git status/read relevant files';
+    const warningLines = warnings.map((w) => `- ${w.level.toUpperCase()}: ${w.title} (${w.paths.join(', ') || 'no path'}) ${w.detail}`).join('\n') || '- none';
+    return `Review target: ${targetLabel}
+${customPrompt ? `Extra reviewer instruction: ${customPrompt}\n` : ''}
+You are a lightweight reviewer running in ask mode. Do not edit files and do not gate the whole session.
+
+Target agents:
+${agentLines}
+
+Tracked files to inspect:
+${fileLines}
+
+Coordination warnings:
+${warningLines}
+
+Review the current working tree and recent coordination context. Inspect the files that matter before deciding. Focus on bugs, regressions, broken contracts between agents, missing validation, and unsafe concurrent edits.
+
+Return exactly this structure:
+Verdict: APPROVE | REVISE | BLOCK
+Risks:
+- concrete risk or "none"
+Tests to run:
+- exact command or manual check
+Files to inspect:
+- path and why
+Notes:
+- short reviewer guidance for the user and agents`;
+}
 function spawnFrom(arg, ctl, ui, images, specialist, mode = 'task') {
     const p = ctl.sessionProvider();
     if (!p)
@@ -287,6 +321,25 @@ export function executeInput(raw, ctl, ui, images) {
             spawnFrom(arg, ctl, ui, images, undefined, 'plan');
             return;
         }
+        case '/review': {
+            const [maybeTarget, ...promptParts] = rest;
+            const targetInfo = maybeTarget && maybeTarget.toLowerCase() !== 'all' ? ctl.board.getAgentByName(maybeTarget) : undefined;
+            const hasExplicitTarget = Boolean(maybeTarget && (maybeTarget.toLowerCase() === 'all' || targetInfo));
+            const target = hasExplicitTarget && maybeTarget ? maybeTarget : 'all';
+            const customPrompt = hasExplicitTarget ? promptParts.join(' ').trim() : arg;
+            if (target !== 'all' && !targetInfo)
+                return ui.system(t('m.notFound', { target, list: agentList(ctl) }), 'error');
+            const agents = target === 'all' ? [...ctl.board.agents.values()] : targetInfo ? [targetInfo] : [];
+            const ids = new Set(agents.map((a) => a.id));
+            const names = new Set(agents.map((a) => a.name));
+            const changes = target === 'all' ? ctl.board.changes : ctl.board.changes.filter((c) => ids.has(c.agentId));
+            const warnings = target === 'all'
+                ? ctl.board.workMapWarnings
+                : ctl.board.workMapWarnings.filter((w) => w.agentNames.some((name) => names.has(name)) || w.paths.some((p) => changes.some((c) => c.path === p)));
+            const reviewTarget = target === 'all' ? 'all agents' : `${targetInfo?.name ?? target}`;
+            spawnFrom(`Reviewer: ${buildReviewPrompt(reviewTarget, customPrompt, agents, changes, warnings)}`, ctl, ui, images, undefined, 'ask');
+            return;
+        }
         case '/issue': {
             // Import a task from GitHub Issues (requires the gh CLI, authenticated).
             const n = Number.parseInt(arg, 10);

package/dist/controller.js

@@ -70,6 +70,7 @@ export class Controller extends EventEmitter {
     sessionName;
     /** Conversation JSONL path per agent id — what makes /restore possible. */
     conversationFiles = new Map();
+    noteNudgeLast = new Map();
     /** The session restored at startup (source of /restore conversations). */
     loadedSession = null;
     sessionOnlyProvider = null;
@@ -87,19 +88,7 @@ export class Controller extends EventEmitter {
         };
         this.board.on('update', () => this.emit('update'));
         this.board.on('agent-event', (ev) => this.onAgentEvent(ev));
-        // Only the USER interrupts an agent's in-flight model call (steering).
-        // Agent→agent notes never cut each other off: they are injected at the
-        // recipient's NEXT step, together with the live snapshot + diffs — agents
-        // adapt at action boundaries, they don't interrupt one another.
-        this.board.on('note', (note) => {
-            if (note.to === 'all' || note.to === 'user')
-                return;
-            if (note.from !== 'user')
-                return;
-            const target = this.findAgent(note.to);
-            if (target)
-                target.nudge();
-        });
+        this.board.on('note', (note) => this.nudgeFromNote(note));
         // Autosave: the session (+ conversations, written live by agents) survives a crash.
         const autosave = setInterval(() => this.saveSession(), 30_000);
         autosave.unref();
@@ -182,6 +171,27 @@ export class Controller extends EventEmitter {
             setTimeout(() => process.stdout.write(''), i * 250);
         }
     }
+    nudgeFromNote(note) {
+        if (note.to === 'user' || note.from === 'system')
+            return;
+        const recipients = note.to === 'all'
+            ? [...this.board.agents.values()].filter((a) => a.name.toLowerCase() !== note.from.toLowerCase())
+            : [this.board.getAgentByName(note.to)].filter((a) => Boolean(a));
+        const active = recipients.filter((a) => !['done', 'error', 'stopped'].includes(a.state));
+        for (const info of active) {
+            const agent = this.agents.get(info.id);
+            if (!agent)
+                continue;
+            const now = Date.now();
+            const key = `${info.id}:${note.from.toLowerCase()}`;
+            const rateLimitMs = note.from === 'user' ? 0 : 1500;
+            if (rateLimitMs > 0 && now - (this.noteNudgeLast.get(key) ?? 0) < rateLimitMs)
+                continue;
+            if (agent.nudge(`reading team update from ${note.from}`)) {
+                this.noteNudgeLast.set(key, now);
+            }
+        }
+    }
     // ---------- approvals ----------
     requestApproval = (agentId, command) => {
         const base = command.trim().split(/\s+/)[0];
@@ -637,11 +647,14 @@ export class Controller extends EventEmitter {
                     tokensIn: a.tokensIn,
                     tokensOut: a.tokensOut,
                     cost: a.cost,
+                    endedAt: a.endedAt,
                     providerName,
                     model: a.model,
                     specialist: a.specialist,
                     claims: a.claims,
                     ctxPct: a.ctxPct,
+                    progressSteps: a.progressSteps,
+                    perf: a.perf,
                     conversation: this.conversationFiles.get(a.id),
                 })),
                 notes: this.board.notes.slice(-200),

package/dist/coordination/blackboard.js

@@ -18,10 +18,12 @@ export class Blackboard extends EventEmitter {
     changes = [];
     logs = [];
     workMapWarnings = [];
+    fileRevisions = new Map();
     noteSeq = 0;
     changeSeq = 0;
     logSeq = 0;
     persistTimer = null;
+    recentNoteKeys = new Map();
     constructor(projectRoot) {
         super();
         this.projectRoot = projectRoot;
@@ -56,8 +58,14 @@ export class Blackboard extends EventEmitter {
         if (action !== undefined)
             a.currentAction = action;
         // A finished agent no longer holds any declared work area.
-        if (state === 'done' || state === 'stopped' || state === 'error')
+        if (state === 'done' || state === 'stopped' || state === 'error') {
             a.claims = undefined;
+            if (!a.endedAt)
+                a.endedAt = Date.now();
+        }
+        else {
+            a.endedAt = undefined;
+        }
         if (prev !== state)
             this.emit('agent-event', { type: 'state', id, state, prev });
         this.touch();
@@ -79,6 +87,7 @@ export class Blackboard extends EventEmitter {
             agentId,
             agentName: agent?.name ?? agentId,
             op,
+            revision: this.fileRevision(relPath),
             ts: Date.now(),
         });
         this.touch();
@@ -91,10 +100,22 @@ export class Blackboard extends EventEmitter {
             if (target)
                 to = target.name;
         }
-        const note = { id: ++this.noteSeq, from, to, content, ts: Date.now() };
+        const now = Date.now();
+        const key = `${from.toLowerCase()}\u0000${to.toLowerCase()}\u0000${content.trim()}`;
+        const recent = this.recentNoteKeys.get(key);
+        if (recent && now - recent.ts < 10_000)
+            return recent;
+        const note = { id: ++this.noteSeq, from, to, content, ts: now };
         this.notes.push(note);
         if (this.notes.length > 400)
             this.notes.splice(0, this.notes.length - 400);
+        this.recentNoteKeys.set(key, note);
+        if (this.recentNoteKeys.size > 100) {
+            for (const [k, n] of this.recentNoteKeys) {
+                if (now - n.ts > 30_000 || this.recentNoteKeys.size > 100)
+                    this.recentNoteKeys.delete(k);
+            }
+        }
         this.log('', 'note', `✉ ${from} → ${to}: ${content}`);
         // Lets the controller nudge the recipient so it reads the note NOW
         // instead of at its next natural turn.
@@ -112,6 +133,9 @@ export class Blackboard extends EventEmitter {
     // ---------- file changes (real-time diff feed) ----------
     addChange(agentId, relPath, before, after) {
         const agent = this.agents.get(agentId);
+        const beforeRevision = this.fileRevision(relPath);
+        const afterRevision = beforeRevision + 1;
+        this.fileRevisions.set(relPath, afterRevision);
         const change = {
             id: ++this.changeSeq,
             agentId,
@@ -119,6 +143,8 @@ export class Blackboard extends EventEmitter {
             path: relPath,
             before,
             after,
+            beforeRevision,
+            afterRevision,
             ts: Date.now(),
         };
         this.changes.push(change);
@@ -160,6 +186,14 @@ export class Blackboard extends EventEmitter {
     lastChangeId() {
         return this.changes.length > 0 ? this.changes[this.changes.length - 1].id : 0;
     }
+    fileRevision(relPath) {
+        return this.fileRevisions.get(relPath) ?? 0;
+    }
+    resolveConflict(relPath) {
+        this.conflictCounts.delete(relPath);
+        this.workMapWarnings = this.workMapWarnings.filter((w) => w.id !== `conflict:${relPath}`);
+        this.touch();
+    }
     static normClaim(p) {
         return p.trim().replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
     }
@@ -295,6 +329,14 @@ export class Blackboard extends EventEmitter {
         this.workMapWarnings = [...(data.workMapWarnings ?? [])].sort((a, b) => a.ts - b.ts);
         this.noteSeq = this.notes.reduce((max, n) => Math.max(max, n.id), 0);
         this.changeSeq = this.changes.reduce((max, c) => Math.max(max, c.id), 0);
+        this.fileRevisions = new Map();
+        for (const c of this.changes) {
+            this.fileRevisions.set(c.path, Math.max(this.fileRevision(c.path), c.afterRevision ?? c.id));
+        }
+        for (const a of this.fileActivity.values()) {
+            if (a.revision !== undefined)
+                this.fileRevisions.set(a.path, Math.max(this.fileRevision(a.path), a.revision));
+        }
         this.touch();
     }
 }