@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/commands/cli/native-engine-commands.js

@@ -19,6 +19,12 @@ function parsePositiveIntegerCliOption(value, flagName) {
     }
     return n;
 }
+function splitCsv(value) {
+    if (!value)
+        return undefined;
+    const parts = value.split(',').map((s) => s.trim()).filter(Boolean);
+    return parts.length > 0 ? parts : undefined;
+}
 export function registerHeartbeatCommands(program) {
     const heartbeat = program
         .command('heartbeat')
@@ -166,6 +172,8 @@ export function registerHubCommands(program) {
         }
         else {
             console.log(`Skill not found: ${name}`);
+            process.exit(1);
+            return;
         }
     });
     hub
@@ -193,11 +201,20 @@ export function registerHubCommands(program) {
         const { getSkillsHub } = await import('../../skills/hub.js');
         const skillsHub = getSkillsHub();
         const installed = skillsHub.list();
+        const { getBundledSkillsPath } = await import('../../skills/index.js');
+        const { countBundledSkillEntries } = await import('../skills-cli/index.js');
+        const bundledCount = countBundledSkillEntries(getBundledSkillsPath());
         if (opts.json) {
-            console.log(JSON.stringify({ count: installed.length, skills: installed }, null, 2));
+            console.log(JSON.stringify({ count: installed.length, skills: installed, bundledCount }, null, 2));
             return;
         }
         if (installed.length === 0) {
+            if (bundledCount > 0) {
+                console.log('No hub-installed skills.');
+                console.log(`${bundledCount} bundled skill(s) shipped with the package are still available to the agent.`);
+                console.log('Install more with: buddy hub search');
+                return;
+            }
             console.log('No skills installed from the hub.');
             return;
         }
@@ -742,6 +759,7 @@ export function registerGatewayPairingCommands(program) {
 export function registerFleetAutonomyCommands(program) {
     const fleet = program
         .command('autonomy')
+        .alias('colab')
         .description('Autonomous fleet loop — claim and run colab tasks on local-first models');
     fleet
         .command('run')
@@ -751,23 +769,61 @@ export function registerFleetAutonomyCommands(program) {
         .option('--max-ticks <n>', 'stop after N ticks')
         .option('--dir <path>', 'colab dir (default: CODEBUDDY_FLEET_COLAB_DIR or <cwd>/.codebuddy)')
         .option('--output-dir <path>', 'artifact output dir')
+        .option('--executor <mode>', 'artifact (default, scoped .md) or agent (real repo edits)')
+        .option('--workspace <dir>', 'bounded dir the agent edits (required for --executor agent)')
+        .option('--verify', 'run each task verifyCommand after the agent (operator-trusted queue)')
         .option('--json', 'output JSON summary')
         .action(async (opts) => {
         const { createDefaultAutonomousLoop, FleetAutonomousDaemon, watchFleetTasks } = await import('../../daemon/autonomous-daemon.js');
+        const { AutonomyBriefingJournal } = await import('../../daemon/autonomy-briefing.js');
+        const { openAutonomyRun, recordAutonomyTick, closeAutonomyRun } = await import('../../daemon/autonomy-run-journal.js');
+        const { RunStore } = await import('../../observability/run-store.js');
         const path = await import('path');
+        const executorModeRaw = (opts.executor ?? process.env['CODEBUDDY_AUTONOMY_EXECUTOR'] ?? 'artifact').toLowerCase();
+        if (executorModeRaw !== 'artifact' && executorModeRaw !== 'agent') {
+            console.error(`Invalid --executor "${opts.executor}" (use artifact|agent).`);
+            process.exit(1);
+            return;
+        }
+        const executorMode = executorModeRaw;
+        const workspaceRoot = opts.workspace
+            ? path.resolve(opts.workspace)
+            : process.env['CODEBUDDY_AUTONOMY_WORKSPACE_ROOT'];
+        if (executorMode === 'agent' && !workspaceRoot?.trim()) {
+            console.error('--executor agent requires --workspace <dir> (or CODEBUDDY_AUTONOMY_WORKSPACE_ROOT).');
+            process.exit(1);
+            return;
+        }
+        const allowVerify = Boolean(opts.verify) || process.env['CODEBUDDY_AUTONOMY_VERIFY_COMMANDS'] === '1';
         const loop = await createDefaultAutonomousLoop({
             ...(opts.dir ? { dir: opts.dir } : {}),
             ...(opts.outputDir ? { outputDir: opts.outputDir } : {}),
+            executorMode,
+            ...(workspaceRoot ? { workspaceRoot } : {}),
+            ...(allowVerify ? { allowVerifyCommand: true } : {}),
         });
         // Same dir resolution the store uses, so the watcher observes the live queue.
         const colabDir = opts.dir || process.env['CODEBUDDY_FLEET_COLAB_DIR'] || path.join(process.cwd(), '.codebuddy');
+        const briefing = new AutonomyBriefingJournal({ dir: colabDir });
+        let briefingErrorReported = false;
+        const runStore = RunStore.getInstance();
+        const autonomyRunId = openAutonomyRun(runStore, 'autonomy run');
         const daemon = new FleetAutonomousDaemon({
             loop,
             intervalMs: parseInt(opts.interval, 10) || 30000,
             onTick: (result, n) => {
+                recordAutonomyTick(runStore, autonomyRunId, result, n);
+                const recorded = briefing.recordTick(result, n);
+                if (!recorded.ok && !briefingErrorReported && !opts.json) {
+                    briefingErrorReported = true;
+                    console.warn(`Morning briefing degraded: ${recorded.error ?? 'unknown write error'}`);
+                }
                 if (!opts.json) {
                     const tier = result.model ? ` [${result.model.tier}${result.model.paid ? ' $' : ''}]` : '';
-                    console.log(`tick ${n}: ${result.outcome}${result.taskTitle ? ` — ${result.taskTitle}` : ''}${tier}`);
+                    const detail = result.detail && result.detail !== 'self-improve on cooldown'
+                        ? ` (${result.detail})`
+                        : '';
+                    console.log(`tick ${n}: ${result.outcome}${result.taskTitle ? ` — ${result.taskTitle}` : ''}${tier}${detail}`);
                 }
             },
             // Event-driven only for continuous runs: a write to the queue wakes the
@@ -783,13 +839,49 @@ export function registerFleetAutonomyCommands(program) {
             ? (opts.maxTicks ? parseInt(opts.maxTicks, 10) : undefined)
             : 1;
         const summary = await daemon.run(maxTicks !== undefined ? { maxTicks } : {});
+        closeAutonomyRun(runStore, autonomyRunId, summary);
         if (opts.json) {
-            console.log(JSON.stringify(summary, null, 2));
+            console.log(JSON.stringify({ ...summary, runId: autonomyRunId }, null, 2));
         }
         else {
             console.log(`\nDone: ${summary.ticks} tick(s), ${JSON.stringify(summary.outcomes)} (${summary.stoppedReason}).`);
+            console.log(`Run journal: ${autonomyRunId}  (buddy run show ${autonomyRunId})`);
         }
     });
+    fleet
+        .command('briefing')
+        .description('Build/show the evidence-first morning brief from the autonomy ledger')
+        .option('--date <yyyy-mm-dd>', 'morning date (default: current reporting window)')
+        .option('--dir <path>', 'colab dir')
+        .option('--json', 'output the machine-readable briefing')
+        .action(async (opts) => {
+        const path = await import('path');
+        const { AutonomyBriefingJournal, renderAutonomyMorningBrief } = await import('../../daemon/autonomy-briefing.js');
+        if (opts.date && !/^\d{4}-\d{2}-\d{2}$/.test(opts.date)) {
+            console.error('--date must use YYYY-MM-DD');
+            process.exit(1);
+            return;
+        }
+        const colabDir = opts.dir
+            || process.env['CODEBUDDY_FLEET_COLAB_DIR']
+            || path.join(process.cwd(), '.codebuddy');
+        const result = new AutonomyBriefingJournal({ dir: colabDir }).refresh(opts.date);
+        if (!result.ok || !result.brief) {
+            const message = `Unable to build autonomy briefing: ${result.error ?? 'unknown error'}`;
+            if (opts.json)
+                console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+            else
+                console.error(message);
+            process.exit(1);
+            return;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(result.brief, null, 2));
+            return;
+        }
+        console.log(renderAutonomyMorningBrief(result.brief));
+        console.log(`Saved: ${result.markdownPath}`);
+    });
     fleet
         .command('bench')
         .description('Benchmark live Tailnet Ollama peers and rank the network model tier')
@@ -803,32 +895,28 @@ export function registerFleetAutonomyCommands(program) {
         .action(async (opts) => {
         const { TailscaleManager } = await import('../../integrations/tailscale.js');
         const { BENCHMARK_PROMPT_SETS, benchmarkCandidates, writeBenchmarkIndex, defaultBenchmarkIndexPath, } = await import('../../agent/model-benchmark.js');
+        const { resolveModelTierConfig } = await import('../../agent/model-tier.js');
+        const { collectAutonomyBenchCandidates } = await import('../../daemon/autonomy-bench-candidates.js');
         const peers = await TailscaleManager.getInstance().discoverOllamaPeers();
-        const filteredPeers = opts.peer
-            ? peers.filter((peer) => peer.hostname.toLowerCase().includes(opts.peer.toLowerCase())
-                || peer.ip.includes(opts.peer.trim()))
-            : peers;
+        const local = resolveModelTierConfig();
         const modelFilters = opts.models
             ? opts.models.split(',').map((part) => part.trim()).filter(Boolean)
             : [];
-        const candidates = filteredPeers.flatMap((peer) => peer.models
-            .filter((model) => modelFilters.length === 0
-            ? true
-            : modelFilters.some((filter) => model.toLowerCase().includes(filter.toLowerCase())))
-            .map((model) => ({
-            model,
-            baseUrl: peer.baseURL,
-            label: peer.hostname,
-        })));
+        const { candidates, error } = collectAutonomyBenchCandidates({
+            local: { model: local.localModel, baseUrl: local.localBaseUrl, label: 'local' },
+            tailnet: peers,
+            ...(opts.peer ? { peerFilter: opts.peer } : {}),
+            ...(modelFilters.length ? { modelFilters } : {}),
+        });
         if (candidates.length === 0) {
-            const message = opts.peer
-                ? `No Tailnet Ollama peers matched "${opts.peer}".`
-                : 'No Tailnet Ollama peers were discovered.';
+            const message = error ?? 'No Ollama candidates to benchmark.';
             if (opts.json) {
                 console.log(JSON.stringify({ ok: false, error: message }, null, 2));
-                return;
             }
-            console.log(message);
+            else {
+                console.log(message);
+            }
+            process.exit(1);
             return;
         }
         const suite = BENCHMARK_PROMPT_SETS[opts.promptSet] ? opts.promptSet : 'coding';
@@ -854,7 +942,7 @@ export function registerFleetAutonomyCommands(program) {
             }, null, 2));
             return;
         }
-        console.log(`\nTailnet Ollama benchmark (${suite})`);
+        console.log(`\nOllama benchmark (${suite})`);
         if (indexPath)
             console.log(`  Cache: ${indexPath}`);
         console.log(`  Candidates: ${ranked.length}`);
@@ -907,6 +995,9 @@ export function registerFleetAutonomyCommands(program) {
         .option('--priority <p>', 'critical | high | medium | low', 'medium')
         .option('--depends-on <ids>', 'comma-separated task ids this task depends on')
         .option('--description <text>', 'task description')
+        .option('--verify-command <cmd>', 'acceptance gate run after the agent (e.g. node add.check.mjs); requires run --verify or CODEBUDDY_AUTONOMY_VERIFY_COMMANDS=1')
+        .option('--files-to-modify <paths>', 'comma-separated repo files this task is allowed to change')
+        .option('--acceptance-criteria <item>', 'acceptance criterion (repeatable)', (v, acc) => { acc.push(v); return acc; }, [])
         .option('--goal-mode', 'judge-gated loop: the worker keeps going until an LLM judge confirms the task is done, then blocks for human review when the budget is spent')
         .option('--goal-max-turns <n>', 'goal-mode turn budget (default 5)')
         .option('--dir <path>', 'colab dir')
@@ -924,11 +1015,17 @@ export function registerFleetAutonomyCommands(program) {
         const { FleetColabStore } = await import('../../fleet/colab-store.js');
         const store = new FleetColabStore({ ...(opts.dir ? { dir: opts.dir } : {}) });
         const priority = ['critical', 'high', 'medium', 'low'].find((p) => p === opts.priority) ?? 'medium';
+        const filesToModify = splitCsv(opts.filesToModify);
+        const acceptanceCriteria = (opts.acceptanceCriteria ?? []).map((s) => s.trim()).filter(Boolean);
+        const verifyCommand = opts.verifyCommand?.trim();
         const task = store.addTask({
             title,
             priority,
             ...(opts.description ? { description: opts.description } : {}),
             ...(opts.dependsOn ? { dependsOn: opts.dependsOn.split(',').map((s) => s.trim()).filter(Boolean) } : {}),
+            ...(verifyCommand ? { verifyCommand } : {}),
+            ...(filesToModify ? { filesToModify } : {}),
+            ...(acceptanceCriteria.length ? { acceptanceCriteria } : {}),
             ...(opts.goalMode ? { goalMode: true } : {}),
             ...(goalMaxTurns !== undefined ? { goalMaxTurns } : {}),
         });
@@ -937,7 +1034,8 @@ export function registerFleetAutonomyCommands(program) {
             return;
         }
         const goalNote = task.goalMode ? ` goal-mode(${task.goalMaxTurns ?? 5} turns)` : '';
-        console.log(`Added task ${task.id} [${task.priority}]${goalNote}${task.dependsOn ? ` depends on ${task.dependsOn.join(', ')}` : ''}`);
+        const gateNote = task.verifyCommand ? ` verify:${task.verifyCommand}` : '';
+        console.log(`Added task ${task.id} [${task.priority}]${goalNote}${gateNote}${task.dependsOn ? ` depends on ${task.dependsOn.join(', ')}` : ''}`);
     });
     tasks
         .command('board')
@@ -1334,6 +1432,173 @@ export function registerCompanionCommands(program) {
         const { getCompanionStatus, formatCompanionStatus } = await import('../../companion/companion-mode.js');
         console.log(formatCompanionStatus(await getCompanionStatus()));
     });
+    companion
+        .command('doctor')
+        .description('Diagnose Lisa persona / spokenPrompt / ROBOT_NAME alignment (exit 1 on errors)')
+        .option('--json', 'Print structured JSON')
+        .action(async (opts) => {
+        const { formatCompanionDoctorReport, runLiveCompanionDoctor, } = await import('../../companion/companion-doctor.js');
+        const report = await runLiveCompanionDoctor();
+        console.log(opts.json ? JSON.stringify(report, null, 2) : formatCompanionDoctorReport(report));
+        if (!report.ok)
+            process.exitCode = 1;
+    });
+    const continuity = companion
+        .command('continuity')
+        .description('Manage the integrity-protected companion lineage across models, machines, and future bodies');
+    continuity
+        .command('init')
+        .description('Create the continuity charter and first reviewed artifact snapshot')
+        .option('--json', 'Print the manifest as JSON')
+        .action(async (opts) => {
+        const { refreshCompanionContinuity, getCompanionContinuityStatus, formatCompanionContinuityStatus, } = await import('../../companion/continuity.js');
+        const manifest = refreshCompanionContinuity();
+        console.log(opts.json
+            ? JSON.stringify(manifest, null, 2)
+            : formatCompanionContinuityStatus(getCompanionContinuityStatus()));
+    });
+    continuity
+        .command('status')
+        .description('Show lineage integrity, required anchors, and migration readiness')
+        .option('--json', 'Print structured JSON')
+        .action(async (opts) => {
+        const { getCompanionContinuityStatus, formatCompanionContinuityStatus, } = await import('../../companion/continuity.js');
+        const status = getCompanionContinuityStatus();
+        console.log(opts.json ? JSON.stringify(status, null, 2) : formatCompanionContinuityStatus(status));
+    });
+    continuity
+        .command('refresh')
+        .description('Accept reviewed artifact changes and refresh their integrity snapshot')
+        .option('--json', 'Print the refreshed manifest as JSON')
+        .action(async (opts) => {
+        const { refreshCompanionContinuity, getCompanionContinuityStatus, formatCompanionContinuityStatus, } = await import('../../companion/continuity.js');
+        const manifest = refreshCompanionContinuity();
+        console.log(opts.json
+            ? JSON.stringify(manifest, null, 2)
+            : formatCompanionContinuityStatus(getCompanionContinuityStatus()));
+    });
+    continuity
+        .command('verify')
+        .description('Verify the charter and every recorded continuity artifact without changing them')
+        .option('--json', 'Print structured JSON')
+        .action(async (opts) => {
+        const { getCompanionContinuityStatus, formatCompanionContinuityStatus, } = await import('../../companion/continuity.js');
+        const status = getCompanionContinuityStatus();
+        console.log(opts.json ? JSON.stringify(status, null, 2) : formatCompanionContinuityStatus(status));
+        if (!status.valid)
+            process.exitCode = 1;
+    });
+    const migration = companion
+        .command('migration')
+        .alias('migrate')
+        .description('Export, verify, and safely restore an encrypted companion lineage bundle');
+    migration
+        .command('export')
+        .description('Create an authenticated encrypted bundle of the reviewed companion lineage')
+        .option('-o, --output <path>', 'Destination .cbm bundle path')
+        .option('--key-file <path>', 'Recovery key file (defaults to ~/.codebuddy/companion/migration.key)')
+        .option('--json', 'Print structured JSON')
+        .action(async (opts) => {
+        const { exportCompanionMigration, formatCompanionMigrationResult, getOrCreateCompanionMigrationPassphrase, readCompanionMigrationPassphrase, } = await import('../../companion/migration.js');
+        const key = opts.keyFile || process.env.CODEBUDDY_COMPANION_MIGRATION_KEY
+            ? readCompanionMigrationPassphrase({ keyFile: opts.keyFile })
+            : getOrCreateCompanionMigrationPassphrase();
+        const result = exportCompanionMigration({ passphrase: key.passphrase, bundlePath: opts.output });
+        console.log(opts.json
+            ? JSON.stringify({ ...result, keyPath: key.keyPath }, null, 2)
+            : formatCompanionMigrationResult(result, key.keyPath));
+    });
+    migration
+        .command('verify <bundle>')
+        .description('Decrypt and verify a migration bundle without writing any companion data')
+        .option('--key-file <path>', 'Recovery key file')
+        .option('--json', 'Print structured JSON')
+        .action(async (bundle, opts) => {
+        const { formatCompanionMigrationResult, readCompanionMigrationPassphrase, restoreCompanionMigration, } = await import('../../companion/migration.js');
+        const key = readCompanionMigrationPassphrase({ keyFile: opts.keyFile });
+        const result = restoreCompanionMigration({ passphrase: key.passphrase, bundlePath: bundle });
+        console.log(opts.json ? JSON.stringify(result, null, 2) : formatCompanionMigrationResult(result, key.keyPath));
+        if (!result.valid)
+            process.exitCode = 1;
+    });
+    migration
+        .command('restore <bundle>')
+        .description('Preview restoration by default; use --apply after reviewing the report')
+        .option('--apply', 'Write the verified artifacts to this machine')
+        .option('--overwrite', 'Replace differing existing artifacts (requires --apply)')
+        .option('--key-file <path>', 'Recovery key file')
+        .option('--json', 'Print structured JSON')
+        .action(async (bundle, opts) => {
+        const { formatCompanionMigrationResult, readCompanionMigrationPassphrase, restoreCompanionMigration, } = await import('../../companion/migration.js');
+        if (opts.overwrite && !opts.apply)
+            throw new Error('--overwrite requires --apply.');
+        const key = readCompanionMigrationPassphrase({ keyFile: opts.keyFile });
+        const result = restoreCompanionMigration({
+            passphrase: key.passphrase,
+            bundlePath: bundle,
+            apply: opts.apply,
+            overwrite: opts.overwrite,
+        });
+        console.log(opts.json ? JSON.stringify(result, null, 2) : formatCompanionMigrationResult(result, key.keyPath));
+        if (!result.valid || (opts.apply && !result.applied))
+            process.exitCode = 1;
+    });
+    companion
+        .command('live')
+        .description('Build a live-session preflight brief for voice, vision, memory, and fleet')
+        .option('--no-record', 'Do not write the live brief into the companion percept journal')
+        .action(async (opts) => {
+        const { buildCompanionLiveBrief, formatCompanionLiveBrief, } = await import('../../companion/companion-mode.js');
+        const brief = await buildCompanionLiveBrief({
+            record: opts.record !== false,
+        });
+        console.log(formatCompanionLiveBrief(brief));
+    });
+    companion
+        .command('listen-check')
+        .alias('heard')
+        .description('Transcribe the latest real companion WAV and show whether the voice gate would answer')
+        .option('--wav <path>', 'Inspect a specific WAV instead of the newest companion utterance')
+        .action(async (opts) => {
+        const { buildCompanionListenCheck, formatCompanionListenCheck, } = await import('../../companion/companion-mode.js');
+        console.log(formatCompanionListenCheck(await buildCompanionListenCheck({ wav: opts.wav })));
+    });
+    companion
+        .command('interactions')
+        .description('List the built-in voice interaction shortcuts used before the LLM path')
+        .option('--category <name>', 'Filter by category')
+        .option('--json', 'Print machine-readable JSON')
+        .action(async (opts) => {
+        const { VOICE_INTERACTIONS } = await import('../../sensory/voice-interactions.js');
+        const category = opts.category?.trim().toLowerCase();
+        const interactions = VOICE_INTERACTIONS
+            .filter(interaction => !category || interaction.category === category)
+            .map(interaction => ({
+            id: interaction.id,
+            category: interaction.category,
+            examples: interaction.examples,
+            reply: interaction.reply,
+        }));
+        if (opts.json) {
+            console.log(JSON.stringify(interactions, null, 2));
+            return;
+        }
+        const lines = [
+            'Voice Interactions',
+            '='.repeat(50),
+            `Count: ${interactions.length}`,
+        ];
+        let currentCategory = '';
+        for (const interaction of interactions) {
+            if (interaction.category !== currentCategory) {
+                currentCategory = interaction.category;
+                lines.push('', `[${currentCategory}]`);
+            }
+            lines.push(`- ${interaction.id}: ${interaction.examples.join(' | ')}`);
+            lines.push(`  → ${interaction.reply}`);
+        }
+        console.log(lines.join('\n'));
+    });
     companion
         .command('self')
         .description('Record Buddy companion self-state into the local percept journal')
@@ -1484,9 +1749,22 @@ export function registerCompanionCommands(program) {
         const { formatCompanionSkillCandidates, readCompanionSkillCandidates, } = await import('../../companion/skill-curator.js');
         console.log(formatCompanionSkillCandidates(await readCompanionSkillCandidates()));
     });
+    skills
+        .command('review <id>')
+        .description('Review a companion skill candidate before promotion')
+        .requiredOption('--reviewed-by <name>', 'Human reviewer identity')
+        .option('--note <text>', 'Optional review note')
+        .action(async (id, opts) => {
+        const { reviewCompanionSkillCandidate } = await import('../../companion/skill-curator.js');
+        const candidate = await reviewCompanionSkillCandidate(id, {
+            reviewedBy: opts.reviewedBy,
+            note: opts.note,
+        });
+        console.log(`Companion skill candidate reviewed: ${candidate.id} by ${candidate.reviewedBy}`);
+    });
     skills
         .command('promote <id>')
-        .description('Promote a companion skill candidate into a workspace-local skill artifact')
+        .description('Promote a reviewed companion skill candidate into a workspace-local skill artifact')
         .action(async (id) => {
         const { formatCompanionSkillPromotion, promoteCompanionSkillCandidate, } = await import('../../companion/skill-curator.js');
         console.log(formatCompanionSkillPromotion(await promoteCompanionSkillCandidate(id)));
@@ -1699,21 +1977,120 @@ export function registerCompanionCommands(program) {
         .description('Show recent companion percepts')
         .option('--limit <n>', 'Maximum percepts to print', '10')
         .option('--modality <name>', 'Filter by modality: vision, hearing, screen, self, memory, tool, suggestion')
+        .option('--workspace-target <path>', 'Workspace whose .codebuddy/companion/percepts.jsonl should be read (default: cwd)')
+        .option('--store-path <path>', 'Explicit percept store JSONL path')
         .action(async (opts) => {
         const { readRecentCompanionPercepts, formatCompanionPercepts } = await import('../../companion/percepts.js');
         const modality = opts.modality;
-        const recent = await readRecentCompanionPercepts({
+        const query = {
             limit: parseInt(opts.limit, 10),
             modality,
-        });
+            ...(opts.workspaceTarget ? { cwd: opts.workspaceTarget } : {}),
+            ...(opts.storePath ? { storePath: opts.storePath } : {}),
+        };
+        const recent = await readRecentCompanionPercepts(query);
         console.log(formatCompanionPercepts(recent));
     });
     percepts
         .command('stats')
         .description('Show companion percept store statistics')
-        .action(async () => {
+        .option('--workspace-target <path>', 'Workspace whose .codebuddy/companion/percepts.jsonl should be read (default: cwd)')
+        .option('--store-path <path>', 'Explicit percept store JSONL path')
+        .action(async (opts) => {
         const { getCompanionPerceptStats, formatCompanionPerceptStats } = await import('../../companion/percepts.js');
-        console.log(formatCompanionPerceptStats(await getCompanionPerceptStats()));
+        console.log(formatCompanionPerceptStats(await getCompanionPerceptStats({
+            ...(opts.workspaceTarget ? { cwd: opts.workspaceTarget } : {}),
+            ...(opts.storePath ? { storePath: opts.storePath } : {}),
+        })));
+    });
+    const ttsCache = companion
+        .command('tts-cache')
+        .description('Inspect the local Piper/TTS synthesis cache used by the voice assistant');
+    ttsCache
+        .command('stats')
+        .description('Show cached spoken phrases sorted by reuse count')
+        .option('--limit <n>', 'Maximum entries to print', '10')
+        .action(async (opts) => {
+        const { getTtsCache } = await import('../../sensory/tts-cache.js');
+        const limit = Math.max(1, Math.min(100, parseInt(opts.limit, 10) || 10));
+        const entries = getTtsCache().stats().slice(0, limit);
+        if (entries.length === 0) {
+            console.log('TTS cache is empty.');
+            return;
+        }
+        const totalBytes = entries.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+        const lines = [
+            'TTS Cache',
+            '='.repeat(50),
+            `Shown: ${entries.length}`,
+            `Shown size: ${Math.round(totalBytes / 1024)} KB`,
+        ];
+        for (const entry of entries) {
+            const preview = entry.text.length > 80 ? `${entry.text.slice(0, 77)}...` : entry.text;
+            lines.push('', `${entry.key} hits=${entry.hits} size=${Math.round(entry.sizeBytes / 1024)}KB`, `  ${preview}`, `  lastUsed=${entry.lastUsedAt}${entry.voice ? ` voice=${entry.voice}` : ''}`);
+        }
+        console.log(lines.join('\n'));
+    });
+    ttsCache
+        .command('prewarm')
+        .description('Pre-generate common voice assistant replies into the local TTS cache without playing audio')
+        .option('--limit <n>', 'Maximum default phrases to pre-generate')
+        .option('--phrase <text...>', 'Specific phrase to pre-generate instead of the default corpus')
+        .action(async (opts) => {
+        const { prewarmVoiceReplyCache } = await import('../../sensory/voice-loop.js');
+        const phrases = opts.phrase && opts.phrase.length > 0 ? [opts.phrase.join(' ')] : undefined;
+        const limit = opts.limit ? Math.max(1, parseInt(opts.limit, 10) || 1) : undefined;
+        const result = await prewarmVoiceReplyCache({ ...(phrases ? { phrases } : {}), ...(limit ? { limit } : {}) });
+        console.log(`TTS cache prewarmed: ${result.cached}/${result.attempted} phrase(s).`);
+    });
+    const ttsBank = companion
+        .command('tts-bank')
+        .description('Build or verify the fixed-phrase TTS bank without playing audio');
+    const parseTtsBankProvider = (value) => {
+        const provider = value.trim().toLowerCase();
+        if (provider !== 'local' && provider !== 'elevenlabs') {
+            throw new Error("--provider must be 'local' or 'elevenlabs'");
+        }
+        return provider;
+    };
+    ttsBank
+        .command('build')
+        .description('Synthesize missing fixed phrases into the selected provider cache')
+        .option('--provider <provider>', 'local (Kyutai) or elevenlabs', 'local')
+        .action(async (opts) => {
+        const { buildTtsBank } = await import('../../voice/tts-bank.js');
+        const result = await buildTtsBank({ provider: parseTtsBankProvider(opts.provider) });
+        console.log(`TTS bank (${result.provider}): built=${result.built} present=${result.present} ` +
+            `failed=${result.failed} expected=${result.expected} rejected=${result.rejected.length}.`);
+        if (result.failed > 0)
+            process.exitCode = 1;
+    });
+    ttsBank
+        .command('list')
+        .description('List fixed phrases and their cache presence without synthesis or playback')
+        .option('--provider <provider>', 'local (Kyutai) or elevenlabs', 'local')
+        .action(async (opts) => {
+        const { listTtsBank } = await import('../../voice/tts-bank.js');
+        const result = listTtsBank({ provider: parseTtsBankProvider(opts.provider) });
+        console.log(`TTS bank (${result.provider}) voice=${result.voice}`);
+        for (const entry of result.entries) {
+            console.log(`${entry.present ? 'present' : 'missing'}\t${entry.text}`);
+        }
+        for (const rejected of result.rejected) {
+            console.log(`rejected:${rejected.reason}\t${rejected.text}`);
+        }
+    });
+    ttsBank
+        .command('verify')
+        .description('Verify fixed-phrase cache presence without synthesis or playback')
+        .option('--provider <provider>', 'local (Kyutai) or elevenlabs', 'local')
+        .action(async (opts) => {
+        const { verifyTtsBank } = await import('../../voice/tts-bank.js');
+        const result = verifyTtsBank({ provider: parseTtsBankProvider(opts.provider) });
+        console.log(`TTS bank (${result.provider}): present=${result.present}/${result.expected} ` +
+            `missing=${result.missing.length} rejected=${result.rejected.length}.`);
+        if (result.missing.length > 0 || result.rejected.length > 0)
+            process.exitCode = 1;
     });
 }
 // ============================================================================

package/dist/commands/cli/sensory-command.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI `buddy sensory status` — read-only inspection of event-driven surveillance.
+ *
+ * Patterned on `buddy rules …` / `registerBackupCommand`: a thin Commander
+ * registration that lazy-imports the collector so `src/index.ts` stays light.
+ */
+import type { Command } from 'commander';
+export declare function registerSensoryCommand(program: Command, write?: (msg: string) => void): void;

package/dist/commands/cli/sensory-command.js

@@ -0,0 +1,27 @@
+/**
+ * CLI `buddy sensory status` — read-only inspection of event-driven surveillance.
+ *
+ * Patterned on `buddy rules …` / `registerBackupCommand`: a thin Commander
+ * registration that lazy-imports the collector so `src/index.ts` stays light.
+ */
+export function registerSensoryCommand(program, write = (msg) => {
+    process.stdout.write(`${msg}\n`);
+}) {
+    program
+        .command('sensory [action]')
+        .description('Inspect event-driven surveillance (read-only) — status')
+        .option('--server-url <url>', 'Code Buddy server URL')
+        .option('--json', 'machine-readable JSON')
+        .action(async (action, options) => {
+        const act = (action || 'status').toLowerCase();
+        if (act !== 'status') {
+            write('Usage: buddy sensory status [--server-url <url>] [--json]');
+            process.exitCode = 1;
+            return;
+        }
+        const { collectSensoryStatus, formatSensoryStatus } = await import('../../sensory/sensory-status.js');
+        const view = await collectSensoryStatus({ serverUrl: options.serverUrl });
+        write(formatSensoryStatus(view, Boolean(options.json)));
+    });
+}
+//# sourceMappingURL=sensory-command.js.map