phronesis 1.0.0

package/vendor/core/src/hook-executor.js

@@ -0,0 +1,527 @@
+// The V1 hook executor (core-0013; change 0010 D3; specs/hooks.md §"Hooks subscribe to
+// events, not vibes" / §"Hook registry format" / §"Safe-output discipline" / §"Bypass
+// discipline"; specs/event-log.md §"Subscription contract"; packet decisions H1/H2/H6 in
+// harness/tasks/core-0013-v1-hook-executor.md).
+//
+// Hooks subscribe to typed events in the install's `.phronesis/registry.json` top-level
+// `hooks` array — the subscription shape both specs publish. The action core fires
+// matching commands synchronously at its two emit points (`action_type.requested` /
+// `action_type.committed`, actions.js); the daemon takes over the full stream at V1.5
+// (change 0010). A per-action binding is expressible AS a subscription (subscribe to the
+// action_type.* pair with a payload filter), so the per-action hooks.pre/post slots stay
+// reserved-and-empty (action-registry.js).
+//
+// Command execution is a SECURITY surface — the registry is operator-editable and names
+// an executable (H2):
+//   - commands are path-anchored under .phronesis/hooks/ (validated at load, re-checked
+//     at exec by resolved-path containment);
+//   - exec is spawn() with NO shell — the event record travels on stdin, never argv;
+//   - quota.max_per_session is enforced from the audit log (file-based, so the count
+//     survives process boundaries and bites on recursive mutation-hook loops);
+//   - PHRONESIS_SKIP=<hook-id> skips AND audits (a logged bypass, never a silent one);
+//   - EVERY fire — success, failure, timeout, skip — appends a .phronesis/audit.log
+//     entry; an audit-append failure fails the fire loudly (hooks that can fail
+//     silently are the spec's named anti-pattern).
+//
+// KNOWN LIMITS: the exec containment check is lexical over resolve() — a symlink inside
+// .phronesis/hooks/ pointing elsewhere is operator-owned filesystem state, the same
+// posture as every other install file. Filters are the V1 field-equality subset
+// (event-log.md:138); jq expressions are the V1.5 daemon superset.
+
+import { join, resolve, sep, isAbsolute } from 'node:path';
+import { appendFile, readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import fse from 'fs-extra';
+import { isValidType, readEventLogConfig } from './event-log.js';
+import { validateSubscription, matchesSubscription } from './subscription.js';
+
+export const HOOK_KINDS = ['ambient', 'gate', 'mutation'];
+export const HOOK_CLASSIFICATIONS = ['silent', 'acknowledged', 'interactive'];
+
+// A hung hook must not hang the act pipeline: hard kill + audited failure. Code-resident
+// (not registry-settable) — the timeout is part of the floor, like the approval lattice.
+export const HOOK_TIMEOUT_MS = 30_000;
+
+const HOOK_ENTRY_KEYS = [
+  'id',
+  'kind',
+  'subscribes_to',
+  'command',
+  'quota',
+  'classification',
+  'kill_switch',
+  'filter',
+];
+const RE_HOOK_ID = /^[a-z0-9][a-z0-9_-]*$/;
+const COMMAND_PREFIX = '.phronesis/hooks/';
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+// H2 load-time path anchor: relative, no traversal, rooted in .phronesis/hooks/ with a
+// real basename after the prefix. The exec path re-checks containment after resolve().
+function commandAnchorError(command) {
+  if (typeof command !== 'string' || command.trim() === '') {
+    return 'command must be a non-empty path string';
+  }
+  if (isAbsolute(command) || command.includes('\\')) {
+    return `command "${command}" must be a relative POSIX path under ${COMMAND_PREFIX}`;
+  }
+  if (command.split('/').includes('..')) {
+    return `command "${command}" contains a ".." segment — commands never escape ${COMMAND_PREFIX}`;
+  }
+  if (!command.startsWith(COMMAND_PREFIX) || command.length === COMMAND_PREFIX.length) {
+    return `command "${command}" must live under ${COMMAND_PREFIX} (hook commands are install-owned scripts)`;
+  }
+  return null;
+}
+
+// Validate the top-level hooks section against the published subscription shape (H1).
+// Absent ⇒ no hooks registered (additive-optional: absence can never loosen anything,
+// the G3 argument — no schema_version bump). Present-but-invalid ⇒ the caller disables
+// the action layer all-or-nothing with these errors (a config error is loud and total).
+export function resolveHooks(registry) {
+  const errors = [];
+  if (!isPlainObject(registry)) {
+    return { errors: ['.phronesis/registry.json must be a JSON object'], hooks: [] };
+  }
+  const section = registry.hooks;
+  if (section === undefined) return { errors, hooks: [] };
+  // Same keying argument as the action_types/v0 rule (core-0011): version 0 predates
+  // every section, and schema_version is what future migrations key on.
+  if (registry.schema_version === 0) {
+    errors.push(
+      'hooks requires schema_version 1 — a version-0 registry predates the section (bump the version, or remove the section: absent means no hooks registered)',
+    );
+  }
+  if (!Array.isArray(section)) {
+    errors.push('hooks: must be an array of hook entries (hooks.md §"Hook registry format")');
+    return { errors, hooks: [] };
+  }
+
+  const seen = new Set();
+  section.forEach((entry, i) => {
+    const label = isPlainObject(entry) && typeof entry.id === 'string' ? `hooks[${i}] (${entry.id})` : `hooks[${i}]`;
+    if (!isPlainObject(entry)) {
+      errors.push(`${label}: must be an object`);
+      return;
+    }
+    const unknown = Object.keys(entry).filter((k) => !HOOK_ENTRY_KEYS.includes(k));
+    if (unknown.length) {
+      errors.push(`${label}: unknown key(s): ${unknown.join(', ')}`);
+    }
+    if (typeof entry.id !== 'string' || !RE_HOOK_ID.test(entry.id)) {
+      errors.push(`${label}: id must be a lowercase [a-z0-9_-] identifier`);
+    } else if (seen.has(entry.id)) {
+      errors.push(`${label}: duplicate hook id "${entry.id}"`);
+    } else {
+      seen.add(entry.id);
+    }
+    if (!HOOK_KINDS.includes(entry.kind)) {
+      errors.push(`${label}: kind "${entry.kind}" is not in the hook-kind vocabulary (${HOOK_KINDS.join(' | ')})`);
+    }
+    // The matching shape (subscribes_to + filter) validates through the ONE shared
+    // subscription validator (subscription.js, T4.0) — the executor's matcher is
+    // matchesSubscription, so its validation must be the same contract, never a
+    // re-typed copy. The hooks registry additionally demands REAL event types: a
+    // subscription to a typo'd type would never fire — silent intent-drop.
+    const sub = validateSubscription({ subscribes_to: entry.subscribes_to, filter: entry.filter });
+    for (const e of sub.errors) errors.push(`${label}: ${e}`);
+    if (Array.isArray(entry.subscribes_to)) {
+      for (const t of entry.subscribes_to) {
+        if (typeof t === 'string' && t !== '' && !isValidType(t)) {
+          errors.push(`${label}: subscribes_to "${t}" is not in the V1 event vocabulary or a connector.<name>.<event> extension`);
+        }
+      }
+    }
+    const cmdError = commandAnchorError(entry.command);
+    if (cmdError) errors.push(`${label}: ${cmdError}`);
+    if (
+      !isPlainObject(entry.quota) ||
+      Object.keys(entry.quota).some((k) => k !== 'max_per_session') ||
+      !Number.isInteger(entry.quota.max_per_session) ||
+      entry.quota.max_per_session < 1
+    ) {
+      errors.push(`${label}: quota must be { max_per_session: <positive integer> } — the runaway-hook guard is not optional`);
+    }
+    if (!HOOK_CLASSIFICATIONS.includes(entry.classification)) {
+      errors.push(
+        `${label}: classification "${entry.classification}" is not in the vocabulary (${HOOK_CLASSIFICATIONS.join(' | ')})`,
+      );
+    }
+    if (typeof entry.id === 'string' && entry.kill_switch !== `PHRONESIS_SKIP=${entry.id}`) {
+      errors.push(`${label}: kill_switch must be "PHRONESIS_SKIP=${entry.id}" — the documented bypass must tell the truth`);
+    }
+  });
+  if (errors.length) return { errors, hooks: [] };
+  return { errors, hooks: section };
+}
+
+// Subscription match through the ONE shared matcher (subscription.js — type membership,
+// then AND-matched payload-field equality). Registry-array order is execution order —
+// deterministic, operator-visible.
+export function matchingHooks(hooks, event) {
+  return hooks.filter((h) => matchesSubscription(event, h));
+}
+
+// --- Audit (.phronesis/audit.log, JSONL) ----------------------------------------------
+
+export function auditLogPath(installRoot) {
+  return join(installRoot, '.phronesis', 'audit.log');
+}
+
+export async function readAuditLog(installRoot) {
+  let content;
+  try {
+    content = await readFile(auditLogPath(installRoot), 'utf8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      out.push(JSON.parse(trimmed));
+    } catch {
+      // a torn/partial line never poisons a read (same posture as readEvents)
+    }
+  }
+  return out;
+}
+
+// The ts is the REAL clock, deliberately not the action's injectable `now`: the audit
+// log is the forensic record of when fires actually happened, and two audits inside one
+// action must not share a synthetic timestamp. `entry` is spread FIRST, then ts is
+// stamped, so a caller's `entry.ts` (forged or accidental) can NEVER override the append
+// time — the forensic clock always wins, and retention can trust every stamped ts.
+export async function appendAuditEntry(installRoot, entry) {
+  await fse.ensureDir(join(installRoot, '.phronesis'));
+  await appendFile(
+    auditLogPath(installRoot),
+    `${JSON.stringify({ ...entry, ts: new Date().toISOString() })}\n`,
+  );
+}
+
+async function appendAudit(installRoot, entry) {
+  await appendAuditEntry(installRoot, entry);
+}
+
+// --- Audit retention (core-0027 J5) ----------------------------------------------------
+//
+// .phronesis/audit.log is a SINGLE JSONL append file (unlike .phronesis/events/, which
+// rotates whole per-day files), so it grows unbounded and the per-emit quota read
+// (readAuditLog) scans more every fire. J5 gives it the event-log retention STORY (default
+// 90 days, configurable — the SAME event_log.retention_days, one retention story per Q2)
+// folded into the SAME verb family (events rotate / events purge). The MECHANISM differs: a
+// single file has no per-day split, so retention is LINE-LEVEL filtering of the one file —
+// kept lines rewritten, older lines moved to audit.log.archive (rotate) or dropped (purge).
+//
+// Single-writer assumption (the install's standing one-writer model — actions.js): these
+// are operator-invoked maintenance verbs, run when no session is appending; the daemon
+// serializes at V1.5. The temp+rename keeps the live file from ever being TORN — but it
+// does NOT make the read→rewrite atomic against a concurrent append: a line appended between
+// partitionAuditLines and the rename is on the inode the rename replaces, so it is LOST. This
+// is strictly more exposed than event-log retention, which only moves INACTIVE past-day files
+// (today's active file is never touched); a single always-active audit.log has no such inert
+// target. The `events` help text surfaces this quiesce constraint to the operator. Likewise
+// the archive-then-rewrite pair is NOT atomic as a whole: a crash between the two re-archives
+// the same lines on retry (over-retention, never loss) — so unlike the day-file MOVE this is
+// not idempotent. Both costs are the price of the line-level mechanism the contract chose over
+// splitting audit.log into dated files (core-0027 J5 / round-11 S1).
+
+export function auditArchivePath(installRoot) {
+  return join(installRoot, '.phronesis', 'audit.log.archive');
+}
+
+// A retention-comparable ts is one toISOString produces — a canonical ISO-8601 UTC
+// instant. The lexical `ts < cutoff` / `ts < before` compares in enforceAuditRetention and
+// purgeAuditLog are only SOUND for that shape; any other string (a corrupt/non-ISO value
+// like "0-not-a-date") is UNDATEABLE and must be KEPT, never lexically mis-ordered into the
+// old set. Millis optional so a non-toISOString ISO instant still counts. (A structurally-ISO
+// but ancient ts like year 0000 is "dateable and old" — dropping it under retention is
+// correct; the KEEP guarantee is for ts we cannot soundly date, not for genuinely-old ones.)
+const ISO_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+function isDateableTs(ts) {
+  return typeof ts === 'string' && ISO_TS_RE.test(ts);
+}
+
+// Read the raw audit file and split each non-empty line into kept vs old by `isOld(ts)`.
+// A line that does not parse, or whose `ts` is not a well-formed ISO-8601 UTC instant
+// (isDateableTs), is KEPT — retention never drops a forensic line it cannot soundly date
+// (the same "a torn line never poisons a read" posture as readAuditLog). Original line text
+// is preserved verbatim (no re-serialization / reformat).
+async function partitionAuditLines(installRoot, isOld) {
+  let content;
+  try {
+    content = await readFile(auditLogPath(installRoot), 'utf8');
+  } catch {
+    return { kept: [], old: [], present: false };
+  }
+  const kept = [];
+  const old = [];
+  for (const line of content.split('\n')) {
+    if (line.trim() === '') continue;
+    let ts;
+    try {
+      ts = JSON.parse(line).ts;
+    } catch {
+      ts = undefined;
+    }
+    if (isDateableTs(ts) && isOld(ts)) old.push(line);
+    else kept.push(line);
+  }
+  return { kept, old, present: true };
+}
+
+async function rewriteAuditLog(installRoot, keptLines) {
+  const path = auditLogPath(installRoot);
+  const body = keptLines.length ? `${keptLines.join('\n')}\n` : '';
+  const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  await fse.writeFile(tmp, body);
+  await fse.move(tmp, path, { overwrite: true });
+}
+
+async function archiveAuditLines(installRoot, oldLines) {
+  if (!oldLines.length) return;
+  await fse.ensureDir(join(installRoot, '.phronesis'));
+  await appendFile(auditArchivePath(installRoot), `${oldLines.join('\n')}\n`);
+}
+
+// ARCHIVE audit lines older than the retention window to audit.log.archive (mirrors
+// event-log enforceRetention; folded into `events rotate`). Retention is an INSTANT cutoff
+// (now − retentionDays) — a single append file has no day-file boundary to round to. Bounds
+// both unbounded growth AND the per-emit quota read, which scans the LIVE file only.
+export async function enforceAuditRetention({ installRoot, retentionDays, now = new Date() } = {}) {
+  const days =
+    Number.isInteger(retentionDays) && retentionDays > 0
+      ? retentionDays
+      : (await readEventLogConfig(installRoot)).retentionDays;
+  const cutoff = new Date(now.getTime() - days * 86_400_000).toISOString();
+  const { old, kept, present } = await partitionAuditLines(installRoot, (ts) => ts < cutoff);
+  if (!present || !old.length) return { archived: 0, kept: kept.length, cutoff, retentionDays: days };
+  await archiveAuditLines(installRoot, old);
+  await rewriteAuditLog(installRoot, kept);
+  return { archived: old.length, kept: kept.length, cutoff, retentionDays: days };
+}
+
+// DELETE audit lines dated before `before` (operator wipe / privacy; mirrors event-log
+// purgeEvents, folded into `events purge`). `before` is a YYYY-MM-DD stamp; a line is old
+// when its ISO ts sorts before it (lexical — ts "2002-01-01T…" > "2002-01-01", so a line ON
+// the boundary day is KEPT, matching the day-file purge). With `archive`, old lines move to
+// audit.log.archive instead of being dropped.
+export async function purgeAuditLog({ installRoot, before, archive = false } = {}) {
+  if (typeof before !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(before)) {
+    throw new Error('audit purge requires --before YYYY-MM-DD');
+  }
+  const { old, kept, present } = await partitionAuditLines(installRoot, (ts) => ts < before);
+  if (!present || !old.length) return { purged: 0, kept: kept.length, before, archived: archive };
+  if (archive) await archiveAuditLines(installRoot, old);
+  await rewriteAuditLog(installRoot, kept);
+  return { purged: old.length, kept: kept.length, before, archived: archive };
+}
+
+// Attempts per (hook, session), counted from the 'firing' entries appended BEFORE each
+// spawn. Counting attempts — not completions — is what makes the quota bite on
+// recursive mutation-hook loops: a hook whose command re-enters `phronesis act` never
+// COMPLETES a fire while the chain grows, so a completion-counted quota would read 0
+// at every depth and guard nothing (found by the core-0013 adversarial review). Skips
+// never consume quota, or a kill-switched hook would burn its budget doing nothing.
+function countAttempts(entries, hookId, sessionId) {
+  return entries.filter(
+    (e) => e.hook === hookId && e.session_id === sessionId && e.outcome === 'firing',
+  ).length;
+}
+
+// --- Execution -------------------------------------------------------------------------
+
+function parseSkipList(env) {
+  const raw = env.PHRONESIS_SKIP;
+  if (typeof raw !== 'string' || raw.trim() === '') return new Set();
+  return new Set(raw.split(',').map((s) => s.trim()).filter(Boolean));
+}
+
+// spawn with NO shell; the event record on stdin; hard timeout. Resolves
+// { exitCode, error?, stderrTail } — never rejects (failure handling is the caller's
+// audit + gate logic).
+//
+// Settle on 'exit', NOT 'close': close waits for every stdio pipe to drain, and a hook
+// that leaves a background child inheriting stderr (`something &`) would keep the pipe
+// open — stalling the act pipeline long after the script itself exited, past the very
+// timeout that exists to prevent hangs (found by the core-0013 adversarial review,
+// reproduced live). The stderr tail is whatever arrived by exit time. The timeout
+// force-settles immediately after the kill for the same reason — an unkillable or
+// orphan-holding child must not hold the pipeline either; the audit records the
+// timeout, and the orphan is the operator-owned script's own mess.
+function runCommand({ file, event, env, timeoutMs, cwd }) {
+  return new Promise((resolvePromise) => {
+    let child;
+    try {
+      child = spawn(file, [], {
+        shell: false,
+        cwd,
+        env,
+        stdio: ['pipe', 'ignore', 'pipe'],
+      });
+    } catch (err) {
+      resolvePromise({ exitCode: null, error: err.message, stderrTail: '' });
+      return;
+    }
+    let stderr = '';
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise(result);
+    };
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      settle({
+        exitCode: null,
+        error: `timed out after ${timeoutMs}ms (killed)`,
+        stderrTail: stderr.slice(-300),
+      });
+    }, timeoutMs);
+    child.stderr.on('data', (chunk) => {
+      if (stderr.length < 4096) stderr += chunk.toString();
+    });
+    child.on('error', (err) => {
+      settle({ exitCode: null, error: err.message, stderrTail: stderr.slice(-300) });
+    });
+    child.on('exit', (code, signal) => {
+      settle({
+        exitCode: code,
+        error:
+          code === 0
+            ? undefined
+            : code === null
+              ? `killed by ${signal}`
+              : `exited ${code}`,
+        stderrTail: stderr.slice(-300),
+      });
+    });
+    child.stdin.on('error', () => {}); // a hook that closes stdin early is not an exec failure
+    child.stdin.end(`${JSON.stringify(event)}\n`);
+  });
+}
+
+// Fire every hook matching `event`, synchronously and in registry order (H6). Every
+// attempt and every outcome is audited (a fire writes a 'firing' attempt line BEFORE
+// the spawn, then its 'fired'/'failed' result — the pre-spawn line is what in-flight
+// quota counting and forensics on a crashed hook stand on); gate-kind failures are
+// returned for the caller to translate into the pipeline's refusal shapes (refuse at
+// requested; surface-after-write at committed — the artifact is never rolled back:
+// agents do not delete). Once a gate has failed, the remaining matched hooks are
+// SKIPPED (audited): a gate guards everything behind it in registry order, and firing
+// a mutation hook for an action a gate already condemned would honor a proposal the
+// pipeline is about to refuse.
+//
+// Concurrency: quota counting is read-then-append over the audit file, so two
+// simultaneous callers in one session could each read N-1 and both fire — the same
+// ONE-writer-per-installation assumption the action core documents (actions.js);
+// serialization is the daemon's job (V1.5) when multi-caller surfaces arrive.
+export async function executeHooksFor({
+  installRoot,
+  hooks,
+  event,
+  env = process.env,
+  timeoutMs = HOOK_TIMEOUT_MS,
+} = {}) {
+  const matched = matchingHooks(hooks, event);
+  const results = [];
+  const gateFailures = [];
+  if (!matched.length) return { results, gateFailures };
+
+  const skip = parseSkipList(env);
+  const hooksDir = join(installRoot, '.phronesis', 'hooks');
+  // One disk read per emit point; attempts made within this call are counted in
+  // memory on top of it (the audit file is append-only, so the snapshot stays valid).
+  const priorEntries = await readAuditLog(installRoot);
+  const attempted = new Map();
+  const attemptsFor = (id) =>
+    (attempted.get(id) || 0) + countAttempts(priorEntries, id, event.session_id);
+
+  for (const hook of matched) {
+    const base = {
+      session_id: event.session_id,
+      hook: hook.id,
+      kind: hook.kind,
+      classification: hook.classification,
+      event_type: event.type,
+      event_id: event.id,
+    };
+
+    if (gateFailures.length) {
+      await appendAudit(installRoot, {
+        ...base,
+        outcome: 'skipped-gate-failed',
+        gate: gateFailures[0].id,
+      });
+      results.push({ id: hook.id, outcome: 'skipped-gate-failed' });
+      continue;
+    }
+
+    if (skip.has(hook.id)) {
+      // Bypass discipline: documented, logged — operators invent unlogged bypasses if
+      // you don't ship a logged one.
+      await appendAudit(installRoot, { ...base, outcome: 'skipped-kill-switch' });
+      results.push({ id: hook.id, outcome: 'skipped-kill-switch' });
+      continue;
+    }
+
+    if (attemptsFor(hook.id) >= hook.quota.max_per_session) {
+      await appendAudit(installRoot, {
+        ...base,
+        outcome: 'skipped-quota',
+        quota: hook.quota.max_per_session,
+      });
+      results.push({ id: hook.id, outcome: 'skipped-quota' });
+      continue;
+    }
+    attempted.set(hook.id, (attempted.get(hook.id) || 0) + 1);
+    await appendAudit(installRoot, { ...base, outcome: 'firing' });
+
+    // Exec-time containment re-check (belt to the load-time anchor): the resolved file
+    // must sit inside .phronesis/hooks/.
+    const file = resolve(installRoot, hook.command);
+    let outcome;
+    if (!file.startsWith(hooksDir + sep)) {
+      outcome = { exitCode: null, error: `command resolves outside ${COMMAND_PREFIX} — refused`, stderrTail: '' };
+    } else {
+      const started = Date.now();
+      outcome = await runCommand({
+        file,
+        event,
+        timeoutMs,
+        cwd: installRoot,
+        env: {
+          ...env,
+          PHRONESIS_HOOK_ID: hook.id,
+          PHRONESIS_EVENT_TYPE: event.type,
+        },
+      });
+      outcome.durationMs = Date.now() - started;
+    }
+
+    const failed = outcome.exitCode !== 0;
+    await appendAudit(installRoot, {
+      ...base,
+      outcome: failed ? 'failed' : 'fired',
+      ...(outcome.exitCode !== null ? { exit_code: outcome.exitCode } : {}),
+      ...(outcome.error ? { error: outcome.error } : {}),
+      ...(outcome.stderrTail ? { stderr_tail: outcome.stderrTail } : {}),
+      ...(outcome.durationMs !== undefined ? { duration_ms: outcome.durationMs } : {}),
+    });
+    results.push({ id: hook.id, outcome: failed ? 'failed' : 'fired', exitCode: outcome.exitCode });
+    if (failed && hook.kind === 'gate') {
+      gateFailures.push({
+        id: hook.id,
+        error: outcome.error || 'failed',
+        stderrTail: outcome.stderrTail || '',
+      });
+    }
+  }
+  return { results, gateFailures };
+}