@phuetz/code-buddy 1.1.0 → 1.3.0

package/dist/sensory/screen-reaction.js

@@ -0,0 +1,59 @@
+/**
+ * Screen reaction — on a `screen/change` event from the nervous-system daemon,
+ * record a companion percept and (optionally) run an injected analyzer (OCR /
+ * vision describe). DEBOUNCED, opt-in (`CODEBUDDY_SENSORY_SCREEN=true`),
+ * never-throws. The heavy OCR/describe is pluggable so we don't duplicate Code
+ * Buddy's existing OCR/vision; inject an analyzer to wire it.
+ *
+ * @module sensory/screen-reaction
+ */
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+import { perceptionOf } from './reactions.js';
+export function wireScreenReaction(options = {}) {
+    const bus = getGlobalEventBus();
+    const debounceMs = options.debounceMs ?? Number(process.env.CODEBUDDY_SCREEN_DEBOUNCE_MS ?? 5000);
+    const now = options.now ?? (() => Date.now());
+    let lastAt = Number.NEGATIVE_INFINITY;
+    let inFlight = false;
+    const id = bus.on('sensory:perception', (evt) => {
+        const p = perceptionOf(evt);
+        if (p.modality !== 'screen' || p.kind !== 'change')
+            return;
+        const t = now();
+        if (t - lastAt < debounceMs) {
+            logger.info('[screen] change (debounced)');
+            return;
+        }
+        if (inFlight)
+            return; // a prior analyze() is still running — don't stampede
+        lastAt = t;
+        inFlight = true;
+        void (async () => {
+            try {
+                const analysis = options.analyzer ? await options.analyzer.analyze() : {};
+                const { recordCompanionPercept } = await import('../companion/percepts.js');
+                const score = p.payload?.score;
+                await recordCompanionPercept({
+                    modality: 'screen',
+                    source: 'sensory_screen_reaction',
+                    summary: `Screen changed${analysis.description ? ` → ${analysis.description}` : ''}`,
+                    confidence: 0.85,
+                    payload: { score, description: analysis.description },
+                    tags: ['screen', 'change'],
+                }, options.cwd ? { cwd: options.cwd } : {});
+                logger.info(`[screen] change recorded${analysis.description ? ` → ${analysis.description}` : ''}`);
+            }
+            catch (err) {
+                logger.warn(`[screen] reaction failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                inFlight = false;
+            }
+        })();
+    });
+    return () => {
+        bus.off(id);
+    };
+}
+//# sourceMappingURL=screen-reaction.js.map

package/dist/sensory/sensory-bridge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Sensory bridge — the ingress for the Rust `buddy-sense` nervous-system daemon.
+ *
+ * A loopback-only WebSocket server that receives `SensoryEvent` JSON frames from
+ * the daemon and re-emits them onto Code Buddy's internal event bus as
+ * `sensory:perception` events. Reactions (reactions.ts) subscribe to the bus.
+ *
+ * Opt-in via `CODEBUDDY_SENSORY=true` (wired in `buddy server`). Loopback-only +
+ * optional shared token. Never throws on a malformed frame.
+ *
+ * @module sensory/sensory-bridge
+ */
+export interface SensoryBridgeOptions {
+    host?: string;
+    port?: number;
+    /** If set, frames must carry a matching `token` field. */
+    token?: string;
+}
+export interface SensoryBridgeHandle {
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startSensoryBridge(options?: SensoryBridgeOptions): SensoryBridgeHandle;

package/dist/sensory/sensory-bridge.js

@@ -0,0 +1,85 @@
+/**
+ * Sensory bridge — the ingress for the Rust `buddy-sense` nervous-system daemon.
+ *
+ * A loopback-only WebSocket server that receives `SensoryEvent` JSON frames from
+ * the daemon and re-emits them onto Code Buddy's internal event bus as
+ * `sensory:perception` events. Reactions (reactions.ts) subscribe to the bus.
+ *
+ * Opt-in via `CODEBUDDY_SENSORY=true` (wired in `buddy server`). Loopback-only +
+ * optional shared token. Never throws on a malformed frame.
+ *
+ * @module sensory/sensory-bridge
+ */
+import { WebSocketServer } from 'ws';
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+/** The trust boundary: only known modalities pass; kinds are sanitized to a safe
+ * shape (no control chars / newlines, ≤64 chars) so a crafted local frame can't
+ * inject content downstream (e.g. into CODEBUDDY_MEMORY.md via dreaming). */
+const KNOWN_MODALITIES = new Set(['audio', 'vision', 'screen', 'vital', 'ui']);
+function sanitizeKind(kind) {
+    return kind.replace(/[^a-zA-Z0-9_:.-]/g, '').slice(0, 64);
+}
+export function startSensoryBridge(options = {}) {
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? Number(process.env.CODEBUDDY_SENSORY_PORT ?? 8129);
+    const token = options.token ?? process.env.CODEBUDDY_SENSORY_TOKEN;
+    const bus = getGlobalEventBus();
+    const wss = new WebSocketServer({ host, port });
+    wss.on('connection', (ws, req) => {
+        // Reject cross-origin (CSWSH): the Rust daemon sends NO Origin header; a
+        // browser page / extension always does. This stops a local web origin from
+        // injecting frames (and, with the camera reaction on, triggering the webcam).
+        if (req.headers.origin) {
+            ws.close();
+            return;
+        }
+        // Loopback-only: exact match, tolerating IPv4-mapped IPv6 (::ffff:127.0.0.1).
+        const remote = (req.socket.remoteAddress ?? '').replace(/^::ffff:/, '');
+        if (remote !== '127.0.0.1' && remote !== '::1') {
+            ws.close();
+            return;
+        }
+        logger.info('[sensory] daemon connected');
+        ws.on('message', (data) => {
+            let frame;
+            try {
+                frame = JSON.parse(String(data));
+            }
+            catch {
+                return; // ignore malformed
+            }
+            if (token && frame.token !== token)
+                return;
+            if (!frame.modality || !frame.kind)
+                return;
+            // Validate the string fields at the trust boundary (not just the numbers):
+            // unknown modality is dropped, kind is sanitized — blocks memory injection.
+            if (!KNOWN_MODALITIES.has(frame.modality))
+                return;
+            const kind = sanitizeKind(frame.kind);
+            if (!kind)
+                return;
+            // Validate/clamp numeric fields so a malformed frame can't poison downstream.
+            const salience = Number.isFinite(frame.salience) ? Math.max(0, Math.min(255, Math.round(frame.salience))) : 0;
+            const tsMs = Number.isFinite(frame.ts_ms) && frame.ts_ms >= 0 ? frame.ts_ms : undefined;
+            bus.emit('sensory:perception', {
+                source: 'buddy-sense',
+                metadata: {
+                    modality: frame.modality,
+                    kind,
+                    salience,
+                    tsMs,
+                    payload: frame.payload,
+                },
+            });
+        });
+    });
+    wss.on('error', (err) => logger.warn(`[sensory] bridge error: ${err instanceof Error ? err.message : String(err)}`));
+    logger.info(`[sensory] bridge listening on ws://${host}:${port}`);
+    return {
+        port,
+        close: () => new Promise((resolve) => wss.close(() => resolve())),
+    };
+}
+//# sourceMappingURL=sensory-bridge.js.map

package/dist/sensory/sensory-memory.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Short-term sensory memory — a bounded rolling buffer of recent perceptions
+ * (the nervous system's working memory). Reactions push every perception here;
+ * the dreaming consolidator drains + summarizes it into long-term memory every N
+ * heartbeats (like OpenClaw's dreaming: short-term recall → consolidated store).
+ *
+ * @module sensory/sensory-memory
+ */
+import type { Perception } from './reactions.js';
+export declare class SensoryMemory {
+    private readonly cap;
+    private buf;
+    constructor(cap?: number);
+    push(p: Perception): void;
+    snapshot(): Perception[];
+    /** Take everything and clear (consolidation consumes the window). */
+    drain(): Perception[];
+    size(): number;
+}
+export declare function getSensoryMemory(): SensoryMemory;

package/dist/sensory/sensory-memory.js

@@ -0,0 +1,39 @@
+/**
+ * Short-term sensory memory — a bounded rolling buffer of recent perceptions
+ * (the nervous system's working memory). Reactions push every perception here;
+ * the dreaming consolidator drains + summarizes it into long-term memory every N
+ * heartbeats (like OpenClaw's dreaming: short-term recall → consolidated store).
+ *
+ * @module sensory/sensory-memory
+ */
+export class SensoryMemory {
+    cap;
+    buf = [];
+    constructor(cap = 1000) {
+        this.cap = cap;
+    }
+    push(p) {
+        this.buf.push(p);
+        if (this.buf.length > this.cap)
+            this.buf.shift();
+    }
+    snapshot() {
+        return [...this.buf];
+    }
+    /** Take everything and clear (consolidation consumes the window). */
+    drain() {
+        const out = this.buf;
+        this.buf = [];
+        return out;
+    }
+    size() {
+        return this.buf.length;
+    }
+}
+let singleton;
+export function getSensoryMemory() {
+    if (!singleton)
+        singleton = new SensoryMemory();
+    return singleton;
+}
+//# sourceMappingURL=sensory-memory.js.map

package/dist/sensory/speech-reaction.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Speech reaction — closes the perception→cognition loop. On a `speech_end` event
+ * that carries the source WAV (the daemon tags it), transcribe the utterance (STT)
+ * and record what was heard as a `hearing` percept; an optional `onHeard` hook can
+ * drive further action (a turn, a command). DEBOUNCED (one transcription per
+ * utterance — the energy VAD over-segments), opt-in (`CODEBUDDY_SENSORY_SPEECH=true`),
+ * injectable transcriber, never-throws.
+ *
+ * @module sensory/speech-reaction
+ */
+export type Transcriber = (wav: string) => Promise<string>;
+export interface SpeechReactionOptions {
+    /** Injectable STT (tests / custom). Default: faster-whisper via python ($0). */
+    transcriber?: Transcriber;
+    debounceMs?: number;
+    cwd?: string;
+    now?: () => number;
+    /** Action hook for the transcript (e.g. trigger an agent turn). */
+    onHeard?: (text: string) => void | Promise<void>;
+}
+export declare function wireSpeechReaction(options?: SpeechReactionOptions): () => void;

package/dist/sensory/speech-reaction.js

@@ -0,0 +1,83 @@
+/**
+ * Speech reaction — closes the perception→cognition loop. On a `speech_end` event
+ * that carries the source WAV (the daemon tags it), transcribe the utterance (STT)
+ * and record what was heard as a `hearing` percept; an optional `onHeard` hook can
+ * drive further action (a turn, a command). DEBOUNCED (one transcription per
+ * utterance — the energy VAD over-segments), opt-in (`CODEBUDDY_SENSORY_SPEECH=true`),
+ * injectable transcriber, never-throws.
+ *
+ * @module sensory/speech-reaction
+ */
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+import { perceptionOf } from './reactions.js';
+/** Default transcriber: local faster-whisper (base), best-effort, $0. */
+async function defaultTranscribe(wav) {
+    const { spawn } = await import('child_process');
+    const model = process.env.CODEBUDDY_SPEECH_MODEL ?? 'base';
+    const py = [
+        'import sys',
+        'from faster_whisper import WhisperModel',
+        `m = WhisperModel(${JSON.stringify(model)}, device='cpu', compute_type='int8')`,
+        'segs, _ = m.transcribe(sys.argv[1])',
+        "print(' '.join(s.text for s in segs).strip())",
+    ].join('\n');
+    return new Promise((resolve) => {
+        const proc = spawn('python3', ['-c', py, wav], { stdio: ['ignore', 'pipe', 'ignore'] });
+        let out = '';
+        proc.stdout.on('data', (d) => (out += String(d)));
+        proc.on('close', () => resolve(out.trim()));
+        proc.on('error', () => resolve(''));
+    });
+}
+export function wireSpeechReaction(options = {}) {
+    const bus = getGlobalEventBus();
+    const debounceMs = options.debounceMs ?? Number(process.env.CODEBUDDY_SPEECH_DEBOUNCE_MS ?? 4000);
+    const now = options.now ?? (() => Date.now());
+    const transcribe = options.transcriber ?? defaultTranscribe;
+    let lastAt = Number.NEGATIVE_INFINITY;
+    let inFlight = false;
+    const id = bus.on('sensory:perception', (evt) => {
+        const p = perceptionOf(evt);
+        if (p.modality !== 'audio' || p.kind !== 'speech_end')
+            return;
+        const wav = p.payload?.wav;
+        if (!wav)
+            return; // no audio to transcribe (e.g. a live-mic path not yet wired)
+        const t = now();
+        if (t - lastAt < debounceMs)
+            return; // one transcription per utterance
+        if (inFlight)
+            return; // a prior STT (faster-whisper, seconds) is still running
+        lastAt = t;
+        inFlight = true;
+        void (async () => {
+            try {
+                const text = await transcribe(wav);
+                if (!text)
+                    return;
+                const { recordCompanionPercept } = await import('../companion/percepts.js');
+                await recordCompanionPercept({
+                    modality: 'hearing',
+                    source: 'sensory_speech_reaction',
+                    summary: `Heard: ${text}`,
+                    confidence: 0.8,
+                    payload: { text, wav },
+                    tags: ['speech', 'stt'],
+                }, options.cwd ? { cwd: options.cwd } : {});
+                logger.info(`[speech] heard → ${text}`);
+                await options.onHeard?.(text);
+            }
+            catch (err) {
+                logger.warn(`[speech] reaction failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                inFlight = false;
+            }
+        })();
+    });
+    return () => {
+        bus.off(id);
+    };
+}
+//# sourceMappingURL=speech-reaction.js.map

package/dist/sensory/vision-reaction.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Vision reaction — on a `vision/motion` event from the nervous-system daemon,
+ * run `camera_analyze` (capture a frame + describe it with a local gemma vision
+ * model) and record a companion percept. DEBOUNCED (gemma is heavy: 3–10s warm),
+ * opt-in (`CODEBUDDY_SENSORY_CAMERA=true`), best-effort, never-throws.
+ *
+ * @module sensory/vision-reaction
+ */
+export interface VisionAnalysis {
+    success: boolean;
+    description?: string;
+    imagePath?: string;
+}
+export interface VisionAnalyzer {
+    analyze(prompt: string): Promise<VisionAnalysis>;
+}
+export interface VisionReactionOptions {
+    /** Injectable analyzer (tests / custom). Defaults to camera_analyze (local gemma). */
+    analyzer?: VisionAnalyzer;
+    debounceMs?: number;
+    cwd?: string;
+    now?: () => number;
+}
+/** Security invariant (pure + testable): the camera reaction may only be wired
+ * when explicitly enabled AND a shared token is set — a crafted local frame can
+ * trigger the webcam, so an unauthenticated bridge must not be able to. */
+export declare function shouldWireVisionReaction(env: {
+    camera?: string;
+    token?: string;
+}): boolean;
+export declare function wireVisionReaction(options?: VisionReactionOptions): () => void;

package/dist/sensory/vision-reaction.js

@@ -0,0 +1,74 @@
+/**
+ * Vision reaction — on a `vision/motion` event from the nervous-system daemon,
+ * run `camera_analyze` (capture a frame + describe it with a local gemma vision
+ * model) and record a companion percept. DEBOUNCED (gemma is heavy: 3–10s warm),
+ * opt-in (`CODEBUDDY_SENSORY_CAMERA=true`), best-effort, never-throws.
+ *
+ * @module sensory/vision-reaction
+ */
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+import { perceptionOf } from './reactions.js';
+/** Default analyzer: Code Buddy's camera_analyze tool (ffmpeg capture + local gemma). */
+async function defaultAnalyze(prompt) {
+    const { CameraAnalyzeTool } = await import('../tools/registry/vision-tools.js');
+    const tool = new CameraAnalyzeTool({});
+    const result = await tool.execute({ prompt });
+    const data = result.data;
+    return { success: result.success, description: data?.description ?? result.output, imagePath: data?.imagePath };
+}
+/** Security invariant (pure + testable): the camera reaction may only be wired
+ * when explicitly enabled AND a shared token is set — a crafted local frame can
+ * trigger the webcam, so an unauthenticated bridge must not be able to. */
+export function shouldWireVisionReaction(env) {
+    return env.camera === 'true' && Boolean(env.token);
+}
+export function wireVisionReaction(options = {}) {
+    const bus = getGlobalEventBus();
+    const debounceMs = options.debounceMs ?? Number(process.env.CODEBUDDY_VISION_DEBOUNCE_MS ?? 8000);
+    const now = options.now ?? (() => Date.now());
+    const analyzer = options.analyzer ?? { analyze: defaultAnalyze };
+    let lastAt = Number.NEGATIVE_INFINITY;
+    let inFlight = false;
+    const id = bus.on('sensory:perception', (evt) => {
+        const p = perceptionOf(evt);
+        if (p.modality !== 'vision' || p.kind !== 'motion')
+            return;
+        const t = now();
+        if (t - lastAt < debounceMs) {
+            logger.info('[vision] motion (debounced — analysis throttled)');
+            return;
+        }
+        if (inFlight)
+            return; // a prior analyze() (ffmpeg+gemma, 3–10s) is still running
+        lastAt = t;
+        inFlight = true;
+        void (async () => {
+            try {
+                const res = await analyzer.analyze('Motion detected — describe the scene in one sentence.');
+                if (!res.success)
+                    return;
+                const { recordCompanionPercept } = await import('../companion/percepts.js');
+                await recordCompanionPercept({
+                    modality: 'vision',
+                    source: 'sensory_motion_reaction',
+                    summary: `Motion → ${res.description ?? '(no description)'}`,
+                    confidence: 0.9,
+                    payload: { description: res.description, imagePath: res.imagePath },
+                    tags: ['motion', 'camera', 'vision'],
+                }, options.cwd ? { cwd: options.cwd } : {});
+                logger.info(`[vision] motion analyzed → ${res.description ?? '(no description)'}`);
+            }
+            catch (err) {
+                logger.warn(`[vision] reaction failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                inFlight = false;
+            }
+        })();
+    });
+    return () => {
+        bus.off(id);
+    };
+}
+//# sourceMappingURL=vision-reaction.js.map

package/dist/server/index.js

@@ -14,6 +14,8 @@ import { createRequire } from 'module';
 import express from 'express';
 import cors from 'cors';
 import { createServer } from 'http';
+import { createServer as createHttpsServer, Server as HttpsServer } from 'https';
+import { resolveServerTlsOptions } from './tls-config.js';
 const _require = createRequire(import.meta.url);
 let SERVER_VERSION = '0.0.0';
 try {
@@ -77,7 +79,10 @@ export function getServerBaseUrl(server, config) {
     const port = typeof address === 'object' && address ? address.port : config.port;
     const publicHost = config.host === '0.0.0.0' || config.host === '::' ? '127.0.0.1' : config.host;
     const host = publicHost.includes(':') && !publicHost.startsWith('[') ? `[${publicHost}]` : publicHost;
-    return `http://${host}:${port}`;
+    // Report https:// when the server was constructed with TLS so the logged URL
+    // isn't a lie. Default (plain http.Server) stays http://.
+    const scheme = server instanceof HttpsServer ? 'https' : 'http';
+    return `${scheme}://${host}:${port}`;
 }
 // Default configuration
 const DEFAULT_CONFIG = {
@@ -839,6 +844,10 @@ function createApp(config) {
     app.use(errorHandler);
     return app;
 }
+/** Guards the sensory layer against double-wiring on a second in-process start. */
+let sensoryWired = false;
+/** Teardown fns for the sensory layer (bridge close, listener unsubscribes, scheduler stop). */
+let sensoryTeardown = [];
 /**
  * Start the server
  */
@@ -878,7 +887,17 @@ export async function startServer(userConfig = {}) {
         /* prometheus exporter optional */
     }
     const app = createApp(config);
-    const server = createServer(app);
+    // Optional TLS: serve the API (including /api/mobile) over HTTPS when
+    // CODEBUDDY_HTTPS / CODEBUDDY_MOBILE_TLS is set so the mobile-supervision
+    // endpoint can be exposed off-device securely. Default (no env) is plain HTTP,
+    // byte-for-byte unchanged. resolveServerTlsOptions() throws (never silently
+    // downgrades) if TLS is requested but cannot be satisfied. The https.Server
+    // surface (listen/address/on('upgrade')/close) matches http.Server at runtime,
+    // so we keep the `HttpServer` type to avoid widening downstream signatures.
+    const tlsOptions = resolveServerTlsOptions();
+    const server = tlsOptions
+        ? createHttpsServer(tlsOptions, app)
+        : createServer(app);
     const startChannelBridge = async (baseUrl) => {
         try {
             const { getChannelManager } = await import('../channels/index.js');
@@ -1003,6 +1022,80 @@ export async function startServer(userConfig = {}) {
             logger.info(`Metrics Dashboard: ${baseUrl}/api/metrics/dashboard`);
             logger.info(`Docs: ${baseUrl}/api/docs`);
             logger.info(`WebSocket: ${config.websocketEnabled ? 'Enabled (/ws)' : 'Disabled'}`);
+            // Sensory nervous-system bridge (opt-in): ingress for the Rust buddy-sense
+            // daemon → internal event bus → reactions. Loopback-only.
+            if (process.env.CODEBUDDY_SENSORY === 'true' && !sensoryWired) {
+                sensoryWired = true; // wire once per process (a 2nd start would double listeners + re-bind the port)
+                try {
+                    const { startSensoryBridge } = await import('../sensory/sensory-bridge.js');
+                    const { wireSensoryReactions } = await import('../sensory/reactions.js');
+                    const { getHeartbeatScheduler } = await import('../sensory/heartbeat-scheduler.js');
+                    const sensoryBridgeHandle = startSensoryBridge();
+                    const unwireReactions = wireSensoryReactions();
+                    sensoryTeardown.push(() => sensoryBridgeHandle.close(), unwireReactions);
+                    // Vision reaction (opt-in) — vision/motion → camera_analyze (local gemma).
+                    // Requires a shared token: a frame can trigger the webcam, so refuse to
+                    // wire it on an unauthenticated bridge.
+                    const sensoryToken = process.env.CODEBUDDY_SENSORY_TOKEN;
+                    {
+                        const { shouldWireVisionReaction, wireVisionReaction } = await import('../sensory/vision-reaction.js');
+                        if (shouldWireVisionReaction({ camera: process.env.CODEBUDDY_SENSORY_CAMERA, token: sensoryToken })) {
+                            sensoryTeardown.push(wireVisionReaction());
+                            logger.info('Sensory vision reaction: Enabled (vision/motion → camera_analyze)');
+                        }
+                        else if (process.env.CODEBUDDY_SENSORY_CAMERA === 'true') {
+                            logger.warn('Sensory vision reaction NOT enabled: set CODEBUDDY_SENSORY_TOKEN to allow camera triggering.');
+                        }
+                    }
+                    // Screen reaction (opt-in) — also token-gated (an injected analyzer could capture the desktop).
+                    if (process.env.CODEBUDDY_SENSORY_SCREEN === 'true') {
+                        if (sensoryToken) {
+                            const { wireScreenReaction } = await import('../sensory/screen-reaction.js');
+                            sensoryTeardown.push(wireScreenReaction());
+                            logger.info('Sensory screen reaction: Enabled (screen/change → percept)');
+                        }
+                        else {
+                            logger.warn('Sensory screen reaction NOT enabled: set CODEBUDDY_SENSORY_TOKEN.');
+                        }
+                    }
+                    // Speech reaction (opt-in) — speech_end → STT → 'hearing' percept (+ onHeard hook).
+                    if (process.env.CODEBUDDY_SENSORY_SPEECH === 'true') {
+                        const { wireSpeechReaction } = await import('../sensory/speech-reaction.js');
+                        sensoryTeardown.push(wireSpeechReaction());
+                        logger.info('Sensory speech reaction: Enabled (speech_end → STT → percept)');
+                    }
+                    // Privacy: camera/screen descriptions land in percepts.jsonl — warn if not encrypted at rest.
+                    if ((process.env.CODEBUDDY_SENSORY_CAMERA === 'true' || process.env.CODEBUDDY_SENSORY_SCREEN === 'true') &&
+                        !process.env.CODEBUDDY_COMPANION_ENCRYPTION_KEY &&
+                        !process.env.CODEBUDDY_MEMORY_KEY) {
+                        logger.warn('Sensory camera/screen percepts are written UNENCRYPTED — set CODEBUDDY_COMPANION_ENCRYPTION_KEY to encrypt scene/screen descriptions at rest.');
+                    }
+                    // Heartbeat pacemaker — heartbeats trigger periodic processing (every N beats).
+                    const heart = getHeartbeatScheduler();
+                    const everyBeats = Math.max(1, Number(process.env.CODEBUDDY_HEARTBEAT_EVERY ?? 10));
+                    heart.register({
+                        name: 'pacemaker-tick',
+                        everyBeats,
+                        handler: (ctx) => logger.info(`[heartbeat] pacemaker tick — beat ${ctx.beat} (load ${ctx.load1 ?? '?'})`),
+                    });
+                    // Dreaming — consolidate short-term sensory memory every N beats.
+                    const dreamEvery = Math.max(1, Number(process.env.CODEBUDDY_DREAM_EVERY ?? 30));
+                    heart.register({
+                        name: 'dreaming',
+                        everyBeats: dreamEvery,
+                        handler: async () => {
+                            const { runDreamingPass } = await import('../sensory/dreaming.js');
+                            await runDreamingPass();
+                        },
+                    });
+                    heart.start();
+                    sensoryTeardown.push(() => heart.stop());
+                    logger.info(`Sensory bridge: Enabled (buddy-sense → event bus; heartbeat treatments every ${everyBeats} beats)`);
+                }
+                catch (err) {
+                    logger.warn(`Sensory bridge failed to start: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
             logger.info(`Auth: ${config.authEnabled ? 'Enabled' : 'Disabled'}`);
             if (!isLoopbackHost(config.host)) {
                 logger.warn(`Server is bound to ${config.host} (non-loopback) and is reachable from the network. ` +
@@ -1057,6 +1150,17 @@ export async function startServer(userConfig = {}) {
  * Stop the server gracefully
  */
 export async function stopServer(server) {
+    // Tear down the sensory layer (WS bridge, bus listeners, heartbeat scheduler) so
+    // an in-process restart doesn't leak listeners or EADDRINUSE the bridge port.
+    for (const teardown of sensoryTeardown.splice(0)) {
+        try {
+            await teardown();
+        }
+        catch {
+            /* never throw on shutdown */
+        }
+    }
+    sensoryWired = false;
     return new Promise((resolve, reject) => {
         // Phase (d).9 — cancel the heartbeat timer so it doesn't keep
         // emitting against a half-shut server. Idempotent.

package/dist/server/routes/mobile.d.ts

@@ -1,4 +1,5 @@
 import { Request, Response, NextFunction } from 'express';
+import { EventEmitter } from 'events';
 export declare const mobileRouter: import("express-serve-static-core").Router;
 export declare let activePairingCode: string;
 export declare let activePairingCodeExpiresAt: number;
@@ -10,11 +11,11 @@ export declare const activeTokens: Map<string, {
  * A follow-up prompt review draft. The mobile device (or a draft-only call) can
  * *propose* a prompt, but it never executes: it lands here as
  * `needs_local_operator` and only a local operator (loopback) can `approve` or
- * `cancel` it. Approval is a review-gate marker — it records who/when but never
- * dispatches work, matching the gateway contract's `autoDispatch:false` /
- * `remoteExecutionDisabled:true` invariants.
+ * `cancel` it. When `CODEBUDDY_MOBILE_ALLOW_DISPATCH=true`, an approved draft
+ * can optionally be dispatched to the agent for execution. When the env var is
+ * OFF (default), approval remains a review-gate marker only.
  */
-export type FollowupDraftStatus = 'needs_local_operator' | 'approved' | 'cancelled';
+export type FollowupDraftStatus = 'needs_local_operator' | 'approved' | 'cancelled' | 'dispatched' | 'completed' | 'failed';
 export interface FollowupDraft {
     id: string;
     prompt: string;
@@ -24,9 +25,16 @@ export interface FollowupDraft {
     approvedBy?: string;
     approvedAt?: number;
     cancelledAt?: number;
+    dispatchedAt?: number;
+    completedAt?: number;
+    failedAt?: number;
+    failureReason?: string;
     [key: string]: unknown;
 }
 export declare const followupDrafts: FollowupDraft[];
+export declare const mobileEventBus: EventEmitter<[never]>;
+/** Check whether dispatch is enabled via environment variable. */
+export declare function isDispatchEnabled(): boolean;
 /**
  * Decide whether a request originates from the loopback interface. We read the
  * raw socket address (`req.socket.remoteAddress`) on purpose: `req.ip` and the