tumwater 0.2.0 → 0.3.0

package/dist/src/{tick/tick-prompt.js → run/run-prompt.js}

@@ -1,30 +1,34 @@
 import { allRoleIds, customRole, DIRECTOR_ROLE, roleById, unknownRoleMessage } from "../roles/roles.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
 import { planBacklogTarget } from "../scheduling/claims.js";
 import { configForRole } from "../config/config-views.js";
 import { NOTHING_TO_DO } from "../verdict/reply-contract.js";
 import { dequeuePromptEntry, dequeueRolePromptEntry, peekPrompt, peekRolePrompt } from "../inbox/inbox.js";
 import { stripNotBeforeMarker } from "../inbox/prompt-not-before.js";
-import { readBrief } from "../brief/brief.js";
-import { buildDirectorPrompt, buildTickPrompt } from "../prompt/prompt.js";
+import { briefFile } from "../brief/brief.js";
+import { buildDirectorPrompt, buildRunPrompt } from "../prompt/prompt.js";
 import { readPrinciples } from "../prompt/principles.js";
 import { buildCutOffNote } from "../prompt/prompt-followup.js";
-import { buildAssignmentNote, buildConflictDiscardNote, buildHeldEntriesNote, buildMergedPrerequisitesNote, buildRejectedReviewNote, buildWaitingPartsNote } from "../prompt/gate-prompts.js";
+import { buildAssignmentNote, buildConflictDiscardNote, buildHeldEntriesNote, buildMergedPrerequisitesNote, buildRejectedReviewNote, buildWaitingPartsNote } from "../prompt/gate-notes.js";
 import { eligibleEntries, mergedPrerequisiteRanges, waitingPartRanges } from "../backlog/backlog-eligibility.js";
-import { detectBuildCheck } from "../build/build-check-detect.js";
+import { notesBacklogBlock } from "../prompt/notes-backlog.js";
+import { donePlans, openBugEntries, plannedPlanEntries } from "../backlog/backlog.js";
+import { detectBuildCheck, gateCommandOf } from "../build/build-check-detect.js";
 import { flakeCounts, KNOWN_FLAKE_WINDOW_MS } from "../review/known-flakes.js";
 import { readEventsSince } from "../events/event-window.js";
-import { telemetryDigest } from "./telemetry-digest.js";
+import { selfcheckDigest } from "./selfcheck-digest.js";
 import { readQaCoverage, renderCoverageBlock } from "./qa-coverage.js";
+import { readFeedbackFilings, renderFilingsBlock } from "./feedback-filings.js";
 import { roleNotesPath } from "../paths.js";
 import * as path from "node:path";
-import { pathTokens } from "./stage-check.js";
-import { readTextOrNull, statOrNull } from "../files/files.js";
+import { pathTokens } from "../text/text.js";
+import { isDirectory, readTextOrNull, statOrNull } from "../files/files.js";
 import { dayKey } from "../text/datetime.js";
-import { appendPromptNote } from "../text/format.js";
+import { appendPromptNote, prependPromptNote } from "../text/format.js";
 import { ROLE_NOTES_MAX_BYTES } from "../agent/role-notes-write.js";
 import { truncateWithNote } from "../text/text.js";
-import { renderBacklogIndexBlock, renderBacklogStructureBlock } from "../backlog/backlog-structure.js";
+import { renderBacklogStructureBlock } from "../backlog/backlog-structure.js";
+import { renderBacklogIndexBlock } from "../backlog/backlog-index.js";
 /** The repo paths the entry at `file` lines `range` names that are absent from the checkout at
  * `root`: tokens whose first segment is a directory there but which do not exist themselves —
  * the self-check's top-level-directory rule, read from the working tree. */
@@ -35,19 +39,19 @@ function missingEntryPaths(root, file, range) {
     const entry = text.split("\n").slice(range.start - 1, range.end).join("\n");
     return pathTokens(entry).filter((p) => {
         const top = p.slice(0, p.indexOf("/"));
-        return statOrNull(path.join(root, top))?.isDirectory() === true && statOrNull(path.join(root, p)) === null;
+        return isDirectory(path.join(root, top)) && statOrNull(path.join(root, p)) === null;
     });
 }
-/** Read a role's notebook through files.ts's readTextOrNull — the one read-and-swallow
+/** Read a role's notes through files.ts's readTextOrNull — the one read-and-swallow
  * step — or undefined when it is missing or unreadable (an empty or whitespace-only note is
- * left for buildTickPrompt to omit). The degradation is deliberate: a torn or absent
- * runtime-state file must never fail a tick.
+ * left for buildRunPrompt to omit). The degradation is deliberate: a torn or absent
+ * runtime-state file must never fail a run.
  *
  * The note is bounded on read as well as on write: the write path rejects text over
  * ROLE_NOTES_MAX_BYTES, but the file lives in hand-editable runtime state, so an oversized
  * note (an old build, a manual edit) would otherwise ride into every one of this role's
- * prefill-heavy tick prompts uncapped. The same defensive backstop readPrinciples and the
- * initial-prompt reader apply to their hand-editable files. A UTF-8 character is never
+ * prefill-heavy run prompts uncapped. The same defensive backstop readPrinciples and the
+ * 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. */
@@ -78,42 +82,47 @@ function flakyChecksNote(root) {
         `names one of these, that bug is still firing. When \`## Open\` holds no entries, a check ` +
         `excused 2 or more times is a confirmed latent bug: take it as this run's latent-bug candidate.`);
 }
-/** Assemble the prompt a loop's next tick runs on — the whole "what should this tick see"
- * concern, split out of loop.ts so the runner owns only lifecycle and the prompt owns only
- * content. Returns null when the loop has nothing to run this tick (a director with an empty
+/** Assemble the prompt a role's next run runs 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
  * inbox); `userPrompt` carries the dequeued user request — the director's, or a per-role one
  * queued by `tumwater prompt --role <id>` — back so the runner can record it as pending and
- * re-queue it if the tick leaves it unfulfilled; `userPromptFile` is the queue file it came
+ * re-queue it if the run leaves it unfulfilled; `userPromptFile` is the queue file it came
  * from, so that bookkeeping can clean the prompt's attachments by that file's stem. */
-export function assembleTickPrompt({ root, config, role, state, preview = false, agent, compact = false }) {
-    // One read of the brief yields both the prompt it carries and the owning file's name
-    // (brief.ts's readBrief): readInitialPrompt + briefFile were two full reads of the same
-    // file on this per-tick path.
-    const briefState = readBrief(root);
-    const initialPrompt = briefState?.prompt ?? "";
+export function assembleRunPrompt({ root, config, role, state, preview = false, backend }) {
     // The brief's owning file (TUMWATER.md first, README.md as the compatibility path —
     // plans/portability.md §7a/7), named in both prompt builders' rules instead of a hardcoded
     // README.md. "README.md" is the fallback for a repo with no marked file yet — the team
     // runs blind on prompts either way, so the name in the rules should still point somewhere.
-    const brief = briefState?.file ?? "README.md";
-    // The project's design principles ride along in every prompt — tick and director alike — so
-    // all loops share one standard of taste. Empty when the repo has no PRINCIPLES.md.
+    const brief = briefFile(root) ?? "README.md";
+    // The project's design principles ride along in every prompt — run and director alike — so
+    // all roles share one standard of taste. Empty when the repo has no PRINCIPLES.md.
     const principles = readPrinciples(root);
     // The project's resolved check (plans/portability.md §6/7): the prompt names the actual
     // verify command instead of asserting npm. Detection is a handful of stat calls — a
-    // per-tick recompute keeps a config edit live on the next tick.
+    // per-run recompute keeps a config edit live on the next run.
     const check = detectBuildCheck(root, config) ?? undefined;
-    // The bounded actionable index every tick and director prompt carries, replacing the model's
-    // per-tick `grep -n '^##'` map of the backlog files (BUGS.md 2026-10-06). One render serves
-    // both branches; the worktree starts at main at tick start, so the ranges hold then.
+    // The bounded actionable index every run and director prompt carries, replacing the model's
+    // per-run `grep -n '^##'` map of the backlog files (BUGS.md 2026-10-06). One render serves
+    // both branches; the worktree starts at main at run start, so the ranges hold then.
     const backlogIndex = renderBacklogIndexBlock(root);
+    // A change rejected in review is the only cross-run memory of what was built and why it
+    // failed — every run starts a fresh session, so the full reasons (with the reviewed head and
+    // timestamp) ride along on the next prompt until the role's next reviewed change replaces
+    // them. buildRunPrompt renders it at the very top, before the role charter, so the author
+    // cannot miss it (plans/reviewer-as-role.md part 4/4). A revision run carries the reasons in
+    // buildRevisionNote instead (the rejected diff is already in the worktree), so the note is
+    // suppressed here exactly as it was before this part.
+    const rejectedReview = (state.lastReview?.verdict === "reject" || state.lastReview?.verdict === "reverted") && !state.revision
+        ? buildRejectedReviewNote(state.lastReview, role)
+        : undefined;
     let prompt;
     let userPrompt = null;
     let userPromptFile = null;
     if (role === DIRECTOR_ROLE) {
         // A deferred director prompt's `tumwater:not-before` marker line is plumbing
         // (src/inbox/prompt-not-before.ts),
-        // not content — stripped here exactly like the per-role path below, so the director's tick
+        // not content — stripped here exactly like the per-role path below, so the director's run
         // prompt and the runner's re-queue both see the operator's text alone.
         const entry = preview ? null : dequeuePromptEntry(root);
         const dequeued = preview ? peekPrompt(root) : entry?.text ?? null;
@@ -121,42 +130,41 @@ export function assembleTickPrompt({ root, config, role, state, preview = false,
             return null;
         userPrompt = stripNotBeforeMarker(dequeued);
         userPromptFile = entry?.file ?? null;
-        // The compact prompt leaves the brief block out: the director reads the brief file in full,
-        // and that file carries the same text.
-        prompt = buildDirectorPrompt(userPrompt, compact ? "" : initialPrompt, principles, check, brief, undefined, backlogIndex, agent ?? configForRole(config, DIRECTOR_ROLE).agent, compact, config.roles[DIRECTOR_ROLE]?.instructions);
+        prompt = buildDirectorPrompt(userPrompt, principles, check, brief, undefined, backlogIndex, backend ?? configForRole(config, DIRECTOR_ROLE).agent, config.roles[DIRECTOR_ROLE]?.instructions);
     }
     else {
-        // The loop id keys its inbox and notebook; every lookup ABOUT the role — catalog charter,
+        // The role id keys its inbox and notes; every lookup ABOUT the role — catalog charter,
         // instructions, the qa/selfcheck/clean blocks — resolves through the base role, so
         // `feature-2` runs the feature charter and `roles.feature.instructions` while keeping its
         // own queue and notes (plans/parallel-work-instances.md).
         const base = baseRoleOf(role);
-        // Catalog first, then user-defined loops (plans/user-defined-loops.md): a custom's task
+        // Catalog first, then user-defined roles (plans/user-defined-loops.md): a custom's task
         // is its entire find-something-to-do text and the title identifies it in the prompt.
         const custom = config.customRoles.find((c) => c.name === role);
         const resolved = roleById(role) ?? (custom ? customRole(custom.name, custom.task) : undefined);
         if (!resolved) {
             // The shared unknownRoleMessage (parseRoleFlag, the operator commands) names the valid
-            // ids; this defensive path — a runner asked to tick a role no catalog entry or
+            // ids; this defensive path — a runner asked to run a role no catalog entry or
             // customRoles task can answer — says the same, so if it ever fires it reads as the
             // harness bug it is instead of a bare dead end.
             const validIds = [...allRoleIds(), ...config.customRoles.map((c) => c.name)];
             throw new Error(unknownRoleMessage(role, validIds));
         }
         // A queued per-role prompt is dequeued here, before the prompt is built, so its text rides
-        // in the tick's prompt; PendingPrompt records it as pending and re-queues it on every
+        // in the run's prompt; PendingPrompt records it as pending and re-queues it on every
         // unfulfilled outcome — including a red-main gate block, which returns before any run.
         // A deferred prompt's `tumwater:not-before` marker line is plumbing
         // (src/inbox/prompt-not-before.ts), not
-        // content: it is stripped at delivery, so the loop sees the operator's text alone and the
+        // content: it is stripped at delivery, so the role sees the operator's text alone and the
         // runner's re-queue writes clean text.
         const entry = preview ? null : dequeueRolePromptEntry(root, role);
         const dequeued = preview ? peekRolePrompt(root, role) : entry?.text ?? null;
         const request = dequeued === null ? null : stripNotBeforeMarker(dequeued);
-        // The selfcheck role's evidence is the harness's own event log, one level outside this
-        // worktree, so its evidence module renders it (telemetryDigest) and the tick injects it.
-        const digest = base === "selfcheck" ? telemetryDigest(root) : undefined;
-        // The `qa` observer's flow rotation needs a memory of what it last exercised; every tick
+        // The selfcheck and feedback observers' evidence is the harness's own event log, one level
+        // outside this worktree, so its evidence module renders it (selfcheckDigest) and the run
+        // injects it.
+        const digest = base === "selfcheck" || base === "feedback" ? selfcheckDigest(root) : undefined;
+        // 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
         // (plans/observer-roles.md 2/2).
@@ -169,23 +177,49 @@ export function assembleTickPrompt({ root, config, role, state, preview = false,
                 coverage = undefined;
             }
         }
+        // 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).
+        // 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;
+            }
+        }
         // 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.
         // An unreadable or clean file gives no block, so the prompt is unchanged in the common case.
         const backlogStructure = base === "clean" ? renderBacklogStructureBlock(root) : undefined;
-        // The role's notebook (PLANS.md "Role notebook"): its own earlier ticks' note. A missing,
+        // The role's notes (PLANS.md "Role notebook"): its own earlier runs' note. A missing,
         // empty, or unreadable file yields undefined, so the block is omitted; the write
-        // instruction in buildTickPrompt is present either way. The director branch above never
-        // reads this path, so it carries no notebook.
+        // instruction in buildRunPrompt is present either way. The director branch above never
+        // reads this path, so it carries no notes.
         const notes = readRoleNote(root, role);
         // The note file's mtime is when the notes were last saved (writes replace the file), so the
         // run can weigh how stale they are.
         const savedStat = notes === undefined ? null : statOrNull(roleNotesPath(root, role));
         const notesSavedDay = savedStat ? dayKey(savedStat.mtimeMs) : undefined;
+        // The live state of each entry and series the notes name, so a stale note cannot keep a hold
+        // the backlog has lifted (notes-backlog.ts). The three readers are already stat-cached. A
+        // note naming nothing live yields undefined and no block — the common case, since most notes
+        // are about the code, not the backlog.
+        const notesBacklog = notes === undefined || notes.trim() === ""
+            ? undefined
+            : notesBacklogBlock(notes, {
+                planned: plannedPlanEntries(root),
+                openBugs: openBugEntries(root),
+                donePlanTitles: donePlans(root),
+            });
         // The plan charter's stop threshold is derived from config (plans/parallel-work-
-        // instances.md "…keeping the plan loop ahead", part 5c/7). The catalog text stays a
+        // instances.md "…keeping the plan role ahead", part 5c/7). The catalog text stays a
         // config-free description of the rule; this note supplies the concrete eligible-plan count
-        // so the plan loop stops only once every configured feature instance has a plan waiting.
+        // so the plan role stops only once every configured feature instance has a plan waiting.
         const planTargetNote = base === "plan"
             ? `This run's stop target: when PLANS.md \`## Planned\` already holds ` +
                 `${planBacklogTarget(config)} or more eligible plans, end with ${NOTHING_TO_DO}. ` +
@@ -194,30 +228,31 @@ export function assembleTickPrompt({ root, config, role, state, preview = false,
             : undefined;
         const flakyChecks = base === "bugfix" ? flakyChecksNote(root) : undefined;
         // A run holding a claim with no queued request is assigned its one entry (the assignment
-        // note below). In the compact prompt such a run reads that entry first, so the backlog index
-        // — what an unassigned run chooses its task from — stays out. The brief block stays out of
-        // every compact prompt: an unassigned run reads the brief file in full, which carries the
-        // same text, and an assigned one reads it only when its entry needs it.
-        const variant = compact ? { assigned: state.claim !== undefined && request === null } : undefined;
-        prompt = buildTickPrompt({
+        // note below). Such a run reads that entry first, so the backlog index — what an unassigned
+        // run chooses its task from — stays out.
+        const assigned = state.claim !== undefined && request === null;
+        prompt = buildRunPrompt({
             role: resolved,
-            initialPrompt: compact ? "" : initialPrompt,
             principles,
             digest,
             coverage,
+            filings,
             backlogStructure,
-            backlogIndex: variant?.assigned ? undefined : backlogIndex,
+            backlogIndex: assigned ? undefined : backlogIndex,
             notes,
             notesSavedDay,
+            notesBacklog,
             planTargetNote,
             flakyChecks,
             extraInstructions: config.roles[base]?.instructions,
             check,
+            gateCommand: gateCommandOf(config),
             briefFile: brief,
-            agent: agent ?? configForRole(config, role).agent,
-            compact: variant,
+            agent: backend ?? configForRole(config, role).agent,
+            assigned,
+            rejectedReview,
             // A per-role prompt queued by `tumwater prompt --role <id>` rides as an explicit user
-            // request block; its text is also the tick's userPrompt,
+            // request block; its text is also the run's userPrompt,
             // so the runner's pending-prompt machinery (re-queue on unfulfilled, clear on merge)
             // treats it exactly like the director's dequeued request.
             userRequest: request ?? undefined,
@@ -229,8 +264,8 @@ export function assembleTickPrompt({ root, config, role, state, preview = false,
     }
     // 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 tick that dequeued a user request runs that request instead and keeps the
-    // claim for the next non-request tick. The range is looked up by key in the current checkout,
+    // 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) {
@@ -238,28 +273,28 @@ export function assembleTickPrompt({ root, config, role, state, preview = false,
         prompt = appendPromptNote(prompt, buildAssignmentNote(claim, range, range ? missingEntryPaths(root, claim.file, range) : []));
         const merged = claim.file === "PLANS.md" ? mergedPrerequisiteRanges(root, claim.title) : [];
         if (merged.length > 0)
-            prompt = appendPromptNote(prompt, buildMergedPrerequisitesNote(merged, compact));
+            prompt = appendPromptNote(prompt, buildMergedPrerequisitesNote(merged));
     }
     if (claim && userPrompt === null && claim.file === "PLANS.md") {
         const waiting = waitingPartRanges(root, claim.title);
         if (waiting.length > 0)
-            prompt = appendPromptNote(prompt, buildWaitingPartsNote(waiting, compact));
+            prompt = appendPromptNote(prompt, buildWaitingPartsNote(waiting));
     }
     if (!claim && userPrompt === null && role !== DIRECTOR_ROLE && state.heldElsewhere?.length) {
         prompt = appendPromptNote(prompt, buildHeldEntriesNote(state.heldElsewhere));
     }
-    // A change rejected in review is the only cross-tick memory of what was built and why it
-    // failed — every tick starts a fresh session, so the full reasons ride along on the next
-    // prompt until the role's next reviewed change replaces them.
-    if (state.lastReview?.verdict === "reject" && !state.revision) {
-        prompt = appendPromptNote(prompt, buildRejectedReviewNote(state.lastReview, role));
+    // 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);
     }
     // Likewise a change leftover recovery discarded as unmergeable: named until the role queues
-    // its next change (the discarding tick itself appends it after recovery — see runTick).
+    // its next change (the discarding run itself appends it after recovery — see runOnce).
     const discard = state.conflictDiscard;
     if (discard)
         prompt = appendPromptNote(prompt, buildConflictDiscardNote(discard.summary, discard.attempts));
-    // A fresh tick after the previous run(s) were cut off at the context ceiling (the loop
+    // A fresh run after the previous run(s) were cut off at the context ceiling (the role
     // stopped resuming, or never resumed — the director re-runs its prompt fresh): the only
     // memory that the last attempt was too big for the window is this note.
     if ((state.cutOffStreak ?? 0) > 0) {

package/dist/src/{tick/tick-resume.js → run/run-resume.js}

@@ -1,26 +1,52 @@
-import { agentSessionResumable } from "../agent/agent-backend.js";
+import { backendSessionResumable } from "../agent/agent-backend.js";
 import { latestSession } from "../agent/session-ledger.js";
 import { RETRIABLE_MERGE_RESULTS } from "../merge/merge-core.js";
 import { sessionDir } from "../paths.js";
 import { buildHandoffPrompt, buildResumePrompt } from "../prompt/prompt-followup.js";
-/** Decide how a tick starts, consuming the resume flags as a side effect (the flag is
- * consumed here so a resume that fails falls back to a normal fresh tick; another shutdown
- * mid-resume sets it again) and reclaiming the interrupted tick's re-queued prompt. Returns
- * null — meaning the tick is skipped — when the loop has nothing to run (an empty director
- * inbox); a role loop's assembly never returns null. */
-export function planTickStart(opts) {
+import { appendPromptNote } from "../text/format.js";
+/** Whether a run takes back the work an earlier run of its role left unsettled
+ * (src/git/slot-salvage.ts): an authoring run of the role's own work does, while a promptless
+ * recovery run (it authors nothing) and a user's request (the edits are not about it) leave the
+ * patch waiting for a later run. */
+export function takesSalvagedWork(plan) {
+    return plan.prompt !== null && plan.userPrompt === null;
+}
+/** The plan of a run whose fresh checkout just had its role's salvaged work restored into it
+ * (`restored`, the patch's root-relative path). A fresh run becomes a `salvaged` handoff over
+ * those edits: a fresh session told they are there, which skips the fresh path's reset as every
+ * handoff does. A resume or handoff keeps its plan: its kept slot was lost, and the restore gives
+ * it back the edits it expects. `note`, when the restore left conflicts or hunks it could not
+ * place (buildSalvageRestoreNote), is appended to either prompt. */
+export function planWithSalvagedWork(role, plan, restored, note) {
+    if (plan.prompt === null)
+        return { ...plan, restored };
+    const handingOff = !plan.resuming && !plan.handoff;
+    const prompt = handingOff ? buildHandoffPrompt(role, plan.prompt, "salvaged") : plan.prompt;
+    return {
+        ...plan,
+        ...(handingOff ? { handoff: true, resumeCause: "salvaged" } : {}),
+        prompt: note === undefined ? prompt : appendPromptNote(prompt, note),
+        restored,
+    };
+}
+/** Decide how a run starts, consuming the resume flags as a side effect (the flag is
+ * consumed here so a resume that fails falls back to a normal fresh run; another shutdown
+ * mid-resume sets it again) and reclaiming the interrupted run's re-queued prompt. Returns
+ * null — meaning the run is skipped — when the role has nothing to run (an empty director
+ * inbox); a role runner's assembly never returns null. */
+export function planRunStart(opts) {
     const s = opts.state;
     // The last merge's failure, read before the clear below: a merge that failed
     // non-terminally kept its pin (the merger's own vocabulary — review_error, merge_conflict,
-    // merge_blocked — with the detail it wrote into `lastError`), and when this tick's recovery
-    // re-queues that pin, the failure must still feed the error streak (finishRecoveryTick).
+    // merge_blocked — with the detail it wrote into `lastError`), and when this run's recovery
+    // re-queues that pin, the failure must still feed the error streak (finishRecoveryRun).
     const priorMergeFailure = s.lastResult !== undefined && RETRIABLE_MERGE_RESULTS.has(s.lastResult)
         ? (s.lastError ?? `merge failed: ${s.lastResult}`)
         : undefined;
     s.lastError = undefined;
-    // A tick interrupted by a harness shutdown left its pi session and its worktree's
+    // A run interrupted by a harness shutdown left its pi session and its worktree's
     // uncommitted edits in place: resume that session instead of starting fresh. The flag
-    // is consumed here so a resume that fails falls back to a normal fresh tick; another
+    // is consumed here so a resume that fails falls back to a normal fresh run; another
     // shutdown mid-resume sets it again. Nothing to resume (sessions pruned, or pi never
     // started) also falls back to fresh.
     //
@@ -34,7 +60,7 @@ export function planTickStart(opts) {
     const resumePending = s.resumePending === true;
     // The previous run's own verdict that its `--resume` target is gone is authoritative over the
     // transcript check: a lingering transcript (a torn/empty file, or the fake's planted one) must
-    // not re-arm a resume the backend just rejected, or the loop re-resumes and re-fails forever.
+    // not re-arm a resume the backend just rejected, or the role re-resumes and re-fails forever.
     const resumeMissing = s.resumeMissing === true;
     const latest = resumePending ? latestSession(dir) : null;
     // Our backend decides whether the newest session of this kind is actually resumable: pi
@@ -42,18 +68,18 @@ export function planTickStart(opts) {
     // claude resumes an id (safe across a newer gate line). A backend with no `resumable` hook
     // falls back to the backend-neutral session-file check.
     const resumable = resumePending && !resumeMissing
-        ? agentSessionResumable(dir, { kind: "author", agent }, opts.claudeConfigDir)
+        ? backendSessionResumable(dir, { kind: "author", agent }, opts.claudeConfigDir)
         : false;
     const resumableSession = resumable;
     // A newest line our backend cannot resume is not ours to continue: another kind's or
     // another agent's session, OR our own author line whose session the backend no longer holds
     // (a `--resume` that answered "No conversation found" mid-run, leaving `resumeMissing`, or a
     // pruned session dir). In every such case the interrupted run's uncommitted edits still
-    // deserve a handoff rather than the fresh path's worktree reset: the next tick runs a FRESH
-    // session over the kept worktree, carrying the assembled tick prompt plus the handoff
+    // deserve a handoff rather than the fresh path's worktree reset: the next run runs a FRESH
+    // session over the kept worktree, carrying the assembled run prompt plus the handoff
     // bridge (plans/agent-backends.md "Sessions"). The failed `resumeMissing` run arms
     // `resumePending` and records `resumeMissing` from the verdict (its error turn carries no
-    // assistant content), so the very next tick ends up here with the worktree intact. A dir with
+    // assistant content), so the very next run ends up here with the worktree intact. A dir with
     // no ledger line at all is not a handoff — there is no recorded interrupted session to carry
     // forward.
     // Captured before the flag is consumed below; a stale cause must not leak into a later resume.
@@ -63,7 +89,7 @@ export function planTickStart(opts) {
     // and claude keeps no flags across `--resume` (plans/agent-backends.md §7, part 7a/7).
     const budgetCapped = pendingResumeCause === "budget-capped";
     // An image-blind run with an image-capable peer tier ends `aborted` with this cause
-    // (plans/image-input.md part 4/5): the next tick runs a FRESH session on the TARGET seam
+    // (plans/image-input.md part 4/5): the next run runs a FRESH session on the TARGET seam
     // over the kept worktree — never `--continue` — because the old session carries pi's
     // "image omitted" note and the target may be a different backend.
     const imageReroute = pendingResumeCause === "image-reroute";
@@ -73,7 +99,7 @@ export function planTickStart(opts) {
     s.resumeMissing = undefined;
     // An interruption during the review gate leaves the author's work fully committed — there
     // is nothing left to finish in its session. Recover (and re-review) the leftover commits
-    // via a fresh tick instead: continuing the author session would burn a run on finished
+    // via a fresh run instead: continuing the author session would burn a run on finished
     // work, and any uncommitted edits are the reviewer's stray output, discarded by the fresh
     // path's reset below.
     const resumeBlocked = s.phase === "review";
@@ -81,14 +107,14 @@ export function planTickStart(opts) {
     // when its transcript is still resumable: it hands off instead.
     const resuming = resumableSession && !resumeBlocked && !budgetCapped && !imageReroute;
     const handingOff = handoff && !resumeBlocked;
-    // Reclaim the prompt the interrupted tick re-queued for its resume (src/inbox/pending-prompt.ts):
-    // the resumed session still owns that request in its context, so this tick's bookkeeping
+    // Reclaim the prompt the interrupted run re-queued for its resume (src/inbox/pending-prompt.ts):
+    // the resumed session still owns that request in its context, so this run's bookkeeping
     // operates on the queue's copy. A handoff runs a FRESH session, so it does not reclaim — the
-    // fresh tick dequeues the re-queued request like any other. Consumed even when this tick does
+    // fresh run dequeues the re-queued request like any other. Consumed even when this run does
     // not resume, so a stale record never survives into a later resume.
     opts.pending.reclaimForResume(s, resuming);
     // Why the resume: a named quiet-kill means the last run died on a stalled tool call (the
-    // bridge then warns against re-running it unchanged) or on the tick deadline while still
+    // bridge then warns against re-running it unchanged) or on the run deadline while still
     // making progress (the bridge asks for the smallest finish against the same limit); a
     // cut-off streak means the last run ran out of context and pi compacted the session (the
     // bridge asks for the smallest finish); otherwise a shutdown/crash. A handoff names itself,
@@ -105,7 +131,7 @@ export function planTickStart(opts) {
         prompt = buildResumePrompt(opts.role, resumeCause, agent);
     }
     else {
-        const assembled = opts.tickPrompt(agent, opts.compact);
+        const assembled = opts.runPrompt(agent);
         // The image-reroute handoff note names the model the blind run was on and the image it
         // read; those facts ride the one-shot marker, which is consumed here. A handoff's fresh
         // session also needs the to-be-run model named for its own side of the note, but the
@@ -122,9 +148,12 @@ export function planTickStart(opts) {
                     ? buildHandoffPrompt(opts.role, assembled, resumeCause, rerouteFacts)
                     : assembled;
     }
-    if (prompt === null)
-        return null;
-    // The raw user prompt a director tick is executing (null for role loops), so an
+    if (prompt === null) {
+        if (!opts.recoveryOnly)
+            return null;
+        return { priorMergeFailure, resuming: false, handoff: false, resumeCause, prompt: null, userPrompt: null };
+    }
+    // The raw user prompt a director run is executing (null for role runners), so an
     // unfulfilled outcome below can re-queue it. Captured before the field is cleared.
     const userPrompt = opts.pending.get();
     return { priorMergeFailure, resuming, handoff: handingOff, resumeCause, prompt, userPrompt };