tumwater 0.2.0 → 0.4.0

package/dist/src/roles/role-view.js

@@ -1,8 +1,7 @@
-// vocabulary: plain
-/** One loop's read-only inspection payload — the collector behind `tumwater role <id>`:
- * what the loop IS (catalog entry or custom, enabled, paused, tier), what it RUNS ON
+/** One role's read-only inspection payload — the collector behind `tumwater role <id>`:
+ * what the role IS (catalog entry or custom, enabled, paused, tier), what it RUNS ON
  * (resolved provider/model, the budget fallback pair), what it CARRIES (the instructions
- * override and the role's own find text verbatim), and what its NEXT tick's prompt will
+ * override and the role's own find text verbatim), and what its NEXT run's prompt will
  * read like, assembled through the preview seam so nothing queued is consumed. Split out
  * of cli.ts like backlogPayload and status/status-data.ts's snapshot so the collector is testable
  * without the CLI and one renderer consumes exactly this shape. Every read degrades like
@@ -13,23 +12,26 @@ import { defaultConfig, enabledRoleIds, isCustomRole, knownRoleIds, loadConfigSa
 import { DIRECTOR_ROLE, customRole, roleById, roleTier, unknownRoleMessage } from "./roles.js";
 import { queuedRolePromptCount } from "../inbox/inbox.js";
 import { pausedRoles } from "../team/team-state.js";
-import { loadLoopState } from "../loop/loop-state.js";
-import { baseRoleOf, loopIds, loopPaused } from "./loop-ids.js";
+import { loadRunnerState } from "../runner/runner-state-load.js";
+import { baseRoleOf, runnerIds, runnerPaused } from "./runner-ids.js";
 import { roleCapVerdicts } from "../gates/role-cap-gates.js";
 import { yieldMultiplierFor } from "../scheduling/backoff.js";
 import { quietHoursStatus } from "../scheduling/quiet-hours.js";
-import { assembleTickPrompt } from "../tick/tick-prompt.js";
-import { configForRole, resolvedModelFields, reviewRunConfig, roleSeamTier, seamConcurrencyKey } from "../config/config-views.js";
+import { assembleRunPrompt } from "../run/run-prompt.js";
+import { configForRole, resolvedModelFields, reviewedAfterMerge, reviewRunConfig, roleSeamTier, seamConcurrencyKey } from "../config/config-views.js";
 import { fallbackPair, modelFallbackView } from "../config/config-fallbacks.js";
 import { fallbackModelPair, piModelsPath, seamContextWindow } from "../pi/pi-models.js";
 import { readOpencodeCache } from "../agent/opencode/opencode-catalog.js";
 import { formatModelSelector } from "../config/model-selector.js";
 import { roleImageInfo } from "../agent/image-input.js";
+import { readPiListedModels } from "../pi/pi-listed-models.js";
 import { readImageProbeCache } from "../doctor/image-probe.js";
 import { piSettingsPath, readPiDefaultModel } from "../pi/pi-settings.js";
-import { claudeWindowEntries, readClaudeAccount } from "../agent/claude/claude-account.js";
+import { readClaudeAccount } from "../agent/claude/claude-account.js";
+import { readAccount, windowEntries } from "../agent/subscription-account.js";
 import { CONFIG_BASENAME, configPath, roleNotesPath } from "../paths.js";
-import { readTextOrNull } from "../files/files.js";
+import { coverageRows, readQaCoverage } from "../run/qa-coverage.js";
+import { readTextOrNull, statOrNull } from "../files/files.js";
 import { eventRole, eventUsage, readEvents } from "../events/event-read.js";
 import { finiteNumber, objectOrEmpty } from "../files/json-object.js";
 import { canonicalRoleId } from "./legacy-role-ids.js";
@@ -49,7 +51,7 @@ export function rawRoleField(root, roleId, field) {
         return undefined;
     return obj[field];
 }
-/** Collect one loop's inspection payload. `modelsPath` overrides pi's model definitions location
+/** Collect one role's inspection payload. `modelsPath` overrides pi's model definitions location
  * — a test seam, like status/status-data.ts's snapshot — consulted only when a fallback pair is
  * configured (the freeness verdict needs the definitions; nothing else does). */
 export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now = new Date()) {
@@ -61,30 +63,37 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
     const cfg = config ?? defaultConfig();
     const catalog = roleById(role);
     const customEntry = cfg.customRoles.find((c) => c.name === role);
-    // The director is inspectable like any loop but has no catalog entry: a pseudo-Role whose
+    // The director is inspectable like any role but has no catalog entry: a pseudo-Role whose
     // find text is empty (rolePayload nulls it below — the director's queued prompts ARE its
     // work), so the unknown-role throw only fires for ids nothing can answer.
     const resolved = catalog ??
         (customEntry ? customRole(customEntry.name, customEntry.task)
             : role === DIRECTOR_ROLE ? { id: DIRECTOR_ROLE, title: DIRECTOR_ROLE, find: "" }
                 : undefined);
-    if (!resolved) {
+    // roleById maps any `feature-N` to its base whatever the config runs, so an instance id
+    // counts only when knownRoleIds (the ids the config runs) holds it.
+    if (!resolved || !knownRoleIds(cfg).includes(role)) {
         // The one unknown-role answer (unknownRoleMessage): the CLI's main catch turns the throw
         // into `tumwater: <message>` with exit 1, so the collector keeps the wording and the CLI
         // stays a thin peel-parse-print layer.
         throw new Error(unknownRoleMessage(role, knownRoleIds(cfg)));
     }
     const effective = configForRole(cfg, role);
-    // The claude billing answer, read when a claude seam is in play — the role's OWN seam, or
-    // the review gate's when the reviewer runs claude (PLANS.md "Mixed claude + pi fleets, part
-    // 3/4" gap 7): a pi author on a claude reviewer still shows where its changes' spend lands.
-    // Its subscription window's primary type rides along for the renderer's label. The account
-    // file is team-global, so either seam reads the same answer.
-    const claudeInPlay = effective.agent === "claude" || (cfg.review.enabled && reviewRunConfig(cfg).agent === "claude");
-    const account = claudeInPlay ? readClaudeAccount(root) : null;
+    // The subscription backend whose billing is in play — the role's OWN seam when it routes
+    // to a non-pi backend, else the review gate's backend when the reviewer runs a non-pi
+    // backend (today's claude precedence generalized off the literal "claude", part 3c/9;
+    // PLANS.md "Mixed claude + pi fleets, part 3/4" gap 7): a pi author on a claude/codex
+    // reviewer still shows where its changes' spend lands. Read that backend's account; the
+    // account file is team-global, so either seam reads the same answer. Its subscription
+    // window's primary type rides along for the renderer's label.
+    const roleBackend = effective.agent !== undefined && effective.agent !== "pi" ? effective.agent : undefined;
+    const reviewAgent = reviewRunConfig(cfg).agent;
+    const reviewBackend = cfg.review.enabled && reviewAgent !== undefined && reviewAgent !== "pi" ? reviewAgent : undefined;
+    const billingBackend = roleBackend ?? reviewBackend;
+    const account = billingBackend !== undefined ? readAccount(root, billingBackend) : null;
     const info = readOrchestratorInfo(root);
     const chainStep = (orchestratorAlive(root, info) && info?.chain?.[roleSeamTier(cfg, role)]) || null;
-    const billingWindow = account?.billing === "subscription" ? claudeWindowEntries(account)[0]?.type : undefined;
+    const billingWindow = account?.billing === "subscription" ? windowEntries(account)[0]?.type : undefined;
     // pi's own saved default for a pi seam that resolves no model, read once beside the models
     // catalog this collector already takes as a seam (piSettingsPath). The config's `thinking`
     // wins over the default's because tumwater passes it to pi as `--thinking`, mirroring the
@@ -117,28 +126,34 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
     // gate does) keeps them on one answer. OpenCode's `catalog` is threaded the way claude's
     // `account` is: absent, an opencode pair reads NOT free.
     const opencodeCatalog = readOpencodeCache(root);
-    const freeFallback = declaredFallback ? fallbackModelPair(cfg, modelsPath, readClaudeAccount(root), opencodeCatalog) : null;
+    // The claude account answer (6a/7), read the way the budget gate reads it — always, so the
+    // fallback price verdict sees the subscription even when claude is not this role's own seam
+    // (a pi role may still fall back to claude). The lookup returns it only for "claude" (part
+    // 2a/9) — no caller asks for another backend yet.
+    const claudeFallbackAccount = readClaudeAccount(root);
+    const accounts = (b) => (b === "claude" ? claudeFallbackAccount : null);
+    const freeFallback = declaredFallback ? fallbackModelPair(cfg, modelsPath, accounts, opencodeCatalog) : null;
     const fallback = freeFallback ?? declaredFallback;
-    // One state read serves both the model-fallback episode and the next-tick preview below.
-    const state = loadLoopState(root, role);
+    // One state read serves both the model-fallback episode and the next-run preview below.
+    const state = loadRunnerState(root, role);
     const episode = state.modelFallback;
-    // The loop's recent tick outcomes, read from the event log (readEvents) so the command
+    // The role's recent run outcomes, read from the event log (readEvents) so the command
     // answers with the team stopped and never touches live state. readEvents returns the log's
     // newest events in file (chronological) order, so filtering to this role's run_end events
     // and taking the last 8 yields the newest 8, reversed to newest-first. Durations and
     // summaries ride along only when the event carried them (a torn or empty line drops them),
-    // and an empty result is omitted so a never-ticked loop carries no `recentOutcomes` at all.
-    // One event-log read serves both per-loop facts — the recent outcomes and the spend sum — so
+    // and an empty result is omitted so a never-run role carries no `recentOutcomes` at all.
+    // One event-log read serves both per-role facts — the recent outcomes and the spend sum — so
     // the two cannot drift on what they cover: filtered to this role's run_end events once, then
     // the outcome projection keeps the newest valid 8 while the usage fold sums the whole window.
     const events = readEvents(root);
-    const tickEnds = events.filter((ev) => ev.type === "run_end" && eventRole(ev) === role);
+    const runEnds = events.filter((ev) => ev.type === "run_end" && eventRole(ev) === role);
     // The event log is read without a shape filter, so a torn or hand-edited run_end line can
     // carry a non-numeric ts/durationMs or an empty result — the same foreign shape every other
     // consumer guards with finiteNumber. A line with no usable ts or result is as unusable as
-    // an absent one (the same "a torn line carries no usable timestamp" rule eventTick/tickStartMap
+    // an absent one (the same "a torn line carries no usable timestamp" rule eventRun/runStartMap
     // apply), so it contributes no outcome; a non-numeric durationMs is dropped like a missing one.
-    const recentOutcomes = tickEnds
+    const recentOutcomes = runEnds
         .filter((ev) => {
         return finiteNumber(ev.ts, null) !== null && typeof ev.result === "string" && ev.result !== "";
     })
@@ -150,13 +165,13 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
         ...(typeof ev.summary === "string" && ev.summary !== "" ? { summary: ev.summary } : {}),
     }))
         .reverse();
-    // The loop's own spend over the same retained window, summed per-run_end through the shared
+    // The role's own spend over the same retained window, summed per-run_end through the shared
     // eventUsage guard (a torn or hand-edited run_end line contributes nothing: a non-numeric
     // field reads as 0, and a line without a usable ts is as unusable as an absent one, matching
-    // recentOutcomes's drop rule so a torn tick never silently spends). Omitted when all three
-    // sums are 0, keeping a never-costly loop's JSON unchanged (the report's zero-means-absent
+    // recentOutcomes's drop rule so a torn run never silently spends). Omitted when all three
+    // sums are 0, keeping a never-costly role's JSON unchanged (the report's zero-means-absent
     // convention).
-    const usage = tickEnds.reduce((acc, ev) => {
+    const usage = runEnds.reduce((acc, ev) => {
         if (finiteNumber(ev.ts, null) === null)
             return acc;
         const u = eventUsage(ev);
@@ -178,35 +193,44 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
     // byte-identical when there is no override).
     const rawInterval = rawRoleField(root, base, "minRunIntervalSeconds");
     const minRunIntervalOverride = typeof rawInterval === "number" ? rawInterval : undefined;
-    // The raw provider/model/thinking the FILE holds (roles.<base>), distinct from the resolved
-    // provider/model/thinking fields configForRole merges with the top level — the drawer's
-    // Model overrides editor prefills from these, empty when unset. Presence is judged against
-    // the FILE (rawRoleField) like minRunIntervalOverride, so a config that relies on the top
-    // level or a tier name carries no override. Each is spread only when a string, so a file
-    // with no overrides yields a payload byte-identical to today's.
+    // The raw provider/model/thinking/backend the FILE holds (roles.<base>), distinct from
+    // the resolved provider/model/thinking/backend fields configForRole merges with the top
+    // level — the drawer's Model overrides editor prefills from these, empty when unset.
+    // Presence is judged against the FILE (rawRoleField) like minRunIntervalOverride, so a
+    // config that relies on the top level or a tier name carries no override. Each is spread
+    // only when a string, so a file with no overrides yields a payload byte-identical to
+    // today's.
     const providerOverrideRaw = rawRoleField(root, base, "provider");
     const modelOverrideRaw = rawRoleField(root, base, "model");
     const thinkingOverrideRaw = rawRoleField(root, base, "thinking");
+    const backendOverrideRaw = rawRoleField(root, base, "backend");
     const providerOverride = typeof providerOverrideRaw === "string" ? providerOverrideRaw : undefined;
     const modelOverride = typeof modelOverrideRaw === "string" ? modelOverrideRaw : undefined;
     const thinkingOverride = typeof thinkingOverrideRaw === "string" ? thinkingOverrideRaw : undefined;
+    const backendOverride = typeof backendOverrideRaw === "string" ? backendOverrideRaw : undefined;
     const capUsd = cfg.maxDailyCostUsdPerRole?.[base];
     let dailyCap;
     if (role !== DIRECTOR_ROLE && typeof capUsd === "number" && Number.isFinite(capUsd) && capUsd > 0) {
-        const ids = loopIds(cfg).filter((id) => baseRoleOf(id) === base);
+        const ids = runnerIds(cfg).filter((id) => baseRoleOf(id) === base);
         if (!ids.includes(role))
             ids.push(role);
-        const runners = ids.map((id) => ({ role: id, state: id === role ? state : loadLoopState(root, id) }));
+        const runners = ids.map((id) => ({ role: id, state: id === role ? state : loadRunnerState(root, id) }));
         const verdict = roleCapVerdicts(runners, cfg.maxDailyCostUsdPerRole, now.getTime()).get(base);
         if (verdict)
             dailyCap = { capUsd, spentUsd: verdict.spentUsd, over: verdict.over, roleIds: verdict.roleIds };
     }
-    // The role's notebook, read for display. The same degradation as every other read here: a
+    // The role's notes, read for display. The same degradation as every other read here: a
     // missing, empty, or unreadable file is simply "no note yet". The director has none.
+    // Alongside the read, the same path is stat'd once for the note's save instant (mtimeMs),
+    // null when there is no note.
     let note = null;
+    let noteSavedAt = null;
     if (role !== DIRECTOR_ROLE) {
-        const text = readTextOrNull(roleNotesPath(root, role));
+        const notesPath = roleNotesPath(root, role);
+        const text = readTextOrNull(notesPath);
         note = text !== null && text.trim() !== "" ? text : null;
+        if (note !== null)
+            noteSavedAt = statOrNull(notesPath)?.mtimeMs ?? null;
     }
     // The windows the scheduler applies (gates/gate-polls.ts), through the same parser and
     // predicate; the director is exempt from both gates.
@@ -227,7 +251,7 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
         title: resolved.title,
         custom: isCustomRole(cfg, role),
         enabled: enabledRoleIds(cfg).includes(role),
-        paused: loopPaused(new Set(pausedRoles(root)), role),
+        paused: runnerPaused(new Set(pausedRoles(root)), role),
         tier: roleTier(role),
         modelTier: roleSeamTier(cfg, role),
         ...resolvedModelFields(effective.provider, effective.model, effective.thinking),
@@ -245,46 +269,61 @@ export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now =
         fallback,
         fallbackFree: freeFallback !== null,
         modelFallback: modelFallbackView(episode, cfg, role),
-        ...(account !== null ? { billing: account.billing } : {}),
+        ...(account !== null ? { billing: account.billing, billingBackend } : {}),
         ...(billingWindow !== undefined ? { billingWindow } : {}),
         chainStep,
-        ...roleImageInfo(cfg, role, modelsPath, readImageProbeCache(root)),
+        ...roleImageInfo(cfg, role, modelsPath, readImageProbeCache(root), readPiListedModels(root)),
         minRunIntervalSeconds: effective.minRunIntervalSeconds,
         ...(minRunIntervalOverride !== undefined ? { minRunIntervalOverride } : {}),
         ...(providerOverride !== undefined ? { providerOverride } : {}),
         ...(modelOverride !== undefined ? { modelOverride } : {}),
         ...(thinkingOverride !== undefined ? { thinkingOverride } : {}),
+        ...(backendOverride !== undefined ? { backendOverride } : {}),
         // The configured parallel-runner count (roles.<base>.instances), present only when the
         // config sets it — unlike minRunIntervalSeconds no catalog seed fills built-ins' counts,
         // so the merged cfg tells presence exactly. Resolved through the base role like the
         // instructions and min-run-interval override.
         ...(cfg.roles[base]?.instances !== undefined ? { instances: cfg.roles[base].instances } : {}),
+        // Whether the review gate reviews this role's commits after they merge — the role page's
+        // `- Review: after merge` line. Present only while review is enabled and review.afterMerge
+        // lists the role's base id, so a pre-merge-reviewed role or a gate-off config leaves the
+        // payload (and its render) unchanged.
+        ...(cfg.review.enabled && reviewedAfterMerge(cfg, role) ? { reviewedAfterMerge: true } : {}),
+        // Whether the review gate is on at all (review.enabled !== false) — the gate toggle's
+        // presence, distinct from reviewedAfterMerge's membership, so a before-merge-reviewed role
+        // still gets the drawer's Review control while the gate runs.
+        ...(cfg.review.enabled ? { reviewEnabled: true } : {}),
         // The roles.<base>.instructions override verbatim — resolved through the base role like
         // the cap and quiet hours, so an instance id shows (and can edit) the override its runs
-        // carry (tick-prompt reads config.roles[base]); null when unset.
+        // carry (run-prompt reads config.roles[base]); null when unset.
         instructions: cfg.roles[baseRoleOf(role)]?.instructions ?? null,
         find: role === DIRECTOR_ROLE ? null : resolved.find,
         notes: note,
+        noteSavedAt,
+        // The qa observer's flow-coverage ledger (plans/observer-roles.md 2/2) — each flow's last
+        // exercise and result in the prompt block's order (never-exercised first, then
+        // stalest-first). Present only for the canonical qa id, so every other role's --json
+        // payload and Markdown render stay byte-identical. The ledger read degrades to empty
+        // coverage on a missing or torn file exactly as readQaCoverage already does.
+        ...(role === "qa" ? { flowCoverage: coverageRows(readQaCoverage(root), now.getTime()) } : {}),
         inboxCount: queuedRolePromptCount(root, role),
         // The resolved primary seam's declared context window in tokens, or null when it cannot
         // be known (a non-pi seam, an unresolvable provider/model pair, or a model with no
         // declared window) — the same seam `- Next run:` previews. Independent of the fallback.
         contextWindow,
         // The preview seam: the queued prompt (if any) is read, not consumed, so an inspection
-        // never costs the loop its queued work — the property the tick-prompt test pins.
-        nextPrompt: assembleTickPrompt({
+        // never costs the role its queued work — the property the run-prompt test pins.
+        nextPrompt: assembleRunPrompt({
             root,
             config: cfg,
             role,
             state,
             preview: true,
-            // The compact prompt every run gets (loop-tick.ts), so the preview is the real prompt.
-            compact: true,
         })?.prompt ?? null,
-        // The loop's schedule — surfaced read-only from the same persisted state rolePayload
-        // already loaded for the model-fallback episode and the next-tick preview, so no new
-        // read path exists and the collector stays one loadLoopState per role. `lastRunEndedAt`
-        // is omitted (JSON unchanged) until the loop has actually ticked.
+        // The role's schedule — surfaced read-only from the same persisted state rolePayload
+        // already loaded for the model-fallback episode and the next-run preview, so no new
+        // read path exists and the collector stays one loadRunnerState per role. `lastRunEndedAt`
+        // is omitted (JSON unchanged) until the role has actually run.
         nextRunAt: state.nextRunAt,
         backoffSeconds: state.backoffSeconds,
         yieldMultiplier: yieldMultiplierFor(state),

package/dist/src/roles/roles.js

@@ -1,35 +1,34 @@
-// vocabulary: plain
 /** The role registries and classification helpers over the built-in role catalog. The catalog
- * itself — each loop's identity and its "find something to do" prompt text — lives in
+ * itself — each role's identity and its "find something to do" prompt text — lives in
  * role-catalog.ts (split out 2026-10-01, organize); this module re-exports ROLES and Role so
  * every importer keeps the single roles.js import path, and derives from them the scheduling
  * registries (work/maintenance/observer tiers, deferrable and baseline-blocked sets) and the
- * lookup helpers the CLI, GUI, and tick prompt share. */
+ * lookup helpers the CLI, GUI, and run prompt share. */
 import { ROLES } from "./role-catalog.js";
-import { baseRoleOf } from "./loop-ids.js";
+import { baseRoleOf } from "./runner-ids.js";
 import { typoSuffix } from "../text/suggest.js";
 export { ROLES };
-/** The director loop's id — a target that is not in ROLES (allRoleIds appends it) and is
+/** The director role's id — a target that is not in ROLES (allRoleIds appends it) and is
  * driven by operator prompts, not a find prompt: an un-targeted `tumwater prompt` queues
- * there. It keeps running through a team-wide `pause` (which stops only the role loops);
+ * there. It keeps running through a team-wide `pause` (which stops only the roles);
  * an un-targeted `stop` signals the whole orchestrator, director included. */
 export const DIRECTOR_ROLE = "director";
-/** The bugfix loop's id. It is the one work role that also defers like a maintenance role while its
- * backlog (BUGS.md `## Open`) is empty — see deferTick in src/scheduling/scheduling.ts. With open
+/** The bugfix role's id. It is the one work role that also defers like a maintenance role while its
+ * backlog (BUGS.md `## Open`) is empty — see deferRun in src/scheduling/scheduling.ts. With open
  * bugs it never defers, but pollRunnerReasons stands it down while all of them are held. */
 export const BUGFIX_ROLE = "bugfix";
 /** Work-tier roles (need-based prioritization): they
- * ship work — feature and bugfix merge code on main, plan feeds them — so their due ticks are
+ * ship work — feature and bugfix merge code on main, plan feeds them — so their due runs are
  * never deferred and slot allocation always orders them ahead of maintenance. */
 const WORK_ROLES = new Set(["feature", "bugfix", "plan"]);
 /** Observer roles (plans/observer-roles.md 1/2): a role whose product is an observation, not a
  * commit, and for which `no_change` means "checked, all well" rather than "found nothing to do".
- * The idle ladder's premise — a loop that keeps finding nothing stops burning model time — does
- * not hold for these, so their no_change tick schedules at `minRunIntervalSeconds` and leaves
+ * The idle ladder's premise — a role that keeps finding nothing stops burning model time — does
+ * not hold for these, so their no_change run schedules at `minRunIntervalSeconds` and leaves
  * `backoffSeconds` at 0 (src/scheduling/backoff.ts). The error ladder still applies in full, and
  * they are removed from DEFERRABLE_ROLES because their input (the running product for `qa`, the
- * event log for `selfcheck`) is not a function of whether main moved. */
-export const OBSERVER_ROLES = new Set(["qa", "selfcheck"]);
+ * event log for `selfcheck` and `feedback`) is not a function of whether main moved. */
+export const OBSERVER_ROLES = new Set(["qa", "selfcheck", "feedback", "ci"]);
 /** The built-in maintenance roles that author code on their own cadence — the eight members
  * DEFERRABLE_ROLES and BASELINE_BLOCKED_ROLES share. Both sets list them because both charter
  * the same roles (defer-until-needed scheduling, red-main blocking), so the list lives once
@@ -45,8 +44,8 @@ const CODE_MAINTENANCE_ROLES = [
     "improve",
 ];
 /** Maintenance-tier roles (need-based prioritization): exactly the ten built-ins whose due
- * ticks are deferrable while no feature, bugfix, director, operator or human commit has merged
- * into main since their last tick and that tick did nothing. Unknown/custom roles are
+ * runs are deferrable while no feature, bugfix, director, operator or human commit has merged
+ * into main since their last run and that run did nothing. Unknown/custom roles are
  * deliberately NOT in this
  * set — the harness cannot judge what an arbitrary custom role needs, so they never defer (they
  * still sort into tier 1 for fairOrder via roleTier). Observers are excluded: an unmoved tree
@@ -56,12 +55,12 @@ export const DEFERRABLE_ROLES = new Set([
     ...CODE_MAINTENANCE_ROLES,
     "steward",
 ]);
-/** Does this role's recent yield scale its min-tick gap (yield-scaled clocks, PLANS.md)?
+/** Does this role's recent yield scale its min-run gap (yield-scaled clocks, PLANS.md)?
  * The search/maintenance roles — the deferrable ten, the observers, and bugfix on its
  * empty-backlog search duty (it is the one work role that defers like maintenance, so its
- * idle clock stretches like one too; the open-bugs state is deferTick's concern, not the
- * clock's: ten consecutive empty ticks are empty-yield evidence however many bugs are
- * recorded). Never the work roles whose ticks follow demand — feature, plan, director — a
+ * idle clock stretches like one too; the open-bugs state is deferRun's concern, not the
+ * clock's: ten consecutive empty runs are empty-yield evidence however many bugs are
+ * recorded). Never the work roles whose runs follow demand — feature, plan, director — a
  * role with a queued prompt or a fresh wake bypasses the gap entirely (isEligible), and the
  * multiplier is computed from counted results only (backoff.ts), so feature's errors
  * and quiet kills never stretch anything. */
@@ -76,24 +75,25 @@ export function roleTier(role) {
     return WORK_ROLES.has(baseRoleOf(role)) ? 0 : 1;
 }
 /** The roles blocked from starting an authoring run while main's own build/test suite is known
- * red (the red-main baseline check): every role whose diff
+ * red with no failing test named (the red-main baseline check; a red that names its failing tests
+ * blocks nothing, and these roles get a `<main-known-red>` note instead): every role whose diff
  * can carry non-exempt (code) changes — on a red main such a diff is rejected deterministically
  * by the gate's pre-check, so spending an authoring run on it is pure waste. Exempt: director
- * (human prompts outrank autonomous gates, like the budget gate), bugfix (the designated healer
- * — its tick runs the suite per "leave the project working" and can fix a red main through the
- * existing pre-merge gate; blocking it would leave only humans able to unblock the team), and
- * plan/readme/steward/qa/selfcheck (markdown-only charter — their diffs are exempt from the build
- * pre-check via review.exemptPaths, so a red main does not block them). */
+ * (human prompts outrank autonomous gates, like the budget gate), ci (the designated healer
+ * — its run executes the suite per "leave the project working" and can fix a red main through the
+ * existing pre-merge gate; blocking it would leave only the ci role able to unblock the team), and
+ * plan/readme/steward/qa/selfcheck/feedback (markdown-only charter — their diffs are exempt
+ * from the build pre-check via review.exemptPaths, so a red main does not block them). */
 export const BASELINE_BLOCKED_ROLES = new Set([
     "feature",
     ...CODE_MAINTENANCE_ROLES,
 ]);
-/** Is this loop id blocked from authoring on a red main? True when its base role is in
+/** Is this role id blocked from authoring on a red main? True when its base role is in
  * BASELINE_BLOCKED_ROLES, so `feature-2` is blocked exactly as `feature` is. */
 export function baselineBlocked(role) {
     return BASELINE_BLOCKED_ROLES.has(baseRoleOf(role));
 }
-/** Work ratio 4/4: which commit tier a loop's base role merges into, for the work vs maintenance
+/** Work ratio 4/4: which commit tier a role's base role merges into, for the work vs maintenance
  * split the report and the "Merged today" tile show and the maintenance allowance (Work ratio
  * 1a/4, src/gates/maintenance-quota.ts) counts. The one home of the split. `work` is the
  * shipping tier (feature, bugfix, director); `maintenance` is code upkeep plus readme. Every
@@ -121,17 +121,17 @@ export function roleById(id) {
  * a did-you-mean suggestion when the typed id sits within edit distance 2 of a valid one —
  * the same treatment unknownConfigKeyError gives config keys, so a mistyped `--role feautre`
  * names its fix instead of only the valid list. parseRoleFlag, the operator commands, and
- * tick-prompt's defensive runner path share it so the wording cannot drift between the CLI,
- * the GUI, and a tick's internal error. The hint is text/suggest.ts's typoSuffix —
+ * run-prompt's defensive runner path share it so the wording cannot drift between the CLI,
+ * the GUI, and a run's internal error. The hint is text/suggest.ts's typoSuffix —
  * suggestClosest plus didYouMean composed once, the pairing every other unknown-X error
  * renders through. */
 export function unknownRoleMessage(role, validIds) {
     return `unknown role: ${role} (valid ids: ${validIds.join(", ")})${typoSuffix(role, validIds)}`;
 }
-/** A user-defined loop as a Role (plans/user-defined-loops.md): its task IS the
- * role-specific find-something-to-do text, and the title is what identifies the loop inside
- * its own prompt (`You are the "<name>" loop (user-defined loop)`) and commit context.
- * Custom loops run the `default` tier — the harness cannot judge what an arbitrary loop's
+/** A user-defined role as a Role (plans/user-defined-loops.md): its task IS the
+ * role-specific find-something-to-do text, and the title is what identifies the role inside
+ * its own prompt (`You are the "<name>" role (user-defined role)`) and commit context.
+ * Custom roles run the `default` tier — the harness cannot judge what an arbitrary role's
  * work needs, so it gets the team's ordinary model. */
 export function customRole(name, task) {
     return { id: name, title: "custom role", find: task, tier: "default" };

package/dist/src/roles/runner-ids.js

@@ -0,0 +1,97 @@
+/** Runner-id arithmetic for parallel work instances (plans/parallel-work-instances.md, part 1/7). A
+ * base role may run several runner ids — `feature`, `feature-2`, `bugfix-3`, … — each keying
+ * its own persisted state, branch, refs, session and notes, while every lookup that is ABOUT the
+ * role (its catalog charter, model, tier, caps, scheduling class) resolves through the base role.
+ * With no instances configured, every runner id is bare, so `baseRoleOf` is the identity.
+ *
+ * Only `feature` and `bugfix` may gain instances; any other id is returned unchanged, including a
+ * custom role whose name merely resembles an instance. */
+/** The base roles that may run more than one instance. */
+export const INSTANCE_ROLES = new Set(["feature", "bugfix"]);
+/** How many runner ids an instance role may hold per configured instance. `instances: N` limits the
+ * runs writing code at once; a runner whose change waits in the merge pipeline never runs
+ * (plans/merge-queue.md invariant 3), so tumwater keeps up to N × this many runner ids and the
+ * poll admits another while fewer than N are running (plans/fast-merge.md "Lever 1"). */
+const RUNNERS_PER_INSTANCE = 2;
+/** The instance-id shape: a base role, a dash, and an index of 2 or more (`-1` is not an
+ * instance — the bare id already means instance 1). The source string is also interpolated into
+ * the dashboard script (gui-client-labels.ts). */
+export const INSTANCE_ID_SOURCE = "^(feature|bugfix)-([2-9]|[1-9][0-9]+)$";
+const INSTANCE_RE = new RegExp(INSTANCE_ID_SOURCE);
+/** The base role a runner id belongs to: `feature-2` → `feature`, `bugfix-10` → `bugfix`; any
+ * other id — a bare role, a custom role, `feature-1` — is returned unchanged. */
+export function baseRoleOf(id) {
+    const m = INSTANCE_RE.exec(id);
+    return m ? m[1] : id;
+}
+/** The 1-based instance number of a runner id: 1 for a bare role or any non-instance id, N for
+ * `<role>-N`. */
+export function instanceIndex(id) {
+    const m = INSTANCE_RE.exec(id);
+    return m ? Number(m[2]) : 1;
+}
+/** Whether a runner id is listed in a role scope, directly or through its base role — a scope
+ * naming `feature` takes `feature-2` too. One home for the instance-aware membership test
+ * shared by `logs --role`'s and the merge queue's filters and status snapshot scoping, so the
+ * three cannot drift on whether a bare role id takes its instances. */
+export function roleInScope(id, scope) {
+    return scope.includes(id) || scope.includes(baseRoleOf(id));
+}
+/** The instance count configured for a runner id's base role (`roles.<base>.instances`, default
+ * 1). A caller tells a multi-instance base (whose unassigned runs stage claims for their
+ * siblings) from a single-runner one by this. */
+export function configuredInstances(config, id) {
+    const role = config.roles[baseRoleOf(id)];
+    return role?.instances ?? 1;
+}
+/** How many runner ids a base role holds: its configured instance count, times
+ * RUNNERS_PER_INSTANCE once it runs more than one instance. A role left at one instance keeps its
+ * single bare runner, so its scheduling is exactly the single-runner one. */
+function runnerCount(config, base) {
+    const count = config.roles[base]?.instances ?? 1;
+    return INSTANCE_ROLES.has(base) && count > 1 ? count * RUNNERS_PER_INSTANCE : count;
+}
+/** Is this runner id enabled? True when its base role is enabled in config and the id's instance
+ * index is within the role's runner count (runnerCount). */
+export function runnerEnabled(config, id) {
+    const role = config.roles[baseRoleOf(id)];
+    if (role?.enabled !== true)
+        return false;
+    return instanceIndex(id) <= runnerCount(config, baseRoleOf(id));
+}
+/** Every runner id the config says should exist, in `config.roles` order: each enabled role's
+ * bare id, then `<id>-2`…`<id>-M` for the `INSTANCE_ROLES` at their runner count
+ * (runnerCount: twice the configured instances once there is more than one). Other roles and
+ * custom roles stay bare — only feature and bugfix may split. The one
+ * answer to "which runners should exist", so the orchestrator (part 5b/7) and live reload
+ * enumerate the same set. At the default instance count this returns exactly the bare ids
+ * `enabledRoleIds` returns. */
+export function runnerIds(config) {
+    const ids = [];
+    for (const [id, role] of Object.entries(config.roles)) {
+        if (!role.enabled)
+            continue;
+        ids.push(id);
+        if (!INSTANCE_ROLES.has(id))
+            continue;
+        const count = runnerCount(config, id);
+        for (let i = 2; i <= count; i++)
+            ids.push(`${id}-${i}`);
+    }
+    return ids;
+}
+/** The pause-marker key for a runner id. Instance 1's runner id is the bare role id, which as a
+ * pause key would mean the whole role, so while the role runs several instances instance 1 pauses
+ * under `<role>-1`. `-1` is a pause key only, never a runner id. Every other id is its own key. */
+export function instancePauseKey(config, runnerId) {
+    return INSTANCE_ROLES.has(runnerId) && configuredInstances(config, runnerId) > 1
+        ? `${runnerId}-1`
+        : runnerId;
+}
+/** Does the per-role pause marker stop this runner id? True for its own id, its base role's id (a
+ * whole-role pause), or — for the bare id of an instance role — the `<role>-1` pause key. */
+export function runnerPaused(paused, runnerId) {
+    return (paused.has(runnerId) ||
+        paused.has(baseRoleOf(runnerId)) ||
+        (INSTANCE_ROLES.has(runnerId) && paused.has(`${runnerId}-1`)));
+}