@tekyzinc/gsd-t 3.13.16 → 3.16.11

package/bin/gsd-t-token-dashboard.cjs

@@ -0,0 +1,318 @@
+'use strict';
+/**
+ * GSD-T Token Dashboard (M41 D4)
+ *
+ * Cumulative historical view of `.gsd-t/metrics/token-usage.jsonl`.
+ * Feeds the `gsd-t tokens` CLI and the token-block tail of `gsd-t status`.
+ *
+ * Zero external deps. `.cjs` for ESM/CJS compat.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const DEFAULT_JSONL_PATH = (projectDir) => path.join(projectDir, '.gsd-t', 'metrics', 'token-usage.jsonl');
+
+function _safeParse(line) {
+  try { return JSON.parse(line); } catch (_) { return null; }
+}
+
+function _day(startedAt) {
+  if (!startedAt) return 'unknown';
+  // YYYY-MM-DD slice works for both ISO and our 'YYYY-MM-DD HH:MM' format.
+  return String(startedAt).slice(0, 10);
+}
+
+function _cost(r) {
+  return (typeof r.costUSD === 'number' && r.costUSD >= 0) ? r.costUSD : 0;
+}
+
+/**
+ * Aggregate token-usage records.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectDir
+ * @param {string} [opts.since]       YYYY-MM-DD (inclusive)
+ * @param {string} [opts.milestone]   e.g. 'M41'
+ * @returns {Promise<object>}
+ */
+async function aggregate(opts) {
+  const projectDir = opts.projectDir || '.';
+  const jsonlPath = opts.jsonlPath || DEFAULT_JSONL_PATH(projectDir);
+  const sinceDay = opts.since || null;
+  const milestone = opts.milestone || null;
+
+  const agg = {
+    totalRecords: 0,
+    totalCostUSD: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCacheReadTokens: 0,
+    totalCacheCreateTokens: 0,
+    byDay: {},
+    byCommand: {},
+    byModel: {},
+    topSpawns: [],
+    rolling7d: { days: 0, totalCostUSD: 0, dailyAvgUSD: 0, monthlyProjectionUSD: 0 },
+    currentMilestone: milestone,
+    source: jsonlPath,
+  };
+
+  if (!fs.existsSync(jsonlPath)) {
+    return agg;
+  }
+
+  const rs = fs.createReadStream(jsonlPath, { encoding: 'utf8' });
+  const rl = readline.createInterface({ input: rs, crlfDelay: Infinity });
+
+  const rawRecords = [];
+
+  for await (const line of rl) {
+    const trimmed = line && line.trim();
+    if (!trimmed) continue;
+    const r = _safeParse(trimmed);
+    if (!r || typeof r !== 'object') continue;
+
+    const day = _day(r.startedAt);
+    if (sinceDay && day < sinceDay) continue;
+    if (milestone && r.milestone && r.milestone !== milestone) continue;
+    if (milestone && !r.milestone) continue;
+
+    rawRecords.push(r);
+
+    agg.totalRecords += 1;
+    agg.totalCostUSD += _cost(r);
+    agg.totalInputTokens += Number(r.inputTokens || 0);
+    agg.totalOutputTokens += Number(r.outputTokens || 0);
+    agg.totalCacheReadTokens += Number(r.cacheReadInputTokens || 0);
+    agg.totalCacheCreateTokens += Number(r.cacheCreationInputTokens || 0);
+
+    // byDay
+    if (!agg.byDay[day]) agg.byDay[day] = { day, records: 0, costUSD: 0, inputTokens: 0, outputTokens: 0 };
+    const d = agg.byDay[day];
+    d.records += 1;
+    d.costUSD += _cost(r);
+    d.inputTokens += Number(r.inputTokens || 0);
+    d.outputTokens += Number(r.outputTokens || 0);
+
+    // byCommand
+    const cmd = r.command || 'unknown';
+    if (!agg.byCommand[cmd]) agg.byCommand[cmd] = { command: cmd, records: 0, costUSD: 0, inputTokens: 0, outputTokens: 0 };
+    const c = agg.byCommand[cmd];
+    c.records += 1;
+    c.costUSD += _cost(r);
+    c.inputTokens += Number(r.inputTokens || 0);
+    c.outputTokens += Number(r.outputTokens || 0);
+
+    // byModel
+    const m = r.model || 'unknown';
+    if (!agg.byModel[m]) agg.byModel[m] = { model: m, records: 0, costUSD: 0, inputTokens: 0, cacheReadTokens: 0, cacheHitRate: 0 };
+    const mm = agg.byModel[m];
+    mm.records += 1;
+    mm.costUSD += _cost(r);
+    mm.inputTokens += Number(r.inputTokens || 0);
+    mm.cacheReadTokens += Number(r.cacheReadInputTokens || 0);
+  }
+
+  // Top 10 spawns by cost desc
+  agg.topSpawns = rawRecords
+    .slice()
+    .sort((a, b) => _cost(b) - _cost(a))
+    .slice(0, 10)
+    .map((r) => ({
+      startedAt: r.startedAt,
+      command: r.command,
+      step: r.step,
+      model: r.model,
+      costUSD: _cost(r),
+      inputTokens: r.inputTokens || 0,
+      outputTokens: r.outputTokens || 0,
+    }));
+
+  // Cache-hit rate per model
+  for (const key of Object.keys(agg.byModel)) {
+    const mm = agg.byModel[key];
+    const denom = mm.inputTokens + mm.cacheReadTokens;
+    mm.cacheHitRate = denom > 0 ? mm.cacheReadTokens / denom : 0;
+  }
+
+  // Rolling 7-day window by calendar day
+  const now = Date.now();
+  const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
+  const cutoffMs = now - sevenDaysMs;
+  let rollingCost = 0;
+  const rollingDays = new Set();
+  for (const r of rawRecords) {
+    const ts = Date.parse(String(r.startedAt).replace(' ', 'T') + (r.startedAt && r.startedAt.length === 16 ? ':00Z' : ''));
+    if (Number.isFinite(ts) && ts >= cutoffMs) {
+      rollingCost += _cost(r);
+      rollingDays.add(_day(r.startedAt));
+    }
+  }
+  agg.rolling7d.days = rollingDays.size;
+  agg.rolling7d.totalCostUSD = rollingCost;
+  agg.rolling7d.dailyAvgUSD = rollingCost / 7;
+  agg.rolling7d.monthlyProjectionUSD = agg.rolling7d.dailyAvgUSD * 30;
+
+  return agg;
+}
+
+function _fmtMoney(n) {
+  if (n == null || !Number.isFinite(n)) return '-';
+  return `$${n.toFixed(2)}`;
+}
+function _fmtPct(n) {
+  if (!Number.isFinite(n)) return '-';
+  return `${(n * 100).toFixed(1)}%`;
+}
+function _fmtInt(n) {
+  return String(Number(n || 0).toLocaleString('en-US'));
+}
+
+function renderTable(agg) {
+  const lines = [];
+  lines.push('═══ Token Dashboard ═══');
+  lines.push(`Records: ${_fmtInt(agg.totalRecords)} | Total cost: ${_fmtMoney(agg.totalCostUSD)} | Input: ${_fmtInt(agg.totalInputTokens)} | Output: ${_fmtInt(agg.totalOutputTokens)}`);
+  if (agg.currentMilestone) lines.push(`Milestone filter: ${agg.currentMilestone}`);
+  lines.push('');
+
+  lines.push('── By Day ──');
+  const days = Object.values(agg.byDay).sort((a, b) => a.day.localeCompare(b.day));
+  if (days.length === 0) lines.push('  (no data)');
+  for (const d of days) {
+    lines.push(`  ${d.day}  ${String(d.records).padStart(4)} spawns   ${_fmtMoney(d.costUSD).padStart(8)}   in=${_fmtInt(d.inputTokens)}  out=${_fmtInt(d.outputTokens)}`);
+  }
+  lines.push('');
+
+  lines.push('── By Command ──');
+  const cmds = Object.values(agg.byCommand).sort((a, b) => b.costUSD - a.costUSD);
+  if (cmds.length === 0) lines.push('  (no data)');
+  for (const c of cmds) {
+    lines.push(`  ${c.command.padEnd(30)} ${String(c.records).padStart(4)}   ${_fmtMoney(c.costUSD).padStart(8)}`);
+  }
+  lines.push('');
+
+  lines.push('── By Model ──');
+  const models = Object.values(agg.byModel).sort((a, b) => b.costUSD - a.costUSD);
+  if (models.length === 0) lines.push('  (no data)');
+  for (const m of models) {
+    lines.push(`  ${m.model.padEnd(20)} ${String(m.records).padStart(4)}   ${_fmtMoney(m.costUSD).padStart(8)}   cache-hit: ${_fmtPct(m.cacheHitRate)}`);
+  }
+  lines.push('');
+
+  lines.push('── Top 10 Spawns by Cost ──');
+  if (agg.topSpawns.length === 0) lines.push('  (no data)');
+  for (let i = 0; i < agg.topSpawns.length; i++) {
+    const s = agg.topSpawns[i];
+    lines.push(`  ${String(i + 1).padStart(2)}. ${s.startedAt}  ${String(s.command || '').padEnd(22)} ${String(s.step || '').padEnd(14)} ${_fmtMoney(s.costUSD)}`);
+  }
+  lines.push('');
+
+  lines.push('── Rolling 7-Day Projection ──');
+  lines.push(`  7-day cost: ${_fmtMoney(agg.rolling7d.totalCostUSD)} across ${agg.rolling7d.days} day(s)`);
+  lines.push(`  Daily avg:  ${_fmtMoney(agg.rolling7d.dailyAvgUSD)}`);
+  lines.push(`  Monthly projection (× 30): ${_fmtMoney(agg.rolling7d.monthlyProjectionUSD)}`);
+
+  return lines.join('\n');
+}
+
+function renderJson(agg) {
+  return JSON.stringify(agg, null, 2);
+}
+
+/**
+ * Renders exactly 2 content lines + 1 separator = 3 output lines total.
+ */
+function renderStatusBlock(agg) {
+  const sep = '───';
+  if (!agg || agg.totalRecords === 0) {
+    return sep + '\nTokens: no data yet (run a command to populate)\n(run `gsd-t tokens` for full dashboard)';
+  }
+  const line1 = `Tokens: ${_fmtInt(agg.totalRecords)} spawns, ${_fmtMoney(agg.totalCostUSD)} total${agg.currentMilestone ? ` (${agg.currentMilestone})` : ''}`;
+  const line2 = `Rolling 7d: ${_fmtMoney(agg.rolling7d.totalCostUSD)} (${_fmtMoney(agg.rolling7d.dailyAvgUSD)}/day → ${_fmtMoney(agg.rolling7d.monthlyProjectionUSD)}/mo proj.)`;
+  return `${sep}\n${line1}\n${line2}`;
+}
+
+/**
+ * Synchronous variant of aggregate() — for callers that need a blocking read
+ * (e.g. the `gsd-t status` tail where we can't await). Uses fs.readFileSync
+ * and shares the same record-processing loop. Safe for typical JSONL sizes
+ * (<100k lines); prefer aggregate() for large files or background work.
+ */
+function aggregateSync(opts) {
+  const projectDir = opts.projectDir || '.';
+  const jsonlPath = opts.jsonlPath || DEFAULT_JSONL_PATH(projectDir);
+  const sinceDay = opts.since || null;
+  const milestone = opts.milestone || null;
+
+  const agg = {
+    totalRecords: 0,
+    totalCostUSD: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCacheReadTokens: 0,
+    totalCacheCreateTokens: 0,
+    byDay: {},
+    byCommand: {},
+    byModel: {},
+    topSpawns: [],
+    rolling7d: { days: 0, totalCostUSD: 0, dailyAvgUSD: 0, monthlyProjectionUSD: 0 },
+    currentMilestone: milestone,
+    source: jsonlPath,
+  };
+
+  if (!fs.existsSync(jsonlPath)) return agg;
+
+  const raw = fs.readFileSync(jsonlPath, 'utf8');
+  const lines = raw.split('\n');
+  const rawRecords = [];
+
+  for (const line of lines) {
+    const trimmed = line && line.trim();
+    if (!trimmed) continue;
+    const r = _safeParse(trimmed);
+    if (!r || typeof r !== 'object') continue;
+
+    const day = _day(r.startedAt);
+    if (sinceDay && day < sinceDay) continue;
+    if (milestone && r.milestone && r.milestone !== milestone) continue;
+    if (milestone && !r.milestone) continue;
+
+    rawRecords.push(r);
+    agg.totalRecords += 1;
+    agg.totalCostUSD += _cost(r);
+    agg.totalInputTokens += Number(r.inputTokens || 0);
+    agg.totalOutputTokens += Number(r.outputTokens || 0);
+    agg.totalCacheReadTokens += Number(r.cacheReadInputTokens || 0);
+    agg.totalCacheCreateTokens += Number(r.cacheCreationInputTokens || 0);
+  }
+
+  const now = Date.now();
+  const cutoffMs = now - 7 * 24 * 60 * 60 * 1000;
+  let rollingCost = 0;
+  const rollingDays = new Set();
+  for (const r of rawRecords) {
+    const ts = Date.parse(String(r.startedAt).replace(' ', 'T') + (r.startedAt && r.startedAt.length === 16 ? ':00Z' : ''));
+    if (Number.isFinite(ts) && ts >= cutoffMs) {
+      rollingCost += _cost(r);
+      rollingDays.add(_day(r.startedAt));
+    }
+  }
+  agg.rolling7d.days = rollingDays.size;
+  agg.rolling7d.totalCostUSD = rollingCost;
+  agg.rolling7d.dailyAvgUSD = rollingCost / 7;
+  agg.rolling7d.monthlyProjectionUSD = agg.rolling7d.dailyAvgUSD * 30;
+
+  return agg;
+}
+
+module.exports = {
+  aggregate,
+  aggregateSync,
+  renderTable,
+  renderJson,
+  renderStatusBlock,
+  _safeParse,
+  _day,
+};

package/bin/gsd-t-token-regenerate-log.cjs

@@ -0,0 +1,129 @@
+'use strict';
+/**
+ * GSD-T Token Log Regenerator (M43 D3)
+ *
+ * Reads `.gsd-t/metrics/token-usage.jsonl` end-to-end and writes
+ * `.gsd-t/token-log.md` deterministically. Per metrics-schema-contract v2
+ * §Derived Artifact, `token-log.md` is a regenerated view post-v2.
+ *
+ * Sort (v2 §5): startedAt asc → session_id asc → turn_id asc.
+ * Numeric turn_ids sort numerically; mixed/non-numeric falls back to lex.
+ *
+ * Idempotent and deterministic: running twice produces byte-identical output.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const capture = require('./gsd-t-token-capture.cjs');
+const { NEW_HEADER, NEW_SEP, _formatTokensCell } = capture;
+
+function _readJsonl(jsonlPath) {
+  if (!fs.existsSync(jsonlPath)) return [];
+  const text = fs.readFileSync(jsonlPath, 'utf8');
+  const rows = [];
+  for (const line of text.split('\n')) {
+    const s = line.trim();
+    if (!s) continue;
+    try { rows.push(JSON.parse(s)); }
+    catch (_) { /* skip malformed line */ }
+  }
+  return rows;
+}
+
+function _tokenCellFromRow(row) {
+  if (!row.hasUsage) return '—';
+  const u = {
+    input_tokens: row.inputTokens || 0,
+    output_tokens: row.outputTokens || 0,
+    cache_read_input_tokens: row.cacheReadInputTokens || 0,
+    cache_creation_input_tokens: row.cacheCreationInputTokens || 0,
+    total_cost_usd: (typeof row.costUSD === 'number') ? row.costUSD : undefined,
+  };
+  return _formatTokensCell(u);
+}
+
+function _cmpStart(a, b) {
+  const av = a.startedAt || '';
+  const bv = b.startedAt || '';
+  if (av < bv) return -1;
+  if (av > bv) return 1;
+  return 0;
+}
+
+function _cmpSession(a, b) {
+  const av = a.session_id == null ? '' : String(a.session_id);
+  const bv = b.session_id == null ? '' : String(b.session_id);
+  if (av < bv) return -1;
+  if (av > bv) return 1;
+  return 0;
+}
+
+function _cmpTurn(a, b) {
+  const av = a.turn_id == null ? '' : String(a.turn_id);
+  const bv = b.turn_id == null ? '' : String(b.turn_id);
+  const an = Number(av), bn = Number(bv);
+  if (av !== '' && bv !== '' && Number.isFinite(an) && Number.isFinite(bn)) {
+    return an - bn;
+  }
+  if (av < bv) return -1;
+  if (av > bv) return 1;
+  return 0;
+}
+
+function sortRows(rows) {
+  return rows.slice().sort((a, b) =>
+    _cmpStart(a, b) || _cmpSession(a, b) || _cmpTurn(a, b)
+  );
+}
+
+function _durationCell(row) {
+  const ms = Number(row.durationMs || 0);
+  return `${Math.max(0, Math.round(ms / 1000))}s`;
+}
+
+function _renderRow(row) {
+  const tokensCell = _tokenCellFromRow(row);
+  const notes  = (row.notes  == null || row.notes  === '') ? '-' : String(row.notes).replace(/\|/g, '\\|');
+  const domain = (row.domain == null || row.domain === '') ? '-' : String(row.domain);
+  const task   = (row.task   == null || row.task   === '') ? '-' : String(row.task);
+  const ctxPct = (row.ctxPct == null) ? 'N/A' : String(row.ctxPct);
+  return `| ${row.startedAt || ''} | ${row.endedAt || ''} | ${row.command || ''} | ${row.step || ''} | ${row.model || ''} | ${_durationCell(row)} | ${tokensCell} | ${notes} | ${domain} | ${task} | ${ctxPct} |`;
+}
+
+function renderMarkdown(rows) {
+  const sorted = sortRows(rows);
+  const lines = ['# GSD-T Token Log', '', NEW_HEADER, NEW_SEP];
+  for (const r of sorted) lines.push(_renderRow(r));
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Regenerate token-log.md from token-usage.jsonl.
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir='.']
+ * @param {string} [opts.jsonlPath]     override input path
+ * @param {string} [opts.tokenLogPath]  override output path
+ * @returns {{ wrote: string, rowCount: number }}
+ */
+function regenerateLog(opts = {}) {
+  const projectDir = opts.projectDir || '.';
+  const jsonlPath = opts.jsonlPath || path.join(projectDir, '.gsd-t', 'metrics', 'token-usage.jsonl');
+  const tokenLogPath = opts.tokenLogPath || path.join(projectDir, '.gsd-t', 'token-log.md');
+  const rows = _readJsonl(jsonlPath);
+  const markdown = renderMarkdown(rows);
+  const dir = path.dirname(tokenLogPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(tokenLogPath, markdown);
+  return { wrote: tokenLogPath, rowCount: rows.length };
+}
+
+module.exports = {
+  regenerateLog,
+  renderMarkdown,
+  sortRows,
+  _readJsonl,
+  _renderRow,
+  _tokenCellFromRow,
+};

package/bin/gsd-t-transcript-tee.cjs

@@ -0,0 +1,246 @@
+'use strict';
+/**
+ * GSD-T Transcript Tee (M42 D1)
+ *
+ * Captures raw stream-json frames from every unattended spawn to
+ * `.gsd-t/transcripts/{spawn-id}.ndjson` + maintains a registry at
+ * `.gsd-t/transcripts/.index.json` used by the dashboard sidebar.
+ *
+ * Zero external deps. Append-only. Does not parse the frames — that's the
+ * renderer's job. One frame per line; lines that fail JSON parse are still
+ * tee'd so nothing is silently dropped.
+ *
+ * Contracts:
+ *   - .gsd-t/contracts/stream-json-sink-contract.md v1.1.0 (frame shape)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const TRANSCRIPTS_DIRNAME = path.join('.gsd-t', 'transcripts');
+const INDEX_FILENAME = '.index.json';
+
+function _transcriptsDir(projectDir) {
+  return path.join(projectDir || '.', TRANSCRIPTS_DIRNAME);
+}
+
+function _indexPath(projectDir) {
+  return path.join(_transcriptsDir(projectDir), INDEX_FILENAME);
+}
+
+function _ensureDir(p) {
+  if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
+}
+
+/**
+ * Allocate a hierarchical spawn-id. Shape: `{parent-prefix}-{short}` where
+ * `short` is an 8-char hex from a random UUID. Root spawns get no prefix.
+ *
+ * @param {object} [opts]
+ * @param {string|null} [opts.parentId]
+ * @returns {string}
+ */
+function allocateSpawnId(opts) {
+  const parentId = opts && opts.parentId ? String(opts.parentId) : null;
+  const short = crypto.randomBytes(4).toString('hex');
+  return parentId ? `${parentId}.${short}` : `s-${short}`;
+}
+
+function _readIndex(projectDir) {
+  const p = _indexPath(projectDir);
+  if (!fs.existsSync(p)) return { spawns: [] };
+  try {
+    const raw = fs.readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.spawns)) return { spawns: [] };
+    return parsed;
+  } catch (_) {
+    return { spawns: [] };
+  }
+}
+
+function _writeIndex(projectDir, idx) {
+  const p = _indexPath(projectDir);
+  _ensureDir(path.dirname(p));
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(idx, null, 2));
+  fs.renameSync(tmp, p);
+}
+
+/**
+ * Register a new transcript + create the ndjson file.
+ *
+ * @param {object} opts
+ * @param {string} opts.spawnId
+ * @param {string} [opts.projectDir='.']
+ * @param {object} [opts.meta]           { parentId?, command?, description?, workerPid?, model? }
+ * @returns {{spawnId, transcriptPath, startedAt}}
+ */
+function openTranscript(opts) {
+  if (!opts || !opts.spawnId) throw new Error('openTranscript: spawnId required');
+  const projectDir = opts.projectDir || '.';
+  const meta = opts.meta || {};
+  const dir = _transcriptsDir(projectDir);
+  _ensureDir(dir);
+
+  const transcriptPath = path.join(dir, `${opts.spawnId}.ndjson`);
+  if (!fs.existsSync(transcriptPath)) {
+    fs.writeFileSync(transcriptPath, '');
+  }
+
+  const startedAt = new Date().toISOString();
+  const entry = {
+    spawnId: opts.spawnId,
+    parentId: meta.parentId || null,
+    command: meta.command || null,
+    description: meta.description || null,
+    model: meta.model || null,
+    workerPid: meta.workerPid || null,
+    startedAt,
+    endedAt: null,
+    status: 'running',
+  };
+
+  const idx = _readIndex(projectDir);
+  const existing = idx.spawns.findIndex((s) => s.spawnId === opts.spawnId);
+  if (existing >= 0) {
+    idx.spawns[existing] = { ...idx.spawns[existing], ...entry };
+  } else {
+    idx.spawns.push(entry);
+  }
+  _writeIndex(projectDir, idx);
+
+  return { spawnId: opts.spawnId, transcriptPath, startedAt };
+}
+
+/**
+ * Append a single frame (already JSON-serializable) to the transcript.
+ * `frame` may be a parsed object OR a raw string line — strings are wrapped
+ * as `{type:"raw",line}` so the ndjson shape stays uniform.
+ *
+ * @param {object} opts
+ * @param {string} opts.spawnId
+ * @param {string} [opts.projectDir='.']
+ * @param {object|string} opts.frame
+ */
+function appendFrame(opts) {
+  if (!opts || !opts.spawnId) throw new Error('appendFrame: spawnId required');
+  if (opts.frame === undefined || opts.frame === null) return;
+  const projectDir = opts.projectDir || '.';
+  const p = path.join(_transcriptsDir(projectDir), `${opts.spawnId}.ndjson`);
+  _ensureDir(path.dirname(p));
+
+  let line;
+  if (typeof opts.frame === 'string') {
+    const trimmed = opts.frame.trim();
+    if (!trimmed) return;
+    try {
+      JSON.parse(trimmed);
+      line = trimmed;
+    } catch (_) {
+      line = JSON.stringify({ type: 'raw', line: opts.frame });
+    }
+  } else {
+    try {
+      line = JSON.stringify(opts.frame);
+    } catch (_) {
+      line = JSON.stringify({ type: 'raw', line: String(opts.frame) });
+    }
+  }
+  fs.appendFileSync(p, line + '\n');
+}
+
+/**
+ * Mark a transcript as ended. Idempotent — subsequent calls update endedAt.
+ *
+ * @param {object} opts
+ * @param {string} opts.spawnId
+ * @param {string} [opts.projectDir='.']
+ * @param {'done'|'failed'|'stopped'|'ended'} [opts.status='ended']
+ */
+function closeTranscript(opts) {
+  if (!opts || !opts.spawnId) throw new Error('closeTranscript: spawnId required');
+  const projectDir = opts.projectDir || '.';
+  const idx = _readIndex(projectDir);
+  const i = idx.spawns.findIndex((s) => s.spawnId === opts.spawnId);
+  if (i < 0) return false;
+  idx.spawns[i].endedAt = new Date().toISOString();
+  idx.spawns[i].status = opts.status || 'ended';
+  _writeIndex(projectDir, idx);
+  return true;
+}
+
+/**
+ * List registered spawns (most recent first).
+ *
+ * @param {string} [projectDir='.']
+ * @returns {Array<object>}
+ */
+function listTranscripts(projectDir) {
+  const idx = _readIndex(projectDir || '.');
+  return idx.spawns.slice().sort((a, b) => {
+    const ta = Date.parse(a.startedAt) || 0;
+    const tb = Date.parse(b.startedAt) || 0;
+    return tb - ta;
+  });
+}
+
+function readTranscriptMeta(projectDir, spawnId) {
+  const idx = _readIndex(projectDir || '.');
+  return idx.spawns.find((s) => s.spawnId === spawnId) || null;
+}
+
+/**
+ * Tee a stream-json stdout stream. Returns an `onChunk(buffer)` callback that
+ * you feed chunks to (typed as Buffer or string). Frames are split at `\n`
+ * and each complete line is written to the transcript ndjson. Incomplete
+ * tails are buffered until the next chunk.
+ *
+ * Returns also a `flush()` to call on child exit — writes any stranded tail
+ * as a single `{type:"raw"}` line so nothing is dropped.
+ *
+ * @param {object} opts
+ * @param {string} opts.spawnId
+ * @param {string} [opts.projectDir='.']
+ * @returns {{onChunk: (chunk) => void, flush: () => void}}
+ */
+function makeStreamTee(opts) {
+  if (!opts || !opts.spawnId) throw new Error('makeStreamTee: spawnId required');
+  const projectDir = opts.projectDir || '.';
+  const spawnId = opts.spawnId;
+  let buf = '';
+
+  return {
+    onChunk(chunk) {
+      if (chunk == null) return;
+      buf += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+      let nl;
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (line.length > 0) appendFrame({ spawnId, projectDir, frame: line });
+      }
+    },
+    flush() {
+      if (buf.length > 0) {
+        appendFrame({ spawnId, projectDir, frame: buf });
+        buf = '';
+      }
+    },
+  };
+}
+
+module.exports = {
+  allocateSpawnId,
+  openTranscript,
+  appendFrame,
+  closeTranscript,
+  listTranscripts,
+  readTranscriptMeta,
+  makeStreamTee,
+  _readIndex,
+  _writeIndex,
+  TRANSCRIPTS_DIRNAME,
+  INDEX_FILENAME,
+};