tumwater 0.4.0 → 0.4.2

package/dist/src/run/run-detail.js

@@ -57,24 +57,15 @@ export function newestRunRow(root, role, classes, models) {
 function newestRunNumber(root, role, classes, models) {
     return newestRunRow(root, role, classes, models)?.run ?? null;
 }
-/** `tumwater history <role> [<n>] [--last [--result <class>[,...]]] [--stat] [--patch]
- * [--transcript [--prompt] [--grep <text>]] [--json]`: print one completed
- * run's full event trail. Read-only: stdout only, no state file created — a run the
- * scan cannot find prints a not-found line and exits 0 (history's empty-output convention:
- * an absent record is an answer, not a failure), and under --json it prints the JSON document
- * `null` instead — the report --json precedent
- * that every exit-0 output is parseable, never prose. `tumwater history <role> --last` resolves
- * the role's newest completed run in the scanned window and prints its trail exactly as the
- * numbered form would — the summary header and event rendering are shared, only the number's
- * provenance differs (readRunRows' newest-first scan, not the user's argument). --last and
- * a numeric <n> are rivals: exactly one positional under --last, exactly two without. With
- * --last, `--result <class>[,...]` picks the newest run in the listed outcome classes instead
- * (the listing's classes, scanning up to HISTORY_MAX_RUNS runs); it needs --last. `--model
- * <selector>[,...]` with --last keeps only runs that started on a listed model (the listing's
- * exact match) and composes with --result; it needs --last too. With --last and no role, the
- * newest run of any role is opened (newestRunRow with a null role) and renders as its
- * role's form. */
-export async function cmdRunDetail(root, positionals, json, { last = false, stat = false, patch = false, transcript = false, prompt = false, grep = null, result = null, model = null } = {}) {
+/** The invocation half of cmdRunDetail: rule out the arity and flag mistakes before any run is
+ * resolved, so the shared unknown-role wording and the usage string are the whole validation
+ * surface, found by this one name. Succeeds only for a well-formed call; returns the parsed
+ * bare/role/classes/models for the resolver. The role is checked first, so a typo is named
+ * whatever the count (knownRoleIdsCached: the built-ins plus user-defined roles, read through
+ * the never-throwing cached loader so a transiently broken tumwater.json cannot take a
+ * read-only view down). The arity, unknown-role and flag-dependency failures all `fail` with
+ * the usage. */
+function parseRunDetailInvocation(root, positionals, { last, transcript, prompt, grep, result, model }) {
     // Positional arity by form: cli.ts has already peeled the flags off and gated them (only
     // --json and --last are admitted), so anything left over that does not fit the chosen form
     // is a mistake. The role is checked first, so a typo is named whatever the count; then
@@ -110,29 +101,60 @@ export async function cmdRunDetail(root, positionals, json, { last = false, stat
         fail(`history --model needs --last on a one-run trail (usage: ${RUN_DETAIL_USAGE})`);
     const classes = result !== null ? parseHistoryResultList(result) : null;
     const models = model !== null ? parseHistoryModelList(model) : null;
+    return { bare, role, classes, models };
+}
+/** The resolution half of cmdRunDetail: pick the run to open and read its detail. Bare `--last`
+ * takes the newest run of any role (its role from the row); `--last` with a role the newest run
+ * by number; the numbered path the user's positive integer. An empty or unreadable scan is null
+ * (the detail stays null, and the not-found branch of cmdRunDetail words it), so the resolver
+ * never reports a miss itself. */
+function resolveRunDetailTarget(root, parsed, positionals, last) {
+    let role = parsed.role;
     // The run number: either the user's positive integer (the numbered path, through the
     // shared count parser — a non-positive or non-numeric n fails naming the shape; there is
     // no cap — the number selects, it does not size the scan) or the newest completed run's
     // number, read from readRunRows' newest-first scan for the role. An empty scan is not
     // found by construction, so the not-found path below takes it with the last-form wording.
     let runNumber;
-    if (bare) {
+    if (parsed.bare) {
         // `history --last` with no role: the newest completed run of any role; its role is the row's.
-        const row = newestRunRow(root, null, classes, models);
+        const row = newestRunRow(root, null, parsed.classes, parsed.models);
         if (row !== null)
             role = row.role;
         runNumber = row?.run ?? null;
     }
     else {
-        runNumber = last ? newestRunNumber(root, role, classes, models) : parseCountFlag("history <n>", positionals[1]);
+        runNumber = last ? newestRunNumber(root, role, parsed.classes, parsed.models) : parseCountFlag("history <n>", positionals[1]);
     }
     const detail = runNumber === null ? null : readRunDetail(root, role, runNumber);
+    return { role, runNumber, detail };
+}
+/** `tumwater history <role> [<n>] [--last [--result <class>[,...]]] [--stat] [--patch]
+ * [--transcript [--prompt] [--grep <text>]] [--json]`: print one completed
+ * run's full event trail. Read-only: stdout only, no state file created — a run the
+ * scan cannot find prints a not-found line and exits 0 (history's empty-output convention:
+ * an absent record is an answer, not a failure), and under --json it prints the JSON document
+ * `null` instead — the report --json precedent
+ * that every exit-0 output is parseable, never prose. `tumwater history <role> --last` resolves
+ * the role's newest completed run in the scanned window and prints its trail exactly as the
+ * numbered form would — the summary header and event rendering are shared, only the number's
+ * provenance differs (readRunRows' newest-first scan, not the user's argument). --last and
+ * a numeric <n> are rivals: exactly one positional under --last, exactly two without. With
+ * --last, `--result <class>[,...]` picks the newest run in the listed outcome classes instead
+ * (the listing's classes, scanning up to HISTORY_MAX_RUNS runs); it needs --last. `--model
+ * <selector>[,...]` with --last keeps only runs that started on a listed model (the listing's
+ * exact match) and composes with --result; it needs --last too. With --last and no role, the
+ * newest run of any role is opened (newestRunRow with a null role) and renders as its
+ * role's form. */
+export async function cmdRunDetail(root, positionals, json, { last = false, stat = false, patch = false, transcript = false, prompt = false, grep = null, result = null, model = null } = {}) {
+    const parsed = parseRunDetailInvocation(root, positionals, { last, transcript, prompt, grep, result, model });
+    const { role, runNumber, detail } = resolveRunDetailTarget(root, parsed, positionals, last);
     if (runNumber === null) {
         // The --last scan came up empty: not found by construction, the last-form wording.
         if (json)
             sayJson(null);
         else
-            say(runNotFoundLastMessage(bare ? null : role, classes, models));
+            say(runNotFoundLastMessage(parsed.bare ? null : role, parsed.classes, parsed.models));
         return;
     }
     if (detail === null) {

package/dist/src/run/run-dismiss.js

@@ -0,0 +1,43 @@
+/** The outcome-recording a run writes at its dismissal — the qa-flow ledger entry and the
+ * feedback filing — shared by the two dismissal paths so the run that changed the tree
+ * (run-stage.ts) and the no-change run (run-verdict.ts) file their flow and filing
+ * identically. Before the split each path carried its own copy: the same try/catch, the same
+ * `not recorded` warn wording, and the same issue_filed event, so a wording or guard drift
+ * in one path could not show up in the other. Each recorder is bookkeeping that never fails
+ * the run — a failed write warns and the run's outcome stands — and the caller keeps its own
+ * guard (the cut-off runs record nothing, the changed path records even when the merge is
+ * queued). The ci-parity recorder is deliberately NOT shared: only the no-change path writes
+ * it, because a run that changed the tree has not verified main (run-stage.ts's comment). */
+import { logEventBestEffort } from "../events/events.js";
+import { errorMessage } from "../text/text.js";
+import { recordFiled } from "./feedback-filings.js";
+import { recordFlow } from "./qa-coverage.js";
+/** Record a dismissed run's qa flow (qa-coverage.ts's recordFlow) — a failed write warns
+ * with the same wording on both dismissal paths. `summary` is the run's summary only when
+ * the flow result is a bug (the recordFlow shape carries one just for the bug case, as each
+ * path's caller spelled the ternary inline); a passed flow records none. */
+export function recordDismissedFlow(ctx, root, flow, result, summary) {
+    try {
+        recordFlow(root, flow, result, result === "bug" ? summary : undefined);
+    }
+    catch (err) {
+        ctx.warn(`qa flow "${flow}" not recorded: ${errorMessage(err)}`);
+    }
+}
+/** Record a dismissed run's feedback filing (feedback-filings.ts's recordFiled) and log the
+ * issue_filed event so the filing reaches the operator's activity feed — a failed ledger
+ * write warns with the same wording on both dismissal paths. */
+export function recordDismissedFiling(ctx, root, filed) {
+    logEventBestEffort(root, {
+        source: ctx.role,
+        type: "issue_filed",
+        issue: filed.issue,
+        title: filed.title,
+    });
+    try {
+        recordFiled(root, filed.issue, filed.title);
+    }
+    catch (err) {
+        ctx.warn(`feedback filing #${filed.issue} not recorded: ${errorMessage(err)}`);
+    }
+}

package/dist/src/run/run-finalize.js

@@ -2,7 +2,7 @@ import { hasOutstandingWork, saveRunnerStateBestEffort } from "../runner/runner-
 import { branchHead } from "../git/git.js";
 import { logEventBestEffort, usageFragment, warnEventBestEffort } from "../events/events.js";
 import { observeAccount } from "../agent/subscription-account.js";
-import { ERROR_STREAK_WARN, QUIET_KILL_RESUME_LIMIT, applyRunOutcome } from "./run-apply.js";
+import { CUT_OFF_RESUME_LIMIT, ERROR_STREAK_WARN, QUIET_KILL_RESUME_LIMIT, applyRunOutcome } from "./run-apply.js";
 import { restoreMidRunWake } from "../scheduling/backoff.js";
 import { consecutiveFailuresWarning } from "../text/phrases.js";
 /** The run results that end an instance's claim: the run found nothing to do, refused the
@@ -48,28 +48,46 @@ export async function finalizeRun(deps) {
     // Record the outcome on state and schedule the next run (see src/run/run-apply.ts for the
     // per-result policy: prompt retry, backoff, bounded cut-off resumes).
     applyRunOutcome(s, config, role, outcome);
-    // A run that ends without producing or keeping work releases this instance's backlog claim
-    // (plans/parallel-work-instances.md "Claims", part 4/7): the next run may take a different
-    // entry. Every other result — queued, changed, rejected with a revision, an error, an abort
-    // that resumes — keeps the claim so the same instance retries it; an outstanding revision or
-    // a pending resume also holds it, because the entry is still this instance's task.
-    if (s.claim &&
-        CLAIM_RELEASING.has(outcome.result) &&
-        !hasOutstandingWork(s)) {
-        const title = s.claim.title;
-        s.claim = undefined;
-        logEventBestEffort(root, { source: role, type: "claim", action: "released", title, reason: outcome.result });
-    }
-    // A wake consumed while this run ran stamped the shared state in place, but the outcome
-    // schedule above overwrites it (lastRunEndedAt past wokenAt, nextRunAt a fresh gap or
-    // backoff out), so a plain `tumwater wake --role` with an empty queue would silently wait
-    // out the whole interval (BUGS.md 2026-09-25). Re-apply it here — exactly like a wake
-    // arriving one poll after the run ended.
+    releaseFinishedClaim(root, role, s, outcome);
     restoreMidRunWake(s);
     // A failed save warns and the run still ends: the in-memory state already holds the fold and
     // the runner's next save writes it, while a throw here would skip run_end and the launch
     // task's breaker fold.
     saveRunnerStateBestEffort(root, s);
+    warnOnStreakCrossings(root, role, s, outcome);
+    // The run's wall-clock span rides on run_end too: the
+    // failure digest prices a run by its own durationMs first (src/failure/failure-data.ts
+    // runDurationMs), so the field is ALWAYS present — a run that ends within the same
+    // Date.now() millisecond it started (an instant early-abort error run) or crosses a
+    // backward clock step still attests its 0 ms, where the old omit-when-zero convention
+    // dropped the field and broke the "every run_end carries a span" contract (BUGS.md
+    // 2026-09-29). Unlike the usage fields, run_end's renderer never prints the span, so an
+    // always-present 0 changes no rendered line.
+    const runDurationMs = Math.max(0, Date.now() - deps.runStartedAt);
+    observeRunAccount(root, usage);
+    logRunEnd(root, role, runNumber, s, outcome, usage, runDurationMs);
+    return outcome;
+}
+/** A run that ends without producing or keeping work releases this instance's backlog claim
+ * (plans/parallel-work-instances.md "Claims", part 4/7): the next run may take a different
+ * entry. Every other result — queued, changed, rejected with a revision, an error, an abort
+ * that resumes — keeps the claim so the same instance retries it; an outstanding revision or
+ * a pending resume also holds it, because the entry is still this instance's task. */
+function releaseFinishedClaim(root, role, state, outcome) {
+    if (state.claim &&
+        CLAIM_RELEASING.has(outcome.result) &&
+        !hasOutstandingWork(state)) {
+        const title = state.claim.title;
+        state.claim = undefined;
+        logEventBestEffort(root, { source: role, type: "claim", action: "released", title, reason: outcome.result });
+    }
+}
+/** One warning per error episode (BUGS.md 2026-09-15: every role failing identically
+ * looked like a quiet team), quiet-kill episode (BUGS.md 2026-09-18: a role burning an hour
+ * per run with no output must not look like a sleeping role) and cut-off episode (mirroring
+ * quiet-kill: a role cycling cut-off → resume burns an hour-plus per cycle with no other
+ * operator signal) — each fired exactly once at the streak's crossing, after the schedule. */
+function warnOnStreakCrossings(root, role, state, outcome) {
     // One warning per error episode (BUGS.md 2026-09-15: every role failing identically
     // looked like a quiet team). applyRunOutcome increments the streak on error-class
     // outcomes, preserves it across a plain `queued` run (the run's merge resolves it),
@@ -78,37 +96,34 @@ export async function finalizeRun(deps) {
     // re-warn on the queued run's end. A rejection's crossing warns from the merge side
     // instead (writeMergeOutcome, src/merge/merge-slot.ts), which is where rejections resolve.
     if ((outcome.result === "error" || outcome.recoveryFailure !== undefined) &&
-        (s.consecutiveErrors ?? 0) === ERROR_STREAK_WARN) {
-        warnEventBestEffort(root, role, consecutiveFailuresWarning(s.consecutiveErrors ?? 0, s.lastError ?? outcome.recoveryFailure ?? "unknown error"));
+        (state.consecutiveErrors ?? 0) === ERROR_STREAK_WARN) {
+        warnEventBestEffort(root, role, consecutiveFailuresWarning(state.consecutiveErrors ?? 0, state.lastError ?? outcome.recoveryFailure ?? "unknown error"));
     }
     // One warning per quiet-kill episode (BUGS.md 2026-09-18): a role burning an hour per
     // run with no output must not look like a sleeping role. applyRunOutcome grows the
     // streak on each kill and resets it on any other result, so the crossing fires once;
     // the give-up (fresh session + backoff) follows on the next kill.
-    if ((s.quietKillStreak ?? 0) === QUIET_KILL_RESUME_LIMIT) {
-        warnEventBestEffort(root, role, `${s.quietKillStreak} consecutive stalls (no progress): ${s.lastError ?? "unknown hang"}`);
+    if ((state.quietKillStreak ?? 0) === QUIET_KILL_RESUME_LIMIT) {
+        warnEventBestEffort(root, role, `${state.quietKillStreak} consecutive stalls (no progress): ${state.lastError ?? "unknown hang"}`);
     }
-    // Per-run usage: the event feed is where operators see
-    // spend — this run's tokens and cost ride on run_end so a budget pause or a money-burning
-    // no_change/error/rejected/refused run shows what it spent without diffing status-table
-    // snapshots. Both fields are per-run windows (reset at run start, folded in over every
-    // pi run of the run); they ride on HarnessEvent's index signature like other payloads and
-    // are omitted when zero so skipped runs render byte-identical to a pre-feature line.
-    // The run's wall-clock span rides on run_end too: the
-    // failure digest prices a run by its own durationMs first (src/failure/failure-data.ts
-    // runDurationMs), so the field is ALWAYS present — a run that ends within the same
-    // Date.now() millisecond it started (an instant early-abort error run) or crosses a
-    // backward clock step still attests its 0 ms, where the old omit-when-zero convention
-    // dropped the field and broke the "every run_end carries a span" contract (BUGS.md
-    // 2026-09-29). Unlike the usage fields, run_end's renderer never prints the span, so an
-    // always-present 0 changes no rendered line.
-    const runDurationMs = Math.max(0, Date.now() - deps.runStartedAt);
-    // The account state (plans/agent-backends.md part 6a): fold this run's billing answer and
-    // rate-window readings into the reporting backend's .tumwater/state/<backend>-account.json
-    // for the sibling parts that throttle or display the subscription window. Best-effort — the
-    // file is a cache, and an unwritable state dir must not fail a run whose real work is
-    // already done. A pi run never reports either, so in practice claude owns the file until a
-    // second subscription backend lands (plans/codex-backend.md).
+    // One warning per cut-off episode, mirroring quiet-kill above: a role cycling cut-off →
+    // resume burns an hour-plus per cycle (run-apply.ts CUT_OFF_RESUME_LIMIT) with no other
+    // operator signal, so the crossing must not look like a benign idle role. The `outcome.cutOff`
+    // guard makes it fire only on the run that increments the streak to the limit — every
+    // non-cut-off run resets the streak to 0 and a later cut-off sits above the limit — so
+    // exactly one warning per episode. No role guard, matching quiet-kill (a cut-off director
+    // prompt is re-queued but its streak still counts).
+    if (outcome.cutOff === true && (state.cutOffStreak ?? 0) === CUT_OFF_RESUME_LIMIT) {
+        warnEventBestEffort(root, role, `${state.cutOffStreak} consecutive runs cut off at the context ceiling; give the role a smaller task or a longer context window`);
+    }
+}
+/** The account state (plans/agent-backends.md part 6a): fold this run's billing answer and
+ * rate-window readings into the reporting backend's .tumwater/state/<backend>-account.json
+ * for the sibling parts that throttle or display the subscription window. Best-effort — the
+ * file is a cache, and an unwritable state dir must not fail a run whose real work is
+ * already done. A pi run never reports either, so in practice claude owns the file until a
+ * second subscription backend lands (plans/codex-backend.md). */
+function observeRunAccount(root, usage) {
     if (usage.billing !== undefined || usage.rateWindows !== undefined) {
         try {
             observeAccount(root, usage.agent ?? "pi", {
@@ -120,6 +135,12 @@ export async function finalizeRun(deps) {
             // The next reporting run rewrites it; nothing this run depends on is lost.
         }
     }
+}
+/** Assemble and log the run_end event: the per-run usage fields (tokens and cost), the run's
+ * wall-clock span, and every conditional payload spread. Omitted-when-zero fields ride the
+ * event feed only when nonzero so skipped runs render byte-identically to a pre-feature line;
+ * `durationMs` is ALWAYS present to keep the "every run_end carries a span" contract. */
+function logRunEnd(root, role, runNumber, state, outcome, usage, runDurationMs) {
     // The per-provider split of this run's usage (plans: per-provider spend in the day
     // report): a Record<provider, {costUsd, notionalCostUsd}> for the report's `Cost by
     // provider` line. Omitted when empty like the prompt-token fields, so a run whose runs
@@ -131,10 +152,14 @@ export async function finalizeRun(deps) {
         run: runNumber,
         result: outcome.result,
         summary: outcome.summary,
-        error: s.lastError,
+        error: state.lastError,
         durationMs: runDurationMs,
         ...(outcome.heldOnBranch ? { heldOnBranch: true } : {}),
-        ...usageFragment(s.generatedTokens, usage.costUsd, usage.notionalCostUsd),
+        // The context-ceiling truncation flag: set when the run burned its whole window and
+        // the harness resumes its pinned session (slotPinnedForResume). Omitted when false, so
+        // a normal run — and every run_end written by an older build — renders byte-identically.
+        ...(outcome.cutOff === true ? { cutOff: true } : {}),
+        ...usageFragment(state.generatedTokens, usage.costUsd, usage.notionalCostUsd),
         ...(Object.keys(providerCost).length > 0 ? { providerCost } : {}),
         // The billing answer the run's runs reported, so the report can tell notional spend from
         // real spend without re-deriving it from the file (plans/agent-backends.md part 6a).
@@ -150,6 +175,10 @@ export async function finalizeRun(deps) {
         ...(usage.promptTokens > 0 ? { promptTokens: usage.promptTokens } : {}),
         ...(usage.cacheReadTokens > 0 ? { cacheReadTokens: usage.cacheReadTokens } : {}),
         ...(usage.preEditPromptTokens > 0 ? { preEditPromptTokens: usage.preEditPromptTokens } : {}),
+        // The run's peak single-request context: how hot the run's largest model call ran
+        // against the model's declared window (runner-state.ts's peakContextTokens, reset at
+        // run start). Omitted when zero like the prompt-token fields, so a run that reported
+        // no context — and every run_end written by an older build — renders byte-identically.
+        ...(state.peakContextTokens > 0 ? { peakContextTokens: state.peakContextTokens } : {}),
     });
-    return outcome;
 }