@dzhechkov/harness-core 0.8.39 → 0.8.41

package/src/__tests__/golden-baseline.test.ts

@@ -13,7 +13,7 @@ import { DEFAULT_HARMONIZE_THRESHOLD } from '../vector-tier.js';
 
 let project: string;
 
-beforeEach(() => { project = mkdtempSync(join(tmpdir(), 'dz-golden-')); });
+beforeEach(() => { project = mkdtempSync(join(tmpdir(), 'dz-golden-')); mkdirSync(join(project, '.dz'), { recursive: true }); /* the store pre-exists: a lock never seeds one */ });
 afterEach(() => rmSync(project, { recursive: true, force: true }));
 
 async function seed(): Promise<void> {

package/src/agentdb-index.ts

@@ -23,7 +23,7 @@ import { applyReadonlyPragmas } from './sqlite-read-helpers.js';
 import { rotatePreReindexSnapshotsUnlocked, type SnapshotRotationReport } from './agentdb-snapshot-rotation.js';
 import { snapshotSqliteDatabase, restoreSqliteSnapshot, type SnapshotMethod, type SnapshotDbCtor } from './agentdb-snapshot.js';
 import { withAgentdbSnapshotLock, writeReindexMarker, clearReindexMarker, markReindexMarkerRecoveryRequired, reindexMarkerPath, msFromBackupPath } from './agentdb-reindex-marker.js';
-import { NamedLockTimeoutError, withNamedLockSync } from './named-lock.js';
+import { NamedLockTimeoutError, withDirLockSync } from './named-lock.js';
 import type { StoreLockOptions } from './store-lock.js';
 // The backlog dedup embed form (PURE, zero-dep — no cycle): dz-backlog rows must be embedded in the
 // SAME bounded form the dedup query uses, including through the reindex path.
@@ -206,7 +206,7 @@ export function readStoreGeneration(projectRoot: string, dbPath?: string): numbe
  * under mutual exclusion (AM-2, fix-round after Codex review). A bare read→compute→rename with no
  * lock lets two concurrent writers both read the same current value and both publish `current+1` —
  * one bump is lost — or lets a DELAYED writer overwrite a later value with an earlier one (the
- * counter briefly goes backwards on disk). `withNamedLockSync` (`named-lock.ts`, the repo's
+ * counter briefly goes backwards on disk). `withDirLockSync` (`named-lock.ts`, the repo's
  * advisory lock for a read-modify-write file store — `.claude/rules/cross-runtime-concurrency.md`)
  * serializes the critical section; the counter is RE-READ from disk *inside* the lock (never trusted
  * from before acquisition), so the sequence every process observes is strictly monotonic
@@ -303,7 +303,7 @@ export function bumpStoreGeneration(
     // this sidecar now tracks "last PUBLISHED generation", updated on every successful bump, not just
     // a recovery.
     const recoveredMemoryFile = recoveredMemoryFilePath(genFile);
-    return withNamedLockSync(
+    return withDirLockSync(
       dirname(dbFile),
       'store-generation',
       (): { readonly ok: true; readonly generation: number } | { readonly ok: false; readonly error: string } => {

package/src/agentdb-reindex-marker.ts

@@ -8,8 +8,8 @@
  * concurrent `rotate --keep 0` can delete the very snapshot family a live reindex is relying on as
  * its undo point, with only a 10-minute grace period standing in the way.
  *
- * {@link withAgentdbSnapshotLock} is a thin, dbFile-addressed wrapper over `withNamedLockSync`: the
- * lock lives at `<dirname(dbFile)>/.dz/locks/agentdb-snapshot.lock` — a pure function of the
+ * {@link withAgentdbSnapshotLock} is a thin, dbFile-addressed wrapper over `withDirLockSync`: the
+ * lock lives at `<dirname(dbFile)>/.dz-locks/agentdb-snapshot.lock` (or the pre-existing legacy `.dz/locks` path) — a pure function of the
  * database's OWN directory, never of the caller's cwd, so a project store and the home brain each
  * get their own lock (AC-5) regardless of where `dz` happens to be invoked from. AM-7: it defaults
  * `staleMs` to {@link AGENTDB_SNAPSHOT_LOCK_STALE_MS} (5 minutes) rather than named-lock's ordinary
@@ -56,7 +56,7 @@ import { closeSync, openSync, readFileSync, renameSync, rmSync, writeFileSync }
 import { randomBytes } from 'node:crypto';
 import { basename, dirname } from 'node:path';
 
-import { withNamedLockSync } from './named-lock.js';
+import { withDirLockSync } from './named-lock.js';
 import type { StoreLockOptions } from './store-lock.js';
 
 /** A marker older than this is abandoned — its family is no longer protected (FR-3). `pid` is
@@ -125,7 +125,7 @@ export function withAgentdbSnapshotLock<T>(
   fn: () => T,
   opts: StoreLockOptions = {},
 ): T {
-  return withNamedLockSync(dirname(dbFile), 'agentdb-snapshot', fn, {
+  return withDirLockSync(dirname(dbFile), 'agentdb-snapshot', fn, {
     staleMs: AGENTDB_SNAPSHOT_LOCK_STALE_MS,
     ...opts,
   });

package/src/agentdb-snapshot-rotation.ts

@@ -351,7 +351,7 @@ export function rotatePreReindexSnapshotsUnlocked(
  *
  * `lockTimeoutMs` is test/tuning-only: omitted, the lock uses its ordinary default deadline.
  *
- * AM-4 (carried forward): `withNamedLockSync` creates `<dirname(dbFile)>/.dz/locks/` before it ever
+ * AM-4 (carried forward): `withDirLockSync` creates `<dirname(dbFile)>/.dz-locks/` (or reuses a legacy `.dz/locks/`) before it ever
  * runs `fn` — if `dirname(dbFile)` exists but is NOT a directory (a pathological store path, exactly
  * the shape AM-4's own fixture uses), that `mkdirSync` throws `ENOTDIR` before any lock is even
  * attempted. Scanning is therefore checked FIRST, outside the lock: an unreadable directory is a

package/src/backup-freshness.ts

@@ -0,0 +1,96 @@
+/**
+ * Свежесть резервной копии бэклога по журналу backup-backlog.
+ *
+ * Порядок строк важнее меток времени: отказ без даты ПОСЛЕ успеха — последний вердикт.
+ * Отсутствие вердикта не доказывает ни актуальность копии, ни её отказ.
+ */
+export type BackupFreshnessVerdict =
+  | { readonly state: 'fresh'; readonly verifiedAt: string; readonly ageHours: number; readonly tasks: number | null }
+  | {
+    readonly state: 'stale';
+    readonly reason: 'too-old' | 'last-run-failed';
+    readonly verifiedAt: string | null;
+    readonly ageHours: number | null;
+    readonly failureLine: string | null;
+  }
+  | {
+    readonly state: 'not-established';
+    readonly reason: 'no-verdict' | 'bad-stamp' | 'unrecognized-after-success';
+    readonly detail: string;
+    readonly unrecognizedLine?: string;
+  };
+
+/** Чистое решение. Ничего не читает и не запускает — строки и часы подаёт вызывающий. */
+export function decideBackupFreshness(input: {
+  readonly lines: readonly string[];
+  readonly now: Date;
+  readonly maxAgeHours: number;
+}): BackupFreshnessVerdict {
+  let last: 'success' | 'failure' | 'unrecognized' | null = null;
+  let successLine = '';
+  let unrecognizedLine = '';
+  let failureLine: string | null = null;
+  let verifiedAt: string | null = null;
+  let verifiedMs: number | null = null;
+
+  for (const line of input.lines) {
+    if (line.includes('backup-backlog') && ['не удалось', 'НЕ ПРОШЛА', 'ОТПРАВКА ОТКЛОНЕНА', 'не найден'].some((text) => line.includes(text))) {
+      last = 'failure';
+      failureLine = line;
+      continue;
+    }
+    const isSuccess = line.startsWith('backup-backlog')
+      && (line.includes('копия проверена по свежему клону') || line.includes('изменений нет — копия уже актуальна'));
+    if (!isSuccess) {
+      // Разрешаем только известный прогресс: незнакомый вывод не доказывает успех.
+      if (line.trim() === '' || /^backup-backlog(?: \[[^\]]+\])?: отправлено,/.test(line) || /^\s*разобрано задач:/.test(line)) continue;
+      if (successLine !== '') {
+        last = 'unrecognized';
+        unrecognizedLine = line.slice(0, 200);
+      }
+      continue;
+    }
+    last = 'success';
+    successLine = line;
+    const stamp = /\[(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z)\]/.exec(line)?.[1];
+    const ms = stamp === undefined ? NaN : Date.parse(stamp);
+    // Date.parse нормализует некоторые несуществующие даты: обратная проверка их отвергает.
+    const valid = Number.isFinite(ms) && new Date(ms).toISOString() === stamp?.replace('Z', ':00.000Z');
+    verifiedAt = valid ? stamp! : null;
+    verifiedMs = valid ? ms : null;
+  }
+
+  if (last === null) {
+    return { state: 'not-established', reason: 'no-verdict', detail: 'журнал не содержит ни одной строки с вердиктом' };
+  }
+  if (last === 'unrecognized') {
+    return { state: 'not-established', reason: 'unrecognized-after-success', detail: 'неузнанная строка после успеха', unrecognizedLine };
+  }
+  const elapsed = verifiedMs === null ? null : (input.now.getTime() - verifiedMs) / 3_600_000;
+  const ageHours = elapsed === null ? null : Math.round(elapsed * 10) / 10;
+  if (last === 'failure') {
+    return { state: 'stale', reason: 'last-run-failed', verifiedAt, ageHours, failureLine };
+  }
+  if (verifiedAt === null || ageHours === null || elapsed === null) {
+    return { state: 'not-established', reason: 'bad-stamp', detail: `строка успеха без валидной даты: ${successLine}` };
+  }
+  if (elapsed > input.maxAgeHours) {
+    return { state: 'stale', reason: 'too-old', verifiedAt, ageHours, failureLine: null };
+  }
+  const tasks = /(\d+)\s+задач/.exec(successLine)?.[1];
+  return { state: 'fresh', verifiedAt, ageHours, tasks: tasks === undefined ? null : Number(tasks) };
+}
+
+/** Одна строка для человека: измеренный возраст либо конкретная строка отказа. */
+export function renderBackupFreshness(verdict: BackupFreshnessVerdict): string {
+  if (verdict.state === 'not-established') {
+    return `backlog backup: НЕ УСТАНОВЛЕНО — ${verdict.detail}${verdict.unrecognizedLine === undefined ? '' : `: ${verdict.unrecognizedLine}`}`;
+  }
+  if (verdict.state === 'fresh') {
+    return `backlog backup: копия актуальна — возраст ${verdict.ageHours} ч, проверена ${verdict.verifiedAt}${verdict.tasks === null ? '' : `, ${verdict.tasks} задач`}`;
+  }
+  if (verdict.reason === 'last-run-failed') {
+    return `backlog backup: последний запуск завершился отказом — ${verdict.failureLine}`;
+  }
+  return `backlog backup: копия устарела — возраст ${verdict.ageHours} ч, проверена ${verdict.verifiedAt}`;
+}

package/src/cmd-usage.ts

@@ -21,7 +21,8 @@ import {
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
-import { withNamedLockSync } from './named-lock.js';
+import { withProjectLockSync } from './named-lock.js';
+import { StoreAbsentError } from './store-lock.js';
 import { isRepoBoundary } from './repo-boundary.js';
 
 export const CMD_USAGE_LOG_RELATIVE = '.dz/cmd-usage.jsonl';
@@ -153,6 +154,12 @@ interface RuleUsage {
   readonly stats: ReadonlyMap<string, CmdUsageStat>;
   readonly skipped: number;
   readonly outOfRange: number;
+  /**
+   * Audit rows inside the window that recorded which rules they EVALUATED. Zero means this report
+   * has no evidence about rules at all — which is a different answer from "the rule is unused", and
+   * the distinction is the whole point of counting it (backlog 1bee49dd).
+   */
+  readonly evaluationRows: number;
 }
 
 const REPO_BOUNDARY_IO = {
@@ -401,9 +408,13 @@ export function loadDeadwoodAllowlist(json: string): DeadwoodAllowlistEntry[] {
 function parseGuardAuditUsage(text: string, weeks: number, now: Date): RuleUsage {
   const auditTimestamps: string[] = [];
   const hits: CmdUsageInvocationRecord[] = [];
+  let evaluationRows = 0;
   let skipped = 0;
   let outOfRange = 0;
   const newestAllowed = now.getTime() + DEADWOOD_FUTURE_TOLERANCE_MS;
+  // Same window arithmetic `foldCmdUsage` uses, so "counted as evidence" and "counted as a run"
+  // cannot disagree about which rows are inside.
+  const windowStart = now.getTime() - Math.max(0, weeks) * 7 * DAY_MS;
   for (const line of text.split('\n')) {
     if (line.trim() === '') continue;
     let row: Record<string, unknown>;
@@ -425,17 +436,40 @@ function parseGuardAuditUsage(text: string, weeks: number, now: Date): RuleUsage
       continue;
     }
     auditTimestamps.push(row.ts);
+    // A rule's HEALTHY state is silence, so firing cannot measure whether it is alive. `evaluated`
+    // records the rules that actually got their turn; rows written before the field existed carry
+    // none, and they contribute evidence about firing only.
+    //
+    // Two conditions, both named by cross-family review (Codex gpt-5.6-sol, 2026-09-21), both of
+    // which turn this evidence into a false accusation if skipped:
+    //  · the row must be INSIDE the window. An instrumented row older than `now - weeks` yields no
+    //    in-window runs, so counting it as evidence would let one ancient row flip every absent
+    //    rule from "cannot judge" to "dead".
+    //  · the array must carry a USABLE id. `evaluated: []` is a row that recorded nothing; treating
+    //    it as evidence is the same false accusation by a shorter path.
+    const evaluatedIds = new Set<string>();
+    if (Array.isArray(row.evaluated)) {
+      for (const value of row.evaluated) {
+        if (typeof value === 'string' && value.trim() !== '') evaluatedIds.add(value);
+      }
+    }
+    if (evaluatedIds.size > 0 && tsMs >= windowStart) evaluationRows += 1;
+    for (const id of evaluatedIds) {
+      hits.push({ kind: 'cmd', cmd: id, ts: row.ts, v: CMD_USAGE_SCHEMA });
+    }
     const violations = Array.isArray(row.violations) ? row.violations : [];
     for (const value of violations) {
       const rule = typeof value === 'object' && value !== null
         ? (value as { rule?: unknown }).rule
         : undefined;
-      if (typeof rule === 'string' && rule.trim() !== '') {
+      // One guard run is ONE run. A rule that both evaluated and fired in the same row would be
+      // counted twice — 100 warning evaluations reported as 200 runs (same review, second finding).
+      if (typeof rule === 'string' && rule.trim() !== '' && !evaluatedIds.has(rule)) {
         hits.push({ kind: 'cmd', cmd: rule, ts: row.ts, v: CMD_USAGE_SCHEMA });
       }
     }
   }
-  return { auditTimestamps, stats: foldCmdUsage(hits, weeks, now), skipped, outOfRange };
+  return { auditTimestamps, stats: foldCmdUsage(hits, weeks, now), skipped, outOfRange, evaluationRows };
 }
 
 function timestampDepthDays(timestamps: readonly string[], now: Date): number {
@@ -607,6 +641,23 @@ export function buildDeadwoodReport(input: DeadwoodInput): DeadwoodReport {
       });
       continue;
     }
+    // A rule the window has no EVALUATION evidence for is unjudged, not unused. Firing is the wrong
+    // signal for a guard (silence is its healthy state), so without `evaluated` rows the only honest
+    // answer is "this report cannot judge the rule" — exactly what the skill surface already says.
+    if (item.kind === 'rule' && rules.evaluationRows === 0
+      && (rules.stats.get(item.surface)?.runsInWindow ?? 0) === 0
+      // An explicit allowlist entry is an operator's standing statement about this surface; it keeps
+      // its own wording. Only the ACCUSING path — "zero usage, consider deprecating" — is withdrawn.
+      && !allowlist.has(allowlistKey(item.kind, item.surface))) {
+      noInstrumentation.push({
+        state: 'no-instrumentation',
+        surface: item.surface,
+        kind: item.kind,
+        reason: 'no guard-audit row in this window recorded which rules it evaluated; a rule that '
+          + 'never fires may be a healthy safety net, so firing alone cannot judge it',
+      });
+      continue;
+    }
     classifyInstrumented(
       { surface: item.surface, kind: item.kind },
       item.kind === 'command'
@@ -726,15 +777,15 @@ function compactedText(records: readonly CmdUsageRecord[]): string {
  *
  * The named lock protects competing compactors. Emitters deliberately stay
  * lock-free; this advisory log accepts a possible racing row rather than making
- * every command wait on a lock. Every error is swallowed so compaction can never
- * turn `dz deadwood` into a gate.
+ * every command wait on a lock. An absent store is a no-op; other failures,
+ * including lock timeouts, propagate to the caller.
  */
 export function compactCmdUsageIfNeeded(root: string): void {
   try {
     const resolvedRoot = resolveCmdUsageRoot(root);
     const path = join(resolvedRoot, CMD_USAGE_LOG_RELATIVE);
     if (!existsSync(path) || statSync(path).size <= CMD_USAGE_LOG_MAX_BYTES) return;
-    withNamedLockSync(resolvedRoot, 'cmd-usage', () => {
+    withProjectLockSync(resolvedRoot, 'cmd-usage', () => {
       if (!existsSync(path) || statSync(path).size <= CMD_USAGE_LOG_MAX_BYTES) return;
       const parsed = parseCmdUsageLines(readFileSync(path, 'utf8'), new Date());
       // Preserve a recent raw tail for accurate window counts and fold only the older prefix.
@@ -745,7 +796,7 @@ export function compactCmdUsageIfNeeded(root: string): void {
       writeFileSync(tmp, text, { encoding: 'utf8', mode: 0o600 });
       renameSync(tmp, path);
     });
-  } catch {
-    /* advisory compaction is fail-open just like the writer and report */
+  } catch (err) {
+    if (!(err instanceof StoreAbsentError)) throw err;
   }
 }

package/src/codex-hooks-assets.ts

@@ -12,11 +12,12 @@
  * |----------------|-----------------------------------------------------|------------------------------------------|
  * | Polarity       | mode-driven on POLICY (default `warn` ⇒ exit 0)      | **never-block, always**                  |
  * | Keys on        | presence of `tool_input.command` (AM-8)              | `payload.prompt`                          |
- * | Activation     | nearest `.dz` walking up from `payload.cwd` (AM-25)  | same                                      |
+ * | Activation     | nearest `.dz` from `payload.cwd`, bounded by the repo and HOME (AM-25) | same                         |
  * | Our own failure| exit 0, silent, note to `helper-errors.jsonl`        | exit 0, empty stdout, no write (AM-9)     |
  *
  * `.git` is **not** an activation marker (AM-25): a user-global hook that treats "any git checkout"
  * as opted-in reaches every repository on the machine, including trees nobody pointed at dz.
+ * It only stops the walk at the repository boundary; HOME is never returned or climbed past.
  *
  * The self-failure note goes to `$CODEX_HOME/dz-hooks/helper-errors.jsonl` (AM-33), never into a
  * project — writing it into `<project>/.dz/` would CREATE a `.dz/` in a foreign repo, which is the
@@ -121,15 +122,27 @@ function readPayload() {
 
 /**
  * Walk UP from cwd to the nearest directory containing a \`.dz\` DIRECTORY.
- * \`.git\` is deliberately not a marker (AM-25). No root => the helper is inert.
+ * HOME is never returned or climbed past. Check \`.dz\` before the repository boundary.
+ * \`.git\` only stops the walk, never activates (AM-25). No root => the helper is inert.
  */
 function findProjectRoot(startDir) {
   try {
     let dir = path.resolve(startDir);
+    let home = null;
+    // Step-8 HIGH (find-project-root-boundary): compare RESOLVED paths — a trailing slash in HOME (\`/root/\`)
+    // would otherwise never equal the walked \`dir\` and the home store would activate as a project root.
+    try { home = path.resolve(process.env.HOME || require('node:os').homedir()); } catch (err) { note('find-root', err); }
     for (let i = 0; i < 64; i += 1) {
+      if (dir === home) return null;
       try {
         if (fs.statSync(path.join(dir, '.dz')).isDirectory()) return dir;
       } catch (_) { /* not here; keep walking */ }
+      try {
+        const git = path.join(dir, '.git');
+        const marker = fs.lstatSync(git);
+        if (marker.isDirectory() && fs.lstatSync(path.join(git, 'HEAD')).isFile()) return null;
+        if (marker.isFile() && fs.readFileSync(git, 'utf8').startsWith('gitdir:')) return null;
+      } catch (_) { /* no readable boundary; keep walking */ }
       const parent = path.dirname(dir);
       if (parent === dir) return null;
       dir = parent;