mandrel 2.31.0 → 2.32.0

package/.agents/scripts/lib/signals/detectors/retry.js

@@ -1,253 +0,0 @@
-/**
- * Retry detector — pure module (Epic #1721 / Story #1768 / Task #1773).
- *
- * Scans a `traces.ndjson` file for repeated **failed** Bash invocations
- * keyed by a stable command identity, and emits one `kind: 'retry'`
- * SignalEvent per identity whose failure count strictly exceeds the
- * configured threshold. Pure: takes a file path in, returns events out.
- * Emission to disk is the caller's job.
- *
- * ## Identity rule
- *
- * The detector groups failed Bash trace records by:
- *
- *   1. `details.normalizedHash` when present (canonical form — collapses
- *      whitespace, strips benign flags like `--no-color` / `--quiet`,
- *      and treats `npm test` ≡ `npm run test`). Set by
- *      `lib/observability/tool-trace-hook.js` (Story #1768 / Task #1775).
- *   2. `details.targetHash` as the fallback when `normalizedHash` is
- *      absent (e.g. legacy traces, or a Bash event whose command was
- *      empty / non-string and the normaliser declined to emit a hash).
- *
- * Records that have neither hash are skipped — without a stable key we
- * cannot group repeats. The grouping is by the chosen identity hash, so
- * `npm test` and `npm  run  test` (different `targetHash`, identical
- * `normalizedHash`) collapse into one bucket.
- *
- * ## Failure rule
- *
- * A trace record is treated as **failed** when its `details.exitCode`
- * is a number and not `0`. As of Epic #4406 / Story #4413 the tool-trace
- * hook captures `details.exitCode` for Bash `PostToolUse` events, so this
- * detector fires on real deliveries; records without an `exitCode` field
- * (non-Bash tools, or tools that report no exit code) are ignored, which
- * matches the decision in the parent Epic body that retry only counts
- * non-zero-exit commands.
- *
- * Successful runs after failures **do not** cancel the count — failure-
- * count is monotonic per identity. This matches the Epic's intent: once
- * a command has failed N times, the friction signal has happened, even
- * if a later attempt succeeded. The detector is observational, not a
- * status check.
- *
- * ## Tool filter
- *
- * Only trace records whose `emitter.tool === 'Bash'` participate. Edit /
- * Write / Read / Grep / Glob events are not retries — those belong to
- * other detectors (rework for file-edit churn). The tool name is read
- * from `emitter.tool` first and falls back to `details.tool` (see
- * `common.extractTool`).
- *
- * ## Privacy contract
- *
- * Identity hashes are sha256 strings produced by the hook before any
- * raw value reaches disk (see `lib/observability/tool-trace-hook.js`
- * `hashTarget`). The detector never sees plaintext commands and never
- * reverses a hash. Emitted signals carry `details.commandHash` — the
- * same `sha256:<hex>` string that drove the grouping — so downstream
- * surfaces can dedupe across a Story without ever resolving back to a
- * raw command string.
- *
- * ## Threshold semantics
- *
- * `failureCount > threshold` (strictly greater than). An identity with
- * exactly `threshold` failures does NOT emit. This matches the
- * `delivery.signals.retry.repeatCount` config surface (Epic #1720) —
- * the configured value is the maximum tolerated repeat count, not the
- * trigger count.
- *
- * ## Robustness
- *
- *   - Missing `tracesPath` file → returns `[]`. Never throws.
- *   - Malformed JSON lines → silently skipped (consistent with
- *     `lib/signals/read.js`).
- *   - Non-trace records → ignored. The file may legitimately interleave
- *     other kinds in future.
- *   - Non-Bash trace records → ignored.
- *
- * @module lib/signals/detectors/retry
- */
-
-import { createReadStream } from 'node:fs';
-import fs from 'node:fs/promises';
-import { createInterface } from 'node:readline';
-
-import { extractTool, validateDetectorArgs } from './common.js';
-
-/**
- * Documented argv-normalisation rules — emitted verbatim onto every
- * retry signal so the downstream renderer can show the operator which
- * paraphrases collapsed. Kept as a frozen array so callers cannot
- * mutate the canonical list.
- *
- * Mirrors the rule list in `lib/observability/tool-trace-hook.js`
- * `normaliseBashCommand` — keep these in sync when extending the
- * normaliser.
- *
- * @type {ReadonlyArray<string>}
- */
-export const NORMALIZATION_RULES = Object.freeze([
-  'collapse-whitespace',
-  'strip-benign-flags:--no-color,--quiet',
-  'npm-test-equiv-npm-run-test',
-]);
-
-/**
- * Resolve the identity key used to group a Bash trace record. Prefers
- * `details.normalizedHash` (canonical form, collapses paraphrases),
- * falls back to `details.targetHash` (raw-command hash). Returns `null`
- * when neither is present — the caller skips those records.
- *
- * @param {object} rec
- * @returns {string|null}
- */
-function resolveIdentity(rec) {
-  const normalized = rec?.details?.normalizedHash;
-  if (typeof normalized === 'string' && normalized.length > 0) {
-    return normalized;
-  }
-  const target = rec?.details?.targetHash;
-  if (typeof target === 'string' && target.length > 0) {
-    return target;
-  }
-  return null;
-}
-
-/**
- * Decide whether a trace record represents a failed invocation. As of
- * Epic #4406 / Story #4413 the tool-trace hook records `details.exitCode`
- * for Bash `PostToolUse` events, so the field is present on real Bash
- * traces (and still set directly by tests). A record counts as failed
- * when `details.exitCode` is a number and not zero. Anything else
- * (missing field, null, non-number, zero) is NOT a failure and is ignored
- * entirely — the detector only counts non-zero-exit commands per the
- * parent Epic.
- *
- * @param {object} rec
- * @returns {boolean}
- */
-function isFailedBash(rec) {
-  const code = rec?.details?.exitCode;
-  return typeof code === 'number' && code !== 0;
-}
-
-/**
- * Stream `tracesPath` line-by-line and accumulate per-identity failure
- * counts. Returns a `Map<identityHash, count>`. Missing file → empty map.
- *
- * @param {string} tracesPath
- * @returns {Promise<Map<string, number>>}
- */
-async function tallyFailuresByIdentity(tracesPath) {
-  const counts = new Map();
-
-  // Existence check before opening the stream — `createReadStream`
-  // defers ENOENT until the first read, which leaves the iterator in a
-  // bad state on some Node versions. `fs.access` short-circuits cleanly.
-  try {
-    await fs.access(tracesPath);
-  } catch {
-    return counts;
-  }
-
-  const stream = createReadStream(tracesPath, { encoding: 'utf8' });
-  const rl = createInterface({ input: stream, crlfDelay: Infinity });
-
-  try {
-    for await (const rawLine of rl) {
-      if (rawLine.length === 0) continue;
-      let parsed;
-      try {
-        parsed = JSON.parse(rawLine);
-      } catch {
-        // Mirrors lib/signals/read.js — partial-write races are common.
-        continue;
-      }
-      if (parsed == null || typeof parsed !== 'object') continue;
-      if (parsed.kind !== 'trace') continue;
-
-      const tool = extractTool(parsed);
-      if (tool !== 'Bash') continue;
-
-      if (!isFailedBash(parsed)) continue;
-
-      const identity = resolveIdentity(parsed);
-      if (identity == null) continue;
-
-      counts.set(identity, (counts.get(identity) ?? 0) + 1);
-    }
-  } finally {
-    rl.close();
-    if (!stream.destroyed) stream.destroy();
-  }
-
-  return counts;
-}
-
-/**
- * Detect retries against `tracesPath`. Returns a `kind: 'retry'`
- * SignalEvent for every identity whose failure count strictly exceeds
- * `threshold`. Pure — emission to disk is the caller's responsibility.
- *
- * The detector takes `threshold` as a function arg and never reaches
- * for `getSignals(config).retry.repeatCount`. Resolving the threshold
- * from config lives at the call site so this module stays import-graph-
- * free of `lib/config/*`.
- *
- * @param {object} args
- * @param {string} args.tracesPath — absolute path to a `traces.ndjson`.
- * @param {number} args.epicId — positive integer Epic ID.
- * @param {number} args.storyId — positive integer Story ID.
- * @param {number|null} [args.taskId] — positive integer Task ID, or null.
- * @param {number} args.threshold — the maximum tolerated failure count;
- *   identities with `failureCount > threshold` emit. MUST be a
- *   non-negative integer.
- * @param {() => string} [args.nowFn] — optional clock seam returning the
- *   ISO-8601 `ts` stamped onto every emitted SignalEvent. Defaults to
- *   `() => new Date().toISOString()`. Inject a fixed-return function in
- *   tests to make the emitted `ts` deterministic. MUST, when provided, be
- *   a function.
- * @returns {Promise<object[]>} array of SignalEvent objects conforming
- *   to `.agents/schemas/signal-event.schema.json`.
- */
-export async function detectRetry(args) {
-  const { tracesPath, epicId, storyId, taskId, threshold, nowFn } =
-    validateDetectorArgs(args, { fnName: 'detectRetry' });
-
-  const counts = await tallyFailuresByIdentity(tracesPath);
-
-  // Stable order: sort by identity hash ascending so the same input
-  // always yields the same emission sequence (eases snapshot tests and
-  // downstream deduping).
-  const offenders = [];
-  for (const [identity, count] of counts) {
-    if (count > threshold) offenders.push([identity, count]);
-  }
-  offenders.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
-
-  const ts = nowFn();
-  return offenders.map(([commandHash, failureCount]) => ({
-    ts,
-    kind: 'retry',
-    emitter: { tool: 'retry-detector' },
-    epicId,
-    storyId,
-    taskId,
-    details: {
-      commandHash,
-      failureCount,
-      threshold,
-      normalizationRules: [...NORMALIZATION_RULES],
-    },
-  }));
-}

package/.agents/scripts/lib/signals/detectors/rework.js

@@ -1,167 +0,0 @@
-/**
- * Rework detector — pure module (Epic #1721 / Story #1771 / Task #1774).
- *
- * Scans a `traces.ndjson` file for repeated edits against the same target
- * (keyed by hashed `details.targetHash`) and emits one `kind: 'rework'`
- * SignalEvent per offending target whose edit count strictly exceeds the
- * configured threshold. Pure: takes a file path in, returns events out.
- * Emission to disk is the caller's job.
- *
- * ## Counting rule
- *
- * Only file-mutating tools are counted:
- *   - `Edit`
- *   - `Write`
- *   - `MultiEdit`
- *   - `NotebookEdit`
- *
- * Every other tool (Read, Bash, Grep, Glob, …) is ignored. Trace records
- * without a `details.targetHash` are also skipped — without a stable key
- * we cannot group repeats.
- *
- * ## Privacy contract
- *
- * Trace records key off `details.targetHash` (a sha256 of the file path,
- * see `lib/observability/tool-trace-hook.js`). The detector groups by
- * the hash, never the raw path, so the privacy boundary established by
- * the hook is preserved end-to-end. A future analyzer that wants to
- * surface the offending path must resolve the hash through a separate
- * mapping — the detector itself never touches plaintext.
- *
- * ## Threshold semantics
- *
- * `editCount > threshold` (strictly greater than). A target with exactly
- * `threshold` edits does NOT emit; only the first edit *past* the
- * threshold trips the detector. This matches the
- * `delivery.signals.rework.editsPerFile` config surface (Epic #1720) —
- * the configured value is the maximum tolerated count, not the trigger
- * count.
- *
- * ## Robustness
- *
- *   - Missing `tracesPath` file → returns `[]`. Never throws.
- *   - Malformed JSON lines → silently skipped (consistent with the
- *     `lib/signals/read.js` reader).
- *   - Non-trace records → ignored (the file may legitimately contain
- *     other kinds in future).
- *
- * @module lib/signals/detectors/rework
- */
-
-import { createReadStream } from 'node:fs';
-import fs from 'node:fs/promises';
-import { createInterface } from 'node:readline';
-
-import { extractTool, validateDetectorArgs } from './common.js';
-
-/**
- * Tools that mutate files. Only these contribute to the per-target edit
- * count. Anything outside this set is ignored.
- *
- * @type {ReadonlySet<string>}
- */
-const FILE_MUTATING_TOOLS = Object.freeze(
-  new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']),
-);
-
-/**
- * Stream `tracesPath` line-by-line and accumulate per-targetHash edit
- * counts. Returns a `Map<targetHash, count>`. Missing file → empty map.
- *
- * @param {string} tracesPath
- * @returns {Promise<Map<string, number>>}
- */
-async function tallyEditsByTarget(tracesPath) {
-  const counts = new Map();
-
-  // Existence check before opening the stream — `createReadStream`
-  // defers ENOENT until the first read, which leaves the iterator in a
-  // bad state on some Node versions. `fs.access` short-circuits cleanly.
-  try {
-    await fs.access(tracesPath);
-  } catch {
-    return counts;
-  }
-
-  const stream = createReadStream(tracesPath, { encoding: 'utf8' });
-  const rl = createInterface({ input: stream, crlfDelay: Infinity });
-
-  try {
-    for await (const rawLine of rl) {
-      if (rawLine.length === 0) continue;
-      let parsed;
-      try {
-        parsed = JSON.parse(rawLine);
-      } catch {
-        // Mirrors lib/signals/read.js — malformed lines are common
-        // during a partial-write race; skip silently.
-        continue;
-      }
-      if (parsed == null || typeof parsed !== 'object') continue;
-      // We only care about trace records; the file is named
-      // traces.ndjson but a future writer may interleave other kinds.
-      if (parsed.kind !== 'trace') continue;
-
-      const tool = extractTool(parsed);
-      if (tool == null || !FILE_MUTATING_TOOLS.has(tool)) continue;
-
-      const hash = parsed.details?.targetHash;
-      if (typeof hash !== 'string' || hash.length === 0) continue;
-
-      counts.set(hash, (counts.get(hash) ?? 0) + 1);
-    }
-  } finally {
-    rl.close();
-    if (!stream.destroyed) stream.destroy();
-  }
-
-  return counts;
-}
-
-/**
- * Detect rework against `tracesPath`. Returns a `kind: 'rework'`
- * SignalEvent for every targetHash whose edit count strictly exceeds
- * `threshold`. Pure — emission to disk is the caller's responsibility.
- *
- * @param {object} args
- * @param {string} args.tracesPath — absolute path to a `traces.ndjson`.
- * @param {number} args.epicId — positive integer Epic ID.
- * @param {number} args.storyId — positive integer Story ID.
- * @param {number|null} [args.taskId] — positive integer Task ID, or null.
- * @param {number} args.threshold — the maximum tolerated edit count;
- *   targets with `editCount > threshold` emit. MUST be a non-negative
- *   integer.
- * @param {() => string} [args.nowFn] — optional clock seam returning the
- *   ISO-8601 `ts` stamped onto every emitted SignalEvent. Defaults to
- *   `() => new Date().toISOString()`. Inject a fixed-return function in
- *   tests to make the emitted `ts` deterministic. MUST, when provided, be
- *   a function.
- * @returns {Promise<object[]>} array of SignalEvent objects
- *   conforming to `.agents/schemas/signal-event.schema.json`.
- */
-export async function detectRework(args) {
-  const { tracesPath, epicId, storyId, taskId, threshold, nowFn } =
-    validateDetectorArgs(args, { fnName: 'detectRework' });
-
-  const counts = await tallyEditsByTarget(tracesPath);
-
-  // Stable order: sort by targetHash ascending so the same input always
-  // yields the same emission sequence (eases snapshot testing and
-  // downstream deduping).
-  const offenders = [];
-  for (const [hash, count] of counts) {
-    if (count > threshold) offenders.push([hash, count]);
-  }
-  offenders.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
-
-  const ts = nowFn();
-  return offenders.map(([targetHash, editCount]) => ({
-    ts,
-    kind: 'rework',
-    emitter: { tool: 'rework-detector' },
-    epicId,
-    storyId,
-    taskId,
-    details: { targetHash, editCount, threshold },
-  }));
-}

package/.agents/scripts/lib/signals/read.js

@@ -1,268 +0,0 @@
-/**
- * Streaming signals reader (Epic #1181 / Story #1438 / Task #1459).
- *
- * Provides one async-iterator entry point — `read({ run, story?, kind?,
- * config? })` — that consumers use instead of opening the NDJSON file
- * themselves. The reader streams line-by-line so callers never load the
- * full file into memory (50MB+ traces stay under file size in RSS).
- *
- * On-disk layout (resolved via `lib/config/temp-paths.js`):
- *
- *   <tempRoot>/run-<run>/story-<story>/signals.ndjson
- *
- * When `story` is omitted, the reader fans out across every
- * `story-<id>/signals.ndjson` under `<tempRoot>/run-<run>/`. When the
- * run directory is missing, the iterator yields nothing (consumers
- * treat absence as "no signals yet").
- *
- * ## Filter semantics
- *
- *   - `kind` — when provided, only events whose `kind` matches the
- *     argument are yielded. Filtering happens after the per-line JSON
- *     parse + envelope guard (see `lib/signals/schema.js`).
- *   - `story` — narrows to a single Story's stream; otherwise we walk
- *     every Story directory under the run.
- *
- * ## Warn-once policy (AC #3)
- *
- *   Malformed JSON lines are common during a partial write race; we
- *   warn **once per process** (module-level latch) rather than per line
- *   so a corrupted tail doesn't drown the operator log. The latch
- *   carries the first offending path/line and a count for follow-up.
- *
- * ## Robustness
- *
- *   The reader never throws on a missing file, a permission error, or
- *   malformed JSON — every failure path resolves to "no more events"
- *   so the analyzer can keep walking. Errors from the supplied
- *   `tempRoot` resolver propagate (those are programmer errors, not
- *   I/O conditions).
- *
- * @module lib/signals/read
- */
-
-import { createReadStream } from 'node:fs';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { createInterface } from 'node:readline';
-import {
-  runArtifactPath,
-  runTempDir,
-  signalsFile,
-  storyTempDir,
-} from '../config/temp-paths.js';
-import { parseStoryBranch } from '../git-utils.js';
-import { Logger } from '../Logger.js';
-
-import { isPositiveInt } from './detectors/common.js';
-import { EVENT_KIND_VALUES, hasCommonEnvelope } from './schema.js';
-
-// Module-level latch. Carries `{ path, lineNumber, totalCount }` for the
-// first malformed line we see in this process; subsequent malformed
-// lines bump `totalCount` without emitting. Reset is intentionally
-// not exposed — the warn-once contract is process-wide.
-const _malformedLatch = { fired: false, totalCount: 0 };
-
-/**
- * Test-only helper to reset the warn-once latch. Not part of the public
- * surface — exported so the unit test can exercise per-test isolation
- * without spawning a new Node process.
- *
- * @returns {void}
- */
-export function __resetMalformedLatchForTests() {
-  _malformedLatch.fired = false;
-  _malformedLatch.totalCount = 0;
-}
-
-/**
- * Snapshot of the current warn-once state. Test-only — surfaces the
- * count of malformed lines observed so the unit suite can assert that
- * "10 bad lines → 1 warn but count=10".
- *
- * @returns {{ fired: boolean, totalCount: number }}
- */
-export function __getMalformedLatchForTests() {
-  return { ..._malformedLatch };
-}
-
-function warnOnceMalformed(targetPath, lineNumber, parseErr) {
-  _malformedLatch.totalCount += 1;
-  if (_malformedLatch.fired) return;
-  _malformedLatch.fired = true;
-  Logger.warn(
-    `signals/read: malformed JSON encountered (first at ${targetPath}:${lineNumber}: ${
-      parseErr instanceof Error ? parseErr.message : String(parseErr)
-    }); further malformed lines suppressed for this process.`,
-  );
-}
-
-/**
- * Stream one signals.ndjson file as an async iterable of parsed records.
- * Internal helper; consumers go through `read()`.
- *
- * @param {string} target — absolute on-disk path
- * @param {string | null} kindFilter — kind to filter on (null = no filter)
- * @returns {AsyncGenerator<object>}
- */
-async function* streamFile(target, kindFilter) {
-  // Existence check before opening the stream — `createReadStream`
-  // defers ENOENT until the first `read()`, which leaves the async
-  // iterator with an uncatchable error mid-flight on some Node
-  // versions. `fs.access` is cheap and gives us a clean early return.
-  try {
-    await fs.access(target);
-  } catch {
-    return;
-  }
-
-  const stream = createReadStream(target, { encoding: 'utf8' });
-  const rl = createInterface({ input: stream, crlfDelay: Infinity });
-
-  let lineNumber = 0;
-  try {
-    for await (const rawLine of rl) {
-      lineNumber += 1;
-      if (rawLine.length === 0) continue;
-      let parsed;
-      try {
-        parsed = JSON.parse(rawLine);
-      } catch (err) {
-        warnOnceMalformed(target, lineNumber, err);
-        continue;
-      }
-      if (!hasCommonEnvelope(parsed)) continue;
-      if (kindFilter != null && parsed.kind !== kindFilter) continue;
-      yield parsed;
-    }
-  } finally {
-    rl.close();
-    // `stream.destroy()` is idempotent — `rl.close()` already pulls
-    // the underlying stream down on its own, but we drop it explicitly
-    // here to satisfy the Windows file-handle leak check.
-    if (!stream.destroyed) stream.destroy();
-  }
-}
-
-/**
- * List every `stories/story-<id>/signals.ndjson` path under the run's
- * `<tempRoot>/run-<run>/` directory. Returns an empty array when the
- * run directory is missing.
- *
- * The returned paths are sorted by Story ID ascending so the iterator's
- * output is stable across runs.
- *
- * Story #2940 nested per-Story directories under a `stories/` segment.
- * Run-level signals continue to live at the run root.
- *
- * @param {number} run
- * @param {object | undefined} config
- * @returns {Promise<string[]>}
- */
-async function listRunStorySignalsFiles(run, config) {
-  const runDir = runTempDir(run, config);
-  let runEntries;
-  try {
-    runEntries = await fs.readdir(runDir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  let hasRunLevelSignals = false;
-  let hasStoriesDir = false;
-  for (const ent of runEntries) {
-    if (ent.isDirectory() && ent.name === 'stories') {
-      hasStoriesDir = true;
-    } else if (ent.isFile() && ent.name === 'signals.ndjson') {
-      // Story #1430 — wave-runner lifecycle signals land here.
-      hasRunLevelSignals = true;
-    }
-  }
-  const storyIds = [];
-  if (hasStoriesDir) {
-    let storyEntries;
-    try {
-      storyEntries = await fs.readdir(path.join(runDir, 'stories'), {
-        withFileTypes: true,
-      });
-    } catch {
-      storyEntries = [];
-    }
-    for (const ent of storyEntries) {
-      if (!ent.isDirectory()) continue;
-      const sid = parseStoryBranch(ent.name);
-      if (sid === null || !isPositiveInt(sid)) continue;
-      storyIds.push(sid);
-    }
-  }
-  storyIds.sort((a, b) => a - b);
-  // Yield run-level signals first (wave-start precedes per-Story friction),
-  // then walk the per-Story streams in ascending ID order.
-  const targets = hasRunLevelSignals
-    ? [runArtifactPath(run, 'signals.ndjson', config)]
-    : [];
-  for (const sid of storyIds) {
-    targets.push(path.join(storyTempDir(run, sid, config), 'signals.ndjson'));
-  }
-  return targets;
-}
-
-/**
- * Stream every event matching `{ run, story?, kind? }` from the
- * configured `tempRoot`'s `run-<run>/[story-<story>/]signals.ndjson`
- * file(s).
- *
- * Returns an async iterable so callers can `for await` over it without
- * buffering. The reader is **streaming** — peak memory stays below the
- * file size for any input.
- *
- * @param {{ run: number, story?: number, kind?: string, config?: object }} args
- * @returns {AsyncGenerator<object>}
- *
- * @example
- *   for await (const evt of read({ run: 1181 })) { ... }
- *   for await (const evt of read({ run: 1181, story: 1438, kind: 'friction' })) { ... }
- */
-export async function* read(args) {
-  if (args == null || typeof args !== 'object') {
-    throw new TypeError(
-      `signals/read: args must be an object with at minimum { run }; got ${args}`,
-    );
-  }
-  const { run, story, kind, config } = args;
-  if (!isPositiveInt(run)) {
-    throw new RangeError(
-      `signals/read: run must be a positive integer (got ${run})`,
-    );
-  }
-  if (story !== undefined && !isPositiveInt(story)) {
-    throw new RangeError(
-      `signals/read: story must be a positive integer when provided (got ${story})`,
-    );
-  }
-  if (kind !== undefined && kind !== null) {
-    if (typeof kind !== 'string' || kind.length === 0) {
-      throw new TypeError(
-        `signals/read: kind must be a non-empty string when provided (got ${kind})`,
-      );
-    }
-    if (!EVENT_KIND_VALUES.has(kind)) {
-      // Unknown kinds are not technically invalid — a future detector
-      // might emit a new kind that we don't yet know about. We warn
-      // (best effort) but still let the iterator run so the consumer
-      // can adopt the new kind without code change here.
-      Logger.warn(
-        `signals/read: kind '${kind}' is not in the current EVENT_KINDS enumeration; iterating anyway.`,
-      );
-    }
-  }
-
-  const kindFilter = kind ?? null;
-  const targets =
-    story !== undefined
-      ? [signalsFile(run, story, config)]
-      : await listRunStorySignalsFiles(run, config);
-
-  for (const target of targets) {
-    yield* streamFile(target, kindFilter);
-  }
-}