howtofixcli 0.7.24 → 0.7.26

package/dist/workflow-progress.js

@@ -0,0 +1,446 @@
+/**
+ * The workflow progress surface: the live dock line and the two-pane
+ * "Phases | Agents" view.
+ *
+ * Ported from the reference implementations rather than invented. Two sources
+ * were read before this file was written:
+ *
+ *   1. Claude Code's documented progress view (code.claude.com/docs/en/workflows):
+ *      "The progress view shows each phase with its agent counts, token totals,
+ *      and elapsed time."; "Each call shows its state, such as still running or
+ *      failed."; past 25 agents or 1.5M projected tokens the progress line shows
+ *      a "Large workflow" warning.
+ *   2. `ultracode-workflows`' statusline (`scripts/workflow-statusline.mjs`),
+ *      which fixes the live-line shape: the run name, the phase plan, then
+ *      `●running ✓done <elapsed>`.
+ *
+ * Node conventions: the phase mark is the 1-based position, or
+ * a check once every agent in it is done; agent states are ○ queued / ● running
+ * / ✓ done / ✗ failed; the running agent is accented; each row is a left/right
+ * split with the metric right-aligned and clipped to the column budget.
+ *
+ * Everything here is a pure function of the run record, so the whole surface is
+ * testable without a session, a model or a terminal.
+ */
+import { truncateToWidth, visibleWidth } from "@netrodev/hxf-tui";
+import { fg, ink } from "./theme.js";
+const ROLE = {
+    text: ink.text,
+    muted: ink.mute,
+    dim: ink.dim,
+    accent: ink.accent,
+    success: ink.tool,
+    error: ink.bad,
+    border: ink.line,
+};
+/** Paint text in a semantic role. */
+const t = (role, text, bold = false) => (bold ? fg(text, ROLE[role], { bold: true }) : fg(text, ROLE[role]));
+/** The agent and token thresholds the reference uses for its size warning. */
+export const LARGE_AGENT_THRESHOLD = 25;
+export const LARGE_TOKEN_THRESHOLD = 1_500_000;
+/**
+ * How long a completed phase stays bright. Shorter than the entrance fade: this
+ * is a punctuation mark on a surface the user is already looking at, not an
+ * arrival.
+ */
+export const POP_MS = 420;
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+/** Format a duration the way the reference does: `42s` / `18m45s` / `2h15m`. */
+export function formatElapsed(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    if (hours > 0)
+        return `${hours}h${String(minutes).padStart(2, "0")}m`;
+    if (minutes > 0)
+        return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+    return `${seconds}s`;
+}
+/**
+ * A single-unit duration for a live clock: `12s`, `3m`, `2h`.
+ *
+ * The HUD shows this next to the spinner, where the value changes every second
+ * and the width must not jump: `formatElapsed` grew a field per unit
+ * (`1m05s` → `1h05m`), which shifts everything after it on the row as the run
+ * gets older. One unit keeps the clock three characters wide until a run passes
+ * ten hours, and the exact figure is still in `/stats` and the workflow panel.
+ */
+export function formatAge(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000));
+    if (total < 60)
+        return `${total}s`;
+    if (total < 3600)
+        return `${Math.floor(total / 60)}m`;
+    return `${Math.floor(total / 3600)}h`;
+}
+/** Compact token formatter: `940` / `1.7k` / `1.5M`. */
+export function formatTokens(count) {
+    if (count >= 1_000_000)
+        return `${(count / 1_000_000).toFixed(1)}M`;
+    if (count >= 1_000)
+        return `${(count / 1_000).toFixed(1)}k`;
+    return String(count);
+}
+// ---------------------------------------------------------------------------
+// Layout primitives (ported from the reference's layout module)
+// ---------------------------------------------------------------------------
+const clamp = (value, lo, hi) => Math.max(lo, Math.min(hi, value));
+/** Clip a string to an exact visible width, adding an ellipsis when truncated. */
+const clipEllipsis = (text, width) => (visibleWidth(text) > width ? truncateToWidth(text, Math.max(0, width), "…") : text);
+/** Pad (or truncate) to an EXACT visible width; ANSI-safe via visibleWidth. */
+export function padTo(text, width, align = "left") {
+    if (width <= 0)
+        return "";
+    const measured = visibleWidth(text);
+    if (measured > width)
+        return truncateToWidth(text, width);
+    const padding = " ".repeat(width - measured);
+    return align === "right" ? padding + text : text + padding;
+}
+/** Lay a left and right fragment on one line: right-aligned, left clipped. */
+export function splitRow(left, right, width, gap = 1) {
+    if (width <= 0)
+        return "";
+    const rightWidth = visibleWidth(right);
+    if (rightWidth >= width)
+        return truncateToWidth(right, width);
+    const leftMax = width - rightWidth - gap;
+    if (leftMax <= 0)
+        return padTo(right, width, "right");
+    const leftClipped = visibleWidth(left) > leftMax ? truncateToWidth(left, leftMax) : left;
+    const filler = " ".repeat(width - visibleWidth(leftClipped) - rightWidth);
+    return leftClipped + filler + right;
+}
+/** A titled box; every line is exactly `innerWidth + 4` columns. */
+export function box(title, rows, innerWidth) {
+    const label = clipEllipsis(title, Math.max(0, innerWidth - 2));
+    const dashes = Math.max(1, innerWidth - 1 - visibleWidth(label));
+    const top = t("border", "┌─ ") + t("accent", label) + t("border", ` ${"─".repeat(dashes)}┐`);
+    const bottom = t("border", `└${"─".repeat(innerWidth + 2)}┘`);
+    const bar = t("border", "│");
+    const body = rows.map((row) => `${bar} ${padTo(row, innerWidth)} ${bar}`);
+    return [top, ...body, bottom];
+}
+/** Two titled boxes side by side, forced to equal height. */
+export function twoPane(left, right, width, opts) {
+    const gap = opts?.gap ?? 1;
+    const leftWidth = opts?.leftWidth ?? clamp(Math.round(width * 0.38), 28, 44);
+    const rightWidth = width - leftWidth - gap;
+    const height = Math.max(left.rows.length, right.rows.length);
+    const pad = (rows) => {
+        const out = [...rows];
+        while (out.length < height)
+            out.push("");
+        return out;
+    };
+    const leftBox = box(left.title, pad(left.rows), leftWidth - 4);
+    const rightBox = box(right.title, pad(right.rows), rightWidth - 4);
+    const gapText = " ".repeat(gap);
+    return leftBox.map((line, index) => line + gapText + (rightBox[index] ?? padTo("", rightWidth)));
+}
+// ---------------------------------------------------------------------------
+// Icons (ported: position or check for a phase, lifecycle glyph per agent)
+// ---------------------------------------------------------------------------
+/** Glyph for an agent's lifecycle state, painted by role. */
+export function agentStateIcon(status, selected, active) {
+    switch (status) {
+        case "running":
+            return t(selected || active ? "accent" : "muted", "●");
+        case "failed":
+            return t("error", "✗");
+        default:
+            return t("success", "✓");
+    }
+}
+/** The phase mark: the 1-based position, or a check once the phase is done. */
+export function phaseMark(position, allDone, selected, now = Date.now(), finishedAt = 0) {
+    if (!allDone)
+        return t(selected ? "accent" : "dim", String(position));
+    // The check lands bright and settles: one frame of emphasis is what makes a
+    // completion readable in a pane the eye is not staring at.
+    return now - finishedAt < POP_MS ? t("success", "✓", true) : t("success", "✓");
+}
+/** The phase a step with no phase of its own is attributed to. */
+const UNPHASED = "Workflow";
+/**
+ * Group the run's steps by phase.
+ *
+ * Declared phases come first, in `meta` order, so the view reads as planned. A
+ * phase that only ever appeared on an agent is appended rather than dropped: the
+ * API contract warns that a mismatched title "silently produces an unplanned
+ * progress group", and hiding it would hide real work.
+ */
+export function groupPhases(progress, now = Date.now()) {
+    const titles = progress.phases.map((phase) => phase.title);
+    const details = new Map(progress.phases.map((phase) => [phase.title, phase.detail]));
+    for (const step of progress.steps) {
+        const title = step.phase || UNPHASED;
+        if (!titles.includes(title))
+            titles.push(title);
+    }
+    return titles.map((title, phaseIndex) => {
+        const agents = progress.steps.filter((step) => (step.phase || UNPHASED) === title).map((step) => ({ ...step, phaseIndex }));
+        const done = agents.filter((agent) => agent.status !== "running").length;
+        const failed = agents.filter((agent) => agent.status === "failed").length;
+        const elapsedMs = agents.reduce((longest, agent) => {
+            const end = agent.endedAt ?? now;
+            return Math.max(longest, end - agent.startedAt);
+        }, 0);
+        let anchor = -1;
+        for (let index = 0; index < agents.length; index++) {
+            const agent = agents[index];
+            if (agent.status !== "running")
+                continue;
+            if (anchor < 0 || agent.startedAt >= agents[anchor].startedAt)
+                anchor = index;
+        }
+        const detail = details.get(title);
+        const allDone = agents.length > 0 && done === agents.length && failed === 0;
+        // The moment the phase finished, which is when its last agent settled. The
+        // progress view uses it to mark a completion briefly; nothing else needs it.
+        const finishedAt = allDone ? agents.reduce((latest, agent) => Math.max(latest, agent.endedAt ?? 0), 0) : 0;
+        return {
+            title,
+            ...(detail ? { detail } : {}),
+            agents,
+            done,
+            failed,
+            outputTokens: agents.reduce((sum, agent) => sum + agent.outputTokens, 0),
+            elapsedMs,
+            allDone,
+            finishedAt,
+            anchor,
+        };
+    });
+}
+/** Total output tokens the run has spent. */
+export function totalTokens(progress) {
+    return progress.steps.reduce((sum, step) => sum + step.outputTokens, 0);
+}
+/** Total tool calls the run's agents made, when the backend reports them. */
+export function totalToolCalls(progress) {
+    return progress.steps.reduce((sum, step) => sum + (step.toolCalls ?? 0), 0);
+}
+/** Elapsed time of the run, live while it is still going. */
+export function runElapsedMs(progress, now = Date.now()) {
+    return Math.max(0, (progress.endedAt ?? now) - progress.startedAt);
+}
+/** Whether the run is big enough that the reference says to warn. */
+export function isLargeWorkflow(progress) {
+    return progress.steps.length > LARGE_AGENT_THRESHOLD || totalTokens(progress) > LARGE_TOKEN_THRESHOLD;
+}
+/** The phase to auto-follow: the one holding the most recent running agent. */
+export function activePhaseIndex(groups) {
+    if (groups.length === 0)
+        return 0;
+    const running = groups.map((group, index) => ({ group, index })).filter((entry) => entry.group.anchor >= 0);
+    if (running.length > 0) {
+        return running.reduce((best, entry) => {
+            const candidate = entry.group.agents[entry.group.anchor];
+            const current = best.group.agents[best.group.anchor];
+            return candidate.startedAt >= current.startedAt ? entry : best;
+        }).index;
+    }
+    for (let index = groups.length - 1; index >= 0; index--) {
+        if (groups[index].agents.length > 0)
+            return index;
+    }
+    return groups.length - 1;
+}
+// ---------------------------------------------------------------------------
+// The live line (the dock's activity row, under the input box)
+// ---------------------------------------------------------------------------
+/**
+ * The one-line live summary.
+ *
+ * Shaped after the reference's status line
+ * (`⚡ deep-code-review · Scope › Review › Verify · ●3 ✓2 1m04s`): the run name,
+ * the phase in flight, then agents, tokens and elapsed, with failures last so a
+ * long run cannot bury them.
+ */
+export function formatProgressLine(progress, now = Date.now()) {
+    const groups = groupPhases(progress, now);
+    const total = progress.steps.length;
+    const done = progress.steps.filter((step) => step.status !== "running").length;
+    const failed = progress.steps.filter((step) => step.status === "failed").length;
+    const parts = [progress.name];
+    const active = groups.find((group) => group.anchor >= 0);
+    if (active)
+        parts.push(`${active.title} ${active.done}/${active.agents.length}`);
+    else if (groups.length > 0)
+        parts.push(`${groups[groups.length - 1].title} done`);
+    parts.push(`${done}/${total} agents`);
+    parts.push(`${formatTokens(totalTokens(progress))} tok`);
+    parts.push(formatElapsed(runElapsedMs(progress, now)));
+    if (failed > 0)
+        parts.push(`${failed} failed`);
+    const line = parts.join(" · ");
+    return isLargeWorkflow(progress) ? `large workflow · ${line}` : line;
+}
+// ---------------------------------------------------------------------------
+// The two-pane view
+// ---------------------------------------------------------------------------
+const AGENT_WINDOW = 16;
+const PHASE_WINDOW = 12;
+const LABEL_CAP = 18;
+const FALLBACK_WIDTH = 72;
+const MIN_RIGHT_INNER = 24;
+/** Candidate metric strings for an agent, fullest first; the widest that fits wins. */
+function metricVariants(agent, now) {
+    if (agent.status === "running" && agent.outputTokens === 0) {
+        return [`idle ${formatElapsed(now - agent.startedAt)}`, "idle"];
+    }
+    const tokens = formatTokens(agent.outputTokens);
+    const tools = agent.toolCalls ?? 0;
+    const duration = formatElapsed((agent.endedAt ?? now) - agent.startedAt);
+    return [`${tokens} tok · ${tools} tools · ${duration}`, `${tokens} tok · ${tools} tools`, `${tokens} tok`];
+}
+/** Whether a metric paints dim (an agent that has produced nothing yet). */
+const isDimMetric = (agent) => agent.status === "running" && agent.outputTokens === 0;
+/** Window a list to keep `selected` visible, reserving a "…+K more" row. */
+function windowRows(items, selected, max) {
+    if (items.length <= max)
+        return { slice: items, start: 0, more: 0 };
+    const contentMax = Math.max(1, max - 1);
+    const start = clamp(selected - Math.floor(contentMax / 2), 0, items.length - contentMax);
+    const slice = items.slice(start, start + contentMax);
+    return { slice, start, more: items.length - slice.length };
+}
+/** One phase row: position mark, title, and the done/total count on the right. */
+function phaseRow(group, position, selected, innerWidth, now) {
+    const counts = `${group.done}/${group.agents.length}`;
+    const prefix = selected ? t("accent", "❯") : " ";
+    // A phase that has just finished is painted bright for a moment, so the
+    // change is visible without watching the counter: `justFinished` is the same
+    // fact the mark already encodes, animated.
+    const mark = phaseMark(position + 1, group.allDone, selected, now, group.finishedAt);
+    const budget = Math.max(0, innerWidth - 4 - visibleWidth(counts));
+    const title = visibleWidth(group.title) > budget ? truncateToWidth(group.title, budget, "…") : group.title;
+    const popping = group.allDone && now - group.finishedAt < POP_MS;
+    const body = popping && !selected ? t("success", title) : t(selected ? "accent" : "text", title);
+    const left = `${prefix}${mark} ${body}`;
+    const right = t(selected ? "accent" : "muted", counts);
+    return splitRow(left, right, innerWidth, 1);
+}
+/** One agent row: state glyph, label, and a right-aligned metric. */
+function agentRow(agent, selected, active, labelCol, innerWidth, now) {
+    const prefix = selected ? t("accent", "❯") : " ";
+    const icon = agentStateIcon(agent.status, selected, active);
+    const label = t(selected ? "accent" : "text", padTo(agent.label, labelCol));
+    const left = `${prefix}${icon} ${label}`;
+    const available = Math.max(0, innerWidth - visibleWidth(left) - 1);
+    const metric = metricVariants(agent, now).find((variant) => visibleWidth(variant) <= available) ?? "";
+    const right = t(selected ? "accent" : isDimMetric(agent) ? "dim" : "muted", metric);
+    return splitRow(left, right, innerWidth, 1);
+}
+/** Narrow-width fallback: a single-column phase/agent list. */
+function singleColumn(groups, width, selectedPhase, now) {
+    const lines = [];
+    groups.forEach((group, index) => {
+        const mark = phaseMark(index + 1, group.allDone, index === selectedPhase, now, group.finishedAt);
+        const head = `${mark} ${t(index === selectedPhase ? "accent" : "text", group.title)}` + `  ${t("muted", `${group.done}/${group.agents.length}`)}`;
+        lines.push(clipEllipsis(head, width));
+        const { slice, more } = windowRows(group.agents, 0, AGENT_WINDOW);
+        slice.forEach((agent, position) => {
+            const icon = agentStateIcon(agent.status, false, position === group.anchor);
+            const metric = metricVariants(agent, now)[0] ?? "";
+            lines.push(clipEllipsis(`  ${icon} ${t("text", agent.label)}  ${t("muted", metric)}`, width));
+        });
+        if (more > 0)
+            lines.push(clipEllipsis(`  ${t("dim", `…+${more} more`)}`, width));
+    });
+    return lines;
+}
+/**
+ * Render the two-pane view: a two-line header (name + totals, then the
+ * description), a left "Phases" box and a right box for the selected phase's
+ * agents, and an optional key hint. Falls back to a single column when the
+ * terminal is too narrow to align two boxes.
+ */
+export function renderWorkflowPanes(progress, width, opts) {
+    const now = opts?.now ?? Date.now();
+    const groups = groupPhases(progress, now);
+    const agents = progress.steps;
+    const done = agents.filter((step) => step.status !== "running").length;
+    const failed = agents.filter((step) => step.status === "failed").length;
+    const rightMeta = [`${done}/${agents.length} agents`, `${formatTokens(totalTokens(progress))} tok`, `${totalToolCalls(progress)} tools`, formatElapsed(runElapsedMs(progress, now)), ...(failed > 0 ? [`${failed} failed`] : [])].join(" · ");
+    const header = [splitRow(t("accent", progress.name, true), t("muted", rightMeta), width, 2), ...(progress.description ? [t("muted", clipEllipsis(progress.description, width))] : [])];
+    const footer = opts?.footer ? [t("muted", clipEllipsis(opts.footerText ?? progressFooter(), width))] : [];
+    if (groups.length === 0) {
+        return [...header, ...box("Phases", ["(no agents yet)"], Math.max(0, width - 4)), ...footer];
+    }
+    const selectedPhase = clamp(opts?.selectedPhase ?? activePhaseIndex(groups), 0, Math.max(0, groups.length - 1));
+    const leftWidth = clamp(Math.round(width * 0.38), 28, 44);
+    const rightInner = width - leftWidth - 1 - 4;
+    if (width < FALLBACK_WIDTH || rightInner < MIN_RIGHT_INNER) {
+        return [...header, ...singleColumn(groups, width, selectedPhase, now), ...footer];
+    }
+    const selected = groups[selectedPhase];
+    const { slice, start, more } = windowRows(groups, selectedPhase, PHASE_WINDOW);
+    const phaseRows = slice.map((group, index) => phaseRow(group, start + index, start + index === selectedPhase, leftWidth - 4, now));
+    if (more > 0)
+        phaseRows.push(t("dim", `…+${more} more`));
+    // The `f` filter narrows the agent pane, not the phase list: the phases are
+    // the run's shape and stay visible so the user keeps their bearings.
+    const shown = opts?.filter ? opts.filter(selected.agents) : selected.agents;
+    const labelCol = shown.length ? clamp(Math.max(...shown.map((agent) => visibleWidth(agent.label))), 6, LABEL_CAP) : 6;
+    const { slice: agentSlice, more: agentsMore } = windowRows(shown, 0, opts?.agentWindow ?? AGENT_WINDOW);
+    const agentRows = agentSlice.map((agent, index) => agentRow(agent, false, index === selected.anchor, labelCol, rightInner, now));
+    if (agentsMore > 0)
+        agentRows.push(t("dim", `…+${agentsMore} more`));
+    const body = twoPane({ title: "Phases", rows: phaseRows }, {
+        title: `${selected.title} · ${shown.length} agents${opts?.filterLabel ?? ""}`,
+        rows: agentRows,
+    }, width, { leftWidth, gap: 1 });
+    return [...header, ...body, ...footer];
+}
+/**
+ * The full view at a fixed width, as `string[]`.
+ *
+ * `expanded` names agents whose own detail (task list, last note) should be
+ * printed under the view — the reference's "Enter drill in". `selectedPhase`
+ * overrides auto-follow, which the interactive viewer needs and the frame
+ * renderer uses to pin a phase for the screenshot.
+ */
+export function formatProgressView(progress, expanded = [], width = 96, selectedPhase, opts) {
+    const lines = renderWorkflowPanes(progress, width, {
+        now: progress.endedAt ?? Date.now(),
+        footer: true,
+        ...(selectedPhase === undefined ? {} : { selectedPhase }),
+        ...(opts?.filter ? { filter: opts.filter } : {}),
+        ...(opts?.footerText ? { footerText: opts.footerText } : {}),
+        ...(opts?.filterLabel ? { filterLabel: opts.filterLabel } : {}),
+    });
+    const wanted = new Set(expanded);
+    // `drill` is the interactive "Enter drill in": with it, the selected phase's
+    // agents are expanded without the caller naming each one.
+    if (opts?.drill) {
+        const groups = groupPhases(progress, progress.endedAt ?? Date.now());
+        const selected = groups[Math.max(0, Math.min(groups.length - 1, selectedPhase ?? 0))];
+        for (const agent of selected?.agents ?? [])
+            wanted.add(agent.label);
+    }
+    if (wanted.size === 0)
+        return lines;
+    const extra = [];
+    for (const step of progress.steps) {
+        if (!wanted.has(step.label))
+            continue;
+        for (const task of step.tasks ?? []) {
+            const box = task.status === "completed" ? "[x]" : task.status === "in_progress" ? "[>]" : "[ ]";
+            extra.push(`  ${t("muted", box)} ${t("text", task.content)}`);
+        }
+        if (step.detail)
+            extra.push(`  ${t("dim", step.detail)}`);
+    }
+    if (extra.length === 0)
+        return lines;
+    return [...lines.slice(0, -1), ...extra, lines[lines.length - 1]];
+}
+/** The key hint under the view, mirroring the reference's key list. */
+export function progressFooter() {
+    return "↑/↓ phase · Enter drill in · Esc back out · f filter by status · p pause · x stop · s save script";
+}

package/dist/workflow-view.js

@@ -0,0 +1,195 @@
+/**
+ * The interactive half of the workflow panel: the key map and the view state.
+ *
+ * The panel prints a footer (`↑/↓ phase · Enter drill in · …`) advertising keys,
+ * so the keys have to be real. A footer that describes a different tool than the
+ * one on screen is a lie the user can see.
+ *
+ * Two design points are load-bearing:
+ *
+ * 1. **The keys are only live while the panel is pinned.** `p`, `x` and `s` are
+ *    ordinary characters; if they were always intercepted, typing "please" in
+ *    the editor would pause the run. The panel therefore owns the keyboard only
+ *    while it is on screen, and `Esc` gives the keyboard back.
+ * 2. **The decision is pure.** `workflowAction` maps raw terminal input to an
+ *    action and `applyView` mutates nothing, so the whole key map is testable
+ *    without a terminal, a session or a model.
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { matchesKey } from "@netrodev/hxf-tui";
+import { writeFileAtomicSync } from "./fs-atomic.js";
+export const WORKFLOW_FILTERS = ["all", "running", "failed", "done"];
+export function createWorkflowView() {
+    return { selectedPhase: 0, filter: "all", paused: false, expanded: false, follow: true };
+}
+/**
+ * Map raw terminal input to an action, or `undefined` to let the editor have it.
+ *
+ * Arrow keys are matched through the SDK's `matchesKey` so the kitty protocol and
+ * legacy escape sequences both work; the letters are matched as bare characters,
+ * which is what the terminal delivers for a plain key press.
+ */
+export function workflowAction(data) {
+    if (matchesKey(data, "up"))
+        return "up";
+    if (matchesKey(data, "down"))
+        return "down";
+    if (matchesKey(data, "enter"))
+        return "enter";
+    if (matchesKey(data, "escape"))
+        return "escape";
+    if (data === "f")
+        return "filter";
+    if (data === "p")
+        return "pause";
+    if (data === "x")
+        return "stop";
+    if (data === "s")
+        return "save";
+    return undefined;
+}
+/** Move the selected phase, clamped to the list. */
+export function movePhase(view, groups, delta) {
+    if (groups.length === 0)
+        return view;
+    const selected = Math.max(0, Math.min(groups.length - 1, view.selectedPhase + delta));
+    // Choosing a phase by hand is a statement of intent: stop following the run.
+    return { ...view, selectedPhase: selected, follow: false };
+}
+/** The next filter in the cycle. */
+export function nextFilter(current) {
+    const index = WORKFLOW_FILTERS.indexOf(current);
+    return WORKFLOW_FILTERS[(index + 1) % WORKFLOW_FILTERS.length];
+}
+/** Apply an action to the view. Pure: the caller assigns the result. */
+export function applyView(view, action, groups) {
+    switch (action) {
+        case "up":
+            return movePhase(view, groups, -1);
+        case "down":
+            return movePhase(view, groups, 1);
+        case "enter":
+            return { ...view, expanded: !view.expanded };
+        case "filter":
+            return { ...view, filter: nextFilter(view.filter) };
+        case "pause":
+            return { ...view, paused: !view.paused };
+        default:
+            // `escape`, `stop` and `save` are handled by the caller: they act on the
+            // run or the panel, not on the view.
+            return view;
+    }
+}
+/** Keep auto-follow on while the user has not chosen a phase. */
+export function follow(view, groups, active) {
+    return view.follow ? { ...view, selectedPhase: active } : view;
+}
+/** The agents to draw in the right pane, after the filter. */
+export function filterAgents(agents, filter) {
+    switch (filter) {
+        case "running":
+            return agents.filter((agent) => agent.status === "running");
+        case "failed":
+            return agents.filter((agent) => agent.status === "failed");
+        case "done":
+            return agents.filter((agent) => agent.status !== "running");
+        default:
+            return [...agents];
+    }
+}
+/** How the filter is named in the pane title. */
+export function filterLabel(filter) {
+    return filter === "all" ? "" : ` · ${filter}`;
+}
+/**
+ * The key that hands the panel the keyboard.
+ *
+ * The letters alone cannot do it: `p`, `x`, `s` and `f` are ordinary characters,
+ * and a pinned panel that swallowed them made the editor unusable — typing
+ * "Reply with a numbered list" lost the `p`, `s` and `f`, and Enter was eaten so
+ * the message could not even be sent. So the panel's keys are opt-in, and the
+ * footer says which mode it is in.
+ */
+export const WORKFLOW_KEY_TOGGLE = "ctrl+f";
+/**
+ * The key hint, reflecting what the keys will do right now.
+ *
+ * `x` is only offered while the run is live (stopping a finished run is
+ * meaningless), the pause hint says which way it will go, and while the panel
+ * does *not* hold the keyboard the only hint is how to give it the keyboard.
+ */
+export function viewFooter(view, running, keysActive = true) {
+    if (!keysActive)
+        return `Ctrl+F panel keys · Esc unpin`;
+    const parts = ["↑/↓ phase", view.expanded ? "Enter collapse" : "Enter drill in"];
+    parts.push(view.expanded ? "Esc back out" : "Esc unpin");
+    parts.push(`f filter${view.filter === "all" ? "" : ` (${view.filter})`}`);
+    if (running) {
+        parts.push(view.paused ? "p resume" : "p pause");
+        parts.push("x stop");
+    }
+    else if (view.paused) {
+        parts.push("p resume");
+    }
+    parts.push("s save script");
+    if (view.paused)
+        parts.unshift("paused");
+    return parts.join(" · ");
+}
+// ---------------------------------------------------------------------------
+// Saving the script behind a run
+// ---------------------------------------------------------------------------
+/**
+ * A filename safe to write into the workflows directory.
+ *
+ * The name comes from the script's own `meta.name`, which a model wrote, so it
+ * is untrusted: `../../etc/x` or an absolute path would otherwise escape the
+ * directory. Returns `undefined` for anything that cannot be a plain name.
+ */
+export function safeScriptName(name) {
+    const trimmed = name.trim();
+    if (!trimmed || trimmed.length > 64)
+        return undefined;
+    if (trimmed === "." || trimmed === "..")
+        return undefined;
+    // Letters, digits, dot, dash, underscore — and never a leading dot, so the
+    // file cannot be hidden or shadow a directory entry.
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed))
+        return undefined;
+    if (trimmed.includes(".."))
+        return undefined;
+    return trimmed;
+}
+/**
+ * Write a run's script into the workflows directory and return its path.
+ *
+ * Only `code` runs can be saved. A run started with `path` is already a file
+ * somewhere the user chose, so re-saving it would just make a second copy that
+ * can drift from the original.
+ *
+ * The name must be kept exactly as it was: the workflow tool refuses to run a
+ * script whose `meta.name` does not match its filename, so renaming on save
+ * would produce a file that cannot be run again.
+ */
+export function saveScript(script, dir) {
+    if (!script) {
+        return {
+            ok: false,
+            reason: "this run was started from a file, so it is already saved where you pointed the tool",
+        };
+    }
+    const safe = safeScriptName(script.name);
+    if (!safe) {
+        return { ok: false, reason: `"${script.name}" is not a usable filename, so the script was not written` };
+    }
+    const path = join(dir, `${safe}.js`);
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileAtomicSync(path, script.code);
+    }
+    catch (cause) {
+        return { ok: false, reason: cause instanceof Error ? cause.message : String(cause) };
+    }
+    return { ok: true, path };
+}