@cgh567/agent 2.4.3 → 2.4.4

package/lib/compression/__tests__/smart-crusher.test.js

@@ -0,0 +1,242 @@
+/**
+ * lib/compression/__tests__/smart-crusher.test.js
+ *
+ * Unit tests for SmartCrusher.
+ * Tests: lossless-csv path, lossy-sample path, passthrough gates,
+ *        CCR storage, savings ratio threshold.
+ *
+ * No mocks — tests the real SmartCrusher implementation.
+ */
+'use strict';
+
+const { describe, it, expect, beforeEach } = require('vitest');
+const { SmartCrusher, DEFAULT_CRUSHER_CONFIG } = require('../dist/smart-crusher.js');
+const { CcrStore } = require('../dist/ccr-store.js');
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeUniform(n, extraFields = {}) {
+  return Array.from({ length: n }, (_, i) => ({
+    id: `lead-${String(i).padStart(4, '0')}`,
+    type: 'signal',
+    status: i % 3 === 0 ? 'active' : 'inactive',
+    score: 70 + (i % 30),
+    source: 'salesforce',
+    ...extraFields,
+  }));
+}
+
+function makeSparse(n) {
+  // Each item has only 'id' as a universal field — no lossless-csv possible
+  return Array.from({ length: n }, (_, i) => {
+    const base = { id: `rec-${i}` };
+    if (i % 2 === 0) base.a = `a_${i}`;
+    if (i % 3 === 0) base.b = `b_${i}`;
+    if (i % 5 === 0) base.c = `c_${i}`;
+    if (i % 7 === 0) base.d = `d_${i}`;
+    // Pad to exceed 500 char min
+    base.pad = 'x'.repeat(30);
+    return base;
+  });
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('SmartCrusher — passthrough gates', () => {
+  let crusher;
+  beforeEach(() => { crusher = new SmartCrusher(); });
+
+  it('returns passthrough for input shorter than minCharsToCompress (200)', () => {
+    const tiny = JSON.stringify([{ id: 1 }, { id: 2 }]);
+    expect(tiny.length).toBeLessThan(DEFAULT_CRUSHER_CONFIG.minCharsToCompress);
+    const result = crusher.compress(tiny, null);
+    expect(result.compressed).toBe(false);
+    expect(result.strategy).toBe('passthrough');
+  });
+
+  it('returns passthrough for non-JSON input', () => {
+    const text = 'This is plain text, not JSON. '.repeat(20);
+    const result = crusher.compress(text, null);
+    expect(result.compressed).toBe(false);
+    expect(result.strategy).toBe('passthrough');
+  });
+
+  it('returns passthrough for JSON object (not array)', () => {
+    const obj = JSON.stringify({ key: 'value', items: [1, 2, 3] });
+    const result = crusher.compress(obj, null);
+    expect(result.compressed).toBe(false);
+    expect(result.strategy).toBe('passthrough');
+  });
+
+  it('returns passthrough for arrays smaller than minItemsToAnalyze (5)', () => {
+    const small = JSON.stringify(makeUniform(4));
+    const result = crusher.compress(small, null);
+    expect(result.compressed).toBe(false);
+    expect(result.strategy).toBe('passthrough');
+  });
+
+  it('returns passthrough when lossless savings < losslessMinSavingsRatio (15%)', () => {
+    // A 5-item array — lossless might not save enough; if it doesn't, should passthrough
+    const arr = JSON.stringify(makeUniform(5));
+    const result = crusher.compress(arr, null);
+    // Either passthrough or lossless-csv — never lossy-sample for 5 items
+    if (!result.compressed) {
+      expect(result.strategy).toBe('passthrough');
+    } else {
+      expect(result.strategy).toBe('lossless-csv');
+    }
+  });
+});
+
+describe('SmartCrusher — lossless-csv path', () => {
+  let crusher;
+  beforeEach(() => { crusher = new SmartCrusher(); });
+
+  it('compresses a 30-item uniform array to lossless-csv', () => {
+    const input = JSON.stringify(makeUniform(30));
+    const result = crusher.compress(input, null);
+    expect(result.compressed).toBe(true);
+    expect(result.strategy).toBe('lossless-csv');
+    expect(result.rowsDropped).toBe(0);
+    expect(result.output).toContain('[csv:');
+  });
+
+  it('lossless-csv output contains header row', () => {
+    const input = JSON.stringify(makeUniform(20));
+    const result = crusher.compress(input, null);
+    if (result.strategy !== 'lossless-csv') return; // skip if not triggered
+    // Header should contain field names separated by tabs
+    const lines = result.output.split('\n');
+    const headerLine = lines.find((l) => l.includes('\t'));
+    expect(headerLine).toBeTruthy();
+  });
+
+  it('savings ratio >= 15% for 30-item uniform array', () => {
+    const input = JSON.stringify(makeUniform(30));
+    const result = crusher.compress(input, null);
+    if (result.strategy !== 'lossless-csv') return;
+    const savings = 1 - result.output.length / input.length;
+    expect(savings).toBeGreaterThanOrEqual(DEFAULT_CRUSHER_CONFIG.losslessMinSavingsRatio);
+  });
+
+  it('rejects arrays with fewer than 3 core fields', () => {
+    // Array where only 1 field appears in >=80% of items
+    const arr = Array.from({ length: 20 }, (_, i) => {
+      const o = { id: `id-${i}`, pad: 'p'.repeat(50) };
+      if (i % 5 === 0) o.x = i;
+      if (i % 7 === 0) o.y = i;
+      return o;
+    });
+    const input = JSON.stringify(arr);
+    const result = crusher.compress(input, null);
+    // Should not use lossless-csv (only 2 fields appear in all items, but id+pad=2 < 3)
+    // May be lossy-sample or passthrough depending on n vs maxItemsAfterCrush
+    if (result.compressed) {
+      expect(result.strategy).not.toBe('lossless-csv');
+    }
+  });
+});
+
+describe('SmartCrusher — lossy-sample path', () => {
+  let crusher;
+  let store;
+  beforeEach(() => {
+    crusher = new SmartCrusher();
+    store = new CcrStore(60); // 60s TTL for tests
+  });
+  afterEach(() => { store.destroy(); });
+
+  function makeSparseInput(n) {
+    // Only 'id' universal — no lossless-csv. Long enough to exceed 8000 chars.
+    const pad = 'x'.repeat(200);
+    return Array.from({ length: n }, (_, i) => {
+      const o = { id: `item-${String(i).padStart(5, '0')}` };
+      if (i % 2 === 0) o.payload = `pay_${i}_${pad}`;
+      if (i % 3 === 0) o.stage = 'active';
+      if (i % 4 === 0) o.value = i * 100;
+      if (i % 5 === 0) o.ts = `2026-06-${String((i % 28) + 1).padStart(2, '0')}`;
+      if (i % 6 === 0) o.owner = `rep-${i % 8}`;
+      if (i % 7 === 0) o.src = 'crm';
+      return o;
+    });
+  }
+
+  it('triggers lossy-sample when n > maxItemsAfterCrush (15) and lossless fails', () => {
+    const input = JSON.stringify(makeSparseInput(40));
+    const result = crusher.compress(input, store);
+    expect(result.compressed).toBe(true);
+    expect(result.strategy).toBe('lossy-sample');
+    expect(result.rowsDropped).toBeGreaterThan(0);
+  });
+
+  it('stores dropped rows in CCR store', () => {
+    const input = JSON.stringify(makeSparseInput(40));
+    const result = crusher.compress(input, store);
+    if (result.strategy !== 'lossy-sample') return;
+    expect(result.ccrHash).not.toBeNull();
+    const stored = store.get(result.ccrHash);
+    expect(stored).not.toBeNull();
+    const parsed = JSON.parse(stored);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed.length).toBe(result.rowsDropped);
+  });
+
+  it('output contains CCR marker for dropped rows', () => {
+    const input = JSON.stringify(makeSparseInput(40));
+    const result = crusher.compress(input, store);
+    if (result.strategy !== 'lossy-sample') return;
+    expect(result.output).toContain('_ccr_dropped');
+    expect(result.output).toContain(result.ccrHash);
+  });
+
+  it('kept items include error-signaling items (score += 100)', () => {
+    // Items with 'error' or 'failed' values should be preserved
+    const items = makeSparseInput(40);
+    // Inject an error item in the middle
+    items[20] = { id: 'item-00020', status: '"error"', reason: 'timeout_exceeded' };
+    const input = JSON.stringify(items);
+    const result = crusher.compress(input, store);
+    if (result.strategy !== 'lossy-sample') return;
+    // The error item should be in the kept portion
+    expect(result.output).toContain('item-00020');
+  });
+
+  it('deletes CCR entry when savings < threshold', () => {
+    // Array just over maxItemsAfterCrush but with high savings already (lossless might win)
+    const tiny = JSON.stringify(makeSparseInput(16));
+    const result = crusher.compress(tiny, store);
+    // If no savings or passthrough, CCR store should not be polluted
+    if (!result.compressed) {
+      expect(result.ccrHash).toBeNull();
+    }
+  });
+});
+
+describe('SmartCrusher — DEFAULT_CRUSHER_CONFIG', () => {
+  it('exports expected default config values', () => {
+    expect(DEFAULT_CRUSHER_CONFIG.minItemsToAnalyze).toBe(5);
+    expect(DEFAULT_CRUSHER_CONFIG.minCharsToCompress).toBe(200);
+    expect(DEFAULT_CRUSHER_CONFIG.maxItemsAfterCrush).toBe(15);
+    expect(DEFAULT_CRUSHER_CONFIG.firstFraction).toBe(0.3);
+    expect(DEFAULT_CRUSHER_CONFIG.lastFraction).toBe(0.15);
+    expect(DEFAULT_CRUSHER_CONFIG.losslessMinSavingsRatio).toBe(0.15);
+    expect(DEFAULT_CRUSHER_CONFIG.compactionCoreFieldFraction).toBe(0.8);
+  });
+
+  it('allows config override via constructor', () => {
+    const custom = new SmartCrusher({ maxItemsAfterCrush: 5 });
+    // 8-item sparse array should now trigger lossy (>5) when lossless fails
+    const pad = 'x'.repeat(300);
+    const arr = Array.from({ length: 8 }, (_, i) => {
+      const o = { id: `x-${i}` };
+      if (i % 2 === 0) o.extra = `val_${i}_${pad}`;
+      return o;
+    });
+    const input = JSON.stringify(arr);
+    const result = custom.compress(input, new CcrStore(10));
+    // With maxItemsAfterCrush=5, 8 items should trigger lossy if lossless fails
+    if (result.compressed) {
+      expect(['lossless-csv', 'lossy-sample']).toContain(result.strategy);
+    }
+  });
+});

package/lib/compression/dist/server.js

@@ -150,9 +150,21 @@ async function handleDirectCompress(req, res) {
     const messages = body.messages;
     if (!Array.isArray(messages)) {
         stats.requests.passthrough++;
-        json(res, 200, { messages: body, tokensSaved: 0, compressionRatio: 1, transformsApplied: [], ccrHashes: [] });
+        // Passthrough — return both camelCase and snake_case for SDK compatibility
+        json(res, 200, {
+            messages: body,
+            // camelCase (direct-HTTP callers: context-compaction.ts, hema-dispatch-v3)
+            tokensSaved: 0, compressionRatio: 1, transformsApplied: [], ccrHashes: [],
+            // snake_case (headroom-ai SDK _doCompress reads data.tokens_saved etc.)
+            tokens_before: 0, tokens_after: 0, tokens_saved: 0,
+            compression_ratio: 1, transforms_applied: [], ccr_hashes: [],
+            compressed: false,
+        });
         return;
     }
+    // Estimate tokens_before from raw input length (same heuristic as ContentRouter: 3.5 chars/token)
+    const CHARS_PER_TOKEN = 3.5;
+    const tokensBefore = Math.ceil(JSON.stringify(messages).length / CHARS_PER_TOKEN);
     try {
         const result = pipeline.compress(messages, ccrStore);
         stats.tokens.saved += result.tokensSaved;
@@ -162,12 +174,33 @@ async function handleDirectCompress(req, res) {
             stats.requests.compressed++;
         else
             stats.requests.passthrough++;
+        const tokensAfter = Math.max(0, tokensBefore - result.tokensSaved);
+        const wasCompressed = result.transformsApplied.length > 0;
         json(res, 200, {
             messages: result.messages,
+            // ── camelCase fields ──────────────────────────────────────────────────
+            // Used by direct-HTTP callers: context-compaction.ts (applyHeadroomCompression),
+            // hema-dispatch-v3 (recall compress), helios-api (HBO response wrap).
+            // These callers read result.tokensSaved, result.compressionRatio, etc.
             tokensSaved: result.tokensSaved,
             compressionRatio: result.compressionRatio,
             transformsApplied: result.transformsApplied,
             ccrHashes: result.ccrHashes,
+            // ── snake_case fields ─────────────────────────────────────────────────
+            // Required by headroom-ai SDK v0.22.4 _doCompress():
+            //   data.tokens_before, data.tokens_after, data.tokens_saved,
+            //   data.compression_ratio, data.transforms_applied, data.ccr_hashes
+            // Used by SharedContext.put() to compute entry.savingsPercent and
+            // to set entry.compressed = true so the compressed content is stored.
+            tokens_before: tokensBefore,
+            tokens_after: tokensAfter,
+            tokens_saved: result.tokensSaved,
+            compression_ratio: result.compressionRatio,
+            transforms_applied: result.transformsApplied,
+            ccr_hashes: result.ccrHashes,
+            // compressed: true triggers SharedContext to store result.messages[0].content
+            // instead of falling back to the original uncompressed content.
+            compressed: wasCompressed,
         });
     }
     catch (e) {

package/lib/compression/dist/start-server.js

@@ -0,0 +1,77 @@
+'use strict';
+/**
+ * lib/compression/dist/start-server.js
+ *
+ * Standalone entry point for the Helios Compression Server.
+ * Used by:
+ *   - evals/harbor/test_compression.py (pytest fixture spawns this directly)
+ *   - Manual testing: node lib/compression/dist/start-server.js [--port <n>]
+ *   - npm run test:compression
+ *
+ * The daemon uses server.js via HeadroomProxyManager (daemon/lib/headroom-proxy-manager.js),
+ * which spawns server.js directly. This file is the test-friendly wrapper.
+ *
+ * On ready: emits {"event":"ready","port":<n>,"version":"1.0.0-helios"} to stdout.
+ * On EADDRINUSE: logs to stderr and exits with code 1.
+ * Responds to SIGTERM/SIGINT with graceful shutdown (not available on Windows — falls back).
+ *
+ * Cross-platform: no shell, no signal assumptions beyond try/catch.
+ */
+
+const { createCompressionServer } = require('./server.js');
+
+// ── Port resolution ───────────────────────────────────────────────────────────
+// Priority: --port <n> CLI arg > HEADROOM_PORT env > 8787 default
+
+function resolvePort() {
+  const args = process.argv.slice(2);
+  const portFlagIdx = args.indexOf('--port');
+  if (portFlagIdx !== -1 && args[portFlagIdx + 1]) {
+    const parsed = parseInt(args[portFlagIdx + 1], 10);
+    if (!isNaN(parsed) && parsed > 0 && parsed < 65536) return parsed;
+  }
+  if (process.env.HEADROOM_PORT) {
+    const parsed = parseInt(process.env.HEADROOM_PORT, 10);
+    if (!isNaN(parsed) && parsed > 0 && parsed < 65536) return parsed;
+  }
+  return 8787;
+}
+
+const port = resolvePort();
+const VERSION = '1.0.0-helios';
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+const server = createCompressionServer();
+
+server.listen(port, '127.0.0.1', () => {
+  // Emit the ready signal that HeadroomProxyManager and the test fixture parse
+  process.stdout.write(JSON.stringify({ event: 'ready', port, version: VERSION }) + '\n');
+});
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    process.stderr.write(
+      `[compression-server] Port ${port} already in use. ` +
+      `Use --port <n> or set HEADROOM_PORT env var.\n`
+    );
+    process.exit(1);
+  }
+  // Other errors — re-throw to get a full stack trace
+  throw err;
+});
+
+// ── Graceful shutdown ─────────────────────────────────────────────────────────
+// SIGTERM and SIGINT not available on Windows — wrap in try.
+
+function shutdown(signal) {
+  process.stderr.write(`[compression-server] Received ${signal}, shutting down...\n`);
+  server.close(() => {
+    process.exit(0);
+  });
+  // Force exit after 3s if connections are held open
+  setTimeout(() => process.exit(0), 3000).unref();
+}
+
+try { process.on('SIGTERM', () => shutdown('SIGTERM')); } catch (_) {}
+try { process.on('SIGINT',  () => shutdown('SIGINT'));  } catch (_) {}

package/lib/graph/learning/headroom-learn-bridge.js

@@ -0,0 +1,175 @@
+'use strict';
+/**
+ * lib/graph/learning/headroom-learn-bridge.js
+ *
+ * Post-RETROSPECTIVE learning bridge: mines session compression stats and
+ * tool-call failure patterns, then writes structured knowledge to Memgraph.
+ *
+ * Called from lib/mission-loop/phase-handlers/retrospective.ts (fire-and-forget):
+ *   const { runBridge } = require('../../graph/learning/headroom-learn-bridge');
+ *   await runBridge(safeWrite, sessionId, missionRunId);
+ *
+ * Interface:
+ *   runBridge(safeWrite, sessionId, missionRunId): Promise<void>
+ *     safeWrite: (cypher: string, params?: object) => Promise<void>
+ *     sessionId: string
+ *     missionRunId: string
+ *     Returns: void — never throws, fully fail-open
+ *
+ * Memgraph writes:
+ *   - HeadroomSession node (tracks per-session compression stats)
+ *   - KnowledgeAsset nodes (one per unique tool-failure pattern found)
+ *
+ * Debounce: 5 minutes per sessionId — prevents multiple RETROSPECTIVE calls
+ * within the same session from firing duplicate writes.
+ *
+ * No hardcoded company IDs. companyId is derived from sessionId prefix if
+ * available (format: "<companyId>__<sessionSuffix>"), else 'unknown'.
+ *
+ * Cross-platform: os.homedir(), path.join() throughout.
+ */
+
+const os   = require('os');
+const path = require('path');
+const fs   = require('fs');
+
+// ── Debounce ──────────────────────────────────────────────────────────────────
+// Map<sessionId, lastRunMs>
+const _lastRun = new Map();
+const DEBOUNCE_MS = 5 * 60 * 1000; // 5 minutes
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Derive companyId from sessionId.
+ * Convention in helios-agent: sessionId may be prefixed as "pi__<suffix>" or
+ * "<companyId>__<suffix>". If no __ separator found, returns 'unknown'.
+ */
+function deriveCompanyId(sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') return 'unknown';
+  // Skip the standard pi__ prefix — that's not a companyId
+  if (sessionId.startsWith('pi__')) return 'unknown';
+  const sep = sessionId.indexOf('__');
+  if (sep > 0) return sessionId.substring(0, sep);
+  return 'unknown';
+}
+
+/**
+ * Read tool-failure patterns from HELIOS_SESSION_TOOL_FAILURES env var.
+ * The env var is expected to be a JSON array of { toolName, errorClass } objects,
+ * set by the daemon before spawning Pi. Returns [] if absent or unparseable.
+ */
+function readToolFailures() {
+  try {
+    const raw = process.env.HELIOS_SESSION_TOOL_FAILURES;
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (f) => f && typeof f.toolName === 'string' && typeof f.errorClass === 'string'
+    );
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Write a HeadroomSession node to Memgraph.
+ * Non-fatal: resolves even if safeWrite rejects.
+ */
+async function writeHeadroomSession(safeWrite, sessionId, missionRunId) {
+  const companyId = deriveCompanyId(sessionId);
+  const cypher = `
+    MERGE (hs:HeadroomSession {sessionId: $sessionId})
+    SET hs.missionRunId = $missionRunId,
+        hs.companyId    = $companyId,
+        hs.updatedAt    = localdatetime()
+  `;
+  try {
+    await safeWrite(cypher, { sessionId, missionRunId, companyId });
+  } catch (e) {
+    process.stderr.write(`[headroom-learn-bridge] HeadroomSession write failed (non-fatal): ${e && e.message}\n`);
+  }
+}
+
+/**
+ * Write KnowledgeAsset nodes for each unique tool-failure pattern.
+ * Non-fatal per write.
+ */
+async function writeKnowledgeAssets(safeWrite, failures, sessionId) {
+  if (!failures || failures.length === 0) return;
+
+  // Deduplicate by toolName+errorClass
+  const seen = new Set();
+  const unique = failures.filter((f) => {
+    const key = `${f.toolName}::${f.errorClass}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  for (const failure of unique) {
+    const assetId = `hroom-${Buffer.from(`${sessionId}:${failure.toolName}:${failure.errorClass}`).toString('base64').replace(/[^a-z0-9]/gi, '').slice(0, 32)}`;
+    const cypher = `
+      MERGE (ka:KnowledgeAsset {id: $assetId})
+      SET ka.source      = 'headroom-learn-bridge',
+          ka.type        = 'tool_failure_pattern',
+          ka.toolName    = $toolName,
+          ka.errorClass  = $errorClass,
+          ka.sessionId   = $sessionId,
+          ka.updatedAt   = localdatetime()
+    `;
+    try {
+      await safeWrite(cypher, {
+        assetId,
+        toolName   : failure.toolName,
+        errorClass : failure.errorClass,
+        sessionId,
+      });
+    } catch (e) {
+      process.stderr.write(`[headroom-learn-bridge] KnowledgeAsset write failed (non-fatal): ${e && e.message}\n`);
+    }
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Run the headroom learn bridge for a completed RETROSPECTIVE phase.
+ *
+ * @param {Function} safeWrite  Memgraph writer: (cypher, params?) => Promise<void>
+ * @param {string}   sessionId  Current session ID
+ * @param {string}   missionRunId  Current mission run ID
+ * @returns {Promise<void>}  Always resolves — never rejects
+ */
+async function runBridge(safeWrite, sessionId, missionRunId) {
+  try {
+    // Debounce: skip if we ran within the last 5 minutes for this session
+    const lastRun = _lastRun.get(sessionId);
+    if (lastRun && Date.now() - lastRun < DEBOUNCE_MS) {
+      process.stderr.write(
+        `[headroom-learn-bridge] Debounced for session ${sessionId} ` +
+        `(${Math.round((Date.now() - lastRun) / 1000)}s since last run)\n`
+      );
+      return;
+    }
+    _lastRun.set(sessionId, Date.now());
+
+    // Run both writes in parallel — independent of each other
+    const failures = readToolFailures();
+    await Promise.all([
+      writeHeadroomSession(safeWrite, sessionId, missionRunId),
+      writeKnowledgeAssets(safeWrite, failures, sessionId),
+    ]);
+
+    process.stderr.write(
+      `[headroom-learn-bridge] Completed for session=${sessionId} ` +
+      `missionRunId=${missionRunId} failures=${failures.length}\n`
+    );
+  } catch (e) {
+    // Top-level catch: bridge is fully non-fatal
+    process.stderr.write(`[headroom-learn-bridge] Unexpected error (non-fatal): ${e && e.message}\n`);
+  }
+}
+
+module.exports = { runBridge };

package/lib/hbo-core-store.ts

@@ -285,6 +285,24 @@ function initSchema(db: any): void {
       data_json           TEXT
     );
     CREATE INDEX IF NOT EXISTS idx_routines_company_status ON routines(company_id, status);
+
+    CREATE TABLE IF NOT EXISTS comments (
+      id            TEXT    PRIMARY KEY,
+      task_id       TEXT,
+      approval_id   TEXT,
+      company_id    TEXT    NOT NULL,
+      body          TEXT    NOT NULL,
+      author_type   TEXT    DEFAULT 'user',
+      author_id     TEXT,
+      presentation_kind TEXT,
+      presentation_tone TEXT,
+      sync_status   TEXT    DEFAULT 'pending',
+      created_at    INTEGER,
+      data_json     TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_comments_task ON comments(task_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_comments_approval ON comments(approval_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_comments_sync ON comments(company_id, sync_status);
   `);
 
   // H-7 migration: add created_at column to existing goals tables that predate this commit.
@@ -327,6 +345,9 @@ const _SQLITE_COLUMN_KEYS = new Set([
   // routines
   'agent_id', 'cron_expr', 'concurrency_policy', 'catch_up_policy', 'catch_up_cap',
   'next_run_at', 'last_run_at',
+  // comments (P8C-09)
+  'task_id', 'approval_id', 'author_type', 'author_id',
+  'presentation_kind', 'presentation_tone', 'sync_status',
 ]);
 
 function _stripSqliteCols(obj: Record<string, any>): Record<string, any> {
@@ -793,6 +814,56 @@ export function updateRoutine(id: string, companyId: string, update: Record<stri
   upsertRoutine({ ...cleanExisting, ...update, id, company_id: companyId, updated_at: Date.now() });
 }
 
+// ---------------------------------------------------------------------------
+// Comments (P8C-09: offline queue for task + approval comments)
+// ---------------------------------------------------------------------------
+
+export function createComment(comment: Record<string, any>): void {
+  const companyId = comment.company_id ?? comment.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] createComment: company_id is required`);
+  const db = getDb();
+  const now = Date.now();
+  db.prepare(`
+    INSERT OR REPLACE INTO comments
+      (id, task_id, approval_id, company_id, body, author_type, author_id,
+       presentation_kind, presentation_tone, sync_status, created_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    comment.id,
+    comment.task_id ?? comment.taskId ?? null,
+    comment.approval_id ?? comment.approvalId ?? null,
+    companyId,
+    comment.body ?? '',
+    comment.author_type ?? comment.authorType ?? 'user',
+    comment.author_id ?? comment.authorId ?? null,
+    comment.presentation_kind ?? comment.presentationKind ?? null,
+    comment.presentation_tone ?? comment.presentationTone ?? null,
+    comment.sync_status ?? comment.syncStatus ?? 'pending',
+    comment.created_at ?? comment.createdAt ?? now,
+    JSON.stringify(comment),
+  );
+}
+
+export function getCommentsByTask(taskId: string, companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare('SELECT * FROM comments WHERE task_id = ? AND company_id = ? ORDER BY created_at ASC').all(taskId, companyId) as any[]).map(_mergeRow);
+}
+
+export function getCommentsByApproval(approvalId: string, companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare('SELECT * FROM comments WHERE approval_id = ? AND company_id = ? ORDER BY created_at ASC').all(approvalId, companyId) as any[]).map(_mergeRow);
+}
+
+export function getPendingComments(companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare("SELECT * FROM comments WHERE company_id = ? AND sync_status = 'pending' ORDER BY created_at ASC").all(companyId) as any[]).map(_mergeRow);
+}
+
+export function markCommentSynced(id: string): void {
+  const db = getDb();
+  db.prepare("UPDATE comments SET sync_status = 'synced' WHERE id = ?").run(id);
+}
+
 // ---------------------------------------------------------------------------
 // Leads
 // ---------------------------------------------------------------------------