@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/src/runtime/evidence-ledger.ts

@@ -0,0 +1,338 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { REPO_ROOT } = require('../helper/repo-root.ts');
+const { updateTaskState, readTaskState, mergeRecords } = require('./task-state.ts');
+const { taskStoreDir } = require('./task-scope.ts');
+
+const VALID_EVIDENCE_KINDS = new Set([
+  'exact-search',
+  'semantic-retrieval',
+  'structural',
+  'historical',
+  'documentation',
+  'test-result',
+  'runtime-observation',
+  'user-statement',
+  'diff',
+  'generated-analysis',
+]);
+
+const VALID_PROVENANCE = new Set(['extracted', 'inferred', 'asserted']);
+
+/** An item's lifecycle status, distinct from `freshness.status` (a snapshot judgment about the
+ * file the item points at, which a later edit can only ever move toward STALE, never back).
+ * 'active' is the only non-terminal value; 'superseded' is terminal and permanent — mirrors
+ * `claims.js`'s TERMINAL_CLAIM_STATUSES so a fresher record can retire an item without deleting
+ * it (NFR-003 applies here the same way it does to claims). */
+const EVIDENCE_STATUSES = new Set(['active', 'superseded']);
+
+/**
+ * Gate for a status arriving from disk. The set above was declared and exported while nothing read
+ * it, so the "mirrors claims.js" claim in the comment held for the declaration and not for the use.
+ *
+ * This throws where `claims.js` normalizes, and the asymmetry is deliberate: an unrecognized claim
+ * status falls back to `'hypothesis'`, the weakest state, so the worst case is a claim having to
+ * earn its support again. There is no equivalently safe default here. Treating an unreadable status
+ * as `'active'` would silently un-retire superseded evidence and feed it back into readiness — the
+ * exact failure `supersede` exists to prevent — and treating it as `'superseded'` would retire
+ * evidence nobody retired. With no safe direction, the honest move is to refuse the file and name
+ * the item, rather than pick one and be wrong in a way no output reveals.
+ *
+ * @param {object} item
+ * @param {string} file the ledger path, so the message says which file to look at
+ * @returns {object} the same item, once its status is one of the two
+ */
+function assertKnownStatus(item: any, file: string) {
+  const status = item?.status;
+  if (!EVIDENCE_STATUSES.has(status)) {
+    throw new Error(
+      `Evidence '${item?.id ?? '(no id)'}' in ${file} has status '${status}', which is not one of: `
+      + `${[...EVIDENCE_STATUSES].join(', ')}. Refusing to guess whether it is active.`,
+    );
+  }
+  return item;
+}
+
+/** A task id becomes a filename inside the state directory, so it must not be able to name a path.
+ * `path.join(stateDir, `${taskId}.json`)` happily resolves `../../../etc/hosts` out of the state
+ * dir entirely — read-only today only because nothing calls save(), and an arbitrary file write
+ * the moment a writer is wired up. Constrain it to a flat, filename-safe token instead of trying
+ * to sanitize a traversal after the fact.
+ * @param {string} taskId
+ * @returns {string} the validated id, for use in an expression
+ */
+function assertSafeTaskId(taskId: string): string {
+  if (typeof taskId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(taskId) || taskId.includes('..')) {
+    throw new Error(`Invalid task id '${taskId}': expected letters, digits, dot, dash or underscore, and no path separators`);
+  }
+  return taskId;
+}
+
+class EvidenceLedger {
+  declare fsImpl: any;
+  declare repoRoot: any;
+  declare fixedStateDir: any;
+  declare slug: any;
+  declare stateDir: any;
+  declare evidenceMap: Map<any, any>;
+  declare baseline: Map<any, any>;
+  declare seq: number;
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.repoRoot]
+   * @param {string} [options.stateDir] a fixed directory; when given, no feature namespace applies
+   * @param {string} [options.slug] feature whose namespace the records live under (see task-scope.js)
+   * @param {Object} [options.fsImpl]
+   */
+  constructor(options: any = {}) {
+    this.fsImpl = options.fsImpl || fs;
+    this.repoRoot = options.repoRoot || REPO_ROOT;
+    this.fixedStateDir = options.stateDir || null;
+    this.slug = options.slug || null;
+    this.stateDir = this.fixedStateDir || path.join(this.repoRoot, '.doflow', 'state', 'evidence');
+    this.evidenceMap = new Map();
+    this.baseline = new Map();
+    this.seq = 0;
+  }
+
+  /** Where this task's evidence file lives: the feature's namespace when it has one (IC-002). */
+  fileFor(taskId: any) {
+    const dir = this.fixedStateDir
+      || taskStoreDir({ projectRoot: this.repoRoot, store: 'evidence', taskId, slug: this.slug });
+    return path.join(dir, `${assertSafeTaskId(taskId)}.json`);
+  }
+
+  /**
+   * Generates a unique evidence identifier. Uniqueness must hold ACROSS instances and processes,
+   * not just within one: ids key the concurrency-safe merge in save() (task-state.js), and two
+   * ledgers minting `ev_<ms>_1` in the same millisecond made the merge collapse two distinct
+   * observations into one — the very lost write R4 exists to prevent, reintroduced by an id
+   * scheme. The random component carries that burden; timestamp and sequence stay for readability.
+   * @returns {string}
+   */
+  generateId(): string {
+    this.seq += 1;
+    return `ev_${Date.now().toString(36)}_${crypto.randomBytes(4).toString('hex')}_${this.seq.toString(36)}`;
+  }
+
+  /**
+   * Validates and registers a new evidence item.
+   * @param {Object} item
+   * @returns {string} evidenceId
+   */
+  addEvidence(item: any): string {
+    if (!item || typeof item !== 'object') {
+      throw new Error('Evidence item must be an object');
+    }
+
+    if (!item.kind || !VALID_EVIDENCE_KINDS.has(item.kind)) {
+      throw new Error(`Invalid evidence kind '${item.kind}'. Allowed: ${[...VALID_EVIDENCE_KINDS].join(', ')}`);
+    }
+
+    const provenance = item.provenance || 'extracted';
+    if (!VALID_PROVENANCE.has(provenance)) {
+      throw new Error(`Invalid provenance '${provenance}'. Allowed: ${[...VALID_PROVENANCE].join(', ')}`);
+    }
+
+    const id = item.id || this.generateId();
+    const taskId = item.taskId || 'default';
+
+    const source = item.source || {
+      provider: 'unknown',
+      capability: 'general',
+    };
+
+    const freshness = {
+      gitCommit: item.freshness?.gitCommit || null,
+      fileHash: item.freshness?.fileHash || null,
+      observedAt: item.freshness?.observedAt || new Date().toISOString(),
+      status: item.freshness?.status || 'FRESH',
+    };
+
+    const evidenceRecord = {
+      id,
+      taskId,
+      kind: item.kind,
+      source,
+      locator: item.locator || {},
+      provenance,
+      content: item.content || null,
+      freshness,
+      // Which template requirements this item claims to establish. Readiness counts an item toward
+      // a requirement only when the writer named it here — kind-matching alone let an item saying
+      // "tests failed" satisfy a passing-baseline requirement (architecture review R1, P1).
+      establishes: Array.isArray(item.establishes) ? [...item.establishes] : [],
+      // Typed execution record for test-result / runtime-observation items: what ran and how it
+      // exited. Tree identity and time live in freshness (gitCommit, observedAt).
+      observation: item.observation
+        ? { command: item.observation.command, exitCode: item.observation.exitCode }
+        : null,
+      supports: Array.isArray(item.supports) ? [...item.supports] : [],
+      contradicts: Array.isArray(item.contradicts) ? [...item.contradicts] : [],
+      // Every item starts 'active'. Not settable through addEvidence's own input (EVIDENCE_ITEM_FIELDS
+      // in cli.js does not list it) — the only way to reach 'superseded' is supersedeEvidence below,
+      // the same boundary claims.js already draws around its own status field.
+      status: 'active',
+      supersededBy: null,
+    };
+
+    this.evidenceMap.set(id, evidenceRecord);
+    return id;
+  }
+
+  /**
+   * Retrieves an evidence item by ID.
+   * @param {string} id
+   * @returns {Object|null}
+   */
+  getEvidence(id: string) {
+    return this.evidenceMap.get(id) || null;
+  }
+
+  /**
+   * Queries evidence items matching criteria.
+   * @param {Object} [filter={}]
+   * @returns {Array<Object>}
+   */
+  queryEvidence(filter: any = {}) {
+    const results = [];
+    for (const item of this.evidenceMap.values()) {
+      if (filter.taskId && item.taskId !== filter.taskId) continue;
+      if (filter.kind && item.kind !== filter.kind) continue;
+      if (filter.provider && item.source.provider !== filter.provider) continue;
+      if (filter.capability && item.source.capability !== filter.capability) continue;
+      if (filter.file && item.locator.file !== filter.file) continue;
+      if (filter.status && item.freshness.status !== filter.status) continue;
+      results.push(item);
+    }
+    return results;
+  }
+
+  /**
+   * Records that this item's content no longer represents the tree as it stands, and points
+   * forward to the item that does. Nothing is deleted or rewritten: the record and its original
+   * freshness stay exactly as observed, only `status` changes — mirrors
+   * `ClaimsManager.supersedeClaim` field for field, including the checks and their order (the
+   * replacement is validated before the target, for the same reason: a typo in the target reads
+   * as "unknown evidence" either way, but a typo in the replacement should not be reported as a
+   * problem with the target instead).
+   * @param {string} evidenceId the item to retire
+   * @param {string} replacedBy the id of the item that supersedes it; must already exist
+   * @returns {string} the new status
+   */
+  supersedeEvidence(evidenceId: string, replacedBy: string): string {
+    if (!replacedBy) {
+      throw new Error('supersede requires the id of the evidence item that replaces this one');
+    }
+    if (replacedBy === evidenceId) {
+      throw new Error(`Evidence '${evidenceId}' cannot supersede itself`);
+    }
+    if (!this.evidenceMap.has(replacedBy)) {
+      throw new Error(`No evidence '${replacedBy}' is recorded — a forward pointer to nothing is worse `
+        + 'than no pointer. Record the replacing evidence first: doflow evidence --task-id <id> --action add ...');
+    }
+    const item = this.evidenceMap.get(evidenceId);
+    if (!item) {
+      throw new Error(`Unknown evidence '${evidenceId}'`);
+    }
+    if (item.status === 'superseded') {
+      throw new Error(`Evidence '${evidenceId}' is already superseded and cannot be superseded again`);
+    }
+    item.status = 'superseded';
+    item.supersededBy = replacedBy;
+    item.supersededAt = new Date().toISOString();
+    return item.status;
+  }
+
+  /**
+   * Marks all evidence items referencing modified files as STALE.
+   * @param {Array<string>} modifiedFiles
+   * @returns {number} count of invalidated items
+   */
+  invalidateFiles(modifiedFiles: any): number {
+    if (!Array.isArray(modifiedFiles) || modifiedFiles.length === 0) return 0;
+    const fileSet = new Set(modifiedFiles);
+    let count = 0;
+
+    for (const item of this.evidenceMap.values()) {
+      if (item.locator?.file && fileSet.has(item.locator.file)) {
+        item.freshness.status = 'STALE';
+        count += 1;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Returns all evidence records in memory.
+   * @returns {Array<Object>}
+   */
+  getAllEvidence() {
+    return Array.from(this.evidenceMap.values());
+  }
+
+  /**
+   * Persists evidence for a specific task to disk — locked, merged, revisioned (task-state.js).
+   * A concurrent writer's items that this instance never loaded survive the save: they are folded
+   * in from disk inside the lock, so overlapping sessions append rather than overwrite each other.
+   * @param {string} [taskId='default']
+   * @returns {string} filePath
+   */
+  save(taskId = 'default'): string {
+    const targetFile = this.fileFor(taskId);
+    let merged: any;
+    const file = updateTaskState({
+      fsImpl: this.fsImpl, file: targetFile,
+      build: (disk: any) => {
+        merged = mergeRecords(this.queryEvidence({ taskId }), disk?.evidence || [], this.baseline);
+        return { taskId, updatedAt: new Date().toISOString(), evidenceCount: merged.length, evidence: merged };
+      },
+    });
+    for (const item of merged) {
+      this.evidenceMap.set(item.id, item);
+      this.baseline.set(item.id, JSON.parse(JSON.stringify(item)));
+    }
+    return file;
+  }
+
+  /**
+   * Loads evidence for a task from disk into memory.
+   * @param {string} [taskId='default']
+   * @returns {number} count of loaded items
+   */
+  load(taskId = 'default'): number {
+    const targetFile = this.fileFor(taskId);
+    const data = readTaskState(this.fsImpl, targetFile);
+    if (data && Array.isArray(data.evidence)) {
+      for (const item of data.evidence) {
+        assertKnownStatus(item, targetFile);
+        this.evidenceMap.set(item.id, item);
+        this.baseline.set(item.id, JSON.parse(JSON.stringify(item)));
+      }
+      return data.evidence.length;
+    }
+    return 0;
+  }
+
+  /**
+   * Resets the in-memory ledger.
+   */
+  clear() {
+    this.evidenceMap.clear();
+    this.baseline.clear();
+    this.seq = 0;
+  }
+}
+
+module.exports = {
+  EvidenceLedger,
+  VALID_EVIDENCE_KINDS,
+  VALID_PROVENANCE,
+  EVIDENCE_STATUSES,
+  assertSafeTaskId,
+};

package/src/runtime/failure/capture.ts

@@ -0,0 +1,272 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The Node failure writer (IC-011, IC-014, IC-015, DEC-019, DEC-020). Records one line per internal
+ * error in the machine-wide `events.jsonl`. Capture is a side channel and must never be noticed by
+ * the command it observes:
+ *   - it writes no byte to stdout or stderr and never throws;
+ *   - it is synchronous and takes no lock (one append of one line);
+ *   - while capture is off it opens no file and creates no folder.
+ * Only the normalised, masked message is stored, never the raw message, argv, stdin or environment.
+ *
+ * Rotation by rename at 1 MiB is done here and by the `failure` verb only; the bash writers append.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.ts');
+const { normaliseMessage, maskLine } = require('../mask.ts');
+const { isProgrammingError, errorKind } = require('./classifier.ts');
+const { failureHome, captureIsOff, eventsPath } = require('./home.ts');
+
+const MAX_LINE_BYTES = 2048;
+const MAX_RAW_MESSAGE = 4096;
+const ROTATE_AT_BYTES = 1048576;
+const KEEP_ROTATED = 4;
+const PARTIAL_KEEP_MS = 60 * 60 * 1000;
+const ROTATED = /^events-\d{8}T\d{6}Z-\d+\.jsonl$/;
+const COMMAND_NAME = /^[a-z][a-z0-9-]{0,39}$/;
+
+/** Errors already recorded in this process, so one error caught at two points counts once. */
+const recorded = new WeakSet();
+
+let cachedVersion: string | null = null;
+/** The package version; the projected runtime ships no package.json, so a tolerant read. */
+function packageVersion(): string {
+  if (cachedVersion === null) {
+    try { cachedVersion = String(require('../../../package.json').version); } catch { cachedVersion = 'unknown'; }
+  }
+  return cachedVersion;
+}
+
+function harnessName(env: any): string {
+  const raw = env.DOFLOW_AGENT;
+  return typeof raw === 'string' && /^[A-Za-z0-9._-]{1,40}$/.test(raw) ? raw : 'none';
+}
+
+/** The absolute, non-root homes to compare a working directory with: HOME as given, its real path, and `os.homedir()`. */
+function homeCandidates(env: any): string[] {
+  const out: string[] = [];
+  const add = (value: any) => {
+    if (typeof value !== 'string' || !path.isAbsolute(value)) return;
+    const home = value.replace(/\/+$/, '');
+    if (home.length > 1 && !out.includes(home)) out.push(home);
+  };
+  add(env.HOME);
+  if (typeof env.HOME === 'string' && path.isAbsolute(env.HOME)) { try { add(fs.realpathSync(env.HOME)); } catch { /* HOME does not exist */ } }
+  try { add(os.homedir()); add(fs.realpathSync(os.homedir())); } catch { /* no home known to the system */ }
+  return out;
+}
+
+/**
+ * The working directory as stored: the home prefix written as `~` whichever way home is spelled (a
+ * symlinked HOME makes `process.cwd()` the physical path), masked like any other free text. A
+ * directory under no known home, when `HOME` itself is not usable, is stored as its folder name only,
+ * so an absolute path with a user name in it never reaches the file.
+ */
+function projectName(env: any): string {
+  let cwd: string;
+  try { cwd = process.cwd(); } catch { return ''; }
+  const home = homeCandidates(env).find((h) => cwd === h || cwd.startsWith(`${h}/`));
+  if (home) return maskLine(`~${cwd.slice(home.length)}`, { home: null }).text.slice(0, 200);
+  const homeGiven = typeof env.HOME === 'string' && path.isAbsolute(env.HOME);
+  if (!homeGiven) return maskLine(path.basename(cwd), { home: null }).text.slice(0, 200);
+  return maskLine(cwd, { home: env.HOME }).text.slice(0, 200);
+}
+
+function commandName(command: any): string {
+  return typeof command === 'string' && COMMAND_NAME.test(command) ? command : 'unknown';
+}
+
+/**
+ * The first stack frame inside DoFlow's own files as `<relative path>:<function>`, no line number
+ * (IC-011). Null when no frame is inside the package, which is also what keeps a frame from a
+ * dependency or a user's own file out of the record.
+ * @param {*} error
+ * @returns {string|null}
+ */
+function doflowFrame(error: any): string | null {
+  let stack: string;
+  try { stack = typeof error.stack === 'string' ? error.stack : ''; } catch { return null; }
+  const root = REPO_ROOT + path.sep;
+  for (const line of stack.split('\n')) {
+    const match = /^\s*at (?:async )?(?:(.+?) \()?(.+?):\d+:\d+\)?$/.exec(line);
+    if (!match) continue;
+    const file = match[2].replace(/^file:\/\//, '');
+    if (!file.startsWith(root) || file.includes(`${path.sep}node_modules${path.sep}`)) continue;
+    const fn = (match[1] || '').replace(/^new /, '').split('.').pop()!.replace(/\s.*$/, '') || '<anonymous>';
+    return `${path.relative(REPO_ROOT, file).split(path.sep).join('/')}:${fn}`;
+  }
+  return null;
+}
+
+/** One line at or under MAX_LINE_BYTES including the newline: shorten `message`, then `project`. */
+function buildLine(record: any): string | null {
+  const bytes = (r: any) => Buffer.byteLength(JSON.stringify(r), 'utf8') + 1;
+  const out = { ...record };
+  for (const field of ['message', 'project']) {
+    while (bytes(out) > MAX_LINE_BYTES && out[field].length > 0) {
+      out[field] = out[field].slice(0, Math.max(0, out[field].length - Math.max(8, bytes(out) - MAX_LINE_BYTES)));
+    }
+  }
+  return bytes(out) > MAX_LINE_BYTES ? null : `${JSON.stringify(out)}\n`;
+}
+
+const stamp = (date: Date): string => date.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+
+/** Rotated files with their size and modification time, oldest last-modified first (names alone tie inside one second). */
+function rotatedFiles(home: string): Array<{ name: string; size: number; mtime: number }> {
+  return fs.readdirSync(home).filter((name: string) => ROTATED.test(name)).map((name: string) => {
+    let size = 0;
+    let mtime = 0;
+    try { const st = fs.statSync(path.join(home, name)); size = st.size; mtime = st.mtimeMs; } catch { /* gone */ }
+    return { name, size, mtime };
+  }).sort((a: any, b: any) => a.mtime - b.mtime || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/**
+ * Removes rotated files beyond the newest four full ones, and partial ones (see rotateIfDue) once
+ * they are an hour old. A partial file never counts toward the four, so it cannot push a real one out.
+ */
+function prune(home: string, now = Date.now()): void {
+  const files = rotatedFiles(home);
+  const full = files.filter((f) => f.size >= ROTATE_AT_BYTES);
+  const doomed = [
+    ...full.slice(0, Math.max(0, full.length - KEEP_ROTATED)),
+    ...files.filter((f) => f.size < ROTATE_AT_BYTES && now - f.mtime > PARTIAL_KEEP_MS),
+  ];
+  for (const f of doomed) {
+    try { fs.unlinkSync(path.join(home, f.name)); } catch { /* ignored */ }
+  }
+}
+
+/**
+ * Rotation (IC-015): at 1 MiB the live file is renamed to `events-<UTC time>-<pid>.jsonl`, and the
+ * rotated files beyond the newest four are deleted. A failed rename or delete is ignored, so a
+ * process that lost the race simply appends to whatever is there.
+ *
+ * A process that measured the old live file may rename the fresh one another writer just created
+ * (it holds less than 1 MiB). That file is linked back as the live file when nobody has recreated it
+ * (same inode, so a writer still holding it loses nothing); when the live file exists again it stays
+ * as a small rotated file, which readers read like any other and which is never counted toward the
+ * four kept, so a real rotated file is never pushed out by one. Nothing is ever copied or deleted
+ * here except by prune, so no line is lost to the race.
+ * @param {string} home the failure home
+ * @returns {boolean} whether this call rotated a full file
+ */
+function rotateIfDue(home: string): boolean {
+  const live = eventsPath(home);
+  try {
+    if (fs.statSync(live).size < ROTATE_AT_BYTES) return false;
+  } catch { return false; }
+  // The name carries the second and the pid, so a process that rotates twice inside one second would
+  // rename onto its own earlier file and destroy it: take the next free second instead.
+  let rotated = path.join(home, `events-${stamp(new Date())}-${process.pid}.jsonl`);
+  for (let i = 1; i < 120 && fs.existsSync(rotated); i++) {
+    rotated = path.join(home, `events-${stamp(new Date(Date.now() + i * 1000))}-${process.pid}.jsonl`);
+  }
+  try {
+    fs.renameSync(live, rotated);
+  } catch { return false; }
+  let size = 0;
+  try { size = fs.statSync(rotated).size; } catch { return false; }
+  if (size < ROTATE_AT_BYTES) {
+    try { fs.linkSync(rotated, live); fs.unlinkSync(rotated); } catch { /* the live file exists again: the small file stays */ }
+    return false;
+  }
+  try { prune(home); } catch { /* ignored */ }
+  return true;
+}
+
+/**
+ * Appends one line to `file` only when it is absent or a regular file. A FIFO, a device or a symlink
+ * there is skipped silently: opening a FIFO for writing blocks until something reads it, which would
+ * hang the command capture is meant to observe. `O_NONBLOCK` fails such an open at once and the
+ * descriptor is checked before the write, so a file swapped in after any earlier check is still safe.
+ * @returns {boolean} whether the line was written
+ */
+function appendRegular(file: string, line: string): boolean {
+  const c = fs.constants;
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(file, c.O_WRONLY | c.O_APPEND | c.O_CREAT | (c.O_NOFOLLOW || 0) | (c.O_NONBLOCK || 0), 0o600);
+    if (!fs.fstatSync(fd).isFile()) return false;
+    fs.writeSync(fd, line);
+    return true;
+  } catch { return false; } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* nothing more to do */ } }
+  }
+}
+
+/**
+ * Appends one failure line. Every failure to do so is swallowed.
+ * @param {{source: string, command: string, kind: string, message?: string, frame?: string|null, exit?: number|null}} fields
+ *   `message` must already be normalised (see captureError).
+ * @param {Object} [env] defaults to process.env
+ * @returns {boolean} whether a line was written
+ */
+function captureFailure(fields: any, env = process.env): boolean {
+  try {
+    const home = failureHome(env);
+    if (!home || captureIsOff(home, env)) return false;
+    const line = buildLine({
+      v: 1,
+      at: new Date().toISOString(),
+      source: fields.source,
+      command: commandName(fields.command),
+      harness: harnessName(env),
+      version: packageVersion(),
+      project: projectName(env),
+      kind: String(fields.kind).slice(0, 80),
+      message: typeof fields.message === 'string' ? fields.message : '',
+      frame: typeof fields.frame === 'string' ? fields.frame : null,
+      exit: Number.isInteger(fields.exit) ? fields.exit : null,
+    });
+    if (line === null) return false;
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    rotateIfDue(home);
+    return appendRegular(eventsPath(home), line);
+  } catch {
+    return false;
+  }
+}
+
+/** The error's message cut to 4096 characters before any masking, so no input makes the rules do unbounded work. */
+function rawMessage(error: any): string {
+  try {
+    const message = error.message;
+    return typeof message === 'string' ? message.slice(0, MAX_RAW_MESSAGE) : '';
+  } catch { return ''; }
+}
+
+/**
+ * Records a caught error when it is a programming error (IC-010). The caller keeps doing whatever it
+ * did before: this returns a boolean and nothing else changes.
+ * @param {*} error
+ * @param {{command?: string, exit?: number|null, uncaught?: boolean}} [context]
+ *   `uncaught` marks an error that escaped every handler (kind `uncaught:<kind>`).
+ * @param {Object} [env]
+ * @returns {boolean} whether a line was written
+ */
+function captureError(error: any, context: any = {}, env = process.env): boolean {
+  try {
+    if (!isProgrammingError(error) || recorded.has(error)) return false;
+    recorded.add(error);
+    const kind = errorKind(error);
+    return captureFailure({
+      source: 'cli',
+      command: context.command,
+      kind: context.uncaught ? `uncaught:${kind}` : kind,
+      message: normaliseMessage(rawMessage(error), { home: env.HOME }),
+      frame: doflowFrame(error),
+      exit: context.exit,
+    }, env);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { appendRegular, captureFailure, captureError, rotateIfDue, doflowFrame, MAX_LINE_BYTES, ROTATE_AT_BYTES, KEEP_ROTATED };

package/src/runtime/failure/classifier.ts

@@ -0,0 +1,68 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The programming-error classifier (IC-010, DEC-013, DEC-031). Decides whether a caught error is a
+ * bug in DoFlow worth recording, as opposed to a finding, a refusal, a bad flag or a fault in the
+ * user's environment. Pure and total: it never throws, whatever it is handed.
+ *
+ * The same function is copied into core/harnesses/shared/hooks/stream-hook-runner.js, because hook
+ * files are installed without the runtime library; a test runs both copies over one fixture set.
+ */
+
+const CLASS_NAMES = new Set(['TypeError', 'RangeError', 'ReferenceError']);
+
+/** Reads one property without ever throwing: a throwing getter reads as undefined. */
+function read(error: any, key: string): any {
+  try { return error[key]; } catch { return undefined; }
+}
+
+/** `error instanceof Class`, never throwing. */
+function isA(error: any, Class: any): boolean {
+  try { return error instanceof Class; } catch { return false; }
+}
+
+/**
+ * The `instanceof` checks come first and every property read is guarded, so a getter that throws
+ * never drops a real TypeError.
+ * @param {*} error
+ * @returns {boolean}
+ */
+function isProgrammingError(error: any): boolean {
+  try {
+    if (error === null || typeof error !== 'object') return false;
+    const code = read(error, 'code');
+    const name = read(error, 'name');
+    // A broken pipe on stdout or stderr is the reader going away, not a bug (DEC-031).
+    if (code === 'EPIPE') return false;
+    if (isA(error, SyntaxError) || name === 'SyntaxError') return false;
+    if (isA(error, TypeError) || isA(error, RangeError) || isA(error, ReferenceError)) return true;
+    if (CLASS_NAMES.has(name)) return true;
+    if (name === 'AssertionError' || code === 'ERR_ASSERTION') return true;
+    if (code === 'MODULE_NOT_FOUND') return true;
+    return typeof code === 'string' && (typeof read(error, 'syscall') === 'string' || typeof read(error, 'errno') === 'number');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The `kind` a captured error is recorded under: the class name for the programming-error classes,
+ * else the error's code (a system error or MODULE_NOT_FOUND), else its name.
+ * @param {*} error
+ * @returns {string}
+ */
+function errorKind(error: any): string {
+  for (const Class of [TypeError, RangeError, ReferenceError]) {
+    if (isA(error, Class)) return Class.name;
+  }
+  const name = read(error, 'name');
+  const code = read(error, 'code');
+  if (CLASS_NAMES.has(name) || name === 'AssertionError') return name;
+  if (typeof code === 'string') return code;
+  if (typeof name === 'string' && name) return name;
+  return 'Error';
+}
+
+module.exports = { isProgrammingError, errorKind };