@dzhechkov/harness-core 0.8.29 → 0.8.31

package/src/round.ts

@@ -0,0 +1,228 @@
+/**
+ * A focused work round. The module owns decisions only: callers inject observed state, time,
+ * lesson ids, ledger writing/reading and pid liveness. In particular, this file never imports a
+ * filesystem or process API; the CLI owns `.dz/rounds/` and the witnessed ledger writer.
+ */
+
+const ROUND_OUTCOMES = ['shipped', 'refuted', 'blocked', 'abandoned'] as const;
+type RoundOutcome = typeof ROUND_OUTCOMES[number];
+
+export interface RoundState {
+  readonly slug: string;
+  readonly round: number;
+  readonly topic: string;
+  readonly startedAt: string;
+  readonly pid: number;
+  readonly ownerKind: 'explicit' | 'parent' | 'exec' | 'run';
+  readonly ownerRun?: string;
+  readonly run?: string;
+  readonly recalled: readonly string[];
+  readonly execs?: readonly RoundExecState[];
+}
+
+export interface RoundExecState {
+  readonly startedAt: string;
+  readonly endedAt: string;
+  readonly exitCode: number | null;
+  readonly outcome: import('./round-exec.js').RoundExecOutcome;
+  readonly tokens: number | null;
+}
+
+/** Additive row shape accepted by the existing run-cost ledger readers. */
+export interface RoundLedgerRow {
+  readonly slug: string;
+  readonly stage: 'round';
+  readonly tier: null;
+  readonly coder: string | null;
+  readonly reviewer: string | null;
+  readonly lead: null;
+  readonly minutes: number | null;
+  readonly agents: number | null;
+  readonly tokens: number | null;
+  readonly grade: null;
+  readonly outcome: RoundOutcome;
+  readonly reason: string | null;
+  readonly round: number;
+  readonly lessons: readonly string[];
+  readonly noNewKnowledge: string | null;
+  readonly note: string;
+  readonly date: null;
+  readonly costIn?: 'stages';
+  /** round-state-lock (lead edit after Codex re-review): identity of the state instance this row
+   * closes — lets a retried `close` detect its own earlier row regardless of the clock. */
+  readonly stateId?: string;
+}
+
+type RoundRefusal = { readonly ok: false; readonly exit: 1 | 2; readonly reason: string };
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function validSlug(value: string): boolean {
+  return /^[a-z0-9][a-z0-9._-]*$/i.test(value);
+}
+
+function validCount(value: number | undefined): boolean {
+  return value === undefined || (Number.isInteger(value) && value >= 0);
+}
+
+export function openRound(input: {
+  readonly slug: string;
+  readonly round: number;
+  readonly topic: string;
+  readonly startedAt: string;
+  readonly ownerPid: number;
+  readonly ownerKind: 'explicit' | 'parent' | 'run';
+  readonly ownerRun?: string | undefined;
+  readonly run?: string | undefined;
+  readonly recalled: readonly string[];
+  readonly existing: RoundState | null;
+  readonly force: boolean;
+  readonly existingOwnerAlive: boolean | null;
+  readonly isRunAlive: (runId: string) => boolean | null;
+}): { readonly ok: true; readonly state: RoundState; readonly archiveExisting: boolean } | RoundRefusal {
+  if (!validSlug(input.slug) || !Number.isInteger(input.round) || input.round < 1 || !nonEmpty(input.topic)) {
+    return { ok: false, exit: 2, reason: 'нужны безопасный --slug, положительный --round и непустой --topic' };
+  }
+  const runOwner = input.ownerKind === 'run';
+  if (!Number.isFinite(Date.parse(input.startedAt)) || !Number.isInteger(input.ownerPid)
+    || (runOwner ? input.ownerPid !== 0 || !nonEmpty(input.ownerRun) : input.ownerPid < 1)
+    || (!runOwner && input.ownerKind !== 'explicit' && input.ownerKind !== 'parent')) {
+    return { ok: false, exit: 2, reason: 'время начала или pid круга недопустимы' };
+  }
+  const state: RoundState = {
+    slug: input.slug,
+    round: input.round,
+    topic: input.topic.trim(),
+    startedAt: input.startedAt,
+    pid: input.ownerPid,
+    ownerKind: input.ownerKind,
+    ...(runOwner ? { ownerRun: input.ownerRun!.trim() } : {}),
+    ...(nonEmpty(input.run) ? { run: input.run.trim() } : {}),
+    recalled: [...input.recalled],
+  };
+  let existingOwnerAlive = input.existingOwnerAlive;
+  if (input.existing?.ownerKind === 'run' && input.force) {
+    try { existingOwnerAlive = nonEmpty(input.existing.ownerRun) ? input.isRunAlive(input.existing.ownerRun) : null; }
+    catch { existingOwnerAlive = null; }
+  }
+  if (input.existing !== null && input.force && existingOwnerAlive === false) {
+    return { ok: true, archiveExisting: true, state };
+  }
+  if (input.existing !== null && input.force) {
+    return {
+      ok: false,
+      exit: 1,
+      reason: input.existing.ownerKind === 'run'
+        ? `круг открыт живым прогоном ${input.existing.ownerRun ?? 'unknown'}, --force не перезаписывает живой круг`
+        : `круг открыт живым процессом ${input.existing.pid}, --force не перезаписывает живой круг`,
+    };
+  }
+  if (input.existing !== null) return { ok: false, exit: 1, reason: 'круг уже открыт' };
+  return { ok: true, archiveExisting: false, state };
+}
+
+export function closeRound(input: {
+  readonly state: RoundState;
+  readonly outcome: string;
+  readonly reason?: string | undefined;
+  readonly lessons?: readonly string[];
+  readonly noNewKnowledge?: string | undefined;
+  readonly tokens?: number | undefined;
+  readonly agents?: number | undefined;
+  readonly coder?: string | undefined;
+  readonly reviewer?: string | undefined;
+  readonly note?: string | undefined;
+  readonly noCost?: boolean | undefined;
+  readonly closedAt: string;
+  readonly knownLessonIds: readonly string[];
+  readonly stateId?: string | undefined;
+}, io: {
+  readonly writeLedger: (row: RoundLedgerRow) => unknown;
+  readonly readLedgerTail: () => string;
+}): { readonly ok: true; readonly row: RoundLedgerRow; readonly marker: string } | RoundRefusal {
+  if (!(ROUND_OUTCOMES as readonly string[]).includes(input.outcome)) {
+    return { ok: false, exit: 2, reason: '--outcome: shipped | refuted | blocked | abandoned' };
+  }
+  if (!validCount(input.tokens) || !validCount(input.agents)) {
+    return { ok: false, exit: 2, reason: '--tokens и --agents должны быть целыми числами не меньше нуля' };
+  }
+  const lessons = [...new Set(input.lessons ?? [])];
+  const noNewKnowledge = input.noNewKnowledge?.trim() ?? '';
+  if (lessons.length === 0 && noNewKnowledge === '') {
+    return { ok: false, exit: 1, reason: 'урок не назван: передайте --lesson teach:<id> или --no-new-knowledge "<почему>"' };
+  }
+  if (lessons.length > 0 && noNewKnowledge !== '') {
+    return { ok: false, exit: 1, reason: '--lesson и --no-new-knowledge взаимоисключающие' };
+  }
+  const known = new Set(input.knownLessonIds);
+  const missing = lessons.find((id) => !/^teach:[a-z0-9]+$/i.test(id) || !known.has(id));
+  if (missing !== undefined) return { ok: false, exit: 1, reason: `урок не найден: ${missing}` };
+
+  const startedMs = Date.parse(input.state.startedAt);
+  const closedMs = Date.parse(input.closedAt);
+  if (!Number.isFinite(startedMs) || !Number.isFinite(closedMs) || closedMs < startedMs) {
+    return { ok: false, exit: 1, reason: 'длительность круга не установлена: время состояния недопустимо' };
+  }
+  const compactTs = new Date(closedMs).toISOString().replace(/[-:.]/g, '');
+  const marker = `round-${input.state.slug}-${input.state.round}-${compactTs}`;
+  const note = input.note?.trim() ?? '';
+  const row: RoundLedgerRow = {
+    slug: input.state.slug,
+    stage: 'round',
+    tier: null,
+    coder: nonEmpty(input.coder) ? input.coder.trim() : null,
+    reviewer: nonEmpty(input.reviewer) ? input.reviewer.trim() : null,
+    lead: null,
+    minutes: input.noCost === true ? null : Math.floor((closedMs - startedMs) / 60_000),
+    agents: input.noCost === true ? null : input.agents ?? null,
+    tokens: input.noCost === true ? null : input.tokens ?? null,
+    grade: null,
+    outcome: input.outcome as RoundOutcome,
+    reason: nonEmpty(input.reason) ? input.reason.trim() : null,
+    round: input.state.round,
+    lessons,
+    noNewKnowledge: noNewKnowledge === '' ? null : noNewKnowledge,
+    note: note === '' ? marker : `${marker} | ${note}`,
+    date: null,
+    ...(input.noCost === true ? { costIn: 'stages' as const } : {}),
+    ...(nonEmpty(input.stateId) ? { stateId: input.stateId } : {}),
+  };
+
+  try {
+    io.writeLedger(row);
+  } catch {
+    return { ok: false, exit: 1, reason: 'строка не найдена — круг НЕ закрыт (писатель отказал)' };
+  }
+  let tail = '';
+  try { tail = io.readLedgerTail(); } catch { /* unreadable is absence of a receipt */ }
+  if (!tail.includes(marker)) {
+    return { ok: false, exit: 1, reason: 'строка не найдена — круг НЕ закрыт' };
+  }
+  return { ok: true, row, marker };
+}
+
+export function listRounds(states: readonly RoundState[], input: {
+  readonly now: number;
+  readonly olderThanMinutes: number;
+  readonly isPidAlive: (pid: number) => boolean | null;
+  readonly isRunAlive: (runId: string) => boolean | null;
+}): Array<{ readonly state: RoundState; readonly ageMinutes: number; readonly pidAlive: boolean | null }> {
+  if (!Number.isFinite(input.now) || !Number.isFinite(input.olderThanMinutes) || input.olderThanMinutes < 0) return [];
+  const rows: Array<{ state: RoundState; ageMinutes: number; pidAlive: boolean | null }> = [];
+  for (const state of states) {
+    const startedMs = Date.parse(state.startedAt);
+    if (!Number.isFinite(startedMs)) continue;
+    const ageMinutes = Math.max(0, Math.floor((input.now - startedMs) / 60_000));
+    if (ageMinutes <= input.olderThanMinutes) continue;
+    let pidAlive: boolean | null = null;
+    try {
+      pidAlive = state.ownerKind === 'run'
+        ? input.isRunAlive(state.ownerRun ?? '')
+        : input.isPidAlive(state.pid);
+    } catch { /* an unavailable probe is unknown */ }
+    rows.push({ state, ageMinutes, pidAlive });
+  }
+  return rows.sort((a, b) => b.ageMinutes - a.ageMinutes || a.state.slug.localeCompare(b.state.slug) || a.state.round - b.state.round);
+}

package/src/run-records.ts

@@ -114,6 +114,14 @@ export function decideRecordWrite(input: {
   targetHasPair?: boolean;
   /** Stamped INTO the object before serialising — never rewritten in the shell afterwards (FR-7). */
   timestamp?: string | null;
+  /**
+   * ledger-stage-minutes FR-2/FR-3: the `ts` of the LAST ledger row that shares this row's `runId`,
+   * found by the CALLER (the CLI reads the file; this function stays pure). Absent/null means "no
+   * such row, or it had no `ts`" — both collapse to the same honest `unavailable`, never a guess.
+   */
+  previousRowTs?: string | null;
+  /** The runId this row WILL carry after write-time resolution, when the payload itself has none. */
+  effectiveRunId?: string | null;
   /** Who ran it. Supplied by the CALLER, which lives outside the workflow sandbox and can see the
    *  host; absent stays absent (see the stamping comment below). */
   runnerId?: string | null;
@@ -174,13 +182,12 @@ export function decideRecordWrite(input: {
   // inside an already-serialised document — text surgery on a structured value, and the exact place
   // a payload containing that literal token could corrupt itself.
   const stamped: Record<string, unknown> = { ...obj };
+  const isGap = (v: unknown): boolean => v === null || v === undefined || (typeof v === 'string' && v.trim() === '');
   if (input.timestamp != null && input.timestamp !== '') {
     // An EMPTY STRING is a gap, not a value. Stamping only over null/undefined let
     // `"date":""` through as `written` (cross-family review, 2026-08-21) — a row that looks recorded
     // and carries no date.
-    const isGap = (v: unknown): boolean => v === null || v === undefined || (typeof v === 'string' && v.trim() === '');
     if (kind === 'ledger' && isGap(stamped['date'])) stamped['date'] = input.timestamp.slice(0, 10);
-    if (kind === 'training-pair' && isGap(stamped['ts'])) stamped['ts'] = input.timestamp;
   }
 
   // WHO ran this. Stamped HERE and nowhere else, for a structural reason: the workflow lives in a
@@ -194,10 +201,78 @@ export function decideRecordWrite(input: {
   // because a fabricated identity is worse than a missing one for anything that later joins on it.
   // A blank supplied id is a gap too: `'   '` sneaking in as a value would join later as a distinct
   // runner made of spaces — the same class of harm as inventing 'unknown'.
+  //
+  // Stamped BEFORE `ts` below (fix-round-1/AM-n, cross-family review B): a runnerId this call itself
+  // adds is still an ESTABLISHED field, from the runnerId feature that shipped before
+  // ledger-stage-minutes — NFR-1's "new fields land after everything else" is a promise about the
+  // fields THIS feature introduces (`ts`, `minutesSincePrev`, `minutesSource`), not about the order
+  // decideRecordWrite happens to run its own blocks in. The original order stamped `ts` first, so a
+  // freshly-added runnerId landed AFTER it — an object key order a `--full-qe-extended` Codex review
+  // (grade B) caught by diffing `Object.keys` against the documented convention.
   if (kind === 'ledger' && isRunnerGap(stamped['runnerId']) && !isRunnerGap(input.runnerId)) {
     stamped['runnerId'] = (input.runnerId as string).trim();
   }
 
+  if (input.timestamp != null && input.timestamp !== '') {
+    // FR-1 (ledger-stage-minutes): every ledger row also gets the FULL ISO instant it was recorded,
+    // next to `date` — `date` alone cannot answer "how long between two rows of this run", `ts` can.
+    //
+    // fix-round-1/AM-n (cross-family review B): `ts` is ALWAYS the instant of THIS write, never a
+    // value the payload happened to bring in — the delta below measures from `ts`, and a caller-
+    // supplied instant (stale, forged, or simply wrong) would silently become "now" for that
+    // measurement. The original `isGap` check let a non-empty payload `ts` survive untouched, which
+    // is exactly the value a clock-skewed or replayed payload could poison. No data is discarded: a
+    // real payload `ts` is kept, renamed to `payloadTs`, so the row still says what the caller claimed
+    // — just not under the name the delta trusts.
+    if (kind === 'ledger') {
+      const payloadTs = stamped['ts'];
+      // Lead edit after re-review (Codex B): never clobber a `payloadTs` the caller already carries,
+      // and re-insert `ts` so it lands LAST even when the payload brought its own `ts` key
+      // (assigning an existing property keeps its old insertion position).
+      if (!isGap(payloadTs) && isGap(stamped['payloadTs'])) stamped['payloadTs'] = payloadTs;
+      delete stamped['ts'];
+      stamped['ts'] = input.timestamp;
+    }
+    if (kind === 'training-pair' && isGap(stamped['ts'])) stamped['ts'] = input.timestamp;
+  }
+
+  // FR-2 (ledger-stage-minutes): the writer cannot measure a stage's full duration — the workflow
+  // sandbox has no clock (`Date.now()` is banned there for resume-safety) — but it DOES know the
+  // moment of every write and the run each write belongs to. For an `auto:true` row that carries a
+  // `runId`, the gap since the PREVIOUS row of the same run is a real, partial measurement, and it
+  // gets its own named field and source rather than being folded into (or mistaken for) `minutes`
+  // — "a claim exactly as strong as its inputs" (lesson, repeated 2026-08-25/2026-09-12): a partial
+  // quantity is reported as itself, tagged with where it came from, never smuggled into a field that
+  // implies the whole. `minutes` is left untouched by this block — it stays whatever the payload
+  // already carried (null for every auto row today).
+  if (kind === 'ledger') {
+    const runIdVal = stamped['runId'];
+    // Lead edit after re-review (Codex B): the pipeline's own rows carry NO runId in the payload —
+    // the CLI resolves it at write time (`resolved-at-write`) — so the caller may hand the resolved
+    // id in as `effectiveRunId`; the delta is measurable for those rows too.
+    const effectiveRunId = typeof input.effectiveRunId === 'string' && input.effectiveRunId.trim() !== '' ? input.effectiveRunId : null;
+    const hasRunId = (typeof runIdVal === 'string' && runIdVal.trim() !== '') || effectiveRunId !== null;
+    if (stamped['auto'] === true && hasRunId) {
+      const nowTs = typeof stamped['ts'] === 'string' && stamped['ts'].trim() !== '' ? stamped['ts'] : null;
+      const prevTs = typeof input.previousRowTs === 'string' && input.previousRowTs.trim() !== '' ? input.previousRowTs : null;
+      let minutesSincePrev: number | null = null;
+      let minutesSource: 'ledger-ts-delta' | 'unavailable' = 'unavailable';
+      if (nowTs !== null && prevTs !== null) {
+        const nowMs = Date.parse(nowTs);
+        const prevMs = Date.parse(prevTs);
+        // Absence of a receipt is not success: an unparseable timestamp or a previous row that is
+        // somehow LATER than this one (clock skew, out-of-order backfill) must not be reported as a
+        // measured value — it stays `unavailable`, never a fabricated or negative minute count.
+        if (Number.isFinite(nowMs) && Number.isFinite(prevMs) && nowMs >= prevMs) {
+          minutesSincePrev = Math.round(((nowMs - prevMs) / 60000) * 10) / 10;
+          minutesSource = 'ledger-ts-delta';
+        }
+      }
+      stamped['minutesSincePrev'] = minutesSincePrev;
+      stamped['minutesSource'] = minutesSource;
+    }
+  }
+
   let line: string;
   try {
     line = JSON.stringify(stamped);

package/src/setup.ts

@@ -17,7 +17,7 @@
  */
 
 import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
 import { execSync, spawnSync } from 'node:child_process';
 
 import { mergeManagedHookEntries } from './managed-hooks.js';
@@ -29,6 +29,17 @@ import {
   isDzManagedHookBody,
 } from './claude-hooks-assets.js';
 import { applyIntegrationFragments, IntegrationApplyError } from './integration-apply.js';
+import { harnessCoreDistDir } from './harness-core-location.js';
+import { ensureAgentdbSchema } from './agentdb-index.js';
+import {
+  APPLY_LEG_VERSION,
+  applyLegHookEntries,
+  applyLegVersionOf,
+  bakedCoreDistDirOf,
+  embedDaemonSource,
+  recallHookSource,
+  hookCommandInvokes,
+} from './apply-leg.js';
 
 /** Memory backend type. */
 export type MemoryBackend = 'jsonl' | 'agentdb';
@@ -45,6 +56,14 @@ export interface SetupOptions {
   readonly force?: boolean | undefined;
   /** Also deploy the operating-instructions "driver" skill + agent docs. */
   readonly installDriver?: boolean | undefined;
+  /**
+   * Absolute directory holding the BUILT harness-core modules, baked into the generated apply-leg
+   * hooks as the first resolve candidate (ADR-001 Decision 2, feature `setup-installs-apply-leg`).
+   * The CLI computes this from ITS OWN `@dzhechkov/harness-core` resolution (the installation
+   * actually running `dz setup`); when core's own `runSetup` is called without it (e.g. a direct
+   * programmatic call, or a test), it falls back to resolving ITSELF via {@link harnessCoreDistDir}.
+   */
+  readonly coreDistDir?: string | undefined;
 }
 
 /** Setup result. */
@@ -384,8 +403,13 @@ export function generateHooksConfig(projectRoot: string, backend: MemoryBackend)
   // Use a RELATIVE path (Claude Code runs hooks from the project root): interpolating the absolute
   // ${dzDir} into a single-quoted JS literal inside shell double-quotes breaks on Windows backslash
   // paths (\U, \b…) and on any path containing a quote. `.dz/sessions.jsonl` sidesteps all of it.
+  // AM-5 (dz-harness-hub issue #10 defect 5): `mkdirSync('.dz',{recursive:true})` FIRST —
+  // `appendFileSync` throws ENOENT when `.dz/` has been removed (a fresh checkout with `.dz`
+  // gitignored, or a user who deleted it) or when custom `settings.json` runs hooks from a cwd
+  // where the directory was never created; `mkdirSync` with `recursive:true` is a no-op when the
+  // directory already exists, so this is free on the common path.
   const jsonlCmd = (event: 'start' | 'end' | 'precompact'): string =>
-    `node -e "const fs=require('fs');const d=new Date().toISOString();fs.appendFileSync('.dz/sessions.jsonl',JSON.stringify({event:'${event}',ts:d,backend:'jsonl'})+'\\n')"`;
+    `node -e "const fs=require('fs');fs.mkdirSync('.dz',{recursive:true});const d=new Date().toISOString();fs.appendFileSync('.dz/sessions.jsonl',JSON.stringify({event:'${event}',ts:d,backend:'jsonl'})+'\\n')"`;
   // Matcher-less PreCompact mirrors the agentdb backend so long-session bookkeeping stays reliable
   // even without a vector store (jsonl has no consolidator — this is just an honest marker row).
   return JSON.stringify({
@@ -485,7 +509,14 @@ function installAgentdbLocally(projectRoot: string): boolean {
     // 'pipe') avoids execSync's 1 MB maxBuffer aborting the child on npm's verbose output.
     // --save-exact: agentdb is alpha; a semver range would let a later `npm update` drift the
     // local copy away from the version the MCP registration pins (audit gap G7).
-    execSync('npm install agentdb better-sqlite3 --save-exact --no-audit --no-fund --loglevel=error', {
+    //
+    // better-sqlite3@^11 (AM-2, dz-harness-hub issue #10 defect 1, MEASURED Node 20.20.2 with no
+    // `make` on PATH): an unpinned `npm install better-sqlite3` resolved 12.11.1, which ships no
+    // prebuilt binary for Node 20's ABI 115 — the install fell through to a node-gyp source build
+    // and failed on a machine with no C toolchain. `agentdb` itself requests `^11.8.1`, which DOES
+    // publish an ABI-115 prebuild, so pinning the range here costs nothing agentdb wasn't already
+    // going to resolve to, and buys a working install on a bare Node 20/22 host.
+    execSync('npm install agentdb better-sqlite3@^11 --save-exact --no-audit --no-fund --loglevel=error', {
       cwd: projectRoot,
       stdio: 'ignore',
       timeout: 300000,
@@ -623,6 +654,158 @@ function installDriverDocs(projectRoot: string, force: boolean): string {
   return parts.join('; ') || 'no changes';
 }
 
+/**
+ * Install the apply-leg (recall hook + embed daemon) — ADR-001 Decision 1, feature
+ * `setup-installs-apply-leg`. The third self-learning leg (COLLECT/RANK are Steps 4/2 of
+ * `runSetup`; APPLY is this one) lived only as hand-committed files in this hub's OWN
+ * `.claude/helpers/` — a consumer's `dz setup --memory agentdb` wrote session hooks and a memory
+ * store but never a `UserPromptSubmit` recall hook at all (00_complexity_assessment.md, MEASURED
+ * 2026-09-12).
+ *
+ * WHY THIS RUNS ITS WORK BEFORE "Configure hooks", even though the STEP is reported after it
+ * (`runSetup` calls this first, then pushes the returned step once "Configure hooks" has run).
+ * "Configure hooks" owns SessionStart too (the session-hook writer's own entry) via
+ * `mergeManagedHookEntries`'s drop-its-own-managed-entries/reappend-at-tail algorithm — a call that
+ * is perfectly stable in isolation, but which REORDERS a genuinely foreign SessionStart entry
+ * relative to its own the FIRST time one coexists (kept-foreign-entries-in-place, then append fresh
+ * own at the tail — stable only once the foreign entry is already positioned before it). Running
+ * this step's ADDITIVE-ONLY write first establishes that stable [foreign, own] layout on the VERY
+ * FIRST run, so "Configure hooks" never has anything to reorder on any later run — MEASURED: with
+ * the write ordered the other way, a repeat `runSetup` flips `SessionStart`'s two entries back and
+ * forth forever and neither step ever reports `skipped`, breaking the pre-existing
+ * `setup.test.ts` "PreCompact merge is idempotent" contract (FR-6) this feature must not touch.
+ *
+ * ADDITIVE-ONLY, deliberately NOT `mergeManagedHookEntries`: this step never needs to REPLACE a
+ * stale command text (the two commands `applyLegHookEntries()` emits do not change without an
+ * `APPLY_LEG_VERSION` bump, and a version bump is about the FILE content, not the hook command) —
+ * it only needs "is our command already referenced under this event, anywhere, in any position?".
+ * That question is order-independent, so it can never itself be a source of reordering, and it is
+ * exactly what keeps "Configure hooks" stable once the first run has established the layout above.
+ */
+function applyLegStepResult(opts: SetupOptions, backend: MemoryBackend): SetupStep {
+  if (opts.noHooks) return { name: 'Install apply-leg', status: 'skipped', detail: '--no-hooks' };
+  if (backend !== 'agentdb') {
+    return {
+      name: 'Install apply-leg',
+      status: 'skipped',
+      detail: "apply-leg needs --memory agentdb (embed daemon requires agentdb's transformers)",
+    };
+  }
+  try {
+    const coreDistDir = opts.coreDistDir ?? harnessCoreDistDir();
+    // Re-review Codex (B) finding: the hub's own portable `null` marker must survive an ordinary
+    // `dz setup` run INSIDE the hub — when harness-core resolves to a path inside THIS project's
+    // `packages/@dzhechkov/harness-core`, the checkout is the monorepo itself and the helper is
+    // baked portable (`null` → runtime `<project>/packages/...` candidate), never an absolute path
+    // that would dirty the committed twin and break the twins test in any other clone.
+    const monorepoCoreDist = join(opts.projectRoot, 'packages', '@dzhechkov', 'harness-core', 'dist');
+    const relToMonorepo = relative(monorepoCoreDist, coreDistDir);
+    const insideMonorepo = relToMonorepo === '' || (!relToMonorepo.startsWith('..') && !isAbsolute(relToMonorepo));
+    const bakeTarget: string | null = insideMonorepo ? null : coreDistDir;
+    const helpersDir = join(opts.projectRoot, '.claude', 'helpers');
+    const recallHookPath = join(helpersDir, 'recall-hook.cjs');
+    const embedDaemonPath = join(helpersDir, 'dz-embed-daemon.mjs');
+    const settingsPath = join(opts.projectRoot, '.claude', 'settings.json');
+
+    const deployedRecallContent = existsSync(recallHookPath) ? readFileSync(recallHookPath, 'utf-8') : undefined;
+    const deployedEmbedContent = existsSync(embedDaemonPath) ? readFileSync(embedDaemonPath, 'utf-8') : undefined;
+    const deployedRecallVersion = deployedRecallContent !== undefined ? applyLegVersionOf(deployedRecallContent) : -1;
+    const deployedEmbedVersion = deployedEmbedContent !== undefined ? applyLegVersionOf(deployedEmbedContent) : -1;
+    // MEDIUM finding "переезд ядра" (fix round 1): a version-only staleness check misses the case
+    // where npm/nvm RELOCATED the installed harness-core without any template change — the deployed
+    // file still stamps the current APPLY_LEG_VERSION, but its baked `CORE_DIST_DIR` now points at a
+    // path that no longer exists, and `loadCoreModule` degrades to permanent silence rather than an
+    // error nothing else would ever surface. Comparing the BAKED path against the CURRENT one closes
+    // that gap independently of the version stamp.
+    const deployedCoreDistDir = deployedRecallContent !== undefined ? bakedCoreDistDirOf(deployedRecallContent) : undefined;
+    // Re-review Codex (B) finding: a path-staleness rewrite must never DOWNGRADE a helper that a
+    // newer CLI already deployed — only a file at or below the current version is ours to rewrite.
+    const recallDistDirStale = deployedRecallContent !== undefined
+      && deployedRecallVersion <= APPLY_LEG_VERSION
+      && deployedCoreDistDir !== bakeTarget;
+    let wroteHelpers = false;
+    if (deployedRecallVersion === -1 || opts.force || deployedRecallVersion < APPLY_LEG_VERSION || recallDistDirStale) {
+      mkdirSync(helpersDir, { recursive: true });
+      writeFileSync(recallHookPath, recallHookSource(bakeTarget), { mode: 0o755 });
+      wroteHelpers = true;
+    }
+    if (deployedEmbedVersion === -1 || opts.force || deployedEmbedVersion < APPLY_LEG_VERSION) {
+      mkdirSync(helpersDir, { recursive: true });
+      writeFileSync(embedDaemonPath, embedDaemonSource(), { mode: 0o755 });
+      wroteHelpers = true;
+    }
+
+    // ADD-IF-MISSING, per event: FR-2's literal contract — "ours is added only if no command of
+    // the event already contains OUR entry". Never removes or reorders an existing entry (foreign
+    // OR our own) — see the WHY above for why that matters here.
+    //
+    // MEDIUM finding "совпадение подстроки в чужой команде" (fix round 1): the substring probe used
+    // to be the bare filename (`recall-hook.cjs`), so a foreign command that merely MENTIONS the
+    // filename (e.g. `echo recall-hook.cjs`) was indistinguishable from our own entry and silently
+    // blocked ours from ever being added. "Ours is already present" now means either an EXACT match
+    // of the command we would emit, or the command containing our full relative PATH
+    // (`.claude/helpers/<file>`, the same marker `applyLegStatus` structurally looks for) — a bare
+    // filename mention under any other wrapper text no longer counts.
+    const entries = applyLegHookEntries();
+    const existingSettings = existsSync(settingsPath)
+      ? (JSON.parse(readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>)
+      : {};
+    const hooks = { ...((existingSettings['hooks'] ?? {}) as Record<string, unknown[]>) };
+    let hooksAdded = false;
+    const addIfMissing = (event: string, ownCommand: string, markerPath: string, entry: unknown): void => {
+      const current = Array.isArray(hooks[event]) ? hooks[event] : [];
+      const alreadyPresent = current.some((e) =>
+        commandsOf(e).some((cmd) => cmd === ownCommand || hookCommandInvokes(cmd, markerPath)),
+      );
+      if (alreadyPresent) return;
+      hooks[event] = [...current, entry];
+      hooksAdded = true;
+    };
+    addIfMissing(
+      'UserPromptSubmit',
+      entries.userPromptSubmit.hooks[0]?.command ?? '',
+      '.claude/helpers/recall-hook.cjs',
+      entries.userPromptSubmit,
+    );
+    addIfMissing(
+      'SessionStart',
+      entries.sessionStart.hooks[0]?.command ?? '',
+      '.claude/helpers/dz-embed-daemon.mjs',
+      entries.sessionStart,
+    );
+    if (hooksAdded) {
+      existingSettings['hooks'] = hooks;
+      mkdirSync(dirname(settingsPath), { recursive: true });
+      writeFileSync(settingsPath, JSON.stringify(existingSettings, null, 2));
+    }
+
+    // AM-4 (dz-harness-hub issue #10 defect 4): create the empty AgentDB-schema store now, so a
+    // lesson taught before the first session's SessionEnd/PreCompact writer has ever run still has
+    // somewhere to mirror into — see `ensureAgentdbSchema`'s own doc for the full mechanism. Never
+    // touches an EXISTING store (never re-opens a populated db on every routine re-run); "creates a
+    // store" is a claim about a store that did not exist.
+    const dbPath = join(opts.projectRoot, '.dz', 'agentdb.db');
+    let schemaDetail = '';
+    if (!existsSync(dbPath)) {
+      const schemaResult = ensureAgentdbSchema(opts.projectRoot);
+      schemaDetail = schemaResult.ok ? '; empty agentdb.db created' : `; agentdb.db NOT created (${schemaResult.error ?? 'unknown error'})`;
+    }
+
+    const changed = wroteHelpers || hooksAdded;
+    return {
+      name: 'Install apply-leg',
+      status: changed ? 'done' : 'skipped',
+      detail: (changed ? `Apply-leg: installed v${APPLY_LEG_VERSION}` : `Apply-leg: current (v${APPLY_LEG_VERSION})`) + schemaDetail,
+    };
+  } catch (err) {
+    return {
+      name: 'Install apply-leg',
+      status: 'error',
+      detail: `could not install apply-leg: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
 export function runSetup(opts: SetupOptions): SetupResult {
   const steps: SetupStep[] = [];
   const dzDir = join(opts.projectRoot, '.dz');
@@ -712,6 +895,13 @@ export function runSetup(opts: SetupOptions): SetupResult {
     }
   }
 
+  // Step 4.6: Install apply-leg — the WORK happens here (before "Configure hooks" writes
+  // SessionStart), so a foreign SessionStart entry is already in place before that step's own
+  // merge ever sees it; see `applyLegStepResult`'s doc for why order matters. The STEP is reported
+  // further down, after "Configure hooks" pushes its own, so the printed order still reads as
+  // "collect → rank → apply".
+  const applyLegStep = applyLegStepResult(opts, backend);
+
   // Step 5: Configure hooks (write to .claude/settings.json) — EVENT-LEVEL merge (gap G2):
   // dz-generated entries (recognized by signature, incl. the broken legacy `agentdb add` hooks
   // this feature fixes) are replaced in place WITHOUT --force; the user's own hooks and every
@@ -897,6 +1087,11 @@ export function runSetup(opts: SetupOptions): SetupResult {
     steps.push({ name: 'Configure hooks', status: 'skipped', detail: '--no-hooks' });
   }
 
+  // Step 5.6: Install apply-leg — report pushed AFTER "Configure hooks" below (for a report order
+  // that reads naturally), but see `applyLegStepResult()` above `runSetup` for why the WRITE itself
+  // happens BEFORE it.
+  steps.push(applyLegStep);
+
   // Step 5.5: Register agentdb MCP through the SAME ownership-aware transaction used by `dz init`.
   // `.mcp.json` is the project-scope carrier Claude Code actually loads. A known historical dz
   // agentdb shape is adopted; an ambiguous hand-authored entry is preserved and named as an error.