tumwater 0.2.0 → 0.4.0

package/dist/src/config/config.js

@@ -1,7 +1,6 @@
-// vocabulary: plain
 import fs from "node:fs";
 import { allRoleIds } from "../roles/roles.js";
-import { loopIds } from "../roles/loop-ids.js";
+import { runnerIds } from "../roles/runner-ids.js";
 import { cachedByStat } from "../files/stat-cache.js";
 import { CONFIG_BASENAME, configPath } from "../paths.js";
 import { errorMessage } from "../text/text.js";
@@ -31,7 +30,7 @@ export function parseJsonConfig(file, basename) {
     return { raw, renamed };
 }
 /** Build the default TumwaterConfig: every role enabled except the opt-in selfcheck (steward on its
- * slow ~6 h tick, qa and selfcheck on ~2 h, readme on 30 min, plan and organize on 1 h), with
+ * slow ~6 h run, qa and selfcheck on ~2 h, readme on 30 min, plan and organize on 1 h), with
  * defaults for concurrency, timeouts, log size, retention, thrash detection, idle backoff,
  * self-redeploy, and review settings. The return type is the resolved view (config-views.ts): a
  * freshly defaulted config has no model map to resolve — only a loaded file can carry one — so
@@ -47,18 +46,26 @@ export function defaultConfig() {
     roles.steward = { enabled: true, minRunIntervalSeconds: 21600 };
     // QA exercises the product like a user on a ~2 h clock: user flows change slower than code.
     roles.qa = { enabled: true, minRunIntervalSeconds: 7200 };
-    // Selfcheck reads the event log on the same slow clock: the digest is a windowed view, so a
-    // tick a couple of hours apart reads a new window rather than re-filing the same cluster.
-    // It is the one opt-in role: its evidence is this harness's own event log and its charter
-    // files only harness misbehavior, so on any other project every finding is a tumwater bug
-    // filed into the wrong backlog, which that project's bugfix loop rightly rejects. Tumwater's
-    // own tumwater.example.json enables it, so this repo's checkouts still get it at `init`.
+    // CI verifies main's parity with the workflow on the same ~2 h clock: a full suite plus e2e
+    // is minutes of work, so it must be at most an hourly-ish cost, and the parity block makes
+    // the no-op a single model run when main has not moved (part 3/3).
+    roles.ci = { enabled: true, minRunIntervalSeconds: 7200 };
+    // Selfcheck and feedback are the two opt-in roles, both on the same ~2 h clock: the digest is
+    // a windowed view, so a run a couple of hours apart reads a new window rather than re-filing
+    // the same cluster. Selfcheck's evidence is this harness's own event log and its charter files
+    // only harness misbehavior, so on any other project every finding is a tumwater bug filed into
+    // the wrong backlog, which that project's bugfix role rightly rejects — that is why it is
+    // opt-in. Feedback files the same digest's findings as GitHub issues on znation/tumwater, so
+    // nothing leaves the machine until the operator opts in (plans/feedback-role.md). Tumwater's
+    // own tumwater.example.json keeps selfcheck (dogfood) and not feedback, so this repo's
+    // checkouts still get their findings at `init` and file nothing upstream.
     roles.selfcheck = { enabled: false, minRunIntervalSeconds: 7200 };
+    roles.feedback = { enabled: false, minRunIntervalSeconds: 7200 };
     // The bookkeeping roles run on slower clocks too. In dogfood readme (95 commits, 82 of them
     // status syncs) and plan (80, 44 of them refine/re-audit notes) were 30% of every commit and
-    // 20% of every tick: readme woke on every merge to restamp one line, and plan re-audited plans
+    // 20% of every run: readme woke on every merge to restamp one line, and plan re-audited plans
     // nobody had touched. A 30 min readme clock batches a burst of merges into one sync; a 1 h
-    // plan clock leaves the slots to the loops that ship. Both still wake early when main moves —
+    // plan clock leaves the slots to the roles that ship. Both still wake early when main moves —
     // the clock only bounds how often.
     roles.readme = { enabled: true, minRunIntervalSeconds: 1800 };
     roles.plan = { enabled: true, minRunIntervalSeconds: 3600 };
@@ -74,7 +81,7 @@ export function defaultConfig() {
         piArgs: [],
         // Agent backends (plans/agent-backends.md, part 4a/7): empty until a file names one.
         // Keeping the map always present means read sites need no `?? {}`; the legacy
-        // agentBin/piArgs are read as pi's entry through resolvedAgentConfig (config-views.ts).
+        // agentBin/piArgs are read as pi's entry through resolvedBackendConfig (config-views.ts).
         backends: {},
         maxConcurrent: 6,
         // Three is the team's realistic concurrent-role count: a busy queue coalesces the
@@ -84,7 +91,7 @@ export function defaultConfig() {
         // without a burst stacking every check on the host beside the authors' own test runs.
         maxConcurrentChecks: 2,
         minRunIntervalSeconds: 20,
-        // Four hours: the largest tick a hosted model legitimately took and still merged work
+        // Four hours: the largest run a hosted model legitimately took and still merged work
         // measured 185 minutes (BUGS.md 2026-09-29), so 30 minutes discarded real work and burned
         // every resume before the task could finish. A run that stops making progress is still
         // bounded earlier by the quiet watchdog, not by this cap.
@@ -103,12 +110,12 @@ export function defaultConfig() {
         maxDailyCostUsd: 50,
         // Work ratio 1a/4 and 1b/4 (plans/work-ratio.md): the maintenance allowance is
         // maintenancePerWorkMerge × work merges + 12 per rolling 24 h, and the scheduler holds
-        // maintenance loops once the window reaches it. Two keeps roughly two upkeep merges per
+        // maintenance roles once the window reaches it. Two keeps roughly two upkeep merges per
         // shipped change while the fixed floor lets hygiene run on an empty backlog.
         maintenancePerWorkMerge: 2,
         // Disk floor (plans/disk-floor.md, part 1/4): when the volume the worktrees live on drops
         // below this many GB free, the team holds new work until it climbs 5 GB back above it.
-        // 10 GB leaves room for an in-flight tick to finish and a state write to land. 0 disables.
+        // 10 GB leaves room for an in-flight run to finish and a state write to land. 0 disables.
         diskHoldGB: 10,
         // Pressure reclaim (plans/disk-floor.md, part 2/4): below this many GB free, a background
         // pass deletes gitignored build outputs from idle worktrees before the 10 GB hold engages.
@@ -119,9 +126,9 @@ export function defaultConfig() {
         // whatever the free space. A day catches paused, retired and rarely due roles without
         // sweeping a worktree that merely slept through the night. 0 disables idle reclaim.
         worktreeIdleReclaimHours: 24,
-        // Friction is flagged only when a changed tick burns BOTH thresholds
-        // (src/tick/tick-stage.ts): the absolute turn count alone measures model speed, so a fast
-        // model's ordinary 40+ turn / few-minute tick stays unflagged, while a genuinely hard tick
+        // Friction is flagged only when a changed run burns BOTH thresholds
+        // (src/run/run-stage.ts): the absolute turn count alone measures model speed, so a fast
+        // model's ordinary 40+ turn / few-minute run stays unflagged, while a genuinely hard run
         // that burned 40+ turns over half an hour or more still is (BUGS.md 2026-09-19). Tuned for
         // the ~27B local model at 24-35 tok/s, where 40 turns is half an hour of work.
         thrashTurns: 40,
@@ -134,9 +141,17 @@ export function defaultConfig() {
         // writes a request file the harness applies to the live config before any commit, so no
         // diff can ever touch tumwater.json and the exemption — once the only thing keeping an
         // explicit user instruction from being discarded by a rejected review — has nothing left
-        // to exempt. Removing it also closes the path where a director tick could merge a mixed
+        // to exempt. Removing it also closes the path where a director run could merge a mixed
         // doc-plus-config diff unreviewed.
-        review: { enabled: true, exemptPaths: ["*.md", "docs/**"] },
+        // Reviewer as a regular role (part 1/4): the high-volume, low-blast-radius roles — bugfix,
+        // readme, organize, plus clean, dedupe, coverage — are reviewed AFTER they merge, on their
+        // merged commit (src/review/post-merge-review.ts), instead of holding the merge queue for a
+        // reviewer run on their (usually trivial) diff; a rejection keeps the commit on main
+        // with the reviewer's reasons. feature, director, perf, improve and custom roles stay
+        // pre-merge. A
+        // config that omits `review.afterMerge` inherits this, and `"afterMerge": []` opts out (back
+        // to reviewing before merging).
+        review: { enabled: true, exemptPaths: ["*.md", "docs/**"], afterMerge: ["bugfix", "clean", "coverage", "dedupe", "organize", "readme"] },
         customRoles: [],
         roles,
     };
@@ -161,7 +176,7 @@ export function overlayDefaults(base, cfg) {
         review: { ...base.review, ...(cfg.review ?? {}) },
         piArgs: cfg.piArgs ?? base.piArgs,
         // Clone each backend entry (and its args array) so the result owns its data like every
-        // other section. The legacy agentBin/piArgs stay beside it; resolvedAgentConfig picks
+        // other section. The legacy agentBin/piArgs stay beside it; resolvedBackendConfig picks
         // between them.
         backends: Object.fromEntries(Object.entries(cfg.backends ?? base.backends ?? {}).map(([id, a]) => [
             id,
@@ -172,16 +187,16 @@ export function overlayDefaults(base, cfg) {
         customRoles: (cfg.customRoles ?? []).map((c) => ({ ...c })),
         roles: { ...base.roles },
     };
-    // Seed each user-defined loop into roles BEFORE the overlay loop so a file's `roles` section
+    // Seed each user-defined role into roles BEFORE the overlay loop so a file's `roles` section
     // overrides per-key for a custom exactly like for built-ins (enabled, instructions,
-    // tickInterval, provider/model); seeding after would silently ignore those overrides.
+    // runInterval, provider/model); seeding after would silently ignore those overrides.
     // A custom absent from `roles` stays enabled. Insertion order = built-ins then customs in
     // array order — the display and startup tie-break order.
     for (const c of merged.customRoles) {
         // Own-property test, not a bare truthiness read: the custom name `constructor` passes the
         // lowercase charset check and collides with an Object.prototype key, whose inherited value
-        // is truthy — a bare `!merged.roles[c.name]` would skip the seed and the loop would never
-        // become an own key, so loopIds silently dropped it.
+        // is truthy — a bare `!merged.roles[c.name]` would skip the seed and the role would never
+        // become an own key, so runnerIds silently dropped it.
         if (!Object.hasOwn(merged.roles, c.name))
             merged.roles[c.name] = { enabled: true };
     }
@@ -295,7 +310,7 @@ export function liveConfig(root) {
  * dropped from the serialized candidate. A merged config always carries the default `piArgs`,
  * so without this a whole-config write would put both spellings on disk and the next load's
  * raw pass would reject the file; a config that uses only the legacy spellings is unchanged. */
-export function collapseAgentAliases(config) {
+export function collapseBackendAliases(config) {
     const pi = config.backends?.pi;
     if (pi === undefined)
         return config;
@@ -312,11 +327,11 @@ export function collapseAgentAliases(config) {
     return next;
 }
 /** Persist a config after validating it, so an invalid tumwater.json can never be written.
- * Written atomically (writeJsonAtomic, trailing newline — the POSIX-newline convention here
- * and at config-write.ts, the file's other writers): the config-live poller re-reads the file
+ * Written atomically (writeJsonAtomic, trailing newline — the POSIX-newline convention shared
+ * with config-write.ts and config-request.ts): the config-live poller re-reads the file
  * every ~2 s, so a plain overwrite could hand it a torn read mid-write. */
 export function saveConfig(root, config) {
-    const collapsed = collapseAgentAliases(config);
+    const collapsed = collapseBackendAliases(config);
     validateConfig(collapsed);
     writeJsonAtomic(configPath(root), collapsed, true);
 }
@@ -359,36 +374,36 @@ export function changedConfigKeys(prev, next) {
     }
     return keys.sort();
 }
-/** The names of the user-defined loops, in array order (plans/user-defined-loops.md).
+/** The names of the user-defined roles, in array order (plans/user-defined-loops.md).
  * One source of truth for "which ids are user-defined" so consumers cannot drift. */
-export function customLoopNames(config) {
+export function customRoleNames(config) {
     return config.customRoles.map((c) => c.name);
 }
-/** True when `id` is a user-defined loop rather than a catalog role. */
+/** True when `id` is a user-defined role rather than a catalog role. */
 export function isCustomRole(config, id) {
     return config.customRoles.some((c) => c.name === id);
 }
-/** Every valid role id — the catalog plus the user-defined loops (the one answer for "which
+/** Every valid role id — the catalog plus the user-defined roles (the one answer for "which
  * ids exist", so consumers cannot drift from each other). */
 export function knownRoleIds(config) {
-    const ids = [...allRoleIds(), ...customLoopNames(config)];
+    const ids = [...allRoleIds(), ...customRoleNames(config)];
     const seen = new Set(ids);
-    // Parallel work instances (part 5b/7): an enabled role's instance loop ids (`feature-2`) are
+    // Parallel work instances (part 5b/7): an enabled role's instance role ids (`feature-2`) are
     // valid CLI and GUI targets even though they are not catalog roles. The bare ids are already
     // present, so this only appends the extras; deduping keeps the catalog+customs order intact.
-    for (const id of loopIds(config))
+    for (const id of runnerIds(config))
         if (!seen.has(id)) {
             ids.push(id);
             seen.add(id);
         }
     return ids;
 }
-/** Every valid role id a READ-ONLY surface accepts: the catalog plus the user-defined loops,
+/** Every valid role id a READ-ONLY surface accepts: the catalog plus the user-defined roles,
  * read through loadConfigCached (which never throws), so a transiently broken tumwater.json
  * falls back to the built-in catalog instead of taking the view down or refusing every id.
  * The one home of that fallback rule — every read-only role-id consumer resolves through it:
  * parseRoleScope (cmdLogs/cmdHistory), validRoleIds (the GUI endpoints), cmdDiff's role flag,
- * cmdTick's positional, cmdPrompt's --list and list-wide --cancel/--edit scope, and
+ * cmdRunDetail's positional, cmdPrompt's --list and list-wide --cancel/--edit scope, and
  * collectTeamChanges' roster — so they cannot drift. (Read-only deliberately: state-changing
  * commands resolve ids through loadConfig and fail loudly, because the operator is owed the
  * config error before a write.) */

package/dist/src/config/model-selector.js

@@ -1,10 +1,9 @@
-// vocabulary: plain
 /** Parsing model selector strings — `provider/id[:thinking]`, the form pi's own `--model`
  * accepts (plans/model-tiers.md "Selectors"). Tumwater parses them itself because pricing
  * (src/pi/pi-models.ts) needs the provider and id apart, while the argv builder
  * (src/pi/pi-args.ts) still passes `--provider` / `--model` / `--thinking` separately. Pure
  * string algebra — no I/O, no config knowledge beyond THINKING_LEVELS. */
-import { AGENT_IDS, THINKING_LEVELS } from "./config-schema.js";
+import { BACKEND_IDS, THINKING_LEVELS } from "./config-schema.js";
 /** Parse one selector string. Rules:
  * 1. A trailing `:x` is a thinking level only when `x` is in THINKING_LEVELS, so
  *    `…:together` (a provider pin) survives on the id while `…:together:low` strips to
@@ -36,27 +35,25 @@ export function parseModelSelector(s, legacyProvider) {
         })();
     return thinking ? { ...base, thinking } : base;
 }
-/** True when `s` names a registered agent backend — the reserved selector provider namespace
- * (`claude/<id>` always runs on claude). Validation restricts the config's `agent` key to the
- * same ids; a `provider/id` selector's provider is checked here. */
-export function isAgentId(s) {
-    return s !== undefined && AGENT_IDS.includes(s);
+/** True when `s` names a registered agent backend. Validation restricts the config's `backend`
+ * key to these ids; a model id never names one. */
+export function isBackendId(s) {
+    return s !== undefined && BACKEND_IDS.includes(s);
 }
 /** Resolve a seam's backend identity: its own `agent` when it carries one (configForRole,
- * reviewConfig and resolverConfig all do), else `provider` when it names an agent backend (a
- * `claude/<id>` selector runs on claude), else pi — the one backend with providers, the
- * default a selector routes to when neither an agent nor a reserved provider prefix names one.
+ * reviewConfig, resolverConfig and a fallback pair's `backend` all do), else pi — the one
+ * backend with providers.
  * The single home of the rule: the budget gate's claude check, pi's free-ness and
  * context-window lookups, and the image-input seam all read a seam's backend through it, so
  * no two sites can disagree on which backend a selector runs. */
 export function seamAgent(seam) {
-    return seam.agent ?? (isAgentId(seam.provider) ? seam.provider : "pi");
+    return seam.agent ?? "pi";
 }
 /** Each agent backend's per-tier default model, applied only when the config resolves no model
  * id for a seam (plans/agent-backends.md "Config" decision 5). pi has none — its own default
  * applies. It lives here, in the pure config layer, because `routeModel` runs at config-
  * resolution time and must not import the runtime backend registry. */
-const AGENT_DEFAULT_MODELS = {
+const BACKEND_DEFAULT_MODELS = {
     pi: {},
     claude: {
         small: "claude-haiku-5-5",
@@ -67,30 +64,33 @@ const AGENT_DEFAULT_MODELS = {
     // applies, exactly as pi's does. The free model is a time-limited promotion, so its id
     // belongs in tumwater.json, not in code.
     opencode: {},
+    // codex's tier defaults (plans/codex-backend.md decision 4), from the catalog's own
+    // descriptions (design finding 14): strong is `gpt-6-astra`, default is `gpt-6.1-sol` (Codex's
+    // own default), small is `gpt-6-luna`. The director runs the strong tier, as on claude.
+    codex: {
+        small: "gpt-6-luna",
+        default: "gpt-6.1-sol",
+        strong: "gpt-6-astra",
+    },
 };
 /** The backend and concrete model a resolved seam's provider/model pair routes to
- * (plans/agent-backends.md "Config"). The provider segment decides the backend: a provider
- * naming a registered agent id runs that agent (and its provider field is cleared, since it is
- * a namespace, not a pi provider); any other provider runs on pi, the one backend with
- * providers; no provider at all runs on the config's `agent`. When no model id survives the
- * resolution, the backend's tier default fills in (pi supplies none).
- *
- * Rule 3a (plans/provider-concurrency.md "Routing a bare Claude model id to claude"): a bare id
- * (no provider) that starts with `claude-` runs on claude, whatever `configAgent` says — the one
- * prefix where the model id decides the backend. A named provider still wins
- * (`anthropic/claude-…` stays pi); bare aliases (`sonnet`, `opus`) keep today's routing. */
-export function routeModel(provider, model, configAgent, tier) {
-    const agent = provider === undefined
-        ? model?.startsWith("claude-")
-            ? "claude"
-            : configAgent
-        : isAgentId(provider)
-            ? provider
-            : "pi";
-    if (model !== undefined)
-        return { agent, model };
-    const def = AGENT_DEFAULT_MODELS[agent]?.[tier];
-    return def !== undefined ? { agent, model: def } : { agent };
+ * (plans/agent-backends.md "Config"). The backend is the `explicitBackend` (a tier entry's,
+ * role's or review's `backend` key), else the config's `backend`, else pi — a model id never
+ * names one. pi keeps the parsed provider (the caller's); claude and opencode take the whole
+ * `provider/model` id with no provider, verbatim; codex takes the bare model as written (there
+ * is no `codex/<id>` spelling — a model id never names a backend, and a whole `codex/<id>`
+ * parses to provider `codex` which codex, like pi, drops, leaving the model half). When no
+ * model id survives the resolution, the
+ * backend's tier default fills in (pi and opencode supply none). */
+export function routeModel(provider, model, configBackend, tier, explicitBackend) {
+    const backend = explicitBackend ?? configBackend;
+    const whole = model !== undefined && provider !== undefined && backend !== "pi" && backend !== "codex"
+        ? `${provider}/${model}`
+        : model;
+    if (whole !== undefined)
+        return { agent: backend, model: whole };
+    const def = BACKEND_DEFAULT_MODELS[backend]?.[tier];
+    return def !== undefined ? { agent: backend, model: def } : { agent: backend };
 }
 /** The inverse of parseModelSelector (in its no-legacyProvider form): the selector string a
  * triple round-trips through, for messages and future writers. */