tumwater 0.4.2 → 0.4.4

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

@@ -31,30 +31,41 @@ export function runDetailStat(root, d) {
 export function runDetailPatch(root, d) {
     return runCommitShow(root, runCommitSha(d), "--patch");
 }
-/** The human view of a RunDetail: one summary line — result (or the in-flight/unpaired
- * marker), duration, usage, and the model the run started on when its `run_start` carried one
- * (after the usage, before the pinned-commit sha), plus the pinned commit sha when the block's
- * `merge_queued`/`merge_done` event carries one — then each event through formatEvent, the
- * shared renderer `logs` and the
- * TUI use, so the trail reads exactly like the feed it came from. A queued run whose merge
- * has finished shows that verdict in the header and ends with the merge's outcome line; a
- * leftover-recovery run's verdict is the failed attempt it re-queued (resolveQueuedResult),
- * logged before the run began, so that outcome line leads the trail instead — the trail stays
- * in time order. */
-export function renderRunDetail(d) {
-    const summary = [];
+/** The run's result cell, always present: the outcome label when the run finished, the
+ * in-flight/unpaired marker when it has not. Owns the first summary cell. */
+function runResultCell(d) {
     if (d.endTs === null)
-        summary.push(d.startTs === null ? "unpaired" : "in flight");
-    else
-        summary.push(d.result ? eventTypeLabel(d.result) : "?");
+        return d.startTs === null ? "unpaired" : "in flight";
+    return d.result ? eventTypeLabel(d.result) : "?";
+}
+/** The run's cut-off cell, the ceiling-truncation marker straight after the result cell. It
+ * only rides a completed end (cutOff is set from the run_end), so it can never follow in
+ * flight/unpaired. */
+function runCutOffCell(d) {
     // The ceiling-truncation marker, straight after the result cell. It only rides a
     // completed end (cutOff is set from the run_end), so it can never follow in flight/unpaired.
-    if (d.cutOff === true)
-        summary.push("cut off at the context ceiling");
-    if (d.durationMs !== null)
-        summary.push(shortSpanPhrase(d.durationMs));
-    if (d.usage !== "")
-        summary.push(d.usage);
+    if (d.cutOff !== true)
+        return null;
+    return "cut off at the context ceiling";
+}
+/** The run's duration cell. */
+function runDurationCell(d) {
+    if (d.durationMs === null)
+        return null;
+    return shortSpanPhrase(d.durationMs);
+}
+/** The run's usage cell. */
+function runUsageCell(d) {
+    if (d.usage === "")
+        return null;
+    return d.usage;
+}
+/** The run's prompt cell: the prompt-token total and the share the backend served from cache,
+ * the input side a cost-only header hides. The `${n}% cached` wording and rounding are the
+ * usage report's `Prompt tokens by role` share; a run with prompt tokens but no cache reads
+ * shows no parenthetical, and a run that reported neither keeps today's header byte-identical
+ * (the omit-when-zero convention). */
+function runPromptCell(d) {
     // The run's prompt-token total and the share the backend served from cache, the input
     // side a cost-only header hides. The `${n}% cached` wording and rounding are the usage
     // report's `Prompt tokens by role` share; a run with prompt tokens but no cache reads
@@ -62,37 +73,71 @@ export function renderRunDetail(d) {
     // byte-identical (the omit-when-zero convention).
     const prompt = d.promptTokens ?? 0;
     const cached = Math.min(d.cacheReadTokens ?? 0, prompt);
-    if (prompt > 0)
-        summary.push(cached > 0 ? `prompt ${compactTokens(prompt)} tok (${Math.round((100 * cached) / prompt)}% cached)` : `prompt ${compactTokens(prompt)} tok`);
+    if (prompt <= 0)
+        return null;
+    return cached > 0 ? `prompt ${compactTokens(prompt)} tok (${Math.round((100 * cached) / prompt)}% cached)` : `prompt ${compactTokens(prompt)} tok`;
+}
+/** The run's pre-edit prompt-token share, the `… before first edit` signal a cost-only header
+ * hides: how much of the prompt budget went out before the run made its first edit. Clamped
+ * to the total (run-detail-data.ts), written after the prompt cell and before the
+ * peak-context cell; a run that reported no pre-edit reading — and an in-flight run — keeps
+ * today's header byte-identical. */
+function runPreEditCell(d) {
     // The run's pre-edit prompt-token share, the `… before first edit` signal a cost-only
     // header hides: how much of the prompt budget went out before the run made its first
     // edit. Clamped to the total (run-detail-data.ts), written after the prompt cell and
     // before the peak-context cell; a run that reported no pre-edit reading — and an
     // in-flight run — keeps today's header byte-identical.
+    const prompt = d.promptTokens ?? 0;
     const preEdit = Math.min(d.preEditPromptTokens ?? 0, prompt);
-    if (preEdit > 0)
-        summary.push(`pre-edit ${compactTokens(preEdit)} tok`);
+    if (preEdit <= 0)
+        return null;
+    return `pre-edit ${compactTokens(preEdit)} tok`;
+}
+/** The run's peak-context cell against the seam's declared window, the one header every surface
+ * renders. Omitted when the run reported no peak (byte-identical to today's header). */
+function runPeakContextCell(d) {
     // The run's peak context against the seam's declared window, the one header every surface
     // renders. Omitted when the run reported no peak (byte-identical to today's header).
-    if ((d.peakContextTokens ?? 0) > 0)
-        summary.push(`peak ctx ${contextShareLabel(d.peakContextTokens ?? 0, d.contextWindow)}`);
-    if (d.model !== null)
-        summary.push(d.model);
+    if ((d.peakContextTokens ?? 0) <= 0)
+        return null;
+    return `peak ctx ${contextShareLabel(d.peakContextTokens ?? 0, d.contextWindow)}`;
+}
+/** The run's model cell, the model the run started on. */
+function runModelCell(d) {
+    if (d.model === null)
+        return null;
+    return d.model;
+}
+/** The summary cells in today's push order — result, cut-off, duration, usage, prompt,
+ * pre-edit, peak-context, model — each present only when its guard omits nothing. */
+function runSummaryCells(d) {
+    return [runResultCell(d), runCutOffCell(d), runDurationCell(d), runUsageCell(d), runPromptCell(d), runPreEditCell(d), runPeakContextCell(d), runModelCell(d)].filter((cell) => cell !== null);
+}
+/** The header's ` · `-separated suffix cells after the summary: the pinned commit, `merged
+ * as`, end-of-run landing latency, and the deliberate-revert verdict. */
+function runHeaderSuffixCells(d) {
     const sha = runCommitSha(d);
-    let header = `${roleLabel(d.role)} run #${d.run} — ${summary.join(" · ")}`;
+    const cells = [];
     if (sha !== null)
-        header += ` · commit ${shortSha(sha)}`;
+        cells.push(`commit ${shortSha(sha)}`);
     if (d.mergedSha !== null && d.mergedSha !== sha)
-        header += ` · merged as ${shortSha(d.mergedSha)}`;
+        cells.push(`merged as ${shortSha(d.mergedSha)}`);
     // The end-of-run → on-main landing latency, the per-change twin of the day report's `Merge
     // wait median`. shortSpanPhrase is the duration cell's renderer, so both spans read alike; a
     // run without the field (rejected/failed merge, in flight, landing rotated out, no-op
     // fast-forward) keeps today's header byte-identical.
     if (d.mergeAfterRunMs !== undefined)
-        header += ` · merged ${shortSpanPhrase(d.mergeAfterRunMs)} after the run`;
+        cells.push(`merged ${shortSpanPhrase(d.mergeAfterRunMs)} after the run`);
     if (d.reverted !== null) {
-        header += ` · reverted ${shortSha(d.reverted.sha)} (by operator)`; // vocabulary-ok: the deliberate-revert writer this header names
+        cells.push(`reverted ${shortSha(d.reverted.sha)} (by operator)`); // vocabulary-ok: the deliberate-revert writer this header names
     }
+    return cells;
+}
+/** The trail lines: the run's events through the shared formatEvent, with the merge outcome
+ * line placed before the first event when it predates it (a leftover-recovery run) and after
+ * the last otherwise, keeping the trail in time order. */
+function runTrailLines(d) {
     const trail = d.events.map(formatEvent);
     if (d.merge !== null) {
         const first = d.events[0];
@@ -101,7 +146,19 @@ export function renderRunDetail(d) {
         else
             trail.push(formatEvent(d.merge));
     }
-    return [header, ...trail].join("\n");
+    return trail;
+}
+/** The human view of a RunDetail: one summary line assembled from the per-cell and
+ * per-trail-step helpers — the result (or in-flight/unpaired marker), cut-off, duration,
+ * usage, prompt, pre-edit, peak-context and model cells, then the committed sha, `merged as`,
+ * merge-latency and reverted suffix cells — and each event through formatEvent. A queued run
+ * whose merge has finished shows that verdict in the header and ends with the merge's outcome
+ * line; a leftover-recovery run's verdict is the failed attempt it re-queued
+ * (resolveQueuedResult), logged before the run began, so that outcome line leads the trail
+ * instead — the trail stays in time order. */
+export function renderRunDetail(d) {
+    const header = [`${roleLabel(d.role)} run #${d.run} — ${runSummaryCells(d).join(" · ")}`, ...runHeaderSuffixCells(d)].join(" · ");
+    return [header, ...runTrailLines(d)].join("\n");
 }
 /** The transcript block of `--transcript`: the rendered lines of the agent runs that started in the
  * run's window, or `found: []` plus the `note` the text view prints in their place. The

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

@@ -57,15 +57,11 @@ export function newestRunRow(root, role, classes, models) {
 function newestRunNumber(root, role, classes, models) {
     return newestRunRow(root, role, classes, models)?.run ?? 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 }) {
+/** The positional and role half of parseRunDetailInvocation's validation: the bare/last arity,
+ * the canonical role id, the unknown-role guard (knownRoleIdsCached) and the three arity
+ * `fail`s — one name so the whole positional surface is found by this helper. Returns whether
+ * the call is bare (`--last` with no role) and the resolved role. */
+function runDetailPositionals(root, positionals, last) {
     // 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
@@ -91,6 +87,13 @@ function parseRunDetailInvocation(root, positionals, { last, transcript, prompt,
         }
         fail(`usage: ${RUN_DETAIL_USAGE}`);
     }
+    return { bare, role };
+}
+/** The flag-dependency half of parseRunDetailInvocation's validation: the four `fail` guards —
+ * `--prompt`/`--grep` need `--transcript`, `--result`/`--model` need `--last` — one name so the
+ * whole dependency surface is found by this helper. */
+function checkRunDetailFlagDeps(flags) {
+    const { last, transcript, prompt, grep, result, model } = flags;
     if (prompt && !transcript)
         fail(`history --prompt needs --transcript (usage: ${RUN_DETAIL_USAGE})`);
     if (grep !== null && !transcript)
@@ -99,10 +102,67 @@ function parseRunDetailInvocation(root, positionals, { last, transcript, prompt,
         fail(`history --result needs --last on a one-run trail (usage: ${RUN_DETAIL_USAGE})`);
     if (model !== null && !last)
         fail(`history --model needs --last on a one-run trail (usage: ${RUN_DETAIL_USAGE})`);
+}
+/** 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. Delegates the positional/role arity to
+ * runDetailPositionals and the flag-dependency guards to checkRunDetailFlagDeps, then parses
+ * the --result class and --model selector lists. */
+function parseRunDetailInvocation(root, positionals, { last, transcript, prompt, grep, result, model }) {
+    const { bare, role } = runDetailPositionals(root, positionals, last);
+    checkRunDetailFlagDeps({ last, transcript, prompt, grep, result, model });
     const classes = result !== null ? parseHistoryResultList(result) : null;
     const models = model !== null ? parseHistoryModelList(model) : null;
     return { bare, role, classes, models };
 }
+/** The not-found branch of cmdRunDetail for the --last form: the scan came up empty, not found
+ * by construction, the last-form wording — `sayJson(null)` under --json, else
+ * runNotFoundLastMessage. */
+function runDetailLastMiss(parsed, role, json) {
+    // The --last scan came up empty: not found by construction, the last-form wording.
+    if (json)
+        sayJson(null);
+    else
+        say(runNotFoundLastMessage(parsed.bare ? null : role, parsed.classes, parsed.models));
+}
+/** The not-found branch of cmdRunDetail for the numbered form: not found stays exit 0 in both
+ * renderings, but --json still owes a parseable document in every exit-0 case (`null`), else
+ * the runNotFoundMessage prose line. */
+function runDetailNumberMiss(role, runNumber, json) {
+    // Not found stays exit 0 in both renderings, but --json still owes a parseable document in
+    // every exit-0 case (the report --json precedent, the invariant this command's own doc
+    // comment claims): `null` is the JSON answer for a single-record lookup that missed — the
+    // prose line would end a jq pipe mid-team-incident.
+    if (json)
+        sayJson(null);
+    else
+        say(runNotFoundMessage(role, runNumber));
+}
+/** The render half of cmdRunDetail: build the --stat/--patch footer and the --transcript lines,
+ * then emit the --json payload or the human-rendered trail (renderRunDetail plus the footer and
+ * transcript text). */
+async function emitRunDetail(root, role, runNumber, detail, json, opts) {
+    // --json swaps the renderer for the collector's own payload, exactly as history --json: a
+    // JSON document in every exit-0 case, never prose.
+    const footer = {};
+    if (opts.stat)
+        footer.stat = await runDetailStat(root, detail);
+    if (opts.patch)
+        footer.patch = await runDetailPatch(root, detail);
+    const transcriptLines = opts.transcript
+        ? runTranscriptLines(root, role, runNumber, detail, { includePrompts: opts.prompt, grep: opts.grep ?? undefined })
+        : null;
+    if (json) {
+        sayJson({ ...detail, ...footer, ...(transcriptLines === null ? {} : { transcript: transcriptLines.found }) });
+    }
+    else {
+        const transcriptText = transcriptLines === null
+            ? []
+            : [transcriptLines.found.length > 0 ? transcriptLines.found.join("\n") : transcriptLines.note];
+        say([renderRunDetail(detail), ...Object.values(footer), ...transcriptText].join("\n\n"));
+    }
+}
 /** 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
@@ -150,41 +210,12 @@ export async function cmdRunDetail(root, positionals, json, { last = false, stat
     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(parsed.bare ? null : role, parsed.classes, parsed.models));
+        runDetailLastMiss(parsed, role, json);
         return;
     }
     if (detail === null) {
-        // Not found stays exit 0 in both renderings, but --json still owes a parseable document in
-        // every exit-0 case (the report --json precedent, the invariant this command's own doc
-        // comment claims): `null` is the JSON answer for a single-record lookup that missed — the
-        // prose line would end a jq pipe mid-team-incident.
-        if (json)
-            sayJson(null);
-        else
-            say(runNotFoundMessage(role, runNumber));
+        runDetailNumberMiss(role, runNumber, json);
         return;
     }
-    // --json swaps the renderer for the collector's own payload, exactly as history --json: a
-    // JSON document in every exit-0 case, never prose.
-    const footer = {};
-    if (stat)
-        footer.stat = await runDetailStat(root, detail);
-    if (patch)
-        footer.patch = await runDetailPatch(root, detail);
-    const transcriptLines = transcript
-        ? runTranscriptLines(root, role, runNumber, detail, { includePrompts: prompt, grep: grep ?? undefined })
-        : null;
-    if (json) {
-        sayJson({ ...detail, ...footer, ...(transcriptLines === null ? {} : { transcript: transcriptLines.found }) });
-    }
-    else {
-        const transcriptText = transcriptLines === null
-            ? []
-            : [transcriptLines.found.length > 0 ? transcriptLines.found.join("\n") : transcriptLines.note];
-        say([renderRunDetail(detail), ...Object.values(footer), ...transcriptText].join("\n\n"));
-    }
+    await emitRunDetail(root, role, runNumber, detail, json, { stat, patch, transcript, prompt, grep });
 }

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

@@ -23,7 +23,7 @@ import { readFeedbackFilings, renderFilingsBlock } from "./feedback-filings.js";
 import { roleNotesPath } from "../paths.js";
 import * as path from "node:path";
 import { pathTokens } from "../text/text.js";
-import { isDirectory, readTextOrNull, statOrNull } from "../files/files.js";
+import { isDirectory, readRegularTextOrNull, readTextOrNull, statOrNull } from "../files/files.js";
 import { dayKey } from "../text/datetime.js";
 import { appendPromptNote, prependPromptNote } from "../text/format.js";
 import { ROLE_NOTES_MAX_BYTES } from "../agent/role-notes-write.js";
@@ -55,9 +55,11 @@ function missingEntryPaths(root, file, range) {
  * brief text reader apply to their hand-editable files. A UTF-8 character is never
  * fewer than one byte, so a note the tool accepted (≤ 4096 bytes) is always ≤ 4096 chars
  * and never trips this bound; only an over-cap file is cut, with truncateWithNote's visible
- * marker naming the loss. */
+ * marker naming the loss. A symlinked note file reads as absent (readRegularTextOrNull never
+ * follows a symlink out of the worktree, INV-G3/G4's lstat policy): a hostile note that is a
+ * symlink cannot pull an arbitrary host file's text into this role's prompt. */
 function readRoleNote(root, role) {
-    const text = readTextOrNull(roleNotesPath(root, role));
+    const text = readRegularTextOrNull(roleNotesPath(root, role));
     return text === null ? undefined : truncateWithNote(text, ROLE_NOTES_MAX_BYTES, "role notes");
 }
 /** The bugfix run's tally of checks the merge gate excused as flaky in the last day, or
@@ -199,55 +201,40 @@ function collectRoleRequest(root, role, preview) {
 function collectSelfcheckDigest(root, base) {
     return base === "selfcheck" || base === "feedback" ? selfcheckDigest(root) : undefined;
 }
-/** The `qa` observer's flow-coverage ledger: rerendered from disk each run, degrading to no
- * block on a missing or unreadable ledger (plans/observer-roles.md 2/2). */
-function collectQaCoverageBlock(root, base) {
-    // The `qa` observer's flow rotation needs a memory of what it last exercised; every run
-    // is a fresh session, and a passing cheap check leaves nothing in the repo. The ledger is
-    // runtime state, and a missing or unreadable one degrades to no block.
-    let coverage;
-    if (base === "qa") {
-        try {
-            coverage = renderCoverageBlock(readQaCoverage(root));
-        }
-        catch {
-            coverage = undefined;
-        }
+/** One observer-ledger block: rendered from disk only for its owning role, degrading to no
+ * block on a missing or unreadable ledger (a throw) so the run prompt stays byte-unchanged in
+ * the common first-run case. The `qa` (flow coverage), `ci` (parity) and `feedback` (filings)
+ * ledgers are runtime state a fresh session must not depend on, and the three collect*Block
+ * functions each rendered their ledger through this same try/catch guard before the helper. */
+function runtimeLedgerBlock(base, role, render) {
+    if (base !== role)
+        return undefined;
+    try {
+        return render();
+    }
+    catch {
+        return undefined;
     }
-    return coverage;
 }
-/** The `ci` observer's parity block: what the last run covered (tip and lock hash) so a
- * fresh session can decide nothing-to-do without re-running the whole suite (part 3/3).
- * Runtime state, and a missing/unreadable record degrades to no block, exactly like qa's. */
+/** The `qa` observer's flow-coverage ledger, rerendered from disk each run (the flow rotation
+ * needs a memory of what it last exercised — every run is a fresh session, and a passing cheap
+ * check leaves nothing in the repo), degrading to no block (plans/observer-roles.md 2/2). */
+function collectQaCoverageBlock(root, base) {
+    return runtimeLedgerBlock(base, "qa", () => renderCoverageBlock(readQaCoverage(root)));
+}
+/** The `ci` observer's parity block: what the last run covered (tip and lock hash) so a fresh
+ * session can decide nothing-to-do without re-running the whole suite (part 3/3). Degrades to
+ * no block exactly like qa's. */
 function collectCiParityBlock(root, config, base) {
-    let ciParity;
-    if (base === "ci") {
-        try {
-            ciParity = parityBlockFor(root, config);
-        }
-        catch {
-            ciParity = undefined;
-        }
-    }
-    return ciParity;
+    return runtimeLedgerBlock(base, "ci", () => parityBlockFor(root, config));
 }
 /** The `feedback` observer's per-install filing ledger: what this install already filed as
  * GitHub issues on znation/tumwater, so the fresh session's charter dedupes against a
- * "previously filed" block instead of the network alone. Runtime state, and a missing or
- * unreadable ledger degrades to no block (plans/feedback-role.md 2/2). */
+ * "previously filed" block instead of the network alone. Degrades to no block
+ * (plans/feedback-role.md 2/2); the render returns undefined for an empty ledger, so the
+ * prompt is unchanged in the common first-run case. */
 function collectFeedbackFilingsBlock(root, base) {
-    // The render returns undefined for an empty ledger, so the prompt is unchanged in the common
-    // first-run case.
-    let filings;
-    if (base === "feedback") {
-        try {
-            filings = renderFilingsBlock(readFeedbackFilings(root));
-        }
-        catch {
-            filings = undefined;
-        }
-    }
-    return filings;
+    return runtimeLedgerBlock(base, "feedback", () => renderFilingsBlock(readFeedbackFilings(root)));
 }
 /** The clean role's deterministic backlog repair: stranded plan headings in the primary
  * checkout's PLANS.md (plans, part 3/4), rendered like the digest and coverage blocks. */
@@ -258,7 +245,7 @@ function collectBacklogStructureBlock(root, base) {
 /** Read the role's own notes plus their saved day and live backlog state (notes-backlog.ts),
  * returning all three in one place. */
 function readPromptNotes(root, role) {
-    // The role's notes (PLANS.md "Role notebook"): its own earlier runs' note. A missing,
+    // The role's own notes (readRoleNote): its earlier runs' note. A missing,
     // empty, or unreadable file yields undefined, so the block is omitted; the write
     // instruction in buildRunPrompt is present either way. The director branch above never
     // reads this path, so it carries no notes.
@@ -312,15 +299,12 @@ function collectRoleDirectives(root, config, base, check) {
         : undefined;
     return { planTargetNote, flakyChecks, noCheck };
 }
-/** Append the shared claim/held/discard/cut-off tail — identical for a director and a role —
- * in its current order, and return the finished prompt. */
-function appendRunEpilogue(root, role, state, prompt, userPrompt, rejectedReview) {
+function appendAssignmentNotes(prompt, root, role, claim, userPrompt) {
     // A work instance holding a claim is told which entry is its one task (plans/parallel-work-
     // instances.md "Claims", part 4/7) — the harness picked it, so the charter's choosing step
     // is replaced. A run that dequeued a user request runs that request instead and keeps the
     // claim for the next non-request run. The range is looked up by key in the current checkout,
     // so it survives a moved section boundary.
-    const claim = role === DIRECTOR_ROLE ? undefined : state.claim;
     if (claim && userPrompt === null) {
         const range = eligibleEntries(root, role).find((e) => e.key === claim.key);
         prompt = appendPromptNote(prompt, buildAssignmentNote(claim, range, range ? missingEntryPaths(root, claim.file, range) : []));
@@ -328,20 +312,32 @@ function appendRunEpilogue(root, role, state, prompt, userPrompt, rejectedReview
         if (merged.length > 0)
             prompt = appendPromptNote(prompt, buildMergedPrerequisitesNote(merged));
     }
+    return prompt;
+}
+function appendWaitingPartsNote(prompt, root, claim, userPrompt) {
     if (claim && userPrompt === null && claim.file === "PLANS.md") {
         const waiting = waitingPartRanges(root, claim.title);
         if (waiting.length > 0)
             prompt = appendPromptNote(prompt, buildWaitingPartsNote(waiting));
     }
+    return prompt;
+}
+function appendHeldElsewhereNote(prompt, role, claim, userPrompt, state) {
     if (!claim && userPrompt === null && role !== DIRECTOR_ROLE && state.heldElsewhere?.length) {
         prompt = appendPromptNote(prompt, buildHeldEntriesNote(state.heldElsewhere));
     }
+    return prompt;
+}
+function prependRejectedReviewNote(prompt, role, rejectedReview) {
     // The director builds its prompt through buildDirectorPrompt, which does not take the rejected
     // note, so the standing rejection leads its prompt here instead (a director-authored change can
     // be rejected too). Kept uniform with the authoring roles: the reasons open the run.
     if (rejectedReview !== undefined && role === DIRECTOR_ROLE) {
         prompt = prependPromptNote(prompt, rejectedReview);
     }
+    return prompt;
+}
+function appendRunMemoryNotes(prompt, state) {
     // Likewise a change leftover recovery discarded as unmergeable: named until the role queues
     // its next change (the discarding run itself appends it after recovery — see runOnce).
     const discard = state.conflictDiscard;
@@ -355,6 +351,23 @@ function appendRunEpilogue(root, role, state, prompt, userPrompt, rejectedReview
     }
     return prompt;
 }
+/** Append the shared claim/held/discard/cut-off tail — identical for a director and a role —
+ * in its current order, and return the finished prompt. It delegates each note group to a
+ * named module-private helper: appendAssignmentNotes (which folds in the merged-prerequisite
+ * follow-up), appendWaitingPartsNote, appendHeldElsewhereNote, prependRejectedReviewNote and
+ * appendRunMemoryNotes. */
+function appendRunEpilogue(root, role, state, prompt, userPrompt, rejectedReview) {
+    // The shared cross-run tail every role prompt carries, ordinally: the claim assignment (with
+    // its merged-prerequisite and waiting-part follow-ups), the held-elsewhere note, the
+    // director's leading rejection, and the discard and cut-off run memory.
+    const claim = role === DIRECTOR_ROLE ? undefined : state.claim;
+    prompt = appendAssignmentNotes(prompt, root, role, claim, userPrompt);
+    prompt = appendWaitingPartsNote(prompt, root, claim, userPrompt);
+    prompt = appendHeldElsewhereNote(prompt, role, claim, userPrompt, state);
+    prompt = prependRejectedReviewNote(prompt, role, rejectedReview);
+    prompt = appendRunMemoryNotes(prompt, state);
+    return prompt;
+}
 /** Assemble the prompt a role's next run operates on — the whole "what should this run see"
  * concern, split out of runner.ts so the runner owns only lifecycle and the prompt owns only
  * content. Returns null when the role has nothing to run this run (a director with an empty