catherd-cli 0.2.1 → 1.1.0

package/src/entry/tui/run.tsx

@@ -0,0 +1,98 @@
+import { type CliRenderer, createCliRenderer, SystemClock } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { gitToplevel } from "../../infra/git.ts";
+import { readConfig } from "../../services/profile-store.ts";
+import { CatherdError } from "../../domain/errors.ts";
+import { EXIT, printError } from "../cli-kit.ts";
+import { type Keybinds, resolveKeybinds } from "./commands.ts";
+import type { Effects } from "./effects.ts";
+import { liveEffects } from "./effects.ts";
+import { fixtureEffects } from "./fixtures.ts";
+import { createAppKeymap } from "./providers/keymap.tsx";
+import { Providers } from "./providers/root.tsx";
+import { initialState, type Tab } from "./state.ts";
+import { detectUi, type ThemeMode } from "./theme.ts";
+import { App } from "./views/app.tsx";
+
+export interface TuiOptions {
+  rawArgs: string[];
+  tab?: Tab;
+  env?: Record<string, string | undefined>;
+  /** Whether stdin and stdout are a terminal; tests pass it so none reads the real one. */
+  tty?: boolean;
+}
+
+/** The keys in force: the defaults under config.json's `keybinds` (E_CONFIG_KEYBIND before anything draws). */
+export const keybindsFromConfig = (): Keybinds =>
+  resolveKeybinds((readConfig() as { keybinds?: unknown }).keybinds);
+
+/** The terminal's own background decides dark or light, else dark (spec §9.3). */
+async function modeOf(renderer: CliRenderer): Promise<ThemeMode> {
+  return renderer.themeMode ?? (await renderer.waitForThemeMode(1000)) ?? "dark";
+}
+
+/**
+ * Spec §9.4's renderer: no mouse capture, `exitOnCtrlC: false` (ctrl+c is the app's to layer), the
+ * alternate screen for the app only; the lines the user must keep print to stdout once it is gone.
+ * Resolves to the exit code: 0, or 130 when unsaved changes were discarded with ctrl+c.
+ */
+export async function openTui(o: TuiOptions): Promise<number> {
+  const env = o.env ?? process.env;
+  const tty = o.tty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!tty) {
+    printError(
+      new CatherdError("E_INPUT_INVALID", "the dashboard needs an interactive terminal", {
+        fix: "in a script, run catherd status, catherd doctor or catherd watch --once",
+      }),
+    );
+    return EXIT.usage;
+  }
+  const keybinds = keybindsFromConfig();
+  const story = Boolean(env.CATHERD_STORY);
+  // the repo this directory is in, resolved once at start (the repo ruling)
+  const effects: Effects = story ? fixtureEffects() : liveEffects(await gitToplevel(process.cwd()));
+  const renderer = await createCliRenderer({
+    exitOnCtrlC: false,
+    useMouse: false,
+    autoFocus: false,
+    screenMode: "alternate-screen",
+    // the kitty protocol tells esc from alt+key at once; CATHERD_NO_KITTY=1 turns it off where it misbehaves
+    useKittyKeyboard: env.CATHERD_NO_KITTY ? null : {},
+    targetFps: 30,
+  });
+  let result = { code: EXIT.ok as number, kept: [] as string[] };
+  const done = new Promise<void>((resolve) => renderer.once("destroy", () => resolve()));
+  // anything that throws once the renderer exists gives the terminal back before the error surfaces
+  try {
+    const ui = { ...detectUi(o.rawArgs, env), mode: await modeOf(renderer) };
+    renderer.setTerminalTitle(story ? "catherd stories" : "catherd");
+    createRoot(renderer).render(
+      <Providers
+        ui={ui}
+        keybinds={keybinds}
+        keymap={createAppKeymap(renderer)}
+        effects={effects}
+        clock={new SystemClock()}
+        initial={initialState(o.tab ?? "status")}
+        copy={(text) => renderer.copyToClipboardOSC52(text)}
+        onExit={(code, kept) => {
+          result = { code, kept };
+          renderer.destroy();
+        }}
+      >
+        <App story={story} />
+      </Providers>,
+    );
+  } catch (e) {
+    renderer.destroy();
+    throw e;
+  }
+  await done;
+  for (const line of result.kept) console.log(line);
+  return result.code;
+}
+
+/** Bare `catherd`: `cli.ts` imports this only when no subcommand was named, so no subcommand loads OpenTUI. */
+export async function tuiRun(ctx: { rawArgs: string[] }): Promise<void> {
+  process.exitCode = await openTui({ rawArgs: ctx.rawArgs });
+}

package/src/entry/tui/state.ts

@@ -0,0 +1,356 @@
+import {
+  applyPatch,
+  diffProfiles,
+  patchBetween,
+  type ProfileDoc,
+  type ProfilePatch,
+  resolveProfile,
+} from "../../domain/profile.ts";
+import type { Role } from "../../domain/roles.ts";
+
+/** Spec §9.1: one app, three tabs. */
+export const TABS = ["status", "profiles", "runs"] as const;
+export type Tab = (typeof TABS)[number];
+
+/** What a draft can undo to: the edited document and the treat-likes staged with it. */
+interface Snapshot {
+  doc: ProfileDoc;
+  /** rung → the scored rung it is treated like; written to catalog.override.json on save */
+  treatLikes: Record<string, string>;
+}
+
+/** Spec §9.2: edits are staged per profile and touch nothing on disk until a save. */
+export interface Draft extends Snapshot {
+  name: string;
+  /** the document as it was read, which a save diffs against */
+  base: ProfileDoc;
+  past: Snapshot[];
+  future: Snapshot[];
+}
+
+/** The number fields a value editor sets. */
+const NUMBER_PATHS = [
+  "budget.minutes",
+  "budget.tokens",
+  "budget.usd",
+  "timeouts.idleMin",
+  "timeouts.wallMin",
+] as const;
+export type NumberPath = (typeof NUMBER_PATHS)[number];
+
+/** Why a dialog is open, so the one handler for that purpose runs when it is answered. */
+export type Purpose =
+  | { type: "palette" }
+  | { type: "help" }
+  | { type: "quit" }
+  | { type: "save"; name: string }
+  /** `repo`: the scope the prompt shows, the bound repo or null for the global profile */
+  | { type: "activate"; name: string; repo: string | null }
+  | { type: "revert"; name: string }
+  | { type: "profiles" }
+  | { type: "new" }
+  | { type: "copy"; from: string }
+  | { type: "number"; path: NumberPath }
+  | { type: "start"; role: Role }
+  | { type: "treatLike"; rung: string; role: Role | null }
+  | { type: "failover"; rung: string }
+  | { type: "stories" };
+
+export interface SelectOption {
+  value: string;
+  title: string;
+  /** options with a group are shown under its heading, in the order the groups first appear */
+  group?: string;
+  /** muted text after the title, in a column of its own: a key, a mark */
+  detail?: string;
+  /** a second muted column after the detail (the command's CLI twin); dropped when it does not fit */
+  cli?: string;
+  /** the value in force now, marked `●` */
+  current?: boolean;
+}
+
+export type Dialog =
+  | {
+      kind: "select";
+      purpose: Purpose;
+      title: string;
+      options: SelectOption[];
+      /** Suggested options, shown first while the filter is empty */
+      suggested?: string[];
+      /** offers ctrl+d, pressed twice, to delete the selected option */
+      deletable?: boolean;
+      /** the one muted line shown when there is nothing to choose */
+      empty: string;
+    }
+  | {
+      kind: "confirm";
+      purpose: Purpose;
+      title: string;
+      message: string[];
+      yes: string;
+      no: string;
+      /** a destructive confirm starts on its "no" button */
+      destructive: boolean;
+    }
+  | { kind: "prompt"; purpose: Purpose; title: string; label: string; value: string; error: string | null }
+  | {
+      kind: "save";
+      purpose: { type: "save"; name: string };
+      error: string | null;
+      /** a save is writing: the dialog shows "saving…", takes no answer and cannot be closed */
+      saving?: boolean;
+    };
+
+/** A double press waiting for its second key (spec §9.2: ctrl+c when dirty, ctrl+d to delete or cancel). */
+export interface Armed {
+  what: "interrupt" | "delete" | "cancel";
+  target: string;
+  at: number;
+}
+
+/** How long the second press of each double press may wait. */
+export const ARM_MS: Record<Armed["what"], number> = { interrupt: 1_500, delete: 5_000, cancel: 5_000 };
+
+export const HISTORY_LIMIT = 100;
+
+export interface AppState {
+  tab: Tab;
+  /** the profile the Profiles tab shows; null until one is read */
+  profile: string | null;
+  drafts: Record<string, Draft>;
+  /** the open dialogs; only the top one is drawn and takes keys */
+  dialogs: Dialog[];
+  /** spec §4: the session the Runs tab has open (`key` null: "earlier runs"); null shows the sessions */
+  session: { key: string | null } | null;
+  /** the role the open session shows, by its dispatch */
+  role: { run: string; dispatchId: string } | null;
+  /** spec 1.1 §10: the milestone the open session shows, its digest */
+  milestone: { run: string; name: string } | null;
+  paused: boolean;
+  armed: Armed | null;
+}
+
+export type Action =
+  | { type: "tab"; tab: Tab }
+  | { type: "show"; name: string; doc: ProfileDoc }
+  | { type: "edit"; patch: ProfilePatch }
+  /** `patch` (ticking the rung) lands in the same undo step as the treat-like */
+  | { type: "treatLike"; rung: string; like: string | null; patch?: ProfilePatch }
+  | { type: "undo" }
+  | { type: "redo" }
+  /** `doc`: the profile as it is on disk now, the new base (else the draft's own base) */
+  | { type: "revert"; name: string; doc?: ProfileDoc }
+  /** `from` is the draft as the save began; edits made while it wrote stay staged over `doc` */
+  | { type: "saved"; name: string; doc: ProfileDoc; from?: Snapshot }
+  | { type: "forget"; name: string }
+  | { type: "open"; dialog: Dialog }
+  | { type: "replace"; dialog: Dialog }
+  | { type: "close" }
+  | { type: "saving"; name: string; on: boolean }
+  | { type: "input"; value: string }
+  | { type: "invalid"; error: string | null }
+  /** opens a session of the Runs tab (`key` null: "earlier runs") */
+  | { type: "session"; key: string | null }
+  /** opens one role of the open session */
+  | { type: "role"; run: string; dispatchId: string }
+  /** opens one milestone of the open session, on its digest */
+  | { type: "milestone"; run: string; name: string }
+  /** the Runs tab goes back one level: a milestone or a role to its session, a session to the list */
+  | { type: "up" }
+  | { type: "pause" }
+  | { type: "arm"; what: Armed["what"]; target: string; at: number }
+  | { type: "disarm" };
+
+export const initialState = (tab: Tab = "status"): AppState => ({
+  tab,
+  profile: null,
+  drafts: {},
+  dialogs: [],
+  session: null,
+  role: null,
+  milestone: null,
+  paused: false,
+  armed: null,
+});
+
+const fresh = (name: string, doc: ProfileDoc): Draft => ({
+  name,
+  base: doc,
+  doc,
+  treatLikes: {},
+  past: [],
+  future: [],
+});
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+
+/** The draft the Profiles tab shows, if any. */
+export const currentDraft = (s: AppState): Draft | null => (s.profile ? (s.drafts[s.profile] ?? null) : null);
+
+/** Changes staged in a draft: each changed field of the profile, and each staged treat-like. */
+const isStaged = (d: Draft | undefined): boolean => d !== undefined && dirtyCount(d) > 0;
+
+export function dirtyCount(d: Draft): number {
+  const fields = diffProfiles(resolveProfile(d.base, d.name), resolveProfile(d.doc, d.name)).length;
+  return fields + Object.keys(d.treatLikes).length;
+}
+
+export const totalDirty = (s: AppState): number =>
+  Object.values(s.drafts).reduce((n, d) => n + dirtyCount(d), 0);
+
+/** Whether a save is writing: its dialog stays open, and the TUI does not quit, until it settles. */
+export const isSaving = (s: AppState): boolean =>
+  s.dialogs.some((d) => d.kind === "save" && d.saving === true);
+
+/** Whether the second press of `what` on `target` at `now` completes the double press. */
+export const isArmed = (s: AppState, what: Armed["what"], target: string, now: number): boolean =>
+  s.armed !== null && s.armed.what === what && s.armed.target === target && now - s.armed.at <= ARM_MS[what];
+
+/** A draft moved to `next`, the old state kept for undo; a change to nothing is no change. */
+function step(d: Draft, next: Snapshot): Draft {
+  if (same(next.doc, d.doc) && same(next.treatLikes, d.treatLikes)) return d;
+  return {
+    ...d,
+    ...next,
+    past: [...d.past, { doc: d.doc, treatLikes: d.treatLikes }].slice(-HISTORY_LIMIT),
+    future: [],
+  };
+}
+
+function withDraft(s: AppState, name: string | null, f: (d: Draft) => Draft): AppState {
+  const d = name ? s.drafts[name] : undefined;
+  if (!d) return s;
+  const next = f(d);
+  return next === d ? s : { ...s, drafts: { ...s.drafts, [d.name]: next } };
+}
+
+/** Spec §9.4 `state.ts`: the pure reducer for tabs, drafts and their history, dialogs and armed keys. */
+export function reduce(s: AppState, a: Action): AppState {
+  switch (a.type) {
+    case "tab":
+      return { ...s, tab: a.tab, armed: null };
+    case "show":
+      return {
+        ...s,
+        tab: "profiles",
+        profile: a.name,
+        // Keep only a draft with staged changes; a clean one restarts from the file just read.
+        drafts: isStaged(s.drafts[a.name]) ? s.drafts : { ...s.drafts, [a.name]: fresh(a.name, a.doc) },
+      };
+    case "edit":
+      return withDraft(s, s.profile, (d) =>
+        step(d, { doc: applyPatch(d.doc, a.patch), treatLikes: d.treatLikes }),
+      );
+    case "treatLike":
+      return withDraft(s, s.profile, (d) => {
+        const treatLikes = { ...d.treatLikes };
+        if (a.like === null) delete treatLikes[a.rung];
+        else treatLikes[a.rung] = a.like;
+        return step(d, { doc: a.patch ? applyPatch(d.doc, a.patch) : d.doc, treatLikes });
+      });
+    case "undo":
+      return withDraft(s, s.profile, (d) => {
+        const prev = d.past.at(-1);
+        if (!prev) return d;
+        return {
+          ...d,
+          ...prev,
+          past: d.past.slice(0, -1),
+          future: [{ doc: d.doc, treatLikes: d.treatLikes }, ...d.future],
+        };
+      });
+    case "redo":
+      return withDraft(s, s.profile, (d) => {
+        const next = d.future[0];
+        if (!next) return d;
+        return {
+          ...d,
+          ...next,
+          past: [...d.past, { doc: d.doc, treatLikes: d.treatLikes }],
+          future: d.future.slice(1),
+        };
+      });
+    case "revert":
+      return withDraft(s, a.name, (d) => {
+        const base = a.doc ?? d.base;
+        if (same(base, d.base)) return step(d, { doc: d.base, treatLikes: {} });
+        // another process saved the profile since the draft opened: what is saved now is the new base, and
+        // the history (with this revert's undo step) keeps each staged change, now over that base. A step
+        // that cannot be carried over (a hand-written rung no patch accepts) is dropped: a reducer that
+        // throws from a key handler would end the TUI
+        const moved = (x: Snapshot): Snapshot[] => {
+          try {
+            return [{ ...x, doc: applyPatch(base, patchBetween(d.base, x.doc)) }];
+          } catch {
+            return [];
+          }
+        };
+        return {
+          ...d,
+          base,
+          doc: base,
+          treatLikes: {},
+          past: [...d.past, { doc: d.doc, treatLikes: d.treatLikes }].flatMap(moved).slice(-HISTORY_LIMIT),
+          future: [],
+        };
+      });
+    case "saved": {
+      const d = s.drafts[a.name];
+      const from = a.from;
+      if (!from || !d || (same(d.doc, from.doc) && same(d.treatLikes, from.treatLikes)))
+        return { ...s, drafts: { ...s.drafts, [a.name]: fresh(a.name, a.doc) } };
+      // edited while the save wrote: the saved file is the new base, and the newer edits stay staged over it
+      const treatLikes = Object.fromEntries(
+        Object.entries(d.treatLikes).filter(([rung, like]) => from.treatLikes[rung] !== like),
+      );
+      const doc = applyPatch(a.doc, patchBetween(from.doc, d.doc));
+      return { ...s, drafts: { ...s.drafts, [a.name]: { ...fresh(a.name, a.doc), doc, treatLikes } } };
+    }
+    case "forget": {
+      const { [a.name]: _gone, ...drafts } = s.drafts;
+      return { ...s, drafts, profile: s.profile === a.name ? null : s.profile };
+    }
+    case "open":
+      return { ...s, dialogs: [...s.dialogs, a.dialog], armed: null };
+    case "replace":
+      return { ...s, dialogs: [...s.dialogs.slice(0, -1), a.dialog], armed: null };
+    case "close": {
+      const top = s.dialogs.at(-1);
+      if (top?.kind === "save" && top.saving) return s;
+      return { ...s, dialogs: s.dialogs.slice(0, -1), armed: null };
+    }
+    case "saving": {
+      const at = s.dialogs.findIndex((d) => d.kind === "save" && d.purpose.name === a.name);
+      const d = s.dialogs[at];
+      if (d?.kind !== "save" || (d.saving === true) === a.on) return s;
+      const dialogs = [...s.dialogs];
+      dialogs[at] = { ...d, saving: a.on };
+      return { ...s, dialogs };
+    }
+    case "input":
+    case "invalid": {
+      const top = s.dialogs.at(-1);
+      if (!top) return s;
+      let next: Dialog = top;
+      if (top.kind === "prompt")
+        next = a.type === "input" ? { ...top, value: a.value, error: null } : { ...top, error: a.error };
+      else if (top.kind === "save" && a.type === "invalid") next = { ...top, error: a.error };
+      return next === top ? s : { ...s, dialogs: [...s.dialogs.slice(0, -1), next] };
+    }
+    case "session":
+      return { ...s, session: { key: a.key }, role: null, milestone: null, armed: null };
+    case "role":
+      return { ...s, role: { run: a.run, dispatchId: a.dispatchId }, milestone: null, armed: null };
+    case "milestone":
+      return { ...s, milestone: { run: a.run, name: a.name }, role: null, armed: null };
+    case "up":
+      if (s.milestone) return { ...s, milestone: null, armed: null };
+      return s.role ? { ...s, role: null, armed: null } : { ...s, session: null, armed: null };
+    case "pause":
+      return { ...s, paused: !s.paused };
+    case "arm":
+      return { ...s, armed: { what: a.what, target: a.target, at: a.at } };
+    case "disarm":
+      return s.armed ? { ...s, armed: null } : s;
+  }
+}

package/src/entry/tui/stories.ts

@@ -0,0 +1,107 @@
+import type { ProfilePatch } from "../../domain/profile.ts";
+import type { CommandId } from "./commands.ts";
+import type { FixtureOptions } from "./fixtures.ts";
+import type { AppApi } from "./providers/app.tsx";
+import type { AppKeymap } from "./providers/keymap.tsx";
+import type { Action } from "./state.ts";
+
+/** One step towards a screen: a command as a key would run it, a reducer action, or a profile shown. */
+export type Step = { command: CommandId } | { action: Action } | { show: string } | { edit: ProfilePatch };
+
+export interface Story {
+  name: string;
+  title: string;
+  steps: Step[];
+  /** the fixtures the frame snapshots render it on (the storybook shows it on its one set) */
+  fixtures?: FixtureOptions;
+}
+
+const SHOWN: Step[] = [{ show: "default" }];
+const DIRTY: Step[] = [
+  ...SHOWN,
+  { edit: { budget: { usd: 5 }, roles: { verifier: { access: "read-only" } } } },
+];
+
+/**
+ * Every view and widget in a state worth seeing (spec §9.4 `CATHERD_STORY=1`): the storybook lists them
+ * and the frame snapshots render them at three sizes, in Unicode and plain.
+ */
+export const STORIES: Story[] = [
+  {
+    name: "status",
+    title: "Status: checks with fixes, profile, recent runs",
+    steps: [{ command: "tab.status" }],
+  },
+  { name: "profiles", title: "Profiles: the tree", steps: SHOWN },
+  { name: "profiles-dirty", title: "Profiles: two unsaved changes", steps: DIRTY },
+  {
+    name: "save",
+    title: "Save dialog: diff, agents, what applies when",
+    steps: [...DIRTY, { command: "profile.save" }],
+  },
+  { name: "quit", title: "Quit with unsaved changes", steps: [...DIRTY, { command: "app.quit" }] },
+  { name: "new-profile", title: "New profile prompt", steps: [{ command: "profile.new" }] },
+  { name: "profile-list", title: "Profile list", steps: [{ command: "profile.list" }] },
+  {
+    name: "palette",
+    title: "Command palette",
+    steps: [{ command: "tab.status" }, { command: "app.palette" }],
+  },
+  { name: "help", title: "Keyboard shortcuts", steps: [{ command: "tab.status" }, { command: "app.help" }] },
+  {
+    name: "runs-empty",
+    title: "Runs: no runs yet",
+    steps: [{ command: "tab.runs" }],
+    fixtures: { runs: [], sessions: [] },
+  },
+  { name: "runs", title: "Runs: the sessions", steps: [{ command: "tab.runs" }] },
+  {
+    name: "session",
+    title: "Runs: one session with two runs, one continued elsewhere",
+    steps: [{ command: "tab.runs" }, { action: { type: "session", key: "s-auth" } }],
+  },
+  {
+    name: "session-live",
+    title: "Runs: a live session with three live roles",
+    steps: [{ command: "tab.runs" }, { action: { type: "session", key: "s-jobs" } }],
+  },
+  {
+    name: "role",
+    title: "Runs: a role opened",
+    steps: [
+      { command: "tab.runs" },
+      { action: { type: "session", key: "s-jobs" } },
+      { action: { type: "role", run: "20260926-114800-jobs-screen", dispatchId: "d1" } },
+    ],
+  },
+  {
+    name: "milestone",
+    title: "Runs: a milestone opened on its digest",
+    steps: [
+      { command: "tab.runs" },
+      { action: { type: "session", key: "s-jobs" } },
+      { action: { type: "milestone", run: "20260926-114800-jobs-screen", name: "M0" } },
+    ],
+  },
+];
+
+/** One step, as a key or the reducer would take it. */
+export function applyStep(s: Step, app: AppApi, keymap: AppKeymap): void {
+  if ("command" in s) keymap.dispatchCommand(s.command);
+  else if ("action" in s) app.dispatch(s.action);
+  else if ("show" in s) app.dispatch({ type: "show", name: s.show, doc: app.effects.readProfile(s.show) });
+  else app.dispatch({ type: "edit", patch: s.edit });
+}
+
+/** Plays a story's steps, letting the app draw between them (a step may need the view the last one opened). */
+export async function playStory(
+  story: Story,
+  app: AppApi,
+  keymap: AppKeymap,
+  wait: () => Promise<void>,
+): Promise<void> {
+  for (const s of story.steps) {
+    applyStep(s, app, keymap);
+    await wait();
+  }
+}

package/src/entry/tui/text.ts

@@ -0,0 +1,130 @@
+/** Terminal columns a string takes (wide and zero-width characters counted as the terminal does). */
+export const width = (s: string): number => Bun.stringWidth(s);
+
+/** Cuts `s` at the end to `max` columns with an ellipsis; never in the middle (spec §9.3). */
+export function truncateEnd(s: string, max: number, plain = false): string {
+  if (max <= 0) return "";
+  if (width(s) <= max) return s;
+  const more = plain ? "..." : "…";
+  const room = max - width(more);
+  if (room <= 0) return more.slice(0, max);
+  let out = "";
+  for (const ch of s) {
+    if (width(out + ch) > room) break;
+    out += ch;
+  }
+  return out + more;
+}
+
+/** `1 change`, `2 changes`: a count with its noun, never `change(s)`. */
+export const plural = (n: number, noun: string): string => `${n} ${noun}${n === 1 ? "" : "s"}`;
+
+/** Pads with spaces to exactly `w` columns (truncating nothing: callers truncate first). */
+export const padEnd = (s: string, w: number): string => s + " ".repeat(Math.max(0, w - width(s)));
+
+/**
+ * Wraps to `max` columns without losing a character: breaks at spaces, and inside a word only when the
+ * word alone is wider than a line (ids, paths and commands wrap; spec §9.3).
+ */
+export function wrap(s: string, max: number): string[] {
+  if (max <= 0) return [s];
+  const lines: string[] = [];
+  let line = "";
+  const push = () => {
+    lines.push(line);
+    line = "";
+  };
+  for (const word of s.split(" ")) {
+    const candidate = line ? `${line} ${word}` : word;
+    if (width(candidate) <= max) {
+      line = candidate;
+      continue;
+    }
+    if (line) push();
+    let rest = word;
+    while (width(rest) > max) {
+      let head = "";
+      for (const ch of rest) {
+        if (head && width(head + ch) > max) break;
+        head += ch;
+      }
+      lines.push(head);
+      rest = rest.slice(head.length);
+    }
+    line = rest;
+  }
+  if (line || lines.length === 0) push();
+  return lines;
+}
+
+/**
+ * `wrap` with a hanging indent: a line's leading spaces and list marker (`- `, `* `, `1. `) are kept on its first
+ * line, and its continuation lines are indented to match, so a wrapped bullet does not read as a new line.
+ */
+export function wrapHanging(s: string, max: number): string[] {
+  const lead = /^\s*(?:[-*+] |\d+[.)] )?/.exec(s)?.[0] ?? "";
+  const hang = width(lead);
+  if (!lead || max - hang < 1) return wrap(s, max);
+  const pad = " ".repeat(hang);
+  return wrap(s.slice(lead.length), max - hang).map((l, i) => (i === 0 ? lead : pad) + l);
+}
+
+/** `04:12`, or `1:02:03` past an hour. */
+export function clock(secs: number): string {
+  const s = Math.max(0, Math.floor(secs));
+  const h = Math.floor(s / 3600);
+  const mm = String(Math.floor(s / 60) % 60).padStart(2, "0");
+  const ss = String(s % 60).padStart(2, "0");
+  return h > 0 ? `${h}:${mm}:${ss}` : `${mm}:${ss}`;
+}
+
+/** "just now", "12s ago", "4m ago", "2h ago", "3d ago". */
+export function ago(ms: number): string {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 2) return "just now";
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86_400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86_400)}d ago`;
+}
+
+/** `gpt-6-sol#medium` from `codex:gpt-6-sol#medium`: the backend goes, and a provider path keeps its last part. */
+export function shortRung(rung: string): string {
+  const noBackend = rung.slice(rung.indexOf(":") + 1);
+  return noBackend.slice(noBackend.lastIndexOf("/") + 1);
+}
+
+const ASCII: Record<string, string> = {
+  "—": "-",
+  "–": "-",
+  "·": "-",
+  "…": "...",
+  "⋯": "...",
+  "→": "->",
+  "←": "<-",
+  "↑": "^",
+  "↓": "v",
+  "●": "*",
+  "•": "*",
+  "◌": ".",
+  "✓": "+",
+  "✗": "x",
+  "▸": ">",
+  "▾": "v",
+  "┃": "|",
+  "─": "-",
+  "█": "#",
+  "░": ".",
+  "×": "x",
+  ω: "w",
+};
+
+/** `s` with every character outside printable ASCII replaced, for --plain (spec §9.3). */
+export function ascii(s: string): string {
+  let out = "";
+  for (const ch of s) {
+    const c = ch.codePointAt(0) ?? 0;
+    out += c >= 0x20 && c <= 0x7e ? ch : (ASCII[ch] ?? "?");
+  }
+  return out;
+}