tumwater 0.4.2 → 0.4.4

package/dist/src/cli/{config-commands.js → cli-config-commands.js}

@@ -59,16 +59,11 @@ function screenOperableKey(root, key) {
             fail(fieldError);
     }
     else if (parsed.kind === "map") {
-        // Only role-keyed maps check the role catalog. `maxConcurrentPerProvider.<provider>` is
-        // keyed by provider, not a role id, and `config set` writes it without the role check —
-        // so get/unset must agree, or set would succeed while get/unset refused the provider as
-        // an "unknown role". A typo'd role id in the other two maps is refused the same way set's
+        // Role-keyed maps check the role catalog: a typo'd role id is refused the way set's
         // validator treats it.
-        if (parsed.map !== "maxConcurrentPerProvider") {
-            const ids = knownRoleIds(config);
-            if (!ids.includes(parsed.role))
-                fail(unknownRoleMessage(parsed.role, ids));
-        }
+        const ids = knownRoleIds(config);
+        if (!ids.includes(parsed.role))
+            fail(unknownRoleMessage(parsed.role, ids));
     }
     return { parsed, config };
 }
@@ -89,72 +84,74 @@ function resolvedConfigValue(config, parsed, key) {
                         ? record.roles?.[parsed.id]?.[parsed.field]
                         : record[canonicalConfigKey(key)];
 }
-/** The `tumwater config` command body: bare prints the resolved config; `get` and `unset`
- * screen their key through screenOperableKey, while `set` writes through setConfigKey. */
-export async function cmdConfig(root, args = []) {
-    const [sub, key, ...rest] = args;
-    if (sub === "get") {
-        const { parsed, config } = screenOperableKey(root, key ?? "");
-        const value = resolvedConfigValue(config, parsed, key ?? "");
-        sayJsonLine(value === undefined ? null : value); // Absent optional key → JSON null.
-        return;
+/** The `config get` verb: screen the key through screenOperableKey, then print its resolved
+ * value (defaults merged in) as JSON, or JSON null when nothing sets it. */
+async function configGet(root, key) {
+    const { parsed, config } = screenOperableKey(root, key ?? "");
+    const value = resolvedConfigValue(config, parsed, key ?? "");
+    sayJsonLine(value === undefined ? null : value); // Absent optional key → JSON null.
+}
+/** The `config unset` verb: screen the key, remove it, and confirm what, if anything, was
+ * removed (or what the key now resolves to). */
+async function configUnset(root, key) {
+    // cli.ts's arity gate requires exactly two args (`unset <key>`) before cmdConfig runs;
+    // this is the defensive tail for a direct caller, matching the bare-config tail below.
+    if (key === undefined)
+        fail(CONFIG_USAGE);
+    const k = canonicalConfigKey(key);
+    // The same screens get runs first, so a typo'd top-level key, role id, or role field
+    // fails identically — unsetConfigKey's own parse/field checks are the mutation-side
+    // backstop, not the wording the operator sees.
+    const { parsed } = screenOperableKey(root, k);
+    const result = unsetConfigKey(root, k);
+    if (!result.ok)
+        fail(result.error);
+    // The reload only feeds the message, so a failed one leaves `now` undefined.
+    const reloaded = loadConfigSafe(root).config;
+    const now = reloaded === undefined ? undefined : resolvedConfigValue(reloaded, parsed, k);
+    const resolves = now === undefined ? "" : JSON.stringify(now);
+    if (result.oldValue === undefined) {
+        say(`${k} is not set in tumwater.json, so nothing was removed` +
+            (now === undefined ? "" : ` (it resolves to ${resolves})`));
     }
-    if (sub === "unset") {
-        // cli.ts's arity gate requires exactly two args (`unset <key>`) before cmdConfig runs;
-        // this is the defensive tail for a direct caller, matching the bare-config tail below.
-        if (key === undefined)
-            fail(CONFIG_USAGE);
-        const k = canonicalConfigKey(key);
-        // The same screens get runs first, so a typo'd top-level key, role id, or role field
-        // fails identically — unsetConfigKey's own parse/field checks are the mutation-side
-        // backstop, not the wording the operator sees.
-        const { parsed } = screenOperableKey(root, k);
-        const result = unsetConfigKey(root, k);
-        if (!result.ok)
-            fail(result.error);
-        // The reload only feeds the message, so a failed one leaves `now` undefined.
-        const reloaded = loadConfigSafe(root).config;
-        const now = reloaded === undefined ? undefined : resolvedConfigValue(reloaded, parsed, k);
-        const resolves = now === undefined ? "" : JSON.stringify(now);
-        if (result.oldValue === undefined) {
-            say(`${k} is not set in tumwater.json, so nothing was removed` +
-                (now === undefined ? "" : ` (it resolves to ${resolves})`));
-        }
-        else {
-            const was = JSON.stringify(result.oldValue);
-            say(`unset ${k} (was ${was}${now === undefined ? "" : `; now resolves to ${resolves}`})`);
-        }
-        return;
+    else {
+        const was = JSON.stringify(result.oldValue);
+        say(`unset ${k} (was ${was}${now === undefined ? "" : `; now resolves to ${resolves}`})`);
     }
-    if (sub === "set") {
-        // A flag-looking value is a dropped `--` in disguise: `config set model --json` would
-        // otherwise take the literal string "--json" as the value (the JSON-parse fallback
-        // swallows any token) and validateConfig's string keys accept it silently — the same
-        // shape gui/gui-command.ts's --token gate refuses, where the value the next flag holds is never
-        // what the operator meant. Refuse before setConfigKey reads it; a value that really
-        // does begin with `--` has no legitimate shape among the config keys' values
-        // (identifiers, durations, windows, JSON scalars and arrays), so nothing is lost.
-        const raw = rest[0] ?? "";
-        if (raw.startsWith("--"))
-            fail(`config set got the flag-looking value ${JSON.stringify(raw)} instead of a value — is a flag missing its value, or did a token slip into the value's position? (e.g. \`tumwater config set model gpt-5\`)`);
-        const result = setConfigKey(root, key ?? "", raw);
-        if (!result.ok)
-            fail(result.error);
-        if (result.unchanged) {
-            say(`${canonicalConfigKey(key ?? "")} is already ${JSON.stringify(result.value)}, so tumwater.json was not written`);
-            return;
-        }
-        say(`set ${canonicalConfigKey(key ?? "")} to ${JSON.stringify(result.value)}`);
-        const note = result.note;
-        if (note)
-            say(`note: ${note}`);
-        // A bare `roles` set replaces the FILE's section, but the built-in catalog always merges
-        // per entry at load, so the replacement cannot disable a role by omission. Say so here
-        // rather than let the confirmation imply the role is gone.
-        if (key === "roles")
-            say("note: the built-in role catalog still merges per entry — disable a role with `tumwater config set roles.<id>.enabled false`, not by omitting it");
+}
+/** The `config set` verb: write one value through setConfigKey (refusing a flag-looking
+ * value first) and confirm the write or that it was already that value. */
+async function configSet(root, key, rest) {
+    // A flag-looking value is a dropped `--` in disguise: `config set model --json` would
+    // otherwise take the literal string "--json" as the value (the JSON-parse fallback
+    // swallows any token) and validateConfig's string keys accept it silently — the same
+    // shape gui/gui-command.ts's --token gate refuses, where the value the next flag holds is never
+    // what the operator meant. Refuse before setConfigKey reads it; a value that really
+    // does begin with `--` has no legitimate shape among the config keys' values
+    // (identifiers, durations, windows, JSON scalars and arrays), so nothing is lost.
+    const raw = rest[0] ?? "";
+    if (raw.startsWith("--"))
+        fail(`config set got the flag-looking value ${JSON.stringify(raw)} instead of a value — is a flag missing its value, or did a token slip into the value's position? (e.g. \`tumwater config set model gpt-5\`)`);
+    const result = setConfigKey(root, key ?? "", raw);
+    if (!result.ok)
+        fail(result.error);
+    if (result.unchanged) {
+        say(`${canonicalConfigKey(key ?? "")} is already ${JSON.stringify(result.value)}, so tumwater.json was not written`);
         return;
     }
+    say(`set ${canonicalConfigKey(key ?? "")} to ${JSON.stringify(result.value)}`);
+    const note = result.note;
+    if (note)
+        say(`note: ${note}`);
+    // A bare `roles` set replaces the FILE's section, but the built-in catalog always merges
+    // per entry at load, so the replacement cannot disable a role by omission. Say so here
+    // rather than let the confirmation imply the role is gone.
+    if (key === "roles")
+        say("note: the built-in role catalog still merges per entry — disable a role with `tumwater config set roles.<id>.enabled false`, not by omitting it");
+}
+/** The bare-config tail: the whole resolved config as pretty JSON, refusing a surplus
+ * subcommand the arity gate somehow missed. */
+async function configDump(root, sub) {
     // Bare config, or anything else: the whole-config dump is the default, and cli.ts's arity
     // check has already rejected a malformed get/set — this usage line is the defensive tail.
     if (sub !== undefined)
@@ -164,3 +161,17 @@ export async function cmdConfig(root, args = []) {
         fail(error); // validateConfig's message, via the standard fail()
     sayJson(config);
 }
+/** The `tumwater config` command body: bare prints the resolved config; `get` and `unset`
+ * screen their key through screenOperableKey, while `set` writes through setConfigKey. Each
+ * verb's guards and confirmation wording live in one named helper — configGet, configUnset,
+ * configSet, configDump — that this dispatcher delegates to. */
+export async function cmdConfig(root, args = []) {
+    const [sub, key, ...rest] = args;
+    if (sub === "get")
+        return configGet(root, key);
+    if (sub === "unset")
+        return configUnset(root, key);
+    if (sub === "set")
+        return configSet(root, key, rest);
+    return configDump(root, sub);
+}

package/dist/src/cli/cli-doctor-command.js

@@ -0,0 +1,103 @@
+import { rejectUnknownArgs, JSON_FLAG, PROBLEMS_FLAG, KILL_ORPHANS_FLAG, COMMIT_BACKLOG_FLAG, RESYNC_INSTALL_FLAG, DROP_BROKEN_PINS_FLAG, RETIRE_LEFTOVERS_FLAG, } from "./cli-flag-specs.js";
+import { say, sayJsonOrRender } from "./cli-output.js";
+import { parseDoctorChecks, peelPositionals } from "./cli-command-args.js";
+import { loadConfigSafe } from "../config/config.js";
+/** Run one doctor side-effect (`--kill-orphans`, `--commit-backlog`, `--resync-install`,
+ * `--drop-broken-pins`, `--retire-leftovers`) and return its report payload for the optional
+ * `--json` run — the shape every doctor*Case side-effect wrapper follows: import the effect's
+ * module and run it only when its flag is present, then (text form only) print the effect's
+ * own lines before the report with a separating blank line when there is anything to print;
+ * `--json` keeps stdout one document, carrying the result on the payload instead. The lazy
+ * per-effect `load` keeps each module imported only when its flag is asked for. */
+async function doctorSideEffect(args, flag, load) {
+    if (!args.includes(flag))
+        return undefined;
+    const { run, lines } = await load();
+    const payload = await run();
+    // The text form prints the effect before the report; --json keeps stdout one document.
+    if (!args.includes("--json")) {
+        const out = lines(payload);
+        for (const line of out)
+            say(line);
+        if (out.length > 0)
+            say("");
+    }
+    return payload;
+}
+async function doctorKillOrphans(root, args) {
+    return doctorSideEffect(args, "--kill-orphans", async () => {
+        const { killOrphans, orphanKillLines } = await import("../doctor/doctor-orphans.js");
+        return { run: () => killOrphans(root), lines: orphanKillLines };
+    });
+}
+async function doctorCommitBacklog(root, args) {
+    return doctorSideEffect(args, "--commit-backlog", async () => {
+        const { commitUncommittedBacklog, backlogCommitLines } = await import("../doctor/doctor-backlog.js");
+        const { config } = loadConfigSafe(root); // the report's own config, so base resolution and the off-base skip match the `uncommitted backlog` row's
+        return { run: () => commitUncommittedBacklog(root, config), lines: backlogCommitLines };
+    });
+}
+async function doctorResyncInstall(root, args) {
+    return doctorSideEffect(args, "--resync-install", async () => {
+        const { resyncRootInstall, rootInstallResyncLines } = await import("../build/dep-install.js");
+        return { run: () => resyncRootInstall(root), lines: rootInstallResyncLines };
+    });
+}
+async function doctorDropBrokenPins(root, args) {
+    return doctorSideEffect(args, "--drop-broken-pins", async () => {
+        const { dropBrokenPins, brokenPinDropLines } = await import("../doctor/doctor-contention-checks.js");
+        return { run: () => dropBrokenPins(root), lines: brokenPinDropLines };
+    });
+}
+async function doctorRetireLeftovers(root, args) {
+    return doctorSideEffect(args, "--retire-leftovers", async () => {
+        const { retireLeftovers, leftoverRetireLines } = await import("../doctor/doctor-contention-checks.js");
+        const { config } = loadConfigSafe(root); // the row's own config, so the reap and the report agree on what is retirable
+        return { run: () => retireLeftovers(root, config), lines: leftoverRetireLines };
+    });
+}
+function doctorPayload(payload, parts) {
+    const out = { ...payload };
+    if (parts.leftoverRetire !== undefined)
+        out.leftoverRetire = parts.leftoverRetire;
+    if (parts.brokenPinDrop !== undefined)
+        out.brokenPinDrop = parts.brokenPinDrop;
+    if (parts.resyncInstall !== undefined)
+        out.resyncInstall = parts.resyncInstall;
+    if (parts.backlogCommit !== undefined)
+        out.backlogCommit = parts.backlogCommit;
+    if (parts.orphanKill !== undefined)
+        out.orphanKill = parts.orphanKill;
+    return out;
+}
+/** `tumwater doctor`: report what in the environment is keeping the team from running, and
+ * run the optional repair side-effects. No ready-repo gate: doctor's job is to report WHY the
+ * environment isn't ready, so it must run outside a git repo and print fail lines rather than
+ * throwing. */
+export async function cmdDoctor(root, args) {
+    const { positionals: checkNames, rest: doctorFlags } = peelPositionals(args);
+    rejectUnknownArgs("doctor", doctorFlags, [JSON_FLAG, PROBLEMS_FLAG, KILL_ORPHANS_FLAG, COMMIT_BACKLOG_FLAG, RESYNC_INSTALL_FLAG, DROP_BROKEN_PINS_FLAG, RETIRE_LEFTOVERS_FLAG]);
+    const only = parseDoctorChecks(checkNames);
+    const { runDoctor } = await import("../doctor/doctor.js");
+    const parts = {
+        orphanKill: await doctorKillOrphans(root, args),
+        backlogCommit: await doctorCommitBacklog(root, args),
+        resyncInstall: await doctorResyncInstall(root, args),
+        brokenPinDrop: await doctorDropBrokenPins(root, args),
+        leftoverRetire: await doctorRetireLeftovers(root, args),
+    };
+    const { renderDoctor, renderDoctorProblems, problemsOnly } = await import("../doctor/doctor-render.js");
+    const report = await runDoctor(root, undefined, undefined, only);
+    // --json prints the collector's own payload (the DoctorReport object), not a re-parse of
+    // the render — the `report --json` precedent. The exit-code contract below holds in both
+    // forms: 1 when any check fails, 0 otherwise; warnings never fail the exit.
+    // --problems keeps the full report for the render (it counts the hidden ok rows) and
+    // hands --json the filtered one; the exit code below reads the full report either way.
+    // --kill-orphans adds the kill result to the JSON object as `orphanKill`.
+    if (args.includes("--problems"))
+        sayJsonOrRender(args, args.includes("--json") ? doctorPayload(problemsOnly(report), parts) : report, renderDoctorProblems);
+    else
+        sayJsonOrRender(args, args.includes("--json") ? doctorPayload(report, parts) : report, renderDoctor);
+    if (report.checks.some((c) => c.level === "fail"))
+        process.exitCode = 1; // Warnings never fail the exit.
+}

package/dist/src/cli/cli-flag-specs.js

@@ -465,35 +465,55 @@ export const GUI_FLAG_SPECS = [PORT_FLAG, ALL_INTERFACES_FLAG, TOKEN_FLAG];
 export function rejectUnknownArgs(command, args, specs) {
     if (args.length === 0)
         return;
-    const claim = new Map();
-    for (const spec of specs)
-        for (const name of spec.names)
-            claim.set(name, spec);
+    const claim = flagClaims(specs);
     const seen = new Set();
     const consumed = new Array(args.length).fill(false);
     for (let i = 0; i < args.length; i++) {
         if (consumed[i])
             continue;
         const arg = args[i] ?? ""; // Unreachable fallback: the loop bound guarantees a token here.
-        const spec = claim.get(arg);
-        if (spec === undefined) {
-            // An equals-form token names a real flag; refuse it with its own message before the
-            // generic "unknown argument" misreports `--role=feature` as a misspelling.
-            rejectEqualsForm(arg, specs);
-            if (specs.length === 0)
-                fail(`tumwater ${command} takes no arguments${gotSuffix(arg)}`);
-            failUnknownArgument(command, arg, specs);
-        }
+        const spec = claim.get(arg) ?? rejectUnknownFlag(command, arg, specs);
         rejectRepeatFlag(seen.has(spec), spec.names[0]);
         seen.add(spec);
-        if (spec.value && i === args.length - 1)
-            fail(spec.missingValue ?? `${spec.names[0]} needs a value`);
-        // The value exists (the trailing-no-value case failed above): name a malformed one now,
-        // before the ready-repo gate or any environment check can mask it.
-        if (spec.value)
-            spec.validate?.(args[i + 1] ?? "");
-        const n = spec.value ? 2 : 1;
-        for (let j = 0; j < n && i + j < args.length; j++)
-            consumed[i + j] = true;
+        consumeFlagOccurrence(spec, args, i, consumed);
     }
 }
+/** The spelling-to-spec claim map rejectUnknownArgs keyed its loop on: every accepted flag
+ * spelling maps to the spec declaring it, alias spellings (-f and --follow) sharing one spec
+ * entry. Built once up front so a token look-up is a map get, not a scan. */
+function flagClaims(specs) {
+    const claim = new Map();
+    for (const spec of specs)
+        for (const name of spec.names)
+            claim.set(name, spec);
+    return claim;
+}
+/** The one refusal for a token naming no known flag: an equals-form token first reroutes
+ * through rejectEqualsForm, which names a REAL flag's offending `--flag=value` spelling
+ * before the generic "unknown argument" misreports `--role=feature` as a misspelling; then
+ * a command with no flags at all fails with the takes-no-arguments wording; otherwise the
+ * shared unknown-argument wording (with its did-you-mean hint) fires. Returns never, so the
+ * caller's `claim.get(arg) ?? rejectUnknownFlag(...)` narrows `spec` to a known FlagSpec. */
+function rejectUnknownFlag(command, arg, specs) {
+    // An equals-form token names a real flag; refuse it with its own message before the
+    // generic "unknown argument" misreports `--role=feature` as a misspelling.
+    rejectEqualsForm(arg, specs);
+    if (specs.length === 0)
+        fail(`tumwater ${command} takes no arguments${gotSuffix(arg)}`);
+    failUnknownArgument(command, arg, specs);
+}
+/** Consume one recognised flag occurrence: fail a valued flag left without its value, name a
+ * malformed value via the spec's validate call, and mark the one or two tokens (the flag and,
+ * for a valued flag, its value) as consumed so a later loop iteration skips them. The value
+ * is marked only after the value checks pass, so a failed value is never silently swallowed. */
+function consumeFlagOccurrence(spec, args, i, consumed) {
+    if (spec.value && i === args.length - 1)
+        fail(spec.missingValue ?? `${spec.names[0]} needs a value`);
+    // The value exists (the trailing-no-value case failed above): name a malformed one now,
+    // before the ready-repo gate or any environment check can mask it.
+    if (spec.value)
+        spec.validate?.(args[i + 1] ?? "");
+    const n = spec.value ? 2 : 1;
+    for (let j = 0; j < n && i + j < args.length; j++)
+        consumed[i + j] = true;
+}

package/dist/src/cli/cli-init.js

@@ -1,7 +1,7 @@
 /** `tumwater init`'s implementation (src/init/init.ts does the work; this prints the report).
  * Split out of cli/cli-start.ts, whose name is for start alone: every command it dispatches
- * delegates to its own module (operator/operator-commands.ts, config-commands.ts, log-commands.ts,
- * doctor.ts, …), and init is no exception. cli.ts stays the pure dispatcher. */
+ * delegates to its own module (cli-config-commands.ts, cli-log-commands.ts, doctor.ts, …), and init
+ * is no exception. cli.ts stays the pure dispatcher. */
 import { say } from "./cli-output.js";
 import { parseInitArgs } from "./cli-command-args.js";
 import { initProject } from "../init/init.js";
@@ -12,8 +12,7 @@ import { templateCatalog } from "../init/init-templates.js";
 export async function cmdInit(root, args) {
     const { prompt, branch, template, listTemplates, adopt, dryRun } = parseInitArgs(args);
     if (listTemplates) {
-        for (const { id, description } of templateCatalog())
-            say(`${id} — ${description}`);
+        printTemplateCatalog();
         return;
     }
     const result = await initProject(root, prompt, branch ?? undefined, {
@@ -21,21 +20,44 @@ export async function cmdInit(root, args) {
         dryRun,
         template: template ?? undefined,
     });
+    printInitIntro(result);
+    if (result.dryRun) {
+        printDryRun(result);
+        return;
+    }
+    printInitReport(result);
+}
+/** Print the `tumwater init --list-templates` catalog: one line per template. */
+function printTemplateCatalog() {
+    for (const { id, description } of templateCatalog())
+        say(`${id} — ${description}`);
+}
+/** Print the `template:`/adopt intro lines shared by the dry-run and completed paths. */
+function printInitIntro(result) {
     if (result.template !== "blank")
         say(`template: ${result.template}`);
     if (result.adopted) {
         say(`${result.dryRun ? "would adopt" : "adopting"} an existing repo: the project brief goes in TUMWATER.md and README.md is left untouched`);
     }
-    if (result.dryRun) {
-        if (result.repoInitialized && result.branch) {
-            say(`dry run — would initialize a new git repository on branch ${result.branch}`);
-        }
-        const list = (names) => (names.length > 0 ? names.join(", ") : "nothing");
-        say(`dry run — would create: ${list(result.created)}`);
-        say(`would leave alone: ${list(result.leftAlone)}`);
-        say("nothing written; re-run without --dry-run to apply");
-        return;
+}
+/** Print the dry-run preview: repo line, the would-create/would-leave-alone lists, and the
+ * "nothing written" line. */
+function printDryRun(result) {
+    if (result.repoInitialized && result.branch) {
+        say(`dry run — would initialize a new git repository on branch ${result.branch}`);
     }
+    const list = (names) => (names.length > 0 ? names.join(", ") : "nothing");
+    say(`dry run — would create: ${list(result.created)}`);
+    say(`would leave alone: ${list(result.leftAlone)}`);
+    say("nothing written; re-run without --dry-run to apply");
+}
+/** Format the created-files line, appending `(committed)` when the repo was seeded. */
+function createdLine(result) {
+    return `created ${result.created.join(", ")}${result.committed ? " (committed)" : ""}`;
+}
+/** Print the completed-init report: the already-initialized no-op, the repo line, the
+ * created-files line, the bootstrap note, and the "next:" line. */
+function printInitReport(result) {
     if (result.created.length === 0) {
         say("already initialized; nothing to do");
         return;
@@ -43,7 +65,7 @@ export async function cmdInit(root, args) {
     if (result.repoInitialized && result.branch) {
         say(`initialized a new git repository on branch ${result.branch}`);
     }
-    say(`created ${result.created.join(", ")}${result.committed ? " (committed)" : ""}`);
+    say(createdLine(result));
     if (result.bootstrap !== null) {
         say(`fresh project — maintenance roles wait until ${result.bootstrap} plans are done; remove "bootstrap" from tumwater.json to end that early`);
     }

package/dist/src/cli/{log-commands.js → cli-log-commands.js}

@@ -103,6 +103,11 @@ export function followUntilParentGone(file, offset, onLines, seams) {
         });
     });
 }
+/** The `-n` ceiling for the event-log dump (`tumwater logs -n <count>`): a terminal tail has
+ * no use for more than this many scanned events, and bounding it keeps an accidental
+ * `-n 999999999` from traversing the whole event file. Sister counts are bounded the same way
+ * (history's HISTORY_MAX_RUNS, report's REPORT_MAX_DAYS); the GUI clamps its logs counts too. */
+const LOGS_MAX_EVENTS = 100_000;
 /** `tumwater logs [-f] [-n <count>] [--since <duration>] [--until <duration>]
  * [--role <id>[,<id>...]] [--transcript <id>] [--prompt]
  * [--grep <text>]`: follow or dump the harness event log, with `--since` a bounded
@@ -126,7 +131,7 @@ export async function cmdLogs(root, args, seams = {}) {
         return;
     }
     const nRaw = flagValue(feed.rest, "-n");
-    const limit = nRaw !== null ? parseCountFlag("-n", nRaw) : 50;
+    const limit = nRaw !== null ? parseCountFlag("-n", nRaw, LOGS_MAX_EVENTS) : 50;
     // The event feed (no --transcript) never needs the config at all: parseRoleScope reads it only
     // when the flag is present.
     const role = parseRoleScope(root, feed.rest, "--transcript", LOGS_TRANSCRIPT_VALUE_ERROR);
@@ -278,39 +283,54 @@ function sayLogsWindowNoMatch(feed, windowPhrase) {
     else
         say(feed.roles !== null ? `${feed.roleEmpty} ${windowPhrase}` : `no events ${windowPhrase}`);
 }
-/** The `-n` tail view and its follow: `readEventsTailWithEnd`, the `shown` filter, the
- * `--count` branch and its empty-match prose, the per-event print, the `!follow` return, and
- * `followUntilParentGone` seeded from `tail.coveredEnd`. It owns the follow-loop locals. */
+/** The `-n` tail view and its `-f` follow: read the filtered tail, print the `--count`
+ * tally or the per-event rows, and seed the follow; each job lives in a named helper. */
 async function sayLogsTail(root, feed, limit, seams) {
-    // -n bounds the scan, not the print: the matched subset of the last `limit` events is what
-    // appears, so `-n 200 --grep merge_failed` may print 3 rows from 200 scanned. The read is
-    // the tail-with-end shape (not the per-poll cached readEvents) so the follow below can seed
-    // from the byte end this very read covered instead of a later stat of the file.
-    const tail = readEventsTailWithEnd(root, limit);
-    const shown = feed.grepLower !== null || feed.type !== null || feed.roles !== null || feed.notable ? tail.events.filter(feed.filter) : tail.events;
-    // `--count` over the -n view answers with the tally of exactly the filtered rows the plain
-    // view would print, and carries over the plain view's empty-match prose below (a `--type`
-    // or `--grep` that matches nothing names its value; an empty unfiltered -n view prints
-    // nothing, as the plain view does). In JSON mode the empty output is the answer.
+    const { shown, coveredEnd } = readTailShown(root, feed, limit);
     if (feed.count) {
+        // `--count` over the -n view answers with the tally of exactly the filtered rows the plain
+        // view would print, and carries over the plain view's empty-match prose (a `--type` or
+        // `--grep` that matches nothing names its value; an empty unfiltered -n view prints
+        // nothing, as the plain view does). In JSON mode the empty output is the answer.
         if (shown.length !== 0)
             sayTally(shown, feed.json);
-        else if (!feed.json && (feed.filtersGrepOrType || feed.roles !== null || feed.notable))
-            sayLogsTailNoMatch(feed);
+        else
+            sayTailEmptyNote(shown, feed);
         return;
     }
     for (const e of shown)
         sayEventLine(e, feed.json);
     if (!feed.follow) {
-        // The empty-match line is prose: in JSON mode the empty output is the answer. It fires
-        // for either filter, naming the flag's value(s) whose match came up empty so the operator
-        // knows what to loosen.
-        if (shown.length === 0 && !feed.json && (feed.filtersGrepOrType || feed.roles !== null || feed.notable))
-            sayLogsTailNoMatch(feed);
+        sayTailEmptyNote(shown, feed);
         return;
     }
+    await followLogsTail(root, feed, coveredEnd, seams);
+}
+/** How `-n` scans versus prints: `limit` bounds the scan, not the print — the matched
+ * subset of the last `limit` events is what appears, so `-n 200 --grep merge_failed` may
+ * print 3 rows from 200 scanned. The read is the tail-with-end shape (not the per-poll
+ * cached readEvents) so the follow can seed from the byte end this very read covered
+ * instead of a later stat of the file. It also owns the share of output to print: the
+ * `shown` rows in read order. */
+function readTailShown(root, feed, limit) {
+    const tail = readEventsTailWithEnd(root, limit);
+    const shown = feed.grepLower !== null || feed.type !== null || feed.roles !== null || feed.notable ? tail.events.filter(feed.filter) : tail.events;
+    return { shown, coveredEnd: tail.coveredEnd };
+}
+/** The empty-match guard shared by the `--count` branch and the no-follow plain branch: the
+ * empty-match line is prose (in JSON mode the empty output is the answer) and fires for
+ * either filter, naming the flag's value(s) whose match came up empty so the operator knows
+ * what to loosen. */
+function sayTailEmptyNote(shown, feed) {
+    if (shown.length === 0 && !feed.json && (feed.filtersGrepOrType || feed.roles !== null || feed.notable))
+        sayLogsTailNoMatch(feed);
+}
+/** The `-f` follow: resolve the event-log path and stream every newly landed event through
+ * the same `feed.filter` as the seeded window, seeded from `coveredEnd` (the byte end the
+ * initial read covered) and holding the filter across rotation. */
+async function followLogsTail(root, feed, coveredEnd, seams) {
     const file = eventsLogPath(root);
-    // Seed the follow from the byte end the initial read covered (tail.coveredEnd), mirroring
+    // Seed the follow from the byte end the initial read covered (coveredEnd), mirroring
     // cmdLogsTranscript's tail.end seed: an event appended between the read and the follow's
     // start lies past the printed window but at or above this offset, so the follow's first
     // poll delivers it — seeding from a fresh statOrNull(file).size instead would start past
@@ -318,7 +338,7 @@ async function sayLogsTail(root, feed, limit, seams) {
     // log scans to coveredEnd 0, and followFile tolerates a missing file (its poll re-stats
     // every interval), so a read-only command never leaves a harness state file behind — the
     // module contract above promises writes to stdout only.
-    await followUntilParentGone(file, tail.coveredEnd, (lines) => {
+    await followUntilParentGone(file, coveredEnd, (lines) => {
         for (const line of lines.filter(Boolean)) {
             const e = parseEventLine(line);
             // The filter holds across rotation: every event the follow callback sees goes through

package/dist/src/cli/{notify-command.js → cli-notify-command.js}

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { fail, say } from "./cli-output.js";
 import { loadConfig } from "../config/config.js";
 import { TUMWATER_SOURCE } from "../events/events.js";
-import { notifyCommandEnv, notifyExitGloss } from "../events/notify.js";
+import { notifyCommandEnv, notifyExitGloss } from "../events/event-notify.js";
 /** The one representative allowlisted event `tumwater notify --test` fires: a failed merge
  * with source `tumwater`. Fixed and opinionated — the goal is to prove the hook runs, not to
  * replay a specific page, so there are no per-type or per-message flags. */
@@ -16,7 +16,7 @@ const NOTIFY_TEST_MESSAGE = "tumwater notify --test";
  * Generous enough not to misclassify a hook that is merely slow. */
 export const NOTIFY_TEST_TIMEOUT_MS = 10_000;
 /** Run one notify hook to completion, returning its exit code. Unlike the notifier's detached
- * fire-and-forget spawn (src/events/notify.ts), this waits with inherited stdio by
+ * fire-and-forget spawn (src/events/event-notify.ts), this waits with inherited stdio by
  * default (the dashboard passes "ignore"), so the
  * operator sees the hook's own output and its exit. A shell that cannot start resolves 127 —
  * the conventional "command not found" code. A hook that does not finish within `timeoutMs`

package/dist/src/cli/cli-query-commands.js

@@ -1,6 +1,6 @@
 /** The read-only query commands' bodies (status, diff, queue, backlog), split out of
  * cli.ts's dispatcher: main() routes to a cmd* here exactly as it routes to operator-commands's
- * cmdAbort or config-commands's cmdConfig, and cli.ts keeps only routing and the help/version
+ * cmdAbort or cli-config-commands's cmdConfig, and cli.ts keeps only routing and the help/version
  * surfaces. Each command owns its argument gate, ready-repo gating decision, and output shape,
  * with the wording and gating order moved verbatim from main()'s cases. */
 import { fail, say, sayJson, sayJsonOrRender } from "./cli-output.js";
@@ -25,7 +25,7 @@ import { renderMergeQueue, scopeMergeQueue } from "../merge/merge-queue-render.j
 import { mergeChanges } from "../merge/merge-slot.js";
 import { shortSha } from "../text/format.js";
 import { roleLabel } from "../roles/role-labels.js";
-import { orchestratorAlive } from "../team/orchestrator-info.js";
+import { orchestratorAlive } from "../team/team-orchestrator-info.js";
 import { queueInFlight } from "../status/status-polls.js";
 import { roleInScope } from "../roles/runner-ids.js";
 /** `tumwater status [-f/--follow]`: the team snapshot as rendered text or as the JSON