mandrel 1.87.0 → 1.89.0

package/.agents/scripts/lib/observability/perf-report-readers.js

@@ -274,7 +274,7 @@ export async function aggregateBaselineFrictionFromSignals({
         ) {
           return;
         }
-        const ts = Date.parse(record.timestamp);
+        const ts = Date.parse(record.ts);
         if (Number.isFinite(ts) && ts < cutoffMs) return;
 
         totalRecords += 1;

package/.agents/scripts/lib/observability/signal-validator.js

@@ -0,0 +1,204 @@
+/**
+ * signal-validator.js — write-time validation of NDJSON signal records
+ * against the canonical `signal-event.schema.json` (Epic #4406 /
+ * Story #4413).
+ *
+ * The signals writer calls {@link validateSignal} before appending a
+ * record so a schema-invalid line is dropped with a `Logger.warn` naming
+ * the violating field rather than polluting the stream (and defeating the
+ * downstream consumers that assume the canonical shape). Validation is
+ * best-effort: the writer contract (Tech Spec #1032) is preserved —
+ * observability MUST NOT throw into the runner, so every helper here
+ * swallows its own faults and degrades to "treat as valid" only when the
+ * validator itself cannot be constructed.
+ *
+ * The AJV instance compiles the on-disk schema **once** at module load so
+ * the writer and the contract test validate against the exact same
+ * document (no hand-rolled drift). `strict: false` matches the repo's
+ * other draft-07 validators (see `tests/schemas/signal-schemas.test.js`).
+ *
+ * A per-Epic reject tally is persisted under the Epic temp tree
+ * (`temp/epic-<eid>/signal-rejects.json`) so a cross-process reader (the
+ * loop-health check, a follow-on Story) can surface how many records were
+ * dropped. The tally is read-modify-written best-effort; a lost increment
+ * under a write race is acceptable for a diagnostic counter.
+ */
+
+import { readFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+import { epicArtifactPath } from '../config/temp-paths.js';
+import { Logger } from '../Logger.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'signal-event.schema.json',
+);
+
+const REJECT_TALLY_BASENAME = 'signal-rejects.json';
+
+/**
+ * Compile the signal-event schema once. Returns `null` when the schema
+ * cannot be read or compiled — the caller then treats every record as
+ * valid (fail-open) so a packaging error never silently drops all
+ * signals.
+ *
+ * @returns {import('ajv').ValidateFunction | null}
+ */
+function buildValidator() {
+  try {
+    const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    return ajv.compile(schema);
+  } catch (err) {
+    Logger.warn(
+      `signal-validator: failed to compile signal-event schema (${
+        err instanceof Error ? err.message : String(err)
+      }); write-time validation disabled for this process.`,
+    );
+    return null;
+  }
+}
+
+const _validate = buildValidator();
+
+/**
+ * Derive a human-readable "violating field" label from the first AJV
+ * error. Prefers the missing property name (required errors) or the
+ * instance path, falling back to the raw message.
+ *
+ * @param {import('ajv').ErrorObject[] | null | undefined} errors
+ * @returns {string}
+ */
+function violatingFieldOf(errors) {
+  const first = Array.isArray(errors) && errors.length > 0 ? errors[0] : null;
+  if (!first) return 'unknown';
+  if (first.keyword === 'required' && first.params?.missingProperty) {
+    return String(first.params.missingProperty);
+  }
+  if (typeof first.instancePath === 'string' && first.instancePath.length > 0) {
+    return first.instancePath.replace(/^\//, '').replace(/\//g, '.');
+  }
+  if (
+    first.keyword === 'additionalProperties' &&
+    first.params?.additionalProperty
+  ) {
+    return String(first.params.additionalProperty);
+  }
+  return first.message ?? 'unknown';
+}
+
+/**
+ * Validate a signal record against the canonical schema.
+ *
+ * Fail-open: when the validator could not be compiled the record is
+ * reported valid (the writer keeps working). A non-object record is
+ * reported invalid without invoking AJV.
+ *
+ * @param {unknown} record
+ * @returns {{ valid: boolean, violatingField: string|null, message: string|null }}
+ */
+export function validateSignal(record) {
+  if (_validate === null) {
+    return { valid: true, violatingField: null, message: null };
+  }
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+    return {
+      valid: false,
+      violatingField: 'record',
+      message: 'signal record must be a plain object',
+    };
+  }
+  const valid = _validate(record);
+  if (valid) return { valid: true, violatingField: null, message: null };
+  const field = violatingFieldOf(_validate.errors);
+  const message = _validate.errors?.[0]?.message ?? 'schema validation failed';
+  return { valid: false, violatingField: field, message };
+}
+
+/**
+ * Increment the per-Epic reject tally persisted under the Epic temp tree.
+ * Best-effort and never throws: a missing/corrupt tally file resets to a
+ * count of 1. When `epicId` is not a positive integer (e.g. a standalone
+ * friction record with `epicId: null`) the tally write is skipped — there
+ * is no Epic temp tree to anchor it to.
+ *
+ * @param {{ epicId: number|null|undefined, config?: object, field?: string|null }} args
+ * @returns {Promise<number|null>} the new count, or null when skipped/failed.
+ */
+export async function recordSignalReject({ epicId, config, field }) {
+  if (!Number.isInteger(epicId) || epicId <= 0) return null;
+  let target;
+  try {
+    target = epicArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
+  } catch {
+    return null;
+  }
+  try {
+    let prior = { count: 0, lastField: null };
+    try {
+      const raw = await fs.readFile(target, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (
+        parsed &&
+        typeof parsed === 'object' &&
+        Number.isFinite(parsed.count)
+      ) {
+        prior = { count: parsed.count, lastField: parsed.lastField ?? null };
+      }
+    } catch {
+      // Missing or corrupt file → start a fresh tally.
+    }
+    const next = {
+      count: prior.count + 1,
+      lastField: field ?? prior.lastField ?? null,
+      updatedAt: new Date().toISOString(),
+    };
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, `${JSON.stringify(next)}\n`, 'utf8');
+    return next.count;
+  } catch (err) {
+    Logger.warn(
+      `signal-validator: failed to persist reject tally for epic-${epicId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Read the current per-Epic reject count. Cross-process readable
+ * counterpart to {@link recordSignalReject}. Returns 0 when the tally
+ * file is absent or unreadable.
+ *
+ * @param {{ epicId: number, config?: object }} args
+ * @returns {Promise<number>}
+ */
+export async function readSignalRejectCount({ epicId, config }) {
+  if (!Number.isInteger(epicId) || epicId <= 0) return 0;
+  let target;
+  try {
+    target = epicArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
+  } catch {
+    return 0;
+  }
+  try {
+    const raw = await fs.readFile(target, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && Number.isFinite(parsed.count) ? parsed.count : 0;
+  } catch {
+    return 0;
+  }
+}

package/.agents/scripts/lib/observability/signals-writer.js

@@ -42,6 +42,7 @@ import {
   storyTempDir,
 } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
+import { recordSignalReject, validateSignal } from './signal-validator.js';
 import { classifyPathSource } from './source-classifier.js';
 
 const TRACES_BASENAME = 'traces.ndjson';
@@ -60,20 +61,23 @@ function tracesFile(eid, sid, config) {
  * Best-effort decoration of a signal record with a `source` field
  * (`"framework"` or `"consumer"`) produced by `classifyPathSource`.
  *
- * Rules (Epic #2547 / Story #2553 / Tech Spec #2550):
+ * Post the Epic #4406 cutover `source` is reserved **exclusively** for
+ * this framework/consumer classification — a record's originating tool
+ * lives in `emitter`, never `source`. That freed the classifier to run
+ * for every friction record (pre-cutover a provenance object under the
+ * `source` key blocked it via `Object.hasOwn`).
+ *
+ * Rules:
  *   - If the record is not a plain object (string, number, null,
- *     undefined), return it unchanged — the writer's existing
- *     serialisation guard will reject or pass it through as before.
- *   - If the caller pre-set `signal.source`, preserve it verbatim. Some
- *     detectors classify upstream (e.g. wave-lifecycle signals always
- *     belong to the framework) and we MUST NOT overwrite their
- *     intentional tag.
- *   - Otherwise, invoke `classifyPathSource` against the record's
- *     `failingPath` / `path` and `command` fields, and inject the result
- *     as a new `source` key. The classifier itself never throws, but we
- *     belt-and-braces a try/catch so an unexpected fault degrades to a
- *     `Logger.warn` and a passthrough of the original signal — never a
- *     dropped write.
+ *     undefined), return it unchanged.
+ *   - If the caller pre-set `source` to exactly `"framework"` or
+ *     `"consumer"`, preserve it verbatim — some detectors classify
+ *     upstream and we MUST NOT overwrite their intentional tag.
+ *   - Otherwise (absent, or any other value — defense in depth against a
+ *     stray non-canonical `source`), invoke `classifyPathSource` against
+ *     the record's `failingPath` / `path` and `command` /
+ *     `emitter.command` fields and inject/overwrite `source` with the
+ *     result.
  *
  * @param {unknown} signal
  * @returns {unknown}
@@ -82,16 +86,17 @@ function tagSignalSource(signal) {
   if (signal === null || typeof signal !== 'object' || Array.isArray(signal)) {
     return signal;
   }
-  // Caller-supplied source wins, even when undefined-typed but present as
-  // an own property — only inject when the key is absent entirely so we
-  // never overwrite an explicit decision.
-  if (Object.hasOwn(signal, 'source')) {
-    return signal;
+  const record = /** @type {Record<string, unknown>} */ (signal);
+  if (record.source === 'framework' || record.source === 'consumer') {
+    return record;
   }
   try {
-    const record = /** @type {Record<string, unknown>} */ (signal);
     const failingPath = record.failingPath ?? record.path;
-    const command = record.command;
+    const emitter =
+      record.emitter && typeof record.emitter === 'object'
+        ? /** @type {Record<string, unknown>} */ (record.emitter)
+        : null;
+    const command = record.command ?? emitter?.command;
     const source = classifyPathSource(failingPath, command);
     return { ...record, source };
   } catch (err) {
@@ -104,6 +109,27 @@ function tagSignalSource(signal) {
   }
 }
 
+/**
+ * Validate a record against the canonical `signal-event.schema.json`
+ * before it is appended. On failure the record is **dropped** (never
+ * appended), a `Logger.warn` names the violating field, and the per-Epic
+ * reject tally is incremented under the Epic temp tree. Never throws —
+ * the writer's best-effort contract is preserved.
+ *
+ * @param {unknown} record
+ * @param {{ epicId?: number|null, config?: object, label: string }} ctx
+ * @returns {Promise<boolean>} true when the record is valid (safe to append).
+ */
+async function validateOrDrop(record, { epicId, config, label }) {
+  const { valid, violatingField, message } = validateSignal(record);
+  if (valid) return true;
+  Logger.warn(
+    `signals-writer: dropping schema-invalid ${label} record — violating field '${violatingField}' (${message}).`,
+  );
+  await recordSignalReject({ epicId, config, field: violatingField });
+  return false;
+}
+
 /**
  * Best-effort append of a single record as one newline-terminated JSON
  * line. Caller-supplied record must be JSON-serialisable; circular refs
@@ -163,14 +189,24 @@ export async function appendSignal(args) {
     );
     return false;
   }
-  return appendOne(target, tagSignalSource(signal));
+  const tagged = tagSignalSource(signal);
+  const ok = await validateOrDrop(tagged, {
+    epicId: Number.isInteger(epicId) ? epicId : null,
+    config,
+    label: 'signal',
+  });
+  if (!ok) return false;
+  return appendOne(target, tagged);
 }
 
 /**
  * Append one signal record to the per-Epic stream at
- * `temp/epic-<eid>/signals.ndjson` — used for wave-lifecycle signals
- * (`wave-start`, `wave-tick`, `wave-complete`, `epic-complete`) that are
- * not scoped to an individual Story.
+ * `temp/epic-<eid>/signals.ndjson` — used for Epic-scoped signals not tied
+ * to an individual Story: the wave-window forensics kinds (`wave-start`,
+ * `wave-complete`), notification-derived anchors (`state-transition`,
+ * `notification.emitted`), and Epic-level `friction` (e.g.
+ * `lifecycle-emit.js`). The retired write-only kinds `wave-tick` /
+ * `epic-complete` are gone (Story #3909) and are NOT valid here.
  *
  * @param {{ epicId: number, signal: unknown, config?: object }} args
  * @returns {Promise<boolean>}
@@ -188,7 +224,14 @@ export async function appendEpicSignal(args) {
     );
     return false;
   }
-  return appendOne(target, tagSignalSource(signal));
+  const tagged = tagSignalSource(signal);
+  const ok = await validateOrDrop(tagged, {
+    epicId: Number.isInteger(epicId) ? epicId : null,
+    config,
+    label: 'epic signal',
+  });
+  if (!ok) return false;
+  return appendOne(target, tagged);
 }
 
 /**
@@ -211,41 +254,32 @@ export async function appendTrace(args) {
     );
     return false;
   }
+  const ok = await validateOrDrop(trace, {
+    epicId: Number.isInteger(epicId) ? epicId : null,
+    config,
+    label: 'trace',
+  });
+  if (!ok) return false;
   return appendOne(target, trace);
 }
 
 /**
- * Stream `signals.ndjson` line by line, invoking `cb(parsed, lineNumber)`
- * for each successfully parsed JSON line. `lineNumber` is 1-based to
- * match operator log expectations. Malformed lines are skipped with a
- * `Logger.warn`. A missing file resolves with `missing: true` rather
- * than throwing — the analyzer treats absence as "no signals yet" and
- * keeps walking.
+ * Stream any NDJSON `target` file line by line, invoking
+ * `cb(parsed, lineNumber)` for each successfully parsed JSON line.
+ * `lineNumber` is 1-based to match operator log expectations. Malformed
+ * lines are skipped with a `Logger.warn`. A missing file resolves with
+ * `missing: true` rather than throwing.
  *
- * @param {number} epicId
- * @param {number} storyId
+ * Shared spine for `forEachLine` (per-Story stream) and `forEachEpicLine`
+ * (per-Epic stream) so the two readers cannot drift in their
+ * malformed-line / missing-file / cb-throw handling.
+ *
+ * @param {string} target
  * @param {(parsed: unknown, lineNumber: number) => unknown | Promise<unknown>} cb
- * @param {object} [config]
+ * @param {string} label   Reader name used in warn messages.
  * @returns {Promise<{ linesRead: number, linesParsed: number, missing: boolean }>}
  */
-export async function forEachLine(epicId, storyId, cb, config) {
-  if (typeof cb !== 'function') {
-    Logger.warn('signals-writer: forEachLine called without a callback');
-    return { linesRead: 0, linesParsed: 0, missing: false };
-  }
-
-  let target;
-  try {
-    target = signalsFile(epicId, storyId, config);
-  } catch (err) {
-    Logger.warn(
-      `signals-writer: invalid epicId/storyId for forEachLine: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return { linesRead: 0, linesParsed: 0, missing: false };
-  }
-
+async function forEachLineIn(target, cb, label) {
   try {
     await fs.access(target);
   } catch {
@@ -278,7 +312,7 @@ export async function forEachLine(epicId, storyId, cb, config) {
         await cb(parsed, linesRead);
       } catch (err) {
         Logger.warn(
-          `signals-writer: forEachLine cb threw at ${target}:${linesRead}: ${
+          `signals-writer: ${label} cb threw at ${target}:${linesRead}: ${
             err instanceof Error ? err.message : String(err)
           }`,
         );
@@ -286,7 +320,7 @@ export async function forEachLine(epicId, storyId, cb, config) {
     }
   } catch (err) {
     Logger.warn(
-      `signals-writer: forEachLine read failed for ${target}: ${
+      `signals-writer: ${label} read failed for ${target}: ${
         err instanceof Error ? err.message : String(err)
       }`,
     );
@@ -294,3 +328,72 @@ export async function forEachLine(epicId, storyId, cb, config) {
 
   return { linesRead, linesParsed, missing: false };
 }
+
+/**
+ * Stream a per-Story `signals.ndjson` line by line, invoking
+ * `cb(parsed, lineNumber)` for each successfully parsed JSON line. A
+ * missing file resolves with `missing: true` rather than throwing — the
+ * analyzer treats absence as "no signals yet" and keeps walking.
+ *
+ * @param {number} epicId
+ * @param {number} storyId
+ * @param {(parsed: unknown, lineNumber: number) => unknown | Promise<unknown>} cb
+ * @param {object} [config]
+ * @returns {Promise<{ linesRead: number, linesParsed: number, missing: boolean }>}
+ */
+export async function forEachLine(epicId, storyId, cb, config) {
+  if (typeof cb !== 'function') {
+    Logger.warn('signals-writer: forEachLine called without a callback');
+    return { linesRead: 0, linesParsed: 0, missing: false };
+  }
+
+  let target;
+  try {
+    target = signalsFile(epicId, storyId, config);
+  } catch (err) {
+    Logger.warn(
+      `signals-writer: invalid epicId/storyId for forEachLine: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return { linesRead: 0, linesParsed: 0, missing: false };
+  }
+
+  return forEachLineIn(target, cb, 'forEachLine');
+}
+
+/**
+ * Stream the per-Epic `signals.ndjson` line by line, invoking
+ * `cb(parsed, lineNumber)` for each successfully parsed JSON line. This is
+ * the read side of `appendEpicSignal` — the wave-lifecycle stream at
+ * `temp/epic-<eid>/signals.ndjson` written by `appendEpicSignal` callers
+ * (e.g. `lifecycle-emit`). A missing file resolves with `missing: true`
+ * rather than throwing, mirroring the per-Story `forEachLine` contract so
+ * the retro's unified counts scan can fold the Epic stream in alongside the
+ * Story streams without a special-cased absence branch.
+ *
+ * @param {number} epicId
+ * @param {(parsed: unknown, lineNumber: number) => unknown | Promise<unknown>} cb
+ * @param {object} [config]
+ * @returns {Promise<{ linesRead: number, linesParsed: number, missing: boolean }>}
+ */
+export async function forEachEpicLine(epicId, cb, config) {
+  if (typeof cb !== 'function') {
+    Logger.warn('signals-writer: forEachEpicLine called without a callback');
+    return { linesRead: 0, linesParsed: 0, missing: false };
+  }
+
+  let target;
+  try {
+    target = epicArtifactPath(epicId, EPIC_SIGNALS_BASENAME, config);
+  } catch (err) {
+    Logger.warn(
+      `signals-writer: invalid epicId for forEachEpicLine: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return { linesRead: 0, linesParsed: 0, missing: false };
+  }
+
+  return forEachLineIn(target, cb, 'forEachEpicLine');
+}

package/.agents/scripts/lib/observability/tool-trace-hook.js

@@ -220,10 +220,10 @@ function hashBashInput(toolInput) {
  * (`tool_input.file_path`, `tool_input.path`, `tool_input.pattern`)
  * before recording. The raw value never appears on disk.
  *
- * @param {{ tool: string, toolInput?: object, durationMs?: number|null }} args
+ * @param {{ tool: string, toolInput?: object, durationMs?: number|null, exitCode?: number|null }} args
  * @returns {object}
  */
-function buildDetails({ tool, toolInput, durationMs }) {
+function buildDetails({ tool, toolInput, durationMs, exitCode }) {
   const details = {};
   if (typeof durationMs === 'number') {
     details.durationMs = durationMs;
@@ -231,6 +231,14 @@ function buildDetails({ tool, toolInput, durationMs }) {
     details.durationMs = null;
   }
 
+  // Bash exit code — the retry detector's failure predicate
+  // (`details.exitCode !== 0`) can only fire once this is recorded. Only
+  // Bash PostToolUse events carry a meaningful exit code; other tools omit
+  // the field entirely (Epic #4406 / Story #4413).
+  if (tool === 'Bash' && typeof exitCode === 'number') {
+    details.exitCode = exitCode;
+  }
+
   if (toolInput && typeof toolInput === 'object') {
     // Bash: hash `command` so a token-laden string never lands on disk.
     // Story #1768 also records `normalizedHash` (paraphrase-collapsed)
@@ -273,6 +281,35 @@ function buildDetails({ tool, toolInput, durationMs }) {
   return details;
 }
 
+/**
+ * Extract the Bash exit code from a PostToolUse event. The harness reports
+ * the tool result under `tool_response` (occasionally at the event root);
+ * the exit-code field name is not contractually fixed across harness
+ * versions, so we probe the known aliases and return the first numeric
+ * hit. Returns `null` when no numeric exit code is present — the caller
+ * omits `details.exitCode` entirely rather than recording a guess.
+ *
+ * Exported for testing.
+ *
+ * @param {object} event
+ * @returns {number|null}
+ */
+export function extractExitCode(event) {
+  const candidates = [
+    event?.tool_response?.exitCode,
+    event?.tool_response?.exit_code,
+    event?.tool_response?.returnCode,
+    event?.tool_response?.code,
+    event?.tool_response?.status,
+    event?.exit_code,
+    event?.exitCode,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'number' && Number.isFinite(c)) return c;
+  }
+  return null;
+}
+
 /**
  * PreToolUse handler. Stashes `{ startedAt, tool }` into the in-flight
  * Map keyed by the harness `tool_use_id`. Does not append to
@@ -306,6 +343,7 @@ export async function handlePost(event, active) {
   const id = event?.tool_use_id ?? event?.id ?? null;
   const tool = event?.tool_name ?? event?.tool ?? 'unknown';
   const toolInput = event?.tool_input;
+  const exitCode = extractExitCode(event);
 
   let durationMs = null;
   if (id && inflight.has(id)) {
@@ -317,13 +355,13 @@ export async function handlePost(event, active) {
   const trace = {
     ts: new Date().toISOString(),
     kind: 'trace',
-    source: { tool: clamp(tool) },
+    emitter: { tool: clamp(tool) },
     epicId: active.epicId,
     storyId: active.storyId,
     taskId: null,
     phase:
       typeof process.env.CC_PHASE === 'string' ? process.env.CC_PHASE : null,
-    details: buildDetails({ tool, toolInput, durationMs }),
+    details: buildDetails({ tool, toolInput, durationMs, exitCode }),
   };
 
   await appendTrace({

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -174,7 +174,7 @@ export function buildAcceptanceEvalSignal({
     epicId: epicId ?? null,
     storyId,
     phase,
-    source: { tool: 'acceptance-eval.js' },
+    emitter: { tool: 'acceptance-eval.js' },
     details: {
       decision: outcome.decision,
       round: outcome.round,