@dzhechkov/harness-core 0.8.37 → 0.8.39

package/src/review-cost.ts

@@ -0,0 +1,139 @@
+/**
+ * review-cost-ledger T1/FR-1/A1 (ADR-001 п.1): a pure parser for the qe-bridge reviewer's own cost
+ * receipt — the last non-empty line of the Claude CLI's raw stdout, which (for every observed
+ * signoff) is a JSON object carrying `total_cost_usd`, `usage.*`, `duration_ms`, `num_turns`.
+ *
+ * Deliberately narrow and honest: absence of a price is never silently read as a price of zero.
+ * `status:'absent'` (no non-empty line at all) and `status:'unparseable'` (a line that IS present
+ * but does not parse into a usable cost) are each their own outcome — never collapsed into `ok`, and
+ * never guessed. This module owns no filesystem access (NFR-2): the caller (the cli) reads the
+ * stdout sidecar file and hands its TEXT in here.
+ */
+
+/** The four cost-bearing token components, plus their sum. `tokensPartial` is present (`true`) only
+ *  when at least one component was missing/unusable in the source JSON and was substituted with 0 —
+ *  never silently blended with a genuine zero. */
+export interface QeBridgeCostTokens {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheCreation: number;
+  readonly cacheRead: number;
+  readonly total: number;
+  readonly tokensPartial?: true;
+}
+
+/**
+ * `ok` — a usable price was found. `absent` — no non-empty line to read at all (an empty/whitespace
+ * stdout, or a caller who never had one to offer); `reason` is OPTIONAL here because the parser
+ * itself never has anything more specific to say about a literal absence, but a CALLER (the cli's
+ * `readQeBridgeCostSidecar`, T3) may attach its own known reason to a synthesized `absent` (e.g. "no
+ * qe-bridge signoff for this round") without inventing a THIRD status for that case. `unparseable` —
+ * a non-empty last line existed but did not yield a valid cost (not JSON, not an object, no numeric
+ * `total_cost_usd`, or a negative/NaN one) — `reason` is mandatory here, naming what failed.
+ */
+export type QeBridgeCost =
+  | {
+      readonly status: 'ok';
+      readonly costUsd: number;
+      readonly tokens: QeBridgeCostTokens;
+      readonly durationMs: number | null;
+      readonly numTurns: number | null;
+    }
+  | { readonly status: 'absent'; readonly reason?: string }
+  | { readonly status: 'unparseable'; readonly reason: string };
+
+function finiteNonNegative(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+function finiteNumberOrNull(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** fix-round-1 #6 (Codex r1 HIGH #6): a token COMPONENT is a count, never a measurement — it is only
+ *  ever trustworthy as a nonnegative SAFE integer. `1e308` is `typeof 'number'` and finite, but adding
+ *  four of those silently produces `Infinity` (which then serializes to `null` on the ledger row while
+ *  the in-memory type still claims `number`); a fractional or >2^53 value is likewise not a real token
+ *  count. Distinct from "component ABSENT" (undefined — stays the existing partial-with-zero path). */
+function safeNonNegativeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+/**
+ * `text` is the full raw stdout of a qe-bridge reviewer invocation (Claude CLI, `--output-format
+ * json`-shaped result line). The COST line is always the LAST non-empty line — Claude CLI streams
+ * intermediate events first and finishes with one `type:"result"` object carrying the run's totals.
+ */
+export function parseQeBridgeStdoutCost(text: string): QeBridgeCost {
+  const lines = text.split('\n');
+  let lastLine = '';
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const candidate = lines[i]!.trim();
+    if (candidate !== '') { lastLine = candidate; break; }
+  }
+  if (lastLine === '') return { status: 'absent' };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(lastLine);
+  } catch (error) {
+    return { status: 'unparseable', reason: `last non-empty line is not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { status: 'unparseable', reason: 'last non-empty line did not parse to a JSON object' };
+  }
+  const rec = parsed as Record<string, unknown>;
+  const totalCostUsd = rec['total_cost_usd'];
+  if (!finiteNonNegative(totalCostUsd)) {
+    return {
+      status: 'unparseable',
+      reason: typeof totalCostUsd === 'number'
+        ? `total_cost_usd is not a finite non-negative number: ${totalCostUsd}`
+        : `total_cost_usd field is missing or not a number (got ${JSON.stringify(totalCostUsd)})`,
+    };
+  }
+
+  const usageRaw = rec['usage'];
+  const usage = typeof usageRaw === 'object' && usageRaw !== null && !Array.isArray(usageRaw)
+    ? (usageRaw as Record<string, unknown>)
+    : {};
+  let tokensPartial = false;
+  // fix-round-1 #6: a MISSING component (undefined) is the pre-existing partial-with-zero case
+  // (never touched by this fix); a PRESENT-but-invalid component (adversarial: 1e308, a fraction,
+  // 2^53+1, negative, NaN) is a different failure — the whole result turns `unparseable` rather than
+  // silently zeroing a value that was actually there. `invalidComponent` names which key failed.
+  let invalidComponent: string | null = null;
+  const component = (key: string): number => {
+    const value = usage[key];
+    if (value === undefined) { tokensPartial = true; return 0; }
+    if (safeNonNegativeInteger(value)) return value;
+    invalidComponent = key;
+    return 0;
+  };
+  const input = component('input_tokens');
+  const output = component('output_tokens');
+  const cacheCreation = component('cache_creation_input_tokens');
+  const cacheRead = component('cache_read_input_tokens');
+  if (invalidComponent !== null) {
+    return { status: 'unparseable', reason: `usage.${invalidComponent} is not a nonnegative safe integer: ${JSON.stringify(usage[invalidComponent])}` };
+  }
+  const total = input + output + cacheCreation + cacheRead;
+  if (!Number.isSafeInteger(total)) {
+    return { status: 'unparseable', reason: `token total ${total} exceeds Number.MAX_SAFE_INTEGER — not a trustworthy count` };
+  }
+
+  return {
+    status: 'ok',
+    costUsd: totalCostUsd,
+    tokens: {
+      input,
+      output,
+      cacheCreation,
+      cacheRead,
+      total,
+      ...(tokensPartial ? { tokensPartial: true as const } : {}),
+    },
+    durationMs: finiteNumberOrNull(rec['duration_ms']),
+    numTurns: finiteNumberOrNull(rec['num_turns']),
+  };
+}

package/src/round.ts

@@ -5,6 +5,7 @@
  */
 
 import { validateExperimentEnvelope } from './feature-adr-envelope.js';
+import type { QeBridgeCost } from './review-cost.js';
 
 const ROUND_OUTCOMES = ['shipped', 'refuted', 'blocked', 'abandoned'] as const;
 type RoundOutcome = typeof ROUND_OUTCOMES[number];
@@ -24,6 +25,11 @@ export interface RoundState {
    * unchanged through `round open --envelope` into `closeRound`'s ledger row. Opaque here (never
    * interpreted by round.ts) — validated once, at `openRound`, and trusted from then on. */
   readonly envelope?: unknown;
+  /** experiment-instrument FR-1/FR-3 (ADR-001): minted once at `openRound` — `--task` when given
+   * (validated), else `slug@startedAt`. Optional at the TYPE level, not because a fresh round ever
+   * omits it, but because a state file written before this feature landed has no such key on disk;
+   * `closeRound` derives the same default for that legacy case and names the source (A4/A5). */
+  readonly taskId?: string;
 }
 
 export interface RoundExecState {
@@ -63,11 +69,85 @@ export interface RoundLedgerRow {
    * closes — lets a retried `close` detect its own earlier row regardless of the clock. */
   readonly stateId?: string;
   /** measurement-integrity FR-7: present ONLY when `reviewer` was filled from the qe-bridge sidecar
-   *  (no explicit `--reviewer`) — `elapsedMs / 60000`, rounded to 1 decimal. */
+   *  (no explicit `--reviewer`) — `elapsedMs / 60000`, rounded to 1 decimal. review-cost-ledger
+   *  fix-round-1 #1/#2 (ADR-001 п.2 amended): also present when an EXPLICIT `--reviewer` AGREES with
+   *  the sidecar's own `gradedBy` (`reviewSource:'flag+qe-bridge'` below names that case). */
   readonly reviewMinutes?: number;
   /** measurement-integrity FR-7: present ONLY alongside `reviewMinutes` — names where `reviewer` and
-   *  `reviewMinutes` came from, so a reader never confuses a sidecar-sourced figure for a flag. */
-  readonly reviewSource?: 'qe-bridge';
+   *  `reviewMinutes` came from, so a reader never confuses a sidecar-sourced figure for a flag.
+   *  review-cost-ledger fix-round-1 #1/#2 (ADR-001 п.2 amended): `'qe-bridge'` when `reviewer` was
+   *  FILLED from the sidecar (no `--reviewer` flag); `'flag+qe-bridge'` when an explicit `--reviewer`
+   *  AGREES with the sidecar's own `gradedBy` (case-insensitive `family:model` equality, or a
+   *  family-only flag matching the sidecar's family) — the flag's IDENTITY is confirmed by the
+   *  sidecar, so its price/minutes are attributed too. A DISAGREEING explicit `--reviewer` is refused
+   *  outright (`closeRound` never reaches row-building for that case) — never silently ignored. */
+  readonly reviewSource?: 'qe-bridge' | 'flag+qe-bridge';
+  /** experiment-instrument FR-1/FR-3 (ADR-001): the task identity this round's state carried (or, for
+   *  a legacy state with no `taskId` on disk, the same `slug@startedAt` default `openRound` would have
+   *  minted — always present, never null: a round always has a slug and a startedAt). */
+  readonly taskId?: string;
+  /** experiment-instrument A4/A5: present ONLY when `taskId` above was DERIVED here rather than read
+   *  from the state file — i.e. the state predates this feature. A fresh round never carries this. */
+  readonly taskIdSource?: 'derived-legacy';
+  /** experiment-instrument FR-3/A2: the git sha `dz round close` resolved at close time (cli-only —
+   *  the core never shells out), present only for a FINISHED outcome (`shipped|refuted`). */
+  readonly shipSha?: string | null;
+  /** experiment-instrument FR-3/A2: same timestamp as this row's own close (`closedAt`), present only
+   *  alongside `shipSha` — the anchor "when was this shipped", not a duplicate of `date`. */
+  readonly shippedAt?: string;
+  /** experiment-instrument A2: present only when `shipSha` is `null` for a finished outcome — why the
+   *  sha could not be resolved (e.g. "not a git repository", "git failed: …"). */
+  readonly shipShaReason?: string;
+  /** experiment-instrument r1-5 (Codex r1 HIGH #5, ADR-001 amended): `HEAD` alone does not identify
+   *  what was actually shipped when the worktree carries uncommitted changes — this hub's own tree is
+   *  ALWAYS dirty with unrelated files, so a clean-tree requirement was rejected; instead the row
+   *  names the limit. `true` when `git status --porcelain` was non-empty at close time, `false` when
+   *  empty, present only for a FINISHED outcome, alongside `shipSha`. */
+  readonly shipTreeDirty?: boolean;
+  /** experiment-instrument r1-5: present ONLY when `shipTreeDirty` above could not be determined (the
+   *  `git status --porcelain` probe itself failed) — the same "never a bare unexplained gap" rule
+   *  `shipShaReason` already follows, for the sibling probe. */
+  readonly shipTreeDirtyReason?: string;
+  /** review-cost-ledger FR-2/A2 (ADR-001 п.1-2): the qe-bridge reviewer's OWN price, from the stdout
+   *  sidecar — present only when {@link reviewerCostSource} is `'qe-bridge-stdout'` (a usable price
+   *  was found) or `'unavailable'` (present with the reviewer known but the price is not — `null` in
+   *  that case, never omitted: NFR-4, "nothing is guessed"). */
+  readonly reviewerCostUsd?: number | null;
+  /** review-cost-ledger FR-2/A2: sum of the four token components below, present only alongside a
+   *  successful {@link reviewerCostUsd} (`reviewerCostSource:'qe-bridge-stdout'`). fix-round-1 #5
+   *  (Codex r1 HIGH #5): `null` — never a silently-zeroed sum — when the sidecar's own
+   *  `tokens.tokensPartial` was `true` (at least one component was missing from the source JSON): an
+   *  incomplete sum read as an exact zero is indistinguishable from a genuine zero-token review, which
+   *  is the defect this field exists to avoid. */
+  readonly reviewerTokens?: number | null;
+  /** review-cost-ledger FR-2/A2: the same four components broken out, present only alongside a
+   *  successful {@link reviewerCostUsd}. fix-round-1 #5: `partial:true` when the sidecar's `total`
+   *  above is `null` for the reason described there — the four components themselves are still the
+   *  real (possibly zero-substituted) values, only the aggregate is withheld. */
+  readonly reviewerTokensBreakdown?: {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheCreation: number;
+    readonly cacheRead: number;
+    readonly partial?: true;
+  };
+  /** review-cost-ledger FR-2/A2/A3: `'qe-bridge-stdout'` when {@link reviewerCostUsd} is a real,
+   *  parsed price; `'unavailable'` when a reviewer is known but no usable price could be found (the
+   *  Codex limit, an unreadable/absent/unparseable stdout sidecar, or — fix-round-1 #2 — a sidecar
+   *  price that exists but is NOT tied to this row's reviewer). Present ONLY in the same branch as
+   *  {@link reviewMinutes}/{@link reviewSource} above (`reviewSource` is `'qe-bridge'` or
+   *  `'flag+qe-bridge'`) — WITH two named exceptions, neither of which ever yields an `'ok'` price:
+   *  (a) a Codex reviewer supplied via `--reviewer` with no matching signoff still gets `'unavailable'`
+   *  + a reason naming the limit (ADR-001 п.3/FR-4); (b) an explicit `--reviewer` alongside a sidecar
+   *  that carries a REAL cost record but is NOT tied to it (empty `gradedBy`, i.e. never fills
+   *  `reviewer` and never agrees with it either) also gets `'unavailable'` — fix-round-1 #2 (Codex r1
+   *  CRITICAL #2): an untied sidecar price, even `status:'ok'`, is NEVER attributed to an explicit
+   *  reviewer it was not written for; a DISAGREEING sidecar (real `gradedBy`, does not match the flag)
+   *  is refused outright by `closeRound` before any row is built at all (fix-round-1 #1/BLOCKER). */
+  readonly reviewerCostSource?: 'qe-bridge-stdout' | 'unavailable';
+  /** review-cost-ledger FR-2/A3: present ONLY alongside `reviewerCostSource:'unavailable'` — the
+   *  status text explaining WHY (never a bare unexplained gap, same discipline as `shipShaReason`). */
+  readonly reviewerCostReason?: string;
 }
 
 /**
@@ -94,6 +174,12 @@ export interface RoundReviewSidecar {
   /** measurement-integrity fix-round-1/F9: when this signoff was emitted — the timestamp
    *  `findQeBridgeSignoffForRound` uses to confirm it falls inside THIS round's own interval. */
   readonly emittedAt?: string;
+  /** review-cost-ledger FR-2/T3 (ADR-001 п.1): the reviewer's own price, read by the CALLER (the cli
+   *  — `readQeBridgeCostSidecar`, T3) from the signoff's `rawStdoutFile` and parsed by
+   *  `parseQeBridgeStdoutCost` (T1). `round.ts` never opens a file itself, same discipline as
+   *  `gradedBy`/`elapsedMs` above. Absent when the caller never attempted a cost lookup at all
+   *  (distinct from `{status:'absent'}`, which means a lookup WAS attempted and found nothing). */
+  readonly cost?: QeBridgeCost;
 }
 
 type RoundRefusal = { readonly ok: false; readonly exit: 1 | 2; readonly reason: string };
@@ -102,6 +188,25 @@ function nonEmpty(value: unknown): value is string {
   return typeof value === 'string' && value.trim() !== '';
 }
 
+/** review-cost-ledger fix-round-1 #1/#2 (ADR-001 п.2 amended): does an explicit `--reviewer` AGREE
+ *  with the qe-bridge sidecar's own `gradedBy` (already normalized by the caller to `family:model`,
+ *  e.g. `claude:sonnet`)? Case-insensitive. An exact `family:model` match agrees; a FAMILY-ONLY flag
+ *  (no `:` in it at all, e.g. `claude`) agrees with ANY `family:*` gradedBy of that same family —
+ *  the lead naming only the family (not a specific model) is still confirming the sidecar's identity.
+ *  Anything else (a different family, or a full `family:model` that does not match exactly) does NOT
+ *  agree — `closeRound` refuses that case outright rather than guessing which one is right. */
+function reviewerAgreesWithSidecar(reviewerFlag: string, gradedBy: string): boolean {
+  const flag = reviewerFlag.trim().toLowerCase();
+  const graded = gradedBy.trim().toLowerCase();
+  if (flag === '' || graded === '') return false;
+  if (flag === graded) return true;
+  if (!flag.includes(':')) {
+    const gradedFamily = graded.split(':')[0] ?? '';
+    return flag === gradedFamily;
+  }
+  return false;
+}
+
 function validSlug(value: string): boolean {
   return /^[a-z0-9][a-z0-9._-]*$/i.test(value);
 }
@@ -110,6 +215,12 @@ function validCount(value: number | undefined): boolean {
   return value === undefined || (Number.isInteger(value) && value >= 0);
 }
 
+/** experiment-instrument A1: a `--task` value is a non-empty string, at most 120 characters, with no
+ *  control characters (C0 or DEL) — long/garbled input refuses rather than being silently minted. */
+function validTaskId(value: string): boolean {
+  return value.trim() !== '' && value.length <= 120 && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
 export function openRound(input: {
   readonly slug: string;
   readonly round: number;
@@ -128,6 +239,10 @@ export function openRound(input: {
    * envelope refuses the open (exit 2) with the validator's own reason, same as any other malformed
    * input to this command. Absent stays absent (round open without --envelope is unaffected). */
   readonly envelope?: unknown;
+  /** experiment-instrument FR-1 (ADR-001): explicit task identity for this round. Absent ⇒
+   * `slug@startedAt` (minted below); present but invalid (empty, >120 chars, control characters) ⇒
+   * refused (A1) — never silently substituted with the default. */
+  readonly task?: string | undefined;
 }): { 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' };
@@ -136,6 +251,9 @@ export function openRound(input: {
     const v = validateExperimentEnvelope(input.envelope);
     if (!v.ok) return { ok: false, exit: 2, reason: `--envelope invalid — ${v.reason}` };
   }
+  if (input.task !== undefined && !validTaskId(input.task)) {
+    return { ok: false, exit: 2, reason: '--task должен быть непустой строкой ≤120 символов без управляющих символов' };
+  }
   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)
@@ -153,6 +271,7 @@ export function openRound(input: {
     ...(nonEmpty(input.run) ? { run: input.run.trim() } : {}),
     recalled: [...input.recalled],
     ...(input.envelope !== undefined ? { envelope: input.envelope } : {}),
+    taskId: input.task !== undefined ? input.task.trim() : `${input.slug}@${input.startedAt}`,
   };
   let existingOwnerAlive = input.existingOwnerAlive;
   if (input.existing?.ownerKind === 'run' && input.force) {
@@ -195,6 +314,20 @@ export function closeRound(input: {
   readonly grade?: string | undefined;
   /** measurement-integrity FR-7: the qe-bridge signoff for this slug, read by the CALLER. */
   readonly reviewSidecar?: RoundReviewSidecar | undefined;
+  /** experiment-instrument FR-3/A2/NFR-3: the git sha the CLI resolved (`git rev-parse HEAD`) — the
+   *  core never shells out, so this always arrives as data, `null` when it could not be resolved.
+   *  Only consulted for a FINISHED outcome (`shipped|refuted`); ignored otherwise. */
+  readonly shipSha?: string | null | undefined;
+  /** experiment-instrument A2: why `shipSha` is `null` (e.g. "not a git repository", "git failed: …")
+   *  — required to explain a null sha on a finished outcome, ignored when `shipSha` is non-null. */
+  readonly shipShaReason?: string | undefined;
+  /** experiment-instrument r1-5: whether `git status --porcelain` in `projectRoot` was non-empty at
+   *  close time (cli-resolved, same discipline as `shipSha` — the core never shells out). Ignored for
+   *  an unfinished outcome, same as `shipSha`. */
+  readonly shipTreeDirty?: boolean | undefined;
+  /** experiment-instrument r1-5: why `shipTreeDirty` could not be determined — required only when the
+   *  probe itself failed (`shipTreeDirty` absent), ignored otherwise. */
+  readonly shipTreeDirtyReason?: string | undefined;
 }, io: {
   readonly writeLedger: (row: RoundLedgerRow) => unknown;
   readonly readLedgerTail: () => string;
@@ -263,18 +396,118 @@ export function closeRound(input: {
   }
   const gradeForRow = gradeFlag;
 
-  // reviewer/reviewMinutes/reviewSource: an explicit --reviewer always wins; the sidecar fills the
-  // gap only, and only its OWN two derived fields travel with it (a flag-supplied reviewer never
-  // carries a sidecar-sourced `reviewMinutes`/`reviewSource` — that would misattribute where the
-  // minutes figure came from).
+  // reviewer/reviewMinutes/reviewSource: reviewer is TIED to the sidecar (ADR-001 п.2, amended by
+  // fix-round-1 #1/#2 after the Codex r1 BLOCKER/CRITICAL pair) either (a) it is FILLED from the
+  // sidecar (no explicit --reviewer), or (b) it is an explicit --reviewer that AGREES with the
+  // sidecar's own gradedBy. Case (b) exists because the pipeline's normal path ALWAYS passes
+  // --reviewer (feature-adr.js) — under the old "flag always wins, sidecar never trusted for cost"
+  // rule, the price this feature exists to record would NEVER be written on that path (BLOCKER #1).
+  // A DISAGREEING explicit --reviewer is refused outright, below — never silently ignored, and never
+  // silently misattributed (CRITICAL #2).
   let reviewer = nonEmpty(input.reviewer) ? input.reviewer.trim() : null;
   let reviewMinutes: number | null = null;
-  let reviewSource: 'qe-bridge' | null = null;
-  if (reviewer === null && input.reviewSidecar !== undefined && nonEmpty(input.reviewSidecar.gradedBy)) {
-    reviewer = input.reviewSidecar.gradedBy.trim();
-    const elapsedMs = input.reviewSidecar.elapsedMs;
+  let reviewSource: 'qe-bridge' | 'flag+qe-bridge' | null = null;
+  const sidecarGradedBy = input.reviewSidecar !== undefined && nonEmpty(input.reviewSidecar.gradedBy)
+    ? input.reviewSidecar.gradedBy.trim()
+    : null;
+  if (reviewer === null && sidecarGradedBy !== null) {
+    reviewer = sidecarGradedBy;
+    const elapsedMs = input.reviewSidecar!.elapsedMs;
     reviewMinutes = Number.isFinite(elapsedMs) && elapsedMs >= 0 ? Math.round((elapsedMs / 60_000) * 10) / 10 : null;
     reviewSource = 'qe-bridge';
+  } else if (reviewer !== null && sidecarGradedBy !== null) {
+    if (reviewerAgreesWithSidecar(reviewer, sidecarGradedBy)) {
+      const elapsedMs = input.reviewSidecar!.elapsedMs;
+      reviewMinutes = Number.isFinite(elapsedMs) && elapsedMs >= 0 ? Math.round((elapsedMs / 60_000) * 10) / 10 : null;
+      reviewSource = 'flag+qe-bridge';
+    } else {
+      // fix-round-1 #1/#2 (ADR-001 п.2 amended): the same discipline a --grade disagreeing with the
+      // sidecar's own grade already follows (FR-7) — an explicit reviewer naming someone ELSE than
+      // the sidecar's own reviewer must never silently receive (or silently omit) that reviewer's
+      // price; it refuses, naming both values, before any row is built.
+      return {
+        ok: false,
+        exit: 2,
+        reason: `--reviewer "${reviewer}" conflicts with the qe-bridge sidecar's reviewer "${sidecarGradedBy}" for slug ${input.state.slug}`,
+      };
+    }
+  }
+
+  // review-cost-ledger FR-3/A4 (ADR-001 п.4): a FINISHED review (shipped|refuted) with NEITHER an
+  // explicit --reviewer NOR one filled from the sidecar is unmeasurable by definition — the audit
+  // this feature exists to close (ADR-001 Q5). blocked|abandoned carry no such requirement, same as
+  // they carry no grade requirement above: a review that never finished has no reviewer to name yet.
+  if (finishedOutcome && reviewer === null) {
+    return {
+      ok: false,
+      exit: 2,
+      reason: `finished review requires a reviewer: outcome=${outcome} needs --reviewer <model> (no --reviewer flag and no qe-bridge signoff to fill it from)`,
+    };
+  }
+
+  // review-cost-ledger FR-2/A2/A3 (ADR-001 п.1-3, amended by fix-round-1 #2/#3/#5): the reviewer's
+  // price is written ONLY when the row's reviewer is TIED to the sidecar — reviewSource is
+  // 'qe-bridge' or 'flag+qe-bridge' (the two cases computed above). fix-round-1 #2 (Codex r1
+  // CRITICAL #2): the old "or it carries no gradedBy at all" hack is REMOVED — an untrusted sidecar
+  // (empty gradedBy, e.g. T3's Codex-no-signoff synthesis) can still explain an ABSENT/UNPARSEABLE
+  // price (that is a structural fact about the instrument, not an attribution), but it can NEVER
+  // yield an 'ok' price for a reviewer it was not written for — an adversarial ok-cost sidecar with
+  // an empty gradedBy is exactly the CRITICAL #2 failing input, and it must never buy a price here.
+  let reviewerCostFields: Pick<RoundLedgerRow, 'reviewerCostUsd' | 'reviewerTokens' | 'reviewerTokensBreakdown' | 'reviewerCostSource' | 'reviewerCostReason'> | null = null;
+  const sidecarCost = input.reviewSidecar?.cost;
+  const reviewerTiedToSidecar = reviewSource === 'qe-bridge' || reviewSource === 'flag+qe-bridge';
+  if (reviewerTiedToSidecar) {
+    // fix-round-1 #3 (Codex r1 HIGH #3): a sidecar that filled/confirmed the reviewer but carries NO
+    // cost record at all (cost undefined) used to leave every price field silently absent — the same
+    // "never a bare unexplained gap" discipline as `shipShaReason` now applies here too.
+    if (sidecarCost === undefined) {
+      reviewerCostFields = { reviewerCostUsd: null, reviewerCostSource: 'unavailable', reviewerCostReason: 'sidecar carried no cost record' };
+    } else if (sidecarCost.status === 'ok') {
+      // fix-round-1 #5 (Codex r1 HIGH #5): tokensPartial on the sidecar means the sum is NOT a real
+      // count (at least one component was missing) — reviewerTokens goes null rather than a silently
+      // zeroed/short sum, while the still-valid price and the partial breakdown are kept.
+      const partial = sidecarCost.tokens.tokensPartial === true;
+      reviewerCostFields = {
+        reviewerCostUsd: sidecarCost.costUsd,
+        reviewerTokens: partial ? null : sidecarCost.tokens.total,
+        reviewerTokensBreakdown: {
+          input: sidecarCost.tokens.input,
+          output: sidecarCost.tokens.output,
+          cacheCreation: sidecarCost.tokens.cacheCreation,
+          cacheRead: sidecarCost.tokens.cacheRead,
+          ...(partial ? { partial: true as const } : {}),
+        },
+        reviewerCostSource: 'qe-bridge-stdout',
+      };
+    } else {
+      const reason = nonEmpty(sidecarCost.reason)
+        ? sidecarCost.reason.trim()
+        : 'qe-bridge stdout sidecar carried no parseable cost line';
+      reviewerCostFields = { reviewerCostUsd: null, reviewerCostSource: 'unavailable', reviewerCostReason: reason };
+    }
+  } else if (sidecarCost !== undefined) {
+    // The reviewer is NOT tied to this sidecar (an untrusted/untied sidecar — e.g. T3's
+    // Codex-no-signoff synthesis, empty gradedBy). It may still explain a NAMED limit
+    // (status !== 'ok') — that is honest instrument metadata, not an attribution. fix-round-1 #2: an
+    // 'ok' status here is NEVER trusted for a price, whatever the number — the sidecar was not
+    // written for this reviewer, full stop.
+    if (sidecarCost.status !== 'ok') {
+      // Lead delta after Codex r2 (#2 partial): an untied sidecar's OWN reason (the cli's Codex
+      // "tokens not visible" synthesis) was copied onto ANY explicit reviewer's row — a Claude
+      // reviewer got a Codex-specific limit as its explanation. The sidecar's reason travels only
+      // to a reviewer of the codex family; every other untied reviewer gets the neutral fact.
+      const reviewerIsCodex = /^codex\b/i.test(reviewer ?? '');
+      const reason = reviewerIsCodex && nonEmpty(sidecarCost.reason)
+        ? sidecarCost.reason.trim()
+        : 'explicit --reviewer is not tied to a qe-bridge sidecar (no signoff names this reviewer)';
+      reviewerCostFields = { reviewerCostUsd: null, reviewerCostSource: 'unavailable', reviewerCostReason: reason };
+    } else {
+      reviewerCostFields = {
+        reviewerCostUsd: null,
+        reviewerCostSource: 'unavailable',
+        reviewerCostReason: 'qe-bridge sidecar carried a price but is not tied to this row\'s reviewer',
+      };
+    }
   }
 
   const startedMs = Date.parse(input.state.startedAt);
@@ -285,6 +518,37 @@ export function closeRound(input: {
   const compactTs = new Date(closedMs).toISOString().replace(/[-:.]/g, '');
   const marker = `round-${input.state.slug}-${input.state.round}-${compactTs}`;
   const note = input.note?.trim() ?? '';
+
+  // experiment-instrument FR-1/A4/A5: the state ALWAYS carries a taskId for a round opened after this
+  // feature; a state written before it lacks the key on disk, so the same default `openRound` mints
+  // is derived here and the derivation is named (`taskIdSource`) — never silently blended with a
+  // fresh-mint taskId, which is what `taskIdSource` absent means.
+  const taskIdFromState = input.state.taskId;
+  const taskId = nonEmpty(taskIdFromState) ? taskIdFromState.trim() : `${input.state.slug}@${input.state.startedAt}`;
+  const taskIdSource: 'derived-legacy' | null = nonEmpty(taskIdFromState) ? null : 'derived-legacy';
+
+  // experiment-instrument FR-3/A2: only a FINISHED outcome carries a ship anchor — `blocked|abandoned`
+  // never shipped anything, so a sha there would misleadingly imply a release. A null sha REQUIRES its
+  // reason to be recorded next to it (never a bare, unexplained null on a finished row) — r1-6 (Codex
+  // r1 MEDIUM #6): a caller that supplies no reason at all no longer leaves the row silently
+  // unexplained; a stable default fills the gap instead of an absent key.
+  const finishedForShip = outcome === 'shipped' || outcome === 'refuted';
+  const shipSha = finishedForShip ? (input.shipSha ?? null) : null;
+  const shipShaReason = finishedForShip && shipSha === null
+    ? (nonEmpty(input.shipShaReason) ? input.shipShaReason.trim() : 'not provided')
+    : null;
+  // experiment-instrument r1-5 (Codex r1 HIGH #5, ADR-001 amended): `shipTreeDirty` is present only
+  // when the caller (the cli) actually resolved it; `shipTreeDirtyReason` fills the gap when it could
+  // not be. Neither is ever guessed here — the core never shells out to compute either.
+  const shipTreeDirtyValue: boolean | undefined = finishedForShip && typeof input.shipTreeDirty === 'boolean'
+    ? input.shipTreeDirty
+    : undefined;
+  // r2-2 (Codex r2 MEDIUM N2, lead delta): a finished row with NEITHER field used to omit both —
+  // the same bare-gap shape r1-6 closed for the sha. The rule is symmetric: boolean, or a reason.
+  const shipTreeDirtyReason = finishedForShip && shipTreeDirtyValue === undefined
+    ? (nonEmpty(input.shipTreeDirtyReason) ? input.shipTreeDirtyReason.trim() : 'not provided')
+    : undefined;
+
   const row: RoundLedgerRow = {
     slug: input.state.slug,
     stage: 'round',
@@ -308,6 +572,13 @@ export function closeRound(input: {
     ...(input.state.envelope !== undefined ? { envelope: input.state.envelope } : {}),
     ...(reviewSource !== null ? { reviewSource } : {}),
     ...(reviewMinutes !== null ? { reviewMinutes } : {}),
+    taskId,
+    ...(taskIdSource !== null ? { taskIdSource } : {}),
+    ...(finishedForShip ? { shipSha, shippedAt: input.closedAt } : {}),
+    ...(shipShaReason !== null ? { shipShaReason } : {}),
+    ...(shipTreeDirtyValue !== undefined ? { shipTreeDirty: shipTreeDirtyValue } : {}),
+    ...(shipTreeDirtyReason !== undefined ? { shipTreeDirtyReason } : {}),
+    ...(reviewerCostFields !== null ? reviewerCostFields : {}),
   };
 
   try {
@@ -362,6 +633,51 @@ export function validateClosedRoundLedgerRow(row: unknown): { readonly ok: true
   return { ok: true };
 }
 
+/**
+ * experiment-instrument FR-1/FR-3 (ADR-001 D-A): the single source every OTHER writer (an auto ledger
+ * row, a qe-bridge signoff, a control-review row) consults to find this slug's task identity —
+ * never guessed, never minted here. `states` is whatever the CALLER already read as "currently open
+ * round state files for this slug" (the cli walks `.dz/rounds/<slug>-*.json`); this function does not
+ * touch a filesystem and does not assume the caller pre-filtered by slug, so it filters again itself.
+ *
+ * `unreadableStateCount` (r1-2, Codex r1 HIGH #2) is how many FILENAMES the caller found matching this
+ * slug's pattern that it could NOT parse into a `RoundState` — a corrupt or half-written state file is
+ * never silent absence; it means the true open-round count for this slug is UNKNOWN, not zero.
+ *
+ * - Any unreadable candidate exists AND no readable one does ⇒ `{taskId: null, source: 'unavailable'}`
+ *   — a round MAY be open here, but its state cannot be read (r1-2).
+ * - Any unreadable candidate exists ALONGSIDE at least one readable one ⇒ `{taskId: null, source:
+ *   'ambiguous'}` — the readable one might not be the only genuinely open round (r1-2).
+ * - Zero candidates at all (readable or not) ⇒ `{taskId: null, source: 'no-open-round'}` — no open
+ *   round, nothing to fill from (A4).
+ * - Two or more readable matches, no unreadable ones ⇒ `{taskId: null, source: 'ambiguous'}` — which
+ *   one is authoritative is not decidable here; a NULL is the honest answer, never "the latest wins" (A5).
+ * - Exactly one readable match, no unreadable ones ⇒ its `taskId` when the state carries one
+ *   (`source: 'open-round'`), or the SAME `slug@startedAt` default `openRound`/`closeRound` would
+ *   derive for a legacy state missing the field on disk — labelled `source: 'derived-legacy'` (r1-1,
+ *   Codex r1 CRITICAL #1: this used to report `'open-round'` for an invented value, indistinguishable
+ *   from a value the round itself actually minted).
+ */
+export function readOpenRoundTaskId(
+  states: readonly RoundState[],
+  slug: string,
+  unreadableStateCount = 0,
+): {
+  readonly taskId: string | null;
+  readonly source: 'open-round' | 'derived-legacy' | 'no-open-round' | 'ambiguous' | 'unavailable';
+} {
+  const matches = states.filter((s) => s.slug === slug);
+  const unreadable = Number.isFinite(unreadableStateCount) && unreadableStateCount > 0 ? Math.floor(unreadableStateCount) : 0;
+  if (unreadable > 0 && matches.length === 0) return { taskId: null, source: 'unavailable' };
+  if (unreadable > 0) return { taskId: null, source: 'ambiguous' };
+  if (matches.length === 0) return { taskId: null, source: 'no-open-round' };
+  if (matches.length > 1) return { taskId: null, source: 'ambiguous' };
+  const state = matches[0]!;
+  const taskId = nonEmpty(state.taskId) ? state.taskId.trim() : `${state.slug}@${state.startedAt}`;
+  const source = nonEmpty(state.taskId) ? 'open-round' : 'derived-legacy';
+  return { taskId, source };
+}
+
 export function listRounds(states: readonly RoundState[], input: {
   readonly now: number;
   readonly olderThanMinutes: number;