@hegemonart/get-design-done 1.27.5 → 1.27.7

package/scripts/lib/parallelism-engine/concurrency-tuner.d.cts

@@ -0,0 +1,53 @@
+// scripts/lib/parallelism-engine/concurrency-tuner.d.cts — types for concurrency-tuner.cjs (Phase 27.6 D-07).
+
+export interface ResolveConcurrencyOptions {
+  /** Override CPU count detection (defaults to `os.cpus().length`). */
+  cpuCount?: number;
+  /** Override last-observed optimum (else read from event-chain). */
+  lastObservedOptimum?: number;
+  /** Hard ceiling cap. Defaults to `DEFAULT_HARD_CEILING` (8). */
+  hardCeiling?: number;
+  /** Event-chain path override (else use `DEFAULT_EVENTS_PATH`). */
+  eventsPath?: string;
+  /** Base directory override (else `process.cwd()`). */
+  baseDir?: string;
+}
+
+export interface ReadLastObservedOptimumOptions {
+  eventsPath?: string;
+  baseDir?: string;
+}
+
+export interface EmitParallelismVerdictPayload {
+  task_ids?: string[];
+  verdict?: string;
+  reason?: string;
+  intended_concurrency?: number;
+  observed_concurrency?: number;
+  contention_detected?: boolean;
+  wall_clock_ms?: number;
+}
+
+/**
+ * Resolve the concurrency default per D-07: `min(cpu-1, last_observed_optimum, hard_ceiling)`.
+ * Falls back to `cpu-1` capped at `hard_ceiling` when no prior verdict exists.
+ */
+export function resolveConcurrency(opts?: ResolveConcurrencyOptions): number;
+
+/**
+ * Read the latest `parallelism.verdict` event's optimum from the event chain.
+ * Returns null when no prior verdict exists.
+ */
+export function readLastObservedOptimum(
+  opts?: ReadLastObservedOptimumOptions,
+): number | null;
+
+/**
+ * Emit a `parallelism.verdict` event (additive payload — back-compat preserved).
+ */
+export function emitParallelismVerdict(
+  payload?: EmitParallelismVerdictPayload,
+): void;
+
+export const DEFAULT_HARD_CEILING: number;
+export const DEFAULT_EVENTS_PATH: string;

package/scripts/lib/perf-analyzer/cost-regression.cjs

@@ -0,0 +1,299 @@
+/**
+ * scripts/lib/perf-analyzer/cost-regression.cjs — Plan 27.6-01
+ *
+ * Stateless detection rules over the telemetry row arrays returned by
+ * scripts/lib/perf-analyzer/index.cjs. Three pure functions:
+ *
+ *   detectCostRegressions  — top-3 agents whose p50 USD-cost has
+ *                            regressed >= thresholdPct (default 25%
+ *                            per Phase 27.6 D-01) vs baseline across
+ *                            cyclesRequired distinct cycles (default 3).
+ *   computeCacheHitDelta   — per-agent current hit rate vs baseline.
+ *   computeP95Spikes       — per-agent p95 wall-time multiplier vs
+ *                            baseline. Flag when multiplier >= 1.5.
+ *
+ * All inputs are plain arrays / objects. No I/O. No external deps.
+ */
+'use strict';
+
+/**
+ * Median (p50) of a numeric array. Returns 0 for empty input.
+ * Even-length arrays return the mean of the two middle values.
+ *
+ * @param {number[]} arr
+ * @returns {number}
+ */
+function p50(arr) {
+  if (!arr || arr.length === 0) return 0;
+  const sorted = [...arr].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+/**
+ * p95 of a numeric array (nearest-rank, floor index, clamped to last).
+ * Returns 0 for empty input.
+ *
+ * @param {number[]} arr
+ * @returns {number}
+ */
+function p95(arr) {
+  if (!arr || arr.length === 0) return 0;
+  const sorted = [...arr].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95));
+  return sorted[idx];
+}
+
+/**
+ * Group cost rows by agent, then by cycle. Filters out rows missing
+ * the required shape (agent, est_cost_usd, cycle).
+ *
+ * @param {object[]} rows
+ * @returns {Map<string, { cycles: Map<string, number[]> }>}
+ */
+function groupRowsByAgentCycle(rows) {
+  const byAgent = new Map();
+  for (const row of rows || []) {
+    if (
+      !row ||
+      typeof row.agent !== 'string' ||
+      typeof row.est_cost_usd !== 'number' ||
+      typeof row.cycle !== 'string'
+    ) {
+      continue;
+    }
+    let bucket = byAgent.get(row.agent);
+    if (!bucket) {
+      bucket = { cycles: new Map() };
+      byAgent.set(row.agent, bucket);
+    }
+    let cycleArr = bucket.cycles.get(row.cycle);
+    if (!cycleArr) {
+      cycleArr = [];
+      bucket.cycles.set(row.cycle, cycleArr);
+    }
+    cycleArr.push(row.est_cost_usd);
+  }
+  return byAgent;
+}
+
+/**
+ * Top-3 token-cost regressions across the most recent `cyclesRequired`
+ * distinct cycles per agent. Honours D-01 defaults (25% / 3 cycles).
+ *
+ * @param {object}   opts
+ * @param {object[]} opts.rows             - cost rows (from loadCosts)
+ * @param {Record<string, {p50_usd:number, hit_rate?:number, p95_ms?:number}>} opts.baseline
+ * @param {number}   [opts.thresholdPct=25] - regression threshold (D-01)
+ * @param {number}   [opts.cyclesRequired=3] - minimum distinct cycles (D-01)
+ * @returns {{
+ *   regressions: Array<{agent:string, baseline_p50_usd:number, current_p50_usd:number, delta_pct:number, cycles_observed:number}>,
+ *   summary: {agents_evaluated:number, agents_skipped_insufficient_data:number, regressions_count:number, threshold_pct:number, cycles_required:number}
+ * }}
+ */
+function detectCostRegressions({ rows, baseline, thresholdPct, cyclesRequired } = {}) {
+  const _thresholdPct = thresholdPct ?? 25;
+  const _cyclesRequired = cyclesRequired ?? 3;
+  const _baseline = baseline || {};
+
+  const byAgent = groupRowsByAgentCycle(rows);
+
+  /** @type {Array<{agent:string, baseline_p50_usd:number, current_p50_usd:number, delta_pct:number, cycles_observed:number}>} */
+  const candidates = [];
+  let agents_evaluated = 0;
+  let agents_skipped = 0;
+
+  for (const [agent, bucket] of byAgent.entries()) {
+    // Newest cycles first (lexicographic descending) — take up to N.
+    const cycleKeys = [...bucket.cycles.keys()].sort().reverse();
+    const recentCycles = cycleKeys.slice(0, _cyclesRequired);
+
+    if (recentCycles.length < _cyclesRequired) {
+      agents_skipped += 1;
+      continue;
+    }
+
+    const baselineEntry = _baseline[agent];
+    if (!baselineEntry || typeof baselineEntry.p50_usd !== 'number') {
+      agents_skipped += 1;
+      continue;
+    }
+
+    const flatCosts = recentCycles.flatMap((c) => bucket.cycles.get(c));
+    const current = p50(flatCosts);
+    const base = baselineEntry.p50_usd;
+
+    // Contract (plan 27.6-01 behavior): "an agent's p50 USD-cost across
+    // the LAST cyclesRequired cycles is >= baseline_p50 × (1 + thresholdPct/100)".
+    // Apply the multiplicative form directly so the threshold-boundary case
+    // (e.g. baseline=0.05, current=0.0625, thresholdPct=25) is exact rather
+    // than dropping a ULP into the < side after a divide-and-multiply.
+    let delta_pct;
+    let isRegression;
+    if (base === 0) {
+      delta_pct = current === 0 ? 0 : Infinity;
+      isRegression = current > 0; // base=0+current>0 → always regression (D-01 edge)
+    } else {
+      const threshold = base * (1 + _thresholdPct / 100);
+      delta_pct = ((current - base) / base) * 100;
+      isRegression = current >= threshold;
+    }
+
+    agents_evaluated += 1;
+
+    if (isRegression) {
+      candidates.push({
+        agent,
+        baseline_p50_usd: base,
+        current_p50_usd: current,
+        delta_pct,
+        cycles_observed: recentCycles.length,
+      });
+    }
+  }
+
+  candidates.sort((a, b) => b.delta_pct - a.delta_pct);
+  const regressions = candidates.slice(0, 3);
+
+  return {
+    regressions,
+    summary: {
+      agents_evaluated,
+      agents_skipped_insufficient_data: agents_skipped,
+      regressions_count: regressions.length,
+      threshold_pct: _thresholdPct,
+      cycles_required: _cyclesRequired,
+    },
+  };
+}
+
+/**
+ * Cache-hit-rate delta per agent: current hit rate over the most recent
+ * `cyclesRequired` distinct cycles vs baseline hit rate.
+ *
+ * @param {object} opts
+ * @param {object[]} opts.rows
+ * @param {Record<string, {hit_rate?:number}>} opts.baseline
+ * @param {number} [opts.cyclesRequired=3]
+ * @returns {{ perAgent: Array<{agent:string, baseline_hit_rate:number, current_hit_rate:number, delta_pct:number, cycles_observed:number}> }}
+ */
+function computeCacheHitDelta({ rows, baseline, cyclesRequired } = {}) {
+  const _cyclesRequired = cyclesRequired ?? 3;
+  const _baseline = baseline || {};
+
+  // Group by agent: { agent -> Map<cycle, { hits: number, total: number }> }
+  const byAgent = new Map();
+  for (const row of rows || []) {
+    if (!row || typeof row.agent !== 'string' || typeof row.cycle !== 'string') continue;
+    let bucket = byAgent.get(row.agent);
+    if (!bucket) {
+      bucket = { cycles: new Map() };
+      byAgent.set(row.agent, bucket);
+    }
+    let cycleEntry = bucket.cycles.get(row.cycle);
+    if (!cycleEntry) {
+      cycleEntry = { hits: 0, total: 0 };
+      bucket.cycles.set(row.cycle, cycleEntry);
+    }
+    cycleEntry.total += 1;
+    if (row.cache_hit === true) cycleEntry.hits += 1;
+  }
+
+  /** @type {Array<{agent:string, baseline_hit_rate:number, current_hit_rate:number, delta_pct:number, cycles_observed:number}>} */
+  const perAgent = [];
+  for (const [agent, bucket] of byAgent.entries()) {
+    const cycleKeys = [...bucket.cycles.keys()].sort().reverse();
+    const recentCycles = cycleKeys.slice(0, _cyclesRequired);
+    if (recentCycles.length === 0) continue;
+
+    let hits = 0;
+    let total = 0;
+    for (const c of recentCycles) {
+      const entry = bucket.cycles.get(c);
+      hits += entry.hits;
+      total += entry.total;
+    }
+    if (total === 0) continue;
+
+    const current_hit_rate = hits / total;
+    const baselineEntry = _baseline[agent];
+    const baseline_hit_rate =
+      baselineEntry && typeof baselineEntry.hit_rate === 'number' ? baselineEntry.hit_rate : 0;
+
+    let delta_pct;
+    if (baseline_hit_rate === 0) {
+      delta_pct = current_hit_rate === 0 ? 0 : Infinity;
+    } else {
+      delta_pct = ((current_hit_rate - baseline_hit_rate) / baseline_hit_rate) * 100;
+    }
+
+    perAgent.push({
+      agent,
+      baseline_hit_rate,
+      current_hit_rate,
+      delta_pct,
+      cycles_observed: recentCycles.length,
+    });
+  }
+
+  return { perAgent };
+}
+
+/**
+ * Aggregate wall_time_ms per agent across all cycles in `byCycle` and
+ * compare current p95 to baseline p95. Flag agents whose
+ * `current_p95 / baseline_p95 >= multiplierThreshold` (default 1.5).
+ *
+ * @param {object} opts
+ * @param {Record<string, object[]>} opts.byCycle
+ * @param {Record<string, {p95_ms?:number}>} opts.baseline
+ * @param {number} [opts.multiplierThreshold=1.5]
+ * @returns {{ spikes: Array<{agent:string, baseline_p95_ms:number, current_p95_ms:number, multiplier:number, cycles_observed:number}> }}
+ */
+function computeP95Spikes({ byCycle, baseline, multiplierThreshold } = {}) {
+  const _multiplier = multiplierThreshold ?? 1.5;
+  const _baseline = baseline || {};
+  const _byCycle = byCycle || {};
+
+  // Aggregate per agent: agent -> { walls: number[], cycles: Set<string> }
+  /** @type {Map<string, { walls: number[], cycles: Set<string> }>} */
+  const byAgent = new Map();
+  for (const [cycle, entries] of Object.entries(_byCycle)) {
+    for (const entry of entries || []) {
+      if (!entry || typeof entry.agent !== 'string' || typeof entry.wall_time_ms !== 'number') {
+        continue;
+      }
+      let bucket = byAgent.get(entry.agent);
+      if (!bucket) {
+        bucket = { walls: [], cycles: new Set() };
+        byAgent.set(entry.agent, bucket);
+      }
+      bucket.walls.push(entry.wall_time_ms);
+      bucket.cycles.add(cycle);
+    }
+  }
+
+  /** @type {Array<{agent:string, baseline_p95_ms:number, current_p95_ms:number, multiplier:number, cycles_observed:number}>} */
+  const spikes = [];
+  for (const [agent, bucket] of byAgent.entries()) {
+    const baselineEntry = _baseline[agent];
+    if (!baselineEntry || typeof baselineEntry.p95_ms !== 'number') continue;
+    const base = baselineEntry.p95_ms;
+    if (base === 0) continue; // can't form a multiplier against zero
+    const current_p95_ms = p95(bucket.walls);
+    const multiplier = current_p95_ms / base;
+    if (multiplier >= _multiplier) {
+      spikes.push({
+        agent,
+        baseline_p95_ms: base,
+        current_p95_ms,
+        multiplier,
+        cycles_observed: bucket.cycles.size,
+      });
+    }
+  }
+
+  return { spikes };
+}
+
+module.exports = { detectCostRegressions, computeCacheHitDelta, computeP95Spikes };

package/scripts/lib/perf-analyzer/index.cjs

@@ -0,0 +1,139 @@
+/**
+ * scripts/lib/perf-analyzer/index.cjs — Plan 27.6-01
+ *
+ * Telemetry reader for the Phase 27.6 perf-analyzer reflector agent.
+ * Reads `.design/telemetry/costs.jsonl` (cost rows, Phase 10.1) and
+ * `.design/telemetry/trajectories/<cycle>.jsonl` files (agent trace
+ * lines per Phase 22).
+ *
+ * JSONL discipline (same as scripts/lib/event-stream/reader.ts):
+ *   - One JSON object per line.
+ *   - Blank lines / whitespace-only lines ignored silently.
+ *   - Malformed lines tolerated — counted in skipped_count, NOT thrown.
+ *
+ * No external deps. Stateless. Safe to require from CommonJS callers
+ * (agents, hooks, CI gates) without dragging the gdd-state MCP graph.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_COSTS_PATH = '.design/telemetry/costs.jsonl';
+const DEFAULT_TRAJECTORIES_DIR = '.design/telemetry/trajectories';
+
+/**
+ * Resolve a path against an optional baseDir. Absolute paths win.
+ * @param {string} p
+ * @param {string|undefined} baseDir
+ * @returns {string}
+ */
+function resolvePath(p, baseDir) {
+  if (path.isAbsolute(p)) return p;
+  if (baseDir) return path.join(baseDir, p);
+  return p;
+}
+
+/**
+ * Parse a JSONL file tolerantly: blank lines silently skipped,
+ * malformed lines counted in skipped_count without throwing.
+ *
+ * @param {string} contents - raw file contents (utf-8)
+ * @returns {{ rows: object[], skipped: number }}
+ */
+function parseJsonl(contents) {
+  const rows = [];
+  let skipped = 0;
+  const lines = contents.split(/\r?\n/);
+  for (const line of lines) {
+    if (line.trim() === '') continue;
+    try {
+      const obj = JSON.parse(line);
+      rows.push(obj);
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { rows, skipped };
+}
+
+/**
+ * Read `.design/telemetry/costs.jsonl` (or override) into row objects.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path]       Override (default: DEFAULT_COSTS_PATH)
+ * @param {string} [opts.sinceCycle] Drop rows with row.cycle < this string (lex)
+ * @param {string} [opts.baseDir]    Resolve relative paths against this dir
+ * @returns {{ rows: object[], parsed_count: number, skipped_count: number }}
+ */
+function loadCosts(opts) {
+  const o = opts || {};
+  const rawPath = o.path !== undefined ? o.path : DEFAULT_COSTS_PATH;
+  const targetPath = resolvePath(rawPath, o.baseDir);
+
+  if (!fs.existsSync(targetPath)) {
+    return { rows: [], parsed_count: 0, skipped_count: 0 };
+  }
+
+  const contents = fs.readFileSync(targetPath, 'utf8');
+  const { rows: parsed, skipped: skipped_count } = parseJsonl(contents);
+
+  let rows = parsed;
+  if (o.sinceCycle !== undefined) {
+    const since = o.sinceCycle;
+    rows = parsed.filter(
+      (row) => row && typeof row.cycle === 'string' && row.cycle >= since,
+    );
+  }
+
+  return { rows, parsed_count: rows.length, skipped_count };
+}
+
+/**
+ * Read `.design/telemetry/trajectories/<cycle>.jsonl` files (or override
+ * directory) into a per-cycle map keyed by basename-without-extension.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.dir]     Override (default: DEFAULT_TRAJECTORIES_DIR)
+ * @param {string} [opts.baseDir] Resolve relative paths against this dir
+ * @returns {{ byCycle: Record<string, object[]>, files_read: number }}
+ */
+function loadTrajectories(opts) {
+  const o = opts || {};
+  const rawDir = o.dir !== undefined ? o.dir : DEFAULT_TRAJECTORIES_DIR;
+  const targetDir = resolvePath(rawDir, o.baseDir);
+
+  if (!fs.existsSync(targetDir)) {
+    return { byCycle: {}, files_read: 0 };
+  }
+
+  /** @type {Record<string, object[]>} */
+  const byCycle = {};
+  let files_read = 0;
+
+  const entries = fs.readdirSync(targetDir);
+  for (const entry of entries) {
+    if (!entry.endsWith('.jsonl')) continue;
+    const filePath = path.join(targetDir, entry);
+    let contents;
+    try {
+      contents = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      // Permission / IO error on one file should not abort the whole read.
+      continue;
+    }
+    const cycleSlug = path.basename(entry, '.jsonl');
+    const { rows } = parseJsonl(contents);
+    byCycle[cycleSlug] = rows;
+    files_read += 1;
+  }
+
+  return { byCycle, files_read };
+}
+
+module.exports = {
+  loadCosts,
+  loadTrajectories,
+  DEFAULT_COSTS_PATH,
+  DEFAULT_TRAJECTORIES_DIR,
+};

package/scripts/lib/prompt-dedup/index.cjs

@@ -0,0 +1,161 @@
+/**
+ * scripts/lib/prompt-dedup/index.cjs — Plan 27.6-06
+ *
+ * Phase 27.6 D-11 prompt-deduplication analyzer. Detects cases where
+ * >= 3 distinct agents in the same cycle read the same reference/*.md
+ * file. Produces a preamble injection that gets prepended to the
+ * Phase 14.5 retrieval-contract preamble during cycle execution.
+ *
+ * v1.27.6 ships the analyzer + injection text builder. The event-
+ * emission side-effect is wired here for downstream consumers. The
+ * actual `reference.read` event emission from agent-read paths is
+ * deferred to a follow-up phase (this library is ready to consume
+ * those events when they exist).
+ *
+ * No external deps. Pure analyzer + lazy event-stream require.
+ */
+'use strict';
+
+const DEFAULT_THRESHOLD = 3;  // D-11 — '>= 3 agents'
+
+/**
+ * Lazy require for the event-stream appendEvent helper. Returns a
+ * no-op if event-stream is unavailable so emitDedupInjection can be
+ * called in tests / Codex no-PreCompact paths without throwing.
+ *
+ * @returns {(ev: object) => void}
+ */
+function getAppendEvent() {
+  try {
+    const m = require('../event-stream');
+    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+  } catch { /* swallow — event-stream not on path */ }
+  return function noopAppend(_ev) {};
+}
+
+/**
+ * Detect reference/*.md files that have been read by >= threshold
+ * distinct agents in the same cycle. The detection is pure — it
+ * consumes an in-memory events array and returns a structured result.
+ *
+ * @param {object} [opts]
+ * @param {Array<object>} [opts.events]   Event-stream entries (any shape)
+ * @param {number} [opts.threshold]       Override DEFAULT_THRESHOLD (3)
+ * @param {string} [opts.cycle]           Filter — only consider events
+ *                                        whose event.cycle === this value
+ * @returns {{duplicates: Array<{ref_path: string, agents: string[], hash?: string, cycle?: string}>}}
+ */
+function detectDuplicateReferenceReads({ events, threshold, cycle } = {}) {
+  const list = Array.isArray(events) ? events : [];
+  const N = typeof threshold === 'number' && threshold >= 1
+    ? Math.floor(threshold)
+    : DEFAULT_THRESHOLD;
+  const cycleFilter = typeof cycle === 'string' && cycle.length > 0 ? cycle : null;
+
+  // Group by (cycle, ref_path) → Set<agent>
+  const groups = new Map();
+  for (const ev of list) {
+    if (!ev || ev.type !== 'reference.read') continue;
+    if (!ev.payload || typeof ev.payload.ref_path !== 'string' || typeof ev.payload.agent !== 'string') continue;
+    const evCycle = typeof ev.cycle === 'string'
+      ? ev.cycle
+      : (typeof ev.payload.cycle === 'string' ? ev.payload.cycle : '');
+    if (cycleFilter !== null && evCycle !== cycleFilter) continue;
+    const key = evCycle + ' ' + ev.payload.ref_path;
+    let group = groups.get(key);
+    if (!group) {
+      group = { cycle: evCycle, ref_path: ev.payload.ref_path, agents: new Set(), hash: undefined };
+      groups.set(key, group);
+    }
+    group.agents.add(ev.payload.agent);
+    if (typeof ev.payload.content_hash === 'string' && !group.hash) {
+      group.hash = ev.payload.content_hash;
+    }
+  }
+
+  const duplicates = [];
+  for (const group of groups.values()) {
+    if (group.agents.size >= N) {
+      duplicates.push({
+        ref_path: group.ref_path,
+        agents: [...group.agents].sort(),
+        hash: group.hash,
+        cycle: group.cycle || undefined,
+      });
+    }
+  }
+  duplicates.sort((a, b) => a.ref_path.localeCompare(b.ref_path));
+  return { duplicates };
+}
+
+/**
+ * Build the markdown preamble injection text that gets prepended to
+ * the Phase 14.5 retrieval-contract preamble during cycle execution.
+ * Returns an empty string when duplicates is empty (no injection).
+ *
+ * @param {object} [opts]
+ * @param {Array<object>} [opts.duplicates]  From detectDuplicateReferenceReads
+ * @param {string}        [opts.sessionId]   Optional breadcrumb
+ * @returns {string}
+ */
+function buildPreambleInjection({ duplicates, sessionId } = {}) {
+  const list = Array.isArray(duplicates) ? duplicates : [];
+  if (list.length === 0) return '';
+  const lines = [
+    '## Shared Context (Phase 27.6 dedup)',
+    '',
+    'The following reference files have been read by >= 3 agents in this cycle and are now loaded ONCE as shared context. Subsequent agents see a content-hash reference instead of the full file body:',
+    '',
+  ];
+  for (const d of list) {
+    const hashSuffix = d.hash ? ` [hash: ${d.hash}]` : '';
+    lines.push(`- \`${d.ref_path}\` (read by: ${d.agents.join(', ')})${hashSuffix}`);
+  }
+  lines.push('');
+  lines.push('To opt out of dedup for a specific read, set `GDD_DEDUP_OPT_OUT=1` in the agent\'s environment.');
+  lines.push('');
+  // sessionId is consumed as a breadcrumb hint; not embedded in the
+  // preamble text by default to keep the markdown minimal.
+  if (typeof sessionId === 'string' && sessionId.length > 0) {
+    lines.push(`<!-- dedup-session: ${sessionId} -->`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Emit one `dedup.injection` event per duplicate via the event-stream
+ * appendEvent helper. Lazy-required; safe when event-stream is
+ * unavailable (no-op fallback). Returns void.
+ *
+ * @param {object} [opts]
+ * @param {Array<object>} [opts.duplicates]
+ * @param {string}        [opts.sessionId]
+ * @returns {void}
+ */
+function emitDedupInjection({ duplicates, sessionId } = {}) {
+  const list = Array.isArray(duplicates) ? duplicates : [];
+  if (list.length === 0) return;
+  const append = getAppendEvent();
+  for (const d of list) {
+    append({
+      type: 'dedup.injection',
+      timestamp: new Date().toISOString(),
+      sessionId: typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : 'prompt-dedup',
+      payload: {
+        ref_path: d.ref_path,
+        agents: d.agents,
+        agent_count: d.agents.length,
+        content_hash: d.hash,
+        cycle: d.cycle,
+      },
+    });
+  }
+}
+
+module.exports = {
+  detectDuplicateReferenceReads,
+  buildPreambleInjection,
+  emitDedupInjection,
+  DEFAULT_THRESHOLD,
+};