tumwater 0.2.0 → 0.4.0

package/dist/src/tick/stage-check.js

@@ -1,419 +0,0 @@
-// vocabulary: plain
-/** The merge gate's deterministic checks, run BEFORE a changed tick commits.
- *
- * The gate runs `backlogStructureReason` and `falseFixReason` at merge time, by which point
- * the author's session is over: a finding costs a queue slot, a verification, and a rejection that
- * discards the work (13 phantom-fix rejections between 2026-09-23 and 2026-10-02). Both checks
- * read the worktree and the change's merge-base, so the same questions can be asked at staging
- * time, while the authoring session can still be continued for one fix-up turn. This module
- * runs them over the tick's uncommitted edits; the gate still has the final say.
- *
- * Scope mirrors the gate exactly: `backlogStructureReason` runs on every changed tick, while
- * `falseFixReason` runs only for an exempt (doc-only) diff — the condition under which the gate
- * consults it.
- *
- * Part 2/2 appends git-level, language-neutral findings (PLANS.md "Pre-queue self-check, part
- * 2/2") for path drift, the organize loop's main rejection cause: references left behind by a
- * rename or delete, added lines naming paths that do not exist in the resulting tree, and text
- * files whose final newline the change removed. These stage the change (`git add -A`) to read
- * the index with git only, then restore the index to HEAD before returning: staging is a read
- * aid for the checks, not a change to the tick's state. A git hiccup yields no finding rather
- * than failing the tick. Unlike the backlog checks above, the gate does not run these: they are
- * heuristics for what a reviewer tends to reject, so neither path check looks inside record
- * prose (isRecordProse), where an old or not-yet-created path is correct as written.
- *
- * `planDependencyFinding` is staging-only: it is not part of the review gate or the in-lock
- * merge re-check, because `tumwater doctor`'s plan-dependency warning is the backstop for
- * anything that gets past the fix-up turn. `waitingNoteFinding` is staging-only and bugfix-only
- * for the same reason: it nudges a bugfix run that left a Progress note without the hold. */
-import path from "node:path";
-import { changedFiles } from "../git/git-diff.js";
-import { conflictMarkerReason } from "../merge/merge-git.js";
-import { isExemptDiff } from "../review/exemptions.js";
-import { backlogStructureReason } from "../backlog/backlog-structure.js";
-import { protectedEditReason } from "../review/protected-edits.js";
-import { secretLeakReason } from "../review/secret-leaks.js";
-import { falseFixReason } from "../verdict/fix-claim.js";
-import { changeBaseRev, fileContentAt } from "../git/git.js";
-import { readTextOrNull } from "../files/files.js";
-import { BACKLOG_FILES, finishedArchiveOf, parseEntryDetails } from "../backlog/backlog-md.js";
-import { entryKey, planDependencyProblems, refusalNote, waitingNote } from "../backlog/backlog-eligibility.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
-import { WAITING_FOR_FAILURE_NOTE } from "../roles/role-guidance.js";
-import { gitTry } from "../git/git-run.js";
-import { moreSuffix } from "../text/phrases.js";
-/** Where finished plans are archived (plans/backlog-archive.md). */
-const PLANS_ARCHIVE = finishedArchiveOf("PLANS.md").archive;
-/** How many `file:line` hits a single stale-reference finding lists before it stops. */
-const MAX_STALE_HITS = 10;
-/** How many renamed/deleted paths each stale-reference finding reports before stopping — the
- * cap that keeps a 40-file rename to a bounded finding list. */
-const MAX_STALE_PATHS = 10;
-/** How many nonexistent added paths one finding names before it stops. */
-const MAX_MISSING_PATHS = 10;
-/** How many files one lost-final-newline finding names before it stops. */
-const MAX_NEWLINE_FILES = 10;
-/** The path a unified diff's `+++ b/<path>` header names. Strips the four-character `+++ `
- * marker and git's `b/` prefix. A deleted file's new side is `+++ /dev/null`, which carries no
- * `b/` prefix and is returned as `/dev/null`. */
-function diffPlusPath(line) {
-    return line.slice(4).replace(/^b\//, "");
-}
-/** True for record prose: a backlog file (BACKLOG_FILES: PLANS.md, BUGS.md, QUESTIONS.md and the
- * finished-entry archives) or a markdown design doc under `plans/`. They record history and
- * describe planned work, so a path there is correct as written even when it is absent from the
- * tree: a finished entry names a file as it was, and a plan names the file it will create or
- * both sides of the move it describes. Asking a rename to sweep them rewrote "old → new" into
- * "new → new" and history into the present; that failure took five rejections on
- * one rename on 2026-10-18 and -19. */
-function isRecordProse(file) {
-    const base = file.slice(file.lastIndexOf("/") + 1);
-    return BACKLOG_FILES.has(base) || (file.startsWith("plans/") && file.endsWith(".md"));
-}
-/** The capped list a finding line appends: at most `max` entries joined by ", ", then
- * `moreSuffix` for the rest. Shared by the missing-path and lost-final-newline findings so both
- * cap and join identically. */
-function cappedList(items, max) {
-    const shown = items.slice(0, max);
-    return `${shown.join(", ")}${moreSuffix(items.length - shown.length)}`;
-}
-/** The finding for the heading `requires` clause problems that `head` (the edited PLANS.md)
- * adds over `base` (its text at the merge-base), or undefined when it adds none; `archivedTitles`
- * (PLANS-DONE.md's headings) count as existing headings on both sides. Only new
- * problems count: one already on main is not this run's fault and stays doctor's to report, so
- * the author is never asked to fix another run's heading. The most serious new problem is named
- * — cycle, then dangling, unparsed, then misworded — with a count of the rest. */
-export function planDependencyFinding(head, base, archivedTitles = []) {
-    const problems = (text) => planDependencyProblems(parseEntryDetails(text, "Planned"), [...parseEntryDetails(text, "Done").map((e) => e.title), ...archivedTitles]);
-    const was = problems(base);
-    const now = problems(head);
-    const newCycle = now.cycle !== null && was.cycle === null ? now.cycle : null;
-    const newDangling = now.dangling.filter((d) => !was.dangling.some((b) => b.title === d.title && b.ref === d.ref));
-    const newUnparsed = now.unparsed.filter((t) => !was.unparsed.includes(t));
-    const newMisworded = now.misworded.filter((m) => !was.misworded.some((b) => b.title === m.title && b.ref === m.ref));
-    const total = (newCycle !== null ? 1 : 0) + newDangling.length + newUnparsed.length + newMisworded.length;
-    if (total === 0)
-        return undefined;
-    let first;
-    if (newCycle !== null) {
-        first = `PLANS.md's requires clauses now form a cycle: ${newCycle.join(" → ")} — every part on it stays blocked forever; ` + // vocabulary-ok: PLANS.md heading syntax
-            "edit one heading's `requires … landed` clause to break it"; // vocabulary-ok: PLANS.md heading syntax
-    }
-    else if (newDangling.length > 0) {
-        const d = newDangling[0];
-        first = `PLANS.md plan "${d.title}" requires ${d.ref}, which no PLANS.md heading carries — the claim allocator ` +
-            "ignores the clause and hands the plan out now; fix the series name or part number to match the prerequisite's heading";
-    }
-    else if (newUnparsed.length > 0) {
-        first = `PLANS.md plan "${newUnparsed[0]}" has a \`requires … landed\` clause that names no part the claim allocator can read — ` + // vocabulary-ok: PLANS.md heading syntax
-            "it holds nothing; write each ref as `<Series> i/n` or `part i/n` after a `<Series>, part i/n:` heading prefix";
-    }
-    else {
-        const w = newMisworded[0];
-        first = `PLANS.md plan "${w.title}" names ${w.ref} as a prerequisite without a \`requires … landed\` clause — ` + // vocabulary-ok: PLANS.md heading syntax
-            "the claim allocator ignores that wording and hands the part out now; write it as `requires part i/n landed` — fix it before this change commits"; // vocabulary-ok: PLANS.md heading syntax
-    }
-    return `${first}${moreSuffix(total - 1)}`;
-}
-/** The number of `- **Progress …` lines in an entry body. */
-function progressCount(body) {
-    return body.split("\n").filter((l) => /^-\s+\*\*Progress\b/.test(l.trim())).length;
-}
-/** The finding for a BUGS.md bug that `head` (the edited file) shows with more Progress notes
- * than `base` (its text at the merge-base) while it stays under `## Open` with neither a Waiting
- * note nor a Refused note — bugfix's step 2 asks a run that cannot reproduce a bug to write the
- * Waiting note, and runs that skip it leave the bug open to re-investigation. A newly filed bug
- * is not a re-investigation. Names the first such bug in file order, with a count of the rest. */
-export function waitingNoteFinding(head, base) {
-    const was = new Map(parseEntryDetails(base, "Open").map((e) => [entryKey(e.title), e.body]));
-    const counting = parseEntryDetails(head, "Open").filter((e) => {
-        const before = was.get(entryKey(e.title));
-        return (before !== undefined &&
-            progressCount(e.body) > progressCount(before) &&
-            waitingNote(e.body) === null &&
-            refusalNote(e.body) === null);
-    });
-    if (counting.length === 0)
-        return undefined;
-    return (`BUGS.md bug "${counting[0].title}" gained a Progress note but stays open with no Waiting for the next ` +
-        `failure note — if this run could not reproduce it, add ${WAITING_FOR_FAILURE_NOTE} as its own line under ` +
-        `the heading so later runs wait for new evidence (bugfix's step 2); if it did reproduce, leave the entry ` +
-        `as it is${moreSuffix(counting.length - 1)}`);
-}
-/** The findings likely to get this uncommitted change rejected at merge, or an empty list when
- * it is clean: the merge gate's own deterministic checks plus the staging-only heuristics (plan
- * dependencies, the bugfix Waiting note, path drift). Checks the worktree at `wt` against
- * `mainBranch`'s merge-base; `exemptPaths` are the config's review-exemption globs that scope
- * the false-fix check.
- *
- * Never throws: a check that fails yields no finding, so a git hiccup at staging time defers to
- * the gate instead of failing the tick. */
-export async function stageCheckFindings(wt, mainBranch, exemptPaths, role) {
-    const files = await changedFiles(wt).catch(() => null);
-    if (files === null || files.length === 0)
-        return [];
-    const findings = [];
-    const structure = await backlogStructureReason(wt, mainBranch, files).catch(() => undefined);
-    if (structure)
-        findings.push(structure);
-    if (files.includes("PLANS.md")) {
-        const head = readTextOrNull(path.join(wt, "PLANS.md")) ?? "";
-        const base = await fileContentAt(wt, await changeBaseRev(wt, mainBranch), "PLANS.md").catch(() => undefined);
-        // Finished plans are archived in PLANS-DONE.md (plans/backlog-archive.md): a requires clause
-        // naming a merged part resolves there, on both sides of the comparison alike.
-        const archived = parseEntryDetails(readTextOrNull(path.join(wt, PLANS_ARCHIVE)) ?? "", "Done").map((e) => e.title);
-        const dependency = base === undefined ? undefined : planDependencyFinding(head, base, archived);
-        if (dependency !== undefined)
-            findings.push(dependency);
-    }
-    if (baseRoleOf(role) === "bugfix" && files.includes("BUGS.md")) {
-        const head = readTextOrNull(path.join(wt, "BUGS.md")) ?? "";
-        const base = await fileContentAt(wt, await changeBaseRev(wt, mainBranch), "BUGS.md").catch(() => undefined);
-        const waiting = base === undefined ? undefined : waitingNoteFinding(head, base);
-        if (waiting !== undefined)
-            findings.push(waiting);
-    }
-    const protectedReason = await protectedEditReason(wt, mainBranch, files, role).catch(() => undefined);
-    if (protectedReason)
-        findings.push(protectedReason);
-    const secretReason = await secretLeakReason(wt, mainBranch, files).catch(() => undefined);
-    if (secretReason)
-        findings.push(secretReason);
-    if (isExemptDiff(files, exemptPaths)) {
-        const falseFix = await falseFixReason(wt, mainBranch, files).catch(() => undefined);
-        if (falseFix)
-            findings.push(falseFix);
-    }
-    findings.push(...(await gitLevelFindings(wt, mainBranch).catch(() => [])));
-    const markers = conflictMarkerReason(wt, files);
-    if (markers !== undefined)
-        findings.push(markers);
-    return findings;
-}
-/** The staging finding for a tick that holds a claim but moved a different backlog entry
- * (plans/parallel-work-instances.md "Claims", part 4/7): the assigned entry is the instance's
- * one task, so moving another is the same class of mistake `backlogStructureReason` catches
- * and costs one fix-up turn before the change commits. undefined when nothing moved or the
- * claimed entry itself moved — a merged entry is the expected way to release a claim. */
-export function assignedMovedFinding(claimKey, moved) {
-    if (moved.length === 0 || moved.some((m) => m.key === claimKey))
-        return undefined;
-    return `this run is assigned one backlog entry but moved a different one: "${moved[0].title}"`;
-}
-/** The staging finding for an unassigned tick that moved a backlog entry a sibling instance
- * holds — one the poll listed in the tick's `<held-entries>` note (LoopState.heldElsewhere).
- * The note is advice the model can ignore; this is the deterministic backstop at the same
- * point as assignedMovedFinding (BUGS.md 2026-10-12: 24 of 29 staged claims duplicated a
- * sibling's held entry, and each duplicate cost a gate check, a review, and a conflict
- * resolver run holding the merge slot). The fix-up turn is asked to drop the duplicate work.
- * A change that held nothing else then ends with no change to merge. undefined when no moved
- * entry is held. */
-export function heldMovedFinding(heldKeys, moved) {
-    const dup = moved.find((m) => heldKeys.has(m.key));
-    if (dup === undefined)
-        return undefined;
-    return (`this run moved a backlog entry another instance of this role is working on: "${dup.title}" — it is that ` +
-        `instance's task (see <held-entries>), so revert every edit made for it, including the ` +
-        `entry's move, and leave nothing behind if that was the whole change`);
-}
-/** Parse `git diff --cached -M --name-status` output: `M\tpath`, `D\tpath`, or
- * `R100\told\tnew`. Malformed lines are skipped. */
-function parseNameStatus(out) {
-    const entries = [];
-    for (const line of (out ?? "").split("\n")) {
-        if (!line)
-            continue;
-        const parts = line.split("\t");
-        const status = (parts[0] ?? "").charAt(0);
-        if (!status)
-            continue;
-        if (status === "R" || status === "C") {
-            const oldPath = parts[1];
-            const path = parts[2];
-            if (oldPath && path)
-                entries.push({ status, path, oldPath });
-        }
-        else if (parts[1]) {
-            entries.push({ status, path: parts[1] });
-        }
-    }
-    return entries;
-}
-/** Stage the change and run the three git-level path checks over the resulting index, then
- * restore the index to HEAD so the staging is invisible to the tick's own change detection.
- * Each check is best-effort: a failed git command contributes nothing. */
-async function gitLevelFindings(wt, mainBranch) {
-    await gitTry(wt, "add", "-A");
-    try {
-        const base = await changeBaseRev(wt, mainBranch);
-        const entries = parseNameStatus(await gitTry(wt, "diff", "--cached", "-M", "--name-status", base));
-        const findings = await staleReferenceFindings(wt, entries);
-        const diff = (await gitTry(wt, "diff", "--cached", "-U0", base)) ?? "";
-        findings.push(...(await missingPathFindings(wt, diff, entries)));
-        findings.push(...newlineFindings(diff));
-        return findings;
-    }
-    finally {
-        // Restore the index to HEAD. Without this, the tick's change detection (changedFiles and
-        // stageTickMerge's "nothing left to merge" guard) reads the stale index and reports a
-        // fix-up that reverted the whole change as still changed, so an empty tree would reach
-        // commitAll instead of the tick ending no_change.
-        await gitTry(wt, "reset");
-    }
-}
-/** (a) References left behind by a rename or delete: for each `D` path and each `R` origin,
- * `git grep --cached` the old path across the staged tree and report up to MAX_STALE_HITS
- * `file:line` hits outside record prose (isRecordProse). Renames report the path they moved to;
- * deletes report the deletion. */
-async function staleReferenceFindings(wt, entries) {
-    const findings = [];
-    let reported = 0;
-    for (const e of entries) {
-        if (e.status !== "D" && e.status !== "R")
-            continue;
-        if (reported >= MAX_STALE_PATHS)
-            break;
-        const old = e.oldPath ?? e.path;
-        // `git grep` exits 1 with no output when nothing matches — the common, clean case — and
-        // gitTry maps that to null exactly as it maps a real failure, both of which mean "no hits".
-        const out = await gitTry(wt, "grep", "-n", "-F", "-I", "--cached", "-e", old);
-        if (!out)
-            continue;
-        const hits = [];
-        for (const line of out.split("\n")) {
-            const m = /^([^:]+):(\d+):(.*)$/.exec(line);
-            if (!m || isRecordProse(m[1]) || !hasStandalonePathOccurrence(m[3] ?? "", old))
-                continue;
-            hits.push(`${m[1]}:${m[2]}`);
-            if (hits.length >= MAX_STALE_HITS)
-                break;
-        }
-        if (hits.length === 0)
-            continue;
-        const moved = e.status === "R" ? `was renamed to ${e.path}` : "was deleted";
-        findings.push(`${old} ${moved} but is still named at: ${hits.join(", ")}`);
-        reported++;
-    }
-    return findings;
-}
-/** True when `needle` appears in `line` as a repo path of its own — not as one segment of a
- * longer path. `git grep -F` matches substrings, so a line naming a rename's destination
- * (`src/config.ts`) would otherwise read as a stale reference to an old root `config.ts`.
- * A preceding path character (or a following one that continues the token, as a `.` extension
- * or an alphanumeric does) disqualifies the occurrence; trailing sentence punctuation does not. */
-function hasStandalonePathOccurrence(line, needle) {
-    const pathChar = /[A-Za-z0-9_./-]/;
-    for (let i = line.indexOf(needle); i !== -1; i = line.indexOf(needle, i + 1)) {
-        const before = i > 0 ? line[i - 1] : "";
-        if (before && pathChar.test(before))
-            continue;
-        const after = line[i + needle.length] ?? "";
-        if (/[A-Za-z0-9_/-]/.test(after))
-            continue;
-        if (after === "." && /[A-Za-z0-9]/.test(line[i + needle.length + 1] ?? ""))
-            continue;
-        return true;
-    }
-    return false;
-}
-/** Each distinct path-shaped token in `text`, in first-appearance order: at least one slash and
- * a final `.<ext>` segment. Scanned inside the text (not whitespace-split) so surrounding
- * backticks, brackets, and sentence punctuation fall away with the match. */
-export function pathTokens(text) {
-    const tokenRe = /[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+\.[A-Za-z0-9]+/g;
-    return [...new Set([...text.matchAll(tokenRe)].map((m) => m[0]))];
-}
-/** (b) Nonexistent paths: every path-shaped token on an added diff line whose first segment is
- * a tracked top-level directory but which is absent from the staged tree. Rename origins and
- * deleted paths are excluded — "moved from X" prose names them legitimately. */
-async function missingPathFindings(wt, diff, entries) {
-    const ls = await gitTry(wt, "ls-files");
-    const staged = new Set();
-    const topDirs = new Set();
-    for (const p of (ls ?? "").split("\n")) {
-        if (!p)
-            continue;
-        staged.add(p);
-        const slash = p.indexOf("/");
-        if (slash > 0)
-            topDirs.add(p.slice(0, slash));
-    }
-    const oldPaths = new Set();
-    for (const e of entries) {
-        if (e.oldPath)
-            oldPaths.add(e.oldPath);
-        if (e.status === "D")
-            oldPaths.add(e.path);
-    }
-    const seen = new Set();
-    const missing = [];
-    let file = null;
-    for (const line of diff.split("\n")) {
-        if (line.startsWith("+++ ")) {
-            file = diffPlusPath(line);
-            continue;
-        }
-        if (!line.startsWith("+") || line.startsWith("+++"))
-            continue;
-        // A test file's fixtures routinely name paths from the software under test, which need
-        // not exist here, and record prose names the paths a plan proposes to create; the
-        // added-nonexistent-path heuristic targets real references, so it spares added lines in
-        // test/ and in record prose (isRecordProse).
-        if (file !== null && (file.startsWith("test/") || isRecordProse(file)))
-            continue;
-        for (const p of pathTokens(line.slice(1))) {
-            const top = p.slice(0, p.indexOf("/"));
-            if (!topDirs.has(top) || oldPaths.has(p) || staged.has(p) || seen.has(p))
-                continue;
-            seen.add(p);
-            missing.push(p);
-        }
-    }
-    if (missing.length === 0)
-        return [];
-    return [
-        `added lines name paths that do not exist in the tree: ${cappedList(missing, MAX_MISSING_PATHS)}`,
-    ];
-}
-/** (c) Lost final newlines: a text file whose new diff side carries git's
- * `` marker while its base side does not. Git emits the marker
- * immediately after the line it applies to, so a marker after a `+` line flags the new side and
- * one after a `-` line flags the base side; a new file (`+` only) counts. Binary files have no
- * line hunks and never appear. */
-function newlineFindings(diff) {
-    const files = [];
-    let path = null;
-    let newLacks = false;
-    let oldLacks = false;
-    let prev = "";
-    const flush = () => {
-        if (path !== null && newLacks && !oldLacks)
-            files.push(path);
-    };
-    for (const line of diff.split("\n")) {
-        if (line.startsWith("diff --git ")) {
-            flush();
-            path = null;
-            newLacks = false;
-            oldLacks = false;
-            continue;
-        }
-        if (line.startsWith("+++ ")) {
-            path = diffPlusPath(line);
-            continue;
-        }
-        if (line.startsWith("\")) {
-            if (prev.startsWith("+"))
-                newLacks = true;
-            else if (prev.startsWith("-"))
-                oldLacks = true;
-            continue;
-        }
-        if (line.startsWith("+") || line.startsWith("-") || line.startsWith(" "))
-            prev = line;
-    }
-    flush();
-    if (files.length === 0)
-        return [];
-    return [`the change removes the final newline from: ${cappedList(files, MAX_NEWLINE_FILES)}`];
-}

package/dist/src/tick/telemetry-digest.js

@@ -1,25 +0,0 @@
-/** The `telemetry` role's tick-time evidence: the failure digest rendered over the role's own
- * trailing 24 h window. Split out of src/failure/failure-render.ts — which stays the pure
- * renderer — so every observer role's evidence builder has its own module the way
- * qa-coverage.ts and backlog-structure.ts do, and the tick lifecycle (tick-prompt.ts) injects
- * it from there instead of reaching into a report module. */
-import { collectFailureReportSince } from "../failure/failure-data.js";
-import { renderFailureMarkdown } from "../failure/failure-render.js";
-/** The `telemetry` role's own digest window: the trailing 24 h ending now, not the local
- * calendar day. A calendar day starts at midnight, so a run at 06:32 would never see the
- * previous evening. The CLI keeps the usage report's 14-day default; the role reads 24 h so a
- * cluster re-surfaces only while it is live. The collector's equal-length prior window is what
- * makes the delta line meaningful. */
-export const TELEMETRY_DIGEST_MS = 24 * 60 * 60 * 1000;
-/** The `telemetry` role's tick-time evidence: the failure digest rendered over its own
- * trailing 24 h window. A missing or corrupt log omits the block (undefined) and never fails the
- * tick — an observer must not break on bookkeeping (plans/telemetry-role.md). The window and
- * the swallow-errors policy live with the digest, not in the tick lifecycle that injects it. */
-export function telemetryDigest(root) {
-    try {
-        return renderFailureMarkdown(collectFailureReportSince(root, TELEMETRY_DIGEST_MS));
-    }
-    catch {
-        return undefined;
-    }
-}

package/dist/src/tick/tick-detail-data.js

@@ -1,108 +0,0 @@
-// vocabulary: plain
-/** Collection half of `tumwater tick <role> <n>`: one completed tick's full event block,
- * distilled from the event log into a TickDetail payload. The collector-in-core convention
- * beside history-data.ts and src/report/report-data.ts — a pure read over root, so core
- * modules can serve the same payload without reaching into ui/, and the CLI
- * (`tick-detail.ts`) and the GUI History drill-down (`src/gui/gui-endpoints.ts`) cannot
- * drift on what one tick's block contains.
- * Every datum rides the events the harness already writes, so this is a distillation of the
- * existing record, not a new one. The rendering half — the summary header, formatEvent, the
- * CLI command — lives in tick-detail.ts. */
-import { HISTORY_SCAN_MAX_EVENTS, bucketMergeEvents, resolveQueuedResult } from "../history/history-data.js";
-import { eventUsage, readEvents, tickSpanMs, tickStartMap } from "../events/event-read.js";
-import { outcomeText, usageText } from "../events/event-format.js";
-/** The event block of `role`'s tick `n`, or null when the scanned window holds no such tick.
- * The newest `run_start` the log retains for `${role}#${n}` wins (a counter reset can make an
- * old tick number recur; the operator asking by number means the most recent one), and the
- * block closes at the first `run_end` for that tick after the start — or, when that end is
- * missing (in flight, or its tail lost to rotation), at the loop's next `run_start`, so a
- * rotation-cut block never leaks the following tick's events into this one. When even the
- * start is gone but a matching `run_end` survives, the end-alone block still answers with
- * `startTs` null and a null duration (the unpaired rule); nothing at all in the scan is the
- * not-found case the caller renders as a not-found line. */
-export function readTickDetail(root, role, tick) {
-    // The scan rides history-data.ts's shared one-ask ceiling (HISTORY_SCAN_MAX_EVENTS): one
-    // tick's block is small, but it can sit arbitrarily far back in a long-lived team's log,
-    // and readTailText reads bytes proportional to the limit's line count — so the cap is also
-    // the largest byte read one command can cost, and every read-only view scans under the
-    // same bound.
-    const events = readEvents(root, HISTORY_SCAN_MAX_EVENTS).filter((e) => e.source === role);
-    // Newest run_start for this loop+tick: the block's lower bound.
-    let startIdx = -1;
-    for (let i = events.length - 1; i >= 0; i--) {
-        const e = events[i];
-        if (e.type === "run_start" && e.run === tick) {
-            startIdx = i;
-            break;
-        }
-    }
-    if (startIdx < 0) {
-        // The start is gone (rotation) or the tick never ran. A surviving run_end for the same
-        // number still answers — unpaired, undated at the front — else there is no such tick here.
-        for (let i = events.length - 1; i >= 0; i--) {
-            const e = events[i];
-            if (e.type === "run_end" && e.run === tick)
-                return detailFrom(role, tick, events, [e], e, null);
-        }
-        return null;
-    }
-    const start = events[startIdx];
-    // The block's upper bound: the first run_end for this tick after the start ends it; a
-    // later run_start (this tick's end lost to rotation) closes the block exclusive — the
-    // events after it belong to the next tick, not this one. No end and no next start reads as
-    // in flight: everything since the start belongs to the open tick.
-    let end = null;
-    let nextStart = null;
-    for (let i = startIdx + 1; i < events.length; i++) {
-        const e = events[i];
-        if (e.type === "run_end" && e.run === tick) {
-            end = e;
-            break;
-        }
-        if (e.type === "run_start") {
-            nextStart = e;
-            break;
-        }
-    }
-    // The block itself: the start event plus everything this loop logged up to the bound —
-    // inclusive at a paired end, exclusive at a next tick's start.
-    const block = [];
-    for (let i = startIdx; i < events.length; i++) {
-        const e = events[i];
-        if (end !== null ? e.ts > end.ts : nextStart !== null && e.ts >= nextStart.ts)
-            break;
-        block.push(e);
-    }
-    return detailFrom(role, tick, events, block, end, start.ts);
-}
-/** Fill the payload around a collected block: usage from the run_end via eventUsage/usageText,
- * duration via tickSpanMs against the loop's own start map (the shared pairing helper, so this
- * view and the history rows cannot drift on what a span is), events oldest-first. */
-function detailFrom(role, tick, scoped, block, end, startTs) {
-    const usageNums = end === null ? { tokens: 0, costUsd: 0 } : eventUsage(end);
-    let result = end === null ? null : outcomeText(end);
-    let merge = null;
-    if (end !== null && result === "queued") {
-        // A fresh claim cursor suits one tick: the walk starts at the newest pin at or before this
-        // tick's end, which is its own pin, since later ticks' pins sit after it.
-        const { mergeQueuedByLoop, outcomeByLoop } = bucketMergeEvents(scoped);
-        const resolved = resolveQueuedResult(end, mergeQueuedByLoop, outcomeByLoop, new Map(), tickStartMap(scoped), null);
-        if (resolved !== null) {
-            result = resolved.result;
-            merge = resolved.outcome;
-        }
-    }
-    return {
-        role,
-        run: tick,
-        startTs,
-        endTs: end === null ? null : end.ts,
-        durationMs: end === null ? null : tickSpanMs(end, tickStartMap(scoped)),
-        result,
-        tokens: usageNums.tokens,
-        costUsd: usageNums.costUsd,
-        usage: end === null ? "" : usageText(end),
-        events: block,
-        merge,
-    };
-}