@dzhechkov/harness-core 0.4.1 → 0.4.2

package/src/loop-trace.ts

@@ -26,7 +26,7 @@
 import type { TraceProjection } from './loop-plan.js';
 
 /** Blob version stamp for the emitter half (read by scripts/gen-loop-blobs.mjs). */
-export const LOOP_TRACE_BLOB_VERSION = '1.0.0';
+export const LOOP_TRACE_BLOB_VERSION = '1.1.0';
 
 export const LOOP_TRACE_SCHEMA_VERSION = 1;
 
@@ -211,6 +211,83 @@ export function traceFlushCmd(state: TraceState, traceFileAbs: string): string |
   return 'mkdir -p ' + dir + ' && ' + printfs;
 }
 
+/**
+ * Build the feature-ADR live-panel telemetry leg. Totality comes from the caller's grouped splice:
+ * returning the bare command lets that splice preserve the trace flush's exit status while
+ * swallowing only the panel leg's failure. The `loop` producer marker stops a generated loop's
+ * high-frequency zero counters from displacing a live `/feature-adr` run's meaningful panel.
+ */
+export function traceFaRecordCmd(dzBin: unknown, slug: unknown, stepLabel: unknown, projectAbs: unknown): string | null {
+  if (typeof slug !== 'string' || slug === ''
+    || typeof stepLabel !== 'string' || stepLabel === ''
+    || typeof projectAbs !== 'string' || projectAbs === '') return null;
+  const bin = typeof dzBin === 'string' && dzBin !== '' ? dzBin : 'dz';
+  const cmd = traceShellQuote(bin) + ' statusline --fa-record --slug ' + traceShellQuote(slug)
+    + ' --step ' + traceShellQuote(stepLabel) + ' --kind loop --project ' + traceShellQuote(projectAbs);
+  return cmd + ' >/dev/null 2>&1';
+}
+
+/** Build one feature-ADR run-cost row without manufacturing wall-clock data in JavaScript. */
+export function traceLedgerLine(opts: {
+  slug: unknown;
+  runId?: unknown;
+  planDigest?: unknown;
+  /**
+   * `agents` is the TOTAL number of agent invocations this run made — model dispatches AND infra
+   * agents (trace flush, checkpoint read/write, training-pair write/backfill, landed-barrier probes,
+   * and this ledger writer itself) — counted at write time. It is NOT the trace's model-dispatch
+   * count; the ledger's `agents` column means `agent_count` from the Workflow completion
+   * notification, and this row must not silently redefine it.
+   */
+  agents?: unknown;
+  date?: unknown;
+  outcome?: unknown;
+}): string | null {
+  try {
+    if (typeof opts.slug !== 'string' || opts.slug === '') return null;
+    const agents = typeof opts.agents === 'number'
+      && Number.isFinite(opts.agents)
+      && Number.isInteger(opts.agents)
+      && opts.agents >= 0
+      ? opts.agents
+      : 0;
+    const date = typeof opts.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : null;
+    const outcome = typeof opts.outcome === 'string' && opts.outcome !== '' ? opts.outcome : 'unknown';
+    const line = JSON.stringify({
+      slug: opts.slug,
+      stage: 'loop-run',
+      tier: null,
+      tokens: null,
+      minutes: null,
+      agents,
+      coder: null,
+      grade: null,
+      date,
+      auto: true,
+      outcome,
+      runId: typeof opts.runId === 'string' ? opts.runId : null,
+      planDigest: typeof opts.planDigest === 'string' ? opts.planDigest : null,
+    });
+    return line.length <= 4000 ? line : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Build the single command that appends a run-cost row and confirms the write. */
+export function traceLedgerAppendCmd(repoAbs: unknown, line: unknown): string | null {
+  if (typeof repoAbs !== 'string' || repoAbs === '' || typeof line !== 'string' || line === '') return null;
+  const dir = traceShellQuote(repoAbs + '/.dz/feature-adr');
+  const file = traceShellQuote(repoAbs + '/.dz/feature-adr/run-cost-ledger.jsonl');
+  // The field token has a fixed position, and JSON-escaped scalar values (including slug,
+  // runId, and planDigest) cannot introduce the raw `"date":null` token targeted by sed.
+  return 'mkdir -p ' + dir
+    + " && printf '%s' " + traceShellQuote(line)
+    + ' | sed "s/\\"date\\":null/\\"date\\":\\"$(date -u +%Y-%m-%d)\\"/" >> ' + file
+    + " && printf '\\n' >> " + file
+    + ' && echo LEDGER-OK';
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // READER HALF — parseTrace / runInvariants / assembleTimeline / renderTimelineHtml.
 // Pure over strings; the CLI does the fs.

package/src/statusline.ts

@@ -14,8 +14,8 @@
  * @packageDocumentation
  */
 
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 
 import { listBrain } from './brain.js';
@@ -28,6 +28,8 @@ import { RECALL_USAGE_LOG_RELATIVE, aggregateRecallUsage, parseRecallUsageLog }
  * path (readonly, best-effort) by `readFeatureAdrState`.
  */
 export interface FeatureAdrState {
+  /** Producer of this panel state. Missing/invalid legacy values are treated as `feature-adr`. */
+  readonly kind?: 'feature-adr' | 'loop';
   /** The feature slug the pipeline is working on (kebab-case). */
   readonly slug: string;
   /** Human-readable step label (e.g. "Step 0", "Step 8 QE"). */
@@ -70,9 +72,29 @@ function consolidateWatermarkPath(projectRoot: string): string {
   return join(projectRoot, '.dz', 'memory', 'consolidate.json');
 }
 
-/** Path of the live `/feature-adr` learning-state file (per-run panel source). */
-export function featureAdrStatePath(projectRoot: string): string {
-  return join(projectRoot, '.dz', 'feature-adr', 'learning-state.json');
+/** Directory of the per-slug live `/feature-adr` learning-state slots. */
+export function featureAdrStateDir(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'feature-adr', 'learning-state');
+}
+
+/** Make a slug safe as one bounded filename component (never `/`, `..`, or leading dot/dash). */
+function featureAdrStateSlug(slug: string): string {
+  const safe = slug
+    .replace(/[^A-Za-z0-9._-]/g, '_')
+    .replace(/^[.-]+/, '_')
+    .replace(/\.{2,}/g, '_')
+    .slice(0, 60);
+  return safe.length > 0 ? safe : '_unnamed';
+}
+
+/**
+ * Path of a live `/feature-adr` learning-state file. With a slug this is its namespaced slot;
+ * without one this remains the legacy single-slot path for backward-compatible readers/callers.
+ */
+export function featureAdrStatePath(projectRoot: string, slug?: string): string {
+  return slug === undefined
+    ? join(projectRoot, '.dz', 'feature-adr', 'learning-state.json')
+    : join(featureAdrStateDir(projectRoot), `${featureAdrStateSlug(slug)}.json`);
 }
 
 /**
@@ -181,35 +203,84 @@ function consolidatedAgeHours(projectRoot: string, now: number): number | undefi
  * @param now Injectable clock (epoch ms) for the freshness check — defaults to `Date.now()`.
  */
 export function readFeatureAdrState(projectRoot: string, now: number = Date.now()): FeatureAdrState | undefined {
-  const path = featureAdrStatePath(resolve(projectRoot));
-  if (!existsSync(path)) return undefined;
+  const root = resolve(projectRoot);
+  const candidates: string[] = [];
+
+  // Keep the legacy single slot in the candidate set: an older dz may still be writing it while a
+  // newer statusline renders. Directory discovery is guarded separately because this is the hot,
+  // readonly ~300ms render path; it never performs housekeeping or any other write.
   try {
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<FeatureAdrState>;
-    if (typeof parsed.slug !== 'string' || parsed.slug.length === 0) return undefined;
-    if (typeof parsed.step !== 'string' || parsed.step.length === 0) return undefined;
-    if (typeof parsed.ts !== 'string') return undefined;
-    const tsMs = Date.parse(parsed.ts);
-    if (Number.isNaN(tsMs)) return undefined;
-    if (now - tsMs > FEATURE_ADR_FRESH_MS) return undefined; // stale run — do not surface a panel
-    const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
-    const state: FeatureAdrState = {
-      slug: parsed.slug,
-      step: parsed.step,
-      pool: num(parsed.pool),
-      recalled: num(parsed.recalled),
-      stored: num(parsed.stored),
-      ...(num(parsed.reinforced) > 0 ? { reinforced: num(parsed.reinforced) } : {}),
-      ts: parsed.ts,
-      ...(typeof parsed.mode === 'string' && parsed.mode.length > 0 ? { mode: parsed.mode } : {}),
-    };
-    return state;
-  } catch {
-    return undefined;
+    const legacyPath = featureAdrStatePath(root);
+    if (existsSync(legacyPath)) candidates.push(legacyPath);
+  } catch { /* best-effort candidate discovery */ }
+  try {
+    const remaining = 64 - candidates.length;
+    if (remaining > 0) {
+      const dir = featureAdrStateDir(root);
+      const names = readdirSync(dir)
+        .filter((name) => name.endsWith('.json'))
+        .map((name) => {
+          let mtimeMs = -Infinity;
+          try {
+            mtimeMs = statSync(join(dir, name)).mtimeMs;
+          } catch { /* a disappearing/unreadable entry sorts last */ }
+          return { name, mtimeMs };
+        })
+        // Truncation may only drop the least recent slots: kind-rank arbitration cannot rescue a non-candidate.
+        .sort((a, b) => b.mtimeMs - a.mtimeMs)
+        .slice(0, remaining);
+      for (const { name } of names) candidates.push(join(dir, name));
+    }
+  } catch { /* absent/unreadable per-slug directory is normal */ }
+
+  const parseCandidate = (path: string): { state: FeatureAdrState; tsMs: number; rank: number } | undefined => {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<FeatureAdrState>;
+      if (typeof parsed.slug !== 'string' || parsed.slug.length === 0) return undefined;
+      if (typeof parsed.step !== 'string' || parsed.step.length === 0) return undefined;
+      if (typeof parsed.ts !== 'string') return undefined;
+      const tsMs = Date.parse(parsed.ts);
+      if (Number.isNaN(tsMs)) return undefined;
+      if (now - tsMs > FEATURE_ADR_FRESH_MS) return undefined; // stale run — do not surface a panel
+      const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+      // The panel exists to surface the /feature-adr Pattern-memory loop. A generated loop writes
+      // zero recalled/stored counters far more often, so freshest-wins would recreate F5 by making
+      // a live pipeline's meaningful counters disappear. Missing/invalid legacy markers therefore
+      // retain the historical `feature-adr` rank, which outranks every loop slot regardless of ts.
+      const kind: 'feature-adr' | 'loop' = parsed.kind === 'loop' ? 'loop' : 'feature-adr';
+      const state: FeatureAdrState = {
+        kind,
+        slug: parsed.slug,
+        step: parsed.step,
+        pool: num(parsed.pool),
+        recalled: num(parsed.recalled),
+        stored: num(parsed.stored),
+        ...(num(parsed.reinforced) > 0 ? { reinforced: num(parsed.reinforced) } : {}),
+        ts: parsed.ts,
+        ...(typeof parsed.mode === 'string' && parsed.mode.length > 0 ? { mode: parsed.mode } : {}),
+      };
+      return { state, tsMs, rank: kind === 'feature-adr' ? 1 : 0 };
+    } catch {
+      return undefined;
+    }
+  };
+
+  let winner: ReturnType<typeof parseCandidate>;
+  for (const path of candidates) {
+    const candidate = parseCandidate(path);
+    if (candidate === undefined) continue;
+    if (winner === undefined
+      || candidate.rank > winner.rank
+      || (candidate.rank === winner.rank && candidate.tsMs > winner.tsMs)) {
+      winner = candidate;
+    }
   }
+  return winner?.state;
 }
 
 /** Fields the `/feature-adr` pipeline supplies when recording its live learning state. */
 export interface WriteFeatureAdrStateInput {
+  readonly kind?: 'feature-adr' | 'loop';
   readonly slug: string;
   readonly step: string;
   readonly recalled: number;
@@ -239,6 +310,7 @@ export function writeFeatureAdrState(
     pool = 0;
   }
   const state: FeatureAdrState = {
+    kind: input.kind === 'loop' ? 'loop' : 'feature-adr',
     slug: input.slug,
     step: input.step,
     pool,
@@ -249,8 +321,23 @@ export function writeFeatureAdrState(
     ...(input.mode !== undefined && input.mode.length > 0 ? { mode: input.mode } : {}),
   };
   try {
-    const path = featureAdrStatePath(root);
-    mkdirSync(dirname(path), { recursive: true });
+    const dir = featureAdrStateDir(root);
+    mkdirSync(dir, { recursive: true });
+
+    // Housekeeping belongs only on this write path, never the ~300ms render path. Every file is
+    // independently guarded so an unreadable/racing entry cannot prevent the live state write.
+    try {
+      const cutoff = Date.now() - 24 * 60 * 60 * 1_000;
+      for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.json')) continue;
+        const stalePath = join(dir, name);
+        try {
+          if (statSync(stalePath).mtimeMs < cutoff) unlinkSync(stalePath);
+        } catch { /* best-effort per-file cleanup */ }
+      }
+    } catch { /* best-effort directory cleanup */ }
+
+    const path = featureAdrStatePath(root, input.slug);
     writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`);
   } catch {
     return undefined;