tumwater 0.1.2 → 0.1.3

package/dist/src/brief-edit.js

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+import { INITIAL_PROMPT_MAX_CHARS, PROMPT_END, PROMPT_START, briefPath, replaceInitialPrompt } from "./brief.js";
+import { commitOperatorBacklogEdit } from "./backlog/backlog-commit.js";
+import { withStateLock } from "./concurrency/lock.js";
+import { writeTextAtomic } from "./files/files.js";
+import { stampedSubject } from "./git/commit-message.js";
+import { primaryWorktreeLockPath } from "./paths.js";
+import { PREFILL_REASON } from "./text/phrases.js";
+import { tooLongMessage } from "./text/text.js";
+const NO_BRIEF = "no project brief with a prompt block found — run `tumwater init` first";
+/** Replace the initial prompt with `text` under the checks init applies (non-empty, at most
+ * INITIAL_PROMPT_MAX_CHARS, no prompt marker), write it under the primary-worktree lock, and
+ * commit that one file on main. The one writer behind `tumwater brief --file` and the
+ * dashboard's Settings card, so the two cannot drift. */
+export async function editInitialPrompt(root, text) {
+    const prompt = text.trim();
+    if (prompt === "")
+        return { ok: false, error: "the new initial prompt is empty" };
+    if (prompt.length > INITIAL_PROMPT_MAX_CHARS)
+        return { ok: false, error: tooLongMessage("the new initial prompt", prompt.length, INITIAL_PROMPT_MAX_CHARS, PREFILL_REASON) };
+    if (prompt.includes(PROMPT_START) || prompt.includes(PROMPT_END))
+        return { ok: false, error: "the new initial prompt contains a tumwater:prompt marker, which would break the block for every reader" };
+    const file = briefPath(root);
+    if (file === null)
+        return { ok: false, error: NO_BRIEF };
+    const name = path.basename(file);
+    const changed = withStateLock(primaryWorktreeLockPath(root), () => {
+        const current = fs.readFileSync(file, "utf8");
+        const next = replaceInitialPrompt(current, prompt);
+        if (next === null)
+            return `${name} no longer carries a prompt block`;
+        if (next === current)
+            return false;
+        writeTextAtomic(file, next);
+        return true;
+    });
+    if (typeof changed === "string")
+        return { ok: false, error: changed };
+    const committed = changed && (await commitOperatorBacklogEdit(root, name, stampedSubject("operator", "Edit initial prompt")));
+    return { ok: true, file: name, changed, committed };
+}

package/dist/src/brief.js

@@ -101,14 +101,40 @@ export function briefFile(root) {
 export function readInitialPrompt(root) {
     return readBrief(root)?.prompt ?? "";
 }
-function extractPrompt(text) {
+/** The full path of the file that owns the prompt block (the same candidate readBrief
+ * resolves), or null when none does — so a writer edits the file every reader reads. */
+export function briefPath(root) {
+    const found = firstBriefText(root, ownsBrief);
+    return found ? path.join(root, found.file) : null;
+}
+/** `text` with the prompt block's content replaced by `prompt` (trimmed), every byte outside
+ * the two markers kept; null when the text has no well-formed block. Finds the block by
+ * extractPrompt's rule (first start marker, then the first end marker after it). */
+export function replaceInitialPrompt(text, prompt) {
+    const start = text.indexOf(PROMPT_START);
+    if (start < 0)
+        return null;
+    const bodyStart = start + PROMPT_START.length;
+    const end = text.indexOf(PROMPT_END, bodyStart);
+    if (end < 0)
+        return null;
+    return `${text.slice(0, bodyStart)}\n${prompt.trim()}\n${text.slice(end)}`;
+}
+/** The trimmed, untruncated text between the first start marker and the first end marker after
+ * it; null when `text` has no well-formed block. */
+export function promptBlockOf(text) {
     const start = text.indexOf(PROMPT_START);
     if (start < 0)
         return null;
     const end = text.indexOf(PROMPT_END, start + PROMPT_START.length);
     if (end < 0)
         return null;
-    const prompt = text.slice(start + PROMPT_START.length, end).trim();
+    return text.slice(start + PROMPT_START.length, end).trim();
+}
+function extractPrompt(text) {
+    const prompt = promptBlockOf(text);
+    if (prompt === null)
+        return null;
     // A hand-edited brief can carry an over-long prompt past init's length check. Truncate it
     // for every tick instead of injecting the whole thing (the same defensive cap readPrinciples
     // applies, through text.ts's truncateWithNote), with a visible note so the loss is not
@@ -125,3 +151,8 @@ export function readBrief(root) {
     const found = firstBriefText(root, ownsBrief);
     return found ? { file: found.file, prompt: extractPrompt(found.text) ?? "" } : null;
 }
+/** The brief's plain-text form: its file name, then the initial prompt — what `tumwater brief`
+ * prints and the TUI's Brief tab shows, so the two cannot drift. */
+export function renderBrief(brief) {
+    return `${brief.file}\n${brief.prompt}`;
+}

package/dist/src/change/change-data.js

@@ -34,7 +34,7 @@ const DIFF_MAX_BYTES = 200_000;
 /** Collect the change the role's loop holds: both halves of the view, or a degraded state
  * when the worktree or the base branch is missing. Never throws on a degraded fleet — a
  * query about a loop that has not run yet must answer, not fail (report's rationale). */
-export async function collectRoleChange(root, role) {
+export async function collectRoleChange(root, role, opts = {}) {
     const branch = branchName(role);
     const { config } = loadConfigSafe(root);
     const mainBranch = targetBranch(config?.baseBranch, await currentBranch(root));
@@ -59,9 +59,18 @@ export async function collectRoleChange(root, role) {
         return { ...empty, state: "absent" };
     const ahead = await aheadOfMain(wt, mainBranch);
     const commits = parseOnelineLog(await gitTry(wt, "log", "--oneline", `${mainBranch}..HEAD`));
-    const diff = ahead === 0 ? "" : await aheadOfMainDiff(wt, mainBranch);
+    // Under opts.stat both halves hold the uncapped `git diff --stat` summary (one line per file).
+    const diff = ahead === 0
+        ? ""
+        : opts.stat
+            ? ((await gitTry(wt, "diff", "--stat", `${mainBranch}...HEAD`)) ?? "")
+            : await aheadOfMainDiff(wt, mainBranch);
     const dirtyFiles = await changedFiles(wt);
-    const uncommittedDiff = dirtyFiles.length === 0 ? "" : await cappedWorkingDiff(wt);
+    const uncommittedDiff = dirtyFiles.length === 0
+        ? ""
+        : opts.stat
+            ? ((await gitTry(wt, "diff", "--stat", "HEAD")) ?? "")
+            : await cappedWorkingDiff(wt);
     return { ...empty, state: "ready", ahead, commits, diff, dirtyFiles, uncommittedDiff };
 }
 /** Parse `git log --oneline` output into {sha, subject} pairs — sha up to the first space,

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

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { readBrief, renderBrief } from "../brief.js";
+import { editInitialPrompt } from "../brief-edit.js";
+import { editInEditor } from "./cli-editor.js";
+import { readPromptFileArg } from "./cli-command-args.js";
+import { JSON_FLAG, rejectUnknownArgs } from "./cli-flag-specs.js";
+import { fail, say, sayJson } from "./cli-output.js";
+import { requireReadyRepo } from "./cli-repo-gate.js";
+/** `brief`'s `--file <path>` flag: the replacement prompt (`-` for stdin). */
+const FILE_SPEC = { names: ["--file"], value: true, valueName: "<path>" };
+/** `brief`'s `--edit` flag: open the prompt in `$VISUAL`/`$EDITOR`. */
+const EDIT_SPEC = { names: ["--edit"] };
+/** `tumwater brief`: show the initial prompt and the file holding it, or with `--file <path>`
+ * replace it (or with `--edit`, open it in the editor) under the checks init applies and commit that one file on main. */
+export async function cmdBrief(root, args) {
+    rejectUnknownArgs("brief", args, [JSON_FLAG, FILE_SPEC, EDIT_SPEC]);
+    await requireReadyRepo(root);
+    const json = args.includes("--json");
+    const fileIdx = args.indexOf("--file");
+    const edit = args.includes("--edit");
+    if (edit && fileIdx >= 0)
+        fail("pass --edit or --file, not both");
+    const brief = readBrief(root);
+    if (brief === null)
+        fail("no project brief with a prompt block found — run `tumwater init` first");
+    if (fileIdx < 0 && !edit) {
+        if (json)
+            sayJson({ file: brief.file, prompt: brief.prompt });
+        else
+            say(renderBrief(brief));
+        return;
+    }
+    let text;
+    if (edit) {
+        text = editInEditor(brief.prompt, "brief.md", "pass --file <path>");
+        if (text.trim() === brief.prompt.trim()) {
+            if (json)
+                sayJson({ file: path.basename(brief.file), changed: false, committed: false });
+            else
+                say("initial prompt unchanged");
+            return;
+        }
+    }
+    else
+        text = readPromptFileArg(args[fileIdx + 1]);
+    const outcome = await editInitialPrompt(root, text);
+    if (!outcome.ok)
+        fail(outcome.error);
+    const { file: name, changed, committed } = outcome;
+    if (json)
+        sayJson({ file: name, changed, committed });
+    else if (!changed)
+        say("initial prompt unchanged");
+    else
+        say(`initial prompt updated in ${name}${committed ? " (committed to main)" : ""}`);
+}

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

@@ -307,7 +307,7 @@ export function parsePromptArgs(args) {
         // claims. Tokens preceding --edit (other than a claimed flag) would be silently dropped —
         // a mistyped command would edit prompt N with only the trailing fragment — so they are
         // refused here by the same stray-argument wording the sibling modes use; tokens after the
-        // position are the replacement text, minus any claimed attach pair.
+        // position are the replacement text, minus any claimed attach pair (none: edit in $EDITOR).
         const fileClaim = fileFlag >= 0 ? [fileFlag, fileFlag + 1] : [];
         for (let i = 0; i < editFlag; i++) {
             if (roleClaim.includes(i) || attachClaims.includes(i) || fileClaim.includes(i))
@@ -328,9 +328,8 @@ export function parsePromptArgs(args) {
             textTokens.push(args[i]);
         }
         const text = textTokens.join(" ").trim();
-        if (!text)
-            fail('edit text required — usage: tumwater prompt --edit <n> "<new text>" (add --role <id> to aim it at one loop)');
-        return { mode: "edit", role, position: n, text, attachPaths };
+        // No text and no --file: the caller opens the prompt's current body in the editor.
+        return { mode: "edit", role, position: n, text: text === "" ? null : text, attachPaths };
     }
     if (fileFlag >= 0) {
         // The file is the prompt: read it whole (a path of `-` reads stdin, so a pipe or heredoc

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

@@ -0,0 +1,52 @@
+// Open text in the operator's editor, the way `git commit` and `crontab -e` do.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fail } from "./cli-output.js";
+/** Signal number → name, for the shell's 128+n convention: a shell that does not re-raise a
+ * signal-killed child (dash on Linux) exits with 128+signo, so node sees an exit status where
+ * bash on macOS lets it see the signal. Keyed by number, so a later alias (SIGABRT over SIGIOT)
+ * wins; any name is fine for the message. */
+const SIGNAL_NAMES = Object.fromEntries(Object.entries(os.constants.signals).map(([name, n]) => [n, name]));
+/** How an editor run ended, naming a signal even when the shell folded it into 128+n. A null
+ * status (spawn error, signal) and a plain non-zero status fall through unchanged. */
+function exitReason(r) {
+    if (r.error)
+        return r.error.message;
+    if (r.signal)
+        return `signal ${r.signal}`;
+    const signalled = r.status !== null && r.status > 128 ? SIGNAL_NAMES[r.status - 128] : undefined;
+    return signalled ? `signal ${signalled}` : `status ${r.status}`;
+}
+/** Write `initial` to a temp file named `fileName`, run `$VISUAL` (else `$EDITOR`) on it, and
+ * return the saved text. The editor value runs through `sh -c` (git's convention) so one with
+ * arguments, like `code -w`, works. There is no `vi` fallback: a script without a TTY must fail
+ * rather than hang. A missing editor, a spawn error, a non-zero exit, or a signal fails the
+ * command (`fallback` ends the no-editor message); the temp dir is removed before the failure exits. */
+export function editInEditor(initial, fileName, fallback = "pass the new text or --file <path>") {
+    const editor = (process.env.VISUAL || process.env.EDITOR || "").trim();
+    if (editor === "")
+        fail(`no editor: set $VISUAL or $EDITOR, or ${fallback}`);
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tumwater-edit-"));
+    let saved;
+    let failure;
+    try {
+        const file = path.join(dir, fileName);
+        fs.writeFileSync(file, `${initial}\n`);
+        const r = spawnSync("sh", ["-c", `${editor} "$1"`, "sh", file], { stdio: "inherit" });
+        if (r.error || r.status !== 0) {
+            failure = `editor exited with ${exitReason(r)}; nothing changed`;
+        }
+        else {
+            saved = fs.readFileSync(file, "utf8");
+        }
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    // fail() exits the process, which would skip the finally above, so it runs after cleanup.
+    if (failure !== undefined)
+        fail(failure);
+    return saved;
+}

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

@@ -127,15 +127,22 @@ export const PAUSE_FOR_OVERFLOW_HINT = "for a longer or standing pause run bare
  * `pause --for` honors, the same not-initialized-masking rationale durationFlagSpec records).
  * missingValue names the command for a trailing `--in` (`wake --in needs a value`), the same
  * command-named pattern durationFlagSpec and sinceFlagSpec follow. */
-export const WAKE_IN_FLAG = {
-    names: ["--in"],
-    value: true,
-    valueName: "<duration>",
-    missingValue: "wake --in needs a value",
-    validate: (value) => {
-        failOverDurationCap("wake --in", parseDurationFlag("wake --in", value), PAUSE_FOR_MAX_MS);
-    },
-};
+function inFlagSpec(command) {
+    return {
+        names: ["--in"],
+        value: true,
+        valueName: "<duration>",
+        missingValue: `${command} --in needs a value`,
+        validate: (value) => {
+            failOverDurationCap(`${command} --in`, parseDurationFlag(`${command} --in`, value), PAUSE_FOR_MAX_MS);
+        },
+    };
+}
+export const WAKE_IN_FLAG = inFlagSpec("wake");
+/** `tumwater stop --in <duration>`: the scheduled graceful stop, same shape and cap as wake's. */
+export const STOP_IN_FLAG = inFlagSpec("stop");
+/** `tumwater stop --cancel`: drop the scheduled stop. */
+export const STOP_CANCEL_FLAG = { names: ["--cancel"] };
 /** The `--cancel` flag spec for `tumwater wake --cancel`: drop pending scheduled wakes. */
 export const WAKE_CANCEL_FLAG = { names: ["--cancel"] };
 /** `wake --list`: print the pending scheduled wakes instead of writing one. Takes no value. */
@@ -195,11 +202,17 @@ export const N_FLAG = {
  * siblings it needs neither a factory nor a missing-value error — so the constant is the
  * whole spec, and the render-vs-JSON switch stays in each command body beside its render. */
 export const JSON_FLAG = { names: ["--json"] };
+/** The `--stat` flag spec, accepted by `diff --role`: print each patch as its `git diff --stat`
+ * summary. Value-less, like JSON_FLAG. */
+export const STAT_FLAG = { names: ["--stat"] };
+/** The `--summary` flag spec, accepted by `history`: tally each loop's tick outcomes instead of
+ * printing the rows. Value-less, like STAT_FLAG. */
+export const SUMMARY_FLAG = { names: ["--summary"] };
 /** The `--force` flag spec, accepted by `retire` (the only override-the-rails command): one
  * definition of the flag's spelling beside ROLE_FLAG and JSON_FLAG, so the gate's accepted
  * vocabulary cannot drift from the command body's `args.includes("--force")`. */
 export const FORCE_FLAG = { names: ["--force"] };
-/** The `--dry-run` flag spec: preview a reclaim pass without deleting anything. Beside
+/** The `--dry-run` flag spec: preview a reclaim pass or a retire without changing anything. Beside
  * FORCE_FLAG so its spelling lives with the other boolean flags the gate admits. */
 export const DRY_RUN_FLAG = { names: ["--dry-run"] };
 /** The `--last` flag spec for `tumwater tick <role> --last`: one definition of the flag's

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

@@ -20,6 +20,15 @@ function writeLine(text) {
 export function say(text) {
     writeLine(stripTerminalControls(text));
 }
+/** Tell the operator, on stderr, that an operator backlog write landed in the working tree but
+ * was not committed to main (commitOperatorBacklogEdit returned false: the primary is off the
+ * base branch, or git failed). The write itself succeeded, so this warns instead of failing;
+ * a no-op when the commit landed. */
+export function warnIfUncommitted(committed, file) {
+    if (committed)
+        return;
+    process.stderr.write(`warning: ${file} was written but not committed to main — commit it before the next fast-forward\n`);
+}
 /** Print a value as pretty-printed (2-space) JSON — the `--json` output every CLI query
  * command (status, history, report, config) renders through: the pretty-print spelling
  * (indent 2) decided once so the machine-readable surface cannot drift per command. Writes

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

@@ -3,9 +3,9 @@
  * cmdAbort or 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";
+import { fail, say, sayJson, sayJsonOrRender, warnIfUncommitted } from "./cli-output.js";
 import { flagValue, parseRoleFlag, rejectRepeatFlag } from "./cli-args.js";
-import { JSON_FLAG, rejectEqualsForm, rejectUnknownArgs, ROLE_FLAG } from "./cli-flag-specs.js";
+import { JSON_FLAG, rejectEqualsForm, rejectUnknownArgs, ROLE_FLAG, STAT_FLAG } from "./cli-flag-specs.js";
 import { requireReadyRepo } from "./cli-repo-gate.js";
 import { defaultConfig, knownRoleIds, knownRoleIdsCached, loadConfigSafe } from "../config/config.js";
 import { gotSuffix, parsePositiveInt } from "../text/text.js";
@@ -19,6 +19,8 @@ import { collectFleetChanges, collectRoleChange } from "../change/change-data.js
 import { renderFleetChange, renderRoleChange } from "../change/change-render.js";
 import { readLandingQueue } from "../landing/landing-queue.js";
 import { renderLandingQueue } from "../landing/landing-queue-render.js";
+import { orchestratorAlive } from "../fleet/orchestrator-info.js";
+import { queueInFlight } from "../status/status-polls.js";
 import { rolePayload } from "../roles/role-view.js";
 import { renderRoleMarkdown } from "../roles/role-render.js";
 import { DIRECTOR_ROLE, unknownRoleMessage } from "../roles/roles.js";
@@ -26,7 +28,10 @@ import { saveRoleNote } from "../agent/role-notes-write.js";
 import { roleNotesPath } from "../paths.js";
 import { errorMessage } from "../text/text.js";
 import { readPromptFileArg, promptFileValue } from "./cli-command-args.js";
-import { answerQuestion, answerQuestionFromText, sayAnswered, sayQuestionList } from "./question-commands.js";
+import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
+import { stampedSubject } from "../git/commit-message.js";
+import { answerEditorBuffer, answerQuestion, answerQuestionFromText, decisionFromEditorBuffer, questionListPayload, sayAnswered, sayQuestionList } from "./question-commands.js";
+import { editInEditor } from "./cli-editor.js";
 /** `questions answer`'s `--file <path>` flag: the decision comes from the file, lines kept. */
 const FILE_SPEC = { names: ["--file"], value: true, valueName: "<path>" };
 /** `role`'s notebook-write flags: clear the note, or replace it from a file (`-` for stdin). */
@@ -87,17 +92,19 @@ export async function cmdDiff(root, args) {
     // command. Past the gate an absent worktree still degrades to a `no worktree for
     // <role>` line (exit 0), so the command answers in any initialized directory —
     // report's rationale.
-    rejectUnknownArgs("diff", args, [ROLE_FLAG, JSON_FLAG]);
+    rejectUnknownArgs("diff", args, [ROLE_FLAG, JSON_FLAG, STAT_FLAG]);
     await requireReadyRepo(root);
     // Absent --role is the fleet-wide form: one line per loop holding pending work
     // (parseRoleFlag returns null only for an absent flag — an empty or unknown value
     // already failed above). A named role keeps the full per-role view.
     const role = parseRoleFlag(args, knownRoleIdsCached(root));
     if (role === null) {
+        if (args.includes("--stat"))
+            fail("diff --stat needs --role <id> (the fleet roster prints no patch)");
         sayJsonOrRender(args, await collectFleetChanges(root), renderFleetChange);
     }
     else {
-        const change = await collectRoleChange(root, role);
+        const change = await collectRoleChange(root, role, { stat: args.includes("--stat") });
         sayJsonOrRender(args, change, renderRoleChange);
     }
 }
@@ -113,7 +120,11 @@ export async function cmdQueue(root, args) {
     // The JSON branch prints the reader's own document — raw sha and numeric enqueuedAt, not
     // the render's short sha and age — and the render is the collector's view with one clock
     // read, so `tumwater queue` and `tumwater status --json`'s landQueue cannot drift.
-    sayJsonOrRender(args, readLandingQueue(root), (view) => renderLandingQueue(view, Date.now()));
+    // The in-flight marker rides along only while an orchestrator runs and the marker names a
+    // queued entry (queueInFlight) — status --json's landQueue.inFlight, so the two agree.
+    const view = readLandingQueue(root);
+    const inFlight = queueInFlight(root, view.entries, orchestratorAlive(root));
+    sayJsonOrRender(args, inFlight ? { ...view, inFlight } : view, (v) => renderLandingQueue(v, Date.now(), inFlight));
 }
 /** `tumwater backlog`: the planned/open entries as Markdown or as the GUI's JSON payload. */
 export async function cmdBacklog(root, args) {
@@ -195,15 +206,30 @@ export async function cmdQuestions(root, args) {
         if (words.length > 2)
             fail(`unexpected argument ${JSON.stringify(words[2])} — with --file the decision comes from the file`);
         const answered = answerQuestionFromText(root, n, readPromptFileArg(file));
+        warnIfUncommitted(await commitOperatorBacklogEdit(root, "QUESTIONS.md", stampedSubject("operator", `Answer question: ${answered.title}`)), "QUESTIONS.md");
         sayAnswered(n, answered.title, jsonFlag, answered.decision);
         return;
     }
     const decision = words.slice(2).join(" ").trim();
+    if (words.length === 2) {
+        const open = questionListPayload(root).questions;
+        const question = open[n - 1];
+        if (question === undefined)
+            fail(`no question at position ${n} (${open.length} open)`);
+        const edited = decisionFromEditorBuffer(editInEditor(answerEditorBuffer(question.title, question.body), `answer-${n}.md`, "pass a decision or --file <path>"));
+        if (edited.trim() === "")
+            fail("questions answer needs a decision: the editor left it blank; nothing changed");
+        const answered = answerQuestionFromText(root, n, edited, question.title);
+        warnIfUncommitted(await commitOperatorBacklogEdit(root, "QUESTIONS.md", stampedSubject("operator", `Answer question: ${answered.title}`)), "QUESTIONS.md");
+        sayAnswered(n, answered.title, jsonFlag, answered.decision);
+        return;
+    }
     if (decision === "")
         fail('questions answer needs a decision: questions answer <n> "<decision>"');
     // answerQuestion collapses the free-form decision to one line before writing it; report
     // that landed text in the --json payload so it matches the file, not the caller's spacing.
     const { title, decision: landedDecision } = answerQuestion(root, n, decision);
+    warnIfUncommitted(await commitOperatorBacklogEdit(root, "QUESTIONS.md", stampedSubject("operator", `Answer question: ${title}`)), "QUESTIONS.md");
     sayAnswered(n, title, jsonFlag, landedDecision);
 }
 /** `tumwater role <id>`: one loop's standing prompt and next tick's assembled prompt. */