clementine-agent 1.1.20 → 1.1.22

package/dist/cli/index.js

@@ -428,17 +428,22 @@ async function cmdRestart(options) {
     }
 }
 function cmdStatus() {
+    const DIM = '\x1b[0;90m';
+    const RESET = '\x1b[0m';
     const pid = readPid();
     const name = getAssistantName();
+    const localVersion = readPkgVersion(PACKAGE_ROOT);
     if (!pid) {
-        console.log(`  ${name} is not running (no PID file).`);
+        console.log(`  ${name} is not running ${DIM}(no PID file, v${localVersion})${RESET}.`);
+        surfaceUpdateNudge(localVersion);
         return;
     }
     if (!isProcessAlive(pid)) {
-        console.log(`  ${name} is not running (stale PID ${pid}).`);
+        console.log(`  ${name} is not running ${DIM}(stale PID ${pid}, v${localVersion})${RESET}.`);
+        surfaceUpdateNudge(localVersion);
         return;
     }
-    console.log(`  ${name} is running (PID ${pid})`);
+    console.log(`  ${name} is running ${DIM}(PID ${pid}, v${localVersion})${RESET}`);
     // Show uptime from PID file mtime
     try {
         const { mtimeMs } = statSync(getPidFilePath());
@@ -468,6 +473,36 @@ function cmdStatus() {
     if (channels.length > 0) {
         console.log(`  Channels: ${channels.join(', ')}`);
     }
+    surfaceUpdateNudge(localVersion);
+}
+/**
+ * Print a one-line nudge if a newer version is on npm. Reads the cached
+ * result synchronously (no network on the hot path) and fires off an async
+ * refresh in the background so the next call has fresh data.
+ */
+function surfaceUpdateNudge(localVersion) {
+    const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
+    const YELLOW = '\x1b[1;33m';
+    const RESET = '\x1b[0m';
+    try {
+        const cached = (() => {
+            // Lazy require to avoid pulling https/network into trivial CLI calls
+            // when the cache module isn't needed.
+            const { readCachedUpdateCheck } = require('./version-check.js');
+            return readCachedUpdateCheck(BASE_DIR, localVersion);
+        })();
+        if (cached?.updateAvailable && cached.latestVersion) {
+            console.log(`  ${YELLOW}⬆${RESET}  Update available: ${BOLD}v${cached.latestVersion}${RESET} ${DIM}(you're on v${localVersion})${RESET}`);
+            console.log(`     ${DIM}Run: ${BOLD}clementine update restart${RESET}`);
+        }
+        // Fire-and-forget background refresh — never blocks status output.
+        const { checkForUpdate } = require('./version-check.js');
+        void checkForUpdate(BASE_DIR, localVersion).catch(() => { });
+    }
+    catch {
+        // version-check failed to load — degrade silently
+    }
 }
 function cmdDoctor(opts = {}) {
     const DIM = '\x1b[0;90m';
@@ -1991,11 +2026,16 @@ program
 });
 program
     .command('update')
-    .description('Pull latest code, rebuild, and reinstall (preserves config)')
-    .argument('[action]', 'Optional: "restart" to restart daemon after update')
+    .description('Pull latest code, rebuild, and reinstall (preserves config). Pass "history" to show recent updates.')
+    .argument('[action]', 'Optional: "restart" = restart daemon after update; "history" = show update log')
     .option('--restart', 'Restart daemon after update')
     .option('--dry-run', 'Preview what would happen without making changes')
+    .option('-n, --limit <n>', 'For history mode: max entries to show', '10')
     .action((action, options) => {
+    if (action === 'history') {
+        cmdUpdateHistory(parseInt(options.limit ?? '10', 10));
+        return;
+    }
     if (action === 'restart')
         options.restart = true;
     cmdUpdate(options).catch((err) => {
@@ -2257,6 +2297,223 @@ agentCmd
 const memoryCmd = program
     .command('memory')
     .description('Search and manage memory');
+memoryCmd
+    .command('status')
+    .description('Show memory store stats — chunk count, embeddings coverage, agent/category breakdown, salience')
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (opts) => {
+    const BOLD = '\x1b[1m';
+    const DIM = '\x1b[0;90m';
+    const CYAN = '\x1b[0;36m';
+    const RESET = '\x1b[0m';
+    try {
+        const { MemoryStore } = await import('../memory/store.js');
+        const VAULT_DIR = path.join(BASE_DIR, 'vault');
+        const DB_PATH = path.join(VAULT_DIR, '.memory.db');
+        const store = new MemoryStore(DB_PATH, VAULT_DIR);
+        const stats = store.getMemoryStats();
+        if (opts.json) {
+            console.log(JSON.stringify(stats, null, 2));
+            return;
+        }
+        const pct = stats.totalChunks > 0
+            ? ((stats.chunksWithEmbeddings / stats.totalChunks) * 100).toFixed(1)
+            : '0.0';
+        console.log();
+        console.log(`  ${BOLD}Memory store${RESET}  ${DIM}${DB_PATH}${RESET}`);
+        console.log();
+        console.log(`  Total chunks:         ${BOLD}${stats.totalChunks.toLocaleString()}${RESET}`);
+        console.log(`  With embeddings:      ${stats.chunksWithEmbeddings.toLocaleString()} ${DIM}(${pct}%, TF-IDF 512-dim)${RESET}`);
+        console.log(`  Pinned (manual):      ${stats.pinnedChunks}`);
+        console.log(`  Avg salience:         ${stats.avgSalience.toFixed(3)} ${DIM}(0 = no access boost; >1 = strong reinforcement)${RESET}`);
+        if (stats.oldestUpdated) {
+            console.log(`  Date range:           ${stats.oldestUpdated.slice(0, 10)} → ${stats.newestUpdated?.slice(0, 10)}`);
+        }
+        console.log();
+        console.log(`  ${BOLD}Per agent${RESET}`);
+        for (const a of stats.perAgent.slice(0, 10)) {
+            console.log(`    ${CYAN}${a.agentSlug.padEnd(28)}${RESET}${a.count.toLocaleString().padStart(8)}`);
+        }
+        if (stats.perAgent.length > 10)
+            console.log(`    ${DIM}…and ${stats.perAgent.length - 10} more${RESET}`);
+        console.log();
+        console.log(`  ${BOLD}Per category${RESET}`);
+        for (const c of stats.perCategory.slice(0, 10)) {
+            console.log(`    ${CYAN}${c.category.padEnd(28)}${RESET}${c.count.toLocaleString().padStart(8)}`);
+        }
+        console.log();
+    }
+    catch (err) {
+        console.error(`  Error reading memory stats: ${err}`);
+        process.exit(1);
+    }
+});
+memoryCmd
+    .command('pin <chunkId>')
+    .description('Pin a chunk — gives its score a 2x boost in recall (use chunk IDs from `memory search`)')
+    .action(async (chunkIdStr) => {
+    const GREEN = '\x1b[0;32m';
+    const RED = '\x1b[0;31m';
+    const RESET = '\x1b[0m';
+    const chunkId = parseInt(chunkIdStr, 10);
+    if (!Number.isFinite(chunkId) || chunkId <= 0) {
+        console.error(`  ${RED}Invalid chunk id${RESET}: "${chunkIdStr}". Use IDs from \`clementine memory search\`.`);
+        process.exit(1);
+    }
+    try {
+        const { MemoryStore } = await import('../memory/store.js');
+        const VAULT_DIR = path.join(BASE_DIR, 'vault');
+        const DB_PATH = path.join(VAULT_DIR, '.memory.db');
+        const store = new MemoryStore(DB_PATH, VAULT_DIR);
+        const ok = store.setPinned(chunkId, true);
+        if (!ok) {
+            console.error(`  ${RED}Chunk ${chunkId} not found.${RESET}`);
+            process.exit(1);
+        }
+        console.log(`  ${GREEN}✓${RESET} Pinned chunk ${chunkId}. It now gets a 2× boost in memory_recall.`);
+    }
+    catch (err) {
+        console.error(`  Error pinning chunk: ${err}`);
+        process.exit(1);
+    }
+});
+memoryCmd
+    .command('unpin <chunkId>')
+    .description('Unpin a chunk — removes the manual 2x boost, leaves automatic salience untouched')
+    .action(async (chunkIdStr) => {
+    const GREEN = '\x1b[0;32m';
+    const RED = '\x1b[0;31m';
+    const RESET = '\x1b[0m';
+    const chunkId = parseInt(chunkIdStr, 10);
+    if (!Number.isFinite(chunkId) || chunkId <= 0) {
+        console.error(`  ${RED}Invalid chunk id${RESET}: "${chunkIdStr}".`);
+        process.exit(1);
+    }
+    try {
+        const { MemoryStore } = await import('../memory/store.js');
+        const VAULT_DIR = path.join(BASE_DIR, 'vault');
+        const DB_PATH = path.join(VAULT_DIR, '.memory.db');
+        const store = new MemoryStore(DB_PATH, VAULT_DIR);
+        const ok = store.setPinned(chunkId, false);
+        if (!ok) {
+            console.error(`  ${RED}Chunk ${chunkId} not found.${RESET}`);
+            process.exit(1);
+        }
+        console.log(`  ${GREEN}✓${RESET} Unpinned chunk ${chunkId}.`);
+    }
+    catch (err) {
+        console.error(`  Error unpinning chunk: ${err}`);
+        process.exit(1);
+    }
+});
+memoryCmd
+    .command('dedup')
+    .description('Find near-duplicate chunks via embedding cosine similarity. Dry-run by default.')
+    .option('--threshold <n>', 'Cosine similarity threshold (0-1)', '0.95')
+    .option('--apply', 'Actually delete duplicates (default: dry-run preview only)')
+    .option('--limit <n>', 'Max clusters to report', '50')
+    .action(async (opts) => {
+    const BOLD = '\x1b[1m';
+    const DIM = '\x1b[0;90m';
+    const GREEN = '\x1b[0;32m';
+    const YELLOW = '\x1b[0;33m';
+    const RESET = '\x1b[0m';
+    const threshold = parseFloat(opts.threshold);
+    const limit = parseInt(opts.limit, 10);
+    try {
+        const { MemoryStore } = await import('../memory/store.js');
+        const VAULT_DIR = path.join(BASE_DIR, 'vault');
+        const DB_PATH = path.join(VAULT_DIR, '.memory.db');
+        const store = new MemoryStore(DB_PATH, VAULT_DIR);
+        const clusters = store.findNearDuplicates({ threshold, limit });
+        if (clusters.length === 0) {
+            console.log(`  ${GREEN}No near-duplicates found above threshold ${threshold}.${RESET}`);
+            return;
+        }
+        const totalDupes = clusters.reduce((sum, c) => sum + c.duplicates.length, 0);
+        console.log();
+        console.log(`  ${BOLD}Found ${clusters.length} cluster${clusters.length === 1 ? '' : 's'} (${totalDupes} duplicate chunk${totalDupes === 1 ? '' : 's'})${RESET}`);
+        console.log(`  ${DIM}Keeping the most-recent chunk per cluster; older copies will be removed if --apply is passed.${RESET}`);
+        console.log();
+        for (const cluster of clusters.slice(0, 20)) {
+            const keepLabel = `${cluster.keep.sourceFile} > ${cluster.keep.section}`;
+            const agent = cluster.keep.agentSlug ?? 'global';
+            console.log(`  ${BOLD}KEEP${RESET} #${cluster.keep.chunkId}  ${DIM}[${agent}]${RESET}  ${keepLabel}`);
+            for (const dup of cluster.duplicates) {
+                const dupLabel = `${dup.sourceFile} > ${dup.section}`;
+                console.log(`    ${YELLOW}drop${RESET} #${dup.chunkId}  sim=${dup.similarity.toFixed(3)}  ${DIM}${dupLabel}${RESET}`);
+            }
+        }
+        if (clusters.length > 20) {
+            console.log(`  ${DIM}…and ${clusters.length - 20} more clusters (raise --limit to see them).${RESET}`);
+        }
+        console.log();
+        if (opts.apply) {
+            const allDupeIds = clusters.flatMap(c => c.duplicates.map(d => d.chunkId));
+            const removed = store.deleteChunks(allDupeIds);
+            console.log(`  ${GREEN}✓${RESET} Deleted ${removed} duplicate chunk${removed === 1 ? '' : 's'}.`);
+        }
+        else {
+            console.log(`  ${DIM}This was a preview. Re-run with ${BOLD}--apply${RESET}${DIM} to delete the duplicates.${RESET}`);
+        }
+        console.log();
+    }
+    catch (err) {
+        console.error(`  Error during dedup: ${err}`);
+        process.exit(1);
+    }
+});
+memoryCmd
+    .command('cross-agent')
+    .description('Surface chunks that recur across 3+ agents — candidates for promotion to global memory')
+    .option('--threshold <n>', 'Cosine similarity threshold for "same idea" (0-1)', '0.88')
+    .option('--min-agents <n>', 'Minimum distinct agents touched by a cluster', '3')
+    .option('--limit <n>', 'Max clusters to report', '30')
+    .action(async (opts) => {
+    const BOLD = '\x1b[1m';
+    const DIM = '\x1b[0;90m';
+    const CYAN = '\x1b[0;36m';
+    const GREEN = '\x1b[0;32m';
+    const RESET = '\x1b[0m';
+    try {
+        const { MemoryStore } = await import('../memory/store.js');
+        const VAULT_DIR = path.join(BASE_DIR, 'vault');
+        const DB_PATH = path.join(VAULT_DIR, '.memory.db');
+        const store = new MemoryStore(DB_PATH, VAULT_DIR);
+        const clusters = store.findCrossAgentRecurrence({
+            threshold: parseFloat(opts.threshold),
+            minAgents: parseInt(opts.minAgents, 10),
+            limit: parseInt(opts.limit, 10),
+        });
+        if (clusters.length === 0) {
+            console.log(`  ${GREEN}No cross-agent recurrence found above threshold ${opts.threshold} touching ${opts.minAgents}+ agents.${RESET}`);
+            return;
+        }
+        console.log();
+        console.log(`  ${BOLD}Found ${clusters.length} cluster${clusters.length === 1 ? '' : 's'} recurring across ${opts.minAgents}+ agents${RESET}`);
+        console.log(`  ${DIM}These are candidates for promotion to global memory — facts the team has independently arrived at.${RESET}`);
+        console.log();
+        for (const c of clusters) {
+            const preview = c.representative.content.replace(/\n/g, ' ').slice(0, 140);
+            console.log(`  ${BOLD}Cluster (${c.agents.length} agents)${RESET}  ${CYAN}${c.agents.join(', ')}${RESET}`);
+            console.log(`    representative #${c.representative.chunkId}  ${DIM}${c.representative.sourceFile} > ${c.representative.section}${RESET}`);
+            console.log(`    ${DIM}${preview}${preview.length >= 140 ? '…' : ''}${RESET}`);
+            for (const m of c.members.slice(1, 4)) {
+                console.log(`    ${DIM}└─ #${m.chunkId} [${m.agentSlug}] sim=${m.similarity.toFixed(3)}${RESET}`);
+            }
+            if (c.members.length > 4) {
+                console.log(`    ${DIM}└─ +${c.members.length - 4} more${RESET}`);
+            }
+            console.log();
+        }
+        console.log(`  ${DIM}To promote a chunk to global, use the agent-side ${BOLD}memory_promote${RESET}${DIM} tool with the chunk id, or pin it with ${BOLD}clementine memory pin <id>${RESET}${DIM} for now.${RESET}`);
+        console.log();
+    }
+    catch (err) {
+        console.error(`  Error finding cross-agent recurrence: ${err}`);
+        process.exit(1);
+    }
+});
 memoryCmd
     .command('search <query>')
     .description('Search memory (full-text)')
@@ -2281,10 +2538,13 @@ memoryCmd
             const source = r.sourceFile ? path.basename(r.sourceFile) : 'unknown';
             const section = r.section || '';
             const snippet = r.content.replace(/\n/g, ' ').slice(0, 120);
-            console.log(`  ${BOLD}${source}${RESET}${section ? ` › ${CYAN}${section}${RESET}` : ''}`);
+            const pinned = r.pinned ? ' 📌' : '';
+            console.log(`  ${DIM}#${r.chunkId}${RESET}  ${BOLD}${source}${RESET}${section ? ` › ${CYAN}${section}${RESET}` : ''}${pinned}`);
             console.log(`  ${DIM}${snippet}${snippet.length >= 120 ? '…' : ''}${RESET}`);
             console.log();
         }
+        console.log(`  ${DIM}Tip: pin a chunk to boost its score in recall — ${BOLD}clementine memory pin <id>${RESET}`);
+        console.log();
     }
     catch (err) {
         console.error(`  Error searching memory: ${err}`);
@@ -2363,14 +2623,113 @@ projectsCmd
     }
 });
 // ── Update command ──────────────────────────────────────────────────
+/** Print the last N entries from update-history.jsonl. */
+function cmdUpdateHistory(limit) {
+    const BOLD = '\x1b[1m';
+    const DIM = '\x1b[0;90m';
+    const GREEN = '\x1b[0;32m';
+    const RED = '\x1b[0;31m';
+    const RESET = '\x1b[0m';
+    const historyPath = path.join(BASE_DIR, 'update-history.jsonl');
+    if (!existsSync(historyPath)) {
+        console.log();
+        console.log(`  ${DIM}No update history yet (${historyPath} doesn't exist).${RESET}`);
+        console.log(`  Run ${BOLD}clementine update${RESET} once to start the log.`);
+        console.log();
+        return;
+    }
+    const lines = readFileSync(historyPath, 'utf-8').split('\n').filter(Boolean);
+    const entries = lines
+        .map(l => { try {
+        return JSON.parse(l);
+    }
+    catch {
+        return null;
+    } })
+        .filter((e) => e !== null)
+        .slice(-Math.max(1, limit))
+        .reverse();
+    if (entries.length === 0) {
+        console.log(`  ${DIM}History file exists but is empty or unparseable.${RESET}`);
+        return;
+    }
+    console.log();
+    console.log(`  ${BOLD}Update history${RESET}  ${DIM}(${historyPath})${RESET}`);
+    console.log();
+    for (const e of entries) {
+        const ts = String(e.timestamp ?? '').slice(0, 19).replace('T', ' ');
+        const from = String(e.fromVersion ?? '?');
+        const to = String(e.toVersion ?? '?');
+        const flavor = String(e.flavor ?? 'git');
+        const failed = e.failed === true;
+        const arrow = from === to ? '=' : '→';
+        const verLabel = failed
+            ? `${RED}v${from} ${arrow} v${to} FAILED${RESET}`
+            : (from === to ? `${DIM}v${from}${RESET}` : `v${from} ${arrow} ${BOLD}v${to}${RESET}`);
+        const dur = typeof e.durationMs === 'number' ? ` ${DIM}(${Math.round(e.durationMs / 1000)}s)${RESET}` : '';
+        console.log(`  ${DIM}${ts}${RESET}  ${verLabel}  ${DIM}[${flavor}]${RESET}${dur}`);
+        if (typeof e.commitHash === 'string' && e.commitHash) {
+            console.log(`     ${DIM}commit ${e.commitHash}${e.commitDate ? ` (${e.commitDate})` : ''}, ${e.commitsPulled ?? 0} commit${e.commitsPulled === 1 ? '' : 's'} pulled${RESET}`);
+        }
+        if (typeof e.summary === 'string' && e.summary) {
+            const trimmed = e.summary.length > 100 ? e.summary.slice(0, 100) + '…' : e.summary;
+            console.log(`     ${DIM}${trimmed}${RESET}`);
+        }
+        if (failed && typeof e.error === 'string') {
+            console.log(`     ${RED}error: ${e.error.slice(0, 120)}${RESET}`);
+        }
+        const modSummary = [];
+        if (typeof e.modsReapplied === 'number' && e.modsReapplied > 0)
+            modSummary.push(`${e.modsReapplied} re-applied`);
+        if (typeof e.modsSuperseded === 'number' && e.modsSuperseded > 0)
+            modSummary.push(`${e.modsSuperseded} superseded`);
+        if (typeof e.modsNeedReconciliation === 'number' && e.modsNeedReconciliation > 0)
+            modSummary.push(`${e.modsNeedReconciliation} need attention`);
+        if (typeof e.modsFailed === 'number' && e.modsFailed > 0)
+            modSummary.push(`${e.modsFailed} failed`);
+        if (modSummary.length > 0) {
+            console.log(`     ${DIM}source mods: ${modSummary.join(', ')}${RESET}`);
+        }
+    }
+    console.log();
+    console.log(`  ${GREEN}Showing ${entries.length}${RESET}${DIM} of ${lines.length} total entries.${RESET}`);
+    console.log();
+}
+/** Read the npm version from a package.json (returns 'unknown' on failure). */
+function readPkgVersion(packageRoot) {
+    try {
+        const pkgPath = path.join(packageRoot, 'package.json');
+        if (!existsSync(pkgPath))
+            return 'unknown';
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Append one line to the update-history log. Append-only, never throws. */
+function appendUpdateHistory(entry) {
+    try {
+        const historyPath = path.join(BASE_DIR, 'update-history.jsonl');
+        const line = JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + '\n';
+        require('node:fs').appendFileSync(historyPath, line, { mode: 0o600 });
+    }
+    catch {
+        // Non-fatal — history is observability, not critical state.
+    }
+}
 async function cmdUpdate(options) {
     const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
     const GREEN = '\x1b[0;32m';
     const YELLOW = '\x1b[1;33m';
     const RED = '\x1b[0;31m';
     const RESET = '\x1b[0m';
+    const updateStartedAt = Date.now();
+    const previousVersion = readPkgVersion(PACKAGE_ROOT);
     console.log();
-    console.log(`  ${DIM}Updating ${getAssistantName()}...${RESET}`);
+    console.log(`  ${DIM}Updating ${getAssistantName()} (current: v${previousVersion})...${RESET}`);
     console.log();
     // 1. Detect install flavor. Two valid paths:
     //    - git-clone install (PACKAGE_ROOT has .git) → pull + rebuild path below
@@ -2388,12 +2747,36 @@ async function cmdUpdate(options) {
         console.log();
         try {
             execSync('npm install -g clementine-agent@latest', { stdio: 'inherit' });
+            const newVersion = readPkgVersion(PACKAGE_ROOT);
             console.log();
-            console.log(`  ${GREEN}OK${RESET}  Updated via npm`);
+            if (previousVersion !== 'unknown' && newVersion !== 'unknown' && previousVersion !== newVersion) {
+                console.log(`  ${GREEN}OK${RESET}  Updated v${previousVersion} → ${BOLD}v${newVersion}${RESET}`);
+            }
+            else if (previousVersion === newVersion) {
+                console.log(`  ${GREEN}OK${RESET}  Already on latest (v${newVersion})`);
+            }
+            else {
+                console.log(`  ${GREEN}OK${RESET}  Updated via npm`);
+            }
+            appendUpdateHistory({
+                flavor: 'npm-global',
+                fromVersion: previousVersion,
+                toVersion: newVersion,
+                durationMs: Date.now() - updateStartedAt,
+                restartRequested: !!options.restart,
+            });
         }
         catch (err) {
             console.error(`  ${RED}FAIL${RESET}  npm update failed: ${String(err).slice(0, 200)}`);
             console.error(`  ${YELLOW}Hint${RESET}  If you see EACCES, see README "Troubleshooting" for npm prefix setup.`);
+            appendUpdateHistory({
+                flavor: 'npm-global',
+                fromVersion: previousVersion,
+                toVersion: previousVersion,
+                durationMs: Date.now() - updateStartedAt,
+                failed: true,
+                error: String(err).slice(0, 300),
+            });
             process.exit(1);
         }
         if (options.restart) {
@@ -2932,6 +3315,26 @@ async function cmdUpdate(options) {
         }).trim().slice(0, 10);
     }
     catch { /* best effort */ }
+    // Capture the new version once the build is verified — package.json on
+    // disk is now authoritative for the version we're about to run.
+    const newVersion = readPkgVersion(PACKAGE_ROOT);
+    // Persist update history before the restart (in case daemon restart fails,
+    // we still have the record of what was attempted).
+    appendUpdateHistory({
+        flavor: 'git',
+        fromVersion: previousVersion,
+        toVersion: newVersion,
+        commitHash,
+        commitDate,
+        commitsPulled,
+        summary: pullSummary.split('\n').slice(0, 5).join('; '),
+        modsReapplied: reconcileResult?.reapplied.length ?? 0,
+        modsSuperseded: reconcileResult?.superseded.length ?? 0,
+        modsNeedReconciliation: reconcileResult?.needsReconciliation.length ?? 0,
+        modsFailed: reconcileResult?.failed.length ?? 0,
+        durationMs: Date.now() - updateStartedAt,
+        restartRequested: !!(options.restart || wasRunning),
+    });
     if (options.restart || wasRunning) {
         const sentinelPath = path.join(BASE_DIR, '.restart-sentinel.json');
         const sentinel = {
@@ -2939,6 +3342,8 @@ async function cmdUpdate(options) {
             restartedAt: new Date().toISOString(),
             reason: 'update',
             updateDetails: {
+                previousVersion,
+                newVersion,
                 commitHash,
                 commitDate,
                 commitsBehind: commitsPulled,
@@ -3029,7 +3434,13 @@ async function cmdUpdate(options) {
     }
     // 14. Show current version
     console.log();
-    if (commitHash) {
+    if (previousVersion !== 'unknown' && newVersion !== 'unknown' && previousVersion !== newVersion) {
+        console.log(`  ${GREEN}Updated v${previousVersion} → ${BOLD}v${newVersion}${RESET}${commitHash ? ` ${DIM}(${commitHash})${RESET}` : ''}`);
+    }
+    else if (previousVersion === newVersion && previousVersion !== 'unknown') {
+        console.log(`  ${GREEN}Already on latest (v${newVersion})${RESET}${commitHash ? ` ${DIM}(${commitHash})${RESET}` : ''}`);
+    }
+    else if (commitHash) {
         console.log(`  ${GREEN}Updated to ${commitHash} (${commitDate})${RESET}`);
     }
     else {

package/dist/cli/version-check.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Background "is there a newer version on npm?" check.
+ *
+ * Polls the public npm registry once per `CACHE_TTL_MS` (default 24h) and
+ * caches the result on disk so subsequent calls are instant. Surfaced in
+ * `clementine status` and the dashboard header so the user discovers
+ * updates without remembering to run `clementine update`.
+ *
+ * Pure read-only — never installs anything. Network failures are silent
+ * (offline → no nudge, not an error).
+ */
+export interface VersionCheckResult {
+    localVersion: string;
+    latestVersion: string | null;
+    /** True when latestVersion is strictly greater than localVersion. */
+    updateAvailable: boolean;
+    /** ISO of last successful registry check. null = never checked or fetch failed. */
+    checkedAt: string | null;
+    /** True when the cache was used (no network call this invocation). */
+    fromCache: boolean;
+}
+/**
+ * Check whether a newer version is available. Uses the cache when fresh.
+ * Pass `force = true` to bypass the cache (e.g. from a "check now" CLI flag).
+ */
+export declare function checkForUpdate(baseDir: string, localVersion: string, opts?: {
+    force?: boolean;
+}): Promise<VersionCheckResult>;
+/**
+ * Synchronous read of the cached result — used in fast paths like
+ * `clementine status` so we never block on a network call. Returns null
+ * when there's no cache yet.
+ */
+export declare function readCachedUpdateCheck(baseDir: string, localVersion: string): VersionCheckResult | null;
+//# sourceMappingURL=version-check.d.ts.map

package/dist/cli/version-check.js

@@ -0,0 +1,147 @@
+/**
+ * Background "is there a newer version on npm?" check.
+ *
+ * Polls the public npm registry once per `CACHE_TTL_MS` (default 24h) and
+ * caches the result on disk so subsequent calls are instant. Surfaced in
+ * `clementine status` and the dashboard header so the user discovers
+ * updates without remembering to run `clementine update`.
+ *
+ * Pure read-only — never installs anything. Network failures are silent
+ * (offline → no nudge, not an error).
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import https from 'node:https';
+const PACKAGE_NAME = 'clementine-agent';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+function cachePath(baseDir) {
+    return path.join(baseDir, '.update-check.json');
+}
+function readCache(baseDir) {
+    try {
+        const p = cachePath(baseDir);
+        if (!existsSync(p))
+            return null;
+        return JSON.parse(readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(baseDir, entry) {
+    try {
+        writeFileSync(cachePath(baseDir), JSON.stringify(entry, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // Non-fatal — cache is an optimization, not state.
+    }
+}
+/**
+ * Fetch the latest published version of the package from npm. Resolves null
+ * on any network/parse error so callers can degrade silently.
+ */
+function fetchLatestFromNpm(timeoutMs = 5000) {
+    return new Promise(resolve => {
+        const req = https.get(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, { timeout: timeoutMs, headers: { Accept: 'application/json' } }, res => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            let body = '';
+            res.setEncoding('utf-8');
+            res.on('data', chunk => { body += chunk; });
+            res.on('end', () => {
+                try {
+                    const parsed = JSON.parse(body);
+                    resolve(parsed.version ?? null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on('error', () => resolve(null));
+        req.on('timeout', () => { req.destroy(); resolve(null); });
+    });
+}
+/**
+ * Compare two semver strings lexicographically by parts. Returns positive
+ * when `a` > `b`, negative when `a` < `b`, zero when equal. Tolerates
+ * pre-release suffixes by ignoring them (we only care about released bumps).
+ */
+function compareSemver(a, b) {
+    if (a === b)
+        return 0;
+    const partsA = a.replace(/[-+].*$/, '').split('.').map(n => parseInt(n, 10) || 0);
+    const partsB = b.replace(/[-+].*$/, '').split('.').map(n => parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+        const av = partsA[i] ?? 0;
+        const bv = partsB[i] ?? 0;
+        if (av !== bv)
+            return av - bv;
+    }
+    return 0;
+}
+/**
+ * Check whether a newer version is available. Uses the cache when fresh.
+ * Pass `force = true` to bypass the cache (e.g. from a "check now" CLI flag).
+ */
+export async function checkForUpdate(baseDir, localVersion, opts = {}) {
+    const cache = readCache(baseDir);
+    const now = Date.now();
+    const cacheFresh = !!cache && (now - new Date(cache.checkedAt).getTime() < CACHE_TTL_MS);
+    if (cache && cacheFresh && !opts.force) {
+        return {
+            localVersion,
+            latestVersion: cache.latestVersion,
+            updateAvailable: compareSemver(cache.latestVersion, localVersion) > 0,
+            checkedAt: cache.checkedAt,
+            fromCache: true,
+        };
+    }
+    const latest = await fetchLatestFromNpm();
+    if (!latest) {
+        // Couldn't reach the registry — fall back to stale cache if we have one.
+        if (cache) {
+            return {
+                localVersion,
+                latestVersion: cache.latestVersion,
+                updateAvailable: compareSemver(cache.latestVersion, localVersion) > 0,
+                checkedAt: cache.checkedAt,
+                fromCache: true,
+            };
+        }
+        return { localVersion, latestVersion: null, updateAvailable: false, checkedAt: null, fromCache: false };
+    }
+    writeCache(baseDir, {
+        checkedAt: new Date().toISOString(),
+        latestVersion: latest,
+        observedLocalVersion: localVersion,
+    });
+    return {
+        localVersion,
+        latestVersion: latest,
+        updateAvailable: compareSemver(latest, localVersion) > 0,
+        checkedAt: new Date().toISOString(),
+        fromCache: false,
+    };
+}
+/**
+ * Synchronous read of the cached result — used in fast paths like
+ * `clementine status` so we never block on a network call. Returns null
+ * when there's no cache yet.
+ */
+export function readCachedUpdateCheck(baseDir, localVersion) {
+    const cache = readCache(baseDir);
+    if (!cache)
+        return null;
+    return {
+        localVersion,
+        latestVersion: cache.latestVersion,
+        updateAvailable: compareSemver(cache.latestVersion, localVersion) > 0,
+        checkedAt: cache.checkedAt,
+        fromCache: true,
+    };
+}
+//# sourceMappingURL=version-check.js.map

package/dist/index.js

@@ -888,8 +888,14 @@ async function asyncMain() {
         else if (sentinel.reason === 'update' && sentinel.updateDetails) {
             const d = sentinel.updateDetails;
             const parts = [];
-            // Version info
-            if (d.commitHash) {
+            // Version info — prefer semver transition over commit hash for human readability.
+            if (d.previousVersion && d.newVersion && d.previousVersion !== d.newVersion) {
+                parts.push(`Updated v${d.previousVersion} → v${d.newVersion}`);
+            }
+            else if (d.newVersion) {
+                parts.push(`Now on v${d.newVersion}`);
+            }
+            else if (d.commitHash) {
                 parts.push(`Updated to ${d.commitHash}${d.commitDate ? ` (${d.commitDate})` : ''}`);
             }
             else {

package/dist/memory/store.d.ts

@@ -50,6 +50,94 @@ export declare class MemoryStore {
     private get conn();
     /** Return the total number of indexed chunks. */
     getChunkCount(): number;
+    /** Toggle the manual pin flag on a chunk. Pinned chunks get a 2x score boost in recall. */
+    setPinned(chunkId: number, pinned: boolean): boolean;
+    /**
+     * Aggregate stats for the memory store — used by `clementine memory status`.
+     * Single-pass scans so it stays fast even on large chunk tables.
+     */
+    getMemoryStats(): {
+        totalChunks: number;
+        chunksWithEmbeddings: number;
+        pinnedChunks: number;
+        perAgent: Array<{
+            agentSlug: string;
+            count: number;
+        }>;
+        perCategory: Array<{
+            category: string;
+            count: number;
+        }>;
+        avgSalience: number;
+        oldestUpdated: string | null;
+        newestUpdated: string | null;
+    };
+    /**
+     * Find clusters of near-duplicate chunks using embedding cosine similarity.
+     * Returns clusters where at least 2 chunks score above the threshold.
+     *
+     * Caller decides what to do — typical use is `clementine memory dedup` to
+     * preview / merge / mark-superseded. Per-pair O(n²) within agent scope to
+     * keep the search space tractable; cross-agent dupes are surfaced separately
+     * by the auto-promote flow.
+     */
+    findNearDuplicates(opts?: {
+        threshold?: number;
+        minLen?: number;
+        limit?: number;
+    }): Array<{
+        keep: {
+            chunkId: number;
+            sourceFile: string;
+            section: string;
+            content: string;
+            agentSlug: string | null;
+            updatedAt: string | null;
+        };
+        duplicates: Array<{
+            chunkId: number;
+            sourceFile: string;
+            section: string;
+            content: string;
+            agentSlug: string | null;
+            updatedAt: string | null;
+            similarity: number;
+        }>;
+    }>;
+    /** Delete chunks by id. Used by dedup --apply. */
+    deleteChunks(chunkIds: number[]): number;
+    /**
+     * Find chunks whose semantic content recurs across 3+ different agents —
+     * candidates for promotion to global memory. Detection-only; surfacing.
+     * The user (or a future cron) decides whether to actually promote.
+     *
+     * Approach: scan agent-scoped chunks with embeddings, cluster cross-agent
+     * pairs above the similarity threshold, return clusters touching >= minAgents
+     * distinct agents. Limits keep the O(n²) scan tractable on large stores.
+     */
+    findCrossAgentRecurrence(opts?: {
+        threshold?: number;
+        minAgents?: number;
+        minLen?: number;
+        limit?: number;
+    }): Array<{
+        representative: {
+            chunkId: number;
+            sourceFile: string;
+            section: string;
+            content: string;
+            agentSlug: string;
+        };
+        members: Array<{
+            chunkId: number;
+            sourceFile: string;
+            section: string;
+            agentSlug: string;
+            similarity: number;
+            updatedAt: string | null;
+        }>;
+        agents: string[];
+    }>;
     /**
      * Scan the entire vault, hash-compare, and re-index changed files.
      */

package/dist/memory/store.js

@@ -173,6 +173,15 @@ export class MemoryStore {
         catch {
             // Column already exists
         }
+        // Add pinned flag — manual salience reinforcement. When true, recall
+        // applies an extra score boost on top of the access-pattern salience.
+        // Toggled by `clementine memory pin/unpin <chunkId>` (or the dashboard).
+        try {
+            this.conn.exec('ALTER TABLE chunks ADD COLUMN pinned INTEGER DEFAULT 0');
+        }
+        catch {
+            // Column already exists
+        }
         // Indexes for category/topic filtering
         try {
             this.conn.exec('CREATE INDEX idx_chunks_category ON chunks(category)');
@@ -737,6 +746,213 @@ export class MemoryStore {
             return 0;
         }
     }
+    /** Toggle the manual pin flag on a chunk. Pinned chunks get a 2x score boost in recall. */
+    setPinned(chunkId, pinned) {
+        try {
+            const result = this.conn.prepare('UPDATE chunks SET pinned = ? WHERE id = ?')
+                .run(pinned ? 1 : 0, chunkId);
+            return result.changes > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Aggregate stats for the memory store — used by `clementine memory status`.
+     * Single-pass scans so it stays fast even on large chunk tables.
+     */
+    getMemoryStats() {
+        const totalChunks = this.getChunkCount();
+        const chunksWithEmbeddings = this.conn
+            .prepare('SELECT COUNT(*) as cnt FROM chunks WHERE embedding IS NOT NULL')
+            .get()?.cnt ?? 0;
+        const pinnedChunks = this.conn
+            .prepare('SELECT COUNT(*) as cnt FROM chunks WHERE pinned = 1')
+            .get()?.cnt ?? 0;
+        const perAgent = this.conn
+            .prepare(`SELECT COALESCE(agent_slug, 'global') as agentSlug, COUNT(*) as count
+                FROM chunks GROUP BY agent_slug ORDER BY count DESC`)
+            .all();
+        const perCategory = this.conn
+            .prepare(`SELECT COALESCE(category, '(none)') as category, COUNT(*) as count
+                FROM chunks GROUP BY category ORDER BY count DESC`)
+            .all();
+        const avgRow = this.conn
+            .prepare('SELECT AVG(salience) as avg FROM chunks WHERE salience > 0')
+            .get();
+        const dateRow = this.conn
+            .prepare('SELECT MIN(updated_at) as oldest, MAX(updated_at) as newest FROM chunks WHERE updated_at IS NOT NULL')
+            .get();
+        return {
+            totalChunks,
+            chunksWithEmbeddings,
+            pinnedChunks,
+            perAgent,
+            perCategory,
+            avgSalience: avgRow?.avg ?? 0,
+            oldestUpdated: dateRow?.oldest ?? null,
+            newestUpdated: dateRow?.newest ?? null,
+        };
+    }
+    /**
+     * Find clusters of near-duplicate chunks using embedding cosine similarity.
+     * Returns clusters where at least 2 chunks score above the threshold.
+     *
+     * Caller decides what to do — typical use is `clementine memory dedup` to
+     * preview / merge / mark-superseded. Per-pair O(n²) within agent scope to
+     * keep the search space tractable; cross-agent dupes are surfaced separately
+     * by the auto-promote flow.
+     */
+    findNearDuplicates(opts = {}) {
+        const threshold = opts.threshold ?? 0.95;
+        const minLen = opts.minLen ?? 80; // skip very short chunks — too easily collide
+        const limitClusters = opts.limit ?? 50; // cap results so the CLI stays readable
+        if (!embeddingsModule.isReady())
+            return [];
+        const rows = this.conn.prepare(`SELECT id, source_file, section, content, embedding, agent_slug, updated_at
+       FROM chunks
+       WHERE embedding IS NOT NULL AND length(content) >= ?
+       ORDER BY agent_slug, updated_at DESC`).all(minLen);
+        // Group by agent first — only compare within the same scope to bound the
+        // O(n²) blow-up. Cross-agent dedup is the auto-promote flow's job.
+        const buckets = new Map();
+        for (const r of rows) {
+            const key = r.agent_slug ?? '__global__';
+            if (!buckets.has(key))
+                buckets.set(key, []);
+            buckets.get(key).push(r);
+        }
+        const clusters = [];
+        const consumed = new Set();
+        for (const bucket of buckets.values()) {
+            // Decode embeddings once per row.
+            const decoded = bucket.map(r => ({
+                ...r,
+                vec: embeddingsModule.deserializeEmbedding(r.embedding),
+            }));
+            for (let i = 0; i < decoded.length; i++) {
+                if (consumed.has(decoded[i].id))
+                    continue;
+                const head = decoded[i];
+                const dupes = [];
+                for (let j = i + 1; j < decoded.length; j++) {
+                    if (consumed.has(decoded[j].id))
+                        continue;
+                    const sim = embeddingsModule.cosineSimilarity(head.vec, decoded[j].vec);
+                    if (sim >= threshold) {
+                        dupes.push({
+                            chunkId: decoded[j].id,
+                            sourceFile: decoded[j].source_file,
+                            section: decoded[j].section,
+                            content: decoded[j].content,
+                            agentSlug: decoded[j].agent_slug,
+                            updatedAt: decoded[j].updated_at,
+                            similarity: sim,
+                        });
+                        consumed.add(decoded[j].id);
+                    }
+                }
+                if (dupes.length > 0) {
+                    consumed.add(head.id);
+                    clusters.push({
+                        keep: {
+                            chunkId: head.id,
+                            sourceFile: head.source_file,
+                            section: head.section,
+                            content: head.content,
+                            agentSlug: head.agent_slug,
+                            updatedAt: head.updated_at,
+                        },
+                        duplicates: dupes,
+                    });
+                    if (clusters.length >= limitClusters)
+                        return clusters;
+                }
+            }
+        }
+        return clusters;
+    }
+    /** Delete chunks by id. Used by dedup --apply. */
+    deleteChunks(chunkIds) {
+        if (!chunkIds.length)
+            return 0;
+        const placeholders = chunkIds.map(() => '?').join(',');
+        const result = this.conn.prepare(`DELETE FROM chunks WHERE id IN (${placeholders})`).run(...chunkIds);
+        return result.changes;
+    }
+    /**
+     * Find chunks whose semantic content recurs across 3+ different agents —
+     * candidates for promotion to global memory. Detection-only; surfacing.
+     * The user (or a future cron) decides whether to actually promote.
+     *
+     * Approach: scan agent-scoped chunks with embeddings, cluster cross-agent
+     * pairs above the similarity threshold, return clusters touching >= minAgents
+     * distinct agents. Limits keep the O(n²) scan tractable on large stores.
+     */
+    findCrossAgentRecurrence(opts = {}) {
+        const threshold = opts.threshold ?? 0.88; // looser than dedup — paraphrases count
+        const minAgents = opts.minAgents ?? 3;
+        const minLen = opts.minLen ?? 100;
+        const limitClusters = opts.limit ?? 30;
+        if (!embeddingsModule.isReady())
+            return [];
+        // Only consider chunks that ARE agent-scoped (NULL = already global).
+        const rows = this.conn.prepare(`SELECT id, source_file, section, content, embedding, agent_slug, updated_at
+       FROM chunks
+       WHERE embedding IS NOT NULL
+         AND agent_slug IS NOT NULL
+         AND length(content) >= ?
+       ORDER BY updated_at DESC`).all(minLen);
+        if (rows.length < minAgents)
+            return [];
+        const decoded = rows.map(r => ({ ...r, vec: embeddingsModule.deserializeEmbedding(r.embedding) }));
+        const clusters = [];
+        const consumed = new Set();
+        for (let i = 0; i < decoded.length; i++) {
+            if (consumed.has(decoded[i].id))
+                continue;
+            const head = decoded[i];
+            const members = [
+                { chunkId: head.id, sourceFile: head.source_file, section: head.section, agentSlug: head.agent_slug, similarity: 1.0, updatedAt: head.updated_at },
+            ];
+            const agentsTouched = new Set([head.agent_slug]);
+            for (let j = i + 1; j < decoded.length; j++) {
+                if (consumed.has(decoded[j].id))
+                    continue;
+                const sim = embeddingsModule.cosineSimilarity(head.vec, decoded[j].vec);
+                if (sim >= threshold) {
+                    members.push({
+                        chunkId: decoded[j].id,
+                        sourceFile: decoded[j].source_file,
+                        section: decoded[j].section,
+                        agentSlug: decoded[j].agent_slug,
+                        similarity: sim,
+                        updatedAt: decoded[j].updated_at,
+                    });
+                    agentsTouched.add(decoded[j].agent_slug);
+                }
+            }
+            if (agentsTouched.size >= minAgents) {
+                // Mark all in this cluster consumed so we don't re-cluster around them.
+                for (const m of members)
+                    consumed.add(m.chunkId);
+                clusters.push({
+                    representative: {
+                        chunkId: head.id,
+                        sourceFile: head.source_file,
+                        section: head.section,
+                        content: head.content,
+                        agentSlug: head.agent_slug,
+                    },
+                    members,
+                    agents: Array.from(agentsTouched).sort(),
+                });
+                if (clusters.length >= limitClusters)
+                    break;
+            }
+        }
+        return clusters;
+    }
     // ── Full Sync ──────────────────────────────────────────────────────
     /**
      * Scan the entire vault, hash-compare, and re-index changed files.
@@ -878,7 +1094,7 @@ export class MemoryStore {
         try {
             let sql = `SELECT c.id, c.source_file, c.section, c.content, c.chunk_type,
                   c.updated_at, c.salience, c.last_outcome_score, c.agent_slug, c.category, c.topic,
-                  bm25(chunks_fts) as score
+                  c.pinned, bm25(chunks_fts) as score
            FROM chunks_fts f
            JOIN chunks c ON c.id = f.rowid
            WHERE chunks_fts MATCH ?`;
@@ -912,6 +1128,7 @@ export class MemoryStore {
                 agentSlug: row.agent_slug ?? null,
                 category: row.category,
                 topic: row.topic,
+                pinned: row.pinned === 1,
             }));
         }
         catch {
@@ -1030,6 +1247,12 @@ export class MemoryStore {
             if (r.salience > 0) {
                 r.score *= 1.0 + r.salience;
             }
+            // Manual pin: stronger boost than access-pattern salience. Toggled via
+            // `clementine memory pin <chunkId>`. Doubles the relevance score so
+            // pinned chunks consistently rank near the top within their relevance band.
+            if (r.pinned) {
+                r.score *= 2.0;
+            }
             // Outcome-driven adjustment: chunks that recently got cited in
             // responses get a small boost; chunks that were pulled in and
             // ignored get a small penalty. Bounded to ±30% so outcome noise

package/dist/tools/memory-tools.js

@@ -108,6 +108,51 @@ export function registerMemoryTools(server) {
             }
         }
     });
+    // ── 0b. team_scratchpad ────────────────────────────────────────────────
+    //
+    // Cross-agent shared scratchpad. Unlike working_memory (per-agent), this
+    // is a single shared markdown file every agent can read and append to.
+    // Use cases: live coordination ("Sasha is drafting the brief, Ross hold
+    // outbound for 30m"), cross-agent context drops, async hand-offs that
+    // don't warrant a full goal_create or task_add. Append tags every entry
+    // with the author's agent slug + ISO timestamp so the trail stays clear.
+    const TEAM_SCRATCHPAD_FILE = path.join(BASE_DIR, 'team-scratchpad.md');
+    server.tool('team_scratchpad', getToolDescription('team_scratchpad') ?? 'Cross-agent shared scratchpad for live team coordination. All agents read/write the same file. Use for hand-offs, "I am working on X", short-term context drops. For durable facts, use memory_write/MEMORY.md instead.', {
+        action: z.enum(['read', 'append', 'replace', 'clear']).describe('What to do with the team scratchpad'),
+        content: z.string().optional().describe('Text to append or replace with (required for append/replace)'),
+    }, async ({ action, content }) => {
+        const author = ACTIVE_AGENT_SLUG ?? 'clementine';
+        switch (action) {
+            case 'read': {
+                if (!existsSync(TEAM_SCRATCHPAD_FILE)) {
+                    return textResult('Team scratchpad is empty.');
+                }
+                return textResult(readFileSync(TEAM_SCRATCHPAD_FILE, 'utf-8'));
+            }
+            case 'append': {
+                if (!content)
+                    return textResult('Error: content is required for append.');
+                const stamp = new Date().toISOString();
+                const entry = `\n- **[${author}@${stamp}]** ${content}\n`;
+                const existing = existsSync(TEAM_SCRATCHPAD_FILE) ? readFileSync(TEAM_SCRATCHPAD_FILE, 'utf-8') : '# Team Scratchpad\n\nShared across all agents. Append tags entries with author + timestamp.\n';
+                writeFileSync(TEAM_SCRATCHPAD_FILE, existing + entry);
+                return textResult(`Appended to team scratchpad as ${author}.`);
+            }
+            case 'replace': {
+                if (!content)
+                    return textResult('Error: content is required for replace.');
+                const stamp = new Date().toISOString();
+                const header = `# Team Scratchpad\n\n_Replaced by ${author} at ${stamp}._\n\n`;
+                writeFileSync(TEAM_SCRATCHPAD_FILE, header + content + '\n');
+                return textResult(`Team scratchpad replaced by ${author}.`);
+            }
+            case 'clear': {
+                if (existsSync(TEAM_SCRATCHPAD_FILE))
+                    unlinkSync(TEAM_SCRATCHPAD_FILE);
+                return textResult('Team scratchpad cleared.');
+            }
+        }
+    });
     // ── 1. memory_read ─────────────────────────────────────────────────────
     server.tool('memory_read', getToolDescription('memory_read') ?? "Read a note from the Obsidian vault. Shortcuts: 'today', 'yesterday', 'memory', 'tasks', 'heartbeat', 'cron', 'soul'. Or pass a relative path or note name.", {
         name: z.string().describe('Note name, path, or shortcut'),

package/dist/tools/tool-meta.js

@@ -11,10 +11,15 @@
 const TOOL_META = {
     // ── Memory & Vault ────────────────────────────────────────────────
     working_memory: {
-        description: 'Persistent scratchpad that survives across conversations. Use to jot down current project context, TODOs, reminders, or anything you need to remember for next time. Actions: read, append, replace, clear. ALWAYS read before replacing to avoid overwriting useful notes.',
+        description: 'Per-agent persistent scratchpad — only YOU see it. Survives across conversations. Use for current project context, TODOs, reminders, or anything you need to remember for next time. Actions: read, append, replace, clear. ALWAYS read before replacing. For cross-agent coordination, use team_scratchpad instead.',
         exampleUsage: 'Before starting complex work, read working_memory to check for context from prior sessions.',
         returnHint: 'Full working memory contents (markdown text).',
     },
+    team_scratchpad: {
+        description: 'Cross-agent shared scratchpad — every agent on the team reads and writes the same file. Use for live coordination, hand-offs, "I am working on X — back off until Y", short-lived context drops. For durable facts that should outlive coordination noise, use memory_write to MEMORY.md instead. Append tags entries with author slug + timestamp.',
+        exampleUsage: 'Before starting outbound work, read team_scratchpad to see if another agent has already claimed a prospect or paused outreach.',
+        returnHint: 'Full scratchpad contents with per-entry author + ISO timestamp.',
+    },
     memory_search: {
         description: 'Full-text search across all vault notes. Best for finding specific keywords or phrases. For broader semantic matching, use memory_recall instead. Results include file path, section heading, and relevance score.',
         exampleUsage: 'Use when the user asks "what did we discuss about X" or you need to find a specific note.',

package/dist/types.d.ts

@@ -15,6 +15,7 @@ export interface SearchResult {
     agentSlug?: string | null;
     category?: string | null;
     topic?: string | null;
+    pinned?: boolean;
 }
 export type ChunkCategory = 'facts' | 'events' | 'discoveries' | 'preferences' | 'advice';
 export interface Chunk {
@@ -572,6 +573,10 @@ export interface RestartSentinel {
     sessionKey?: string;
     changedFiles?: string[];
     updateDetails?: {
+        /** Semver before the update — read from package.json prior to git pull. */
+        previousVersion?: string;
+        /** Semver after the update — read from package.json after build. */
+        newVersion?: string;
         commitHash?: string;
         commitDate?: string;
         commitsBehind?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.1.20",
+  "version": "1.1.22",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",