phronesis 1.0.0

package/src/eval.js

@@ -0,0 +1,467 @@
+// `phronesis eval view` (core-0029 PR1 / T7.1) — the tiny LOCAL eval data viewer
+// (specs/eval-discipline.md §"Custom data viewer (not a platform dependency)").
+//
+// L1 — it binds localhost ONLY, writes NOTHING into the repo, and exposes NOTHING over the
+// network. It renders the operator's own private golden material locally (goldens carry real
+// names; change 0023), so it must never copy that material into the repo tree or serve it
+// off-localhost. The render is held in memory and served on 127.0.0.1; no file is written.
+//
+// L2 — it renders only data that EXISTS: per skill, the golden list; input → expected →
+// model_default from the GOLDENS (the text lives there, not in runs/*.json — those are judge
+// scores + metadata only, judge.py); L2 per-criterion means + below-floor (signed_mean < 4)
+// from results/aggregate.json. The "actual"/candidate column lights up ONLY when core-0028's
+// candidate runner has persisted candidate output to results/candidates/*.json — never
+// invented, never read from runs/*.json. The viewer runs no evals.
+
+import { createServer } from 'node:http';
+import { existsSync, statSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const DEFAULT_HOST = '127.0.0.1';
+export const QUALITY_FLOOR = 4;
+
+// L1 — the viewer renders the operator's private golden material, so it may bind ONLY a
+// loopback address. An operator may pick IPv4/IPv6 loopback, or the convenience input
+// `localhost` (canonicalized to numeric before binding — see canonicalBindHost); nothing else.
+const LOCALHOST_BINDS = new Set(['127.0.0.1', '::1', 'localhost']);
+export function isLocalhostBind(host) {
+  return LOCALHOST_BINDS.has(host);
+}
+
+// `localhost` is accepted as a convenience input, but it is NEVER handed to listen(): the OS
+// resolver (tampered hostfile / unusual NSS) could map it off-loopback, and listen()'s
+// callback only runs AFTER the socket has already bound — a post-listen check is too late to
+// stop a momentary off-host bind. So we canonicalize `localhost` to numeric 127.0.0.1
+// ourselves: the bind is loopback BY CONSTRUCTION, not by hope. (127.0.0.1 / ::1 pass through.)
+export function canonicalBindHost(host) {
+  return host === 'localhost' ? DEFAULT_HOST : host;
+}
+
+// Defense-in-depth behind canonicalBindHost: after listen() we still assert the ACTUAL bound
+// address is loopback and refuse otherwise (belt-and-suspenders, also covered by tests).
+export function isLoopbackAddress(addr) {
+  if (typeof addr !== 'string') return false;
+  return addr === '::1' || /^127\./.test(addr) || /^::ffff:127\./i.test(addr);
+}
+
+function localUrl(host, port) {
+  const h = host.includes(':') ? `[${host}]` : host; // bracket IPv6 (::1 → [::1])
+  return `http://${h}:${port}/`;
+}
+
+// --- Source-root resolution (the same rule as `phronesis skills bump`, core-0031 B6) -------
+// --repo, else cwd must be a repo ROOT (skills/ + changes/ present). Refuse if neither
+// resolves — no silent install fallback. (Re-stated locally so PR1 is independent of the
+// core-0031 merge; the two resolvers can unify once both land.)
+function isDir(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function resolveRepoRoot({ repo, cwd = process.cwd() } = {}) {
+  const root = repo || cwd;
+  // Require DIRECTORIES, not mere existence — a plain file named skills/ or changes/ would
+  // pass an existsSync check and then blow up the first readdir().
+  if (isDir(join(root, 'skills')) && isDir(join(root, 'changes'))) return { root };
+  return {
+    error:
+      `not a Phronesis repo root: ${root} (expected skills/ and changes/). ` +
+      'eval view reads repo rubrics + gitignored candidate results — pass --repo <path> or run from the repo root. ' +
+      'Goldens resolve from the install ($PHRONESIS_INSTALL); there is no install fallback for the repo root.',
+  };
+}
+
+// --- Data loading -----------------------------------------------------------
+
+// Skills with any eval data to show: a rubric or an aggregate.json. (A skill dir alone is not
+// enough — we only list ones with something to render.)
+export async function collectEvalSkills(repoRoot) {
+  const skillsDir = join(repoRoot, 'skills');
+  if (!existsSync(skillsDir)) return [];
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const evalsDir = join(skillsDir, e.name, 'evals');
+    if (existsSync(join(evalsDir, 'rubric.md')) || existsSync(join(evalsDir, 'results', 'aggregate.json'))) {
+      out.push(e.name);
+    }
+  }
+  return out.sort();
+}
+
+// Resolve the install golden dir the same way run_skill_goldens.py does: --goldens-dir →
+// $PHRONESIS_INSTALL/corpus/skill-goldens/<skill>. Goldens carry input/expected/model_default
+// TEXT; they live in the install, never the repo (change 0023).
+export async function loadGoldens({ skill, goldensDir }) {
+  const dir = goldensDir
+    || (process.env.PHRONESIS_INSTALL
+      ? join(process.env.PHRONESIS_INSTALL, 'corpus', 'skill-goldens', skill)
+      : null);
+  if (!dir || !existsSync(dir)) return { resolved: false, source: dir || '(no $PHRONESIS_INSTALL set)', byId: {}, warnings: [] };
+  const files = (await readdir(dir)).filter((f) => /^golden-.*\.json$/.test(f)).sort();
+  const byId = {};
+  const warnings = [];
+  for (const f of files) {
+    let d;
+    try {
+      d = JSON.parse(await readFile(join(dir, f), 'utf8'));
+    } catch {
+      // Don't silently drop a corrupt golden — that makes bad data look like missing data.
+      warnings.push(`golden ${f} is unparseable JSON — skipped`);
+      continue;
+    }
+    if ('input' in d && 'expected' in d && 'model_default' in d) {
+      byId[d.id || f.replace(/\.json$/, '')] = d;
+    } else {
+      warnings.push(`golden ${f} is missing input/expected/model_default — skipped`);
+    }
+  }
+  return { resolved: true, source: dir, byId, warnings };
+}
+
+// The "actual" column: candidate output persisted by core-0028's runner to
+// results/candidates/*.json. Each file carries { golden_id, candidate_message, loop, ... }.
+// We surface the LATEST candidate per golden_id. NEVER read runs/*.json (scores only, L2).
+export async function loadCandidates({ repoRoot, skill }) {
+  const dir = join(repoRoot, 'skills', skill, 'evals', 'results', 'candidates');
+  if (!existsSync(dir)) return { present: false, byGolden: {}, warnings: [] };
+  const files = (await readdir(dir)).filter((f) => f.endsWith('.json')).sort();
+  const byGolden = {};
+  const warnings = [];
+  for (const f of files) {
+    let d;
+    try {
+      d = JSON.parse(await readFile(join(dir, f), 'utf8'));
+    } catch {
+      warnings.push(`candidate ${f} is unparseable JSON — skipped`);
+      continue;
+    }
+    const gid = d.golden_id;
+    if (!gid) {
+      warnings.push(`candidate ${f} has no golden_id — skipped`);
+      continue;
+    }
+    // A candidate file must carry actual persisted output. Without a string candidate_message
+    // there is nothing to show — and counting it as "present" would light up the "actual"
+    // column for output that does not exist. Skip + surface it rather than render a blank.
+    if (typeof d.candidate_message !== 'string') {
+      warnings.push(`candidate ${f} (golden ${gid}) has no candidate_message string — skipped`);
+      continue;
+    }
+    // files sort ascending by stamp, so the last write for a gid wins (latest run).
+    byGolden[gid] = {
+      candidate_message: d.candidate_message,
+      outcome: d.loop?.outcome || 'unknown',
+      model_id: d.model_id || null,
+    };
+  }
+  return { present: Object.keys(byGolden).length > 0, byGolden, warnings };
+}
+
+export async function loadEvalData({ repoRoot, skill, goldensDir }) {
+  const evalsDir = join(repoRoot, 'skills', skill, 'evals');
+  const rubricPath = join(evalsDir, 'rubric.md');
+  const aggregatePath = join(evalsDir, 'results', 'aggregate.json');
+  const rubric = existsSync(rubricPath) ? await readFile(rubricPath, 'utf8') : null;
+  let aggregate = null;
+  if (existsSync(aggregatePath)) {
+    try {
+      aggregate = JSON.parse(await readFile(aggregatePath, 'utf8'));
+    } catch {
+      aggregate = { error: `aggregate.json is unparseable: ${aggregatePath}` };
+    }
+  }
+  const goldens = await loadGoldens({ skill, goldensDir });
+  const candidates = await loadCandidates({ repoRoot, skill });
+  const warnings = [...(goldens.warnings || []), ...(candidates.warnings || [])];
+  return { skill, rubric, aggregate, goldens, candidates, warnings };
+}
+
+// --- Rendering (pure — held in memory, never written to disk) ---------------
+
+function esc(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+const MAX_CELL_CHARS = 20000;
+function truncate(text) {
+  if (text.length <= MAX_CELL_CHARS) return text;
+  return `${text.slice(0, MAX_CELL_CHARS)}\n… (truncated ${text.length - MAX_CELL_CHARS} more chars)`;
+}
+
+function renderValue(v) {
+  if (v === null || v === undefined) return '<span class="muted">—</span>';
+  const text = typeof v === 'string' ? v : JSON.stringify(v, null, 2);
+  return `<pre>${esc(truncate(text))}</pre>`;
+}
+
+// Below-floor criteria for a golden's aggregate row: signed_mean < 4 (the L2 pass bar).
+function belowFloor(goldenAgg, criteriaLabels) {
+  const out = [];
+  const crit = goldenAgg?.criteria || {};
+  for (const [key, v] of Object.entries(crit)) {
+    if (typeof v?.signed_mean === 'number' && v.signed_mean < QUALITY_FLOOR) {
+      out.push({ key, label: criteriaLabels[key] || key, mean: v.signed_mean });
+    }
+  }
+  return out;
+}
+
+function renderScores(goldenAgg, criteriaLabels) {
+  const crit = goldenAgg?.criteria || {};
+  const keys = Object.keys(crit);
+  if (!keys.length) return '<span class="muted">no scores</span>';
+  const rows = keys.map((key) => {
+    const v = crit[key];
+    const mean = typeof v?.signed_mean === 'number' ? v.signed_mean : null;
+    const fail = mean !== null && mean < QUALITY_FLOOR;
+    const label = criteriaLabels[key] || key;
+    const cls = fail ? ' class="below-floor"' : '';
+    const def = typeof v?.default_mean === 'number' ? ` <span class="muted">(default ${esc(v.default_mean)})</span>` : '';
+    return `<tr${cls}><td>${esc(label)}</td><td>${mean === null ? '—' : esc(mean)}${fail ? ' &darr; below floor' : ''}${def}</td></tr>`;
+  });
+  return `<table class="scores">${rows.join('')}</table>`;
+}
+
+function renderSkillSection(data) {
+  const { skill, rubric, aggregate, goldens, candidates } = data;
+  const hasActual = candidates.present;
+  const warnings = [...(data.warnings || [])];
+  const criteriaLabels = {};
+  // aggregate.criteria is the criterion-label LIST (an array). A hand-edited aggregate.json
+  // with a non-array criteria ({} etc.) must not crash the render — guard + surface it.
+  const criteriaList = Array.isArray(aggregate?.criteria) ? aggregate.criteria : [];
+  if (aggregate && !aggregate.error && aggregate.criteria != null && !Array.isArray(aggregate.criteria)) {
+    warnings.push('aggregate.json "criteria" is not an array — criterion labels unavailable');
+  }
+  for (const c of criteriaList) criteriaLabels[c.key] = c.label;
+
+  // The golden ids to show: union of aggregate's goldens, resolved golden ids, AND any
+  // candidate's golden_id (so a candidate for a golden retired from the corpus still shows
+  // — it never silently vanishes).
+  const aggGoldens = aggregate && !aggregate.error ? aggregate.goldens || {} : {};
+  const ids = [...new Set([
+    ...Object.keys(aggGoldens),
+    ...Object.keys(goldens.byId),
+    ...Object.keys(candidates.byGolden),
+  ])].sort();
+
+  const header = [
+    `<h2>${esc(skill)}</h2>`,
+    warnings.length
+      ? `<div class="warn warnings"><strong>data warnings:</strong><ul>${warnings.map((w) => `<li>${esc(w)}</li>`).join('')}</ul></div>`
+      : '',
+    aggregate?.error
+      ? `<p class="warn">${esc(aggregate.error)}</p>`
+      : aggregate
+        ? `<p class="meta">judge ${esc((Array.isArray(aggregate.judge_model) ? aggregate.judge_model.join(', ') : aggregate.judge_model) || '—')} · k=${esc(aggregate.k ?? '—')} · ${ids.length} golden(s)${aggregate.total_cost_usd != null ? ` · $${esc(aggregate.total_cost_usd)}` : ''}</p>`
+        : '<p class="meta muted">no results/aggregate.json yet — run this skill\'s goldens to populate scores</p>',
+    goldens.resolved
+      ? ''
+      : `<p class="meta muted">golden text not resolved (${esc(goldens.source)}) — set $PHRONESIS_INSTALL or pass --goldens-dir to render input/expected/model_default</p>`,
+    hasActual
+      ? '<p class="meta">actual column present — candidate output persisted by the runner (core-0028)</p>'
+      : '<p class="meta muted">no actual column — no candidate output persisted yet (core-0028 runner has not written results/candidates/)</p>',
+    rubric ? `<details class="rubric"><summary>L2 rubric (the eval — vague rubric, vague scores)</summary>${renderValue(rubric)}</details>` : '',
+  ].join('\n');
+
+  if (!ids.length) {
+    return `<section>\n${header}\n<p class="muted">no goldens to display.</p>\n</section>`;
+  }
+
+  const cols = ['golden', 'input', 'expected', 'model_default', ...(hasActual ? ['actual'] : []), 'scores'];
+  const thead = `<tr>${cols.map((c) => `<th>${esc(c)}</th>`).join('')}</tr>`;
+  const rows = ids.map((gid) => {
+    const g = goldens.byId[gid];
+    const ga = aggGoldens[gid];
+    const title = ga?.title || g?.title;
+    const cells = [
+      `<td class="gid">${esc(gid)}${title ? `<br><span class="muted">${esc(title)}</span>` : ''}</td>`,
+      `<td>${g ? renderValue(g.input) : '<span class="muted">—</span>'}</td>`,
+      `<td>${g ? renderValue(g.expected) : '<span class="muted">—</span>'}</td>`,
+      `<td>${g ? renderValue(g.model_default) : '<span class="muted">—</span>'}</td>`,
+    ];
+    if (hasActual) {
+      const cand = candidates.byGolden[gid];
+      cells.push(
+        `<td>${cand ? `${renderValue(cand.candidate_message)}<span class="muted">outcome: ${esc(cand.outcome)}${cand.model_id ? ` · ${esc(cand.model_id)}` : ''}</span>` : '<span class="muted">no candidate for this golden</span>'}</td>`,
+      );
+    }
+    const fails = belowFloor(ga, criteriaLabels);
+    const failNote = fails.length
+      ? `<div class="fail-trace">below floor: ${fails.map((f) => `${esc(f.label)} (${esc(f.mean)})`).join('; ')}</div>`
+      : '';
+    cells.push(`<td>${renderScores(ga, criteriaLabels)}${failNote}</td>`);
+    return `<tr>${cells.join('')}</tr>`;
+  });
+
+  return `<section>\n${header}\n<table class="goldens">${thead}${rows.join('')}</table>\n</section>`;
+}
+
+export function renderEvalView({ skills, repoRoot }) {
+  const sections = skills.length
+    ? skills.map(renderSkillSection).join('\n')
+    : '<p class="muted">no skills with eval data (a rubric or results/aggregate.json) under skills/.</p>';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="robots" content="noindex,nofollow">
+<title>Phronesis eval view</title>
+<style>
+  :root { color-scheme: light; }
+  body { font-family: Georgia, 'Times New Roman', serif; margin: 2rem auto; max-width: 70rem; padding: 0 1.5rem; color: #1a1a1a; line-height: 1.5; }
+  h1 { font-size: 1.5rem; border-bottom: 2px solid #7a3b2e; padding-bottom: .4rem; }
+  h2 { font-size: 1.2rem; margin-top: 2.2rem; border-bottom: 1px solid #ccc; }
+  .lede { color: #555; font-size: .9rem; }
+  .meta { font-size: .85rem; margin: .2rem 0; }
+  .muted { color: #888; }
+  .warn { color: #7a3b2e; }
+  .warnings ul { margin: .2rem 0 .6rem 1.2rem; font-size: .8rem; }
+  table { border-collapse: collapse; width: 100%; margin: .6rem 0 1.4rem; font-size: .82rem; }
+  th, td { border: 1px solid #ccc; padding: .4rem .5rem; vertical-align: top; text-align: left; }
+  th { background: #f3f1ec; font-weight: bold; }
+  td.gid { white-space: nowrap; font-weight: bold; }
+  pre { white-space: pre-wrap; word-break: break-word; margin: 0; font-family: ui-monospace, Menlo, monospace; font-size: .78rem; max-height: 18rem; overflow: auto; }
+  table.scores { margin: 0; }
+  table.scores td { border: none; border-bottom: 1px dotted #ddd; padding: .15rem .3rem; font-size: .8rem; }
+  tr.below-floor td, .below-floor { color: #7a3b2e; }
+  .fail-trace { margin-top: .4rem; font-size: .78rem; color: #7a3b2e; border-top: 1px solid #e3d9c6; padding-top: .3rem; }
+</style>
+</head>
+<body>
+<h1>Phronesis eval view</h1>
+<p class="lede">${esc(repoRoot)} · localhost-only · read-only. Renders goldens (input / expected / model_default) and L2 scores; the actual column appears once the runner persists candidate output.</p>
+${sections}
+</body>
+</html>
+`;
+}
+
+// --- Server (thin; binds localhost only, serves the in-memory render) -------
+
+export async function buildView({ repo, skill, goldensDir, cwd }) {
+  const resolved = resolveRepoRoot({ repo, cwd });
+  if (resolved.error) return { error: resolved.error };
+  const repoRoot = resolved.root;
+  // Sanitize the skill name before it reaches any path join — `join('skills', '../changes')`
+  // collapses to outside skills/ and would read evals/ content from anywhere in the repo.
+  // A kebab-case name matches the SKILL.md directory contract (same rule as the substrate's
+  // safeName + skills bump).
+  if (skill !== undefined && !/^[a-z0-9][a-z0-9-]*$/.test(skill)) {
+    return { error: `invalid skill name "${skill}" (expected kebab-case [a-z0-9-], matching the skills/ directory)` };
+  }
+  if (skill && !existsSync(join(repoRoot, 'skills', skill))) {
+    return { error: `skill not found: ${join(repoRoot, 'skills', skill)}` };
+  }
+  const names = skill ? [skill] : await collectEvalSkills(repoRoot);
+  // A flat --goldens-dir is per-skill; applying ONE dir across MULTIPLE skills would render
+  // one skill's name-bearing goldens under every skill's table (local misattribution). With a
+  // single skill it is unambiguous; with more than one, require --skill to disambiguate.
+  if (goldensDir && !skill && names.length > 1) {
+    return { error: `--goldens-dir is per-skill and ${names.length} skills have eval data; pass --skill <name> with it (or rely on the per-skill $PHRONESIS_INSTALL default).` };
+  }
+  const skills = [];
+  for (const name of names) skills.push(await loadEvalData({ repoRoot, skill: name, goldensDir }));
+  return { repoRoot, html: renderEvalView({ skills, repoRoot }), skills };
+}
+
+// The render carries the operator's private golden material. The page is fully self-contained
+// (inline <style>, no scripts, no external assets), so a strict CSP + no-store keeps it out of
+// the browser cache and off any other origin.
+const HTML_HEADERS = {
+  'content-type': 'text/html; charset=utf-8',
+  'cache-control': 'no-store, max-age=0',
+  pragma: 'no-cache',
+  'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'",
+  'referrer-policy': 'no-referrer',
+};
+
+// `addressOf` is a test seam: the post-listen loopback assertion guards against a `localhost`
+// that resolved off-host, which is otherwise impossible to trigger deterministically (the
+// pre-bind allowlist blocks literal off-host values, and canonicalBindHost rewrites localhost
+// to numeric). Tests inject one returning a non-loopback address to prove the close+reject branch.
+export function serveEvalView({ html, host = DEFAULT_HOST, port = 0, addressOf = (s) => s.address() } = {}) {
+  if (!isLocalhostBind(host)) {
+    // Refuse BEFORE binding — never expose operator names off-localhost, not even briefly.
+    return Promise.reject(
+      new Error(`eval view binds localhost only (got --host ${host}); allowed: 127.0.0.1, ::1, localhost`),
+    );
+  }
+  // Never hand `localhost` to listen() — bind a numeric loopback address so the OS resolver
+  // cannot place us off-host even momentarily (listen()'s callback runs AFTER the bind).
+  const bindHost = canonicalBindHost(host);
+  const server = createServer((req, res) => {
+    // Read-only viewer: only GET, only the page. Never accept writes, never read a path
+    // from the request (no file serving — the whole render is in memory).
+    if (req.method !== 'GET') {
+      res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store, max-age=0' });
+      res.end('eval view is read-only');
+      return;
+    }
+    res.writeHead(200, HTML_HEADERS);
+    res.end(html);
+  });
+  return new Promise((resolvePromise, rejectPromise) => {
+    server.once('error', rejectPromise);
+    // Bind loopback ONLY — never 0.0.0.0; the render carries real operator names.
+    server.listen(port, bindHost, () => {
+      const addr = addressOf(server);
+      // Defense-in-depth: verify the ACTUAL bound address is loopback. Refuse + close before
+      // serving a single byte off-loopback.
+      if (!isLoopbackAddress(addr.address)) {
+        server.close();
+        rejectPromise(
+          new Error(`refusing off-loopback bind: "${host}" resolved to ${addr.address}; eval view is localhost-only`),
+        );
+        return;
+      }
+      // URL from the ACTUAL bound address, not the input host — with --host localhost the
+      // browser could otherwise resolve a different loopback family than we bound.
+      resolvePromise({ server, host: addr.address, port: addr.port, url: localUrl(addr.address, addr.port) });
+    });
+  });
+}
+
+export async function runEvalView({ repo, skill, goldensDir, port = 0, host = DEFAULT_HOST, json = false, serve = true } = {}) {
+  const view = await buildView({ repo, skill, goldensDir, cwd: process.cwd() });
+  if (view.error) {
+    console.error(view.error);
+    process.exitCode = 1;
+    return;
+  }
+  if (json) {
+    console.log(JSON.stringify({ repoRoot: view.repoRoot, skills: view.skills.map((s) => s.skill) }, null, 2));
+    return;
+  }
+  if (!serve) {
+    process.stdout.write(view.html);
+    return;
+  }
+  if (!isLocalhostBind(host)) {
+    console.error(`eval view binds localhost only (got --host ${host}); allowed: 127.0.0.1, ::1, localhost`);
+    process.exitCode = 1;
+    return;
+  }
+  let served;
+  try {
+    served = await serveEvalView({ html: view.html, host, port });
+  } catch (err) {
+    // EADDRINUSE on a chosen --port, an off-loopback resolution, etc. — clean failure, not a
+    // stack trace.
+    console.error(`eval view could not start: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Phronesis eval view — ${view.repoRoot}`);
+  console.log(`serving ${view.skills.length} skill(s) at ${served.url} (localhost-only; Ctrl-C to stop)`);
+}

package/src/event.js

@@ -0,0 +1,212 @@
+// `phronesis event` / `phronesis events` — the universal emission + read path over the
+// event-log core (core-0006 / T4.0). Every surface/agent shells out to `event emit`; the
+// daemon (T4.1) and surface-native bridges are faster paths to the same record. This module
+// is the CLI glue only — validation, the capture gate, and I/O live in @phronesis/core.
+
+import { watch } from 'node:fs';
+import {
+  resolveInstall,
+  appendEvent,
+  readEvents,
+  enforceRetention,
+  purgeEvents,
+  enforceAuditRetention,
+  purgeAuditLog,
+  readEventLogConfig,
+  isReservedType,
+  eventsDir,
+} from '@phronesis/core';
+
+// Install resolution (explicit --dir or marker walk-up, BOTH fail closed on a missing
+// .phronesis/registry.json) lives in @phronesis/core — shared with the action spine
+// (core-0008) so every install-scoped command resolves identically.
+
+// Resolve or print-and-fail. Returns the install root, or null after setting exitCode = 1.
+function installOrFail(dir) {
+  const r = resolveInstall({ dir });
+  if (r.error) {
+    console.error(r.error);
+    process.exitCode = 1;
+    return null;
+  }
+  return r.root;
+}
+
+export async function runEventEmit({ type, session, payload, actor, surface, dir } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+
+  if (!type) {
+    console.error('event emit: name an event <type> (e.g. session.start).');
+    process.exitCode = 1;
+    return null;
+  }
+  // Reserved-type refusal is a CLI policy, checked before the core write: each
+  // reserved type has a sole authoritative emitter, so a caller cannot forge a
+  // filesystem/observation/lifecycle event through the public CLI (fail-closed).
+  // file.* arrives with the V1.5 daemon's filesystem watch; outcome.due is emitted by
+  // the V1 session-start due-check (`phronesis hooks due-check` — change 0010);
+  // skill.invoked / skill.completed are emitted by compliant surface adapters.
+  if (isReservedType(type)) {
+    console.error(
+      `event emit: "${type}" is reserved for its authoritative emitter (file.*: the V1.5 daemon's filesystem watch; outcome.due / schedule.due: the session-start due-check, \`phronesis hooks due-check\`; skill.invoked/skill.completed: compliant surface adapters; compile.candidate/compile.accepted/compile.rejected: the compile action + the operator accept/reject moves — \`compile review\` trusts these for its fail-closed quarantine, so a freehand one could forge a "clean" draft). The CLI refuses freehand emission.`,
+    );
+    process.exitCode = 1;
+    return null;
+  }
+  if (!session) {
+    console.error('event emit: --session <id> is required.');
+    process.exitCode = 1;
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = payload === undefined ? {} : JSON.parse(payload);
+  } catch {
+    console.error('event emit: --payload must be valid JSON.');
+    process.exitCode = 1;
+    return null;
+  }
+
+  // Mandatory-field defaults (Decision F): surface defaults to cli; actor reads
+  // PHRONESIS_ACTOR (surface adapters set it) else agent, the dominant emitter. Adapters
+  // SHOULD pass both explicitly; --actor / --surface override.
+  const resolvedActor = actor || process.env.PHRONESIS_ACTOR || 'agent';
+  const resolvedSurface = surface || 'cli';
+
+  try {
+    const record = await appendEvent({
+      installRoot,
+      type,
+      session_id: session,
+      actor: resolvedActor,
+      surface: resolvedSurface,
+      payload: parsed,
+    });
+    console.log(record.id);
+    process.exitCode = 0;
+    return record;
+  } catch (err) {
+    console.error(`event emit: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+export async function runEventTail({ type, since, follow, dir } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+
+  // Validate + normalize --since to canonical ISO before comparing. readEvents compares ts as
+  // text, which is only correct when both sides are ISO-8601 UTC — a raw string like
+  // "2026-5-17" (un-padded) or "garbage" would lexically mis-filter and silently empty the
+  // stream. Reject anything Date can't parse; normalize the rest so the compare is sound.
+  let sinceIso;
+  if (since !== undefined) {
+    const parsed = Date.parse(since);
+    if (Number.isNaN(parsed)) {
+      console.error(`event tail: --since "${since}" is not a parseable date/timestamp.`);
+      process.exitCode = 1;
+      return null;
+    }
+    sinceIso = new Date(parsed).toISOString();
+  }
+
+  const printed = new Set();
+  const flush = async () => {
+    for (const ev of await readEvents({ installRoot, since: sinceIso, type })) {
+      if (printed.has(ev.id)) continue;
+      printed.add(ev.id);
+      console.log(JSON.stringify(ev));
+    }
+  };
+
+  await flush();
+  if (!follow) {
+    process.exitCode = 0;
+    return null;
+  }
+
+  // --follow: re-flush on any change to the events dir (fs.watch), with a poll fallback for
+  // filesystems where native watch is unreliable (no chokidar — that dep + FS watching is
+  // T4.1). flush() dedups by id, so a re-read only ever prints genuinely-new lines. Runs
+  // until interrupted; never resolves.
+  const trigger = () => {
+    flush().catch(() => {});
+  };
+  let watcher = null;
+  try {
+    watcher = watch(eventsDir(installRoot), { persistent: true }, trigger);
+  } catch {
+    watcher = null; // dir may not be watchable; the poll fallback covers it
+  }
+  const poll = setInterval(trigger, 1000);
+  poll.unref?.();
+  await new Promise(() => {});
+  // unreachable, but keeps the watcher referenced for the lifetime of the process
+  if (watcher) watcher.close();
+  return null;
+}
+
+export async function runEventsPurge({ before, archive, dir } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+
+  if (!before) {
+    console.error('events purge: --before YYYY-MM-DD is required (the deletion boundary).');
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    const { files } = await purgeEvents({ installRoot, before, archive: Boolean(archive) });
+    const verb = archive ? 'archived' : 'deleted';
+    console.log(
+      files.length
+        ? `${verb} ${files.length} day file(s) before ${before}: ${files.join(', ')}`
+        : `no day files before ${before}.`,
+    );
+    // One retention story, one verb family (core-0027 J5 / Q2): the audit log inherits the
+    // same purge boundary. It is a single append file, so this is line-level, not a file move.
+    const audit = await purgeAuditLog({ installRoot, before, archive: Boolean(archive) });
+    if (audit.purged) {
+      console.log(`${verb} ${audit.purged} audit.log line(s) before ${before}.`);
+    }
+    process.exitCode = 0;
+    return files;
+  } catch (err) {
+    console.error(`events purge: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+export async function runEventsRotate({ dir } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+
+  // try/catch like its sibling purge: rotate MUTATES files (fse.move), so a failed move
+  // (permissions, disk, collision) must surface as exit 1, not an unhandled rejection. A
+  // partial archive is forward-safe — every day file is either in events/ or archive/, both
+  // valid locations, and a re-run continues from where it stopped (the move is idempotent).
+  try {
+    const { retentionDays } = await readEventLogConfig(installRoot);
+    const { archived } = await enforceRetention({ installRoot, retentionDays });
+    console.log(
+      archived.length
+        ? `archived ${archived.length} day file(s) past ${retentionDays}-day retention: ${archived.join(', ')}`
+        : `no day files past ${retentionDays}-day retention.`,
+    );
+    // One retention story, one verb family (core-0027 J5 / Q2): the single-file audit log
+    // honors the same retention window via line-level archival to audit.log.archive.
+    const audit = await enforceAuditRetention({ installRoot, retentionDays });
+    if (audit.archived) {
+      console.log(`archived ${audit.archived} audit.log line(s) past ${retentionDays}-day retention.`);
+    }
+    process.exitCode = 0;
+    return archived;
+  } catch (err) {
+    console.error(`events rotate: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}