@agent-delivery-harness/cli 0.2.0 → 0.7.3

package/src/run-projection.ts

@@ -20,9 +20,13 @@
  */
 import {
   RUN_JOURNAL_REQUIRED_ENTRIES,
+  explainRunJournal,
   runJournalCarries,
+  runPrimaryTicket,
+  projectRunActivities,
   type RunEvent,
   type RunJournalEvaluation,
+  type RunJournalExplanation,
   type RunJournalRequiredEntry,
 } from "@agent-delivery-harness/kernel";
 import { harnessConfigPresentAt, oneLine, oneLineOf } from "./run-surface.ts";
@@ -30,9 +34,91 @@ import { harnessConfigPresentAt, oneLine, oneLineOf } from "./run-surface.ts";
 /** The three labels every readout carries, so no reader mistakes this for evidence. */
 export const READOUT_LABELS = "self-attested; observability, not evidence; unbound to a record";
 
+/** A single progress view shared by renderers; callers supply their observation clock. */
+export function projectRunProgress(events: readonly RunEvent[], now: string, freshnessWindowMs?: number) {
+  const projection = projectRunActivities(events, { now, ...(freshnessWindowMs === undefined ? {} : { freshnessWindowMs }) });
+  const latestFindings = new Map<string, (typeof projection.findings)[number]>();
+  for (const finding of projection.findings) {
+    if (finding.current) latestFindings.set(String(finding.payload["findingId"]), finding);
+  }
+  return {
+    asOf: now,
+    ...projection,
+    currentFindings: [...latestFindings.values()],
+    findingsCoverage: events.some(e => e.kind === "finding.observed") ? "reported" as const : "unreported" as const,
+  };
+}
+
+export function costLabel(value: unknown): string {
+  const cost = typeof value === "object" && value !== null ? value as Record<string, unknown> : {};
+  if (cost["coverage"] === "unreported" || cost["total"] === undefined) return "unreported";
+  const measured = `${oneLineOf(cost["total"])} ${oneLineOf(cost["unit"])}`.trim();
+  return cost["coverage"] === "partial" ? `${measured} (partial coverage)` : measured;
+}
+
+/** Aggregate only comparable review counters; the run-wide counter overlaps them. */
+export function projectCosts(events: readonly RunEvent[]) {
+  const allClosed = events.filter((event) => event.kind === "review.round.closed");
+  // v2 round costs are reported cumulative snapshots. Repeated/reopened round
+  // snapshots cannot be summed as independent consumption. Keep the latest
+  // comparable value and mark coverage partial when supersession occurred.
+  const snapshots = new Map<string, RunEvent>();
+  for (const event of allClosed) {
+    const payload = payloadOf(event);
+    const cost = payload["cost"] as Record<string, unknown>;
+    const key = event.version === "run-event/2"
+      ? JSON.stringify([payload["roundId"], cost["reportedBy"], cost["unit"] ?? "unreported"])
+      : `legacy-${event.seq}`;
+    snapshots.set(key, event);
+  }
+  const closed = [...snapshots.values()];
+  const totals = new Map<string, { unit: string; reportedBy: string; total: number | null }>();
+  let unreportedEntries = 0;
+  let partial = allClosed.length !== closed.length || events.filter((event) => event.kind === "review.round.opened").length !== closed.length;
+  for (const event of closed) {
+    const cost = payloadOf(event)["cost"] as Record<string, unknown>;
+    if (cost["coverage"] === "unreported") {
+      unreportedEntries += 1;
+      continue;
+    }
+    if (cost["coverage"] === "partial") partial = true;
+    const unit = cost["unit"] as string;
+    const reportedBy = cost["reportedBy"] as string;
+    const key = JSON.stringify([reportedBy, unit]);
+    const prior = totals.get(key);
+    const sum = prior?.total === null ? Infinity : (prior?.total ?? 0) + (cost["total"] as number);
+    // The validated event keeps the original finite measurement even if a sum
+    // exceeds the numeric range. Null is unavailable, never measured zero.
+    if (!Number.isFinite(sum)) partial = true;
+    totals.set(key, { unit, total: Number.isFinite(sum) ? sum : null, reportedBy });
+  }
+  const ended = events.find((event) => event.kind === "run.ended");
+  return {
+    review: {
+      coverage: totals.size === 0 ? "unreported" : partial || unreportedEntries > 0 ? "partial" : "complete",
+      unreportedEntries,
+      totals: [...totals.values()],
+    },
+    run: ended === undefined ? { coverage: "unreported" } : payloadOf(ended)["cost"],
+  };
+}
+
 export const payloadOf = (event: RunEvent): Record<string, unknown> =>
   typeof event.payload === "object" && event.payload !== null ? (event.payload as Record<string, unknown>) : {};
 
+/**
+ * The ticket an entry BOUND ITSELF to, as a row suffix, or nothing.
+ *
+ * Only the entry's own binding is rendered. An entry that omits `ticket` binds
+ * to the run's primary, which the runs table already names in the row above
+ * every timeline — repeating it on each unbound line would turn the one thing
+ * the member exists to say, that THIS entry belongs to THAT ticket, into
+ * boilerplate an operator learns to skip. The envelope is read rather than the
+ * payload because the validator holds the two to exact agreement and the
+ * envelope is what every other reader here reads.
+ */
+const boundTicket = (event: RunEvent): string => (event.ticket === undefined ? "" : ` for ${oneLineOf(event.ticket, 128)}`);
+
 /**
  * One row's detail for one event: enough to read the run without printing the
  * whole payload back at the operator.
@@ -43,11 +129,11 @@ export function detailOf(event: RunEvent): string {
     case "run.started":
       return oneLineOf(payload["host"]) + (payload["displacedRunId"] === undefined ? "" : ` displaced ${oneLineOf(payload["displacedRunId"])}`);
     case "run.ended":
-      return `${oneLineOf(payload["result"])} cost ${oneLineOf((payload["cost"] as { total?: unknown } | undefined)?.total)}`;
+      return `${oneLineOf(payload["result"])} cost ${costLabel(payload["cost"])}`;
     case "ticket.read":
       return `${oneLineOf(payload["ticket"])} via ${oneLineOf(payload["tracker"])}`;
     case "posture.declared":
-      return oneLineOf(payload["posture"]);
+      return oneLineOf(payload["posture"]) + boundTicket(event);
     case "lens.selected":
       return `mandated ${oneLineOf(payload["mandated"])} selected ${oneLineOf(payload["selected"])} — ${oneLineOf(payload["rationale"])}`;
     case "review.round.opened":
@@ -57,15 +143,22 @@ export function detailOf(event: RunEvent): string {
     case "command.completed":
       return `${oneLineOf(payload["command"])} ${oneLineOf(payload["outcome"])} in ${oneLineOf(payload["durationMs"])}ms`;
     case "gate.reported":
-      return `${oneLineOf(payload["command"])} ${oneLineOf(payload["outcome"])} in ${oneLineOf(payload["durationMs"])}ms`;
+      return `${oneLineOf(payload["command"])} ${oneLineOf(payload["outcome"])} in ${oneLineOf(payload["durationMs"])}ms${boundTicket(event)}`;
     case "pr.opened":
-      return `${oneLineOf(payload["url"], 400)} on ${oneLineOf(event.candidateTreeSha)}`;
+      return `${oneLineOf(payload["url"], 400)} on ${oneLineOf(event.candidateTreeSha)}${boundTicket(event)}`;
     case "blocker.recorded":
       return `${oneLineOf(payload["code"])} — ${oneLineOf(payload["summary"])}`;
     case "decision.recorded":
       return `${oneLineOf(payload["fork"])} — ${oneLineOf(payload["choice"])}${payload["cited"] === undefined ? "" : ` (cited ${oneLineOf(payload["cited"])})`}`;
     case "compounding.recorded":
       return `${oneLineOf(payload["outcome"])}${payload["reference"] === undefined ? "" : ` — ${oneLineOf(payload["reference"])}`}`;
+    case "context.saved":
+      return `stage ${oneLineOf(payload["stage"])} (observation only)`;
+    case "action.reconciled":
+      return `${oneLineOf(payload["actionId"])} reconciled ${oneLineOf(payload["outcome"])} (host-attested) evidence ${oneLineOf(payload["evidenceReference"])}`;
+    case "action.intent":
+    case "action.observed":
+      return `${oneLineOf(payload["actionId"])} ${oneLineOf(payload["outcome"] ?? "unknown")} reference ${oneLineOf(payload["reference"])}`;
     default:
       return "";
   }
@@ -109,6 +202,20 @@ export function roundEntries(events: readonly RunEvent[]): readonly RoundEntry[]
   });
 }
 
+/**
+ * The lenses a round carried, or the fact that it never opened.
+ *
+ * A round with no `review.round.opened` has no lens set to name, and the two
+ * surfaces have to say the SAME thing about that. The terminal already said
+ * `never opened`; the page rendered nothing, which an operator reads as a
+ * round that opened carrying no lens. That is a second answer to one question
+ * about one file, which is exactly what this module exists to prevent — so the
+ * words live here, once, and each surface only escapes and places them.
+ */
+export function roundLenses(entry: RoundEntry): string {
+  return entry.opened === undefined ? "never opened" : oneLineOf(payloadOf(entry.opened)["lenses"]);
+}
+
 /** One text row per round, each carrying the candidate it was bound to. */
 export function roundRows(events: readonly RunEvent[]): readonly string[] {
   return roundEntries(events).map((entry) => {
@@ -116,12 +223,180 @@ export function roundRows(events: readonly RunEvent[]): readonly string[] {
     return [
       `  round ${entry.round}`,
       `candidate ${entry.candidateTreeSha || "(none)"}`,
-      entry.opened === undefined ? "never opened" : `lenses ${oneLineOf(payloadOf(entry.opened)["lenses"])}`,
-      closed === undefined ? "open" : `${oneLineOf(closed["outcome"])} findings ${oneLineOf(closed["findings"])} cost ${oneLineOf((closed["cost"] as { total?: unknown } | undefined)?.total)}`,
+      entry.opened === undefined ? roundLenses(entry) : `lenses ${roundLenses(entry)}`,
+      closed === undefined ? "open" : `${oneLineOf(closed["outcome"])} findings ${oneLineOf(closed["findings"])} cost ${costLabel(closed["cost"])}`,
     ].join("  ");
   });
 }
 
+// ── Cycle time ───────────────────────────────────────────────────────────────
+
+/**
+ * A span of seconds as one short label, for a column an operator scans.
+ *
+ * WHY A LABEL AND NOT THE NUMBER. `runs list` prints one row per run and the
+ * question it answers is "which of these took a working day"; 47_112 answers
+ * that only after arithmetic. The machine-readable surfaces carry the seconds
+ * themselves, so nothing is lost: `durationSeconds` is beside this everywhere
+ * the label is serialized.
+ *
+ * The smaller unit is zero-padded so the column aligns under a proportional-
+ * enough terminal font, and the largest unit is never dropped: a run of 104
+ * hours reads `104h 03m` rather than being folded into days, because a journal
+ * spans hours and a day boundary is not a thing this file knows about.
+ */
+export function durationLabel(seconds: number): string {
+  const whole = Number.isFinite(seconds) && seconds > 0 ? Math.round(seconds) : 0;
+  const hours = Math.floor(whole / 3600);
+  const minutes = Math.floor((whole % 3600) / 60);
+  const rest = whole % 60;
+  if (hours > 0) return `${hours}h ${String(minutes).padStart(2, "0")}m`;
+  if (minutes > 0) return `${minutes}m ${String(rest).padStart(2, "0")}s`;
+  return `${rest}s`;
+}
+
+/**
+ * The gate time a journal can actually account for.
+ *
+ * `counted` is how many gate completions were journaled and `totalMs` their
+ * sum; `unseen` says the journal carries none at all. That last one is the
+ * honest answer to the thing this ticket was written for: a delivery whose gate
+ * ran outside the CLI wrapper and emitted no `gate.reported` has a tail that
+ * looks free, and a zero printed with no label is indistinguishable from a gate
+ * that took no time. `unreadable` counts a gate completion whose `durationMs`
+ * could not be read as a number, so a partial sum is never passed off as whole.
+ *
+ * EVERY journaled gate is summed, including one superseded by a re-run. The
+ * headline outcome takes the last completion (a re-run supersedes its verdict),
+ * but the time is time: a delivery that gated twice spent both.
+ */
+export interface RunGateTime {
+  readonly totalMs: number;
+  readonly counted: number;
+  readonly unreadable: number;
+  readonly unseen: boolean;
+}
+
+/**
+ * The run's three phases, in seconds, plus what they were spent on.
+ *
+ * The boundaries are the journal's own events, so the three spans tile the
+ * run's whole span and sum back to `durationSeconds` within per-phase rounding:
+ *
+ * - implementation: the first event to the first round event;
+ * - review: that first round event to the last `review.round.closed`, which
+ *   deliberately INCLUDES the fix time between rounds — an operator asking what
+ *   review cost is asking what the loop cost, not what the reviewers were busy;
+ * - tail: the last closed round to the last event, which is `run.ended` on an
+ *   ended run and whatever the run has reached on an open one.
+ *
+ * A run with no round event has no review and no tail: implementation is the
+ * whole span, which is what a delivery that never opened a round actually did.
+ */
+export interface RunPhases {
+  readonly implementationSeconds: number;
+  readonly reviewSeconds: number;
+  readonly tailSeconds: number;
+  /** Logical rounds the journal mentions, opened or closed. */
+  readonly rounds: number;
+  readonly gate: RunGateTime;
+}
+
+/** The two kinds that bound the review phase. */
+const ROUND_KINDS: ReadonlySet<string> = new Set(["review.round.opened", "review.round.closed"]);
+
+/**
+ * An instant held inside `[low, high]`, so the phases tile the span.
+ *
+ * The journal is append-only and its instants are written by whoever holds the
+ * clock, which is not one clock: an executor on a laptop and a CLI inside a
+ * container can disagree by seconds. Without this, one skewed `at` gives a
+ * negative span — reported as zero by `spanSeconds` — and the three phases
+ * silently stop summing to the total. Clamping keeps the arithmetic true and
+ * loses only the skew, which was never measurable anyway. An unparseable
+ * instant is treated as `high`, the same way a missing one is.
+ */
+function heldWithin(value: string | undefined, low: string, high: string): string {
+  const at = value === undefined ? Number.NaN : Date.parse(value);
+  if (!Number.isFinite(at)) return high;
+  const lowAt = Date.parse(low);
+  const highAt = Date.parse(high);
+  if (!Number.isFinite(lowAt) || !Number.isFinite(highAt)) return high;
+  if (at < lowAt) return low;
+  if (at > highAt) return high;
+  return value as string;
+}
+
+/** A gate completion's duration, or nothing when it cannot be read as one. */
+const gateDurationOf = (event: RunEvent): number | undefined => {
+  const value = payloadOf(event)["durationMs"];
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+};
+
+/**
+ * The gate completions a journal carries: the CLI's own for the `gate` command,
+ * and the executor's `gate.reported` for a repository gate that is not a
+ * product command. Both are counted because they are different gates, not two
+ * writers' accounts of one — an adopter whose `npm run check` is not a product
+ * command journals only the second.
+ */
+export function projectGateTime(events: readonly RunEvent[]): RunGateTime {
+  const gates = events.filter(
+    (event) =>
+      event.kind === "gate.reported" ||
+      (event.kind === "command.completed" && event.actor.role === "cli" && payloadOf(event)["command"] === "gate"),
+  );
+  let totalMs = 0;
+  let unreadable = 0;
+  for (const gate of gates) {
+    const duration = gateDurationOf(gate);
+    if (duration === undefined) unreadable += 1;
+    else totalMs += duration;
+  }
+  return { totalMs, counted: gates.length, unreadable, unseen: gates.length === 0 };
+}
+
+/** The run's phase breakdown, derived from the journal and nothing else. */
+export function projectRunPhases(events: readonly RunEvent[]): RunPhases {
+  const startedAt = events[0]?.at ?? "";
+  const lastAt = events[events.length - 1]?.at ?? "";
+  const reviewStart = heldWithin(events.find((event) => ROUND_KINDS.has(event.kind))?.at, startedAt, lastAt);
+  const reviewEnd = heldWithin(events.findLast((event) => event.kind === "review.round.closed")?.at, reviewStart, lastAt);
+  return {
+    implementationSeconds: spanSeconds(startedAt, reviewStart),
+    reviewSeconds: spanSeconds(reviewStart, reviewEnd),
+    tailSeconds: spanSeconds(reviewEnd, lastAt),
+    rounds: roundEntries(events).length,
+    gate: projectGateTime(events),
+  };
+}
+
+/**
+ * The phase breakdown as text rows, shared by every surface that prints it.
+ *
+ * The total row repeats `durationSeconds` rather than re-deriving it, so a
+ * reader can check the three phases against the one figure `runs list` printed
+ * for the same run; `(open)` is on the total because an open run's last event
+ * is not an ending and the tail is still accruing.
+ */
+export function phaseRows(events: readonly RunEvent[]): readonly string[] {
+  const summary = summarize(events);
+  const phases = summary.phases;
+  const gate = phases.gate;
+  const gateRow = gate.unseen
+    ? "unseen — no gate completion is journaled, so any gate this delivery ran is missing from the tail above"
+    : `${durationLabel(gate.totalMs / 1000)} summed over ${gate.counted} journaled gate completion(s)` +
+      (gate.unreadable === 0 ? "" : `; ${gate.unreadable} journaled no readable duration, so the sum under-reports`);
+  return [
+    "  phases:",
+    `    implementation  ${durationLabel(phases.implementationSeconds)}  (first event to the first round)`,
+    `    review          ${durationLabel(phases.reviewSeconds)}  over ${phases.rounds} round(s), fix time between rounds included`,
+    `    tail            ${durationLabel(phases.tailSeconds)}  (last closed round to the last event)`,
+    `    gate time       ${gateRow}`,
+    `    total           ${durationLabel(summary.durationSeconds)}${summary.open ? "  (open; the tail is still accruing)" : ""}`,
+  ];
+}
+
 // ── The readout ──────────────────────────────────────────────────────────────
 
 export interface Readout {
@@ -129,6 +404,12 @@ export interface Readout {
   readonly present: readonly RunJournalRequiredEntry[];
   readonly missing: readonly RunJournalRequiredEntry[];
   readonly violations: readonly string[];
+  /**
+   * One per violation above, in the same order. The readout evaluates unbound
+   * to any record, so these explain the journal's own ordering only; the
+   * record-bound explanations are `verify`'s.
+   */
+  readonly explanations?: readonly RunJournalExplanation[];
   /** The config-presence note, present on exactly the status that it explains. */
   readonly note?: string;
 }
@@ -146,17 +427,22 @@ export interface Readout {
  * and a reader would eventually be told an entry is both present and missing —
  * which is exactly what a rewritten copy of the pairing rule did.
  */
-export function readoutOf(events: readonly RunEvent[], evaluation: RunJournalEvaluation, rootDir: string): Readout {
+export function readoutOf(events: readonly RunEvent[], evaluation: RunJournalEvaluation, rootDir?: string): Readout {
   const present = RUN_JOURNAL_REQUIRED_ENTRIES.filter((entry) => runJournalCarries(events, entry));
   const note =
-    evaluation.status === "complete-executor-only" && harnessConfigPresentAt(rootDir)
+    evaluation.status === "complete-executor-only" && rootDir !== undefined && harnessConfigPresentAt(rootDir)
       ? `no CLI gate completion in this journal; harness.config.ts present at ${oneLine(rootDir, 400)}`
       : undefined;
+  // Explained with the arguments this readout is taken with — none — so the
+  // sentences describe exactly the violations printed beside them. `verify`
+  // supplies a record and gets the record-bound explanations instead.
+  const explanations = evaluation.violations.length === 0 ? undefined : explainRunJournal(events).explanations;
   return {
     status: evaluation.status,
     present,
     missing: evaluation.missing,
     violations: evaluation.violations,
+    ...(explanations === undefined ? {} : { explanations }),
     ...(note === undefined ? {} : { note }),
   };
 }
@@ -173,7 +459,13 @@ export function readoutRows(events: readonly RunEvent[], evaluation: RunJournalE
     `    present: ${readout.present.length === 0 ? "(none)" : readout.present.join(", ")}`,
     `    missing: ${readout.missing.length === 0 ? "(none)" : [...readout.missing].join(", ")}`,
   ];
-  if (readout.violations.length > 0) rows.push(`    violations: ${[...readout.violations].join(", ")}`);
+  if (readout.violations.length > 0) {
+    rows.push(`    violations: ${[...readout.violations].join(", ")}`);
+    for (const explanation of readout.explanations ?? []) {
+      rows.push(`      ${explanation.violation}: ${oneLine(explanation.because, 400)}`);
+    }
+    rows.push("    admission: none of the above blocks admission; no gate, admission, or record decision reads a journal.");
+  }
   if (readout.note !== undefined) rows.push(`    note: ${readout.note}`);
   return rows;
 }
@@ -187,7 +479,12 @@ export interface WrittenOutcome {
 }
 
 export interface RunSummary {
-  /** From the envelope of the first event that carries one; `emit` mirrors it from the payload. */
+  /**
+   * The run's PRIMARY ticket, by the family's own rule: the first the journal
+   * names. A run that read two — a dogfood item and the ordinary item it
+   * delivered — is named here by the first, and every entry that bound no
+   * ticket of its own belongs to it.
+   */
   readonly ticket: string;
   /** A run with no `run.ended` is open, whatever else it holds. */
   readonly open: boolean;
@@ -203,6 +500,13 @@ export interface RunSummary {
    * is too.
    */
   readonly durationSeconds: number;
+  /**
+   * The same span, divided into the three phases a delivery is actually made
+   * of. Derived from the events beside it, never carried by a journal: an
+   * archive written before this member existed is projected with it, and one
+   * carrying invented phases is re-derived over its own events.
+   */
+  readonly phases: RunPhases;
   readonly roundsOpened: number;
   readonly roundsClosed: number;
   readonly findings: { readonly P0: number; readonly P1: number; readonly P2: number; readonly P3: number };
@@ -218,8 +522,18 @@ export interface RunSummary {
   readonly result?: string;
 }
 
+/**
+ * The CLI-written completion of one command that governs, which is the LAST of
+ * them — the same binding `evaluateRunJournal`'s own `cliCompletion` settled
+ * under V26-1709, for the same reason: a command is re-run to supersede its
+ * earlier outcome. The table and the completeness block sit on one row of one
+ * page, so a projection reading the first would report the outcome of a gate
+ * the delivery abandoned beside a verdict taken on the re-run —
+ * `run-01c68dea9d1d5fd0` in this repository's own store is a journal that gates
+ * twice and would read that way.
+ */
 const cliCompletionFor = (events: readonly RunEvent[], command: string): RunEvent | undefined =>
-  events.find(
+  events.findLast(
     (event) => event.kind === "command.completed" && event.actor.role === "cli" && payloadOf(event)["command"] === command,
   );
 
@@ -256,11 +570,12 @@ export function summarize(events: readonly RunEvent[]): RunSummary {
         : undefined;
 
   return {
-    ticket: oneLineOf(events.find((event) => event.ticket !== undefined)?.ticket, 128),
+    ticket: oneLineOf(runPrimaryTicket(events), 128),
     open: ended === undefined,
     startedAt,
     lastAt,
     durationSeconds: spanSeconds(startedAt, lastAt),
+    phases: projectRunPhases(events),
     roundsOpened: events.filter((event) => event.kind === "review.round.opened").length,
     roundsClosed: closed.length,
     findings: {