@dzhechkov/harness-core 0.8.39 → 0.8.40

package/src/operations.ts

@@ -8,7 +8,7 @@
 
 import { execFileSync, spawnSync, type SpawnSyncOptionsWithStringEncoding } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -51,6 +51,7 @@ import { WINDSURF_RULES_ROOT } from '@dzhechkov/adapter-windsurf';
 import { AGENTS_MD_BLOCK_BEGIN, mergeAgentsMd, mergeGeminiMd, mergePolicyBlock, renderAgentsMdSection } from '@dzhechkov/core';
 import type { CanonicalSkill, EmitResult, SkillAsset } from '@dzhechkov/core';
 import { computeRiskScore } from './risk-scoring.js';
+import { checkInstrumentFreshness, checkRankingState } from './doctor-instrument.js';
 
 import { applyEmitResult } from './apply.js';
 import { describeSkillLoadFailure, discoverSkillIds, loadSkillFromDir } from './skills.js';
@@ -1039,6 +1040,12 @@ export function runMigrate(options: { projectRoot: string }): MigrateReport {
 export interface DoctorCheck {
   readonly name: string;
   readonly ok: boolean;
+  /**
+   * Rendering severity for a check that is NOT a failure. `warn` = measured and worth saying out
+   * loud; `unknown` = the evidence could not be gathered, which is never rendered as a pass. Neither
+   * value participates in `DoctorReport.ok`, so neither can change any caller's exit code.
+   */
+  readonly level?: 'warn' | 'unknown';
   readonly detail: string;
 }
 
@@ -1050,7 +1057,13 @@ export interface DoctorReport {
 }
 
 /** Report environment diagnostics for the harness. */
-export async function runDoctor(options: { projectRoot: string }): Promise<DoctorReport> {
+/**
+ * `instrumentPath` is the executable that is answering — normally the CLI's own `process.argv[1]`.
+ * It is an INPUT, not something this module reads for itself: `core-boundary` rule A forbids core
+ * from touching process globals, because core is a library and the process belongs to whoever hosts
+ * it. Omitted ⇒ the instrument-freshness check honestly reports that it could not tell.
+ */
+export async function runDoctor(options: { projectRoot: string; instrumentPath?: string | null }): Promise<DoctorReport> {
   const checks: DoctorCheck[] = [];
   const root = options.projectRoot;
 
@@ -1065,6 +1078,74 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
   // monorepo (or a fork of it) and owes itself these checks; anything else is a consumer project
   // and gets a NAMED skip — a skip, never a silent pass and never a fail.
   const isMonorepo = existsSync(join(root, 'packages', '@dzhechkov'));
+
+  // The executable is part of the measurement. Resolve the CALLER-SUPPLIED path (including its
+  // symlinks), then attribute it to the nearest package.json. Every read is independent and
+  // fail-quiet so a broken install becomes an explicit UNKNOWN diagnostic instead of throwing.
+  let binPath: string | null = null;
+  try {
+    const given = options.instrumentPath;
+    binPath = given === undefined || given === null ? null : realpathSync(given);
+  } catch { /* unresolved is reported by the pure decider */ }
+  let binVersion: string | null = null;
+  if (binPath !== null) {
+    try {
+      let cursor = dirname(binPath);
+      while (true) {
+        const packagePath = join(cursor, 'package.json');
+        if (existsSync(packagePath)) {
+          const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as { version?: unknown };
+          binVersion = typeof parsed.version === 'string' ? parsed.version : null;
+          break;
+        }
+        const parent = dirname(cursor);
+        if (parent === cursor) break;
+        cursor = parent;
+      }
+    } catch { binVersion = null; }
+  }
+  let treeVersion: string | null = null;
+  if (isMonorepo) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(root, 'packages', '@dzhechkov', 'harness-cli', 'package.json'), 'utf8')) as { version?: unknown };
+      treeVersion = typeof parsed.version === 'string' ? parsed.version : null;
+    } catch { treeVersion = null; }
+  }
+  let realRoot = resolvePath(root);
+  let realRootResolved = true;
+  // A root that cannot be resolved through its symlinks makes the containment question undecidable
+  // rather than false — the decider is told so explicitly instead of silently comparing two path
+  // forms that need not agree.
+  try { realRoot = realpathSync(root); } catch { realRootResolved = false; }
+  const instrument = checkInstrumentFreshness({ binPath, binVersion, treeVersion, projectRoot: realRoot, projectRootRealpathed: realRootResolved, isMonorepo });
+  checks.push({
+    name: 'doctor instrument freshness',
+    // The pure decider owns the verdict; this wiring only carries it. Never re-derive `ok` here.
+    ok: true,
+    ...(instrument.level === 'ok' ? {} : { level: instrument.level }),
+    detail: instrument.detail,
+  });
+
+  const rankingStatePath = join(realRoot, '.dz', 'lesson-bandit', 'state.json');
+  let rankingFlagOn = false;
+  try {
+    const parsed = JSON.parse(readFileSync(join(root, '.dz', 'config.json'), 'utf8')) as {
+      memory?: { learning?: { banditRerank?: unknown } };
+    };
+    rankingFlagOn = parsed.memory?.learning?.banditRerank === true;
+  } catch { /* malformed config is owned by the config diagnostic; ranking defaults off */ }
+  const ranking = checkRankingState({
+    flagOn: rankingFlagOn,
+    statePath: rankingStatePath,
+    stateExists: existsSync(rankingStatePath),
+    binPath,
+  });
+  checks.push({
+    name: 'bandit ranking state',
+    ok: true,
+    ...(ranking.level === 'warn' ? { level: 'warn' as const } : {}),
+    detail: ranking.detail,
+  });
   checks.push({
     name: '.claude/skills present',
     ok: existsSync(join(root, '.claude', 'skills')),
@@ -1648,7 +1729,8 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
       const text = readFileSync(p, 'utf-8');
       const v = verifyEventChainText(text);
       if (v.chained === 0 || v.ok) continue;
-      const total = text.split('\n').filter((l) => l.trim() !== '').length;
+      // The verifier already counted non-empty lines; re-deriving it drifts (see cli.ts note).
+      const total = v.lines;
       const age = classifyChainDefects(v, total);
       const named = `${v.defects.length} defect(s): ${v.defects.slice(0, 3).map((d) => `${d.kind}@L${d.line}`).join(', ')}`;
       // A break that an unbroken run has already outlived is not a reason to distrust today's

package/src/registry.ts

@@ -8,7 +8,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync, type Dirent } from 'node:fs';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { stems } from './stem.js';
@@ -188,6 +188,42 @@ export function discoverSkillCarryingDirs(cwd: string): { pack: string; dir: str
  * drop the `unsigned` verdict for a `skills-*` pack that carries no manifest — turning "unsigned" into
  * "absent", which is the same class of silence this fixes.
  */
+/**
+ * Чей это пак: проекта, который проверяют, или самого прибора, который проверяет.
+ *
+ * ИЗМЕРЕНО 2026-09-21 на одном репозитории в одну минуту: `dz` из PATH перечисляет 88 паков и
+ * сообщает «31 verified», сборка из дерева — 57 и «0 verified». Оба ответа ВЕРНЫ и расходятся
+ * ровно на 29 подписанных манифестов внутри глобальной установки: `discoverVerifiablePackDirs`
+ * намеренно дотягивается до упакованных копий самого прибора. Беда не в числе, а в строке, где оно
+ * стоит: «31 verified» рядом с именем проекта читается как охват ПРОЕКТА, хотя проверены копии
+ * инструмента. Разделение считается по пути, потому что только путь и отличает эти два случая.
+ *
+ * Сравнение путей РАЗДЕЛИТЕЛЬНОЕ: `/repo-2/x` не внутри `/repo`. Наивный `startsWith` этот репозиторий
+ * уже однажды отгружал.
+ */
+export function packScope(dir: string, projectRoot: string): 'project' | 'instrument' {
+  const rel = relative(projectRoot, dir);
+  const inside = rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`));
+  return inside ? 'project' : 'instrument';
+}
+
+/**
+ * Уточнение к числу проверенных подписей: сколько из них — паки ЭТОГО проекта, а сколько принадлежат
+ * самому прибору. Возвращает ПУСТУЮ строку, когда уточнять нечего (ничего не проверено либо всё
+ * проверенное — проектное): приписка к нулю была бы шумом, а шум в строке охвата её и обесценивает.
+ */
+export function verifiedScopeNote(
+  checks: readonly { readonly dir: string; readonly verdict: string }[],
+  projectRoot: string,
+): string {
+  const verified = checks.filter((c) => c.verdict === 'verified');
+  if (verified.length === 0) return '';
+  const outside = verified.filter((c) => packScope(c.dir, projectRoot) === 'instrument').length;
+  if (outside === 0) return '';
+  return ` (${verified.length - outside} in this project, ${outside} in the instrument's own install`
+    + " — not this project's artifacts)";
+}
+
 export function discoverVerifiablePackDirs(cwd: string): { pack: string; dir: string }[] {
   const out: { pack: string; dir: string }[] = [];
   // Keyed on the RESOLVED path: a globally-installed `dz` reaches its own bundled packs as well as the
@@ -388,6 +424,60 @@ function categoryFromPack(pack: string): string {
  * `node_modules/@dzhechkov`, **and** the CLI's own install location. This is why
  * `dz registry` works for a globally-installed `dz`, not only inside the monorepo.
  */
+/** One skill as the public showcase page (`marketplace/index.html`) renders it. */
+export interface ShowcaseSkill {
+  readonly id: string;
+  readonly pack: string;
+  readonly description: string;
+  readonly trustTier: number;
+  readonly category: string;
+  /** The exact command a visitor copies. Derived, never stored — one spelling, one place. */
+  readonly install: string;
+}
+
+export interface ShowcaseRegistry {
+  readonly version: string;
+  readonly generated: string;
+  readonly totalSkills: number;
+  readonly totalPacks: number;
+  readonly categories: readonly string[];
+  readonly skills: readonly ShowcaseSkill[];
+}
+
+/**
+ * The public showcase catalogue, projected from the SAME {@link Registry} the plugin manifests come
+ * from — so the page and the manifests can never answer "how many skills are there" differently.
+ *
+ * Why this exists: MEASURED 2026-09-04 and re-measured 2026-09-20, `marketplace/registry.json` said
+ * 57 skills / 10 packs while `buildRegistry` counted 260 / 37, and the file's last commit was
+ * 2026-06-03 — because NOTHING wrote it. A grep for its path across the whole source tree returned
+ * zero writers (backlog 9595b21e). A catalogue with no generator does not go stale slowly; it stops
+ * being true the first time anything ships, and it was the one surface a visitor actually reads.
+ *
+ * `generated` is the caller's to supply: a timestamp minted inside would make the output
+ * non-reproducible and the drift gate unable to compare a fresh build against the published file.
+ */
+export function buildShowcaseRegistry(
+  registry: Registry,
+  opts: { readonly version: string; readonly generated: string },
+): ShowcaseRegistry {
+  return {
+    version: opts.version,
+    generated: opts.generated,
+    totalSkills: registry.totalSkills,
+    totalPacks: registry.totalPacks,
+    categories: [...registry.categories],
+    skills: registry.entries.map((e) => ({
+      id: e.id,
+      pack: e.pack,
+      description: e.description,
+      trustTier: e.trustTier,
+      category: e.category,
+      install: `dz init --target claude-code --select ${e.id}`,
+    })),
+  };
+}
+
 export function buildRegistry(cwd: string): Registry {
   const entries: RegistryEntry[] = [];
   const packs = discoverSkillCarryingDirs(cwd);

package/src/release.ts

@@ -929,6 +929,42 @@ function fencedBlock(text: string, indent = '    '): string[] {
   return [`${indent}${fence}`, ...contentLines, `${indent}${fence}`];
 }
 
+/**
+ * Формы отказа `gh`, означающие «учётные данные не приняты», а не «команда не та».
+ * Список узкий намеренно: широкая сетка превратила бы любой сбой в повод лезть в окружение.
+ */
+const GH_AUTH_FAILURE_SHAPES: readonly RegExp[] = [
+  /no longer valid/i,
+  /bad credentials/i,
+  /authentication failed/i,
+  /requires authentication/i,
+  /gh auth login/i,
+  /HTTP 401/i,
+];
+
+/**
+ * Стоит ли повторить вызов `gh` БЕЗ переменной `GITHUB_TOKEN`.
+ *
+ * ИЗМЕРЕНО 2026-09-21 в этой среде: `gh auth status` → «the github.com token in GITHUB_TOKEN is no
+ * longer valid», а `env -u GITHUB_TOKEN gh auth status` → вход как djd1m через keyring. То есть
+ * мёртвая переменная ЗАТЕНЯЕТ рабочие учётные данные, и всякий вызов `gh` из скрипта падает
+ * (бэклог ead5f8e0). Переменная живёт в окружении tmux-сервера и снимается только владельцем.
+ *
+ * Почему повтор, а не безусловное снятие: в сборочной среде `GITHUB_TOKEN` — ШТАТНЫЙ способ
+ * авторизации, и выбрасывать его всегда значило бы ломать работающее ради сломанного. Поэтому
+ * сначала обычный вызов, и лишь на отказе ИМЕННО по авторизации — одна попытка без переменной.
+ */
+export function shouldRetryGhWithoutToken(input: {
+  readonly exitCode: number;
+  readonly stderr: string;
+  readonly stdout: string;
+  readonly tokenPresent: boolean;
+}): boolean {
+  if (input.exitCode === 0 || !input.tokenPresent) return false;
+  const text = `${input.stderr}\n${input.stdout}`;
+  return GH_AUTH_FAILURE_SHAPES.some((re) => re.test(text));
+}
+
 /**
  * gh-2.4-safe `gh issue create` payload (only `--title`/`--body` are assumed downstream).
  * Pure + deterministic for a fixed verdict — the issue is the verdict's echo, never its judge.

package/src/round-exec.ts

@@ -37,14 +37,25 @@ export function classifyRoundExecOutcome(input: {
   readonly exitCode: number | null;
   readonly timedOut: boolean;
   readonly bytes: number;
+  /** How the run ENDED: the limit/refusal signatures are end-state facts, so they read the tail. */
   readonly tail: string;
+  /**
+   * The WHOLE log, when the caller has it. The turn marker is not an end-state fact — it is the last
+   * `\ncodex\n` ANYWHERE in the log — and a fixed tail window cannot hold it: MEASURED 2026-09-20 on
+   * three real rounds, Codex's final answer ran 12–20 KB (it quotes runner output), so the marker sat
+   * at ~95% of the file and fell outside the caller's 4 KB tail. All three runs had landed their files
+   * and were green, and all three were recorded `failed`. Defaults to `tail` for callers that only
+   * have the window.
+   */
+  readonly fullText?: string;
 }): RoundExecOutcome {
   if (input.timedOut) return 'timeout';
   if (/rate limit|usage limit|limit reached/i.test(input.tail)) return 'session-limit';
   if (/HTTP 400|not supported when using Codex/i.test(input.tail)) return 'model-refused';
   if (input.exitCode === 0 && input.bytes > 0) {
-    const marker = input.tail.lastIndexOf('\ncodex\n');
-    const finalLine = marker < 0 ? '' : input.tail.slice(marker + '\ncodex\n'.length).split(/\r?\n/, 1)[0]?.trim() ?? '';
+    const haystack = input.fullText ?? input.tail;
+    const marker = haystack.lastIndexOf('\ncodex\n');
+    const finalLine = marker < 0 ? '' : haystack.slice(marker + '\ncodex\n'.length).split(/\r?\n/, 1)[0]?.trim() ?? '';
     if (finalLine !== '') return 'done';
   }
   if (input.exitCode === 0 && input.bytes === 0) return 'empty';

package/src/round.ts

@@ -41,9 +41,28 @@ export interface RoundExecState {
 }
 
 /** Additive row shape accepted by the existing run-cost ledger readers. */
+/**
+ * The row this version WRITES. It is deliberately not the shape the FILE holds: the ledger is
+ * append-only, so rows written before a field existed do not carry it. Read a stored line as
+ * `unknown` and put it through {@link validateClosedRoundLedgerRow} or your own guard — typing a
+ * historical line with this interface and dereferencing a later field as a guaranteed string is the
+ * defect this note exists to prevent (named by cross-family review, Codex gpt-5.6-sol, 2026-09-21).
+ */
 export interface RoundLedgerRow {
   readonly slug: string;
   readonly stage: 'round';
+  /**
+   * This round's identity as a FIELD. It is also the first token of `note`, and that prefix is what
+   * the confirmation read greps for — but a key that lives inside prose can only be joined by
+   * parsing prose. MEASURED on the COMMITTED `.dz/feature-adr/run-cost-ledger.jsonl` at `488f596c`
+   * (backlog c60cc857, whose own numbers had gone stale): of 436 rows, 99 are `round`, and the
+   * round's own identity sat in a FIELD 0 times out of 99 while sitting inside `note` prose 99 times
+   * out of 99. Other id fields exist on those rows — 28 carry `taskId`, 76 carry `stateId` — but
+   * they identify the TASK and the STATE FILE, not the round's ledger identity; 22 carry none of
+   * `runId`/`taskId`/`stateId` (those three exactly — `runnerId`, the host, is on all 99).
+   * Reproducer and pinning commit: package README, section `roundId`.
+   */
+  readonly roundId: string;
   readonly tier: null;
   readonly coder: string | null;
   readonly reviewer: string | null;
@@ -552,6 +571,7 @@ export function closeRound(input: {
   const row: RoundLedgerRow = {
     slug: input.state.slug,
     stage: 'round',
+    roundId: marker,
     tier: null,
     coder: nonEmpty(input.coder) ? input.coder.trim() : null,
     reviewer,