@dzhechkov/harness-core 0.4.5 → 0.5.1

package/src/recall-usage.ts

@@ -13,13 +13,26 @@
  * @packageDocumentation
  */
 
+// STATIC node: imports, deliberately (2026-08-19). A deferred `require('node:fs')` here compiled
+// into an ESM dist, where `require` is NOT in scope: every call from the emitted `.cjs` hook threw
+// ReferenceError into `appendRecallUsage`'s own catch and returned **0 rows appended, silently**.
+// The Codex recall leg looked wired and correctly-silent for exactly the reason AM-4's forced-hit
+// canary exists to expose. Importing node: modules at the top costs nothing — they are built in.
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
 import {
+  EMPTY_LOG_TAIL,
   EVENT_CHAIN_FIELD_OVERHEAD_BYTES,
   EVENT_CHAIN_LEDGER_KIND,
+  EVENT_CHAIN_TAIL_BYTES,
+  appendChainedLines,
   chainRewrite,
   defaultEventWeight,
+  readTailInfo,
   verifyEventChainText,
   type EventChainDefect,
+  type LogTail,
 } from './event-chain.js';
 
 export const RECALL_USAGE_LOG_RELATIVE = '.dz/recall-usage.jsonl';
@@ -45,6 +58,35 @@ export interface RecallUsageReadRecord {
   readonly eventId?: string;
   /** True when the stored query is a PREFIX of the real prompt — not replayable. */
   readonly queryTruncated?: boolean;
+  /**
+   * WHICH HOST injected the lesson (ADR-003 §1, H-B additive). Absent ⇒ `claude-code`, so every row
+   * written before the Codex leg keeps its meaning without a migration.
+   */
+  readonly runtime?: Runtime;
+}
+
+/** The hosts that run the apply leg. Additive by design: an old reader ignores the field. */
+export type Runtime = 'claude-code' | 'codex';
+
+export const RUNTIMES: readonly Runtime[] = ['claude-code', 'codex'];
+
+/** A row without `runtime` predates the Codex leg and is Claude Code's by construction. */
+export function runtimeOf(record: RecallUsageReadRecord): Runtime {
+  return record.runtime ?? 'claude-code';
+}
+
+function normalizeRuntime(value: unknown): Runtime | undefined {
+  return value === 'claude-code' || value === 'codex' ? value : undefined;
+}
+
+function normalizeRuntimes(value: unknown): readonly Runtime[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const set = new Set<Runtime>();
+  for (const v of value) {
+    const r = normalizeRuntime(v);
+    if (r !== undefined) set.add(r);
+  }
+  return set.size === 0 ? undefined : [...set].sort();
 }
 
 /** Query text is capped so a pasted wall of text cannot bloat the log. */
@@ -59,6 +101,21 @@ export interface RecallUsageAggregateRecord {
   readonly maxScore: number;
   readonly totalScore: number;
   readonly compactedAt: string;
+  /**
+   * The SET UNION of the runtimes whose reads were folded into this record (sorted, deduped).
+   *
+   * AM-27, and the whole reason it exists: `compactVerifiedRecallUsageLog` keeps verbatim only the
+   * newest {@link RECALL_USAGE_REPLAY_KEEP} read rows that carry a `query`. Everything else — a
+   * *fresh* row without `query` included — is folded into this record, whose merge key is `dzId`
+   * alone. The allowlist on the READ record therefore never touches the path where provenance is
+   * actually lost. The union does.
+   *
+   * Residual accepted loss, registered in `architecture/degradations.md`: this says WHICH runtimes
+   * used a lesson, not HOW OFTEN each did. Widening the merge key to `(dzId, runtime)` would split
+   * the stats rows `buildRecallUsageReport` looks up by `dzId` alone — a cross-feature blast radius
+   * this leg has no mandate for.
+   */
+  readonly runtimes?: readonly Runtime[];
 }
 
 export type RecallUsageRecord = RecallUsageReadRecord | RecallUsageAggregateRecord;
@@ -76,6 +133,8 @@ export interface RecallUsageStat {
   readonly lastReadAt: string;
   readonly maxScore: number;
   readonly avgScore: number;
+  /** Set union of contributing runtimes (AM-27). Empty ⇒ nothing carried provenance. */
+  readonly runtimes: readonly Runtime[];
 }
 
 export interface RecallPatternUsageRef {
@@ -115,6 +174,7 @@ interface Acc {
   lastMs: number;
   maxScore: number;
   totalScore: number;
+  runtimes: Set<Runtime>;
 }
 
 export interface RecallUsageRecordInput {
@@ -125,6 +185,7 @@ export interface RecallUsageRecordInput {
   readonly runId?: unknown;
   readonly eventId?: unknown;
   readonly queryTruncated?: unknown;
+  readonly runtime?: unknown;
 }
 
 /**
@@ -182,6 +243,7 @@ export function aggregateRecallUsage(records: readonly RecallUsageRecord[]): rea
       lastReadAt: a.lastReadAt,
       maxScore: a.maxScore,
       avgScore: a.totalScore / a.reads,
+      runtimes: [...a.runtimes].sort(),
     }))
     .sort(compareStats);
 }
@@ -397,6 +459,10 @@ function normalizeReadRecord(value: unknown): RecallUsageReadRecord | undefined
     ...(typeof runId === 'string' && runId.trim() !== '' ? { runId: runId.trim() } : {}),
     ...(typeof value['eventId'] === 'string' && (value['eventId'] as string).trim() !== '' ? { eventId: (value['eventId'] as string).trim() } : {}),
     ...(value['queryTruncated'] === true ? { queryTruncated: true } : {}),
+    // ALLOWLIST (AM-20): the normaliser is an allowlist and `compactVerifiedRecallUsageLog`
+    // re-serialises every retained row through it — a non-allowlisted field dies at the first
+    // compaction. Necessary, but NOT sufficient: see `runtimes` on the aggregate (AM-27).
+    ...(normalizeRuntime(value['runtime']) !== undefined ? { runtime: normalizeRuntime(value['runtime'])! } : {}),
   };
 }
 
@@ -413,7 +479,18 @@ function normalizeAggregateRecord(value: Record<string, unknown>): RecallUsageAg
   if (!validTs(firstReadAt) || !validTs(lastReadAt) || !validTs(compactedAt)) return undefined;
   if (typeof maxScore !== 'number' || !Number.isFinite(maxScore)) return undefined;
   if (typeof totalScore !== 'number' || !Number.isFinite(totalScore)) return undefined;
-  return { kind: 'aggregate', dzId: dzId.trim(), reads, firstReadAt, lastReadAt, maxScore, totalScore, compactedAt };
+  const runtimes = normalizeRuntimes(value['runtimes']);
+  return {
+    kind: 'aggregate',
+    dzId: dzId.trim(),
+    reads,
+    firstReadAt,
+    lastReadAt,
+    maxScore,
+    totalScore,
+    compactedAt,
+    ...(runtimes !== undefined ? { runtimes } : {}),
+  };
 }
 
 function mergeRead(byId: Map<string, Acc>, rec: RecallUsageReadRecord): void {
@@ -429,9 +506,11 @@ function mergeRead(byId: Map<string, Acc>, rec: RecallUsageReadRecord): void {
       lastMs: ms,
       maxScore: rec.score,
       totalScore: rec.score,
+      runtimes: new Set<Runtime>([runtimeOf(rec)]),
     });
     return;
   }
+  prev.runtimes.add(runtimeOf(rec));
   prev.reads += 1;
   prev.totalScore += rec.score;
   prev.maxScore = Math.max(prev.maxScore, rec.score);
@@ -459,9 +538,11 @@ function mergeAggregate(byId: Map<string, Acc>, rec: RecallUsageAggregateRecord)
       lastMs,
       maxScore: rec.maxScore,
       totalScore: rec.totalScore,
+      runtimes: new Set<Runtime>(rec.runtimes ?? []),
     });
     return;
   }
+  for (const r of rec.runtimes ?? []) prev.runtimes.add(r);
   prev.reads += rec.reads;
   prev.totalScore += rec.totalScore;
   prev.maxScore = Math.max(prev.maxScore, rec.maxScore);
@@ -485,6 +566,9 @@ function aggregateRecord(stat: RecallUsageStat, compactedAt: string): RecallUsag
     maxScore: stat.maxScore,
     totalScore: stat.avgScore * stat.reads,
     compactedAt,
+    // AM-27's mutant: dropping this union silently destroys per-runtime provenance at the first
+    // compaction, and the READ-record allowlist cannot save it because this path never sees one.
+    ...(stat.runtimes.length > 0 ? { runtimes: [...stat.runtimes].sort() } : {}),
   };
 }
 
@@ -535,3 +619,102 @@ function joinLines(lines: readonly string[]): string {
 function byteLength(text: string): number {
   return text.length;
 }
+
+/* ========================================================================== */
+/* The SHARED writer (`crossrt-2-codex-hooks`, ADR-003 · AM-6/AM-7)           */
+/* ========================================================================== */
+/*
+ * Everything above this line is pure. What follows is the ONE writer both hosts call, and it is
+ * here rather than in a helper because the alternative — a second inline appender per runtime — is
+ * exactly the drift AM-7 forbids: the Claude helper had the only implementation for 19 days and the
+ * Codex leg could not exist without either importing it or copying it.
+ *
+ * It NEVER throws. A hook that dies on a logging failure costs the user their turn, and the log is
+ * telemetry: losing a row is a smaller harm than losing a prompt.
+ */
+
+export interface AppendRecallUsageHit {
+  readonly dzId: unknown;
+  readonly score: unknown;
+}
+
+export interface AppendRecallUsageInput {
+  /** Project ROOT (the helper walks up to it; a cwd-relative writer splits the log — AM-5). */
+  readonly projectRoot: string;
+  readonly hits: readonly AppendRecallUsageHit[];
+  /** The host that injected. Omitted ⇒ `claude-code`, matching every pre-Codex row. */
+  readonly runtime?: Runtime;
+  readonly query?: string | undefined;
+  readonly runId?: string | undefined;
+  /** One id per PROMPT. Generated when absent so a multi-hit prompt still counts as one event. */
+  readonly eventId?: string | undefined;
+  readonly now?: string;
+  /** Test seam. Production leaves it unset and the path is derived from `projectRoot`. */
+  readonly logPath?: string;
+}
+
+/**
+ * Append one prompt's injected hits as CHAINED rows.
+ *
+ * @returns the number of rows appended; **0** on any failure (unwritable directory, unreadable
+ *          tail, empty input). Never throws.
+ */
+export function appendRecallUsage(input: AppendRecallUsageInput): number {
+  try {
+    const hits = Array.isArray(input?.hits) ? input.hits : [];
+    if (hits.length === 0) return 0;
+    const ts = validTs(input.now) ? input.now : new Date().toISOString();
+    const eventId =
+      typeof input.eventId === 'string' && input.eventId.trim() !== ''
+        ? input.eventId.trim()
+        : `${ts}:${Math.random().toString(36).slice(2, 10)}`;
+    const full = typeof input.query === 'string' ? input.query.trim() : '';
+    const query = full !== '' ? full.slice(0, RECALL_USAGE_QUERY_MAX_CHARS) : undefined;
+    const queryTruncated = full.length > RECALL_USAGE_QUERY_MAX_CHARS ? true : undefined;
+
+    const records: RecallUsageReadRecord[] = [];
+    for (const hit of hits) {
+      const rec = normalizeReadRecord({
+        dzId: hit?.dzId,
+        score: hit?.score,
+        ts,
+        query,
+        runId: input.runId,
+        eventId,
+        queryTruncated,
+        runtime: input.runtime ?? 'claude-code',
+      });
+      if (rec !== undefined) records.push(rec);
+    }
+    if (records.length === 0) return 0;
+
+    const logPath = input.logPath ?? join(input.projectRoot, ...RECALL_USAGE_LOG_RELATIVE.split('/'));
+    const payload = appendChainedLines(records, readLogTailSync(logPath));
+    if (payload === '') return 0;
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, payload, 'utf-8');
+    return records.length;
+  } catch {
+    return 0; // never-block outranks telemetry completeness
+  }
+}
+
+/** Read the chain tail. An UNREADABLE tail is a torn tail, never an empty one (event-chain AM-6). */
+function readLogTailSync(file: string): LogTail {
+  try {
+    if (!existsSync(file)) return EMPTY_LOG_TAIL;
+    const fd = openSync(file, 'r');
+    try {
+      const size = fstatSync(fd).size;
+      if (!Number.isFinite(size) || size <= 0) return EMPTY_LOG_TAIL;
+      const want = Math.min(size, EVENT_CHAIN_TAIL_BYTES);
+      const buf = Buffer.alloc(want);
+      readSync(fd, buf, 0, want, size - want);
+      return readTailInfo(buf.toString('utf-8'), { partial: want < size });
+    } finally {
+      try { closeSync(fd); } catch { /* nothing to do */ }
+    }
+  } catch {
+    return EMPTY_LOG_TAIL;
+  }
+}

package/src/score.ts

@@ -64,15 +64,28 @@ function evidenceLine(text: string, re: RegExp): string | null {
  * heuristic table). A line whose match is preceded by a negation word is skipped. Heuristic — but
  * the failure mode flips from a silent false pass to a visible miss the shown evidence exposes.
  */
+// The DEFAULT vocabulary — verbs and determiners that deny the sentence they sit in.
 const NEGATION_RE = /\b(no|not|never|without|wasn'?t|isn'?t)\b/i;
-function evidenceLinePositive(text: string, re: RegExp): string | null {
+
+/**
+ * The default vocabulary plus the negative QUANTIFIERS. Opt-in per site, because a quantifier
+ * negates a NOUN, not the claim: "None of the mutants survived; discrimination §42 is proven by the
+ * red run" is idiomatic POSITIVE evidence that the wide list silently discarded (QE B-F2 —
+ * negating-the-mutants is not negating-the-proof). It is passed only where a red test demanded it:
+ * "Nothing was MEASURED in this round" scored as proof of measurement, because the word boundary in
+ * `\bno\b` does NOT match "Nothing". Hedges like "skipped" stay out of both lists — they routinely
+ * appear inside genuine evidence lines.
+ */
+const NEGATION_QUANTIFIED_RE = /\b(no|not|never|without|nothing|none|neither|nor|nobody|wasn'?t|isn'?t)\b/i;
+
+function evidenceLinePositive(text: string, re: RegExp, negationRe: RegExp = NEGATION_RE): string | null {
   for (const line of text.split('\n')) {
     if (!re.test(line)) continue;
     // Whole-line negation: "Codex was NOT used" carries its negation AFTER the match, so a
     // before-the-match check missed it. The trade is deliberate: a genuine line that happens to
     // contain a negation is SKIPPED (a visible miss the evidence exposes) rather than a negated
     // line being ACCEPTED (a silent false pass).
-    if (NEGATION_RE.test(line)) continue;
+    if (negationRe.test(line)) continue;
     return line.trim().slice(0, 140);
   }
   return null;
@@ -104,16 +117,25 @@ export function scoreRun(slug: string, artifacts: RunArtifacts): RunScorecard {
   if (adrText === '') {
     add('adr-confirmation', 'ADR present, property → named test', 'absent', 'no 03_adr/*.md artifact');
   } else {
-    const conf = evidenceLine(adrText, /^##+\s*Confirmation/i);
+    // POSITIVE (QE B-F2 reversed my first call, which exempted this site as "structural"). The
+    // heading regex allows a SUFFIX, so `## Confirmation — not yet performed` — the realistic
+    // placeholder an unfinished ADR carries — scored a full PASS. Heading presence is structural;
+    // heading TEXT is not, and this one can deny itself. Default (narrow) vocabulary: a heading is
+    // a fragment, and the quantifiers only appear in prose. Pinned both ways by tests.
+    const conf = evidenceLinePositive(adrText, /^##+\s*Confirmation/i);
     add(
       'adr-confirmation',
       'ADR present, property → named test',
       conf !== null ? 'pass' : 'partial',
-      conf ?? 'ADR exists but has no Confirmation section — the load-bearing property names no test',
+      conf ?? 'ADR exists but has no (non-negated) Confirmation heading — the load-bearing property names no test',
     );
   }
 
   // 2. Discrimination — proof the test can FAIL (the §42 gate, or an explicit mutation proof).
+  //    Default (narrow) vocabulary ON PURPOSE (QE B-F2): mutation evidence is written by negating the
+  //    MUTANTS — "None of the mutants survived", "neither mutant escaped" — which is the proof, not
+  //    its denial. The quantifiers would discard exactly the strongest lines this discipline exists
+  //    to find. "No discrimination proof was performed" is still caught by the narrow list.
   const discr =
     evidenceLinePositive(allText, /discrimination|§42/i) ??
     evidenceLinePositive(allText, /mutation[s]?\s.*(prov|kill)|mutant[s]?\s.*(kill|red)|RED on the old|goes? RED|failed as expected/i);
@@ -130,6 +152,13 @@ export function scoreRun(slug: string, artifacts: RunArtifacts): RunScorecard {
     add('cross-model-qe', 'independent cross-model review with a grade', 'absent', 'no 08_qe_report.md artifact');
   } else {
     const crossLine = evidenceLinePositive(qeText, /codex|gpt-|cross-model/i);
+    // EXEMPT from the negation filter (wave1-scorer-negation, per-site review): this line is a
+    // DISPLAY LOCATOR, not a verdict input — the verdict above rests on `crossLine` (already
+    // positive-filtered) AND on `grade`, parsed from the whole report. A letter grade is a
+    // structural token ("Grade: D"); there is no idiomatic "no Grade: D". Filtering here would only
+    // drop the most common real grade line ("**Grade: B** — no blockers remain") from the shown
+    // evidence for zero change in verdict. Pinned by a test. Residual, flagged not hidden:
+    // `extractQeGrade` itself is negation-blind and stays so — out of FR-B1's scope.
     const gradeLine = grade !== null ? evidenceLine(qeText, GRADE_RE) : null;
     add(
       'cross-model-qe',
@@ -145,8 +174,11 @@ export function scoreRun(slug: string, artifacts: RunArtifacts): RunScorecard {
 
   // 4. Live verification — the property was observed, not inferred. The health-advisor 1.2.0 QE
   //    report is the cautionary case: "✅ (mechanism)" with no live evidence shipped a dead feature.
-  const live = evidenceLine(qeText, /MEASURED|verified live|VERIFIED LIVE|reproducer/i);
-  const liveAnywhere = live ?? evidenceLine(allText, /MEASURED|verified live|VERIFIED LIVE|reproducer/i);
+  //    POSITIVE (wave1-scorer-negation): "nothing was MEASURED" / "no reproducer was run" is the
+  //    claim's exact opposite and used to score as proof of it (the crossrt-1 6/7 shape).
+  const live = evidenceLinePositive(qeText, /MEASURED|verified live|VERIFIED LIVE|reproducer/i, NEGATION_QUANTIFIED_RE);
+  const liveAnywhere =
+    live ?? evidenceLinePositive(allText, /MEASURED|verified live|VERIFIED LIVE|reproducer/i, NEGATION_QUANTIFIED_RE);
   add(
     'live-verification',
     'claims verified by running, not by reasoning',
@@ -155,7 +187,10 @@ export function scoreRun(slug: string, artifacts: RunArtifacts): RunScorecard {
   );
 
   // 5. README-first — the docs travelled in the same change.
-  const readme = evidenceLine(qeText + '\n' + manifestText, /README/);
+  //    POSITIVE (wave1-scorer-negation): THE acid-A5 defect. crossrt-1-agents-md scored ✓ here over
+  //    its own finding "README-first not satisfied — no README was touched": a negation rendered as
+  //    a checkmark. A README mention is not a README update.
+  const readme = evidenceLinePositive(qeText + '\n' + manifestText, /README/, NEGATION_QUANTIFIED_RE);
   add(
     'readme-first',
     'READMEs updated in the same change',
@@ -164,8 +199,14 @@ export function scoreRun(slug: string, artifacts: RunArtifacts): RunScorecard {
   );
 
   // 6. The learning loop — Step-0 recall folded in, Step-8 lessons taught.
-  const recalled = evidenceLine(complexityText + '\n' + allText, /LEARNED_PATTERNS|dz recall|recalled/i);
-  const taught = evidenceLine(allText, /lesson[s]? taught|dz teach|taught \(/i);
+  //    POSITIVE both halves (wave1-scorer-negation): "recall was not performed" and "no lessons were
+  //    taught (dz teach skipped)" both matched the plain regexes and scored the loop as RUN.
+  const recalled = evidenceLinePositive(
+    complexityText + '\n' + allText,
+    /LEARNED_PATTERNS|dz recall|recalled/i,
+    NEGATION_QUANTIFIED_RE,
+  );
+  const taught = evidenceLinePositive(allText, /lesson[s]? taught|dz teach|taught \(/i, NEGATION_QUANTIFIED_RE);
   add(
     'learning-loop',
     'Step-0 recall used; Step-8 lessons taught',

package/src/setup.ts

@@ -19,6 +19,8 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 
+import { mergeManagedHookEntries } from './managed-hooks.js';
+
 /** Memory backend type. */
 export type MemoryBackend = 'jsonl' | 'agentdb';
 
@@ -567,35 +569,32 @@ export function runSetup(opts: SetupOptions): SetupResult {
     } else {
       try {
         const existing = JSON.parse(readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>;
-        const hooks = (existing['hooks'] ?? {}) as Record<string, unknown[]>;
-        let changed = false;
-        let replacedLegacy = false;
-        for (const event of Object.keys(generated.hooks)) {
-          const current = Array.isArray(hooks[event]) ? hooks[event] : [];
-          // Drop dz-generated entries (any vintage, either shape) — keep the user's own hooks
-          // untouched. Flat dz entries (≤0.3.43) are dropped too, migrating them to the valid
-          // matcher-group shape appended below.
-          const kept = current.filter((entry) => {
-            const cmds = commandsOf(entry);
-            const isDz = cmds.some((cmd) => cmd.includes('agentdb add') || cmd.includes('agentdb-writer.mjs') || cmd.includes('sessions.jsonl'));
-            const isFlat = !Array.isArray((entry as { hooks?: unknown[] })?.hooks);
-            if (isDz && (isFlat || cmds.some((cmd) => cmd.includes('agentdb add')))) replacedLegacy = true;
-            return !isDz;
-          });
-          const next = [...kept, ...generated.hooks[event]!];
-          if (JSON.stringify(next) !== JSON.stringify(current)) changed = true;
-          hooks[event] = next;
-        }
-        if (changed) {
-          existing['hooks'] = hooks;
+        // ONE merge implementation, shared with the Codex target (AM-3 / G-E). The Claude path's
+        // historical SUBSTRING attribution is passed IN verbatim rather than reimplemented, so the
+        // emitted bytes, the report tail string and the no-write path all stay identical (AM-37).
+        const plan = mergeManagedHookEntries(
+          (existing['hooks'] ?? {}) as Record<string, unknown[]>,
+          generated.hooks as unknown as Record<string, unknown[]>,
+          {
+            // Drop dz-generated entries (any vintage, either shape) — keep the user's own hooks
+            // untouched. Flat dz entries (≤0.3.43) are dropped too, migrating them to the valid
+            // matcher-group shape appended below.
+            isManaged: (entry) =>
+              commandsOf(entry).some(
+                (cmd) => cmd.includes('agentdb add') || cmd.includes('agentdb-writer.mjs') || cmd.includes('sessions.jsonl'),
+              ),
+            isLegacy: (entry) =>
+              !Array.isArray((entry as { hooks?: unknown[] })?.hooks) ||
+              commandsOf(entry).some((cmd) => cmd.includes('agentdb add')),
+            reportLabel: backend,
+          },
+        );
+        if (plan.changed) {
+          existing['hooks'] = plan.hooks;
           writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
-          steps.push({
-            name: 'Configure hooks',
-            status: 'done',
-            detail: replacedLegacy ? `replaced legacy dz hooks with ${backend} hooks` : `merged ${backend} hooks (user hooks preserved)`,
-          });
+          steps.push({ name: 'Configure hooks', status: 'done', detail: plan.report });
         } else {
-          steps.push({ name: 'Configure hooks', status: 'skipped', detail: 'hooks already current' });
+          steps.push({ name: 'Configure hooks', status: 'skipped', detail: plan.report });
         }
       } catch {
         steps.push({ name: 'Configure hooks', status: 'error', detail: 'could not parse existing settings.json — fix it and re-run' });

package/src/shell-veto-policy.ts

@@ -0,0 +1,119 @@
+/**
+ * Shell veto policy (`crossrt-2-codex-hooks`, ADR-004 + ADR-005).
+ *
+ * ONE rule, judged on the raw command string, with no I/O of any kind. The mode — what the CALLER
+ * does with a hit — is decided by the caller from project config, never here.
+ *
+ * Polarity, in one sentence (ADR-004): **a policy hit ⇒ WARN by default, BLOCK only when the
+ * project opted in; our own failure ⇒ always ALLOW.**
+ *
+ * ## Why exactly one rule, and why this one
+ *
+ * `shell-veto-policy.ts` is NOT a general shell-guardrail engine (plan §0.1's C4 fence). Its
+ * charter is a single rule whose violation is **unambiguous**: the command line explicitly asks for
+ * WEAKER authentication than the ssh default. Every token below is one a safe invocation never
+ * contains, so a hit always means the user deliberately disabled a protection.
+ *
+ * The withdrawn v1 (`ssh-no-identity`, AM-23) judged the ABSENCE of `-i`/`IdentityFile=`, which
+ * blocked `ssh myhost` whenever the identity came from `~/.ssh/config` or `ssh-agent` — the normal
+ * secure case — from a user-global registry that reaches every directory on the machine. Absence of
+ * a token is not evidence of intent; presence of these four is.
+ *
+ * `StrictHostKeyChecking=no` and `UserKnownHostsFile=/dev/null` are deliberately NOT rules: they are
+ * a real weakening, but CI images use them legitimately, so no unambiguous verdict is available.
+ * They are the first candidates for a future rule with its own ADR — **no second rule ships in this
+ * leg**.
+ *
+ * @packageDocumentation
+ */
+
+/** What the caller does with a hit. `warn` is the shipped default (ADR-004). */
+export type VetoMode = 'off' | 'warn' | 'block';
+
+/** A policy hit. `null` from {@link vetoShellCommand} means allow. */
+export interface VetoHit {
+  readonly rule: string;
+  readonly reason: string;
+}
+
+/** The one rule id this leg ships. Exported so tests and the probe cannot drift from it. */
+export const SHELL_VETO_RULE_ID = 'ssh-explicit-auth-weakening';
+
+/**
+ * Shell word boundaries. Both ends of every token are anchored, so `echo "sshpassword"` and
+ * `--my-passwordauthentication=yes` cannot hit: a user-global guard that matches on a bare
+ * substring is one common word away from a machine-wide outage.
+ */
+const BOUNDARY = String.raw`[\s;&|()'"\`]`;
+const OPT = String.raw`(?:^|${BOUNDARY})-o\s*`;
+const END = String.raw`(?=$|${BOUNDARY})`;
+
+/** `-o PasswordAuthentication=yes` — the user turns ON password auth against the ssh default. */
+const PASSWORD_AUTHENTICATION = new RegExp(`${OPT}passwordauthentication\\s*=\\s*yes${END}`, 'i');
+
+/** `-o PubkeyAuthentication=no` — the user turns OFF key auth. */
+const PUBKEY_AUTHENTICATION = new RegExp(`${OPT}pubkeyauthentication\\s*=\\s*no${END}`, 'i');
+
+/** `-o PreferredAuthentications=…password…` — the user ORDERS password auth ahead of pubkey. */
+const PREFERRED_AUTHENTICATIONS = new RegExp(
+  `${OPT}preferredauthentications\\s*=\\s*` +
+    `(?:[a-z][a-z0-9-]*\\s*,\\s*)*` +
+    `(?:password|keyboard-interactive)` +
+    `(?:\\s*,\\s*[a-z][a-z0-9-]*)*${END}`,
+  'i',
+);
+
+/** `sshpass` as a COMMAND TOKEN — a password is fed to ssh from the command line by construction. */
+const SSHPASS_TOKEN = new RegExp(`(?:^|${BOUNDARY})sshpass${END}`, 'i');
+
+/**
+ * Judge one raw shell command.
+ *
+ * @returns a {@link VetoHit} when the command EXPLICITLY weakens ssh authentication, else `null`.
+ *          Pure: no filesystem, no environment, no config, no clock.
+ */
+export function vetoShellCommand(command: string): VetoHit | null {
+  if (typeof command !== 'string' || command === '') return null;
+
+  if (SSHPASS_TOKEN.test(command)) {
+    return {
+      rule: SHELL_VETO_RULE_ID,
+      reason: 'sshpass feeds an ssh password from the command line, disabling key-based auth by construction',
+    };
+  }
+  if (PASSWORD_AUTHENTICATION.test(command)) {
+    return {
+      rule: SHELL_VETO_RULE_ID,
+      reason: 'PasswordAuthentication=yes turns ON password auth against the ssh default',
+    };
+  }
+  if (PUBKEY_AUTHENTICATION.test(command)) {
+    return {
+      rule: SHELL_VETO_RULE_ID,
+      reason: 'PubkeyAuthentication=no turns OFF key auth',
+    };
+  }
+  if (PREFERRED_AUTHENTICATIONS.test(command)) {
+    return {
+      rule: SHELL_VETO_RULE_ID,
+      reason: 'PreferredAuthentications orders password/keyboard-interactive auth ahead of pubkey',
+    };
+  }
+  return null;
+}
+
+/**
+ * Resolve the enforcement mode from a parsed `.dz/config.json`.
+ *
+ * ABSENT, unknown, non-string, or malformed ⇒ `'warn'`. Never `'block'` by default: fail-closed is
+ * a decision the owner makes, not one a user-global hook install imposes on every directory
+ * (ADR-004 / AM-24). A mutant that flips this default is registered in the mutation registry.
+ */
+export function resolveVetoMode(projectConfig: unknown): VetoMode {
+  if (typeof projectConfig !== 'object' || projectConfig === null) return 'warn';
+  const hooks = (projectConfig as Record<string, unknown>)['hooks'];
+  if (typeof hooks !== 'object' || hooks === null) return 'warn';
+  const mode = (hooks as Record<string, unknown>)['shellVeto'];
+  if (mode === 'off' || mode === 'warn' || mode === 'block') return mode;
+  return 'warn';
+}