clementine-agent 1.1.21 → 1.1.23

package/dist/agent/brain-digest.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Cross-agent brain digest.
+ *
+ * Aggregates raw signals from across the team (memory recurrence, cron
+ * activity, memory growth) and runs a single LLM synthesis pass to
+ * produce a leadable markdown narrative — what the team accomplished,
+ * what they learned in common, where to lead next.
+ *
+ * Intended caller: `clementine brain digest` CLI for v1; cron entry +
+ * heartbeat-side proactive surfacing for v2.
+ */
+import type { AgentManager } from './agent-manager.js';
+import type { MemoryStore } from '../memory/store.js';
+import type { PersonalAssistant } from './assistant.js';
+export interface BrainDigestInputs {
+    windowDays: number;
+    agents: Array<{
+        slug: string;
+        name: string;
+    }>;
+    /** Clusters of similar memory chunks recurring across multiple agents. */
+    crossAgentClusters: Array<{
+        agents: string[];
+        representativeContent: string;
+        representativeSource: string;
+        memberCount: number;
+    }>;
+    /** Per-job summary of runs in the window. */
+    cronRunsByJob: Array<{
+        jobName: string;
+        agentSlug: string | null;
+        runs: number;
+        failures: number;
+    }>;
+    /** Chunk count growth per agent in the window — proxy for "what they worked on". */
+    memoryDeltas: Array<{
+        agentSlug: string;
+        chunksAdded: number;
+    }>;
+}
+/** Aggregate raw signals — pure data, no LLM call. */
+export declare function gatherBrainDigestInputs(opts: {
+    agentManager: AgentManager;
+    memoryStore: MemoryStore;
+    baseDir: string;
+    windowDays: number;
+}): BrainDigestInputs;
+/**
+ * Format the raw inputs as a single text block the LLM can synthesize.
+ * Kept terse — the LLM does the heavy lifting of pattern surfacing.
+ */
+export declare function formatRawMaterial(inputs: BrainDigestInputs): string;
+export declare function runBrainDigest(opts: {
+    assistant: PersonalAssistant;
+    agentManager: AgentManager;
+    memoryStore: MemoryStore;
+    baseDir: string;
+    windowDays?: number;
+    model?: string;
+}): Promise<{
+    markdown: string;
+    inputs: BrainDigestInputs;
+}>;
+//# sourceMappingURL=brain-digest.d.ts.map

package/dist/agent/brain-digest.js

@@ -0,0 +1,196 @@
+/**
+ * Cross-agent brain digest.
+ *
+ * Aggregates raw signals from across the team (memory recurrence, cron
+ * activity, memory growth) and runs a single LLM synthesis pass to
+ * produce a leadable markdown narrative — what the team accomplished,
+ * what they learned in common, where to lead next.
+ *
+ * Intended caller: `clementine brain digest` CLI for v1; cron entry +
+ * heartbeat-side proactive surfacing for v2.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+const logger = pino({ name: 'clementine.brain-digest' });
+/** Aggregate raw signals — pure data, no LLM call. */
+export function gatherBrainDigestInputs(opts) {
+    const sinceMs = Date.now() - opts.windowDays * 86_400_000;
+    const sinceIso = new Date(sinceMs).toISOString();
+    const agents = opts.agentManager.listAll().map(a => ({ slug: a.slug, name: a.name }));
+    // 1. Cross-agent memory recurrence — facts/topics surfaced by 2+ agents.
+    let crossAgentClusters = [];
+    try {
+        const clusters = opts.memoryStore.findCrossAgentRecurrence({
+            threshold: 0.85,
+            minAgents: 2,
+            limit: 20,
+        });
+        crossAgentClusters = clusters.map(c => ({
+            agents: c.agents,
+            representativeContent: c.representative.content.slice(0, 400),
+            representativeSource: `${c.representative.sourceFile}>${c.representative.section}`,
+            memberCount: c.members.length,
+        }));
+    }
+    catch (err) {
+        logger.debug({ err }, 'Cross-agent recurrence scan failed — continuing with empty list');
+    }
+    // 2. Cron run summary — walk cron/runs/*.jsonl, filter to the window.
+    const cronRunsByJob = gatherCronRunsByJob(opts.baseDir, sinceIso);
+    // 3. Memory deltas — chunk growth per agent in the window.
+    const memoryDeltas = gatherMemoryDeltas(opts.memoryStore, sinceIso);
+    return {
+        windowDays: opts.windowDays,
+        agents,
+        crossAgentClusters,
+        cronRunsByJob,
+        memoryDeltas,
+    };
+}
+function gatherCronRunsByJob(baseDir, sinceIso) {
+    const runsDir = path.join(baseDir, 'cron', 'runs');
+    if (!existsSync(runsDir))
+        return [];
+    const sinceMs = Date.parse(sinceIso);
+    const aggregates = new Map();
+    for (const file of readdirSync(runsDir).filter(f => f.endsWith('.jsonl'))) {
+        const jobName = file.replace(/\.jsonl$/, '');
+        const filePath = path.join(runsDir, file);
+        let lines;
+        try {
+            lines = readFileSync(filePath, 'utf-8').split('\n').filter(Boolean);
+        }
+        catch {
+            continue;
+        }
+        let runs = 0;
+        let failures = 0;
+        let agentSlug = null;
+        // jobNames may be agent-scoped: "<agent-slug>:<job>"
+        const parts = jobName.split(':');
+        if (parts.length > 1) {
+            agentSlug = parts[0];
+        }
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                const ts = entry.startedAt ?? entry.finishedAt;
+                if (!ts)
+                    continue;
+                if (Date.parse(ts) < sinceMs)
+                    continue;
+                runs++;
+                if (entry.status === 'error')
+                    failures++;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (runs > 0) {
+            aggregates.set(jobName, { jobName, agentSlug, runs, failures });
+        }
+    }
+    return Array.from(aggregates.values()).sort((a, b) => b.runs - a.runs);
+}
+function gatherMemoryDeltas(memoryStore, sinceIso) {
+    // Reach into the underlying connection — same pattern memory-tools.ts uses.
+    const conn = memoryStore.conn;
+    try {
+        const rows = conn
+            .prepare(`SELECT COALESCE(agent_slug, 'global') as agentSlug, COUNT(*) as chunksAdded
+         FROM chunks
+         WHERE updated_at >= ?
+         GROUP BY agent_slug
+         ORDER BY chunksAdded DESC`)
+            .all(sinceIso);
+        return rows;
+    }
+    catch (err) {
+        logger.debug({ err }, 'Memory delta query failed — continuing with empty list');
+        return [];
+    }
+}
+/**
+ * Format the raw inputs as a single text block the LLM can synthesize.
+ * Kept terse — the LLM does the heavy lifting of pattern surfacing.
+ */
+export function formatRawMaterial(inputs) {
+    const sections = [];
+    sections.push(`## Window\nLast ${inputs.windowDays} days.`);
+    sections.push(`## Team roster\n${inputs.agents.length === 0 ? '(no specialist agents)' : inputs.agents.map(a => `- ${a.name} (${a.slug})`).join('\n')}`);
+    if (inputs.cronRunsByJob.length === 0) {
+        sections.push(`## Cron activity\n(no autonomous runs in window)`);
+    }
+    else {
+        const lines = inputs.cronRunsByJob.slice(0, 20).map(r => {
+            const tag = r.agentSlug ? ` [${r.agentSlug}]` : '';
+            const failTag = r.failures > 0 ? ` — ${r.failures} failure${r.failures === 1 ? '' : 's'}` : '';
+            return `- ${r.jobName}${tag}: ${r.runs} run${r.runs === 1 ? '' : 's'}${failTag}`;
+        });
+        sections.push(`## Cron activity\n${lines.join('\n')}`);
+    }
+    if (inputs.memoryDeltas.length === 0) {
+        sections.push(`## Memory growth\n(no new chunks in window)`);
+    }
+    else {
+        const lines = inputs.memoryDeltas.map(d => `- ${d.agentSlug}: +${d.chunksAdded} chunks`);
+        sections.push(`## Memory growth\n${lines.join('\n')}`);
+    }
+    if (inputs.crossAgentClusters.length === 0) {
+        sections.push(`## Cross-agent recurrence\n(no facts surfaced from 2+ agents)`);
+    }
+    else {
+        const lines = inputs.crossAgentClusters.slice(0, 12).map((c, i) => {
+            const preview = c.representativeContent.replace(/\n/g, ' ').slice(0, 200);
+            return `${i + 1}. agents: ${c.agents.join(', ')} (${c.memberCount} chunks)\n   "${preview}${preview.length >= 200 ? '…' : ''}"`;
+        });
+        sections.push(`## Cross-agent recurrence\n${lines.join('\n')}`);
+    }
+    return sections.join('\n\n');
+}
+const SYNTHESIS_SYSTEM_PROMPT = `You are Clementine, the master assistant. Your team of specialist agents has been working autonomously, and you need to write a **brain digest** — a leadable summary of what happened over the window, what the team learned in common, and where you should lead them next.
+
+Format the digest as markdown:
+
+# Brain Digest — last {N} days
+
+## What happened
+2-3 sentence overview of activity. Be specific about who did what.
+
+## What we learned together
+The cross-agent recurrence section shows facts/topics that surfaced from MULTIPLE agents — these are the team's emerging shared knowledge. List the 3-5 most meaningful patterns. If empty, say "Nothing recurred across agents this window — the team's still working in parallel silos."
+
+## Where to lead
+2-3 concrete priorities or follow-ups based on what you see. What's the team's biggest opportunity? What's at risk? What's a clear next move?
+
+## Per-agent highlights
+One bullet per active agent — what they worked on, status (healthy / quiet / failing). Skip agents with no activity.
+
+**Style rules:**
+- Lead with what matters. Don't list raw data — synthesize.
+- Be honest about sparse data. If the window is quiet, say so. Don't pad.
+- Under 400 words total. Cut anything that doesn't help you lead the team.
+- No greeting, no sign-off — this is a working document.
+`;
+export async function runBrainDigest(opts) {
+    const windowDays = opts.windowDays ?? 7;
+    const inputs = gatherBrainDigestInputs({
+        agentManager: opts.agentManager,
+        memoryStore: opts.memoryStore,
+        baseDir: opts.baseDir,
+        windowDays,
+    });
+    const rawMaterial = formatRawMaterial(inputs);
+    const prompt = `${SYNTHESIS_SYSTEM_PROMPT.replace('{N}', String(windowDays))}\n\n---\n\n# Raw signals\n\n${rawMaterial}`;
+    logger.info({ windowDays, agents: inputs.agents.length, clusters: inputs.crossAgentClusters.length, jobs: inputs.cronRunsByJob.length }, 'Running brain digest synthesis');
+    const markdown = await opts.assistant.runPlanStep('brain-digest', prompt, {
+        tier: 1,
+        maxTurns: 3,
+        model: opts.model ?? 'sonnet',
+        disableTools: true, // synthesis only — no tool calls
+    });
+    return { markdown: markdown.trim(), inputs };
+}
+//# sourceMappingURL=brain-digest.js.map

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) => {
@@ -2090,6 +2130,80 @@ configCmd
         console.error(`  Failed to open editor: ${editor}`);
     }
 });
+// ── Brain commands ──────────────────────────────────────────────────
+const brainCmd = program
+    .command('brain')
+    .description('Cross-agent synthesis — leadable summaries of what your team learned');
+brainCmd
+    .command('digest')
+    .description('Run a brain digest — synthesize the past N days of cross-agent activity into a leadable narrative')
+    .option('-d, --days <n>', 'Window in days', '7')
+    .option('-m, --model <model>', 'Model to use for synthesis (sonnet, haiku, opus)', 'sonnet')
+    .option('--save', 'Also save the digest to vault/00-System/brain-digests/<date>.md')
+    .option('--raw', 'Print the raw signals only — skip the LLM synthesis')
+    .action(async (opts) => {
+    const BOLD = '\x1b[1m';
+    const DIM = '\x1b[0;90m';
+    const GREEN = '\x1b[0;32m';
+    const RED = '\x1b[0;31m';
+    const RESET = '\x1b[0m';
+    const days = Math.max(1, Math.min(60, parseInt(opts.days, 10) || 7));
+    process.env.CLEMENTINE_HOME = BASE_DIR;
+    delete process.env['CLAUDECODE'];
+    try {
+        const { AgentManager } = await import('../agent/agent-manager.js');
+        const { MemoryStore } = await import('../memory/store.js');
+        const { gatherBrainDigestInputs, formatRawMaterial, runBrainDigest } = await import('../agent/brain-digest.js');
+        const VAULT_DIR = path.join(BASE_DIR, 'vault');
+        const DB_PATH = path.join(VAULT_DIR, '.memory.db');
+        const AGENTS_DIR = path.join(BASE_DIR, 'agents');
+        const agentManager = new AgentManager(AGENTS_DIR);
+        const memoryStore = new MemoryStore(DB_PATH, VAULT_DIR);
+        // Raw mode short-circuits the LLM call — useful for inspecting signals.
+        if (opts.raw) {
+            const inputs = gatherBrainDigestInputs({ agentManager, memoryStore, baseDir: BASE_DIR, windowDays: days });
+            console.log();
+            console.log(`  ${BOLD}Brain digest — raw signals (${days} days)${RESET}`);
+            console.log();
+            console.log(formatRawMaterial(inputs));
+            console.log();
+            return;
+        }
+        console.log();
+        console.log(`  ${DIM}Synthesizing brain digest over ${days} days using ${opts.model}…${RESET}`);
+        const { PersonalAssistant } = await import('../agent/assistant.js');
+        const assistant = new PersonalAssistant();
+        // Headless: auto-deny any approval prompts during synthesis.
+        const { setApprovalCallback } = await import('../agent/hooks.js');
+        setApprovalCallback(async () => false);
+        const result = await runBrainDigest({
+            assistant,
+            agentManager,
+            memoryStore,
+            baseDir: BASE_DIR,
+            windowDays: days,
+            model: opts.model,
+        });
+        console.log();
+        console.log(result.markdown);
+        console.log();
+        console.log(`  ${DIM}Sources: ${result.inputs.agents.length} agent(s), ${result.inputs.cronRunsByJob.length} cron job(s) active, ${result.inputs.crossAgentClusters.length} cross-agent cluster(s).${RESET}`);
+        if (opts.save) {
+            const digestsDir = path.join(VAULT_DIR, '00-System', 'brain-digests');
+            mkdirSync(digestsDir, { recursive: true });
+            const stamp = new Date().toISOString().slice(0, 10);
+            const filename = path.join(digestsDir, `${stamp}-${days}d.md`);
+            const fileBody = `---\ntype: brain-digest\ngeneratedAt: ${new Date().toISOString()}\nwindowDays: ${days}\nmodel: ${opts.model}\n---\n\n${result.markdown}\n`;
+            writeFileSync(filename, fileBody);
+            console.log(`  ${GREEN}✓${RESET} Saved to ${DIM}${filename}${RESET}`);
+        }
+        console.log();
+    }
+    catch (err) {
+        console.error(`  ${RED}Error generating brain digest:${RESET} ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
 // ── Agent commands ──────────────────────────────────────────────────
 const agentCmd = program
     .command('agent')
@@ -2583,14 +2697,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
@@ -2608,12 +2821,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) {
@@ -3152,6 +3389,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 = {
@@ -3159,6 +3416,8 @@ async function cmdUpdate(options) {
             restartedAt: new Date().toISOString(),
             reason: 'update',
             updateDetails: {
+                previousVersion,
+                newVersion,
                 commitHash,
                 commitDate,
                 commitsBehind: commitsPulled,
@@ -3249,7 +3508,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/types.d.ts

@@ -573,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.21",
+  "version": "1.1.23",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",