@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/doctor/index.mjs

@@ -0,0 +1,140 @@
+/**
+ * lib/doctor/index.mjs — `construct-doctor` daemon main loop.
+ *
+ * Long-running Node process spawned by `construct up`. Holds the L0 watchers
+ * for resource pressure, service health, disk + log rotation, and cost. Each
+ * watcher ticks on its own interval; the loop is bounded so a slow watcher
+ * never starves the others. Termination via SIGTERM/SIGINT triggers a clean
+ * shutdown that records a final audit entry.
+ *
+ * State file: ~/.construct/doctor.json (pid, started, lastTick).
+ * Audit log:  ~/.cx/doctor-log.jsonl.
+ */
+
+import { writeFileSync, existsSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { record } from './audit.mjs';
+import * as disk from './watchers/disk.mjs';
+import * as cost from './watchers/cost.mjs';
+import * as processPressure from './watchers/process-pressure.mjs';
+import * as serviceHealth from './watchers/service-health.mjs';
+import * as bdWatch from './watchers/bd-watch.mjs';
+import * as handoffs from './watchers/handoffs.mjs';
+
+const STATE_PATH = join(homedir(), '.construct', 'doctor.json');
+const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs];
+
+let running = false;
+let timers = [];
+let lastTickAt = {};
+
+function writeState(state) {
+  const dir = join(homedir(), '.construct');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(STATE_PATH, JSON.stringify({ ...state, updatedAt: Date.now() }));
+}
+
+function clearState() {
+  if (existsSync(STATE_PATH)) {
+    try { unlinkSync(STATE_PATH); } catch { /* best effort */ }
+  }
+}
+
+function processAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export function readState() {
+  if (!existsSync(STATE_PATH)) return null;
+  try {
+    const state = JSON.parse(readFileSync(STATE_PATH, 'utf8'));
+    if (!processAlive(state.pid)) {
+      clearState();
+      return null;
+    }
+    return state;
+  } catch { return null; }
+}
+
+async function runWatcher(watcher) {
+  if (!running) return;
+  const startedAt = Date.now();
+  try {
+    const result = await watcher.tick();
+    lastTickAt[watcher.name] = startedAt;
+    const tookMs = Date.now() - startedAt;
+    if (process.env.CONSTRUCT_DOCTOR_VERBOSE === '1') {
+      process.stderr.write(
+        `[doctor] ${watcher.name} ok ${tookMs}ms actions=${result.actions?.length || 0} escalations=${result.escalations?.length || 0}\n`
+      );
+    }
+  } catch (err) {
+    record({
+      kind: 'error',
+      watcher: watcher.name,
+      result: 'failed',
+      summary: `tick failed: ${err.message || err}`,
+      context: { stack: String(err.stack || '').slice(0, 1024) },
+    });
+  }
+}
+
+export async function start() {
+  if (running) return;
+  running = true;
+  lastTickAt = {};
+
+  writeState({ pid: process.pid, startedAt: Date.now(), watchers: WATCHERS.map((w) => w.name) });
+  record({
+    kind: 'lifecycle',
+    watcher: 'doctor',
+    action: 'start',
+    summary: `doctor started (pid ${process.pid}, ${WATCHERS.length} watchers)`,
+    context: { watchers: WATCHERS.map((w) => ({ name: w.name, intervalMs: w.intervalMs })) },
+  });
+
+  for (const watcher of WATCHERS) {
+    await runWatcher(watcher);
+    const t = setInterval(() => { runWatcher(watcher); }, watcher.intervalMs);
+    if (t.unref) t.unref();
+    timers.push(t);
+  }
+
+  const shutdown = (signal) => {
+    record({ kind: 'lifecycle', watcher: 'doctor', action: 'stop', summary: `doctor stopped (signal=${signal})` });
+    stop();
+    process.exit(0);
+  };
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+
+export function stop() {
+  running = false;
+  for (const t of timers) clearInterval(t);
+  timers = [];
+  clearState();
+}
+
+export function statusSnapshot() {
+  const state = readState();
+  return {
+    running: !!state,
+    state,
+    watchers: WATCHERS.map((w) => ({
+      name: w.name,
+      intervalMs: w.intervalMs,
+      lastTickAt: lastTickAt[w.name] || null,
+    })),
+  };
+}
+
+const isMain = (() => {
+  try { return import.meta.url === `file://${process.argv[1]}`; } catch { return false; }
+})();
+if (isMain) {
+  await start();
+}

package/lib/doctor/report.mjs

@@ -0,0 +1,170 @@
+/**
+ * lib/doctor/report.mjs — M1 self-host measurement reporter.
+ *
+ * Tallies what the L0 doctor and L1 role framework actually did over a window.
+ * Evaluates the "Construct runs on Construct" milestones (M1 = SRE-only,
+ * 7 days unattended; later milestones add more personas). Pure read-only —
+ * scans the JSONL audit logs and ledgers and produces a markdown summary.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { recent } from './audit.mjs';
+import { getTotalDailySpend, getDailySpend, totalBudget, personaBudget, dayKey } from '../cost-ledger.mjs';
+
+function parseWindow(arg) {
+  const m = /^(\d+)([dhm])$/.exec(arg || '7d');
+  if (!m) return 7 * 24 * 60 * 60 * 1000;
+  const n = parseInt(m[1], 10);
+  const unit = m[2];
+  return n * (unit === 'd' ? 86400_000 : unit === 'h' ? 3600_000 : 60_000);
+}
+
+function readJsonl(p) {
+  if (!existsSync(p)) return [];
+  return readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
+    try { return JSON.parse(l); } catch { return null; }
+  }).filter(Boolean);
+}
+
+function groupBy(arr, fn) {
+  const out = {};
+  for (const x of arr) {
+    const k = fn(x) || 'unknown';
+    out[k] = (out[k] || 0) + 1;
+  }
+  return out;
+}
+
+function summarizeActions(auditEntries) {
+  const actions = auditEntries.filter((e) => e.kind === 'action');
+  const escalations = auditEntries.filter((e) => e.kind === 'escalate');
+  const samples = auditEntries.filter((e) => e.kind === 'sample');
+  const recoveries = auditEntries.filter((e) => e.kind === 'recovery');
+  const errors = auditEntries.filter((e) => e.kind === 'error');
+  return {
+    actions: { total: actions.length, byWatcher: groupBy(actions, (e) => e.watcher), byAction: groupBy(actions, (e) => e.action) },
+    escalations: { total: escalations.length, byWatcher: groupBy(escalations, (e) => e.watcher), byEvent: groupBy(escalations, (e) => e.target) },
+    samples: { total: samples.length, byWatcher: groupBy(samples, (e) => e.watcher) },
+    recoveries: { total: recoveries.length, byWatcher: groupBy(recoveries, (e) => e.watcher) },
+    errors: { total: errors.length, byWatcher: groupBy(errors, (e) => e.watcher) },
+  };
+}
+
+function fmtTable(title, obj) {
+  const entries = Object.entries(obj || {}).sort((a, b) => b[1] - a[1]);
+  if (entries.length === 0) return `${title}: (none)\n`;
+  let out = `${title}:\n`;
+  for (const [k, v] of entries) out += `  ${String(v).padStart(4, ' ')}  ${k}\n`;
+  return out;
+}
+
+export async function runReport(args = []) {
+  const windowArg = args.find((a) => a.startsWith('--since='))?.split('=')[1] || '7d';
+  const windowMs = parseWindow(windowArg);
+  const since = Date.now() - windowMs;
+
+  const auditEntries = recent({ since, limit: 10000 });
+  const events = readJsonl(join(homedir(), '.cx', 'events.jsonl')).filter((e) => e.ts >= since);
+  const pending = readJsonl(join(homedir(), '.cx', 'role-pending.jsonl')).filter((e) => e.ts >= since);
+
+  const summary = summarizeActions(auditEntries);
+  const eventsByType = groupBy(events, (e) => e.type);
+  const pendingByPersona = groupBy(pending, (e) => e.cxId);
+  const pendingUnresolved = pending.filter((e) => !e.resolvedAt);
+
+  const personas = ['sre', 'qa', 'security', 'docs-keeper', 'engineer'];
+  const costByPersona = {};
+  for (const p of personas) {
+    const s = getDailySpend({ personaId: p });
+    costByPersona[p] = { spent: s.costUsd, cap: personaBudget(p), invocations: s.invocations };
+  }
+  const total = getTotalDailySpend();
+
+  const lines = [];
+  lines.push(`# Construct-on-Construct measurement — window: ${windowArg}`);
+  lines.push(``);
+  lines.push(`Window: ${new Date(since).toISOString()} → ${new Date().toISOString()}`);
+  lines.push(``);
+  lines.push(`## L0 — Deterministic doctor actions`);
+  lines.push(``);
+  lines.push(`Total actions: ${summary.actions.total}`);
+  lines.push('```');
+  lines.push(fmtTable('By watcher', summary.actions.byWatcher).trim());
+  lines.push(fmtTable('By action', summary.actions.byAction).trim());
+  lines.push(fmtTable('Recoveries (services that came back)', summary.recoveries.byWatcher).trim());
+  lines.push(fmtTable('Errors (watcher tick failures)', summary.errors.byWatcher).trim());
+  lines.push('```');
+  lines.push(``);
+  lines.push(`## L0 → L1 escalations`);
+  lines.push(``);
+  lines.push(`Total escalations: ${summary.escalations.total}`);
+  lines.push('```');
+  lines.push(fmtTable('By watcher', summary.escalations.byWatcher).trim());
+  lines.push(fmtTable('By event type', summary.escalations.byEvent).trim());
+  lines.push('```');
+  lines.push(``);
+  lines.push(`## L1 — Role framework`);
+  lines.push(``);
+  lines.push(`Events emitted: ${events.length}`);
+  lines.push('```');
+  lines.push(fmtTable('By event type', eventsByType).trim());
+  lines.push('```');
+  lines.push(``);
+  lines.push(`Pending invocations created: ${pending.length}  ·  unresolved: ${pendingUnresolved.length}`);
+  lines.push('```');
+  lines.push(fmtTable('By persona', pendingByPersona).trim());
+  lines.push('```');
+  lines.push(``);
+  lines.push(`## Cost (today, ${dayKey()})`);
+  lines.push(``);
+  lines.push(`Total: $${total.costUsd.toFixed(4)} / $${totalBudget().toFixed(2)} cap  ·  ${total.invocations} invocations`);
+  lines.push(``);
+  for (const p of personas) {
+    const c = costByPersona[p];
+    if (c.invocations === 0 && c.spent === 0) continue;
+    lines.push(`- cx-${p}: $${c.spent.toFixed(4)} / $${c.cap.toFixed(2)}  ·  ${c.invocations} invocations`);
+  }
+  lines.push(``);
+
+  const pricingSources = {};
+  for (const e of auditEntries) {
+    if (e.kind === 'action' && e.action === 'ledger-sync' && e.context?.sources) {
+      for (const [src, n] of Object.entries(e.context.sources)) {
+        pricingSources[src] = (pricingSources[src] || 0) + n;
+      }
+    }
+  }
+  if (Object.keys(pricingSources).length > 0) {
+    const total = Object.values(pricingSources).reduce((a, b) => a + b, 0);
+    const staticPct = total > 0 ? Math.round(((pricingSources['estimated:static'] || 0) / total) * 100) : 0;
+    lines.push(`Pricing sources: ${Object.entries(pricingSources).map(([s, n]) => `${s}=${n}`).join(', ')}`);
+    if (staticPct >= 50) {
+      lines.push(`⚠ ${staticPct}% of entries priced from static fallback — telemetry model sync may be inactive; absolute spend is approximate. Run \`construct status\` to check telemetry integration.`);
+    }
+    lines.push(``);
+  }
+  lines.push(`## Health verdict`);
+  lines.push(``);
+  const verdicts = [];
+  if (summary.actions.total === 0 && summary.samples.total === 0) {
+    verdicts.push('⚠ No audit entries in window — doctor may not be running. Verify with \`construct doctor status\`.');
+  } else if (summary.samples.total === 0) {
+    verdicts.push('⚠ Actions logged but no samples — watchers may be partially failing. Check `construct doctor logs`.');
+  } else {
+    verdicts.push('✓ Doctor produced samples and actions in window.');
+  }
+  if (summary.errors.total > 0) {
+    verdicts.push(`⚠ ${summary.errors.total} watcher errors in window — see audit log.`);
+  }
+  if (pendingUnresolved.length > 0) {
+    verdicts.push(`→ ${pendingUnresolved.length} unresolved pending invocations — Construct should dispatch these on next session.`);
+  }
+  if (total.costUsd / totalBudget() > 0.5) {
+    verdicts.push(`⚠ Daily cost is ${Math.round((total.costUsd / totalBudget()) * 100)}% of cap — review burn rate.`);
+  }
+  for (const v of verdicts) lines.push(`- ${v}`);
+  return lines.join('\n');
+}

package/lib/doctor/watchers/bd-watch.mjs

@@ -0,0 +1,117 @@
+/**
+ * lib/doctor/watchers/bd-watch.mjs — periodic bd state poller for handoffs.
+ *
+ * Every 5 min, polls bd for open issues labeled `next:cx-<role>` where the
+ * target persona is onboarded in the role framework. Newly-seen issues are
+ * enqueued as pending invocations so session-start surfaces them to
+ * Construct. Seen issues are remembered in ~/.cx/bd-watch-seen.json to
+ * prevent re-emission while the label remains.
+ *
+ * Closes a gap in agent-tracker: agent-tracker only catches handoffs that
+ * appear in Task result text. bd-watch catches every handoff that exists
+ * as a label, regardless of how it got there (manual, ai, automated).
+ */
+
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { record } from '../audit.mjs';
+import { listOnboardedPersonas, loadManifest } from '../../roles/manifest.mjs';
+
+export const name = 'bd-watch';
+export const intervalMs = 5 * 60 * 1000;
+
+const SEEN_PATH = join(homedir(), '.cx', 'bd-watch-seen.json');
+const PENDING_PATH = join(homedir(), '.cx', 'role-pending.jsonl');
+
+function ensureDir() {
+  const dir = join(homedir(), '.cx');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function loadSeen() {
+  if (!existsSync(SEEN_PATH)) return {};
+  try { return JSON.parse(readFileSync(SEEN_PATH, 'utf8')); } catch { return {}; }
+}
+function saveSeen(state) {
+  ensureDir();
+  const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
+  const trimmed = {};
+  for (const [k, v] of Object.entries(state)) {
+    if ((v?.ts || 0) > cutoff) trimmed[k] = v;
+  }
+  writeFileSync(SEEN_PATH, JSON.stringify(trimmed));
+}
+
+function listByLabel(label) {
+  const r = spawnSync('bd', ['list', '-l', label, '--status', 'open', '--json'], {
+    encoding: 'utf8',
+    timeout: 8000,
+  });
+  if (r.status !== 0) return { ok: false, error: r.stderr || `bd exit ${r.status}` };
+  try {
+    const parsed = JSON.parse(r.stdout || '[]');
+    return { ok: true, issues: Array.isArray(parsed) ? parsed : [] };
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}
+
+export async function tick() {
+  const actions = [];
+  const notes = [];
+  const seen = loadSeen();
+  const onboarded = listOnboardedPersonas();
+  let totalIssues = 0;
+  let newQueued = 0;
+
+  for (const personaId of onboarded) {
+    const label = `next:cx-${personaId}`;
+    const result = listByLabel(label);
+    if (!result.ok) {
+      record({
+        kind: 'error',
+        watcher: name,
+        target: label,
+        result: 'failed',
+        summary: `bd list -l ${label} failed: ${result.error}`,
+      });
+      continue;
+    }
+    totalIssues += result.issues.length;
+    for (const issue of result.issues) {
+      const key = `${issue.id}|${label}`;
+      if (seen[key]) continue;
+      seen[key] = { ts: Date.now(), id: issue.id };
+      const manifest = loadManifest(personaId);
+      const entry = {
+        ts: Date.now(),
+        personaId,
+        cxId: `cx-${personaId}`,
+        bdIssueId: issue.id,
+        fingerprint: `bd-handoff-${issue.id}-${personaId}`,
+        eventType: 'handoff.received',
+        summary: `bd ${issue.id} labeled next:cx-${personaId} — ${(issue.title || '').slice(0, 120)}`,
+        killSwitchEnv: manifest?.killSwitchEnv || '',
+        source: 'bd-watch',
+      };
+      appendFileSync(PENDING_PATH, JSON.stringify(entry) + '\n');
+      record({
+        kind: 'action',
+        watcher: name,
+        action: 'queue-handoff',
+        target: `cx-${personaId}`,
+        summary: `queued ${issue.id} for cx-${personaId}`,
+        context: { bdIssueId: issue.id, label, title: issue.title },
+      });
+      actions.push({ type: 'queue-handoff', target: `cx-${personaId}`, bdIssueId: issue.id });
+      newQueued++;
+    }
+  }
+
+  saveSeen(seen);
+  notes.push({ personasChecked: onboarded.length, totalIssues, newQueued });
+  return { actions, escalations: [], notes };
+}

package/lib/doctor/watchers/cost.mjs

@@ -0,0 +1,130 @@
+/**
+ * lib/doctor/watchers/cost.mjs — daily token-spend monitor.
+ *
+ * Reads the cost ledger and the existing ~/.cx/session-cost.jsonl. Audit-logs
+ * the daily totals so the user has a visible trend; warns when any persona
+ * hits 80% of its daily cap. Hard-stop enforcement lives in the gateway —
+ * the watcher's role is visibility, not enforcement.
+ *
+ * Tick: 10 min.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { record } from '../audit.mjs';
+import {
+  getTotalDailySpend,
+  getDailySpend,
+  personaBudget,
+  totalBudget,
+  dayKey,
+  recordSpend,
+} from '../../cost-ledger.mjs';
+
+export const name = 'cost';
+export const intervalMs = 10 * 60 * 1000;
+
+const SESSION_COST_PATH = join(homedir(), '.cx', 'session-cost.jsonl');
+const STATE_PATH = join(homedir(), '.cx', 'cost-watcher-state.json');
+
+function loadState() {
+  if (!existsSync(STATE_PATH)) return { lastIngestedTsMs: 0 };
+  try { return JSON.parse(readFileSync(STATE_PATH, 'utf8')); } catch { return { lastIngestedTsMs: 0 }; }
+}
+function saveState(state) {
+  const dir = join(homedir(), '.cx');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(STATE_PATH, JSON.stringify(state));
+}
+
+function ingestSessionCosts() {
+  if (!existsSync(SESSION_COST_PATH)) return { ingested: 0, sources: {} };
+  const lines = readFileSync(SESSION_COST_PATH, 'utf8').split('\n').filter(Boolean);
+  if (lines.length === 0) return { ingested: 0, sources: {} };
+  const state = loadState();
+  const cutoffMs = state.lastIngestedTsMs || 0;
+  let ingested = 0;
+  let maxTsMs = cutoffMs;
+  const sources = {};
+  for (const line of lines) {
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    const tsMs = entry.ts ? Date.parse(entry.ts) : 0;
+    if (!Number.isFinite(tsMs) || tsMs <= cutoffMs) continue;
+    const tokens = (entry.total_tokens) || ((entry.input_tokens || 0) + (entry.output_tokens || 0)) || (entry.tokens?.input || 0) + (entry.tokens?.output || 0);
+    const costUsd = entry.cost_usd ?? entry.costUsd ?? entry.cost ?? 0;
+    const rawAgent = entry.agent || entry.persona || entry.personaId || 'unknown';
+    const personaId = String(rawAgent).replace(/^cx-/, '');
+    const source = entry.cost_source || 'unknown';
+    if (tokens > 0 || costUsd > 0) {
+      recordSpend({ personaId, tokens, costUsd, sessionId: entry.task_key || entry.sessionId || '', ts: tsMs });
+      ingested++;
+      sources[source] = (sources[source] || 0) + 1;
+    }
+    if (tsMs > maxTsMs) maxTsMs = tsMs;
+  }
+  if (maxTsMs > cutoffMs) saveState({ lastIngestedTsMs: maxTsMs });
+  return { ingested, sources };
+}
+
+export async function tick() {
+  const actions = [];
+  const notes = [];
+
+  const ingestResult = ingestSessionCosts();
+  if (ingestResult.ingested > 0) {
+    actions.push({ type: 'ledger-sync', count: ingestResult.ingested, sources: ingestResult.sources });
+    const sourcesStr = Object.entries(ingestResult.sources).map(([s, n]) => `${s}=${n}`).join(', ');
+    record({
+      kind: 'action',
+      watcher: name,
+      action: 'ledger-sync',
+      target: 'session-cost.jsonl',
+      summary: `ingested ${ingestResult.ingested} entries — sources: ${sourcesStr}`,
+      context: ingestResult,
+    });
+  }
+
+  const total = getTotalDailySpend();
+  const totalCap = totalBudget();
+  notes.push({ dayKey: dayKey(), totalSpentUsd: total.costUsd, totalCap, invocations: total.invocations, sources: ingestResult.sources });
+
+  record({
+    kind: 'sample',
+    watcher: name,
+    summary: `${dayKey()} total: $${total.costUsd.toFixed(4)} / $${totalCap.toFixed(2)} (${total.invocations} invocations)`,
+    context: { total, totalCap, ingestedFromSessionCost: ingestResult.ingested, sources: ingestResult.sources },
+  });
+
+  const warnAt = 0.8;
+  if (totalCap > 0 && total.costUsd / totalCap >= warnAt) {
+    record({
+      kind: 'warn',
+      watcher: name,
+      action: 'budget-warning',
+      target: 'total',
+      summary: `Daily total spend at ${Math.round((total.costUsd / totalCap) * 100)}% of $${totalCap.toFixed(2)} cap`,
+      context: { total, totalCap },
+    });
+  }
+
+  const onboarded = ['sre', 'qa', 'security', 'docs-keeper'];
+  for (const personaId of onboarded) {
+    const spend = getDailySpend({ personaId });
+    const cap = personaBudget(personaId);
+    if (cap > 0 && spend.costUsd / cap >= warnAt) {
+      record({
+        kind: 'warn',
+        watcher: name,
+        action: 'budget-warning',
+        target: `cx-${personaId}`,
+        summary: `cx-${personaId} at ${Math.round((spend.costUsd / cap) * 100)}% of $${cap.toFixed(2)} daily cap`,
+        context: { spend, cap },
+      });
+    }
+  }
+
+  return { actions, escalations: [], notes };
+}

package/lib/doctor/watchers/disk.mjs

@@ -0,0 +1,122 @@
+/**
+ * lib/doctor/watchers/disk.mjs — disk-space monitor + log rotation.
+ *
+ * Watches free space on the partition holding ~/.cx and rotates the doctor's
+ * own JSONL artifacts (events.jsonl, doctor-log.jsonl, role-pending.jsonl,
+ * agent-log.jsonl, session-cost.jsonl). When free space falls below the
+ * watermark, escalates `service.down` so cx-sre can triage.
+ *
+ * Tick: 5 min. Cheap — only reads file sizes + statfs.
+ */
+
+import { existsSync, statSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { record } from '../audit.mjs';
+import { escalate } from '../escalate.mjs';
+
+export const name = 'disk';
+export const intervalMs = 5 * 60 * 1000;
+
+const TARGETS = [
+  { path: '.cx/events.jsonl', maxLines: 1000 },
+  { path: '.cx/doctor-log.jsonl', maxLines: 2000 },
+  { path: '.cx/role-pending.jsonl', maxLines: 500 },
+  { path: '.cx/agent-log.jsonl', maxLines: 1000 },
+  { path: '.cx/session-cost.jsonl', maxLines: 1000 },
+  { path: '.cx/hook-failures.jsonl', maxLines: 500 },
+];
+
+function freeBytesAt(p) {
+  const r = spawnSync('df', ['-k', p], { encoding: 'utf8' });
+  if (r.status !== 0) return null;
+  const lines = r.stdout.split('\n').filter(Boolean);
+  if (lines.length < 2) return null;
+  const cols = lines[1].split(/\s+/);
+  const freeKb = parseInt(cols[3] || '0', 10);
+  return Number.isFinite(freeKb) ? freeKb * 1024 : null;
+}
+
+function rotateTarget({ path: relPath, maxLines }) {
+  const fullPath = join(homedir(), relPath);
+  if (!existsSync(fullPath)) return { rotated: false };
+  try {
+    const raw = readFileSync(fullPath, 'utf8').split('\n').filter(Boolean);
+    if (raw.length <= maxLines) return { rotated: false, lines: raw.length };
+    const trimmed = raw.slice(raw.length - maxLines).join('\n') + '\n';
+    writeFileSync(fullPath, trimmed);
+    return { rotated: true, droppedLines: raw.length - maxLines };
+  } catch (err) {
+    return { rotated: false, error: String(err) };
+  }
+}
+
+function pruneRuntimeLogs() {
+  const runtimeDir = join(homedir(), '.construct', '.runtime');
+  if (!existsSync(runtimeDir)) return { pruned: 0 };
+  const maxAgeMs = 7 * 24 * 60 * 60 * 1000;
+  const now = Date.now();
+  let pruned = 0;
+  try {
+    for (const name of readdirSync(runtimeDir)) {
+      const p = join(runtimeDir, name);
+      try {
+        const stat = statSync(p);
+        if (stat.isFile() && (now - stat.mtimeMs) > maxAgeMs) {
+          unlinkSync(p);
+          pruned++;
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* runtime dir disappeared */ }
+  return { pruned };
+}
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+
+  for (const target of TARGETS) {
+    const r = rotateTarget(target);
+    if (r.rotated) {
+      record({
+        kind: 'action',
+        watcher: name,
+        action: 'rotate',
+        target: target.path,
+        summary: `rotated ${target.path}: dropped ${r.droppedLines} lines`,
+        context: { droppedLines: r.droppedLines, keptLines: target.maxLines },
+      });
+      actions.push({ type: 'rotate', target: target.path });
+    }
+  }
+
+  const runtimePrune = pruneRuntimeLogs();
+  if (runtimePrune.pruned > 0) {
+    record({
+      kind: 'action',
+      watcher: name,
+      action: 'prune',
+      target: '.construct/.runtime/',
+      summary: `pruned ${runtimePrune.pruned} stale runtime log(s) (>7 days)`,
+      context: runtimePrune,
+    });
+    actions.push({ type: 'prune', target: '.construct/.runtime/' });
+  }
+
+  const free = freeBytesAt(homedir());
+  const lowWaterBytes = 500 * 1024 * 1024;
+  if (free !== null && free < lowWaterBytes) {
+    const r = await escalate({
+      watcher: name,
+      eventType: 'service.down',
+      summary: `Free disk below 500MB on $HOME (${Math.round(free / 1024 / 1024)}MB remaining)`,
+      context: { freeBytes: free, lowWaterBytes },
+    });
+    escalations.push({ eventType: 'service.down', result: r });
+  }
+
+  return { actions, escalations, notes: [{ freeBytes: free, rotated: actions.filter((a) => a.type === 'rotate').length }] };
+}