session-orchestrator 3.24.0 → 4.0.0

package/hooks/post-subagent-discovery-validator.mjs

@@ -18,18 +18,18 @@
  *      TAIL (last ~8 `type:"assistant"` records), concat text blocks. When no
  *      `agent_id` is derivable (or the file is absent) the hook exits 0 and
  *      records NOTHING — see the scope note below.
- *   5. Regex-scan the concatenated text for 8 claim patterns — 6 quantifier-
- *      triggered distributional claims, the #908 bare-cardinal repo-state
- *      fact ("14 commits", "92 learnings", "5 dirty files", "412 lines"), and
- *      the #918 numerator/denominator slash form ("12/14 files", "4/4 callers").
- *   6. For each match, check whether a fenced ```bash block containing a
- *      MEASUREMENT command (grep/rg/find/git/wc/jq/ls/node/npm) appears within
- *      ±5 lines. If a claim has NO adjacent measurement block → record a
- *      `discovery_validator_violation` event in events.jsonl + a stderr WARN.
- *   7. ADVISORY (#908 Baustein 2 input): for claims that ARE verified, check
- *      whether the adjacent block also carries a measurement TIMESTAMP (ISO
- *      date, `HEAD`, "as of", "measured at"). Undated-but-verified claims are
- *      counted and reported in the warn text — they are NOT violations in v1.
+ *   5. Hand the concatenated text to `hooks/_lib/subagent-transcript.mjs`
+ *      `findViolations()` — the whole matcher (claim patterns, negative-context
+ *      guards, evidence proximity, normalisation, dedup) lives there so it can
+ *      be measured against a claim corpus without spawning this hook. It
+ *      returns DEDUPLICATED `{claim, normalized, occurrences}` records.
+ *   6. Attribute the claim: `agent` + `agent_source` (`payload`|`meta`|`none`)
+ *      + `agent_description`, and — on `none` — the sorted stdin `payload_keys`
+ *      the harness DID send, so a gap is diagnosable from the ledger.
+ *   7. Write ONE record per distinct claim per session (session-scoped tmp
+ *      sentinel), plus a stderr WARN. ADVISORY (#908 Baustein 2 input): claims
+ *      that ARE verified but carry no measurement TIMESTAMP are counted and
+ *      reported in the warn text — never recorded as violations in v1.
  *
  * Why read a transcript at all: the SubagentStop stdin payload has NO
  * output_text field — the agent's text only exists on disk.
@@ -71,215 +71,12 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
+import { findViolations, readTranscriptTail } from './_lib/subagent-transcript.mjs';
 import { appendJsonl } from '../scripts/lib/common.mjs';
 import { eventsFilePath } from '../scripts/lib/events.mjs';
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { _parseDiscoveryValidator } from '../scripts/lib/config/discovery-validator.mjs';
 
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Number of trailing assistant records to scan. */
-const TAIL_RECORDS = 8;
-/** Proximity window (in lines) for an adjacent grep transcript. */
-const GREP_PROXIMITY_LINES = 5;
-/** Max characters of claim text persisted to the event record. */
-const CLAIM_TEXT_MAX = 200;
-
-/**
- * Code-distribution context nouns (singular or plural). A distributional claim
- * is only a PSA-006 *code* claim when one of these appears near the trigger —
- * this is what separates "4 of 4 callers" (a real claim) from "Turn 3 of 25"
- * (a turn counter) and "every caller imports X" from "every developer should
- * test" (generic advice). Tightening per W2-review LOW finding (#567).
- *
- * Single optional `\s?` only (call site / callsite) — no nested quantifiers,
- * so the alternation stays linear-time / ReDoS-safe.
- */
-const CTX = '(?:call\\s?sites?|callers?|sites?|references?|instances?|files?|consumers?|imports?|matches|match|occurrences?|usages?|modules?|tests?|places?|functions?|dependenc(?:y|ies)|endpoints?|hooks?)';
-
-/**
- * Repo-STATE nouns (#908). The four documented #908 drift cases were counts of
- * repository state, not of code locations: "14 commits", "92 learnings",
- * "5 dirty files", "412 lines". None of them contains a CTX noun, so the
- * original six patterns could not see them.
- *
- * Vocabulary taken from this repo's own artefacts (`.orchestrator/metrics/*.jsonl`
- * record kinds, `.claude/rules/`, `skills/`, `agents/`, `hooks/`) rather than a
- * generic English list — a noun that never names a countable repo artefact here
- * only buys false positives.
- */
-const STATE = '(?:commits?|learnings?|issues?|branches?|lines?|entries|records?|sessions?|rules?|skills?|probes?|waves?|proposals?|worktrees?)';
-
-/**
- * The noun class the BARE-CARDINAL pattern may use — deliberately a strict
- * subset of STATE ∪ CTX, restricted to the artefact kinds the #908 drift was
- * actually measured in (commit counts, learnings counts, open-issue counts,
- * branch counts, line counts, dirty-file counts).
- *
- * Measured, not guessed: over 32 real agent-stop windows from this repo's own
- * transcripts, admitting the full CTX ∪ STATE set fired 93 times (2.9 per
- * stop — the "validator gets switched off" zone). Every noun below earns its
- * place by naming one of the documented #908 facts; the ones that only cost
- * false positives (`tests`, `references`, `matches`, `agents`, `files` without
- * a state adjective) are excluded here and remain reachable through the six
- * quantifier-triggered patterns above, which have a lexical anchor.
- *
- * `callers` (#918): PSA-006's own canonical noun — the rule text's worked
- * examples ("4 of 4 callers", "100% of callers opt-in") all count callers, yet
- * the cardinal pattern could not see a bare "14 callers". Re-measured with it
- * admitted: 490 real SubagentStop transcripts (2026-07-31), +0 additional
- * firings from the bare form — the noun is free on this corpus (all +3 delta
- * firings came from the #918 slash pattern below).
- */
-const CARDINAL_NOUN = '(?:commits?|learnings?|issues?|branches?|lines?|files?|callers?)';
-
-/**
- * Wide noun class = code-distribution nouns ∪ repo-state nouns. Used by the six
- * QUANTIFIER-triggered patterns ("N of M", "100% of", "all N", "no remaining",
- * "none of") — each of those carries a strong lexical trigger, so widening the
- * noun set there is low-risk.
- *
- * Deliberately NOT used by the `every <noun>` pattern: `every` has no numeric
- * anchor, so `every commit must be signed` / `every rule is always-on` are
- * ordinary prose, not measured claims. That pattern keeps the narrow CTX.
- */
-const WIDE = `(?:${CTX}|${STATE})`;
-
-/** Bounded same-line gap between a trigger and its context noun. */
-const CTX_GAP = '[^\\n]{0,40}?';
-
-/**
- * Distributional-claim patterns (case-insensitive). A match is a PSA-006 claim
- * that requires an adjacent measurement transcript.
- *
- * Each pattern requires a context noun within a small, bounded same-line window
- * of the trigger. The `[^\n]{0,40}?` gap is a bounded lazy character class
- * (linear-time — the ReDoS-safety the W2 reviewer verified is preserved). True
- * claims ("4 of 4 callers opt-in", "every caller imports X", "no remaining
- * references to Y") still flag; benign strings ("Turn 3 of 25 complete",
- * "every developer should test", "100% of users love it") do not.
- */
-const CLAIM_PATTERNS = [
-  new RegExp(`\\b\\d+ of \\d+\\b${CTX_GAP}\\b${WIDE}\\b`, 'i'),
-  new RegExp(`100% of\\b${CTX_GAP}\\b${WIDE}\\b`, 'i'),
-  new RegExp(`\\ball \\d+\\b${CTX_GAP}\\b${WIDE}\\b`, 'i'),
-  new RegExp(`no remaining\\b${CTX_GAP}\\b${WIDE}\\b`, 'i'),
-  new RegExp(`every ${CTX}\\b`, 'i'),
-  new RegExp(`none of\\b${CTX_GAP}\\b${WIDE}\\b`, 'i'),
-];
-
-/**
- * Pattern 7 (#908) — the BARE CARDINAL repo-state fact. `14 commits` has no
- * quantifier trigger at all, which is exactly why the #908 drift went unseen.
- *
- * A naive `\d+` would fire on every issue reference, version literal, date,
- * line number and percentage in a normal report — and a validator that fires on
- * every report gets switched off, which is strictly worse than no validator.
- * Precision is therefore bought three ways:
- *
- *   1. TRIGGER: a digit run that is not glued to identifier punctuation.
- *      Lookbehind rejects `#906`, `v3`, `PSA-006`, `W2`, `foo.mjs:123`;
- *      lookahead rejects `3.17`, `70%`, `2026-07-29`, `12615/0`.
- *   2. GAP: at most two intervening ADJECTIVE-like words, and never a
- *      preposition/article/copula. "5 dirty files" matches; "3 of 5 stars" and
- *      "2 sections below the rules" do not.
- *   3. SCOPE: evaluated only on prose lines with inline-code spans masked out —
- *      fenced blocks are skipped entirely (see `findViolations`), because a
- *      number inside a fence is tool OUTPUT (the evidence itself), not an
- *      unverified assertion about it.
- *
- * All quantifiers are bounded ({1,9}, {0,2}) — linear-time, ReDoS-safe.
- */
-const CARDINAL_TRIGGER = '(?<![\\w#$:/.-])\\d{1,9}(?![\\d.%:/-])';
-const CARDINAL_STOPWORDS =
-  'of|in|on|at|for|to|the|a|an|and|or|is|are|was|were|from|with|by|that|than|per|out|over|into|onto|via|but|as';
-const CARDINAL_GAP = `(?:\\s+(?!(?:${CARDINAL_STOPWORDS})\\b)[A-Za-z][\\w-]*){0,2}`;
-const CARDINAL_PATTERN = new RegExp(`${CARDINAL_TRIGGER}${CARDINAL_GAP}\\s+${CARDINAL_NOUN}\\b`, 'i');
-
-/**
- * Pattern 8 (#918) — the PSA-006 CANONICAL numerator/denominator slash form:
- * "12/14 files", "4/4 callers". PSA-006 literally demands "Quote the numerator
- * AND denominator", and `N/M` is the notation that demand produces — yet the
- * cardinal trigger's lookahead `(?![\d.%:/-])` excludes the slash, making the
- * rule's own canon form structurally invisible (#918).
- *
- * Admitting the slash re-opens the `12615/0/11` gate-summary class the
- * lookahead exists to suppress, so the slash form gets its OWN pattern with a
- * STRICTER contract than the bare cardinal:
- *
- *   1. RATIO: exactly two slash-joined numbers. Both boundary guards stay:
- *      the lookbehind rejects a numerator glued to a path/id (`hooks/12/14`),
- *      the lookahead after the DENOMINATOR rejects a third slash-segment —
- *      `12615/0/11` fails twice over (denominator `0` is followed by `/`, and
- *      the trailing pair `0/11` has a `/`-glued numerator).
- *   2. NOUN IMMEDIATELY AFTER — no CARDINAL_GAP. The noun-after-denominator is
- *      the discriminator that separates a measured ratio ("12/14 files") from
- *      a bare slash pair that is a date or score ("on 12/14 we shipped",
- *      "rated 3/5 overall"): those are followed by anything BUT an artefact
- *      noun. Widening to the gapped form would admit US-date + adjective +
- *      noun collisions with no PSA-006 payoff.
- *
- * FP re-measured on the CORRECT text sort (#918 requirement — the prior 1.07
- * rate was measured on coordinator narration, not on what this hook reads):
- * 490 real SubagentStop subagent transcripts (`~/.claude/projects/<slug>/<session>/
- * subagents/*.jsonl`), spawning THIS hook per transcript, 2026-07-31.
- * Baseline (pre-#918): 345 firings / 0.7041 per stop. With slash form +
- * `callers` admitted: 348 / 0.7102 — +3 firings, of which 1 is a true positive
- * ("0/49 Learnings mit Allow-List-Typ", an unverified canon-form claim), 1
- * quotes the #918 example sentence itself (mention-not-use), and 1 is a
- * before/after line-count pair ("858/857 lines", class-consistent with the
- * bare "412 lines" behaviour of pattern 7).
- *
- * Bounded quantifiers only ({1,9}) — linear-time, ReDoS-safe.
- */
-const CARDINAL_RATIO_PATTERN = new RegExp(
-  `(?<![\\w#$:/.-])\\d{1,9}/\\d{1,9}(?![\\d.%:/-])\\s+${CARDINAL_NOUN}\\b`,
-  'i'
-);
-
-/** Inline-code spans are masked before the cardinal pattern runs. */
-const INLINE_CODE_RE = /`[^`\n]*`/g;
-
-/**
- * Gate-summary / STATUS-report lines are the HARNESS's own completion output —
- * tool evidence, not an unverified assertion about the codebase — yet carried
- * no exemption of their own: they were caught only incidentally, by whichever
- * individual claim pattern happened not to fire on that exact phrasing. GitLab
- * #1198 (Discovery D8, 2026-09-02): a 400-event sample of
- * `discovery_validator_violation` records showed 186/400 (46.5%) firing on
- * this exact class — the single largest false-positive source measured to
- * date. Skipped at the LINE level, before ANY pattern runs, rather than by
- * narrowing `CARDINAL_NOUN`: narrowing the noun set would ALSO silence a true
- * "N files" claim appearing outside a gate-summary line, which is not this
- * bug's fix.
- *
- * Four alternatives cover the measured shapes: an N-passed/M-failed count
- * ("14904 passed / 0 failed"), a `STATUS:` report line (`skills/wave-executor`
- * agent-report convention), a "Full Gate" heading, and a `Gate: <verdict>`
- * summary line (English "typecheck" or German "grün"/"rot").
- */
-const GATE_SUMMARY_LINE_RE =
-  /\b\d+\s+passed\s*\/\s*\d+\s+failed\b|^\s*STATUS:\s*(?:done|partial|failed)\b|\bFull Gate\b|\bGate:\s*(?:typecheck|grün|rot)\b/i;
-
-/**
- * Commands that count as a MEASUREMENT inside a fenced block. `grep|rg|find`
- * (the #567 set) only covers text search; the #908 facts are measured with
- * `git log --oneline | wc -l`, `jq` over a JSONL metrics file, `ls | wc -l`,
- * or a `node`/`npm` script. Refusing to recognise those made the honest,
- * evidence-quoting path fail verification.
- */
-const MEASUREMENT_CMD_RE = /\b(grep|rg|find|git|wc|jq|ls|node|npm)\b/;
-
-/**
- * Markers that date a measurement (#908 Baustein 2 input). ADVISORY in v1:
- * an undated-but-verified claim is counted and reported, never a violation —
- * a hard contract without an established authoring habit buys friction, not
- * accuracy. Baustein 2 can escalate this to a violation once the habit exists.
- */
-const TIMESTAMP_MARKER_RE = /\b\d{4}-\d{2}-\d{2}\b|\bHEAD\b|\bas of\b|\bmeasured (?:at|on)\b|\brev-parse\b/i;
-
 // ---------------------------------------------------------------------------
 // stdin reading (inline — Stop-family hooks exit 0 always, never deny)
 // ---------------------------------------------------------------------------
@@ -324,8 +121,8 @@ function readStdinJson() {
  */
 async function isEnabled() {
   const candidates = [
-    path.join(SO_PROJECT_DIR, 'CLAUDE.md'),
-    path.join(SO_PROJECT_DIR, 'AGENTS.md'),
+    path.join(getProjectDir(), 'CLAUDE.md'),
+    path.join(getProjectDir(), 'AGENTS.md'),
   ];
   for (const file of candidates) {
     try {
@@ -338,194 +135,6 @@ async function isEnabled() {
   return false;
 }
 
-// ---------------------------------------------------------------------------
-// transcript reading
-// ---------------------------------------------------------------------------
-
-/**
- * Read the transcript JSONL at `transcriptPath`, take the last TAIL_RECORDS
- * `type:"assistant"` records, and concatenate their text content blocks.
- * Returns '' on any failure (missing file, /dev/null, malformed lines).
- *
- * @param {string} transcriptPath
- * @returns {Promise<string>}
- */
-async function readTranscriptTail(transcriptPath) {
-  if (typeof transcriptPath !== 'string' || !transcriptPath) return '';
-  let raw;
-  try {
-    raw = await fs.readFile(transcriptPath, 'utf8');
-  } catch {
-    return '';
-  }
-  if (!raw.trim()) return '';
-
-  const assistantRecords = [];
-  for (const line of raw.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    let rec;
-    try { rec = JSON.parse(trimmed); } catch { continue; }
-    if (rec && rec.type === 'assistant') assistantRecords.push(rec);
-  }
-
-  const tail = assistantRecords.slice(-TAIL_RECORDS);
-  const textBlocks = [];
-  for (const rec of tail) {
-    const content = rec?.message?.content;
-    if (!Array.isArray(content)) continue;
-    for (const block of content) {
-      if (block && block.type === 'text' && typeof block.text === 'string') {
-        textBlocks.push(block.text);
-      }
-    }
-  }
-  return textBlocks.join('\n');
-}
-
-// ---------------------------------------------------------------------------
-// claim scanning
-// ---------------------------------------------------------------------------
-
-/**
- * Single fence walk. Returns two disjoint-purpose index sets:
- *   - `measurementLines`: lines belonging to a fenced block whose body contains
- *     a MEASUREMENT_CMD_RE invocation (the evidence a claim can lean on).
- *   - `fencedLines`: lines belonging to ANY fenced block (evidence or not).
- *     Used only to keep the greedy #908 cardinal pattern out of tool output;
- *     the six quantifier patterns are unchanged and still scan fenced lines.
- *
- * An unterminated trailing fence is treated as fenced-to-EOF (conservative for
- * false-positive suppression) but never as a measurement block (its body was
- * never closed, so we cannot claim it verified anything).
- *
- * @param {string[]} lines
- * @returns {{ measurementLines: Set<number>, fencedLines: Set<number> }}
- */
-function scanFences(lines) {
-  const measurementLines = new Set();
-  const fencedLines = new Set();
-  let fenceStart = -1;
-  let buffer = [];
-  let inFence = false;
-
-  for (let i = 0; i < lines.length; i++) {
-    const isFence = /^\s*```/.test(lines[i]);
-    if (!inFence) {
-      if (isFence) { inFence = true; fenceStart = i; buffer = []; }
-      continue;
-    }
-    // inside a fence
-    if (isFence) {
-      // closing fence — evaluate the buffered body
-      const body = buffer.join('\n');
-      const isMeasurement = MEASUREMENT_CMD_RE.test(body);
-      for (let j = fenceStart; j <= i; j++) {
-        fencedLines.add(j);
-        if (isMeasurement) measurementLines.add(j);
-      }
-      inFence = false;
-      fenceStart = -1;
-      buffer = [];
-    } else {
-      buffer.push(lines[i]);
-    }
-  }
-
-  // Unterminated trailing fence — suppress cardinal matches, grant no evidence.
-  if (inFence) {
-    for (let j = fenceStart; j < lines.length; j++) fencedLines.add(j);
-  }
-
-  // INLINE-code evidence: PSA-006 asks for "the exact pattern executed" to be
-  // quoted — an inline `git log --oneline | wc -l` satisfies that exactly as
-  // well as a fenced block, and one-line findings are commonly written that
-  // way. Refusing to count it would penalise the honest path.
-  for (let i = 0; i < lines.length; i++) {
-    if (fencedLines.has(i)) continue;
-    for (const span of lines[i].match(INLINE_CODE_RE) ?? []) {
-      if (MEASUREMENT_CMD_RE.test(span)) { measurementLines.add(i); break; }
-    }
-  }
-
-  return { measurementLines, fencedLines };
-}
-
-/**
- * True when any line in `indices` sits within ±GREP_PROXIMITY_LINES of `i`.
- *
- * @param {Set<number>} indices
- * @param {number} i
- * @returns {boolean}
- */
-function nearIndex(indices, i) {
-  for (let j = i - GREP_PROXIMITY_LINES; j <= i + GREP_PROXIMITY_LINES; j++) {
-    if (indices.has(j)) return true;
-  }
-  return false;
-}
-
-/**
- * True when a measurement TIMESTAMP marker appears within the same proximity
- * window used for the measurement block itself.
- *
- * @param {string[]} lines
- * @param {number} i
- * @returns {boolean}
- */
-function hasMeasurementTimestamp(lines, i) {
-  const from = Math.max(0, i - GREP_PROXIMITY_LINES);
-  const to = Math.min(lines.length - 1, i + GREP_PROXIMITY_LINES);
-  for (let j = from; j <= to; j++) {
-    if (TIMESTAMP_MARKER_RE.test(lines[j])) return true;
-  }
-  return false;
-}
-
-/**
- * Scan concatenated transcript text for claims lacking an adjacent measurement
- * block (within ±GREP_PROXIMITY_LINES).
- *
- * @param {string} text
- * @returns {{ violations: string[], undatedVerified: number }}
- *   `violations` — truncated claim-text snippets; `undatedVerified` — count of
- *   claims that ARE verified but carry no measurement timestamp (advisory).
- */
-function findViolations(text) {
-  if (!text) return { violations: [], undatedVerified: 0 };
-  const lines = text.split(/\r?\n/);
-  const { measurementLines, fencedLines } = scanFences(lines);
-  const violations = [];
-  let undatedVerified = 0;
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    // #1198 FIX 2: gate-summary/STATUS lines are tool OUTPUT, not a claim —
-    // skipped before any pattern runs (see GATE_SUMMARY_LINE_RE header).
-    if (GATE_SUMMARY_LINE_RE.test(line)) continue;
-
-    // #1198 FIX 3 (masking-order bug): mask inline-code spans ONCE, then test
-    // BOTH the six CLAIM_PATTERNS and the cardinal/ratio patterns against the
-    // masked text. Previously only the cardinal branch masked — a claim
-    // quoted entirely inside backticks (evidence/example text, not an
-    // assertion) still tripped CLAIM_PATTERNS via the raw, unmasked line.
-    const masked = line.replace(INLINE_CODE_RE, ' ');
-    let matched = CLAIM_PATTERNS.some((re) => re.test(masked));
-    if (!matched && !fencedLines.has(i)) {
-      matched = CARDINAL_PATTERN.test(masked) || CARDINAL_RATIO_PATTERN.test(masked);
-    }
-    if (!matched) continue;
-
-    if (nearIndex(measurementLines, i)) {
-      if (!hasMeasurementTimestamp(lines, i)) undatedVerified++;
-      continue;
-    }
-
-    violations.push(line.trim().slice(0, CLAIM_TEXT_MAX));
-  }
-  return { violations, undatedVerified };
-}
-
 // ---------------------------------------------------------------------------
 // payload helpers
 // ---------------------------------------------------------------------------
@@ -578,27 +187,92 @@ function resolveAgentTranscriptPath(input, agentId) {
 const AGENT_TYPE_META_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
 
 /**
- * Read the agent TYPE from the sidecar `agent-<id>.meta.json` the harness writes
- * next to the subagent transcript. Used only when the stdin payload omits
- * `agent_type` — the reason `agent` read `"unknown"` on ~91% of events.
+ * The sidecar `description` is free operator prose ("W1-d5 Scripts-Audit"), so
+ * it is clamped by LENGTH and stripped of control characters rather than
+ * charset-validated. 120 chars is the widest description measured on-disk
+ * (2026-09-06, 20 real `agent-*.meta.json` files under
+ * `~/.claude/projects/<slug>/<session>/subagents/`: max 34 chars).
+ *
+ * Exposure note: unlike `orchestrator.agent.stopped` — which deliberately
+ * omits `description` because that record travels the optional Clank webhook
+ * unredacted (see hooks/on-stop.mjs) — this record is appended straight to
+ * `.orchestrator/metrics/events.jsonl` via `appendJsonl`, never through
+ * `emitEvent`, and it ALREADY carries up to 200 characters of the agent's own
+ * prose in `claim_text`. Carrying the description adds no new exposure class.
+ */
+const AGENT_DESCRIPTION_MAX = 120;
+
+/**
+ * Resolve WHO made the claim, and say where the answer came from (#1218).
+ *
+ * Measured 2026-09-06 over the fleet's worst-affected repo
+ * (`extern/aiat-barrierefrei-engine`, 3,360 `discovery_validator_violation`
+ * records): `agent` was the literal string `"unknown"` on 3,026 of them
+ * (90.1%), and NOT ONE record carried an `agent_id`. Both the sidecar-meta
+ * fallback and the `agent_id` field landed in the same commit (936dae8a,
+ * 2026-09-02); the newest of those 3,360 records is 2026-08-25. The 90.1% is
+ * therefore a property of a PRE-FIX corpus, not of the code at HEAD — d3's
+ * open question 3 ("pre- or post-#1191?") resolves to *pre*.
+ *
+ * What the corpus does NOT excuse is the SHAPE of the answer. Two gaps remain
+ * at HEAD and this function closes them:
+ *
+ *   1. `"unknown"` was indistinguishable from a real agent type named
+ *      "unknown", and carried no hint of WHY resolution failed. The record now
+ *      always carries `agent_source` — `payload` | `meta` | `none` — and, on
+ *      `none`, the sorted list of stdin keys that WERE present, so the next
+ *      reader diagnoses the harness gap from the ledger instead of guessing.
+ *   2. `agentType` is frequently the useless class `general-purpose`: measured
+ *      on the same day over 20 real sidecars in THIS repo's own session
+ *      directory, 14 read `general-purpose` and only 6 a plugin-qualified type.
+ *      The sidecar's `description` ("W1-d5 Scripts-Audit") is what actually
+ *      identifies the agent, so it is carried alongside as
+ *      `agent_description`.
  *
+ * @param {object} input — SubagentStop stdin payload
  * @param {string} metaPath — `resolveSubagentSidecar(...).meta`
- * @returns {Promise<string|null>}
+ * @returns {Promise<{agent: string, source: 'payload'|'meta'|'none', description: string|null, payloadKeys: string[]}>}
  */
-async function readAgentTypeFromMeta(metaPath) {
+async function resolveAgentAttribution(input, metaPath) {
+  const fromPayload = firstNonEmptyString(input, ['agent_type', 'subagent_type'], null);
+  // Clamped with the same shape hooks/on-stop.mjs applies to `agentType`
+  // (colon included — `session-orchestrator:code-implementer` is the real
+  // shape). This value reaches BOTH the ledger event and the model-visible
+  // `additionalContext` string, so a mismatch is OMITTED rather than
+  // truncated: an unmeasured type stays visibly unmeasured.
+  const payloadAgent =
+    fromPayload !== null && AGENT_TYPE_META_RE.test(fromPayload.trim()) ? fromPayload.trim() : null;
+
+  let metaAgent = null;
+  let description = null;
   try {
     const meta = JSON.parse(await fs.readFile(metaPath, 'utf8'));
     const t = meta?.agentType;
-    if (typeof t !== 'string' || !t.trim()) return null;
-    // Clamped with the same shape hooks/on-stop.mjs applies to `agentType`
-    // (colon included — `session-orchestrator:code-implementer` is the real
-    // shape). This value reaches BOTH the ledger event and the model-visible
-    // `additionalContext` string, so a mismatch is OMITTED rather than
-    // truncated: the caller then falls back to the honest `'unknown'`.
-    return AGENT_TYPE_META_RE.test(t.trim()) ? t.trim() : null;
+    if (typeof t === 'string' && AGENT_TYPE_META_RE.test(t.trim())) metaAgent = t.trim();
+    const d = meta?.description;
+    if (typeof d === 'string' && d.trim()) {
+      // Control characters (a stray NUL above all: one NUL makes a text
+      // file invisible to every grep-based audit) are replaced, never
+      // carried. Filtered by code point rather than by a control-char
+      // regex so this file itself stays greppable.
+      const clean = [...d]
+        .map((ch) => { const c = ch.codePointAt(0); return c < 0x20 || c === 0x7f ? ' ' : ch; })
+        .join('')
+        .replace(/\s+/g, ' ')
+        .trim();
+      if (clean) description = clean.slice(0, AGENT_DESCRIPTION_MAX);
+    }
   } catch {
-    return null;
+    // absent or corrupt sidecar meta — the payload branch still stands
   }
+
+  const agent = payloadAgent ?? metaAgent ?? 'unknown';
+  const source = payloadAgent !== null ? 'payload' : metaAgent !== null ? 'meta' : 'none';
+  // Keys only, never values: the diagnostic question is "what DID the harness
+  // send?", and a value could carry a path or prose that has no business in a
+  // record whose whole point is attribution.
+  const payloadKeys = input && typeof input === 'object' ? Object.keys(input).sort() : [];
+  return { agent, source, description, payloadKeys };
 }
 
 /**
@@ -657,6 +331,50 @@ function dedupSentinelPath({ projectRoot, sessionId, agentId, claimText }) {
   );
 }
 
+/**
+ * Build the SESSION-scoped LEDGER sentinel for one normalized claim (#1198).
+ *
+ * Distinct from `dedupSentinelPath` above in BOTH key and effect, and the
+ * difference is the point:
+ *   - `dedupSentinelPath` is keyed on the individual AGENT and suppresses only
+ *     the `additionalContext` echo, so each real agent still receives its own
+ *     copy of the feedback.
+ *   - this one is keyed on the SESSION and the NORMALIZED claim, and suppresses
+ *     the events.jsonl WRITE. The ledger is a record of distinct findings; the
+ *     same sentence re-asserted by a second agent of the same session is the
+ *     same finding, and writing it twice is what produced a duplication factor
+ *     of 16.4 (3,360 records over 205 distinct `claim_text` values, measured
+ *     2026-09-06 in `extern/aiat-barrierefrei-engine`).
+ *
+ * Returns null without a session id — a claim that cannot be bound to a session
+ * must not collide with an unrelated one under a global "unknown" key, so it is
+ * always written (the pre-#1198 behaviour, preserved for that case only).
+ *
+ * NAMED CEILING (BV-004): one zero-byte tmp file per distinct claim per
+ * session, never cleaned up by this hook — the same shape (and the same
+ * unbounded growth) `dedupSentinelPath` above has carried since #567, relying
+ * on the OS's tmpdir reaping. Fine at the measured rate: 158 distinct claims
+ * across a repo's worst 90 days. REVISIT TRIGGER: a repo whose distinct-claim
+ * count per session reaches the hundreds — then this belongs in a single
+ * per-session state file rather than one inode per claim.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot
+ * @param {string|null} opts.sessionId
+ * @param {string} opts.normalizedClaim — `normalizeClaim()` output
+ * @returns {string|null}
+ */
+function claimLedgerSentinelPath({ projectRoot, sessionId, normalizedClaim }) {
+  if (typeof sessionId !== 'string' || !sessionId.trim()) return null;
+  if (typeof normalizedClaim !== 'string' || !normalizedClaim) return null;
+
+  const claimHash = createHash('sha256').update(normalizedClaim).digest('hex').slice(0, 16);
+  return path.join(
+    tmpdir(),
+    `psa006-claim-${projectRootHash(projectRoot)}-${safeSentinelComponent(sessionId)}-${claimHash}.lock`
+  );
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
@@ -678,10 +396,8 @@ async function main() {
   const { violations, undatedVerified } = findViolations(text);
   if (violations.length === 0) return;
 
-  const agentForDedup =
-    firstNonEmptyString(input, ['agent_type', 'subagent_type'], null) ??
-    (await readAgentTypeFromMeta(sidecar.meta));
-  const agent = agentForDedup ?? 'unknown';
+  const attribution = await resolveAgentAttribution(input, sidecar.meta);
+  const agent = attribution.agent;
   // session_id precedence: parent_session_id first, mirroring the sibling hook
   // hooks/subagent-telemetry.mjs (firstNonEmptyString(['parent_session_id',
   // 'session_id'])). W2-review LOW finding (#567) — the prior `session_id ||
@@ -694,23 +410,55 @@ async function main() {
   // globally. Keyed on agentId (not agent TYPE, #1198 FIX 1) plus the first
   // violation's claim text so distinct real agents and distinct claims never
   // share a sentinel.
+  const projectRoot = getProjectDir();
   const sentinel = dedupSentinelPath({
-    projectRoot: SO_PROJECT_DIR,
+    projectRoot,
     sessionId,
     agentId,
-    claimText: violations[0],
+    claimText: violations[0].claim,
   });
 
+  // Ledger write, ONE record per distinct normalized claim (#1198). Two
+  // levels, because the duplication had two sources: `findViolations()` already
+  // collapsed the repeats INSIDE this transcript tail into an `occurrences`
+  // count, and the session sentinel below drops a claim this session has
+  // already recorded from an earlier SubagentStop.
   const filePath = eventsFilePath();
-  for (const claim of violations) {
+  let written = 0;
+  for (const violation of violations) {
+    const claimSentinel = claimLedgerSentinelPath({
+      projectRoot,
+      sessionId,
+      normalizedClaim: violation.normalized,
+    });
+    if (claimSentinel !== null) {
+      let seen = false;
+      try {
+        await fs.writeFile(claimSentinel, '', { flag: 'wx' });
+      } catch (err) {
+        // EEXIST = this session already recorded this claim. Any OTHER
+        // filesystem error must NOT suppress the record: losing a finding to a
+        // full disk or a read-only tmpdir is the worse failure.
+        seen = err && err.code === 'EEXIST';
+      }
+      if (seen) continue;
+    }
     await appendJsonl(filePath, {
       event: 'discovery_validator_violation',
       timestamp: new Date().toISOString(),
       agent,
+      // Always present, even (especially) on 'none': a bare "unknown" is
+      // indistinguishable from a real agent type of that name, and says
+      // nothing about WHY resolution failed.
+      agent_source: attribution.source,
+      ...(attribution.description !== null ? { agent_description: attribution.description } : {}),
+      ...(attribution.source === 'none' ? { payload_keys: attribution.payloadKeys } : {}),
       ...(agentId !== null ? { agent_id: agentId } : {}),
       ...(sessionId !== null ? { session_id: sessionId } : {}),
-      claim_text: claim,
+      claim_text: violation.claim,
+      occurrences: violation.occurrences,
     });
+    written++;
   }
 
   // Advisory only (#908 item 4) — never promoted to a violation in v1.
@@ -718,10 +466,18 @@ async function main() {
     ? ` ${undatedVerified} verified claim(s) carry no measurement timestamp (advisory).`
     : '';
 
+  // `written < violations.length` means this session had already recorded the
+  // difference from an earlier SubagentStop — say so rather than let the WARN
+  // count and the ledger count disagree with no explanation (#1198).
+  const suppressedNote = written < violations.length
+    ? ` ${violations.length - written} already recorded earlier in this session.`
+    : '';
+
   const warnText =
-    `⚠ PSA-006: ${violations.length} repo-state/distributional claim(s) from agent "${agent}" ` +
-    `lack an adjacent measurement transcript (grep/rg/find/git/wc/jq/ls/node/npm) (non-blocking).` +
-    `${undatedNote} ` +
+    `⚠ PSA-006: ${violations.length} distinct repo-state/distributional claim(s) from agent ` +
+    `"${agent}" (source: ${attribution.source}) lack an adjacent measurement transcript ` +
+    `(grep/rg/find/git/wc/jq/ls/node/npm) (non-blocking).` +
+    `${suppressedNote}${undatedNote} ` +
     `See .claude/rules/parallel-sessions.md § PSA-006.`;
   process.stderr.write(warnText + '\n');