@cgh567/agent 2.4.2 → 2.4.4

package/daemon/lib/harada/cascade-judge.js

@@ -390,6 +390,35 @@ Market benchmarks: ${benchmarks}`;
 
     this._log(`[CascadeJudge] L2 verdict for pillar ${pillarId}: ${verdict}${critique ? ' — ' + critique : ''}`);
 
+    // T3-06: On PASS, dispatch L3 research for all unreviewed ActionCells in this pillar.
+    if (verdict === 'pass') {
+      setImmediate(async () => {
+        try {
+          const cells = await this._mg(
+            `MATCH (ac:ActionCell {pillarId: $pillarId, companyId: $cid})
+             WHERE ac.l3ReviewStatus IS NULL OR ac.l3ReviewStatus = ''
+             RETURN ac.id AS id, ac.agentId AS agentId
+             LIMIT 8`,
+            { pillarId, cid: this._companyId }
+          ).catch(() => null);
+          if (!cells?.rows?.length) return;
+          const { CascadeResearchDispatcher } = require('./cascade-research-dispatcher');
+          const crd = new CascadeResearchDispatcher(this._mg.bind(this), this._companyId);
+          for (const cr of cells.rows) {
+            const cellId = cr[0] ?? cr['id'];
+            const cellAgentId = cr[1] ?? cr['agentId'];
+            if (!cellId) continue;
+            await crd.dispatchL3Research(cellId, pillarId, this._companyId, cellAgentId || null).catch(e =>
+              this._log(`[CascadeJudge] T3-06: L3 dispatch failed for cell ${cellId}: ${e && e.message || e}`)
+            );
+          }
+          this._log(`[CascadeJudge] T3-06: dispatched L3 research for ${cells.rows.length} ActionCells of pillar ${pillarId}`);
+        } catch (t3Err) {
+          this._log(`[CascadeJudge] T3-06: L3 dispatch error: ${t3Err && t3Err.message || t3Err}`);
+        }
+      });
+    }
+
     // 7/9. Return verdict — caller dispatches L3 (pass) or revised L2 (fail)
     return { verdict, criteriaResults, critique };
     } catch (err) {
@@ -607,12 +636,66 @@ Sub-agent execution plan: ${l3Content}`;
 
     this._log(`[CascadeJudge] L3 verdict for cell ${cellId}: ${verdict}${critique ? ' — ' + critique : ''}`);
 
-    return { verdict, criteriaResults, critique };
+     return { verdict, criteriaResults, critique };
     } catch (err) {
       this._log(`[CascadeJudge] judgeL3 error for cell ${cellId}: ${err && err.message || err}`);
       throw err;
     }
   }
+
+  /**
+   * T3-04: Bulk scan — judge all GoalPillar nodes with l2ReviewStatus='pending_review'.
+   * Called every 5 ticks from helios-company-daemon.js tick loop.
+   * Processes up to 5 pillars per tick to avoid blocking.
+   */
+  async judgeReadyPillars() {
+    const cid = this._companyId;
+    try {
+      const result = await this._mg(
+        `MATCH (gp:GoalPillar {companyId: $cid})
+         WHERE gp.l2ReviewStatus = 'pending_review'
+         RETURN gp.id AS id
+         LIMIT 5`,
+        { cid }
+      ).catch(() => null);
+      for (const row of (result?.rows ?? [])) {
+        const pillarId = row[0] ?? row['id'];
+        if (!pillarId) continue;
+        await this.judgeL2(pillarId).catch(e =>
+          this._log(`[CascadeJudge] judgeReadyPillars: judgeL2 failed for ${pillarId}: ${e && e.message || e}`)
+        );
+      }
+    } catch (err) {
+      this._log(`[CascadeJudge] judgeReadyPillars error: ${err && err.message || err}`);
+    }
+  }
+
+  /**
+   * T3-04: Bulk scan — judge all ActionCell nodes with l3ReviewStatus='pending_review'.
+   * Called every 5 ticks from helios-company-daemon.js tick loop.
+   * Processes up to 5 cells per tick to avoid blocking.
+   */
+  async judgeReadyActionCells() {
+    const cid = this._companyId;
+    try {
+      const result = await this._mg(
+        `MATCH (ac:ActionCell {companyId: $cid})
+         WHERE ac.l3ReviewStatus = 'pending_review'
+         RETURN ac.id AS id
+         LIMIT 5`,
+        { cid }
+      ).catch(() => null);
+      for (const row of (result?.rows ?? [])) {
+        const cellId = row[0] ?? row['id'];
+        if (!cellId) continue;
+        await this.judgeL3(cellId).catch(e =>
+          this._log(`[CascadeJudge] judgeReadyActionCells: judgeL3 failed for ${cellId}: ${e && e.message || e}`)
+        );
+      }
+    } catch (err) {
+      this._log(`[CascadeJudge] judgeReadyActionCells error: ${err && err.message || err}`);
+    }
+  }
 }
 
 module.exports = { CascadeJudge };

package/daemon/lib/harada/cascade-research-dispatcher.js

@@ -0,0 +1,282 @@
+'use strict';
+/**
+ * cascade-research-dispatcher.js — Dispatches L2 and L3 research tasks
+ * for the Hoshin Kanri cascade with full parent context in the task body.
+ *
+ * L2: Dept head agent receives company goal + GoalResearchBrief + pillar domain
+ * L3: Sub-agent receives pillar L2 content + action cell description
+ */
+
+class CascadeResearchDispatcher {
+  /**
+   * @param {Function} mgQuery   - (cypher, params) => Promise<result>
+   * @param {string}   companyId - Company identifier
+   * @param {Function} [log]     - Optional logger function
+   */
+  constructor(mgQuery, companyId, log) {
+    this._mg        = mgQuery;
+    this._companyId = companyId;
+    this._log       = log || (() => {});
+  }
+
+  // ── L2 Research Dispatch ──────────────────────────────────────────────────
+
+  /**
+   * Dispatch a harada_l2_research task to the dept head agent for a pillar.
+   *
+   * @param {string}  pillarId         - GoalPillar node id
+   * @param {string}  goalId           - CompanyGoal node id
+   * @param {string}  companyId        - Company identifier (overrides constructor value if provided)
+   * @param {string}  agentId          - Assignee agent id
+   * @param {string}  [l2ReviewCritique] - Previous CEO critique (for revision cycles)
+   * @returns {{ taskId: string, agentId: string }}
+   */
+  async dispatchL2Research(pillarId, goalId, companyId, agentId, l2ReviewCritique) {
+    const cid = companyId || this._companyId;
+
+    // 1. Fetch GoalPillar name, GoalResearchBrief, and CompanyGoal
+    const contextRows = await this._mg(
+      `MATCH (p:GoalPillar {id: $pillarId})
+       OPTIONAL MATCH (g:CompanyGoal {id: $goalId})
+       OPTIONAL MATCH (grb:GoalResearchBrief {companyId: $cid})
+         WHERE grb.goalId = $goalId OR grb.id STARTS WITH ('grb:' + $goalId)
+       RETURN
+         p.name            AS pillarName,
+         g.title           AS goalTitle,
+         g.description     AS goalDescription,
+         grb.tournamentWinner AS tournamentWinner,
+         grb.marketContext    AS marketContext,
+         grb.benchmarks       AS benchmarks,
+         grb.crmContext       AS crmContext
+       LIMIT 1`,
+      { pillarId, goalId, cid }
+    );
+
+    const row = contextRows && contextRows.rows && contextRows.rows[0]
+      ? (Array.isArray(contextRows.rows[0])
+          ? {
+              pillarName:       contextRows.rows[0][0],
+              goalTitle:        contextRows.rows[0][1],
+              goalDescription:  contextRows.rows[0][2],
+              tournamentWinner: contextRows.rows[0][3],
+              marketContext:    contextRows.rows[0][4],
+              benchmarks:       contextRows.rows[0][5],
+              crmContext:       contextRows.rows[0][6],
+            }
+          : contextRows.rows[0])
+      : {};
+
+    const pillarName       = row.pillarName       || pillarId;
+    const goalTitle        = row.goalTitle        || 'Company Goal';
+    const goalDescription  = row.goalDescription  || '';
+    const tournamentWinner = row.tournamentWinner  || 'TBD';
+    const marketContext    = row.marketContext     || 'Not available';
+    const benchmarks       = row.benchmarks       || 'Not available';
+    const crmContext       = row.crmContext        || 'Not available';
+
+    // 2. Build task body
+    const previousCritiqueSection = l2ReviewCritique
+      ? `\nPrevious CEO critique: ${l2ReviewCritique}`
+      : '';
+
+    const taskBody = `Goal: ${goalTitle}
+Description: ${goalDescription}
+Research Brief Summary: ${marketContext} | Tournament winner: ${tournamentWinner}
+Benchmarks: ${benchmarks}
+CRM context: ${crmContext}
+Your pillar: ${pillarName} (id: ${pillarId})
+Your role: ${pillarName} execution lead
+
+Research your pillar domain using web search and your available tools.
+Produce:
+1. A 50-word purpose statement for this pillar
+2. A strategy label (≤20 chars) matching or improving on the tournament winner
+3. 3 key actions this pillar should execute
+
+When complete, update pillar content by calling:
+  POST /api/hbo/pillar/${pillarId}/l2content
+  Body: { content: string, strategy: string, keyActions: string[] }
+${previousCritiqueSection}`;
+
+    const taskId = `harada-l2:${pillarId}`;
+
+    // 3. MERGE Task
+    await this._mg(
+      `MERGE (t:Task {id: $taskId, companyId: $cid})
+       ON CREATE SET
+         t.originKind      = $originKind,
+         t.assigneeAgentId = $agentId,
+         t.status          = 'todo',
+         t.priority        = 1,
+         t.body            = $body,
+         t.createdAt       = datetime()
+       ON MATCH SET
+         t.body            = $body,
+         t.status          = 'todo',
+         t.updatedAt       = datetime()`,
+      {
+        taskId,
+        cid,
+        originKind: 'harada_l2_research',
+        agentId,
+        body: taskBody,
+      }
+    );
+
+    // 4. Create AgentReadySignal
+    const arsId = `ars:harada-l2:${pillarId}`;
+    await this._mg(
+      `MERGE (s:AgentReadySignal {id: $arsId, companyId: $cid})
+       ON CREATE SET
+         s.agentId   = $agentId,
+         s.status    = 'pending',
+         s.createdAt = datetime()
+       ON MATCH SET
+         s.status    = 'pending',
+         s.updatedAt = datetime()`,
+      { arsId, cid, agentId }
+    );
+
+    this._log(`[CascadeResearchDispatcher] Dispatched L2 research task ${taskId} to agent ${agentId}`);
+
+    // 5. Return
+    return { taskId, agentId };
+  }
+
+  // ── L3 Research Dispatch ──────────────────────────────────────────────────
+
+  /**
+   * Dispatch a harada_l3_research task to a sub-agent for an action cell.
+   *
+   * @param {string}  cellId           - ActionCell node id
+   * @param {string}  pillarId         - Parent GoalPillar node id
+   * @param {string}  companyId        - Company identifier (overrides constructor value if provided)
+   * @param {string}  agentId          - Assignee agent id
+   * @param {string}  [l3ReviewCritique] - Previous dept head critique (for revision cycles)
+   * @returns {{ taskId: string, agentId: string }}
+   */
+  async dispatchL3Research(cellId, pillarId, companyId, agentId, l3ReviewCritique) {
+    const cid = companyId || this._companyId;
+
+    // 1. Fetch ActionCell description, GoalPillar l2Content, l2Strategy, pillar name
+    //    and goal info via the pillar
+    const contextRows = await this._mg(
+      `MATCH (p:GoalPillar {id: $pillarId})
+       OPTIONAL MATCH (c:ActionCell {id: $cellId})
+       OPTIONAL MATCH (g:CompanyGoal)-[:HAS_PILLAR]->(p)
+       RETURN
+         c.description AS cellDescription,
+         p.name        AS pillarName,
+         p.l2Content   AS l2Content,
+         p.l2Strategy  AS l2Strategy,
+         g.title       AS goalTitle
+       LIMIT 1`,
+      { cellId, pillarId }
+    );
+
+    const row = contextRows && contextRows.rows && contextRows.rows[0]
+      ? (Array.isArray(contextRows.rows[0])
+          ? {
+              cellDescription: contextRows.rows[0][0],
+              pillarName:      contextRows.rows[0][1],
+              l2Content:       contextRows.rows[0][2],
+              l2Strategy:      contextRows.rows[0][3],
+              goalTitle:       contextRows.rows[0][4],
+            }
+          : contextRows.rows[0])
+      : {};
+
+    const cellDescription = row.cellDescription || cellId;
+    const pillarName      = row.pillarName       || pillarId;
+    const l2Content       = row.l2Content        || '';
+    const l2Strategy      = row.l2Strategy       || '';
+    const goalTitle       = row.goalTitle        || 'Company Goal';
+
+    // 2. Build task body
+    const previousCritiqueSection = l3ReviewCritique
+      ? `\nPrevious dept head critique: ${l3ReviewCritique}`
+      : '';
+
+    const taskBody = `Goal: ${goalTitle}
+Pillar: ${pillarName}
+Pillar strategy: ${l2Strategy}
+Pillar purpose: ${l2Content}
+
+Your action cell: ${cellDescription} (id: ${cellId})
+
+Research this specific action cell using available tools.
+Produce a specific execution plan (≤100 words) for this action.
+
+When complete, update by calling:
+  POST /api/hbo/actioncell/${cellId}/l3content
+  Body: { content: string }
+${previousCritiqueSection}`;
+
+    const taskId = `harada-l3:${cellId}`;
+
+    // 3. MERGE Task
+    await this._mg(
+      `MERGE (t:Task {id: $taskId, companyId: $cid})
+       ON CREATE SET
+         t.originKind      = $originKind,
+         t.assigneeAgentId = $agentId,
+         t.status          = 'todo',
+         t.priority        = 1,
+         t.body            = $body,
+         t.createdAt       = datetime()
+       ON MATCH SET
+         t.body            = $body,
+         t.status          = 'todo',
+         t.updatedAt       = datetime()`,
+      {
+        taskId,
+        cid,
+        originKind: 'harada_l3_research',
+        agentId,
+        body: taskBody,
+      }
+    );
+
+    // 4. Create AgentReadySignal
+    const arsId = `ars:harada-l3:${cellId}`;
+    await this._mg(
+      `MERGE (s:AgentReadySignal {id: $arsId, companyId: $cid})
+       ON CREATE SET
+         s.agentId   = $agentId,
+         s.status    = 'pending',
+         s.createdAt = datetime()
+       ON MATCH SET
+         s.status    = 'pending',
+         s.updatedAt = datetime()`,
+      { arsId, cid, agentId }
+    );
+
+    this._log(`[CascadeResearchDispatcher] Dispatched L3 research task ${taskId} to agent ${agentId}`);
+
+    // P_EXPLAIN-01: Post a Three Cs interpretation block as a Comment on the task
+    // so the user immediately sees what Helios understood this action cell to mean.
+    // Fire-and-forget (non-blocking, errors are silently swallowed).
+    setImmediate(async () => {
+      try {
+        const commentId = `comment:interp:${taskId}`;
+        const interpretationBody = '```interpretation\n' + JSON.stringify({
+          stated: cellDescription,
+          inferred: `Execute action cell "${cellDescription}" as part of the "${pillarName}" pillar strategy: ${l2Strategy || '(pending L2 review)'}`,
+          defaulted: 'Harada L3 research task — produce ≤100 word execution plan',
+          confidence: 0.75,
+        }) + '\n```';
+        await this._mg(
+          `MERGE (c:Comment {id: $commentId, companyId: $cid})
+           ON CREATE SET c.taskId=$taskId, c.body=$body, c.authorType='system',
+             c.createdAt=datetime(), c.kind='interpretation'`,
+          { commentId, cid, taskId, body: interpretationBody }
+        );
+      } catch (_) {}
+    });
+
+    // 5. Return
+    return { taskId, agentId };
+  }
+}
+
+module.exports = { CascadeResearchDispatcher };

package/daemon/lib/harada/pillar-dispatcher.js

@@ -20,9 +20,10 @@
 // Load the async tournament runner — the sync runTournament export was deprecated
 // and is now a no-op stub. All callers must use runTournamentAsync which delegates
 // to tournament-node-runner.js (cross-platform: Windows, macOS, Linux).
+// Path: from daemon/lib/harada/ → ../../../ reaches project root → lib/triage-core/
 let runTournamentAsync = null;
 try {
-  const tr = require('../../lib/triage-core/tournament-runner.js');
+  const tr = require('../../../lib/triage-core/tournament-runner.js');
   runTournamentAsync = tr.runTournamentAsync || null;
   if (!runTournamentAsync) {
     process.stderr.write('[pillar-dispatcher] WARN: tournament-runner.js loaded but runTournamentAsync not exported — pillar strategy selection will use unranked first candidate\n');
@@ -381,6 +382,26 @@ class PillarDispatcher {
     // Wire first open ActionCell to this task
     await this._assignFirstOpenCell(pillar.id, agentId);
 
+    // P_EXPLAIN-02: Post a Three Cs interpretation block as a Comment on the L2 pillar task
+    // so the user immediately sees what Helios understood about this strategic dispatch.
+    setImmediate(async () => {
+      try {
+        const commentId = `comment:interp:${taskId}`;
+        const interpretationBody = '```interpretation\n' + JSON.stringify({
+          stated: `Execute pillar: ${pillar.name}`,
+          inferred: `Implement the "${strategy.label}" strategy for pillar "${pillar.name}" by working with your assigned action cells and reporting progress via POST /api/hbo/pillar/${pillar.id}/l2content`,
+          defaulted: 'Harada L2 pillar dispatch — strategic execution, workType=strategic',
+          confidence: 0.85,
+        }) + '\n```';
+        await this._mg(
+          `MERGE (c:Comment {id: $commentId, companyId: $cid})
+           ON CREATE SET c.taskId=$taskId, c.body=$body, c.authorType='system',
+             c.createdAt=datetime(), c.kind='interpretation'`,
+          { commentId, cid: companyId, taskId, body: interpretationBody }
+        );
+      } catch (_) {}
+    });
+
     this._log('info', `PillarDispatcher: dispatched "${pillar.name}" → ${agentId} [${strategy.label}]`);
   }
 
@@ -455,7 +476,7 @@ class PillarDispatcher {
       }
     } else {
       // Tournament runner was not loaded — this means pillar strategy selection is
-      // operating blind. Log at 'warn' (not 'debug') so operators see this in production.
+      // operating blind. Log at 'warn' so operators see this in production.
       this._log('warn', `PillarDispatcher: tournament runner unavailable for "${pillar.name}" — strategy selection will use first candidate (unranked). Check tournament-runner.js installation.`);
     }
 

package/daemon/lib/hbo-bridge.js

@@ -74,6 +74,48 @@ function loadService(varRef, relPath) {
 
 const MAX_TOURNAMENT_QUEUE = 50; // L1: module-level constant
 
+/**
+ * _rankingsToPillars(rankingsJson) — converts GoalResearchBrief tournament rankings
+ * into { name, rationale, weight }[] for MandalaManager.initializeMandala().
+ *
+ * Weight allocation: proportional to TrueSkill conservativeScore when available,
+ * otherwise equal-weight with remainder added to rank-1 entry.
+ * Enforces sum=1.0 ± 0.001 tolerance.
+ */
+function _rankingsToPillars(rankingsJson) {
+  if (!rankingsJson) return null;
+  let rankings;
+  try { rankings = typeof rankingsJson === 'string' ? JSON.parse(rankingsJson) : rankingsJson; }
+  catch { return null; }
+  if (!Array.isArray(rankings) || rankings.length === 0) return null;
+
+  const n = rankings.length;
+  let weights;
+  if (rankings[0] && typeof rankings[0].conservativeScore === 'number') {
+    // TrueSkill-proportional weights
+    const total = rankings.reduce((s, r) => s + Math.max(0, r.conservativeScore), 0);
+    if (total > 0) {
+      weights = rankings.map(r => Math.round(Math.max(0, r.conservativeScore) / total * 10000) / 10000);
+    }
+  }
+  if (!weights) {
+    // Equal weights
+    const base = Math.round(10000 / n) / 10000;
+    weights = Array(n).fill(base);
+  }
+  // Normalize floating-point drift
+  const sum = weights.reduce((s, w) => s + w, 0);
+  if (Math.abs(sum - 1.0) > 0.001) {
+    weights[0] += (1.0 - sum);
+    weights[0] = Math.round(weights[0] * 10000) / 10000;
+  }
+  return rankings.map((r, i) => ({
+    name: r.pillarName || r.name || `Pillar ${i + 1}`,
+    rationale: r.rationale || r.description || '',
+    weight: weights[i],
+  }));
+}
+
 // ── HBO Bridge ─────────────────────────────────────────────────────────────────
 
 class HBOBridge {
@@ -685,13 +727,11 @@ class HBOBridge {
       }
 
       this._log('debug', `tickBudgetSync: synced ${spendRows.rows.length} agent(s) spend data`);
-    } catch (e) {
+     } catch (e) {
       this._log('warn', `tickBudgetSync error (non-fatal): ${e.message}`);
     }
   }
 
-  // ── tickGoalDecompose ──────────────────────────────────────────────────────
-
   /**
    * Runs every 5 ticks (same cadence as tickGoalSync).
    * Detects CompanyGoal nodes that have status='active' but no child
@@ -737,7 +777,7 @@ class HBOBridge {
       // Find active goals (CompanyGoal OR BusinessGoal) with no child BusinessTasks
       // and no existing decomposition task (checked by deterministic MERGE on t.id).
       // CompanyGoal: created by seed-company.js at startup
-      // BusinessGoal: created via POST /api/hbo/goals or business-goal-service.js
+      // BusinessGoal: created via POST /api/hbo/goals or the wizard's write-through goal path
       const undecomposed = await this._mg(
         `MATCH (g)
          WHERE (g:CompanyGoal OR g:BusinessGoal)
@@ -780,7 +820,21 @@ class HBOBridge {
         try {
           const { MandalaManager } = require('./harada/mandala');
           const mandala = new MandalaManager(this._mg.bind(this), this._companyId);
-          await mandala.initializeMandala(goalId, goalTitle, null);
+          // GoalResearchBrief: fetch tournament rankings for pillar name seeding
+          let _pillarNames = null;
+          try {
+            const _briefRows = await this._mgQuery(
+              `MATCH (g:CompanyGoal {id: $gid})-[:HAS_RESEARCH]->(grb:GoalResearchBrief)
+               WHERE grb.expiresAt > localdatetime()
+               RETURN grb.tournamentRankings AS rankings
+               ORDER BY grb.createdAt DESC LIMIT 1`,
+              { gid: goalId }
+            );
+            if (_briefRows && _briefRows.length > 0 && _briefRows[0].rankings) {
+              _pillarNames = _rankingsToPillars(_briefRows[0].rankings);
+            }
+          } catch { /* non-fatal — initializeMandala works without pillar names */ }
+          await mandala.initializeMandala(goalId, goalTitle, _pillarNames);
           this._log('info', `tickGoalDecompose: Mandala initialized for goal "${goalTitle}" (8 pillars, 64 cells)`);
         } catch (e) {
           this._log('debug', `tickGoalDecompose: Mandala init failed for goal ${goalId}: ${e.message}`);
@@ -952,7 +1006,21 @@ class HBOBridge {
             { goalId: goal.id, cid: this._companyId }
           ).catch(() => null);
           if (!existingPillar?.rows?.length) {
-            await mandala.initializeMandala(goal.id, goal.title, null);
+            // GoalResearchBrief: fetch tournament rankings for pillar name seeding
+            let _pillarNames = null;
+            try {
+              const _briefRows = await this._mg(
+                `MATCH (g:CompanyGoal {id: $gid})-[:HAS_RESEARCH]->(grb:GoalResearchBrief)
+                 WHERE grb.expiresAt > localdatetime()
+                 RETURN grb.tournamentRankings AS rankings
+                 ORDER BY grb.createdAt DESC LIMIT 1`,
+                { gid: goal.id }
+              );
+              if (_briefRows && _briefRows.length > 0 && _briefRows[0].rankings) {
+                _pillarNames = _rankingsToPillars(_briefRows[0].rankings);
+              }
+            } catch { /* non-fatal — initializeMandala works without pillar names */ }
+            await mandala.initializeMandala(goal.id, goal.title, _pillarNames);
             this._log('info', `tickGoalDecompose: Mandala initialized for goal "${goal.title}" (8 pillars, 64 cells)`);
           }
         } catch (e) {

package/daemon/lib/headroom-middleware.js

@@ -0,0 +1,129 @@
+'use strict';
+/**
+ * daemon/lib/headroom-middleware.js
+ *
+ * CCR (Compress-Cache-Retrieve) middleware helpers for helios-api.js.
+ *
+ * Exports:
+ *   handleCcrRetrieve(req, res)   — GET /api/hbo/retrieve/:hash handler
+ *   isLargeArrayPayload(parsed)   — true when an HBO API response body warrants compression
+ *
+ * Architecture note on CcrStore:
+ *   The compression server runs as a CHILD PROCESS (spawned by HeadroomProxyManager).
+ *   It has its own in-process CcrStore. The daemon process has a separate CcrStore
+ *   instance which is always empty — it never receives the dropped rows.
+ *
+ *   Therefore handleCcrRetrieve MUST proxy to the child process's HTTP endpoint
+ *   (GET /v1/retrieve/:hash) rather than reading the daemon's local CcrStore.
+ *   This is consistent with how helios-api.js proxies /api/headroom/health and
+ *   /api/headroom/stats.
+ *
+ * No hardcoded company IDs. Cross-platform (http module, path.join).
+ */
+
+const http = require('http');
+
+// ── handleCcrRetrieve ─────────────────────────────────────────────────────────
+/**
+ * Handle GET /api/hbo/retrieve/:hash
+ *
+ * Proxies to the compression child's GET /v1/retrieve/:hash endpoint.
+ * req.params.hash is set by the caller (helios-api.js) before invoking.
+ *
+ * Responses:
+ *   200  { hash: string, data: <original JSON>, originalBytes: number }
+ *   400  { error: string }   — missing or invalid hash param
+ *   404  { error: string }   — hash not in child store or expired
+ *   503  { error: string }   — compression server not running
+ */
+async function handleCcrRetrieve(req, res) {
+  const hash = (req.params && req.params.hash) ? String(req.params.hash) : '';
+
+  if (!hash || !/^[a-f0-9]{8,64}$/.test(hash)) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Invalid or missing hash parameter' }));
+    return;
+  }
+
+  // Get the compression server URL from HeadroomProxyManager singleton.
+  // The child process owns the CcrStore — we must proxy to it.
+  let baseUrl;
+  try {
+    const { HeadroomProxyManager } = require('./headroom-proxy-manager');
+    baseUrl = HeadroomProxyManager.getInstance().getBaseUrl();
+  } catch (_) {}
+
+  if (!baseUrl) {
+    res.writeHead(503, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Compression server not running — CCR retrieve unavailable' }));
+    return;
+  }
+
+  // Proxy GET /v1/retrieve/:hash to the child process
+  const url = new URL(baseUrl);
+  const proxyReq = http.request(
+    {
+      hostname: url.hostname,
+      port: parseInt(url.port || '8787', 10),
+      path: `/v1/retrieve/${hash}`,
+      method: 'GET',
+    },
+    (proxyRes) => {
+      let body = '';
+      proxyRes.on('data', (c) => { body += c; });
+      proxyRes.on('end', () => {
+        res.writeHead(proxyRes.statusCode, { 'Content-Type': 'application/json' });
+        res.end(body);
+      });
+    }
+  );
+
+  proxyReq.setTimeout(3000, () => {
+    proxyReq.destroy();
+    res.writeHead(503, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'CCR retrieve timeout' }));
+  });
+
+  proxyReq.on('error', () => {
+    if (!res.headersSent) {
+      res.writeHead(503, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'CCR retrieve: compression server unreachable' }));
+    }
+  });
+
+  proxyReq.end();
+}
+
+// ── isLargeArrayPayload ───────────────────────────────────────────────────────
+/**
+ * Returns true if a parsed JSON body should be routed through Headroom compression.
+ *
+ * Conditions (any one sufficient):
+ *   1. parsed is an array with >= 5 elements
+ *   2. parsed is an object with at least one value that is an array with >= 5 elements
+ *
+ * Threshold 5 matches SmartCrusher.cfg.minItemsToAnalyze (default 5).
+ * Below this threshold SmartCrusher always returns passthrough anyway.
+ *
+ * Called from helios-api.js res.end() wrapper on GET /api/hbo/* routes.
+ * No side effects. Pure function.
+ */
+function isLargeArrayPayload(parsed) {
+  if (parsed === null || parsed === undefined) return false;
+
+  // Case 1: top-level array
+  if (Array.isArray(parsed)) {
+    return parsed.length >= 5;
+  }
+
+  // Case 2: object containing an array value
+  if (typeof parsed === 'object') {
+    const values = Object.values(parsed);
+    return values.some((v) => Array.isArray(v) && v.length >= 5);
+  }
+
+  return false;
+}
+
+module.exports = { handleCcrRetrieve, isLargeArrayPayload };
+