@tekyzinc/gsd-t 3.29.11 → 4.0.12

package/bin/runway-estimator.cjs

@@ -1,242 +0,0 @@
-'use strict';
-/**
- * GSD-T Runway Estimator (M43 D5 — dialog-channel growth meter)
- *
- * Under M43's channel-separation model, the only thing that runs in the
- * in-session channel is the `/gsd` router dialog. Everything else spawns.
- * This module reads the per-turn usage rows the M43 D1 capture writes to
- * `.gsd-t/metrics/token-usage.jsonl` (schema v2) and surfaces a one-line
- * "~N turns to `/compact`" warning to the router.
- *
- * Scope (revised 2026-04-21 per M43 partition.md §D5):
- *   - Read-only. Never refuses, never reroutes. Under always-headless there
- *     is nothing to reroute *to*.
- *   - Median-of-deltas growth slope (outlier-resistant; a single spike turn
- *     does not flip `shouldWarn`).
- *   - Zero external deps. `.cjs` so it loads in both ESM-default projects
- *     and CJS projects without transpilation.
- *
- * Contracts:
- *   - .gsd-t/contracts/context-meter-contract.md §Dialog Growth Meter
- *   - .gsd-t/contracts/metrics-schema-contract.md (schema v2)
- *
- * Consumers:
- *   - commands/gsd.md (router warning footer)
- */
-
-const fs = require('fs');
-const path = require('path');
-const { SAFE_DEFAULT_WINDOW } = require('./model-windows.cjs');
-
-const DEFAULT_K = 5;
-// The model context cap IS the model's true window. Default to the model-aware
-// safe LARGE window (1M) — the old 200K literal was correct only for pre-4
-// models and made turn-to-compact predictions fire 5× too early on Opus/Sonnet.
-// Callers may still pass an explicit `modelContextCap`, and resolveContextCap()
-// below prefers a fresh Context Meter reading when available.
-const DEFAULT_MODEL_CONTEXT_CAP = SAFE_DEFAULT_WINDOW;
-// Claude Code starts auto-compacting ~8% before the model window fills, so the
-// effective dialog ceiling is 0.92 × modelContextCap.
-const PRE_COMPACT_HEADROOM = 0.92;
-// Context Meter state — its modelWindowSize is model-aware (bin/model-windows.cjs).
-const METER_STATE_REL = '.gsd-t/.context-meter-state.json';
-const METER_STATE_STALE_MS = 5 * 60 * 1000;
-
-/**
- * Resolve the effective model context cap. Priority:
- *   1. explicit opts.modelContextCap (caller override)
- *   2. fresh Context Meter state modelWindowSize (model-aware, written by the
- *      meter hook from the running model)
- *   3. DEFAULT_MODEL_CONTEXT_CAP (safe large fallback)
- */
-function resolveContextCap(projectDir, optCap) {
-  if (Number.isFinite(optCap) && optCap > 0) return optCap;
-  try {
-    const fp = path.join(projectDir || '.', METER_STATE_REL);
-    const s = JSON.parse(fs.readFileSync(fp, 'utf8'));
-    if (s && typeof s.modelWindowSize === 'number' && s.modelWindowSize > 0 && s.timestamp) {
-      const age = Date.now() - Date.parse(s.timestamp);
-      if (!isNaN(age) && age >= 0 && age <= METER_STATE_STALE_MS) {
-        return s.modelWindowSize;
-      }
-    }
-  } catch (_) { /* fall through to default */ }
-  return DEFAULT_MODEL_CONTEXT_CAP;
-}
-const DEFAULT_WARN_THRESHOLD_TURNS = 5;
-const MIN_HISTORY = 3;
-
-// ── Row loading ──────────────────────────────────────────────────────
-
-function _safeParse(line) {
-  const s = String(line || '').trim();
-  if (!s || s[0] !== '{') return null;
-  try { return JSON.parse(s); } catch (_) { return null; }
-}
-
-/**
- * Load in-session rows for the given session from the canonical sink.
- *
- * @param {string} projectDir
- * @param {string} sessionId
- * @returns {object[]}  schema-v2 rows, unsorted
- */
-function _loadInSessionRows(projectDir, sessionId) {
-  const p = path.join(projectDir, '.gsd-t', 'metrics', 'token-usage.jsonl');
-  if (!fs.existsSync(p)) return [];
-  let text;
-  try { text = fs.readFileSync(p, 'utf8'); } catch (_) { return []; }
-  const rows = [];
-  for (const line of text.split(/\r?\n/)) {
-    const j = _safeParse(line);
-    if (!j) continue;
-    if (j.sessionType !== 'in-session') continue;
-    if (sessionId != null && j.session_id !== sessionId) continue;
-    rows.push(j);
-  }
-  return rows;
-}
-
-// ── Math helpers ─────────────────────────────────────────────────────
-
-function _median(arr) {
-  if (!arr.length) return 0;
-  const sorted = arr.slice().sort((a, b) => a - b);
-  const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
-}
-
-/**
- * Deterministic ordering for per-turn rows. Prefers timestamp (`ts`) when
- * present (monotonic per session), falls back to `turn_id` string compare.
- */
-function _sortTurns(rows) {
-  return rows.slice().sort((a, b) => {
-    const ta = a.ts || '';
-    const tb = b.ts || '';
-    if (ta !== tb) return ta < tb ? -1 : 1;
-    const ia = String(a.turn_id || '');
-    const ib = String(b.turn_id || '');
-    if (ia !== ib) return ia < ib ? -1 : 1;
-    return 0;
-  });
-}
-
-/**
- * Compute the dialog-growth signal for one session.
- *
- * Reads the last K in-session turns for `sessionId` from
- * `.gsd-t/metrics/token-usage.jsonl`, computes the median of turn-over-turn
- * `input_tokens` deltas (robust to single-turn spikes), then predicts how
- * many turns remain before dialog input crosses the pre-auto-compact ceiling
- * (`modelContextCap × 0.92`).
- *
- * Returns `{ shouldWarn: false, reason: 'insufficient_history' }` when fewer
- * than `MIN_HISTORY` in-session turns exist for the session.
- *
- * @param {object} opts
- * @param {string} opts.projectDir
- * @param {string} opts.sessionId                required
- * @param {number} [opts.k]                      default 5 (last K turns)
- * @param {number} [opts.modelContextCap]        default: fresh Context Meter
- *        modelWindowSize if available, else the model-aware safe window (1M)
- * @param {number} [opts.warnThresholdTurns]     default 5
- * @returns {{
- *   shouldWarn: boolean,
- *   slope: number,
- *   median_delta: number,
- *   latest_input_tokens: number,
- *   predicted_turns_to_compact: number,
- *   k: number,
- *   history_len: number,
- *   reason?: string
- * }}
- */
-function estimateDialogGrowth(opts) {
-  const projectDir = (opts && opts.projectDir) || '.';
-  const sessionId = opts && opts.sessionId;
-  const k = (opts && Number.isFinite(opts.k) && opts.k > 0) ? Math.floor(opts.k) : DEFAULT_K;
-  const cap = resolveContextCap(projectDir, opts && opts.modelContextCap);
-  const warnThreshold = (opts && Number.isFinite(opts.warnThresholdTurns) && opts.warnThresholdTurns > 0)
-    ? opts.warnThresholdTurns
-    : DEFAULT_WARN_THRESHOLD_TURNS;
-
-  const empty = {
-    shouldWarn: false,
-    slope: 0,
-    median_delta: 0,
-    latest_input_tokens: 0,
-    predicted_turns_to_compact: Infinity,
-    k,
-    history_len: 0,
-  };
-
-  if (!sessionId) {
-    return { ...empty, reason: 'missing_session_id' };
-  }
-
-  const allRows = _loadInSessionRows(projectDir, sessionId);
-  if (allRows.length === 0) {
-    return { ...empty, reason: 'no_rows' };
-  }
-
-  const sorted = _sortTurns(allRows);
-  const window = sorted.slice(-k);
-
-  if (window.length < MIN_HISTORY) {
-    return { ...empty, history_len: window.length, reason: 'insufficient_history' };
-  }
-
-  // Per-turn input token footprint. Schema v2 writes `inputTokens` (camel)
-  // via the token-capture wrapper; older rows may carry the raw envelope.
-  const inputs = window.map(r => {
-    if (Number.isFinite(r.inputTokens)) return r.inputTokens;
-    if (r.usage && Number.isFinite(r.usage.input_tokens)) return r.usage.input_tokens;
-    return 0;
-  });
-
-  const deltas = [];
-  for (let i = 1; i < inputs.length; i++) {
-    deltas.push(inputs[i] - inputs[i - 1]);
-  }
-
-  const median_delta = _median(deltas);
-  const slope = median_delta;
-  const latest_input_tokens = inputs[inputs.length - 1];
-
-  const ceiling = cap * PRE_COMPACT_HEADROOM;
-  let predicted_turns_to_compact;
-  if (slope > 0) {
-    const headroom = ceiling - latest_input_tokens;
-    predicted_turns_to_compact = headroom <= 0 ? 0 : Math.ceil(headroom / slope);
-  } else {
-    predicted_turns_to_compact = Infinity;
-  }
-
-  const shouldWarn = Number.isFinite(predicted_turns_to_compact) && predicted_turns_to_compact <= warnThreshold;
-
-  return {
-    shouldWarn,
-    slope,
-    median_delta,
-    latest_input_tokens,
-    predicted_turns_to_compact,
-    k,
-    history_len: window.length,
-  };
-}
-
-module.exports = {
-  estimateDialogGrowth,
-  // Exposed for unit tests; not part of the stable contract.
-  _internal: {
-    _median,
-    _sortTurns,
-    _loadInSessionRows,
-    DEFAULT_K,
-    DEFAULT_MODEL_CONTEXT_CAP,
-    PRE_COMPACT_HEADROOM,
-    DEFAULT_WARN_THRESHOLD_TURNS,
-    MIN_HISTORY,
-  },
-};

package/bin/spawn-plan-derive.cjs

@@ -1,163 +0,0 @@
-'use strict';
-
-/**
- * GSD-T Spawn Plan Derive (M44 D8 T4)
- *
- * Deterministic projection of `.gsd-t/partition.md` + `.gsd-t/domains/*\/tasks.md`
- * into the current "incomplete tasks" slice. No LLM calls, no prompts, no
- * heuristics — just parsing + slicing.
- *
- * Contract: .gsd-t/contracts/spawn-plan-contract.md v1.0.0
- *
- * Consumed by: `bin/spawn-plan-writer.cjs` (when caller does NOT pass an
- * explicit `tasks: [...]` array).
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Derive a `{milestone, wave, domains, tasks}` slice from on-disk partition
- * + tasks. The "current incomplete slice" is the next contiguous run of
- * tasks whose checkboxes are still unchecked (`[ ]`) across all domains in
- * the current wave.
- *
- * Gracefully returns an empty slice when partition.md is absent or no
- * incomplete tasks remain. Never throws for missing files.
- *
- * @param {object} [opts]
- * @param {string} [opts.projectDir='.']
- * @param {string} [opts.milestone]       filter hint (e.g. 'M44'); defaults to parsed from partition
- * @param {string|number} [opts.currentIter]   unused today; reserved for future iter-slicing
- * @returns {{ milestone: string|null, wave: string|null, domains: string[], tasks: Array<{id:string,title:string,status:string}> }}
- */
-function derivePlanFromPartition(opts) {
-  const projectDir = (opts && opts.projectDir) || '.';
-  const result = { milestone: null, wave: null, domains: [], tasks: [] };
-
-  const partitionPath = path.join(projectDir, '.gsd-t', 'partition.md');
-  if (!fs.existsSync(partitionPath)) {
-    return result;
-  }
-
-  let partitionText;
-  try {
-    partitionText = fs.readFileSync(partitionPath, 'utf8');
-  } catch (_) {
-    return result;
-  }
-
-  // Parse the milestone id (first `M\d+` in heading) and the wave we care
-  // about. For now we pick the first wave with any incomplete tasks.
-  const milestoneMatch = partitionText.match(/\b(M\d+)\b/);
-  if (milestoneMatch) result.milestone = milestoneMatch[1];
-  if (opts && opts.milestone) result.milestone = String(opts.milestone);
-
-  // Enumerate domain dirs under .gsd-t/domains/
-  const domainsRoot = path.join(projectDir, '.gsd-t', 'domains');
-  const domains = _listDomains(domainsRoot, result.milestone);
-  if (!domains.length) return result;
-
-  // Collect incomplete tasks from each domain's tasks.md, grouped by wave.
-  // If no explicit wave header is present, "unknown" groups them.
-  const byWave = new Map();
-  for (const d of domains) {
-    const tasks = _parseTasks(path.join(domainsRoot, d, 'tasks.md'));
-    for (const t of tasks) {
-      if (!byWave.has(t.wave)) byWave.set(t.wave, []);
-      byWave.get(t.wave).push({ ...t, domain: d });
-    }
-  }
-
-  // Pick the wave with the most incomplete tasks; ties: first seen.
-  let pickWave = null;
-  let pickCount = -1;
-  for (const [w, arr] of byWave) {
-    const incomplete = arr.filter((t) => t.status !== 'done').length;
-    if (incomplete > pickCount) {
-      pickCount = incomplete;
-      pickWave = w;
-    }
-  }
-  if (pickWave == null) return result;
-
-  const waveTasks = byWave.get(pickWave) || [];
-  result.wave = pickWave;
-  const seenDomains = new Set();
-  for (const t of waveTasks) {
-    if (t.domain) seenDomains.add(t.domain);
-    result.tasks.push({
-      id: t.id,
-      title: t.title,
-      status: t.status,
-    });
-  }
-  result.domains = [...seenDomains];
-  return result;
-}
-
-// ── internal parsers ──────────────────────────────────────────────────────
-
-function _listDomains(dir, milestone) {
-  if (!fs.existsSync(dir)) return [];
-  let entries;
-  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return []; }
-  const names = [];
-  for (const e of entries) {
-    if (!e.isDirectory()) continue;
-    if (milestone) {
-      // Normalize to lowercase m-prefix so we match `m44-d8-…`
-      const prefix = String(milestone).toLowerCase() + '-';
-      if (!e.name.toLowerCase().startsWith(prefix)) continue;
-    }
-    names.push(e.name);
-  }
-  return names.sort();
-}
-
-/**
- * Parse a domain tasks.md into a list of `{id, title, status, wave}`.
- * Recognizes:
- *   `- [ ] **M44-D8-T1** — title…`
- *   `- [x] **M44-D8-T1** — title…`
- *   `- [x] done (2026-04-23 · commit abc123) **M44-D8-T1** — title…`
- * Task-id pattern is `M\d+-D\d+-T\d+`. Wave comes from the nearest
- * preceding `## Wave N` header.
- */
-function _parseTasks(tasksPath) {
-  if (!fs.existsSync(tasksPath)) return [];
-  let text;
-  try { text = fs.readFileSync(tasksPath, 'utf8'); } catch (_) { return []; }
-
-  const out = [];
-  let currentWave = 'unknown';
-  const lines = text.split('\n');
-  for (const line of lines) {
-    const waveMatch = line.match(/^##\s+Wave\s+(\d+)\b/i);
-    if (waveMatch) {
-      currentWave = 'wave-' + waveMatch[1];
-      continue;
-    }
-    const m = line.match(/^-\s*\[([ xX])\][^\*]*\*\*(M\d+-D\d+-T\d+)\*\*\s*[—-]\s*(.+)$/);
-    if (!m) continue;
-    const checked = m[1].toLowerCase() === 'x';
-    const id = m[2];
-    let title = m[3].trim();
-    // Strip trailing " — sub-note" if present; keep only the primary title.
-    // The task title may contain em-dashes; safer to just use the first line.
-    title = title.split(/\s{2,}/)[0].trim();
-    out.push({
-      id,
-      title,
-      status: checked ? 'done' : 'pending',
-      wave: currentWave,
-    });
-  }
-  return out;
-}
-
-module.exports = {
-  derivePlanFromPartition,
-  _parseTasks,
-  _listDomains,
-};

package/bin/spawn-plan-status-updater.cjs

@@ -1,292 +0,0 @@
-'use strict';
-
-/**
- * GSD-T Spawn Plan Status Updater (M44 D8 T2)
- *
- * Pure module — patches spawn-plan files written by spawn-plan-writer.cjs.
- * Called by the post-commit git hook and by `captureSpawn` on completion.
- *
- * Contract: .gsd-t/contracts/spawn-plan-contract.md v1.0.0
- *
- * Hard rules:
- *   - Atomic rewrites only (temp file + rename)
- *   - No-op on unknown spawnId or unknown taskId — observability is best-effort
- *   - Never throw for missing files; callers rely on silent-fail behavior
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const SPAWNS_SUBDIR = path.join('.gsd-t', 'spawns');
-
-/**
- * Patch `{spawnId}.json`: find the task with the given id and flip its
- * status to `done`, recording the commit SHA and (optional) token
- * attribution. If the next pending task exists, promote it to
- * `in_progress` so the single-active-task invariant is preserved.
- *
- * @param {object} opts
- * @param {string} opts.spawnId
- * @param {string} opts.taskId
- * @param {string} [opts.commit]                         short or full SHA
- * @param {object|null} [opts.tokens]                    `{in,out,cr,cc,cost_usd}` or null
- * @param {string} [opts.projectDir='.']
- * @returns {{ patched: boolean, path: string }}
- */
-function markTaskDone(opts) {
-  if (!opts || typeof opts !== 'object') return { patched: false, path: null };
-  const { spawnId, taskId } = opts;
-  if (!spawnId || !taskId) return { patched: false, path: null };
-
-  const projectDir = opts.projectDir || '.';
-  const fp = _planPath(projectDir, spawnId);
-  const plan = _readPlan(fp);
-  if (!plan) return { patched: false, path: fp };
-
-  const tasks = Array.isArray(plan.tasks) ? plan.tasks : [];
-  const idx = tasks.findIndex((t) => t && t.id === taskId);
-  if (idx < 0) return { patched: false, path: fp };
-
-  const task = tasks[idx];
-  task.status = 'done';
-  if (typeof opts.commit === 'string' && opts.commit) task.commit = opts.commit;
-  // Token attribution is "null when absent" per constraints §Format rules.
-  // The caller passes `null` or an object; we never silently overwrite
-  // an already-populated tokens field with null.
-  if (Object.prototype.hasOwnProperty.call(opts, 'tokens')) {
-    if (opts.tokens && typeof opts.tokens === 'object') {
-      task.tokens = _normalizeTokens(opts.tokens);
-    } else if (task.tokens == null) {
-      task.tokens = null;
-    }
-  }
-
-  // Promote the next pending task to in_progress (single-active invariant).
-  const anyInProgress = tasks.some((t) => t && t.status === 'in_progress');
-  if (!anyInProgress) {
-    for (let j = idx + 1; j < tasks.length; j++) {
-      if (tasks[j] && tasks[j].status === 'pending') {
-        tasks[j].status = 'in_progress';
-        break;
-      }
-    }
-  }
-
-  _atomicWriteJson(fp, plan);
-  return { patched: true, path: fp };
-}
-
-/**
- * Mark a spawn plan as ended. Sets `endedAt` to now-ISO and records
- * `endedReason` ('success' | 'error' | caller-supplied). No-op on missing
- * file. Atomic rewrite.
- *
- * @param {object} opts
- * @param {string} opts.spawnId
- * @param {string} [opts.endedReason='success']
- * @param {string} [opts.projectDir='.']
- * @param {Date}   [opts.now]
- * @returns {{ patched: boolean, path: string }}
- */
-function markSpawnEnded(opts) {
-  if (!opts || typeof opts !== 'object') return { patched: false, path: null };
-  const { spawnId } = opts;
-  if (!spawnId) return { patched: false, path: null };
-
-  const projectDir = opts.projectDir || '.';
-  const fp = _planPath(projectDir, spawnId);
-  const plan = _readPlan(fp);
-  if (!plan) return { patched: false, path: fp };
-
-  const now = opts.now instanceof Date ? opts.now : new Date();
-  plan.endedAt = now.toISOString();
-  plan.endedReason = opts.endedReason || 'success';
-  _atomicWriteJson(fp, plan);
-  return { patched: true, path: fp };
-}
-
-/**
- * Enumerate active plan files (those where `endedAt === null`). Returns
- * absolute file paths, sorted by startedAt descending.
- *
- * @param {string} [projectDir='.']
- * @returns {string[]}
- */
-function listActivePlans(projectDir) {
-  const dir = path.join(projectDir || '.', SPAWNS_SUBDIR);
-  if (!fs.existsSync(dir)) return [];
-  let files;
-  try { files = fs.readdirSync(dir); } catch (_) { return []; }
-  const results = [];
-  for (const f of files) {
-    if (!f.endsWith('.json')) continue;
-    const fp = path.resolve(path.join(dir, f));
-    const plan = _readPlan(fp);
-    if (plan && plan.endedAt == null) results.push({ fp, plan });
-  }
-  results.sort((a, b) => {
-    const ta = Date.parse(a.plan && a.plan.startedAt || '') || 0;
-    const tb = Date.parse(b.plan && b.plan.startedAt || '') || 0;
-    return tb - ta;
-  });
-  return results.map((r) => r.fp);
-}
-
-// ── token-log attribution lookup ───────────────────────────────────────────
-
-/**
- * Parse `.gsd-t/token-log.md` and return the sum of `{in,out,cr,cc,cost_usd}`
- * across all rows whose `Task` column matches the given id and whose
- * `Datetime-start` is >= the spawn's startedAt.
- *
- * Returns `null` when no matching rows exist (per the "zero is a
- * measurement, dash is acknowledged gap" rule).
- *
- * @param {object} opts
- * @param {string} opts.projectDir
- * @param {string} opts.taskId
- * @param {string} opts.spawnStartedAt   ISO-8601 (matches plan.startedAt)
- * @param {string} [opts.tokenLogPath]   override for tests
- * @returns {{in:number, out:number, cr:number, cc:number, cost_usd:number}|null}
- */
-function sumTokensForTask(opts) {
-  if (!opts || typeof opts !== 'object') return null;
-  const { projectDir, taskId } = opts;
-  if (!projectDir || !taskId) return null;
-
-  const fp = opts.tokenLogPath || path.join(projectDir, '.gsd-t', 'token-log.md');
-  if (!fs.existsSync(fp)) return null;
-
-  const startMs = _parseDatetime(opts.spawnStartedAt);
-
-  let text;
-  try { text = fs.readFileSync(fp, 'utf8'); } catch (_) { return null; }
-
-  const lines = text.split('\n');
-  // Find header row to locate column indices.
-  const headerIdx = lines.findIndex((l) => /^\|\s*Datetime-start\s*\|/.test(l));
-  if (headerIdx < 0) return null;
-  const header = lines[headerIdx].split('|').map((s) => s.trim());
-  const iStart = header.indexOf('Datetime-start');
-  const iTokens = header.indexOf('Tokens');
-  const iTask = header.indexOf('Task');
-  if (iStart < 0 || iTask < 0) return null;
-
-  const sum = { in: 0, out: 0, cr: 0, cc: 0, cost_usd: 0 };
-  let matched = 0;
-  for (let i = headerIdx + 2; i < lines.length; i++) {
-    const row = lines[i];
-    if (!row || !row.startsWith('|')) continue;
-    const cells = row.split('|').map((s) => s.trim());
-    if (cells.length < header.length) continue;
-    const startedAt = cells[iStart] || '';
-    const task = cells[iTask] || '';
-    if (task !== taskId) continue;
-    // Only rows whose Datetime-start >= spawn.startedAt count.
-    if (startMs != null) {
-      const rowMs = _parseDatetime(startedAt);
-      if (rowMs != null && rowMs < startMs) continue;
-    }
-    const tokensCell = iTokens >= 0 ? (cells[iTokens] || '') : '';
-    const parsed = _parseTokensCell(tokensCell);
-    if (parsed) {
-      sum.in += parsed.in;
-      sum.out += parsed.out;
-      sum.cr += parsed.cr;
-      sum.cc += parsed.cc;
-      sum.cost_usd += parsed.cost_usd;
-      matched++;
-    } else {
-      // No token data in the row; still counts as a "match" for the task
-      // but contributes zero. Keep going.
-      matched++;
-    }
-  }
-  if (matched === 0) return null;
-  // Round cost to 2 decimals for determinism.
-  sum.cost_usd = Math.round(sum.cost_usd * 100) / 100;
-  return sum;
-}
-
-// ── internal helpers ───────────────────────────────────────────────────────
-
-function _planPath(projectDir, spawnId) {
-  return path.resolve(path.join(projectDir, SPAWNS_SUBDIR, spawnId + '.json'));
-}
-
-function _readPlan(fp) {
-  try {
-    const raw = fs.readFileSync(fp, 'utf8');
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    return parsed;
-  } catch (_) {
-    return null;
-  }
-}
-
-function _atomicWriteJson(targetPath, obj) {
-  const dir = path.dirname(targetPath);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  const tmp = targetPath + '.tmp-' + process.pid + '-' + Date.now();
-  const json = JSON.stringify(obj, null, 2) + '\n';
-  fs.writeFileSync(tmp, json);
-  fs.renameSync(tmp, targetPath);
-}
-
-function _normalizeTokens(t) {
-  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : Number(v) || 0);
-  return {
-    in: num(t.in != null ? t.in : t.input_tokens),
-    out: num(t.out != null ? t.out : t.output_tokens),
-    cr: num(t.cr != null ? t.cr : t.cache_read_input_tokens),
-    cc: num(t.cc != null ? t.cc : t.cache_creation_input_tokens),
-    cost_usd: num(
-      t.cost_usd != null
-        ? t.cost_usd
-        : (t.total_cost_usd != null ? t.total_cost_usd : 0)
-    ),
-  };
-}
-
-function _parseDatetime(s) {
-  if (!s) return null;
-  if (typeof s === 'string' && /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/.test(s)) {
-    const [d, t] = s.split(' ');
-    const ms = Date.parse(`${d}T${t}:00`);
-    return Number.isFinite(ms) ? ms : null;
-  }
-  const ms = Date.parse(s);
-  return Number.isFinite(ms) ? ms : null;
-}
-
-/**
- * Parse a tokens cell of the form `in=N out=N cr=N cc=N $X.XX` or `—`
- * or a mixed form. Returns null when no numeric data is present.
- */
-function _parseTokensCell(cell) {
-  if (!cell || cell === '—' || cell === '-') return null;
-  const num = (re) => {
-    const m = cell.match(re);
-    return m ? Number(m[1]) : 0;
-  };
-  const inp = num(/\bin=(\d+)/);
-  const out = num(/\bout=(\d+)/);
-  const cr = num(/\bcr=(\d+)/);
-  const cc = num(/\bcc=(\d+)/);
-  const costM = cell.match(/\$(\d+(?:\.\d+)?)/);
-  const cost_usd = costM ? Number(costM[1]) : 0;
-  if (!inp && !out && !cr && !cc && !cost_usd) return null;
-  return { in: inp, out, cr, cc, cost_usd };
-}
-
-module.exports = {
-  markTaskDone,
-  markSpawnEnded,
-  listActivePlans,
-  sumTokensForTask,
-  // test-only
-  _parseTokensCell,
-  _parseDatetime,
-  _normalizeTokens,
-};