@dzhechkov/harness-cli 0.8.15 → 0.8.17

package/src/cli.ts

@@ -17,6 +17,8 @@ import { createHash, randomBytes } from 'node:crypto';
 import { homedir, hostname, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
 import { isDeepStrictEqual } from 'node:util';
+import { JOURNAL_KINDS, formatLine, parseLine, selectWindow, appendWitnessed, type JournalKind, type JournalIo } from '@dzhechkov/harness-core';
+import { appendRunEvent, readRunRegistry, liveParents, liveness, probePid, settleDeadRuns, planRegistryArchive, planWorktreeCleanup, renderCleanupPlan, worktreeRemovalsToApply, type WorktreeFact, type RunEvent } from '@dzhechkov/harness-core';
 
 import {
   createSkill,
@@ -204,6 +206,7 @@ import {
   checkSwarmBrief,
   visibleText,
   loadStoreRecords,
+  findExactLesson,
   recordToPattern,
   bundleSkills,
   brainHome,
@@ -537,6 +540,7 @@ import {
   amendmentsMissingFromPlan,
   AMENDMENT_VACUITY_NOTE,
   extractContractChecklist,
+  readFeatureTier,
   parseContractVerdictReport,
   verifyContractVerdicts,
   decideSignableSet,
@@ -629,12 +633,15 @@ export const DZ_COMMANDS: readonly string[] = [
   'retro', 'feature-adr-setup', 'challenge', 'discrimination-check',
   'mutation-gate', 'delivery-check', 'skills-verify', 'compounding', 'deadwood',
   'epoch-replay', 'score', 'recap', 'cadence', 'qe-rounds', 'restart-advisor', 'tg-post',
-  'name-check', 'brief-check', 'provenance-check', 'feature-adr-record', 'amendment-check', 'contract-check',
+  'name-check', 'brief-check', 'provenance-check', 'journal', 'feature-adr-record', 'runs', 'runs-record', 'runs-clean', 'amendment-check', 'contract-check',
   'feature-adr-checkpoint', 'profile', 'reqe', 'qe-bridge', 'backlog', 'routing',
   'bto-optimize', 'dashboard', 'roam', 'import-ecc', 'chain',
 ];
 
 const USAGE = `dz - DZ cross-platform harness CLI
+  dz runs [--settle] [--stall-minutes N] [--json] [--project <dir>] [--probe-pid <pid>]   (run registry: live, stalled, orphaned, inconclusive or finished; PID probe prints true|false|unknown)
+  dz runs-record --event started|heartbeat|finished [--run-id <id>] [--kind <kind>] [--slug <slug>] [--pid <pid|host>] [--parent-run-id <id>] [--outcome <outcome>] [--reason <text>] [--project <dir>] [--json]   (append run event; started can allocate a run ID; host resolves the Claude ancestor PID)
+  dz runs-clean [--apply] [--retention-days N] [--project <dir>] [--json]   (plan cleanup of old clean merged worktrees and completed/dead registry events; apply explicitly)
 
 Usage:
   dz init   --target <name> [--skills-dir <dir>] [--project <dir>] [--preset <name>] [--select id,id,...] [--force] [--enrich] [--allow-integrations <sha256:digest>] [--no-integrations] [--no-hooks] [--no-verify]   (integration manifests require exact digest consent; --no-integrations = explicit skills-only)
@@ -689,6 +696,7 @@ Usage:
   dz sbom [--pack <name>] [--out <file>]   (CycloneDX software bill of materials for the workspace, or for one pack with --pack)
   dz amendment-check --slug <slug> | --feature-dir <dir> | --all [--json]   (the deterministic Step-8 amendment gate: every AM-N / AM-CP-N row must resolve to a test found INSIDE the file the row names (the challenge-panel prefix is part of the id: AM-CP-1 is never AM-1); the PLAN is authoritative when it carries rows, and an ideation amendment the plan drops is a failure. exit 0 pass/skip, 1 fail, 3 NOT-ESTABLISHED — a section that parsed ZERO rows is never a pass, UNLESS the plan explicitly declares \"None\"/\"нет\", which is an answer and reports skip. --all is a CENSUS and always exits 0. Does NOT prove non-vacuity — that is dz discrimination-check)
   dz contract-check --slug <s> [--json]   (read-only retrospective feature contract gate: extracts canonical AC-N + ADR Confirmation items, requires one artifact-anchored met|unmet|not-testable verdict per CC-N, and rejects A/B with unmet. exit 0 pass / 1 readable contract or verdict violation / 2 invalid invocation or unreadable/not-established artifacts)
+  dz journal add --kind decision|verdict|run|error|block "<text>" [--ref <trace>] [--at <ISO>] [--quote <file>] [--commit-quote]; dz journal show [--day|--week] [--at <date>] [--kind <kind>] [--json]   (UTC day files, witnessed append; quotes stay local unless explicitly staged)
   dz feature-adr-record --kind ledger|training-pair --stage <s> [--slug <s>] [--row|--pair <json>] [--mark <n>] [--once] [--json]   (the witnessed writer for the run-cost ledger and training pairs: the payload arrives as an ARGUMENT, never as shell; a malformed or wrong-kind payload is REFUSED before any write; the timestamp is stamped before serialising; the append is verified by re-reading the tail. exit 0 written|duplicate|skipped, 2 refused, 3 not-verified — a record failure is never blocking)
   dz feature-adr-checkpoint (--slug <feature> | --feature-dir <abs>) --stage <s> --input-hash <h> --result <json> [--artifact a,b] [--json]   (record a pipeline stage ONLY after measuring its artifacts on disk; refuses a null result, an absent artifact, or a stage that declares none — the subagent runs a COMMAND instead of hand-writing durable state)
   dz profile [init|show|set|sync] [--json]   (WHO the assistant is talking to — per-user store at ~/.dz/profile.json (0600, NEVER in a project), delivered as a marked block in ~/.claude/CLAUDE.md so it loads in EVERY project, dz installed or not. init = five questions (language, register, deep/weak domains as comma lists — "networking (CCIE; NSX)" keeps the parenthetical as the note, Enter skips — teaches y/n with one re-ask, never a silent default); show ALWAYS prints the store path + age + drift verdict + the rendered block; set register|language|teaches <v> or set deep|weak add|rm <tag> [note] — register accepts the owner's own words (профи / профи лайт / просто), an unknown value is REFUSED naming the accepted set; sync re-writes the block (runs automatically after init/set; foreign content byte-for-byte, timestamped backup before every modifying write). The register changes FORM, never FACTS, and governs dialogue only — never ADRs/commits/QE reports; both rules are baked into the rendered block at every level. exit 0 done / 1 no profile or failed / 2 refused input)
@@ -730,7 +738,7 @@ Usage:
   dz brain init  [--project <dir>] [--k <N>]                           (wire the grounding hook into .claude/settings.json — opt-in)
   dz statusline [--json] [--install] [--project <dir>]                 (live self-learning panel for Claude Code's status bar; reads the CC JSON payload from STDIN)
   dz store-guard [--status|--reset] [--yes] [--project <dir>]          (show the monotonic external high-water mark; --reset is the only lowering path and requires confirmation or --yes)
-  dz statusline --fa-record --slug <s> --step "<label>" [--kind <feature-adr|loop>] [--tier <S|M|L|XL>] [--recalled <n>] [--stored <n>] [--mode <m>]   (feature-adr: record live per-run learning state + phase → 📐 SECOND-LINE phase panel; a plain "Step <n>" label that goes BACKWARDS against a slot younger than 90 min is absorbed as a stale duplicate — prefix the label with ⛔ or ⏸ to record a legitimate regression)
+  dz statusline --fa-record --slug <s> --step "<label>" [--kind <feature-adr|loop>] [--tier <S|M|L|XL>] [--run-id <id>] [--recalled <n>] [--stored <n>] [--mode <m>]   (feature-adr: record live per-run learning state + phase → 📐 SECOND-LINE phase panel; the monotone guard absorbs a backwards plain "Step <n>" only within the same non-empty run id, while an absent/empty id retains legacy fresh-slot behavior — prefix the label with ⛔ or ⏸ to record a legitimate regression)
   dz usage [--json] [--project <dir>] | dz usage --calibrate --session <pct> --weekly <pct> [--model fable=<pct>] [--project <dir>]  (ESTIMATE Claude usage from fixed reset windows; optional per-model weekly binding; exit 0 ALWAYS; pct=null when limits unconfigured)
   dz usage --by-stage [--run <runId> | --slug <slug>] [--epsilon <0..1>] [--write <file.jsonl>] [--json]   (per-stage cost ledger for ONE feature-adr run + the reconciliation invariant: accounted + unaccounted = run total; verdict BALANCED | DEFECT | INSUFFICIENT_DATA; local transcript ESTIMATES — catches ATTRIBUTION errors, not pricing errors)
   dz chain [--project <dir>] [--json]   (verify EVERY hash-chained journal in ONE command: coverage is DERIVED from the CHAINED_JOURNALS registry, never typed, so a journal cannot be given a chain and checked by nobody. An ABSENT journal is NAMED absent, never omitted — omission and cleanliness are indistinguishable in a report. Statuses: ok | healed (defects the current unbroken run has outlived — verdicts over present records are sound) | unchained (present, no chained record yet — legal) | absent | broken | unreadable. Exit 1 on broken/unreadable: a verifier that reports damage and exits 0 is one no automation can act on)
@@ -840,6 +848,8 @@ export interface CliIo {
   readonly installRunner?: (command: string, cwd: string) => void;
   /** Fault seam for proving mutation-gate catches and retries thrown runner internals. */
   readonly mutationGateRunner?: MutationGateRunner;
+  /** Read-back fault seam; production uses the real filesystem. */
+  readonly journalIo?: JournalIo;
 }
 
 /** Injected subprocess runner used by `dz release` (see {@link CliIo.releaseRunner}). */
@@ -2730,12 +2740,14 @@ function cmdStatuslineFaRecord(options: Map<string, string>, cwd: string, write:
   }
 
   const mode = options.get('mode');
+  const runId = options.get('run-id')?.trim();
   const projectRoot = resolve(cwd, options.get('project') ?? '.');
   const outcome = writeFeatureAdrStateDetailed(projectRoot, {
     kind: kindRaw, slug, step, recalled, stored,
     ...(reinforced > 0 ? { reinforced } : {}),
     ...(mode !== undefined && mode.trim() !== '' ? { mode: mode.trim() } : {}),
     ...(tier !== undefined ? { tier } : {}),
+    ...(runId !== undefined && runId !== '' ? { runId } : {}),
   });
   const state = outcome.state;
 
@@ -2955,23 +2967,32 @@ function cmdStatusline(
       return 0;
     }
 
+    // ТЕКСТ ПАНЕЛИ — ПО-АНГЛИЙСКИ по просьбе владельца 2026-09-09: строка статуса узкая,
+    // английские слова в ней короче русских при той же ясности. Комментарии остаются русскими.
     const breakdown = data.patternBreakdown;
     let line = breakdown === undefined
       ? `🎓 dz: ${data.patterns} patterns`
-      : `🎓 dz: ${data.patterns} (${breakdown.active} актив${breakdown.quarantined > 0
-        ? ` · ${breakdown.quarantined} карантин${breakdown.attention ? ' ⚠' : ''}`
-        : ''})${breakdown.tierDelta !== undefined ? ` ⚠ тиры Δ${breakdown.tierDelta}` : ''}`;
+      : `🎓 dz: ${data.patterns} (${breakdown.active} active${breakdown.quarantined > 0
+        ? ` · ${breakdown.quarantined} quarantined${breakdown.attention ? ' ⚠' : ''}`
+        : ''})${breakdown.tierDelta !== undefined ? ` ⚠ tiers Δ${breakdown.tierDelta}` : ''}`;
+    // Показатель зеркала печатается и здесь: `dz statusline` — та же панель, и показатель,
+    // живущий только во вспомогательном скрипте, для этой поверхности просто не существовал.
+    if (data.patternMirror?.state === 'unavailable') line += ' (mirror unreadable ⚠)';
+    else if (data.patternMirror?.state === 'different') line += ` (mirror ${data.patternMirror.vector} ⚠)`;
     if (data.storeHealth?.verdict === 'collapsed') {
-      line += ` ⛔ ОБВАЛ: было ${data.storeHealth.previousMax ?? '?'} · dz store-guard --reset`;
+      line += ` ⛔ COLLAPSE: was ${data.storeHealth.previousMax ?? '?'} · dz store-guard --reset`;
     } else if (data.storeHealth?.verdict === 'cold-start-over-existing') {
-      line += ` ⛔ СТОР ПУСТ: было ${data.storeHealth.previousMax ?? '?'} · восстановить из снимков ${data.storeHealth.snapshotPath ?? ''}`.trimEnd();
+      line += ` ⛔ STORE EMPTY: was ${data.storeHealth.previousMax ?? '?'} · restore from snapshots ${data.storeHealth.snapshotPath ?? ''}`.trimEnd();
     } else if (data.storeHealth?.verdict === 'unreadable') {
-      line += ` ⛔ СТОР НЕЧИТАЕМ${data.storeHealth.unreadableFiles !== undefined && data.storeHealth.unreadableFiles.length > 0
+      line += ` ⛔ STORE UNREADABLE${data.storeHealth.unreadableFiles !== undefined && data.storeHealth.unreadableFiles.length > 0
         ? `: ${data.storeHealth.unreadableFiles.join(', ')}` : ''}`;
     } else if (data.storeHealth?.verdict === 'source-changed') {
-      line += ' ⚠ смена источника хранения';
+      line += ' ⚠ store source changed';
     }
-    line += `${data.usedPatterns !== undefined ? ` · ${data.usedPatterns} used` : ''} · 🧠 ${data.brainSources} sources`;
+    // Рядом с числом источников — объём каждого через «/» (просьба владельца 2026-09-09):
+    // четыре источника по 300 единиц и четыре по три — разные корпуса, а число одно и то же.
+    const ku = data.brainKuCounts.length > 0 ? ` (${data.brainKuCounts.join('/')})` : '';
+    line += `${data.usedPatterns !== undefined ? ` · ${data.usedPatterns} used` : ''} · 🧠 ${data.brainSources} sources${ku}`;
     const branch = statuslineGitBranch(projectRoot);
     if (branch !== undefined) line += ` · ⎇ ${branch}`;
     if (data.consolidatedAgeH !== undefined) line += ` · ⟳ ${data.consolidatedAgeH}h`;
@@ -3893,9 +3914,15 @@ async function runTeachGuardReinforcement(
   projectRoot: string,
   dzId: string,
   reward: number,
+  preserveQuarantine = false,
 ): Promise<{ readonly flushed: number }> {
   const backend = resolveLearningBackend(projectRoot);
-  backend.addSample({ dzId, kind: 'reinforce', reward, ts: new Date().toISOString() });
+  backend.addSample({
+    dzId,
+    kind: preserveQuarantine ? 'recall-hit' : 'reinforce',
+    reward,
+    ts: new Date().toISOString(),
+  });
   return backend.train();
 }
 
@@ -3903,7 +3930,7 @@ async function cmdTeach(
   options: Map<string, string>, flags: Set<string>, cwd: string, write: Write,
   writeErr: WriteErr = (line) => { console.error(line); }, interactive = false,
   guardRunner: (projectRoot: string, text: string, opts: { readonly reward?: number }) => Promise<TeachGuardResult> = teachGuard,
-  reinforceRunner: (projectRoot: string, dzId: string, reward: number) => Promise<{ readonly flushed: number }> = runTeachGuardReinforcement,
+  reinforceRunner: (projectRoot: string, dzId: string, reward: number, preserveQuarantine?: boolean) => Promise<{ readonly flushed: number }> = runTeachGuardReinforcement,
 ): Promise<number> {
   // WHICH store this lesson belongs to, and WHO decided (teach-chooses-its-store).
   // `--to` → `DZ_LEARN` → `.dz/config.json` learning.teachTo → project. The owner asked for a
@@ -4141,6 +4168,16 @@ async function cmdTeach(
     }
   }
 
+  if (!flags.has('guard')) {
+    const exact = findExactLesson(loadStoreRecords(storeRoot), pattern, domain);
+    if (exact !== null) {
+      await reinforceRunner(storeRoot, exact.id, Math.max(0, Math.min(1, reward)), exact.quarantined);
+      write(`Reinforced existing: ${exact.id} (exact text)${exact.quarantined ? ' [quarantined]' : ''}`);
+      write(`  Total patterns: ${loadStorePatternsSync(storeRoot).length}`);
+      return 0;
+    }
+  }
+
   // Distill pattern into actionable rule (claude-smart inspired)
   // Convert "what happened" into "what to do next time"
   const isRule = pattern.toLowerCase().startsWith('always') || pattern.toLowerCase().startsWith('never') ||
@@ -7090,10 +7127,18 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     // A one-line preview inline; on error the FULL captured npm error prints below (truncating a publish
     // failure to 60 chars is how a release stays undiagnosable — the reason lives past char 60).
     const detail = pkg.error && pkg.status !== 'error' ? ` (${pkg.error.slice(0, 60)})` : '';
-    write(`  ${icon} ${pkg.name.padEnd(35)} ${pkg.oldVersion} → ${pkg.newVersion}  ${pkg.status}${detail}`);
+    const receipt = pkg.status === 'published' && pkg.registryProbes !== undefined
+      ? ` (confirmed by registry after ${pkg.registryProbes} probes)`
+      : '';
+    write(`  ${icon} ${pkg.name.padEnd(35)} ${pkg.oldVersion} → ${pkg.newVersion}  ${pkg.status}${receipt}${detail}`);
     if (pkg.status === 'error' && pkg.error) {
       for (const line of pkg.error.split('\n')) write(`      ${line}`);
     }
+    // The rollback branch cannot tell "publish failed" from "publish landed, registry never answered":
+    // both restore package.json. The operator can — one registry query — so say what to check.
+    if (pkg.status === 'error' && pkg.error?.startsWith('registry did not confirm')) {
+      write(`      ↳ disk bump rolled back; if \`npm view ${pkg.name}@${pkg.newVersion} version\` answers, the publish DID land — re-apply the bump by hand`);
+    }
     // Surface warn-mode findings that did not block the publish.
     if (pkg.claimCheck && pkg.claimCheck.findings > 0 && pkg.status !== 'error') {
       write(`      ⚠ claim-check: ${pkg.claimCheck.findings} finding(s) (${pkg.claimCheck.high} high) in README.md`);
@@ -11548,13 +11593,33 @@ function cmdMutationGate(
   }
 
   let entries: readonly MutationRegistryEntry[] = parsed.registry.entries;
+  let entryResults: readonly MutationEntryResult[] = parsed.entryResults;
   const only = options.get('only');
   if (only !== undefined) {
     const ids = only.split(',').map((s) => s.trim()).filter(Boolean);
-    const known = new Set(entries.map((e) => e.id));
+    const known = new Set([
+      ...entries.map((entry) => entry.id),
+      ...entryResults.map((result) => result.id),
+    ]);
     const unknown = ids.filter((id) => !known.has(id));
     if (unknown.length > 0) return fail(`--only names unknown entry id(s): ${unknown.join(', ')}`);
     entries = entries.filter((e) => ids.includes(e.id));
+    entryResults = entryResults.filter((result) => ids.includes(result.id));
+  }
+
+  if (entries.length === 0) {
+    const scope = only === undefined ? 'registry' : 'selected registry entries';
+    const error = `${scope} has no runnable entries after validation — nothing can be run; the registry is unusable`;
+    const summary = summarizeMutationResults(entryResults);
+    if (json) {
+      write(JSON.stringify({ error, registryPath, results: entryResults, summary, exitCode: 2 }, null, 2));
+    } else {
+      write(`dz mutation-gate: ${error}`);
+      for (const result of entryResults) {
+        write(`  - ${result.id}: ${result.verdict} — ${result.detail}`);
+      }
+    }
+    return 2;
   }
 
   const testCmdRaw = options.get('test-cmd') ?? parsed.registry.testCommand ?? 'npm test';
@@ -11590,7 +11655,7 @@ function cmdMutationGate(
   let gitTop: string | null = null;
   try { gitTop = execSync('git rev-parse --show-toplevel', { cwd: pkgDir, stdio: 'pipe', encoding: 'utf-8' }).trim() || null; } catch { /* not in a git repo */ }
   let copyDir = join(scratchParent, 'pkg');
-  const results: MutationEntryResult[] = [];
+  const results: MutationEntryResult[] = [...entryResults];
   const observations: MutationObservation[] = [];
   const warnings: string[] = [];
   const internalRetries: {
@@ -11723,8 +11788,8 @@ function cmdMutationGate(
         : undefined,
     );
     if (!baseline.ok) {
-      if (json) { write(JSON.stringify({ packageDir: pkgDir, registryPath, testCommand: testCmd, baseline, results: [], internalRetries, exitCode: 1 }, null, 2)); return 1; }
-      write(renderMutationReport([], baseline, pkgDir));
+      if (json) { write(JSON.stringify({ packageDir: pkgDir, registryPath, testCommand: testCmd, baseline, results, internalRetries, exitCode: 1 }, null, 2)); return 1; }
+      write(renderMutationReport(results, baseline, pkgDir));
       return 1;
     }
 
@@ -13639,6 +13704,206 @@ function cmdLedgerBackfill(options: Map<string, string>, flags: Set<string>, cwd
   return 0;
 }
 
+const runRegistryIO = {
+  append: (path: string, line: string): void => withNamedLockSync(dirname(path), 'run-registry-archive', () => appendFileSync(path, line, 'utf8')),
+  read: (path: string): string => readFileSync(path, 'utf8'),
+  mkdir: (dir: string): void => { mkdirSync(dir, { recursive: true }); },
+};
+
+function cmdRuns(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  if (options.has('probe-pid')) {
+    const result = probePid(Number(options.get('probe-pid')));
+    write(result === null ? 'unknown' : String(result));
+    return 0;
+  }
+  const root = resolve(options.get('project') ?? cwd);
+  const minutes = Number(options.get('stall-minutes') ?? 120);
+  if (!Number.isFinite(minutes) || minutes < 0) {
+    write(flags.has('json') ? JSON.stringify({ status: 'refused', reason: 'stall-minutes must be a finite non-negative number' }) : 'stall-minutes must be a finite non-negative number');
+    return 2;
+  }
+  const opts = { stallMs: minutes * 60_000 };
+  let settled: RunEvent[] = [];
+  if (flags.has('settle')) {
+    settled = withNamedLockSync(join(root, '.dz', 'runs'), 'run-registry-archive', () => {
+      const events = settleDeadRuns(readRunRegistry(root, runRegistryIO), Date.now(), probePid);
+      // Already holding the shared archive/append lock across read-plan-append.
+      const unlockedIO = { ...runRegistryIO, append: (path: string, line: string): void => appendFileSync(path, line, 'utf8') };
+      for (const event of events) appendRunEvent(root, event, unlockedIO);
+      return events;
+    });
+    if (!flags.has('json')) {
+      for (const event of settled) write(`settled ${event.runId} — died (${event.reason})`);
+      if (!settled.length) write('nothing to settle');
+    }
+  }
+  const registry = readRunRegistry(root, runRegistryIO);
+  if (registry.status === 'missing') {
+    write(flags.has('json') ? JSON.stringify(registry) : 'нет реестра: .dz/runs/registry.jsonl ещё не создан (ни одного прогона)');
+    return 0;
+  }
+  const now = Date.now();
+  const parents = liveParents(registry, now, probePid, opts);
+  const rows = registry.runs.map((run, i) => {
+    const parent = parents[i]!.liveness;
+    const own = liveness(run, now, probePid, opts);
+    const decision = registry.status !== 'readable' ? parent :
+      run.finished ? { state: 'finished', reason: run.outcome } :
+      parent.state !== 'live' && parent.state !== 'stalled' ? parent : own;
+    return { ...run, state: decision.state, reason: decision.reason,
+      parentLiveness: parent, heartbeatAgeMs: run.heartbeat ? now - Date.parse(run.heartbeat) : null };
+  });
+  if (flags.has('json')) write(JSON.stringify({ ...registry, runs: rows, ...(flags.has('settle') ? { settled } : {}) }));
+  else {
+    if (registry.status !== 'readable') write('inconclusive — ' + registry.reason);
+    write('runId | kind | slug | pid | parent | liveness | heartbeat age');
+    for (const row of rows) write([row.runId, row.kind, row.slug, row.pid, row.parentRunId ?? '—',
+      row.state, row.heartbeatAgeMs === null ? '—' : `${row.heartbeatAgeMs}ms`].join(' | ') + ' — ' + row.reason);
+  }
+  return registry.status === 'readable' ? 0 : 1;
+}
+
+/** Git effects are injected; the core owns eligibility and the explicit apply boundary. */
+export function cmdRunsClean(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write,
+  exec: (command: string, options: { cwd: string; encoding: 'utf8'; stdio: ['ignore', 'pipe', 'pipe'] }) => string | Buffer = execSync): number {
+  const root = resolve(options.get('project') ?? cwd);
+  const json = flags.has('json');
+  const messages: string[] = [];
+  const say = (line: string): void => { messages.push(line); if (!json) write(line); };
+  try {
+    const days = Number(options.get('retention-days') ?? 2);
+    if (!Number.isFinite(days) || days < 0) throw new Error('retention-days must be a finite non-negative number');
+    const now = Date.now(), retentionMs = days * 86400000;
+    const git = (command: string, dir = root): string => String(exec(command, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
+    // Git C-quotes paths containing controls/non-ASCII bytes. Decode octal UTF-8 as well.
+    const unquote = (value: string): string => {
+      if (!value.startsWith('"')) return value;
+      const bytes: number[] = [];
+      const body = value.slice(1, -1);
+      const escapes: Record<string, string> = { a: '\x07', b: '\b', t: '\t', n: '\n', v: '\v', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+      for (let i = 0; i < body.length; i++) {
+        if (body[i] === '\\') {
+          const octal = /^[0-7]{1,3}/.exec(body.slice(i + 1));
+          if (octal) { bytes.push(parseInt(octal[0], 8)); i += octal[0].length; }
+          else { i++; bytes.push(...Buffer.from(escapes[body[i]!] ?? body[i]!)); }
+        } else {
+          const cp = String.fromCodePoint(body.codePointAt(i)!);
+          bytes.push(...Buffer.from(cp)); i += cp.length - 1;
+        }
+      }
+      return Buffer.from(bytes).toString('utf8');
+    };
+    const list = (): Array<{ path: string; branch: string | null; detached: boolean; sha: string }> => {
+      const text = git('git worktree list --porcelain');
+      const trees = text.trimEnd().split(/\n\n+/).filter(Boolean).map(block => {
+        const lines = block.split('\n');
+        const path = lines.find(line => line.startsWith('worktree '))?.slice(9);
+        const sha = lines.find(line => line.startsWith('HEAD '))?.slice(5);
+        if (!path || !sha) throw new Error('unreadable worktree entry: ' + block);
+        return { path: unquote(path), sha,
+          branch: lines.find(line => line.startsWith('branch '))?.slice(7) ?? null,
+          detached: lines.includes('detached') };
+      });
+      if (!trees.length) throw new Error('empty git worktree list');
+      return trees;
+    };
+    const trees = list();
+    const facts: WorktreeFact[] = trees.map((tree, index) => {
+      // Any unreadable status aborts before removal; unknown cleanliness is never clean.
+      const dirtyFiles = git('git status --short --untracked-files=all', tree.path).split('\n').filter(Boolean)
+        .map(line => unquote(line.slice(3)));
+      let merged: boolean | null = null;
+      try { git(`git merge-base --is-ancestor ${shellQuote(tree.branch ?? tree.sha)} main`); merged = true; }
+      catch (error) { if ((error as { status?: number }).status === 1) merged = false; }
+      let lastCommitTs: number | null = null;
+      try {
+        const raw = git('git log -1 --format=%ct', tree.path).trim();
+        if (/^\d+$/.test(raw) && Number.isFinite(Number(raw) * 1000)) lastCommitTs = Number(raw) * 1000;
+      } catch { /* unknown age keeps the worktree */ }
+      return { path: tree.path, branch: tree.branch?.replace(/^refs\/heads\//, '') ?? null,
+        detached: tree.detached, isMain: index === 0 || tree.branch === 'refs/heads/main', merged, dirtyFiles, lastCommitTs };
+    });
+    const plan = planWorktreeCleanup(facts, { now, retentionMs });
+    for (const line of renderCleanupPlan(plan)) say(line);
+    let code = 0;
+    for (const fact of worktreeRemovalsToApply(plan, flags.has('apply'))) {
+      let failure: string | undefined;
+      try { git(`git worktree remove ${shellQuote(fact.path)}`); }
+      catch (error) { failure = String(error); }
+      try {
+        if (!list().some(tree => tree.path === fact.path)) say(`removed ${fact.path} (confirmed)`);
+        else { say(`NOT removed ${fact.path}` + (failure ? ` — ${failure}` : '')); code = 1; }
+      } catch (error) { say(`NOT removed ${fact.path} — confirmation unavailable: ${String(error)}`); code = 1; }
+    }
+    const archiveRegistry = (): { archive: RunEvent[]; keep: RunEvent[] } => {
+      const registry = readRunRegistry(root, runRegistryIO);
+      if (registry.status === 'inconclusive') throw new Error(registry.reason);
+      const archivePlan = planRegistryArchive(registry, { now, retentionMs, probe: probePid });
+      if (flags.has('apply') && archivePlan.archive.length > 0) {
+        const dir = join(root, '.dz', 'runs');
+        const encode = (events: RunEvent[]): string => events.map(ev => JSON.stringify(ev) + '\n').join('');
+        const temp = join(dir, `registry.${randomBytes(8).toString('hex')}.tmp`);
+        try {
+          writeFileSync(temp, encode(archivePlan.keep), { flag: 'wx', mode: 0o600 });
+          appendFileSync(join(dir, 'registry.archive.jsonl'), encode(archivePlan.archive));
+          renameSync(temp, join(dir, 'registry.jsonl'));
+        } finally { if (existsSync(temp)) unlinkSync(temp); }
+      }
+      return archivePlan;
+    };
+    const archive = flags.has('apply')
+      ? withNamedLockSync(join(root, '.dz', 'runs'), 'run-registry-archive', archiveRegistry)
+      : archiveRegistry();
+    say(`${flags.has('apply') ? 'archived' : 'archive'} ${archive.archive.length} registry event(s)`);
+    if (json) write(JSON.stringify({ ...plan, applied: flags.has('apply'), archive, messages, ok: code === 0 }));
+    return code;
+  } catch (error) {
+    const reason = String(error);
+    if (json) write(JSON.stringify({ ok: false, reason, messages }));
+    else write('runs-clean refused: ' + reason);
+    return 1;
+  }
+}
+
+function cmdRunsRecord(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  try {
+    const event = options.get('event') as RunEvent['event'];
+    const runId = options.get('run-id') ?? (event === 'started' ? randomBytes(16).toString('hex') : '');
+    const ev: RunEvent = { event, runId, ts: new Date().toISOString() };
+    if (event === 'started') {
+      const kind = options.get('kind');
+      const slug = options.get('slug');
+      Object.assign(ev, { ...(kind === undefined ? {} : { kind }), ...(slug === undefined ? {} : { slug }) });
+      const rawPid = options.get('pid');
+      if (rawPid === 'host') {
+        // The shell agent is transient. Walk to the nearest Claude host, never guess from age.
+        let candidate = process.ppid;
+        const seen = new Set<number>();
+        while (candidate > 1 && !seen.has(candidate)) {
+          seen.add(candidate);
+          const row = execFileSync('ps', ['-p', String(candidate), '-o', 'ppid=', '-o', 'comm='], { encoding: 'utf8' }).trim();
+          const match = /^(\d+)\s+(.+)$/.exec(row);
+          if (!match) break;
+          if (/^claude(?:$|[- ])/.test(basename(match[2]!))) { ev.pid = candidate; break; }
+          candidate = Number(match[1]);
+        }
+        if (ev.pid === undefined) throw new Error('Claude host PID unavailable; pass explicit --pid (Workflow args.runPid)');
+      } else ev.pid = Number(rawPid);
+      const parentRunId = options.get('parent-run-id');
+      Object.assign(ev, { ...(parentRunId === undefined ? {} : { parentRunId }) });
+    }
+    const outcome = event === 'finished' ? options.get('outcome') : undefined;
+    const reason = options.get('reason');
+    Object.assign(ev, { ...(outcome === undefined ? {} : { outcome }), ...(reason === undefined ? {} : { reason }) });
+    appendRunEvent(resolve(options.get('project') ?? cwd), ev, runRegistryIO);
+    write(flags.has('json') ? JSON.stringify({ status: 'written', ...ev }) : `written ${event} ${runId}`);
+    return 0;
+  } catch (error) {
+    write(flags.has('json') ? JSON.stringify({ status: 'refused', reason: String(error) }) : `refused: ${String(error)}`);
+    return 2;
+  }
+}
+
 function cmdFeatureAdrRecord(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   const json = flags.has('json');
   // `--backfill` is a different verb on the same store: it fills the ledger's null cost fields from
@@ -13765,7 +14030,7 @@ type ContractDiskRead =
 
 type ContractDirectoryRead =
   | { readonly ok: true; readonly realPath: string }
-  | { readonly ok: false; readonly diagnostic: ContractDiagnostic };
+  | { readonly ok: false; readonly reason: 'missing' | 'unreadable'; readonly diagnostic: ContractDiagnostic };
 
 function contractRepoRoot(cwd: string): string {
   let root = cwd;
@@ -13824,14 +14089,26 @@ function contractDirectoryConfined(repoRoot: string, absolute: string, artifact:
   } catch {
     return {
       ok: false,
+      reason: 'unreadable',
       diagnostic: { code: 'repository-unreadable', message: 'repository root cannot be resolved', artifact: '.' },
     };
   }
+  try {
+    lstatSync(absolute);
+  } catch (error) {
+    const missing = (error as NodeJS.ErrnoException).code === 'ENOENT';
+    return {
+      ok: false,
+      reason: missing ? 'missing' : 'unreadable',
+      diagnostic: { code: 'adr-directory-unreadable', message: `required ADR directory cannot be resolved: ${artifact}`, artifact },
+    };
+  }
   try {
     targetReal = realpathSync(absolute);
   } catch {
     return {
       ok: false,
+      reason: 'unreadable',
       diagnostic: { code: 'adr-directory-unreadable', message: `required ADR directory cannot be resolved: ${artifact}`, artifact },
     };
   }
@@ -13839,6 +14116,7 @@ function contractDirectoryConfined(repoRoot: string, absolute: string, artifact:
   if (rel === '' || rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel)) {
     return {
       ok: false,
+      reason: 'unreadable',
       diagnostic: { code: 'artifact-outside-repository', message: `artifact resolves outside the repository: ${artifact}`, artifact },
     };
   }
@@ -13848,6 +14126,7 @@ function contractDirectoryConfined(repoRoot: string, absolute: string, artifact:
   } catch {
     return {
       ok: false,
+      reason: 'unreadable',
       diagnostic: { code: 'adr-directory-unreadable', message: `required ADR directory is not readable: ${artifact}`, artifact },
     };
   }
@@ -13908,34 +14187,64 @@ function cmdContractCheck(
 
   const adrDirRel = `features/${slug}/03_adr`;
   const adrDirectory = contractDirectoryConfined(repoRoot, join(featureDir, '03_adr'), adrDirRel);
-  if (!adrDirectory.ok) return emitEarly('not-established', 2, [adrDirectory.diagnostic]);
-  const adrDir = adrDirectory.realPath;
+  const informationalDiagnostics: ContractDiagnostic[] = [];
   let adrNames: string[];
-  try {
-    adrNames = readdirSync(adrDir, { withFileTypes: true })
-      .filter((entry) => entry.name.endsWith('.md') && (entry.isFile() || entry.isSymbolicLink()))
-      .map((entry) => entry.name)
-      .sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
-  } catch {
-    return emitEarly('not-established', 2, [{
-      code: 'adr-directory-unreadable',
-      message: `required ADR directory cannot be read: ${adrDirRel}`,
-      artifact: adrDirRel,
-    }]);
-  }
-  if (adrNames.length === 0) {
-    return emitEarly('not-established', 2, [{
-      code: 'adr-artifacts-missing',
-      message: `no direct ADR Markdown artifacts exist under ${adrDirRel}`,
-      artifact: adrDirRel,
-      observed: 0,
-    }]);
+  let adrDir: string | null = null;
+  let adrsOptional: true | undefined;
+  if (!adrDirectory.ok) {
+    if (adrDirectory.reason !== 'missing') return emitEarly('not-established', 2, [adrDirectory.diagnostic]);
+    const tier = readFeatureTier((rel) => {
+      const assessment = contractReadConfined(repoRoot, join(repoRoot, rel), rel);
+      return assessment.ok ? assessment.text : null;
+    }, slug);
+    if (tier === 'S') {
+      adrNames = [];
+      adrsOptional = true;
+      informationalDiagnostics.push({
+        code: 'adr-not-required-for-tier',
+        message: 'ADR artifacts are not required for an S-tier feature',
+        artifact: adrDirRel,
+      });
+    } else if (tier !== null) {
+      return emitEarly('not-established', 2, [{
+        code: 'adr-directory-missing',
+        message: `required ADR directory is missing for ${tier}-tier feature: ${adrDirRel}`,
+        artifact: adrDirRel,
+      }]);
+    } else {
+      return emitEarly('not-established', 2, [{
+        ...adrDirectory.diagnostic,
+        message: `${adrDirectory.diagnostic.message}; feature tier is unreadable`,
+      }]);
+    }
+  } else {
+    adrDir = adrDirectory.realPath;
+    try {
+      adrNames = readdirSync(adrDir, { withFileTypes: true })
+        .filter((entry) => entry.name.endsWith('.md') && (entry.isFile() || entry.isSymbolicLink()))
+        .map((entry) => entry.name)
+        .sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+    } catch {
+      return emitEarly('not-established', 2, [{
+        code: 'adr-directory-unreadable',
+        message: `required ADR directory cannot be read: ${adrDirRel}`,
+        artifact: adrDirRel,
+      }]);
+    }
+    if (adrNames.length === 0) {
+      return emitEarly('not-established', 2, [{
+        code: 'adr-artifacts-missing',
+        message: `no direct ADR Markdown artifacts exist under ${adrDirRel}`,
+        artifact: adrDirRel,
+        observed: 0,
+      }]);
+    }
   }
   const adrs: Array<{ path: string; text: string }> = [];
   const adrReadErrors: ContractDiagnostic[] = [];
   for (const name of adrNames) {
     const rel = `features/${slug}/03_adr/${name}`;
-    const read = contractReadConfined(repoRoot, join(adrDir, name), rel);
+    const read = contractReadConfined(repoRoot, join(adrDir!, name), rel);
     if (read.ok) adrs.push({ path: rel, text: read.text });
     else adrReadErrors.push(read.diagnostic);
   }
@@ -13944,6 +14253,7 @@ function cmdContractCheck(
   const extracted = extractContractChecklist({
     requirements: { path: requirementsRel, text: requirementsRead.text },
     adrs,
+    ...(adrsOptional === true ? { adrsOptional: true } : {}),
   });
   if (!extracted.ok) return emitEarly('fail', 1, extracted.diagnostics);
 
@@ -13985,7 +14295,7 @@ function cmdContractCheck(
   });
   const verification = {
     ...rawVerification,
-    diagnostics: rawVerification.diagnostics.map(withReportArtifact),
+    diagnostics: [...informationalDiagnostics, ...rawVerification.diagnostics.map(withReportArtifact)],
     items: rawVerification.items.map((item) => ({
       ...item,
       diagnostics: item.diagnostics.map(withReportArtifact),
@@ -14013,7 +14323,7 @@ function cmdContractCheck(
   for (const entry of verification.diagnostics) writeErr(contractDiagnosticLine(entry));
   const summary = verification.outcome === 'pass'
     ? `${verification.counts.met} contract item(s) met`
-    : `${verification.diagnostics.length} contract or evidence violation(s)`;
+    : `${rawVerification.diagnostics.length} contract or evidence violation(s)`;
   write(`contract-check: ${verification.outcome === 'pass' ? 'PASS' : 'FAIL'} — ${summary}`);
   return verification.exitCode;
 }
@@ -17508,6 +17818,94 @@ async function cmdProfile(options: Map<string, string>, flags: Set<string>, writ
   return fail(2, `dz profile: unknown subcommand ${JSON.stringify(sub)} — accepted: init | show | set | sync`);
 }
 
+function cmdJournal(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write, injectedIo?: JournalIo): number {
+  try {
+    const verb = options.get('_positional_0');
+    if (verb !== 'add' && verb !== 'show') throw new Error('Ожидается journal add или journal show');
+    const kindRaw = options.get('kind');
+    if ((verb === 'add' || kindRaw !== undefined) && !JOURNAL_KINDS.includes(kindRaw as JournalKind)) {
+      write(`Категория должна быть одной из: ${JOURNAL_KINDS.join(', ')}`);
+      return 1;
+    }
+    if (flags.has('day') && flags.has('week')) throw new Error('Выберите --day или --week');
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    const dir = join(root, 'docs', 'journal');
+    // A journal symlink must never redirect an append or a quote outside this repository.
+    for (const path of [join(root, 'docs'), dir, join(dir, 'quotes')]) {
+      if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw new Error(`Символическая ссылка запрещена: ${path}`);
+    }
+    const at = options.get('at') ?? (verb === 'add' ? new Date().toISOString() : new Date().toISOString().slice(0, 10));
+    let date = at;
+    let time = '';
+    if (verb === 'add') {
+      if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(at)) throw new Error('--at ожидает ISO с часовым поясом');
+      selectWindow([], at.slice(0, 10), false);
+      const stamp = new Date(at).toISOString();
+      date = stamp.slice(0, 10); time = stamp.slice(11, 16);
+    }
+    selectWindow([], date, false);
+    if (verb === 'show') {
+      const days = existsSync(dir) ? readdirSync(dir).filter(n => /^\d{4}-\d{2}-\d{2}\.md$/.test(n)).map(n => n.slice(0, 10)) : [];
+      const rows = selectWindow(days, date, flags.has('week')).flatMap(day => {
+        return readFileSync(join(dir, `${day}.md`), 'utf8').split('\n').filter(line => line.startsWith('- '))
+          .map(raw => ({ day, ...parseLine(raw) }));
+      }).filter(row => row.status === 'unparsed' || kindRaw === undefined || row.kind === kindRaw);
+      if (flags.has('json')) write(JSON.stringify(rows));
+      else for (const row of rows) write(row.status === 'unparsed' ? `[unparsed] ${row.raw}` : row.raw);
+      return 0;
+    }
+    const text = options.get('_positional_1') ?? '';
+    let ref = options.get('ref') ?? '';
+    const event = { time, kind: kindRaw as JournalKind, text, ref };
+    formatLine(event); // validate before any journal/quote write
+    if (options.has('_positional_2')) throw new Error('Текст должен быть одним аргументом');
+    if (flags.has('commit-quote') && !options.has('quote')) throw new Error('--commit-quote требует --quote');
+    return withNamedLockSync(root, 'journal', () => {
+      const path = join(dir, `${date}.md`);
+      if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw new Error(`Символическая ссылка запрещена: ${path}`);
+      const previous = existsSync(path) ? readFileSync(path, 'utf8') : '';
+      if (previous.split('\n').map(parseLine).some(row => row.status === 'parsed' && row.time === time && row.text === text.trim())) {
+        write('уже записано'); return 0;
+      }
+      const quote = options.get('quote');
+      if (quote !== undefined) {
+        const content = readFileSync(resolve(cwd, quote), 'utf8');
+        const quotes = join(dir, 'quotes');
+        const exclude = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], { cwd: root, encoding: 'utf8' }).trim();
+        const excludePath = resolve(root, exclude);
+        const ignored = existsSync(excludePath) ? readFileSync(excludePath, 'utf8') : '';
+        if (!ignored.split('\n').includes('/docs/journal/quotes/')) {
+          mkdirSync(dirname(excludePath), { recursive: true });
+          appendFileSync(excludePath, `${ignored.endsWith('\n') || !ignored ? '' : '\n'}/docs/journal/quotes/\n`);
+        }
+        mkdirSync(quotes, { recursive: true });
+        const tracked = new Set(execFileSync('git', ['ls-files', '-z', '--', 'docs/journal/quotes/'], { cwd: root, encoding: 'utf8' }).split('\0'));
+        let n = 1;
+        while (existsSync(join(quotes, `${date}-${n}.md`)) || tracked.has(`docs/journal/quotes/${date}-${n}.md`)) n++;
+        const quoteRef = `docs/journal/quotes/${date}-${n}.md`;
+        const quotePath = join(root, quoteRef);
+        writeFileSync(quotePath, content, { flag: 'wx' });
+        if (readFileSync(quotePath, 'utf8') !== content) throw new Error('Цитата не засвидетельствована');
+        if (flags.has('commit-quote')) {
+          execFileSync('git', ['add', '-f', '--', quoteRef], { cwd: root, stdio: 'pipe' });
+        }
+        ref = ref ? `${ref}; ${quoteRef}` : quoteRef;
+      }
+      mkdirSync(dir, { recursive: true });
+      if (!existsSync(path)) writeFileSync(path, `# Журнал действий — ${date}\n\n## Решения · вердикты · запуски и падения · ошибки · блокировки (UTC)\n\n`, { flag: 'wx' });
+      else if (previous && !previous.endsWith('\n')) appendFileSync(path, '\n');
+      const fs: JournalIo = injectedIo ?? { read: p => readFileSync(p, 'utf8'), append: (p, s) => appendFileSync(p, s) };
+      const line = formatLine({ ...event, ref });
+      appendWitnessed(fs, path, line);
+      write(`записано и засвидетельствовано: ${line}`);
+      return 0;
+    });
+  } catch (error) {
+    write(`dz journal: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+
 export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
   const cwd = io.cwd ?? process.cwd();
   const write: Write = io.write ?? ((line) => { console.log(line); });
@@ -17776,8 +18174,16 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdBriefCheck(options, flags, cwd, write);
       case 'provenance-check':
         return cmdProvenanceCheck(options, flags, cwd, write);
+      case 'journal':
+        return cmdJournal(options, flags, cwd, write, io.journalIo);
       case 'feature-adr-record':
         return cmdFeatureAdrRecord(options, flags, cwd, write);
+      case 'runs':
+        return cmdRuns(options, flags, cwd, write);
+      case 'runs-clean':
+        return cmdRunsClean(options, flags, cwd, write);
+      case 'runs-record':
+        return cmdRunsRecord(options, flags, cwd, write);
       case 'amendment-check':
         return cmdAmendmentCheck(options, flags, cwd, write);
       case 'contract-check':