@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/sensory/elevenlabs-library.js

@@ -0,0 +1,303 @@
+/**
+ * ElevenLabs voice library — read-only lookup into the phrases already SYNTHESIZED
+ * and PAID FOR in Lisa's real voice.
+ *
+ * Why this exists: `~/.codebuddy/tts-elevenlabs-permanent/` holds 6 400+ short
+ * conversational replies ("Coucou Patrice. Je suis là.", "Je t'entends, on peut
+ * ralentir.") in the ElevenLabs voice, each paid once and reusable for free.
+ * MySoulmate and the phone assistant already consume it through symlinks — the
+ * robot, which speaks every day, did not. This module closes that gap.
+ *
+ * It sits BEFORE synthesis on the speak hot path, so it follows the same contract
+ * as {@link TtsCache}: **read-only, best-effort, never-throws**. Any failure —
+ * missing index, corrupt JSON, deleted audio — returns `null` and the caller falls
+ * back to its normal synthesis. It never writes, never deletes: those files were
+ * paid for, and the shared library is not ours to prune.
+ *
+ * @module sensory/elevenlabs-library
+ */
+import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { logger } from '../utils/logger.js';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../utils/atomic-write.js';
+/**
+ * Normalize a phrase for matching.
+ *
+ * Two phrases that a listener would hear as identical must match: the library was
+ * built over months by different tools, so the same sentence can differ by a
+ * trailing space, a curly vs straight apostrophe, or capitalization. We do NOT
+ * strip accents or punctuation — "Oui." and "Oui !" are different deliveries, and
+ * playing the wrong one would be worse than synthesizing fresh.
+ */
+export function normalizePhrase(text) {
+    return text
+        .normalize('NFC')
+        .replace(/[‘’ʼ]/g, "'")
+        .replace(/[“”]/g, '"')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+/**
+ * Read-only index over the paid ElevenLabs phrases.
+ *
+ * The index is loaded once, lazily, on first lookup — the speak path must not pay
+ * for a 6 400-entry JSON parse until it actually asks for something.
+ */
+export class ElevenLabsVoiceLibrary {
+    dir;
+    disabled;
+    byPhrase = null;
+    loadFailed = false;
+    constructor(opts = {}) {
+        this.dir =
+            opts.dir ??
+                process.env.CODEBUDDY_TTS_LIBRARY_DIR ??
+                path.join(os.homedir(), '.codebuddy', 'tts-elevenlabs-permanent');
+        this.disabled = opts.disabled ?? process.env.CODEBUDDY_TTS_LIBRARY === 'off';
+    }
+    /** Lazily parse `index.json`. Any failure disables the library for this process. */
+    load() {
+        if (this.disabled || this.loadFailed)
+            return null;
+        if (this.byPhrase)
+            return this.byPhrase;
+        try {
+            const parsed = readJsonAtomicSync(path.join(this.dir, 'index.json'), null, { isValid: (value) => (Array.isArray(value) || Boolean(value && typeof value === 'object')) });
+            if (!parsed)
+                return null;
+            const entries = Array.isArray(parsed) ? parsed : (parsed.entries ?? []);
+            const map = new Map();
+            for (const entry of entries) {
+                if (!entry?.text || !entry.file)
+                    continue;
+                const key = normalizePhrase(entry.text);
+                // First writer wins: the library is append-only, so the earliest synthesis
+                // of a phrase is the one that has been heard and validated.
+                if (map.has(key))
+                    continue;
+                map.set(key, {
+                    file: path.isAbsolute(entry.file) ? entry.file : path.join(this.dir, entry.file),
+                    text: entry.text,
+                    voice: entry.voice ?? '',
+                });
+            }
+            this.byPhrase = map;
+            logger.info(`[voice-library] ${map.size} paid phrase(s) available from ${this.dir}`);
+            return map;
+        }
+        catch (err) {
+            // Never throw on the speak path: a missing or corrupt library simply means
+            // "synthesize normally", which is exactly today's behaviour.
+            this.loadFailed = true;
+            logger.warn(`[voice-library] unavailable, falling back to synthesis: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Find an already-paid recording of `text`, or `null` to synthesize normally.
+     *
+     * The audio file is verified to still exist and be non-empty before being
+     * returned — an index entry whose file was deleted must not silently hand back a
+     * path that the player would fail on.
+     */
+    lookup(text) {
+        if (!text?.trim())
+            return null;
+        const index = this.load();
+        if (!index)
+            return null;
+        const hit = index.get(normalizePhrase(text));
+        if (!hit)
+            return null;
+        try {
+            if (fs.statSync(hit.file).size <= 0)
+                return null;
+        }
+        catch {
+            return null;
+        }
+        return hit;
+    }
+    /** Number of indexed phrases, or 0 when the library is unavailable. */
+    size() {
+        return this.load()?.size ?? 0;
+    }
+    /**
+     * Return a **throwaway WAV copy** of the paid recording for `text`, or `null`.
+     *
+     * Two reasons this is not simply the library path:
+     *
+     * 1. **The caller unlinks what it plays.** `sayNow` deletes the file after
+     *    playback — handing it a library path would erase an audio that was paid
+     *    for. Copy-on-hit is the same contract as the TTS cache.
+     * 2. **The player is `aplay`, which only reads WAV.** The library holds both
+     *    `.wav` and `.mp3`; an mp3 is transcoded with ffmpeg. If ffmpeg is missing
+     *    or fails we return `null` and the caller synthesizes normally — staying
+     *    silent would be worse than not using the library.
+     */
+    copyForPlayback(text, tmpDir = os.tmpdir()) {
+        const hit = this.lookup(text);
+        if (!hit)
+            return null;
+        const dest = path.join(tmpDir, `cb-voicelib-${process.pid}-${Date.now()}-${counter++}.wav`);
+        try {
+            if (path.extname(hit.file).toLowerCase() === '.wav') {
+                fs.copyFileSync(hit.file, dest);
+            }
+            else {
+                const res = spawnSync(process.env.CODEBUDDY_FFMPEG_BIN ?? 'ffmpeg', ['-y', '-v', 'error', '-i', hit.file, dest], { stdio: 'ignore', timeout: 15_000 });
+                if (res.status !== 0)
+                    throw new Error(`ffmpeg exit ${res.status}`);
+            }
+            if (fs.statSync(dest).size <= 0)
+                throw new Error('empty copy');
+            return dest;
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(dest);
+            }
+            catch {
+                /* nothing to clean */
+            }
+            logger.warn(`[voice-library] could not prepare "${hit.text.slice(0, 40)}": ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+}
+let counter = 0;
+let shared = null;
+/** Process-wide library — the index is parsed once, then reused. */
+export function getVoiceLibrary() {
+    shared ??= new ElevenLabsVoiceLibrary();
+    return shared;
+}
+/** Reset the shared instance (tests only). */
+export function resetVoiceLibrary() {
+    shared = null;
+}
+/** A voice descriptor that identifies a paid ElevenLabs rendition. */
+export function isPaidElevenLabsVoice(voice) {
+    return Boolean(voice?.trim().toLowerCase().startsWith('elevenlabs:'));
+}
+/** How long a lock file may sit before it is treated as abandoned by a dead writer. */
+const LOCK_STALE_MS = 10_000;
+/**
+ * Take an exclusive lock on the shared index, run `fn`, release.
+ *
+ * The index is read by three products (MySoulmate, the phone assistant, the robot)
+ * and one of them updates it with a naive read-modify-write. A lock cannot fix that
+ * writer from here, but it keeps OUR window closed and lets concurrent robot turns
+ * queue instead of racing. Returns false when the lock could not be taken — the
+ * caller then simply skips publishing, which costs a future re-synthesis and
+ * nothing else.
+ */
+function withIndexLock(lockPath, fn) {
+    let fd;
+    try {
+        try {
+            fd = fs.openSync(lockPath, 'wx');
+        }
+        catch {
+            // A lock left behind by a killed process must not block the library forever.
+            const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+            if (age < LOCK_STALE_MS)
+                return false;
+            fs.unlinkSync(lockPath);
+            fd = fs.openSync(lockPath, 'wx');
+        }
+        fn();
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* already closed */
+            }
+        }
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch {
+            /* someone else cleaned it */
+        }
+    }
+}
+/**
+ * Publish a freshly PAID rendition into the shared library, so the other products
+ * get it for free.
+ *
+ * Doctrine (Patrice, 2026-08-16): a phrase in Lisa's ElevenLabs voice is a
+ * cross-product asset, paid once and reused everywhere. Until now Code Buddy only
+ * READ this library: everything the robot paid for landed in its private TTS cache
+ * — which also evicts — and MySoulmate and the phone assistant never saw it.
+ *
+ * Append-only and conservative by design:
+ * - an existing phrase is never overwritten (the reader takes the first entry, and
+ *   those files were paid for);
+ * - the index is written to a temp file and renamed, so a concurrent reader never
+ *   sees a half-written 6 000-entry JSON;
+ * - the text is stored whitespace-collapsed but CASE-PRESERVED, because MySoulmate's
+ *   own lookup is case-sensitive — lowercasing here would hide the entry from it;
+ * - every failure is swallowed: publishing is a bonus, never a reason to break speech.
+ *
+ * @returns the stored file path, or null when nothing was published.
+ */
+export function publishToVoiceLibrary(text, voice, srcFile, dir = process.env.CODEBUDDY_TTS_LIBRARY_DIR ??
+    path.join(os.homedir(), '.codebuddy', 'tts-elevenlabs-permanent')) {
+    if (process.env.CODEBUDDY_TTS_LIBRARY_PUBLISH === 'off')
+        return null;
+    if (!isPaidElevenLabsVoice(voice))
+        return null;
+    const canonical = text?.trim().replace(/\s+/g, ' ');
+    if (!canonical)
+        return null;
+    const indexPath = path.join(dir, 'index.json');
+    let published = null;
+    const ok = withIndexLock(path.join(dir, 'index.lock'), () => {
+        fs.mkdirSync(dir, { recursive: true });
+        const parsed = readJsonAtomicSync(indexPath, null, { isValid: (value) => (Boolean(value && typeof value === 'object' && !Array.isArray(value))) });
+        if (!parsed && fs.existsSync(indexPath))
+            throw new Error('index unreadable — refusing to overwrite');
+        const entries = Array.isArray(parsed?.entries) ? parsed.entries : [];
+        const wanted = normalizePhrase(canonical);
+        if (entries.some((e) => e?.text && normalizePhrase(e.text) === wanted))
+            return;
+        // Hash the full phrase, not a prefix: the library's own naming truncates to the
+        // first 16 characters of text, which would collide across similar openers.
+        const key = createHash('sha256').update(`${wanted}\u0000${voice}`).digest('hex').slice(0, 32);
+        const file = `${key}${path.extname(srcFile).toLowerCase() || '.wav'}`;
+        const dest = path.join(dir, file);
+        if (!fs.existsSync(dest)) {
+            const tmp = `${dest}.${process.pid}.tmp`;
+            fs.copyFileSync(srcFile, tmp);
+            if (fs.statSync(tmp).size <= 0) {
+                fs.unlinkSync(tmp);
+                throw new Error('refusing to publish an empty rendition');
+            }
+            fs.renameSync(tmp, dest);
+        }
+        entries.push({ key, text: canonical, voice, file });
+        const next = { ...parsed, voice: parsed?.voice ?? voice, count: entries.length, entries };
+        writeJsonAtomicSync(indexPath, next, { mode: 0o600 });
+        published = dest;
+    });
+    if (!ok)
+        return null;
+    if (published) {
+        logger.info(`[voice-library] published a paid phrase for every product to reuse`);
+        shared = null; // the in-process index must see it on the next lookup
+    }
+    return published;
+}
+//# sourceMappingURL=elevenlabs-library.js.map

package/dist/sensory/episodic-journal.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Episodic journal — heartbeat-paced consolidation of the DIALOGUE (not sensor stats).
+ *
+ * `dreaming.ts` consolidates the short-term sensory buffer into counts-by-kind (how much motion /
+ * speech / heartbeat happened). This is its companion for the CONVERSATION: it summarizes what was
+ * actually HEARD into a short episodic line ("récemment on a parlé de …") and promotes it to a stable
+ * memory key, so the arrival opener and event follow-ups can reference "what we talked about" instead
+ * of only the last raw utterance. Phase 6 of the interactions refonte.
+ *
+ * Pure core (`summarizeEpisode`) + a best-effort, never-throws pass; everything injectable for tests.
+ *
+ * @module sensory/episodic-journal
+ */
+import type { ConversationTurn } from '../conversation/types.js';
+export interface EpisodeSummary {
+    at: number;
+    /** Total non-empty utterances considered. */
+    count: number;
+    /** The distinct recent utterances (a proxy for topics without an LLM). */
+    topics: string[];
+    /** The injectable/spoken summary line, '' when there was nothing worth summarizing. */
+    line: string;
+    /** Structured continuity cues extracted from a complete user/Lisa thread. */
+    corrections?: string[];
+    commitments?: string[];
+    openLoops?: string[];
+    lastUserPoint?: string;
+    lastAssistantPosition?: string;
+    fingerprint?: string;
+}
+/** Emotion, a named plan, or an explicit memory — not just the last STT window. */
+export declare function isSalientHeard(text: string): boolean;
+/**
+ * Pure consolidation: turn a list of heard utterances into a compact episode. Drops consecutive
+ * duplicates (STT re-hears). Keeps recent utterances AND earlier salient ones (a train tomorrow
+ * must not vanish because six small-talk turns followed). No LLM — the caller may refine.
+ */
+export declare function summarizeEpisode(heard: string[], now: number): EpisodeSummary;
+/** True when the candidate line is mostly made of words already present in the heard source. */
+export declare function episodeLineIsGrounded(line: string, source: string[]): boolean;
+/** Build a compact "where we were" memory from both sides of the conversation. */
+export declare function summarizeConversationEpisode(sourceTurns: ConversationTurn[], now: number): EpisodeSummary;
+export interface EpisodeDeps {
+    now?: number;
+    cwd?: string;
+    /** How many recent hearing percepts to consolidate. Default 20. */
+    limit?: number;
+    /** Read recent heard utterances. Default: the companion hearing percepts. */
+    readHeard?: (limit: number, cwd?: string) => Promise<string[]>;
+    /** Prefer a complete cross-channel user/Lisa thread when available. */
+    readConversation?: (limit: number) => Promise<ConversationTurn[]>;
+    /** Optional LLM refinement of the episode line → null keeps the template. */
+    refine?: (heard: string[]) => Promise<string | null>;
+    /** Promote the episode to persistent memory. Default: `promoteEpisode`. */
+    promote?: (ep: EpisodeSummary) => Promise<void>;
+    /** Override the deduplication cursor in tests. */
+    statePath?: string;
+}
+/**
+ * One episodic-consolidation pass: read recent dialogue, summarize it, append to the episode journal,
+ * and promote to persistent memory. Returns the episode, or null when there was nothing to consolidate.
+ * Never throws.
+ */
+export declare function runEpisodeConsolidation(deps?: EpisodeDeps): Promise<EpisodeSummary | null>;
+/**
+ * Promote the episode into persistent memory under a STABLE key (`episode:recent`) so repeated
+ * consolidations UPDATE rather than accumulate. Never throws.
+ */
+export declare function promoteEpisode(ep: EpisodeSummary): Promise<void>;

package/dist/sensory/episodic-journal.js

@@ -0,0 +1,240 @@
+/**
+ * Episodic journal — heartbeat-paced consolidation of the DIALOGUE (not sensor stats).
+ *
+ * `dreaming.ts` consolidates the short-term sensory buffer into counts-by-kind (how much motion /
+ * speech / heartbeat happened). This is its companion for the CONVERSATION: it summarizes what was
+ * actually HEARD into a short episodic line ("récemment on a parlé de …") and promotes it to a stable
+ * memory key, so the arrival opener and event follow-ups can reference "what we talked about" instead
+ * of only the last raw utterance. Phase 6 of the interactions refonte.
+ *
+ * Pure core (`summarizeEpisode`) + a best-effort, never-throws pass; everything injectable for tests.
+ *
+ * @module sensory/episodic-journal
+ */
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, rename, stat } from 'fs/promises';
+import path from 'path';
+import { readRecentDialogueHearing } from '../companion/dialogue-percepts.js';
+import { detectEmotion } from '../companion/reply-augment.js';
+import { analyzeConversationTurn, extractSalientTerms, normalizeConversationText, } from '../conversation/dialogue-act.js';
+import { logger } from '../utils/logger.js';
+import { readJsonAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
+const PERSONAL_FACT = /\b(train|souvenir|demain|rendez[- ]vous|anniversaire|je me souviens|j ai un)\b/;
+/** Emotion, a named plan, or an explicit memory — not just the last STT window. */
+export function isSalientHeard(text) {
+    if (!text.trim())
+        return false;
+    if (detectEmotion(text).emotion !== 'neutral')
+        return true;
+    return PERSONAL_FACT.test(normalizeConversationText(text));
+}
+/**
+ * Pure consolidation: turn a list of heard utterances into a compact episode. Drops consecutive
+ * duplicates (STT re-hears). Keeps recent utterances AND earlier salient ones (a train tomorrow
+ * must not vanish because six small-talk turns followed). No LLM — the caller may refine.
+ */
+export function summarizeEpisode(heard, now) {
+    const clean = heard.map((s) => (s ?? '').trim()).filter(Boolean);
+    const distinct = [];
+    for (const t of clean) {
+        if (t !== distinct[distinct.length - 1])
+            distinct.push(t);
+    }
+    const salient = distinct.filter(isSalientHeard).slice(-6);
+    if (salient.length === 0) {
+        const topics = distinct.slice(-6);
+        const line = topics.length ? `Récemment, on a parlé de : ${topics.join(' ; ')}.` : '';
+        return { at: now, count: clean.length, topics, line };
+    }
+    const keep = new Set([...salient, ...distinct.slice(-4)]);
+    const topics = distinct.filter((t) => keep.has(t));
+    const line = topics.length ? `Récemment, on a parlé de : ${topics.join(' ; ')}.` : '';
+    return { at: now, count: clean.length, topics, line };
+}
+/** True when the candidate line is mostly made of words already present in the heard source. */
+export function episodeLineIsGrounded(line, source) {
+    const blob = source.map((s) => normalizeConversationText(s)).join(' ');
+    const terms = extractSalientTerms(line, 12);
+    if (terms.length === 0)
+        return false;
+    const hits = terms.filter((term) => blob.includes(term));
+    return hits.length * 2 >= terms.length;
+}
+function safeExcerpt(text, limit = 240) {
+    return text
+        .replace(/[<>]/g, (character) => (character === '<' ? '‹' : '›'))
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, limit);
+}
+function topFocusTerms(turns, limit = 6) {
+    const scores = new Map();
+    turns.forEach((turn, index) => {
+        const recency = 1 + index / Math.max(1, turns.length);
+        for (const term of extractSalientTerms(turn.content, 8)) {
+            scores.set(term, (scores.get(term) ?? 0) + recency);
+        }
+    });
+    return [...scores.entries()]
+        .sort((left, right) => right[1] - left[1])
+        .slice(0, limit)
+        .map(([term]) => term);
+}
+function lastMatching(turns, predicate, limit) {
+    return turns
+        .map((turn, index) => ({ turn, index }))
+        .filter(({ turn, index }) => predicate(turn, index))
+        .slice(-limit)
+        .map(({ turn }) => safeExcerpt(turn.content));
+}
+/** Build a compact "where we were" memory from both sides of the conversation. */
+export function summarizeConversationEpisode(sourceTurns, now) {
+    const turns = sourceTurns
+        .map((turn) => ({ role: turn.role, content: turn.content.trim() }))
+        .filter((turn) => turn.content)
+        .slice(-40);
+    if (turns.length === 0)
+        return { at: now, count: 0, topics: [], line: '' };
+    const topics = topFocusTerms(turns);
+    const corrections = lastMatching(turns, (turn, index) => turn.role === 'user' && analyzeConversationTurn(turn.content, turns.slice(0, index)).act === 'correction', 2);
+    const commitments = lastMatching(turns, (turn) => /\b(je vais|nous allons|on va|je m engage|prochaine etape|prochaine étape|il faudra|reste a|reste à)\b/i.test(turn.content), 3);
+    const openLoops = lastMatching(turns, (turn, index) => {
+        if (/\b(plus tard|on en reparle|a reprendre|à reprendre|a suivre|à suivre)\b/i.test(turn.content)) {
+            return true;
+        }
+        return index === turns.length - 1 && /\?\s*$/.test(turn.content);
+    }, 3);
+    const lastUserPoint = [...turns].reverse().find((turn) => turn.role === 'user')?.content;
+    const lastAssistantPosition = [...turns]
+        .reverse()
+        .find((turn) => turn.role === 'assistant')?.content;
+    const parts = [
+        topics.length
+            ? `Récemment, notre conversation portait surtout sur : ${topics.join(', ')}.`
+            : '',
+        lastUserPoint ? `Dernier point de l'utilisateur : ${safeExcerpt(lastUserPoint)}.` : '',
+        lastAssistantPosition
+            ? `Dernière position de Lisa : ${safeExcerpt(lastAssistantPosition)}.`
+            : '',
+        corrections.length ? `Correction à respecter : ${corrections.at(-1)}.` : '',
+        commitments.length ? `Engagement ou prochaine étape : ${commitments.at(-1)}.` : '',
+        openLoops.length ? `Point encore ouvert : ${openLoops.at(-1)}.` : '',
+    ].filter(Boolean);
+    const line = parts.join(' ');
+    return {
+        at: now,
+        count: turns.length,
+        topics,
+        line,
+        corrections,
+        commitments,
+        openLoops,
+        ...(lastUserPoint ? { lastUserPoint: safeExcerpt(lastUserPoint) } : {}),
+        ...(lastAssistantPosition
+            ? { lastAssistantPosition: safeExcerpt(lastAssistantPosition) }
+            : {}),
+    };
+}
+async function defaultReadHeard(limit, cwd) {
+    return readRecentDialogueHearing(limit, cwd);
+}
+/**
+ * One episodic-consolidation pass: read recent dialogue, summarize it, append to the episode journal,
+ * and promote to persistent memory. Returns the episode, or null when there was nothing to consolidate.
+ * Never throws.
+ */
+export async function runEpisodeConsolidation(deps = {}) {
+    const limit = deps.limit ?? 20;
+    const now = deps.now ?? Date.now();
+    let conversation;
+    let heard;
+    try {
+        conversation = deps.readConversation ? await deps.readConversation(limit) : [];
+        heard =
+            conversation.length > 0
+                ? conversation.filter((turn) => turn.role === 'user').map((turn) => turn.content)
+                : await (deps.readHeard ?? defaultReadHeard)(limit, deps.cwd);
+    }
+    catch (err) {
+        logger.warn(`[episode] could not read recent dialogue: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    if (conversation.length === 0 && heard.length === 0)
+        return null;
+    const ep = conversation.length > 0
+        ? summarizeConversationEpisode(conversation, now)
+        : summarizeEpisode(heard, now);
+    if (!ep.line)
+        return null;
+    if (deps.refine) {
+        try {
+            const refined = await deps.refine(heard);
+            const candidate = refined?.trim() ?? '';
+            if (candidate && episodeLineIsGrounded(candidate, heard)) {
+                ep.line = candidate;
+            }
+            else if (candidate) {
+                logger.warn('[episode] refinement dropped; invented content is not in the heard source');
+            }
+        }
+        catch (err) {
+            logger.warn(`[episode] refinement failed; keeping template: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    ep.fingerprint = createHash('sha256').update(ep.line).digest('hex');
+    const dir = path.join(deps.cwd ?? process.cwd(), '.codebuddy', 'companion');
+    const statePath = deps.statePath ?? path.join(dir, 'episode-state.json');
+    const previous = await readJsonAtomic(statePath, null, {
+        mode: 0o600,
+        isValid: (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value)),
+    });
+    if (previous?.fingerprint === ep.fingerprint)
+        return null;
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const file = path.join(dir, 'episodes.jsonl');
+        try {
+            const info = await stat(file);
+            if (info.size > 512 * 1024)
+                await rename(file, `${file}.1`); // rotate, one backup (disk-guard lesson)
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            /* no file yet */
+        }
+        await appendFile(file, `${JSON.stringify(ep)}\n`, { encoding: 'utf8', mode: 0o600 });
+        await writeJsonAtomic(statePath, { fingerprint: ep.fingerprint, at: ep.at }, { mode: 0o600 });
+    }
+    catch (err) {
+        logger.warn(`[episode] could not persist episode: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        await (deps.promote ?? promoteEpisode)(ep);
+    }
+    catch (err) {
+        logger.warn(`[episode] could not promote episode: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    logger.info(`[episode] consolidated ${ep.count} utterance(s) → ${ep.topics.length} topic(s)`);
+    return ep;
+}
+/**
+ * Promote the episode into persistent memory under a STABLE key (`episode:recent`) so repeated
+ * consolidations UPDATE rather than accumulate. Never throws.
+ */
+export async function promoteEpisode(ep) {
+    try {
+        const { getMemoryManager } = await import('../memory/persistent-memory.js');
+        const manager = getMemoryManager();
+        await manager.initialize();
+        await manager.remember('episode:recent', ep.line, {
+            scope: 'project',
+            category: 'context',
+            tags: ['episode', 'conversation'],
+        });
+    }
+    catch (err) {
+        logger.warn(`[episode] could not promote episode to memory: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=episodic-journal.js.map

package/dist/sensory/error-watch-reaction.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Error-watch reaction — notices an error already visible in an existing screen
+ * percept and offers one quiet, local-voice-only invitation to help.
+ *
+ * Detection is text-first ($0), with an explicitly enabled local-VLM fallback
+ * for an existing keyframe. The reaction never captures or stores an image and
+ * never starts an agent turn. It is double opt-in, bounded, deduplicated and
+ * never-throws.
+ *
+ * @module sensory/error-watch-reaction
+ */
+import type { Conductor } from '../companion/orchestrator.js';
+export interface ErrorWatchVisionAnalysis {
+    success: boolean;
+    description?: string;
+}
+export interface ErrorWatchVisionAnalyzer {
+    analyze(prompt: string, imagePath?: string): Promise<ErrorWatchVisionAnalysis>;
+}
+export interface ErrorWatchReactionOptions {
+    /** Injectable local vision analyzer. Defaults to the configured local VLM. */
+    analyzer?: ErrorWatchVisionAnalyzer;
+    /** Injectable local voice output. No remote channel is ever used. */
+    say?: (utterance: string) => Promise<void>;
+    /** Shared one-voice arbiter. */
+    conductor?: Pick<Conductor, 'claim'>;
+    debounceMs?: number;
+    maxPerHour?: number;
+    now?: () => number;
+    env?: NodeJS.ProcessEnv;
+}
+interface ErrorIndicator {
+    evidence: string;
+    summary: string;
+}
+/** Extract only fields that explicitly represent OCR/accessibility/terminal text. */
+export declare function extractScreenText(payload: unknown): string;
+export declare function findTextErrorIndicator(text: string): ErrorIndicator | null;
+export declare function shouldWireErrorWatchReaction(env?: NodeJS.ProcessEnv): boolean;
+export declare function wireErrorWatchReaction(options?: ErrorWatchReactionOptions): () => void;
+export {};