@dzhechkov/harness-core 0.4.5 → 0.5.1

package/src/managed-hooks.ts

@@ -0,0 +1,150 @@
+/**
+ * The ONE event-level managed-hook merge (`crossrt-2-codex-hooks`, AM-3 / G-E).
+ *
+ * Both hook targets — Claude Code's `.claude/settings.json` and Codex's
+ * `$CODEX_HOME/hooks.json` — need the same operation: per event, KEEP every entry that is not ours
+ * (byte-identical, same order) and append the entries that are. Before this module the Claude half
+ * lived inline in `setup.ts` and the Codex half did not exist; a second dialect would have been the
+ * obvious way to write it and the wrong one.
+ *
+ * What differs between the targets is ONLY the attribution predicate, so that is the parameter:
+ * the Claude path passes its historical substring list verbatim (bytes must not move — AM-3), the
+ * Codex path passes sha-over-manifest (ADR-001 §3: dz never deletes what it cannot prove it wrote).
+ *
+ * The plan (AM-37) is explicit that the extracted block has **three** outputs, not one: the merged
+ * body, the REPORT tail string, and the no-write path (`changed === false`). A golden test on the
+ * merged bytes alone would pass while the report text and the no-write behaviour silently changed,
+ * so all three are part of {@link HookMergePlan}.
+ *
+ * Pure: no I/O, no clock, no environment.
+ *
+ * @packageDocumentation
+ */
+
+/** One hook registry entry, in either the matcher-group or the legacy flat shape. */
+export type ManagedHookEntry = unknown;
+
+/**
+ * Commands of a hook entry in EITHER shape: the valid matcher-group form
+ * `{matcher?, hooks:[{type,command}]}` or the legacy flat `{type,command}`.
+ *
+ * Deliberately duplicated from `setup.ts`'s `commandsOf` rather than imported: `setup.ts` imports
+ * this module, and the reverse edge would be a cycle. The two are pinned equal by a test.
+ */
+export function hookCommandsOf(entry: ManagedHookEntry): string[] {
+  const e = entry as { command?: unknown; hooks?: { command?: unknown }[] };
+  if (Array.isArray(e?.hooks)) return e.hooks.map((h) => String(h?.command ?? ''));
+  return [String(e?.command ?? '')];
+}
+
+export interface HookMergePlan {
+  /** The merged registry body, ready to serialize. */
+  readonly hooks: Record<string, ManagedHookEntry[]>;
+  /** False ⇒ the caller must NOT write (the `hooks already current` no-write path — AM-37). */
+  readonly changed: boolean;
+  /** The setup REPORT tail string. Part of the extracted block's contract, not decoration (AM-37). */
+  readonly report: string;
+  /** A legacy-shaped entry of ours was replaced (drives the Claude report wording). */
+  readonly replacedLegacy: boolean;
+  /** Entries kept because they are NOT ours, across the WHOLE registry. G-D's number. */
+  readonly foreignPreserved: number;
+  /**
+   * Entries that RESEMBLE ours but are not attributable to the manifest. They are KEPT and counted —
+   * never deleted (ADR-001 §3). Distinct from `replacedLegacy`, which is about our OWN old vintages.
+   */
+  readonly unattributable: number;
+}
+
+export interface MergeManagedHookOptions {
+  /** True ⇒ this entry is OURS and is replaced by the managed set for that event. */
+  readonly isManaged: (entry: ManagedHookEntry, event: string) => boolean;
+  /**
+   * True ⇒ this entry resembles ours but could not be attributed. Optional; when omitted nothing is
+   * counted. Never causes deletion — only counting and a warning upstream.
+   */
+  readonly looksLikeOurs?: (entry: ManagedHookEntry, event: string) => boolean;
+  /** True ⇒ this OURS entry was in a legacy shape/vintage (Claude path only). */
+  readonly isLegacy?: (entry: ManagedHookEntry, event: string) => boolean;
+  /**
+   * Per-HANDLER salvage for an entry `isManaged` claimed. Given an OWNED entry, return it rebuilt
+   * from only the handlers that are NOT ours, or `null` when every handler was ours.
+   *
+   * Optional, and absent means the historical whole-entry behaviour — the Claude path passes
+   * nothing and is byte-identical to before (AM-3). The Codex path passes it because attribution at
+   * matcher-group granularity deleted a foreign handler that merely shared a group with dz's
+   * (independent review, finding 6).
+   */
+  readonly retainForeign?: (entry: ManagedHookEntry, event: string) => ManagedHookEntry | null;
+  /** e.g. `'agentdb'` → `merged agentdb hooks (user hooks preserved)`. */
+  readonly reportLabel?: string;
+  /** Report text when nothing changed. */
+  readonly unchangedReport?: string;
+}
+
+/**
+ * Merge `managed` into `existingHooks` at EVENT level.
+ *
+ * - Events absent from `managed` are copied through untouched (including unknown ones), and their
+ *   entries still count toward `foreignPreserved` — the number answers "how many of the user's
+ *   entries did this registry hold and keep", not "how many survived the touched events".
+ * - Within a touched event, non-ours entries keep their relative order and object identity, then
+ *   the managed entries are appended.
+ * - `merge(merge(x)) === merge(x)`.
+ */
+export function mergeManagedHookEntries(
+  existingHooks: Record<string, ManagedHookEntry[]> | undefined,
+  managed: Record<string, ManagedHookEntry[]>,
+  options: MergeManagedHookOptions,
+): HookMergePlan {
+  const source = existingHooks ?? {};
+  const hooks: Record<string, ManagedHookEntry[]> = {};
+  for (const event of Object.keys(source)) {
+    hooks[event] = Array.isArray(source[event]) ? [...(source[event] as ManagedHookEntry[])] : [];
+  }
+
+  // Census FIRST, over the whole input, so the counts do not depend on which events are touched.
+  let foreignPreserved = 0;
+  let unattributable = 0;
+  for (const [event, entries] of Object.entries(source)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (options.isManaged(entry, event)) {
+        // A mixed group counts as a preserved foreign entry when something of the user's survives
+        // in it — the census must not report zero for a handler the merge actually keeps.
+        if (options.retainForeign?.(entry, event) != null) foreignPreserved += 1;
+        continue;
+      }
+      foreignPreserved += 1;
+      if (options.looksLikeOurs?.(entry, event) === true) unattributable += 1;
+    }
+  }
+
+  let changed = false;
+  let replacedLegacy = false;
+  for (const event of Object.keys(managed)) {
+    const current = Array.isArray(hooks[event]) ? (hooks[event] as ManagedHookEntry[]) : [];
+    const kept: ManagedHookEntry[] = [];
+    for (const entry of current) {
+      const ours = options.isManaged(entry, event);
+      if (!ours) {
+        kept.push(entry);
+        continue;
+      }
+      if (options.isLegacy?.(entry, event) === true) replacedLegacy = true;
+      const salvaged = options.retainForeign?.(entry, event) ?? null;
+      if (salvaged !== null) kept.push(salvaged);
+    }
+    const next = [...kept, ...(managed[event] ?? [])];
+    if (JSON.stringify(next) !== JSON.stringify(current)) changed = true;
+    hooks[event] = next;
+  }
+
+  const label = options.reportLabel ?? 'managed';
+  const report = !changed
+    ? (options.unchangedReport ?? 'hooks already current')
+    : replacedLegacy
+      ? `replaced legacy dz hooks with ${label} hooks`
+      : `merged ${label} hooks (user hooks preserved)`;
+
+  return { hooks, changed, report, replacedLegacy, foreignPreserved, unattributable };
+}

package/src/mutation-gate.ts

@@ -317,6 +317,26 @@ function stripSgr(s: string): string {
 
 export type RunnerKind = 'node-test' | 'vitest' | 'unknown';
 
+/**
+ * Which runner's output shape is this? Extracted VERBATIM from `classifyRunFailure`'s two shape
+ * checks so the discrimination gate's evidence model can identify the runner of a GREEN run too —
+ * `classifyRunFailure` classifies RED runs only (its green branch returns a red-worded
+ * 'unrecognised'), so it cannot answer "which runner produced this pass?".
+ *
+ * ONE regex family per package (the ADR-001 driver): every runner-shape regex in harness-core
+ * lives here, and discrimination-gate.ts consumes this function instead of growing a second copy.
+ * Detection is from the OUTPUT SHAPE, not the command (an `npm test` alias hides the runner):
+ * node --test needs the TAP header AND node's `# duration_ms` trailer (tape emits TAP + `# fail`
+ * but not `# duration_ms`); vitest needs its `RUN v<semver>` banner or `Test Files` summary line.
+ * Anything else is 'unknown' — the honest, narrowed gap, never a silent trust mint.
+ */
+export function detectRunnerKind(rawOutput: string): RunnerKind {
+  const output = stripSgr(rawOutput);
+  if (/^TAP version \d+/m.test(output) && /^#\s*duration_ms\s+[\d.]+/m.test(output)) return 'node-test';
+  if (/^\s*RUN\s+v\d+\./m.test(output) || /^\s*Test Files\s/m.test(output)) return 'vitest';
+  return 'unknown';
+}
+
 export interface RunFailureClassification {
   /** which runner's output shape was recognised. */
   readonly runner: RunnerKind;
@@ -373,9 +393,11 @@ export interface RunFailureClassification {
  */
 export function classifyRunFailure(rawOutput: string): RunFailureClassification {
   const output = stripSgr(rawOutput);
+  // shape detection is shared with the discrimination gate's evidence model (detectRunnerKind above).
+  const runner = detectRunnerKind(rawOutput);
 
   // node --test (flat TAP, node ≥ 20 shape measured on v22.22.0)
-  if (/^TAP version \d+/m.test(output) && /^#\s*duration_ms\s+[\d.]+/m.test(output)) {
+  if (runner === 'node-test') {
     const lines = output.split('\n');
     let sawNotOk = false;
     for (let i = 0; i < lines.length; i++) {
@@ -407,7 +429,7 @@ export function classifyRunFailure(rawOutput: string): RunFailureClassification
   }
 
   // vitest (`vitest run`, shape measured on 3.2.4)
-  if (/^\s*RUN\s+v\d+\./m.test(output) || /^\s*Test Files\s/m.test(output)) {
+  if (runner === 'vitest') {
     const failedSuites = /\bFailed Suites\s+(\d+)\b/.exec(output);
     const suiteFail = /^\s*FAIL\s+(\S+)\s+\[\s*\1\s*\]/m.exec(output);
     if (failedSuites !== null || suiteFail !== null) {

package/src/named-lock.ts

@@ -0,0 +1,277 @@
+/**
+ * Named advisory locks — `.dz/locks/<name>.lock` (feature qe-bridge-claude, ADR-001 D4-A).
+ *
+ * WHY. The pattern store already has a cross-process lock (`store-lock.ts`), but it guards ONE
+ * resource. Other read-modify-write surfaces in this repo have the same lost-update shape and no
+ * guard — the first of them being the `$CODEX_HOME/hooks.json` merge writer, whose race was
+ * ACCEPTED as a degradation with an explicit exit condition naming this leg
+ * (`architecture/degradations.md`). A read-modify-write that two processes interleave loses one
+ * side's addition, and BOTH report success — atomicity (temp+rename) prevents corruption; only
+ * mutual exclusion prevents a lost update.
+ *
+ * WHAT THIS IS. The same `proper-lockfile` machinery as `withStoreLockSync`: atomic `mkdir`
+ * acquisition, heartbeat-refreshed staleness (age alone is never liveness), a real acquisition
+ * DEADLINE, and a LOUD throw on timeout rather than proceeding unlocked — proceeding would restore
+ * exactly the silent lost update this exists to stop. It is emphatically NOT the hand-rolled `wx`
+ * file lock that an independent review graded F (`store-lock.ts:14-31`).
+ *
+ * WHY A MIRROR AND NOT A CALL. `store-lock.ts` keeps its internals private and this feature's
+ * out-of-scope fence forbids changing the store lock's semantics, so the ~40 lines of acquisition
+ * machinery are mirrored here rather than extracted. The duplication is deliberate and is a named
+ * unification candidate; the options type, the stale/timeout defaults and the environment override
+ * are IMPORTED from `store-lock.ts`, so the two cannot drift apart on their contract.
+ *
+ * HONEST LIMIT. This is an ADVISORY lock: it serializes writers that TAKE it. A foreign process
+ * that never heard of it writes whenever it likes. For `hooks.json` the pre-existing mitigations
+ * (foreign entries preserved byte-for-byte, timestamped backup, atomic temp+rename) remain the
+ * backstop for that case, and the rule doc says so in as many words.
+ */
+
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { lockSync } from 'proper-lockfile';
+
+import { LOCK_TIMEOUT_MS, STALE_LOCK_MS } from './store-lock.js';
+import type { StoreLockOptions } from './store-lock.js';
+
+/** `proper-lockfile` silently clamps `stale` up to this minimum. */
+const MIN_STALE_MS = 2_000;
+
+/** Lock names are filenames: one bounded, lowercase, path-free component. */
+const SAFE_LOCK_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+export function isSafeLockName(name: string): boolean {
+  return typeof name === 'string' && SAFE_LOCK_NAME.test(name);
+}
+
+/** Path of a named lock (a DIRECTORY while held). Throws on an unsafe name — a lock whose path a
+ * caller can steer is not a lock. */
+export function namedLockPath(projectRoot: string, name: string): string {
+  if (!isSafeLockName(name)) {
+    throw new NamedLockNameError(name);
+  }
+  return join(projectRoot, '.dz', 'locks', `${name}.lock`);
+}
+
+export class NamedLockNameError extends Error {
+  readonly code = 'ELOCKNAME';
+  constructor(name: string) {
+    super(
+      `invalid lock name ${JSON.stringify(name)} — a lock name must match ${String(SAFE_LOCK_NAME)} ` +
+      '(one lowercase path-free component); a name carrying a separator would place the lock outside .dz/locks/',
+    );
+    this.name = 'NamedLockNameError';
+  }
+}
+
+/** Acquisition gave up at the deadline. Nothing ran; the operation can be retried. */
+export class NamedLockTimeoutError extends Error {
+  readonly code = 'ELOCKTIMEOUT';
+  constructor(lockPath: string, waitedMs: number) {
+    super(
+      `the lock at ${lockPath} stayed held for ${waitedMs}ms — another process is still inside the ` +
+      'guarded section. Nothing was written; retry.',
+    );
+    this.name = 'NamedLockTimeoutError';
+  }
+}
+
+/** The lock was broken out from under the holder while `fn` ran: it DID run, but may have raced. */
+export class NamedLockCompromisedError extends Error {
+  readonly code = 'ECOMPROMISED';
+  constructor(lockPath: string, cause: Error) {
+    super(`the lock at ${lockPath} was compromised while held (${cause.message}) — retry the operation.`);
+    this.name = 'NamedLockCompromisedError';
+  }
+}
+
+const defaultTimeoutMs = (): number => {
+  const env = Number(process.env['DZ_STORE_LOCK_TIMEOUT_MS']);
+  return Number.isFinite(env) && env > 0 ? env : LOCK_TIMEOUT_MS;
+};
+
+/** Synchronous sleep without spinning (Atomics.wait on a throwaway buffer). */
+const sleepSync = (ms: number): void => {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+
+function resolveOpts(opts: StoreLockOptions): { staleMs: number; timeoutMs: number; pollMs: number } {
+  return {
+    staleMs: Math.max(opts.staleMs ?? STALE_LOCK_MS, MIN_STALE_MS),
+    timeoutMs: opts.timeoutMs ?? defaultTimeoutMs(),
+    pollMs: opts.pollMs ?? 25,
+  };
+}
+
+interface Acquired {
+  /** Releases the lock. Returns `'released'` when it was ours, `'stolen'` when it was not (nothing
+   * removed, exit-time removal disarmed) and `'stolen-undisarmed'` when it was not ours AND the
+   * exit-time removal could not be disarmed — a gap the caller must hear about. */
+  readonly release: () => 'released' | 'stolen' | 'stolen-undisarmed';
+}
+
+/**
+ * DISARMING THE LIBRARY'S EXIT HANDLER (round-2 CRITICAL C2, second mechanism).
+ *
+ * `proper-lockfile` registers a process-exit handler that `rmdirSync`s every lock still in its
+ * internal map — unconditionally, with no ownership check (lockfile.js: "Remove acquired locks on
+ * exit"). So even after this module refuses to remove a stolen lock, the holder's PROCESS EXIT
+ * removed the successor's live lock a moment later. MEASURED: process C then acquired the lock while
+ * B was still inside its critical section.
+ *
+ * The map is reachable through the library's own `getLocks()` accessor. It is not re-exported by the
+ * package index, so this is a deep import — guarded by a runtime shape check, and NEVER silent: if
+ * the accessor is missing (a future version moved it), the compromise error says the exit-time
+ * removal could not be disarmed, so the gap is reported rather than assumed away.
+ */
+const lockfileInternals: { getLocks?: () => Record<string, unknown> } = (() => {
+  try {
+    const req = createRequire(import.meta.url);
+    const mod = req('proper-lockfile/lib/lockfile.js') as { getLocks?: unknown };
+    return typeof mod.getLocks === 'function' ? { getLocks: mod.getLocks as () => Record<string, unknown> } : {};
+  } catch {
+    return {};
+  }
+})();
+
+/** Drop a lock we no longer own from the library's exit-time removal list. Returns false when the
+ * accessor is unavailable — the caller says so out loud. */
+function disarmExitRemoval(resourceKey: string): boolean {
+  const get = lockfileInternals.getLocks;
+  if (get === undefined) return false;
+  try {
+    const locks = get();
+    if (Object.prototype.hasOwnProperty.call(locks, resourceKey)) delete locks[resourceKey];
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * OWNERSHIP TOKEN (round-2 CRITICAL C2). `proper-lockfile`'s release is unconditional: it clears its
+ * timer and removes the lock directory, without checking that the directory is still the one it
+ * created. That is safe while the heartbeat runs — but a SYNCHRONOUS critical section blocks the
+ * event loop, so the heartbeat cannot fire, a waiter is entitled to break the stale lock, and the
+ * original holder then deletes its SUCCESSOR's live lock on the way out.
+ *
+ * MEASURED (2026-08-19, three real processes, reproducer in named-lock.test.ts / red-green.md):
+ * with a 6s synchronous body under a 2s stale threshold, process C acquired the lock while B was
+ * still inside its critical section — mutual exclusion gone, silently.
+ *
+ * The fix: stamp a random token BESIDE the lock directory at acquisition and verify it at release. A
+ * lock that no longer carries our token is somebody else's, and we do not touch it — we report the
+ * compromise loudly instead. (The marker lives beside, not inside: `proper-lockfile` removes the
+ * lock with a plain `rmdir`, so a file within it would make every release silently fail and leak the
+ * lock — MEASURED, the first draft of this fix did exactly that and the suite went red.)
+ */
+function ownerMarkerPath(lockPath: string): string {
+  return lockPath + '.owner';
+}
+
+function tryAcquire(
+  projectRoot: string,
+  name: string,
+  staleMs: number,
+  onCompromised: (e: Error) => void,
+): Acquired | 'held' {
+  const lockPath = namedLockPath(projectRoot, name);
+  const resourceKey = resolve(projectRoot, '.dz', 'locks', name);
+  try {
+    const release = lockSync(resourceKey, {
+      lockfilePath: lockPath,
+      stale: staleMs,
+      realpath: false, // the guarded resource is a concept, not an existing file
+      onCompromised,
+    });
+    const token = randomBytes(16).toString('hex');
+    let ino: number | null = null;
+    try {
+      writeFileSync(ownerMarkerPath(lockPath), token, { mode: 0o600 });
+      ino = statSync(lockPath).ino;
+    } catch { /* an unwritable lock dir: fall back to inode-only evidence below */ }
+    return {
+      release: (): 'released' | 'stolen' | 'stolen-undisarmed' => {
+        let ours = false;
+        try {
+          const seen = readFileSync(ownerMarkerPath(lockPath), 'utf8');
+          const sameIno = ino === null ? true : statSync(lockPath).ino === ino;
+          ours = seen === token && sameIno;
+        } catch {
+          ours = false; // gone, or unreadable — either way not provably ours
+        }
+        if (!ours) {
+          // NEVER remove a lock directory we cannot prove is ours — including at process exit.
+          return disarmExitRemoval(resourceKey) ? 'stolen' : 'stolen-undisarmed';
+        }
+        try {
+          release();
+        } catch { /* ERELEASED after a compromise — the lock is no longer ours to remove */ }
+        try {
+          rmSync(ownerMarkerPath(lockPath), { force: true });
+        } catch { /* best effort: a stale marker is overwritten by the next holder anyway */ }
+        return 'released';
+      },
+    };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ELOCKED') return 'held';
+    throw err;
+  }
+}
+
+/**
+ * Run `fn` while holding the named lock, releasing it however `fn` ends.
+ *
+ * Throws {@link NamedLockTimeoutError} when the lock cannot be acquired by the deadline (nothing
+ * has run) and {@link NamedLockCompromisedError} when the lock was broken while `fn` ran. The
+ * heartbeat cannot fire while a synchronous `fn` blocks the event loop, so keep bodies well under
+ * `staleMs` — the same caveat `withStoreLockSync` carries.
+ */
+export function withNamedLockSync<T>(
+  projectRoot: string,
+  name: string,
+  fn: () => T,
+  opts: StoreLockOptions = {},
+): T {
+  const lockPath = namedLockPath(projectRoot, name); // validates the name BEFORE any mkdir
+  const { staleMs, timeoutMs, pollMs } = resolveOpts(opts);
+  mkdirSync(join(projectRoot, '.dz', 'locks'), { recursive: true });
+  const started = Date.now();
+  const deadline = started + timeoutMs;
+  let compromised: Error | undefined;
+  const onCompromised = (e: Error): void => { compromised = e; };
+  for (;;) {
+    const got = tryAcquire(projectRoot, name, staleMs, onCompromised);
+    if (got !== 'held') {
+      let result: T;
+      let outcome: 'released' | 'stolen' | 'stolen-undisarmed' = 'released';
+      try {
+        result = fn();
+      } finally {
+        outcome = got.release();
+      }
+      if (outcome !== 'released') {
+        throw new NamedLockCompromisedError(
+          lockPath,
+          compromised ??
+            new Error(
+              'the lock directory no longer carries this holder\u2019s ownership token — a waiter broke it as stale ' +
+              'while the critical section was still running (a synchronous body cannot heartbeat). The successor\u2019s ' +
+              'lock was left untouched; THIS run must be treated as having raced and retried.' +
+              (outcome === 'stolen-undisarmed'
+                ? ' WARNING: proper-lockfile\u2019s exit-time lock removal could NOT be disarmed (its getLocks() accessor ' +
+                  'is unavailable in this version), so this process may still remove the successor\u2019s lock when it exits.'
+                : ''),
+            ),
+        );
+      }
+      if (compromised !== undefined) throw new NamedLockCompromisedError(lockPath, compromised);
+      return result;
+    }
+    const now = Date.now();
+    if (now >= deadline) throw new NamedLockTimeoutError(lockPath, now - started);
+    sleepSync(Math.min(pollMs, deadline - now));
+  }
+}