tumwater 0.2.0 → 0.4.0

package/dist/src/history/history-queued.js

@@ -0,0 +1,155 @@
+import { textOr } from "../text/text.js";
+import { groupBy } from "../collections.js";
+/** The merge bookkeeping resolveQueuedResult joins over: per role, the `merge_queued` pins
+ * and the `merge_done`/`merge_failed` outcomes, each list oldest-first (the scan order). Exported
+ * as one helper with exactly three call sites — readRunRows' history-row join, the failure
+ * digest's time-and-spend fold (time-spend.ts), and run-detail-data.ts — so the collectors
+ * cannot disagree about which events feed the join or in what order they sit: a fourth
+ * merge-bookkeeping event
+ * type, or a changed order rule, is edited once here. Callers bucket only the events they
+ * need; the digest folds its `review_rejected` reasons with its own pass.
+ * Roles or cutoffs are the caller's concern: pass a role-scoped or wider-read event list and
+ * the maps carry exactly that list's evidence. */
+export function bucketMergeEvents(events) {
+    const mergeQueuedByRunner = groupBy(events.filter((e) => e.type === "merge_queued"), (e) => e.source);
+    const outcomeByRunner = groupBy(events.filter((e) => e.type === "merge_done" || e.type === "merge_failed"), (e) => e.source);
+    return { mergeQueuedByRunner, outcomeByRunner };
+}
+/** Resolve one queued run row's eventual merge verdict: a "queued" run_end carries no
+ * result until its merge batch merges or fails, so the row joins its `end` run_end to the
+ * run's merge_queued pin and that pin's merge_done/merge_failed outcome (both from the
+ * bucketMergeEvents maps, oldest-first per role). The claim cursor `claimTop` (mutated in
+ * place) walks the pin list newest-first and hands each queued run the newest unclaimed pin
+ * at or before its end, so several queued runs cannot claim one pin.
+ *
+ * One change can take several merge attempts: a retriable result (RETRIABLE_MERGE_RESULTS:
+ * review_error, merge_conflict, merge_blocked) keeps the pin, and the role's next run — a
+ * leftover-recovery run that does no work of its own and ends in about a second — re-enqueues
+ * it (isRecoveryPin). The authoring run and the recovery runs resolve by different rules, so
+ * every attempt's verdict shows on exactly one row:
+ * - The run that authored the change (its pin is not a re-enqueue of a kept attempt) takes
+ *   the change's FINAL verdict, not its first attempt's: a retriable failure that recovery
+ *   later merges reads "changed" (BUGS.md 2026-10-10). While a re-enqueued attempt is still
+ *   pending the row keeps the raw "queued" label — the change is waiting to merge again, and
+ *   the failure before it already shows on the recovery run's row.
+ * - A recovery run takes the verdict of the attempt it re-enqueued — the retriable failure
+ *   that kept the pin and made the run happen (recoveredAttemptVerdict). So a change that
+ *   timed out in review seven times and was then rejected reads "rejected" once (the
+ *   authoring row) and "review failed" seven times (the authoring attempt's and six
+ *   recoveries' timeouts, each on the recovery row that followed it), not "rejected" on all
+ *   eight rows.
+ * When main moved before a retry the verification's syncPinToMain rebased the ref
+ * (merge-core.ts), so the recovery pin carries the rebased sha while each attempt's own
+ * merge_done/merge_failed logs its entry's sha (merge-slot.ts's entry.sha): the attempts' shas
+ * differ, so the authoring row's walk follows the pin sequence (isRecoveryPin), not sha
+ * equality alone. It stops at a pin that is not a recovery re-enqueue — a fresh change after a
+ * conflict-cap discard — so the row never credits a different change's verdict (BUGS.md
+ * 2026-10-10). A recovery pin whose previous attempt shows no retriable verdict (a crash
+ * left the commit unpinned or the merge unfinished, or that attempt sits outside the read) is
+ * the change's first visible attempt, so its row takes the authoring rule.
+ *
+ * `joinStarts` maps role#run to its run_start's ts; when `floorTs` (a since-window's cutoff,
+ * null in the count view) sits after that start, the row's join evidence is not whole in the
+ * windowed read and the row keeps its raw "queued" label (null). A MISSING start needs no
+ * guard — it joins, because rotation drops a prefix, so every pin older than the lost start is
+ * lost with it and nothing can be mis-claimed (and a skipped run has no start at all but is
+ * never queued). A merge with no outcome event in the join set also keeps the raw label: the
+ * conservative fallback for a verdict simply not visible here. Returns the verdict's result
+ * text plus the pin and outcome of the attempt that produced it (and that pin's sha), or null
+ * to keep the raw label. Pure apart from the cursor it owns. */
+export function resolveQueuedResult(end, mergeQueuedByRunner, outcomeByRunner, claimTop, joinStarts, floorTs) {
+    // Interlock relief (plans/interlock-relief.md): a held run's commit stayed on the branch and
+    // enqueued nothing, so its queued label names the held commit, not a merge this run made.
+    // Returning null keeps that row's raw queued label and, crucially, leaves the earlier change's
+    // merge pins unclaimed, so the verdict that belongs to the queued entry is not credited to the
+    // held run. One guard covers all three call sites (history-data.ts, time-spend.ts,
+    // run-detail-data.ts).
+    if (end.heldOnBranch === true)
+        return null;
+    if (floorTs !== null) {
+        const startTs = joinStarts.get(`${end.source}#${end.run}`);
+        if (startTs !== undefined && startTs < floorTs)
+            return null;
+    }
+    const queuedList = mergeQueuedByRunner.get(end.source);
+    if (!queuedList || queuedList.length === 0)
+        return null;
+    let top = claimTop.get(end.source) ?? queuedList.length - 1;
+    while (top >= 0 && queuedList[top].ts > end.ts)
+        top--;
+    if (top < 0)
+        return null;
+    claimTop.set(end.source, top - 1);
+    const outcomes = outcomeByRunner.get(end.source) ?? [];
+    // A recovery run's row: the attempt it re-enqueued, not the change's final verdict, so the
+    // final verdict shows once (on the authoring row) and each retriable failure once (here).
+    const recovered = recoveredAttemptVerdict(queuedList, top, outcomes);
+    if (recovered !== null)
+        return recovered;
+    // The authoring row: walk forward while the next pin is a recovery re-enqueue and resolve to
+    // the last attempt's verdict. `findLast` picks the newest same-sha outcome so an un-rebased
+    // retry (recovery re-enqueues the identical sha, logged by both pins) does not re-match the
+    // first attempt's outcome inside the recovery pin's walk. The returned pin/outcome ride the
+    // result so a caller correlating sibling evidence (the failure digest's review-failure
+    // message) can key on THIS attempt's position, not a sha a pre-review rebase may have moved
+    // (BUGS.md 2026-10-10).
+    let idx = top;
+    let resolved = null;
+    for (;;) {
+        const pin = queuedList[idx];
+        const outcome = outcomes.findLast((o) => o.ts >= pin.ts && textOr(o.commit, "") === textOr(pin.commit, ""));
+        // No outcome on the run's own pin, or on a recovery pin the walk reached: that attempt is
+        // still pending, so the change is waiting to merge — keep the raw label. The previous
+        // attempt's retriable verdict already shows on the recovery run's row.
+        if (!outcome)
+            return null;
+        const verdict = attemptVerdict(pin, outcome);
+        if (verdict === null)
+            return resolved;
+        // A merge or a rejection ends the change (the pin is discarded, so no recovery pin can
+        // follow); any other verdict kept the pin, and the walk continues only if the next pin is
+        // the recovery re-enqueue that kept it. Otherwise this attempt's verdict is the final one
+        // visible.
+        if (endsChange(verdict.result) || !isRecoveryPin(queuedList[idx + 1]))
+            return verdict;
+        resolved = verdict;
+        idx += 1;
+    }
+}
+/** The verdict one attempt's outcome carries, or null for a torn outcome with no result (a
+ * merge_failed whose result is missing or not text). A merge_done with no result is a merge. */
+function attemptVerdict(pin, outcome) {
+    const result = textOr(outcome.result, outcome.type === "merge_done" ? "changed" : "");
+    return result ? { result, sha: textOr(pin.commit, ""), pin, outcome } : null;
+}
+/** True when a verdict ends its change: a merge or a rejection discards the pin, so no recovery
+ * re-enqueue can follow it. Every other verdict (the retriable ones) kept the pin. The one rule
+ * both directions of resolveQueuedResult's chain read — the authoring row's walk forward and a
+ * recovery row's step back — so the two cannot disagree on where a change ends. */
+function endsChange(result) {
+    return result === "changed" || result === "rejected";
+}
+/** A recovery run's own row verdict: when the pin at `idx` is a recovery re-enqueue and the
+ * previous pin's attempt ended in a retriable verdict (the kept pin this run re-enqueued), that
+ * verdict, carrying the previous attempt's pin and outcome. The outcome is the newest one for
+ * the previous pin's sha logged between the two pins: recovery runs only after the previous
+ * attempt's outcome is written, and bounding at this pin keeps an un-rebased retry (both pins
+ * share a sha) from matching a LATER attempt's outcome. Null when the pin is not a recovery
+ * re-enqueue, or is one with no retriable attempt visible before it — a crash's unpinned or
+ * unfinished commit, or a previous pin outside the read — so the row takes the authoring rule. */
+function recoveredAttemptVerdict(queuedList, idx, outcomes) {
+    const pin = queuedList[idx];
+    const prev = queuedList[idx - 1];
+    if (prev === undefined || !isRecoveryPin(pin))
+        return null;
+    const outcome = outcomes.findLast((o) => o.ts >= prev.ts && o.ts <= pin.ts && textOr(o.commit, "") === textOr(prev.commit, ""));
+    const verdict = outcome === undefined ? null : attemptVerdict(prev, outcome);
+    return verdict === null || endsChange(verdict.result) ? null : verdict;
+}
+/** True when a pin re-enqueues the previous attempt's kept pin rather than starting a fresh
+ * change. `recoverLeftover` (src/runner/leftover.ts) is the one `merge_queued` producer whose
+ * summary starts with this label, so a fresh change's pin after a conflict-cap discard ends
+ * `resolveQueuedResult`'s walk. */
+function isRecoveryPin(pin) {
+    return pin !== undefined && textOr(pin.summary, "").startsWith("recovered leftover work from ");
+}

package/dist/src/history/history-render.js

@@ -1,5 +1,4 @@
-// vocabulary: plain
-/** Rendering half of `tumwater history`: format a `TickRow[]`/summary — collected by
+/** Rendering half of `tumwater history`: format a `RunRow[]`/summary — collected by
  * history-data.ts — into the aligned table or `--summary` text `cmdHistory` (history.ts)
  * prints. The sibling observing view report does the same (src/report/report.ts prints
  * src/report/report-render.ts's Markdown), and this split keeps the same separation
@@ -10,16 +9,16 @@ import { formatTimestamp, humanSeconds } from "../text/datetime.js";
 import { roleLabel } from "../roles/role-labels.js";
 import { displayWidth, padToWidth } from "../text/text-width.js";
 import { compactTokens, usd } from "../text/format.js";
-import { tickRowCells, tickRowLine } from "./history-data.js";
+import { runRowCells, runRowLine } from "./history-data.js";
 /** Each column's width from its unpadded cell. Text cells measure terminal display columns
- * (displayWidth), not UTF-16 code units: a loop name holding CJK or emoji renders two columns
+ * (displayWidth), not UTF-16 code units: a role name holding CJK or emoji renders two columns
  * per code point, and a code-unit padEnd lets that row's later columns drift right of its
- * ASCII neighbors. The tick cell measures before its "#" prefix is added (the prefix rides
+ * ASCII neighbors. The run cell measures before its "#" prefix is added (the prefix rides
  * outside the pad), and duration is ASCII, so both take plain length. */
 function widthsOf(cells) {
     return {
-        loop: displayWidth(cells.loop),
-        tick: cells.tick.length,
+        role: displayWidth(cells.role),
+        run: cells.run.length,
         result: displayWidth(cells.result),
         model: displayWidth(cells.model),
         duration: cells.duration.length,
@@ -29,11 +28,11 @@ function widthsOf(cells) {
 /** The per-column maxima over every row the table shows — the widths derive from the rows
  * actually shown, so a single-row table has no padding gap. */
 export function widestWidths(rows) {
-    const widths = { loop: 0, tick: 0, result: 0, model: 0, duration: 0, usage: 0 };
+    const widths = { role: 0, run: 0, result: 0, model: 0, duration: 0, usage: 0 };
     for (const row of rows) {
-        const w = widthsOf(tickRowCells(row));
-        widths.loop = Math.max(widths.loop, w.loop);
-        widths.tick = Math.max(widths.tick, w.tick);
+        const w = widthsOf(runRowCells(row));
+        widths.role = Math.max(widths.role, w.role);
+        widths.run = Math.max(widths.run, w.run);
         widths.result = Math.max(widths.result, w.result);
         widths.model = Math.max(widths.model, w.model);
         widths.duration = Math.max(widths.duration, w.duration);
@@ -41,22 +40,43 @@ export function widestWidths(rows) {
     }
     return widths;
 }
+/** The column-wise maximum of two width sets: the running widths of a follow, which only grow. */
+export function widenWidths(a, b) {
+    return {
+        role: Math.max(a.role, b.role),
+        run: Math.max(a.run, b.run),
+        result: Math.max(a.result, b.result),
+        model: Math.max(a.model, b.model),
+        duration: Math.max(a.duration, b.duration),
+        usage: Math.max(a.usage, b.usage),
+    };
+}
 /** One aligned table line: fixed-width columns over the row set, then the free-text detail.
  * Every cell is padded to its column's width even when empty — usage is the one cell that can
- * be empty (a tick with neither tokens nor cost), and dropping it would pull the detail left,
- * misaligning that row against its neighbors; tickRowLine strips only the trailing pad. The
- * row's column order rides history-data.ts's tickRowLine, shared with the grep haystack so the
+ * be empty (a run with neither tokens nor cost), and dropping it would pull the detail left,
+ * misaligning that row against its neighbors; runRowLine strips only the trailing pad. The
+ * row's column order rides history-data.ts's runRowLine, shared with the grep haystack so the
  * two cannot disagree about which field sits where. */
 export function renderRow(row, widths) {
-    return tickRowLine(row, (column, value) => padToWidth(value, widths[column]));
+    return runRowLine(row, (column, value) => padToWidth(value, widths[column]));
 }
-/** The `--summary` text: a header, one line per loop, then the total line. The loop column pads to
+/** The `--summary` text: a header, one line per role, then the total line. The role column pads to
  * display width; each number column right-aligns under its header; the `time` column is the sum of
  * each role's run spans, `—` when none of the role's rows carried a span; the last column,
  * `last change`, is the newest change's timestamp (`—` when none) and is left-aligned, unpadded. */
 export function renderSummary(summary) {
-    const all = [...summary.roles, summary.total];
-    const loopWidth = Math.max(...["role", ...all.map((r) => roleLabel(r.role))].map(displayWidth));
+    return renderSummaryTable("role", [...summary.roles, summary.total].map((row) => ({ label: roleLabel(row.role), row })));
+}
+/** The `--summary --by model` text: renderSummary's table with one line per model (`(unknown)` for
+ * the null bucket), then the total line. */
+export function renderModelSummary(summary) {
+    return renderSummaryTable("model", [
+        ...summary.models.map((row) => ({ label: row.model ?? "(unknown)", row })),
+        { label: "total", row: summary.total },
+    ]);
+}
+function renderSummaryTable(header, all) {
+    const roleWidth = Math.max(...[header, ...all.map((r) => r.label)].map(displayWidth));
     const cols = ["runs", "changes", "none", "refused", "problems", "tokens", "cost", "time"];
     const cell = (r, c) => c === "tokens"
         ? compactTokens(r.tokens)
@@ -67,10 +87,10 @@ export function renderSummary(summary) {
                     ? "—"
                     : humanSeconds(r.durationMs / 1000)
                 : String(c === "runs" ? r.runs : r[c]);
-    const widths = cols.map((c) => Math.max(c.length, ...all.map((r) => cell(r, c).length)));
-    const line = (loop, cells, lastChange) => [padToWidth(loop, loopWidth), ...cells.map((c, i) => c.padStart(widths[i] ?? 0)), lastChange].join("  ").trimEnd();
+    const widths = cols.map((c) => Math.max(c.length, ...all.map((r) => cell(r.row, c).length)));
+    const line = (role, cells, lastChange) => [padToWidth(role, roleWidth), ...cells.map((c, i) => c.padStart(widths[i] ?? 0)), lastChange].join("  ").trimEnd();
     return [
-        line("role", [...cols], "last change"),
-        ...all.map((r) => line(roleLabel(r.role), cols.map((c) => cell(r, c)), r.lastChangeTs === null ? "—" : formatTimestamp(r.lastChangeTs))),
+        line(header, [...cols], "last change"),
+        ...all.map(({ label, row }) => line(label, cols.map((c) => cell(row, c)), row.lastChangeTs === null ? "—" : formatTimestamp(row.lastChangeTs))),
     ].join("\n");
 }

package/dist/src/history/history.js

@@ -1,14 +1,30 @@
-// vocabulary: plain
-import { fail, say, sayJson } from "../cli/cli-output.js";
-import { durationLabel, failRivalShapes, flagValue, parseCountFlag, parseGrepFlag, parseRoleScope, parseSinceFlag } from "../cli/cli-args.js";
-import { HISTORY_DEFAULT_TICKS, HISTORY_MAX_TICKS, HISTORY_RESULT_FLAG_NAMES, historyClass, parseHistoryResultClass, readTickRows, readTickRowsSince, summarizeTickRows, tickRowsMatchingGrep } from "./history-data.js";
-import { renderRow, renderSummary, widestWidths } from "./history-render.js";
+import { fail, say, sayJson, sayJsonLine } from "../cli/cli-output.js";
+import { durationLabel, failRivalShapes, failUntilShorterThanSince, flagValue, parseCountFlag, parseGrepFlag, parseRoleListScope, parseSinceFlag, rejectFlagLookingValue } from "../cli/cli-args.js";
+import { HISTORY_DEFAULT_RUNS, HISTORY_MAX_RUNS, HISTORY_RESULT_FLAG_NAMES, HISTORY_SUMMARY_GROUPS, historyClass, parseHistoryResultClass, readRunRows, readRunRowsSince, runRows, summarizeRunRows, summarizeRunRowsByModel, runRowsMatchingGrep, runRowsOnModels } from "./history-data.js";
+import { renderModelSummary, renderRow, renderSummary, widenWidths, widestWidths } from "./history-render.js";
 import { LOGS_SINCE_MAX_MS, SPARSE_WINDOW_NOTE } from "../events/event-window.js";
-import { gotSuffix } from "../text/text.js";
+import { followUntilParentGone } from "../cli/log-commands.js";
+import { hasFollowFlag } from "../cli/cli-flag-specs.js";
+import { parseEventLine, readEventsTailWithEnd } from "../events/event-read.js";
+import { eventsLogPath } from "../paths.js";
+import { gotSuffix, splitCommaList, splitCommaListUnique } from "../text/text.js";
+import { trimToLast } from "../collections.js";
 import { typoSuffix } from "../text/suggest.js";
-/** `tumwater history [--role <id>] [-n N]`: one row per completed tick, newest first. The
+/** Parse a `--model` value: a comma list of model selectors, deduplicated in first-seen order.
+ * A missing, empty or all-commas value fails with HISTORY_MODEL_VALUE_ERROR; selectors have no
+ * closed vocabulary, so none is rejected as unknown. Shared by the listing and the one-run
+ * trail's `--last --model`. */
+export function parseHistoryModelList(raw) {
+    if (raw === undefined || raw === "")
+        fail(HISTORY_MODEL_VALUE_ERROR);
+    const pieces = splitCommaListUnique(raw);
+    if (pieces.length === 0)
+        fail(HISTORY_MODEL_VALUE_ERROR);
+    return pieces;
+}
+/** `tumwater history [--role <id>[,<id>...]] [-n N]`: one row per completed run, newest first. The
  * observing half beside cmdLogs (log-commands.ts): read-only over the event log, stdout only —
- * every datum rides the `run_end` events src/tick/tick-finalize.ts already writes, so this
+ * every datum rides the `run_end` events src/run/run-finalize.ts already writes, so this
  * is a rendering of the existing record, not a new one. The rows themselves are collected
  * by history-data.ts (beside src/report/report-data.ts and src/failure/failure-data.ts), and
  * the aligned table/summary text they print is rendered by history-render.ts (beside
@@ -23,14 +39,46 @@ export const HISTORY_GREP_VALUE_ERROR = "history --grep needs a pattern";
  * same wording. Its sibling of HISTORY_GREP_VALUE_ERROR: each names the command that printed
  * it. */
 export const HISTORY_RESULT_VALUE_ERROR = "history --result needs a value";
-/** `tumwater history [--role <id>] [-n N] [--since <duration>] [--grep <text>] [--result
- * <class>]`: print the last N completed ticks, newest first — or, with `--since`, the ticks of a
- * bounded past window over the same record, the same shape `logs --since` and `report --since`
- * speak. `--grep` keeps rows whose rendered line matches, and `--result` narrows to one outcome
- * class (changes/none/problems, the dashboard History filter's buckets); both compose with
- * --role, -n, and --since. Read-only: stdout only, no state file created — a missing or empty
+/** The missing-value error cmdHistory prints for a valueless, empty or comma-only `--model`,
+ * exported so cli.ts's rejectUnknownArgs spec for --model fails a trailing `history --model`
+ * with the same wording. Its sibling of HISTORY_RESULT_VALUE_ERROR. */
+export const HISTORY_MODEL_VALUE_ERROR = "history --model needs a model selector";
+/** The missing-value error for a valueless or empty `--by`, exported for cli.ts's flag spec. */
+export const HISTORY_BY_VALUE_ERROR = "history --by needs role or model";
+/** How many trailing events `history -f` keeps: the seed read and the rolling buffer a finished
+ * run's start is paired from. */
+const HISTORY_FOLLOW_BUFFER_EVENTS = 2000;
+/** Parse a `--result` value: a comma list of outcome classes (the spellings
+ * HISTORY_RESULT_FLAG_NAMES prints, plus the hidden `changes` alias), deduplicated in first-seen
+ * order. A missing, empty or all-commas value fails with HISTORY_RESULT_VALUE_ERROR; the first
+ * unknown piece fails naming the accepted classes (gotSuffix plus a did-you-mean hint). Shared by
+ * the listing and the one-run trail's `--last --result`. */
+export function parseHistoryResultList(raw) {
+    if (raw === undefined || raw === "")
+        fail(HISTORY_RESULT_VALUE_ERROR);
+    const pieces = splitCommaList(raw);
+    if (pieces.length === 0)
+        fail(HISTORY_RESULT_VALUE_ERROR);
+    const parsed = [];
+    for (const piece of pieces) {
+        const cls = parseHistoryResultClass(piece);
+        if (cls === null)
+            fail(`history --result must be one of ${Object.values(HISTORY_RESULT_FLAG_NAMES).join(", ")}${gotSuffix(piece)}${typoSuffix(piece, Object.values(HISTORY_RESULT_FLAG_NAMES))}`);
+        if (!parsed.includes(cls))
+            parsed.push(cls);
+    }
+    return parsed;
+}
+/** `tumwater history [--role <id>[,<id>...]] [-n N] [-f] [--since <duration>]
+ * [--until <duration>] [--grep <text>] [--result <class>] [--model <selector>[,...]]`: print the
+ * last N completed runs, newest first — or,
+ * with `--since`, the runs of a bounded past window over the same record, the same shape
+ * `logs --since` and `report --since` speak. `--grep` keeps rows whose rendered line matches,
+ * `--result` narrows to the listed outcome classes (changes/none/problems, the dashboard History
+ * filter's buckets) and `--model` keeps runs that started on the listed models; all compose
+ * with --role, -n, and --since. Read-only: stdout only, no state file created — a missing or empty
  * event log prints `no runs yet` and exits 0. */
-export async function cmdHistory(root, args) {
+export async function cmdHistory(root, args, seams = {}) {
     // `--grep <text>` filters the row set case-insensitively against the WYSIWYG row line (plus a
     // `run_end` prefix, the same haystack rule logs --grep applies to its rendered lines), so
     // both observing views answer substring questions the same way. The flag scan itself — the
@@ -40,7 +88,7 @@ export async function cmdHistory(root, args) {
     // --grep, rest is args.
     const { rest, pattern: grepPattern } = parseGrepFlag(args, HISTORY_GREP_VALUE_ERROR);
     const nRaw = flagValue(rest, "-n");
-    // `--since <duration>` is the window-shaped view over the same tick record the -n view
+    // `--since <duration>` is the window-shaped view over the same run record the -n view
     // dumps: a rival shape to -n, so they fail together naming both (the same rule and wording
     // shape logs uses). It reuses the logs --since cap (same log, same cap — no third cap
     // value) through parseSinceFlag, so the error wordings cannot drift. `--role` composes with
@@ -48,66 +96,108 @@ export async function cmdHistory(root, args) {
     // against.
     let rows;
     let covered = true;
+    const follow = hasFollowFlag(rest);
+    if (follow) {
+        if (rest.includes("--since"))
+            failRivalShapes("history --since", "-f/--follow", 'follow means "from now on"; --since shows a bounded past window');
+        if (rest.includes("--summary"))
+            failRivalShapes("history --summary", "-f/--follow", "a summary tallies a bounded set; -f follows from now on");
+    }
+    const followTail = follow ? readEventsTailWithEnd(root, HISTORY_FOLLOW_BUFFER_EVENTS) : null;
     const sinceMs = parseSinceFlag(rest, "history --since", LOGS_SINCE_MAX_MS);
-    if (sinceMs !== null) {
+    const untilMs = parseSinceFlag(rest, "history --until", LOGS_SINCE_MAX_MS, "--until");
+    failUntilShorterThanSince("history", untilMs, sinceMs);
+    if (followTail !== null) {
+        const limit = nRaw !== null ? parseCountFlag("-n", nRaw, HISTORY_MAX_RUNS) : HISTORY_DEFAULT_RUNS;
+        // The seed goes through readRunRows, which widens its window until it finds `limit` rows;
+        // the tail buffer only feeds the live follow.
+        rows = readRunRows(root, limit, parseRoleListScope(root, rest));
+    }
+    else if (sinceMs !== null) {
         if (nRaw !== null)
             failRivalShapes("history --since", "-n", "a count and a window are rival shapes");
-        const role = parseRoleScope(root, rest);
-        const windowed = readTickRowsSince(root, sinceMs, role);
+        const role = parseRoleListScope(root, rest);
+        const windowed = readRunRowsSince(root, sinceMs, role, untilMs);
         rows = windowed.rows;
         covered = windowed.covered;
     }
     else {
         // parseCountFlag's max caps the scan window: a typo'd "999999" must not build a
-        // HISTORY_MAX_TICKS-sized slice scan from a huge limit.
-        const limit = nRaw !== null ? parseCountFlag("-n", nRaw, HISTORY_MAX_TICKS) : HISTORY_DEFAULT_TICKS;
+        // HISTORY_MAX_RUNS-sized slice scan from a huge limit.
+        const limit = nRaw !== null ? parseCountFlag("-n", nRaw, HISTORY_MAX_RUNS) : HISTORY_DEFAULT_RUNS;
         // The config is read (through loadConfigCached, never throwing) only when --role is present:
         // a read-only view must not refuse a transiently broken tumwater.json.
-        const role = parseRoleScope(root, rest);
-        rows = readTickRows(root, limit, role);
+        const role = parseRoleListScope(root, rest);
+        rows = readRunRows(root, limit, role);
     }
     // The filter runs on the collected rows, before rendering and before --json serialization:
     // the same rows the table would print, filtered the same way in both forms (the logs --grep
     // rule: -n bounds the scanned window, not the printed rows).
     if (grepPattern !== null)
-        rows = tickRowsMatchingGrep(rows, grepPattern);
+        rows = runRowsMatchingGrep(rows, grepPattern);
     // The set --grep admitted, saved so the empty-state wording blames the filter that actually
     // emptied it: if the result filter below removes rows grep matched, naming the pattern would
     // be false (`no runs matching "widget"` when feature #7 does match). The GUI draws the same
     // line between a search and its outcome filter.
     const afterGrep = rows.length;
-    // `--result <class>` narrows to one outcome bucket, reading the same canonical historyClass
-    // rule the dashboard's History filter applies (shared from history-data.ts, not copied). It
-    // composes with --role, -n, --since, and --grep, so no rival-shape rule: a missing or empty
-    // value fails with its own wording, and an unknown class names the accepted ones (the gotSuffix
-    // shape the other flag validators use, plus a did-you-mean hint for a near-miss of a real
-    // result — the same typoSuffix treatment `logs --type` gives its codes). Applied after --grep,
-    // over the same rows both the table
+    // `--result <class>[,<class>...]` narrows to the listed outcome buckets, reading the same
+    // canonical historyClass rule the dashboard's History filter applies (shared from
+    // history-data.ts, not copied). It composes with --role, -n, --since, and --grep, so no
+    // rival-shape rule: a missing or empty value fails with its own wording, and an unknown
+    // class names the accepted ones (the gotSuffix shape the other flag validators use, plus a
+    // did-you-mean hint for a near-miss of a real result — the same typoSuffix treatment
+    // `logs --type` gives its codes). Applied after --grep, over the same rows both the table
     // and --json serialize.
-    const resultRaw = flagValue(rest, "--result");
-    let resultClass = null;
+    const resultRaw = rejectFlagLookingValue("history --result", flagValue(rest, "--result"));
+    let resultClasses = null;
     if (resultRaw !== null) {
-        if (resultRaw === undefined || resultRaw === "")
-            fail(HISTORY_RESULT_VALUE_ERROR);
-        resultClass = parseHistoryResultClass(resultRaw);
-        if (resultClass === null)
-            fail(`history --result must be one of ${Object.values(HISTORY_RESULT_FLAG_NAMES).join(", ")}${gotSuffix(resultRaw)}${typoSuffix(resultRaw, Object.values(HISTORY_RESULT_FLAG_NAMES))}`);
-        rows = rows.filter((r) => historyClass(r.result) === resultClass);
+        const wanted = parseHistoryResultList(resultRaw);
+        resultClasses = wanted;
+        rows = rows.filter((r) => wanted.includes(historyClass(r.result)));
+    }
+    // `--model <selector>[,...]` keeps the rows whose run_start named exactly one of the listed
+    // selectors (case-sensitive, the strings `--summary --by model` prints); a null-model row never
+    // matches. An unknown selector is not an error: models have no closed vocabulary and an old log
+    // holds models the config has since dropped, so it simply keeps no rows.
+    const afterResult = rows.length;
+    const modelRaw = rejectFlagLookingValue("history --model", flagValue(rest, "--model"));
+    let models = null;
+    if (modelRaw !== null) {
+        const pieces = parseHistoryModelList(modelRaw);
+        models = pieces;
+        rows = runRowsOnModels(rows, pieces);
+    }
+    if (followTail !== null) {
+        await followHistory(root, rest, rows, followTail, (r) => rowKept(r, grepPattern, resultClasses, models), seams, rest.includes("--json"));
+        return;
     }
     // --json swaps the renderer for the collector's own payload, exactly as status --json and
     // report --json: the same rows the table prints, each with ts/tokens/costUsd kept raw. A
     // JSON document even when the log is empty ({"rows":[]} — never the prose `no runs yet`,
     // the report --json precedent: the flag's output must be parseable in every exit-0 case).
+    // `--by role|model` picks how --summary groups its lines (role by default).
+    const byRaw = flagValue(rest, "--by");
+    let byModel = false;
+    if (rest.includes("--by")) {
+        if (!byRaw)
+            return fail(HISTORY_BY_VALUE_ERROR);
+        if (!HISTORY_SUMMARY_GROUPS.includes(byRaw)) {
+            fail(`history --by must be one of ${HISTORY_SUMMARY_GROUPS.join(", ")}${gotSuffix(byRaw)}${typoSuffix(byRaw, [...HISTORY_SUMMARY_GROUPS])}`);
+        }
+        if (!rest.includes("--summary"))
+            fail("history --by needs --summary (it picks how the summary groups runs)");
+        byModel = byRaw === "model";
+    }
     const summary = rest.includes("--summary") && rows.length > 0;
     if (rest.includes("--json")) {
-        sayJson(summary ? summarizeTickRows(rows) : { rows });
+        sayJson(summary ? (byModel ? summarizeRunRowsByModel(rows) : summarizeRunRows(rows)) : { rows });
         return;
     }
     if (rows.length === 0) {
         // A grep that matched nothing must not borrow the empty-log prose: `no runs yet` and
         // `no runs in 2h` are statements about the LOG and the WINDOW, and both are false when
         // rows were scanned and filtered out — the operator would read a quiet team where the
-        // truth is `the ticks are there, none match`. The logs --grep rule (its `no events
+        // truth is `the runs are there, none match`. The logs --grep rule (its `no events
         // matching "<pattern>"`, src/cli/log-commands.ts) names the pattern instead; --json stays
         // a bare {"rows":[]} document above, never prose in either form.
         //
@@ -115,17 +205,21 @@ export async function cmdHistory(root, args) {
         // empty log or window scanned no rows, so the result filter removed nothing and the
         // empty-log/window prose is the true one — the dashboard's History view draws the same
         // line. A grep that admitted nothing keeps its own wording regardless of --result.
-        say(resultClass !== null && afterGrep > 0
-            ? `no runs with result "${resultClass}"`
-            : grepPattern !== null
-                ? `no runs matching "${grepPattern}"`
-                : sinceMs === null
-                    ? "no runs yet"
-                    : `no runs in ${durationLabel(sinceMs)}`);
+        say(models !== null && afterResult > 0
+            ? `no runs on model "${models.join(",")}"`
+            : resultClasses !== null && afterGrep > 0
+                ? `no runs with result "${resultClasses.join(",")}"`
+                : grepPattern !== null
+                    ? `no runs matching "${grepPattern}"`
+                    : sinceMs === null
+                        ? "no runs yet"
+                        : untilMs === null
+                            ? `no runs in ${durationLabel(sinceMs)}`
+                            : `no runs between ${durationLabel(sinceMs)} and ${durationLabel(untilMs)} ago`);
         return;
     }
     if (summary)
-        say(renderSummary(summarizeTickRows(rows)));
+        say(byModel ? renderModelSummary(summarizeRunRowsByModel(rows)) : renderSummary(summarizeRunRows(rows)));
     else {
         const widths = widestWidths(rows);
         say(rows.map((r) => renderRow(r, widths)).join("\n"));
@@ -137,3 +231,50 @@ export async function cmdHistory(root, args) {
     if (!covered)
         say(SPARSE_WINDOW_NOTE);
 }
+/** The row filters `--grep`, `--result` and `--model` apply, as one predicate for followed rows. */
+function rowKept(row, grep, classes, models) {
+    if (grep !== null && runRowsMatchingGrep([row], grep).length === 0)
+        return false;
+    if (classes !== null && !classes.includes(historyClass(row.result)))
+        return false;
+    return models === null || runRowsOnModels([row], models).length > 0;
+}
+/** `history -f`: print the seed rows oldest first, then one row per `run_end` as it lands. A run
+ * whose change waits to merge prints `queued` and no second line when the merge resolves. With
+ * `json`, each row is one `sayJsonLine` object (the `history --json` row shape), nothing else. */
+async function followHistory(root, rest, seed, tail, keep, seams, json) {
+    const ordered = [...seed].reverse();
+    let widths = widestWidths(ordered);
+    if (json)
+        for (const r of ordered)
+            sayJsonLine(r);
+    else if (ordered.length > 0)
+        say(ordered.map((r) => renderRow(r, widths)).join("\n"));
+    const seen = new Set(seed.map((r) => `${r.role}#${r.run}`));
+    const buffer = [...tail.events];
+    const role = parseRoleListScope(root, rest);
+    await followUntilParentGone(eventsLogPath(root), tail.coveredEnd, (lines) => {
+        for (const line of lines.filter(Boolean)) {
+            const e = parseEventLine(line);
+            if (!e)
+                continue;
+            buffer.push(e);
+            trimToLast(buffer, HISTORY_FOLLOW_BUFFER_EVENTS);
+            if (e.type !== "run_end")
+                continue;
+            const row = runRows(buffer, 1, role)[0];
+            if (!row)
+                continue;
+            const key = `${row.role}#${row.run}`;
+            if (seen.has(key) || !keep(row))
+                continue;
+            seen.add(key);
+            if (json) {
+                sayJsonLine(row);
+                continue;
+            }
+            widths = widenWidths(widths, widestWidths([row]));
+            say(renderRow(row, widths));
+        }
+    }, seams);
+}