kritya 0.8.45-beta → 0.8.46-beta

package/dist/agent/systemPrompt.js

@@ -3,7 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { gitStatusShort } from "../git/git.js";
 import { buildSkillsSection, defaultExtraSkillRoots } from "./skills.js";
-import { artifactPath, loadProjectState, PHASE_COMMAND, PHASE_ORDER, PHASE_SUMMARY, } from "./workflow.js";
+import { artifactPath, BACK_COMMAND, DEFAULT_GATES, loadProjectState, PHASE_COMMAND, PHASE_ORDER, PHASE_SUMMARY, } from "./workflow.js";
 const MEMORY_FILES = ["KRITYA.md"];
 const MEMORY_MAX_CHARS = 4000;
 /**
@@ -103,13 +103,13 @@ You help with software engineering tasks: writing code, fixing bugs, explaining
 - You are rendering into a terminal: prefer bullets to tables, keep any table to 3 columns or fewer with short cells, and never use <br> or other HTML inside them.
 
 # Project workflow (new projects)
-When the user asks to create a NEW project or app (a FastAPI backend, a Next.js frontend, a CLI, etc.), do not jump straight to code. Run this ${PHASE_ORDER.length}-phase workflow, writing a durable artifact for each phase and STOPPING for the user's approval before advancing:
+When the user asks to create a NEW project or app (a FastAPI backend, a Next.js frontend, a CLI, etc.), do not jump straight to code. Run this ${PHASE_ORDER.length}-phase workflow, writing a durable artifact for each phase:
 ${PHASE_ORDER.map((p, i) => {
         const artifact = artifactPath("<name>", p) ?? "the application code";
         return `  ${i + 1}. ${p.padEnd(11)}-> ${artifact.padEnd(28)}(${PHASE_SUMMARY[p]})`;
     }).join("\n")}
 Each phase reads the artifact immediately before it and does not redo that phase's work: the spec owns requirements, contracts and numbered acceptance criteria; the plan owns architecture and the milestone order, citing criteria by number rather than restating them. Keep artifacts dense — every later phase pays to read them.
-Track state in .kritya/project.json ({ "name", "phase", "updatedAt" }): read it at the start of a turn to resume at the right phase, and update "phase" (with write_file) when you advance. After writing a phase's artifact, summarize it and ask the user to approve — never advance past a phase on your own. The user may also drive phases manually with ${PHASE_ORDER.map((p) => PHASE_COMMAND[p]).join(", ")}; when they do, that command sets the phase for you.
+Track state in .kritya/project.json ({ "name", "phase", "updatedAt" }): read it at the start of a turn to resume at the right phase, and update "phase" (with write_file) when you advance. Stop and ask the user to approve after ${DEFAULT_GATES.join(", ")} — those are the phases where changing course is still cheap. From build onward the run continues without asking, so carry straight on through the phases the command asked for. The user may also drive phases manually with ${PHASE_ORDER.map((p) => PHASE_COMMAND[p]).join(", ")}; when they do, that command sets the phase for you. If a finding cannot be fixed because the requirement or the design is wrong rather than the code, add a "revisit" field ({ "to": "spec" or "plan", "reason": "<one line>" }) instead of working around it, and tell the user to run ${BACK_COMMAND}.
 ${memory}${buildSkillsSection(workspace, defaultExtraSkillRoots(workspace, trustWorkspace), trustWorkspace)}
 # Environment
 - OS: ${os.platform()} (${os.release()})

package/dist/agent/workflow.js

@@ -7,7 +7,44 @@ export const PHASE_ORDER = [
     "build",
     "review",
     "fix",
+    "ship",
 ];
+/**
+ * Phases the workflow stops after, unless the user overrides it.
+ *
+ * Everything up to `plan` is cheap to redo and expensive to get wrong, so each
+ * one hands back to the user. From `build` on the money is already spent —
+ * stopping to ask "shall I now review what I just built?" adds a round trip
+ * without adding a decision, so those run through.
+ */
+export const DEFAULT_GATES = ["brainstorm", "spec", "plan"];
+/** 1-based position of `phase` in the workflow, for progress display. */
+export function phaseIndex(phase) {
+    return PHASE_ORDER.indexOf(phase) + 1;
+}
+/** Whether a run should hand back to the user after `phase`. */
+export function shouldStopAfter(phase, opts = {}) {
+    if (opts.until)
+        return phase === opts.until;
+    if (opts.auto)
+        return false;
+    return (opts.gates ?? DEFAULT_GATES).includes(phase);
+}
+/**
+ * The phases a run starting at `from` will actually execute, in order.
+ *
+ * Pure, so the gate policy is testable without running anything: this is the
+ * list the command layer walks.
+ */
+export function planRun(from, opts = {}) {
+    const run = [];
+    for (let phase = from; phase; phase = nextPhase(phase)) {
+        run.push(phase);
+        if (shouldStopAfter(phase, opts))
+            break;
+    }
+    return run;
+}
 /** The slash command that runs each phase, for user-facing guidance. */
 export const PHASE_COMMAND = {
     brainstorm: "/flow-brainstorm",
@@ -16,7 +53,14 @@ export const PHASE_COMMAND = {
     build: "/flow-build",
     review: "/flow-review",
     fix: "/flow-fix",
+    ship: "/flow-ship",
 };
+/**
+ * Rewind to a phase and re-run everything after it, for when a later phase
+ * turns out to be fixing the wrong requirement. Not a phase, so it is not in
+ * PHASE_ORDER — it is the loop back over it.
+ */
+export const BACK_COMMAND = "/flow-back";
 /** One-line summary of what each phase produces, for help text and the system prompt. */
 export const PHASE_SUMMARY = {
     brainstorm: "problem, users, MVP features, recommended stack",
@@ -25,6 +69,7 @@ export const PHASE_SUMMARY = {
     build: "the application code, with tests per acceptance criterion, written test-first",
     review: "spec-compliance, security, and reliability findings, with a scorecard up top",
     fix: "fixes for the review's findings, each re-verified",
+    ship: "a handover summary, the test suite actually run, and an optional commit",
 };
 /**
  * Word budget for each phase's artifact. These docs are read by every phase
@@ -37,7 +82,16 @@ const PHASE_WORD_CAP = {
     plan: 1000,
     review: 800,
     fix: 600,
+    ship: 500,
 };
+/**
+ * How many times a project may loop back before the workflow refuses.
+ *
+ * A loop is fix -> spec -> plan -> build -> review -> fix, so it is not free,
+ * and without a bound a disagreement the model cannot resolve on its own
+ * becomes an unbounded spend. Past this the user drives it by hand.
+ */
+export const MAX_REVISITS = 2;
 const STATE_REL = path.join(".kritya", "project.json");
 export function stateFile(workspace) {
     return path.join(workspace, STATE_REL);
@@ -103,22 +157,92 @@ export function loadProjectState(workspace) {
         const parsed = JSON.parse(fs.readFileSync(stateFile(workspace), "utf8"));
         if (!parsed || typeof parsed.name !== "string" || !isPhase(parsed.phase))
             return null;
-        return { name: parsed.name, phase: parsed.phase, updatedAt: parsed.updatedAt ?? "" };
+        const state = {
+            name: parsed.name,
+            phase: parsed.phase,
+            updatedAt: parsed.updatedAt ?? "",
+        };
+        // The agent writes this file itself when it runs autonomously, so anything
+        // malformed is treated as absent rather than allowed into the UI.
+        const raw = parsed.revisit;
+        if (raw && typeof raw === "object") {
+            const { to, reason } = raw;
+            if (isPhase(to) && typeof reason === "string")
+                state.revisit = { to, reason };
+        }
+        if (typeof parsed.revisits === "number" && Number.isFinite(parsed.revisits)) {
+            state.revisits = Math.max(0, Math.floor(parsed.revisits));
+        }
+        return state;
     }
     catch {
         return null;
     }
 }
-export function saveProjectState(workspace, name, phase) {
+export function saveProjectState(workspace, name, phase, carry) {
+    const previous = loadProjectState(workspace);
     const state = {
         name: slugify(name),
         phase,
         updatedAt: new Date().toISOString(),
     };
+    // Moving to a phase consumes any recorded revisit: the whole point of looping
+    // back is to act on it, and leaving it set would make the same suggestion
+    // fire again on the next pass. The counter survives, because it is what
+    // bounds the loop. A different project starts fresh — unless the caller is a
+    // rename, which is the same project under a new slug and hands its count in.
+    const revisits = previous && previous.name === state.name ? previous.revisits : carry?.revisits;
+    if (revisits)
+        state.revisits = revisits;
     fs.mkdirSync(path.dirname(stateFile(workspace)), { recursive: true });
     fs.writeFileSync(stateFile(workspace), JSON.stringify(state, null, 2) + "\n");
     return state;
 }
+/**
+ * Record that `phase` has to change before a finding can be fixed — the
+ * programmatic counterpart to the agent writing the same field with
+ * `write_file` during an autonomous run. Returns false when there is no
+ * active project, since there is nothing to attach the note to.
+ */
+export function markRevisit(workspace, to, reason) {
+    const state = loadProjectState(workspace);
+    if (!state)
+        return false;
+    const next = {
+        ...state,
+        revisit: { to, reason },
+        updatedAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(stateFile(workspace), JSON.stringify(next, null, 2) + "\n");
+    return true;
+}
+/** How many loop-backs this project has left before MAX_REVISITS is reached. */
+export function revisitsRemaining(workspace) {
+    return Math.max(0, MAX_REVISITS - (loadProjectState(workspace)?.revisits ?? 0));
+}
+/**
+ * Rewind to `to` and spend one of the project's loop-backs.
+ *
+ * Returns false when there is no project or the budget is spent — the caller
+ * reports that rather than looping anyway, which is what bounds the cycle.
+ * The recorded `revisit` is consumed here: acting on it is what it was for.
+ */
+export function takeRevisit(workspace, to) {
+    const state = loadProjectState(workspace);
+    if (!state)
+        return false;
+    const used = state.revisits ?? 0;
+    if (used >= MAX_REVISITS)
+        return false;
+    const next = {
+        name: state.name,
+        phase: to,
+        updatedAt: new Date().toISOString(),
+        revisits: used + 1,
+    };
+    fs.writeFileSync(stateFile(workspace), JSON.stringify(next, null, 2) + "\n");
+    return true;
+}
 /**
  * End the active workflow. The docs/<name>/ artifacts are left alone — only the
  * pointer goes, so the agent stops being told to resume a project the user has
@@ -166,7 +290,7 @@ export function renameProject(workspace, from, to) {
     catch (err) {
         return { ok: false, error: `Could not move docs/${current}/: ${err.message}` };
     }
-    saveProjectState(workspace, next, state.phase);
+    saveProjectState(workspace, next, state.phase, state);
     return { ok: true, name: next };
 }
 /** The phase before `phase` in PHASE_ORDER, or null for the first one. */
@@ -207,6 +331,21 @@ export function artifactExists(workspace, name, phase) {
  * and it would improvise the requirements instead.
  */
 export function phaseBlocker(workspace, name, phase) {
+    // Build writes code rather than a document, so the "did the previous phase
+    // leave its artifact behind" test passes for review trivially — and always.
+    // That let `/flow-review` run against a project that had never been built,
+    // dispatching subagents to review nothing. There is no file to look for, so
+    // fall back to the one piece of evidence there is: the recorded phase. Only
+    // consulted when there *is* a recorded phase, so a bare workspace behaves as
+    // before.
+    if (phase === "review") {
+        const recorded = loadProjectState(workspace)?.phase;
+        if (recorded && PHASE_ORDER.indexOf(recorded) < PHASE_ORDER.indexOf("build")) {
+            return (`The review phase checks what the build phase produced, and "${name}" has not ` +
+                `reached build yet (it is at ${recorded}). Run ${PHASE_COMMAND.build} first.`);
+        }
+        return null;
+    }
     const prev = previousPhase(phase);
     if (!prev || artifactExists(workspace, name, prev))
         return null;
@@ -315,7 +454,7 @@ function capLine(phase) {
  * the plan phase the belated write lands after plan mode has already been
  * turned off by the next command.
  */
-function approvalLine(phase, artifact) {
+function approvalLine(phase, artifact, stopAfter) {
     const next = nextPhase(phase);
     const write = artifact
         ? `Write ${artifact} BEFORE you ask for anything. Approval comes after the file exists — ` +
@@ -323,15 +462,22 @@ function approvalLine(phase, artifact) {
         : "";
     if (!next)
         return `${write}Finish by summarizing the findings for the user.`;
+    // An ungated phase is followed immediately by the next one in the same run,
+    // so asking for approval here would stall a stretch the user asked to run
+    // through — and the question would arrive after the next phase had started.
+    if (!stopAfter) {
+        return (`${write}Then summarize what you produced in a few lines and carry straight on into the ` +
+            `${next} phase (${PHASE_SUMMARY[next]}). Do not stop for approval.`);
+    }
     return (`${write}Then summarize what you produced in a few lines and ask the user to approve ` +
         `before the ${next} phase (they will run ${PHASE_COMMAND[next]}). Do not advance on your own.`);
 }
 /** The instruction sent to the agent to carry out a given phase. */
-export function phasePrompt(name, phase, userInput) {
+export function phasePrompt(name, phase, userInput, opts = {}) {
     const slug = slugify(name);
     const extra = userInput.trim() ? `\n\nUser input for this phase:\n${userInput.trim()}` : "";
     const cap = capLine(phase);
-    const approve = approvalLine(phase, artifactPath(name, phase));
+    const approve = approvalLine(phase, artifactPath(name, phase), opts.stopAfter ?? shouldStopAfter(phase));
     switch (phase) {
         case "brainstorm":
             return (`PROJECT WORKFLOW — BRAINSTORM phase for project "${slug}".\n` +
@@ -485,12 +631,41 @@ export function phasePrompt(name, phase, userInput) {
                 `verdict per finding — fixed, still open, or newly broken — in docs/${slug}/fix.md.\n` +
                 `If anything is still open after the subagent's check, say so plainly; do not report success ` +
                 `on a finding that didn't actually verify as fixed.\n` +
+                `If a finding cannot be fixed in code because the requirement itself is wrong — an ` +
+                `acceptance criterion that is ambiguous or contradicts another, a plan milestone that ` +
+                `does not survive contact with the code — do NOT work around it. Leave it open, say so ` +
+                `plainly, and record where it belongs by writing .kritya/project.json with a "revisit" ` +
+                `field alongside the existing keys: { "name": "${slug}", "phase": "fix", ` +
+                `"revisit": { "to": "spec", "reason": "<one line>" } }. Use "spec" when the ` +
+                `requirement is wrong and "plan" when the design is. That is what lets the user run ` +
+                `${BACK_COMMAND} to redo the phases that depend on it. Reserve this for findings that ` +
+                `genuinely belong upstream — everything else gets fixed here.\n` +
                 cap +
                 `Write docs/${slug}/fix.md BEFORE you ask for anything. Approval comes after the file ` +
                 `exists — never show the writeup in chat and ask whether to save it. Then summarize the ` +
-                `outcome in a few lines. If anything is still open, tell the user they can run ` +
-                `${PHASE_COMMAND.review} to re-check the whole build, or run ${PHASE_COMMAND.fix} again ` +
-                `once they've decided how to handle what's left.\n` +
+                `outcome in a few lines. If anything is still open, say so, and tell the user they can ` +
+                `run ${PHASE_COMMAND.review} to re-check the whole build, ${PHASE_COMMAND.fix} again ` +
+                `once they've decided how to handle what's left, or ${BACK_COMMAND} <phase> if the ` +
+                `finding belongs upstream. Otherwise they can run ${PHASE_COMMAND.ship} to finish.\n` +
+                extra);
+        case "ship":
+            return (`PROJECT WORKFLOW — SHIP phase for project "${slug}". Plan mode is OFF.\n` +
+                `Read docs/${slug}/spec.md, plan.md, review.md and fix.md. This is the handover, so it ` +
+                `has to be trustworthy rather than encouraging.\n` +
+                `First, actually run the project's test suite and report the real result — the exact ` +
+                `command you ran and what it printed. If there is no test suite, say that plainly ` +
+                `instead of implying one passed. A handover that claims success without running ` +
+                `anything is worse than no handover at all.\n` +
+                `Then write docs/${slug}/ship.md BEFORE you ask anything — approval comes after the ` +
+                `file exists, so never show the handover in chat and ask whether to save it. It should ` +
+                `cover: what was built and where the code lives, how to run ` +
+                `it and how to run its tests, which acceptance criteria from spec.md are met and which ` +
+                `are not, and every finding review.md raised that fix.md left open. Cite the AC, SEC ` +
+                `and REL labels rather than restating the requirements.\n` +
+                cap +
+                `Then summarize in a few lines and ask whether to commit. Do NOT commit, push or tag ` +
+                `anything until the user says yes — and when they do, use a conventional-commit message ` +
+                `describing the project, not the individual edits.\n` +
                 extra);
     }
 }

package/dist/commands/registry.js

@@ -10,15 +10,20 @@ import { scanPluginMcpServers } from "../plugins/mcp.js";
 import { listProviders } from "../config/config.js";
 import { expandCommand } from "./custom.js";
 import { recordCommandUse } from "../ui/recentCommands.js";
-import { artifactPath, clearProjectState, loadProjectState, parseIdea, parsePhase, phaseBlocker, phasePrompt, renameProject, staleArtifacts, PHASE_COMMAND, PHASE_ORDER, PHASE_SUMMARY, saveProjectState, slugify, } from "../agent/workflow.js";
+import { artifactExists, artifactPath, BACK_COMMAND, clearProjectState, DEFAULT_GATES, loadProjectState, MAX_REVISITS, nextPhase, parseIdea, parsePhase, phaseBlocker, phaseIndex, phasePrompt, planRun, renameProject, revisitsRemaining, saveProjectState, shouldStopAfter, staleArtifacts, takeRevisit, PHASE_COMMAND, PHASE_ORDER, PHASE_SUMMARY, slugify, } from "../agent/workflow.js";
 const WORKFLOW = "Workflow";
 const SESSION = "Session";
 const SAFETY = "Safety & limits";
 const INFO = "Info";
 export const BUILTIN_COMMANDS = [
+    {
+        name: "/flow",
+        description: "run the next workflow phase, or a stretch of them: /flow [--until <phase>|--auto]",
+        category: WORKFLOW,
+    },
     {
         name: "/flow-brainstorm",
-        description: "start a new-project workflow: /flow-brainstorm <idea> (brainstorm→spec→plan→build→review→fix)",
+        description: "start a new-project workflow: /flow-brainstorm <idea> (brainstorm→spec→plan→build→review→fix→ship)",
         category: WORKFLOW,
     },
     {
@@ -33,7 +38,7 @@ export const BUILTIN_COMMANDS = [
     },
     {
         name: "/flow-build",
-        description: "project workflow: implement the plan, with tests",
+        description: "project workflow: implement the plan, then review and fix it",
         category: WORKFLOW,
     },
     {
@@ -46,6 +51,16 @@ export const BUILTIN_COMMANDS = [
         description: "project workflow: fix the review's findings, re-verified",
         category: WORKFLOW,
     },
+    {
+        name: "/flow-ship",
+        description: "project workflow: run the tests and write the handover summary",
+        category: WORKFLOW,
+    },
+    {
+        name: "/flow-back",
+        description: "rewind to a phase and re-run everything after it, when a finding belongs upstream",
+        category: WORKFLOW,
+    },
     {
         name: "/project",
         description: "workflow status · /project goto <phase> · rename <name> · clear",
@@ -162,6 +177,10 @@ Also: @path/to/file attaches a file to your message (with autocomplete).
 @mcp:server/name attaches a document an MCP server offers.
 MCP servers can also contribute their own /server-prompt commands.
 Project memory: put standing instructions in KRITYA.md at your workspace root.
+Project workflow: /flow-brainstorm <idea> starts one; /flow runs the next phase.
+It stops for your approval after ${DEFAULT_GATES.join(", ")}, then runs the rest
+through to ship. --auto for no stops · --until <phase> to stop early · --fast to
+merge brainstorm and spec · ${BACK_COMMAND} <phase> when a finding belongs upstream.
 Keys: Esc cancels · Tab completes · Shift+Tab cycles normal/accept-edits/dry-run
 mode · ↑/↓ recalls history · Ctrl+R searches history · Ctrl+P opens the command
 palette · Ctrl+B copies the last code block · Ctrl+O toggles full tool output ·
@@ -170,7 +189,7 @@ Ctrl+K is the kill switch (stops everything until /kill off) · Ctrl+C exits`;
  * A phase boundary is the one place compaction is unambiguously safe: the
  * phase that just ended wrote its conclusions to a durable artifact on disk,
  * so the transcript that produced them is redundant. Compacting here is what
- * keeps a five-phase project from dragging every phase's exploration into the
+ * keeps a seven-phase project from dragging every phase's exploration into the
  * next phase's context window.
  */
 async function compactAtPhaseBoundary(ctx, phase) {
@@ -196,10 +215,48 @@ async function compactAtPhaseBoundary(ctx, phase) {
         ctx.setActivity(null);
     }
 }
-/** Strip a trailing/leading `--force` from a command argument. */
-function takeForce(arg) {
-    const force = /(^|\s)--force(\s|$)/.test(arg);
-    return { arg: arg.replace(/(^|\s)--force(\s|$)/, " ").trim(), force };
+/**
+ * Pull the workflow flags out of a command argument, leaving the user's own
+ * text behind. `--force` was the only one of these once, and it is still
+ * stripped before the prompt is built: it is an instruction to the command,
+ * not to the model, and leaving it in reads as part of the idea.
+ */
+function takeFlowFlags(arg) {
+    let rest = arg;
+    const take = (flag) => {
+        const re = new RegExp(`(^|\\s)${flag}(\\s|$)`);
+        if (!re.test(rest))
+            return false;
+        rest = rest.replace(re, " ");
+        return true;
+    };
+    const force = take("--force");
+    const auto = take("--auto");
+    // --fast merges brainstorm and spec into one stretch. They answer nearly the
+    // same question, and for a small project the second round trip buys nothing.
+    const fast = take("--fast");
+    const untilMatch = /(^|\s)--until[= ](\S+)/.exec(rest);
+    if (untilMatch) {
+        rest = rest.replace(/(^|\s)--until[= ]\S+/, " ");
+        const phase = parsePhase(untilMatch[2]);
+        if (!phase) {
+            return {
+                arg: rest.trim(),
+                force,
+                error: `Unknown phase "${untilMatch[2]}" for --until. Use one of: ${PHASE_ORDER.join(", ")}.`,
+            };
+        }
+        return { arg: rest.trim(), force, until: phase };
+    }
+    if (/(^|\s)--until(\s|$)/.test(rest)) {
+        return { arg: rest.trim(), force, error: "Usage: --until <phase>" };
+    }
+    if (auto)
+        return { arg: rest.trim(), force, auto: true };
+    if (fast) {
+        return { arg: rest.trim(), force, gates: DEFAULT_GATES.filter((p) => p !== "brainstorm") };
+    }
+    return { arg: rest.trim(), force };
 }
 /** Strip a trailing/leading `--default` from a command argument. */
 function takeDefault(arg) {
@@ -208,25 +265,29 @@ function takeDefault(arg) {
 }
 /**
  * Run one workflow phase: check its prerequisite artifact exists, set the mode
- * the phase needs, record the phase, compact, then hand the prompt to the agent.
+ * the phase needs, record the phase, compact, then hand the prompt to the
+ * agent.
+ *
+ * The outcome is what stops a chain. A blocked phase has written nothing, and
+ * an incomplete one has written something half-finished — either way everything
+ * after it reads an artifact that isn't there yet.
  */
-async function runPhase(ctx, phase) {
+async function runPhase(ctx, phase, run) {
     const project = loadProjectState(ctx.workspace);
     if (!project) {
         ctx.addItem({
             kind: "info",
             text: "No active project workflow. Start one with /flow-brainstorm <idea>.",
         });
-        return;
+        return "blocked";
     }
-    const { arg, force } = takeForce(ctx.arg);
     const blocker = phaseBlocker(ctx.workspace, project.name, phase);
-    if (blocker && !force) {
+    if (blocker && !run.force) {
         ctx.addItem({
             kind: "info",
             text: `${blocker}\nTo run ${PHASE_COMMAND[phase]} anyway: ${PHASE_COMMAND[phase]} --force`,
         });
-        return;
+        return "blocked";
     }
     // Warn (never block) if an earlier artifact was edited after this phase's
     // input was written from it — e.g. spec.md changed after plan.md already
@@ -256,13 +317,91 @@ async function runPhase(ctx, phase) {
         text: `${phase} phase for "${project.name}" — ${PHASE_SUMMARY[phase]}` +
             (artifact ? ` → ${artifact}` : "") +
             (wantPlanMode ? " (plan mode ON: read-only apart from that doc)" : "") +
-            (blocker && force ? "\n⚠ Forced past a missing prerequisite." : ""),
+            (blocker && run.force ? "\n⚠ Forced past a missing prerequisite." : ""),
     });
-    ctx.addItem({ kind: "user", text: ctx.raw.trim() });
     ctx.setRunningPhase(phase);
     ctx.refreshWorkflow();
     await compactAtPhaseBoundary(ctx, phase);
-    return ctx.runAgent(phasePrompt(project.name, phase, arg));
+    await ctx.runAgent(phasePrompt(project.name, phase, run.arg, { stopAfter: run.stopAfter }));
+    // A turn that runs out of steps just ends, and the message it appends reads
+    // like model output. The agent flags it, so a chain can tell "the phase
+    // finished" from "the phase gave up mid-sentence" — which matters because
+    // the next phase reads whatever it managed to write. Subagents already
+    // report this (`stoppedEarly: "max-steps"`); phases were treating a
+    // truncated run as a finished one.
+    if (ctx.agent.hitStepLimit)
+        return "incomplete";
+    return "ok";
+}
+/**
+ * Run a stretch of phases back to back from one command.
+ *
+ * `planRun` decides how far the stretch goes. Stopping between build, review
+ * and fix would ask "shall I now review what I just built?" — a round trip
+ * that buys no decision, because by then the work is already done. Stopping
+ * after brainstorm, spec and plan does buy one: those are cheap to redo and
+ * expensive to get wrong.
+ */
+async function runFlow(ctx, from, req) {
+    const phases = planRun(from, req);
+    const chained = phases.length > 1;
+    // One command, so one user line — not one per phase of the stretch.
+    ctx.addItem({ kind: "user", text: ctx.raw.trim() });
+    if (chained) {
+        ctx.addItem({ kind: "info", text: `Running ${phases.length} phases: ${phases.join(" → ")}` });
+        ctx.setChained(true);
+    }
+    try {
+        for (const [i, phase] of phases.entries()) {
+            const outcome = await runPhase(ctx, phase, {
+                arg: i === 0 ? req.arg : "",
+                force: req.force === true,
+                stopAfter: shouldStopAfter(phase, req),
+            });
+            if (outcome === "ok")
+                continue;
+            // A phase that did not finish stops the chain, because everything after
+            // it reads the artifact it did not (or only half) wrote. Say so: without
+            // this the run just goes quiet after the blocker message, and the user
+            // has to work out for themselves that phases they were promised never
+            // happened.
+            const abandoned = phases.slice(i + 1);
+            if (outcome === "incomplete") {
+                ctx.addItem({
+                    kind: "info",
+                    text: `${phase} stopped at the ${ctx.agent.maxSteps}-step limit before it finished, so ` +
+                        `whatever it wrote is incomplete — and the phases after it read that.` +
+                        (abandoned.length ? ` ${abandoned.join(", ")} did not run.` : "") +
+                        `\nSend "continue" to finish ${phase}, then /flow to carry on from there.`,
+                });
+            }
+            else if (abandoned.length) {
+                ctx.addItem({
+                    kind: "info",
+                    text: `Chain stopped at ${phase} — ${abandoned.join(", ")} did not run. ` +
+                        `Clear the blocker above, then /flow to carry on from here.`,
+                });
+            }
+            break;
+        }
+    }
+    finally {
+        // Only a chain ever sets this, so only a chain releases it — a single-phase
+        // command has nothing to suppress and should not touch the flag at all.
+        if (chained)
+            ctx.setChained(false);
+    }
+}
+/** The standard handler for a single phase command: /flow-spec, /flow-build, … */
+function phaseCommand(phase) {
+    return async (ctx) => {
+        const req = takeFlowFlags(ctx.arg);
+        if (req.error) {
+            ctx.addItem({ kind: "info", text: req.error });
+            return;
+        }
+        return runFlow(ctx, phase, req);
+    };
 }
 const handlers = {
     "/help": (ctx) => {
@@ -623,13 +762,20 @@ const handlers = {
             `the change.${trailerInstruction} Do not push. Show the final commit hash and message.`);
     },
     "/flow-brainstorm": async (ctx) => {
-        const input = ctx.arg.trim();
+        const req = takeFlowFlags(ctx.arg);
+        if (req.error) {
+            ctx.addItem({ kind: "info", text: req.error });
+            return;
+        }
+        const input = req.arg;
         const existing = loadProjectState(ctx.workspace);
         if (!existing && !input) {
             ctx.addItem({
                 kind: "info",
                 text: `Usage: /flow-brainstorm <your project idea>. Starts the ${PHASE_ORDER.join(" → ")} workflow.\n` +
-                    `Name it yourself with a short prefix: /flow-brainstorm reverser: a script that reverses a string`,
+                    `Name it yourself with a short prefix: /flow-brainstorm reverser: a script that reverses a string\n` +
+                    `Flags: --fast (run brainstorm and spec as one stretch) · --auto (no stops) · ` +
+                    `--until <phase> · --force`,
             });
             return;
         }
@@ -653,13 +799,117 @@ const handlers = {
             ctx.agent.planMode = false;
             ctx.setPlanMode(false);
         }
-        ctx.addItem({ kind: "user", text: ctx.raw.trim() });
-        ctx.setRunningPhase("brainstorm");
         ctx.refreshWorkflow();
-        // A no-op at the start of a session; earns its keep when a second project
-        // is started in a session that already ran one.
-        await compactAtPhaseBoundary(ctx, "brainstorm");
-        return ctx.runAgent(phasePrompt(name, "brainstorm", idea));
+        // The idea belongs to the brainstorm phase; later phases in a --fast stretch
+        // read its artifact rather than the raw idea again.
+        return runFlow(ctx, "brainstorm", { ...req, arg: idea });
+    },
+    "/flow": async (ctx) => {
+        const project = loadProjectState(ctx.workspace);
+        if (!project) {
+            ctx.addItem({
+                kind: "info",
+                text: "No active project workflow. Start one with /flow-brainstorm <idea>.",
+            });
+            return;
+        }
+        const req = takeFlowFlags(ctx.arg);
+        if (req.error) {
+            ctx.addItem({ kind: "info", text: req.error });
+            return;
+        }
+        // The stored phase is the one that last ran, so continuing means the next
+        // one — re-running what just finished is never what "continue" means.
+        const from = nextPhase(project.phase);
+        if (!from) {
+            ctx.addItem({
+                kind: "info",
+                text: `"${project.name}" has run every phase (last: ${project.phase}). ` +
+                    `Run /project clear to end the workflow, or ${BACK_COMMAND} <phase> to redo one.`,
+            });
+            return;
+        }
+        // A revisit the fix phase recorded means a finding was never really closed.
+        // Carrying on forward would run the rest of the workflow on top of a
+        // requirement that is known to be wrong, so name it here rather than let
+        // the user discover it by reading /project.
+        const revisit = project.revisit;
+        if (revisit && PHASE_ORDER.indexOf(revisit.to) < PHASE_ORDER.indexOf(from)) {
+            ctx.addItem({
+                kind: "info",
+                text: `↩ ${revisit.to} is still flagged as needing a change — ${revisit.reason}\n` +
+                    `Run ${BACK_COMMAND} to redo it and everything after, or carry on anyway with ` +
+                    `${PHASE_COMMAND[from]}.`,
+            });
+        }
+        return runFlow(ctx, from, req);
+    },
+    "/flow-back": async (ctx) => {
+        const project = loadProjectState(ctx.workspace);
+        if (!project) {
+            ctx.addItem({
+                kind: "info",
+                text: "No active project workflow. Start one with /flow-brainstorm <idea>.",
+            });
+            return;
+        }
+        const req = takeFlowFlags(ctx.arg);
+        if (req.error) {
+            ctx.addItem({ kind: "info", text: req.error });
+            return;
+        }
+        // Bare /flow-back acts on whatever the fix phase recorded; naming a phase
+        // works whether or not anything was recorded.
+        const recorded = project.revisit;
+        const target = parsePhase(req.arg) ?? recorded?.to ?? null;
+        if (!target) {
+            ctx.addItem({
+                kind: "info",
+                text: `Usage: ${BACK_COMMAND} <${PHASE_ORDER.join("|")}> — rewind to a phase and re-run everything after it.\n` +
+                    `Nothing upstream was recorded either, so name the phase you want to redo.`,
+            });
+            return;
+        }
+        if (PHASE_ORDER.indexOf(target) >= PHASE_ORDER.indexOf(project.phase)) {
+            ctx.addItem({
+                kind: "info",
+                text: `${BACK_COMMAND} rewinds, and ${target} is not before the current phase ` +
+                    `(${project.phase}). Use ${PHASE_COMMAND[target]} to move forward.`,
+            });
+            return;
+        }
+        if (revisitsRemaining(ctx.workspace) <= 0) {
+            ctx.addItem({
+                kind: "info",
+                text: `"${project.name}" has already looped back ${MAX_REVISITS} time(s), which is the limit — ` +
+                    `another automatic pass would be guessing at what you want. Fix what you can by hand, ` +
+                    `then /project goto ${target} and ${PHASE_COMMAND[target]} if you still want to redo it.`,
+            });
+            return;
+        }
+        if (!takeRevisit(ctx.workspace, target)) {
+            ctx.addItem({ kind: "info", text: `Could not rewind "${project.name}".` });
+            return;
+        }
+        ctx.addItem({
+            kind: "info",
+            text: `↩ Rewinding to ${target}` +
+                (recorded && recorded.to === target ? ` — ${recorded.reason}` : "") +
+                `. Everything after it re-runs, because it all reads what ${target} writes.`,
+        });
+        ctx.refreshWorkflow();
+        // Rewinding exists to regenerate what the wrong phase produced, and to put
+        // the user back where they were — not to carry on past it. So it stops at
+        // the phase the project had reached, unless the user asked for a longer or
+        // shorter run with --auto / --until.
+        //
+        // `arg` is blanked deliberately: it held the phase name the user typed
+        // (`/flow-back spec`), and passing it on would inject the literal string
+        // "spec" into the phase prompt as if it were user input.
+        const options = { ...req, arg: "" };
+        if (!req.auto && !req.until)
+            options.until = project.phase;
+        return runFlow(ctx, target, options);
     },
     // `/plan` (no `flow-` prefix) is pure plan-mode control — on/off or a bare
     // toggle — and never touches the project workflow. `/flow-plan` runs the
@@ -684,11 +934,12 @@ const handlers = {
                 : "Plan mode OFF — the agent can make changes again.",
         });
     },
-    "/flow-spec": (ctx) => runPhase(ctx, "spec"),
-    "/flow-plan": (ctx) => runPhase(ctx, "plan"),
-    "/flow-build": (ctx) => runPhase(ctx, "build"),
-    "/flow-review": (ctx) => runPhase(ctx, "review"),
-    "/flow-fix": (ctx) => runPhase(ctx, "fix"),
+    "/flow-spec": phaseCommand("spec"),
+    "/flow-plan": phaseCommand("plan"),
+    "/flow-build": phaseCommand("build"),
+    "/flow-review": phaseCommand("review"),
+    "/flow-fix": phaseCommand("fix"),
+    "/flow-ship": phaseCommand("ship"),
     "/project": (ctx) => {
         const [sub = "", ...rest] = ctx.arg.trim().split(/\s+/);
         const project = loadProjectState(ctx.workspace);
@@ -735,25 +986,34 @@ const handlers = {
             ctx.refreshWorkflow();
             ctx.addItem({
                 kind: "info",
-                text: `"${project.name}" set to the ${target} phase. Run ${PHASE_COMMAND[target]} to start it.`,
+                text: `"${project.name}" set to the ${target} phase. Run ${PHASE_COMMAND[target]} to start it, or /flow to continue from here.`,
             });
             return;
         }
-        const lines = PHASE_ORDER.map((p) => {
+        const lines = PHASE_ORDER.map((p, i) => {
             const marker = p === project.phase ? "*" : " ";
             const artifact = artifactPath(project.name, p);
-            return `  ${marker} ${p.padEnd(11)}${PHASE_SUMMARY[p]}\n      ${artifact ?? "(application code)"}`;
+            // build has no document of its own, so there is nothing to look for.
+            const written = artifact !== null && artifactExists(ctx.workspace, project.name, p);
+            return (`  ${marker} ${String(i + 1).padStart(2)}. ${p.padEnd(11)}${PHASE_SUMMARY[p]}` +
+                `\n         ${artifact ?? "(application code)"}${written ? "  ✓" : ""}`);
         });
         const stale = staleArtifacts(ctx.workspace, project.name, project.phase);
         const staleBlock = stale.length ? `\n\n${stale.join("\n")}` : "";
+        const revisitBlock = project.revisit
+            ? `\n\n↩ ${project.revisit.to} was flagged as needing a change: ${project.revisit.reason}` +
+                `\n   ${BACK_COMMAND} redoes it and everything after it.`
+            : "";
         ctx.addItem({
             kind: "info",
-            text: `Project "${project.name}" — ${project.phase} phase` +
+            text: `Project "${project.name}" — ${project.phase} phase ` +
+                `(${phaseIndex(project.phase)}/${PHASE_ORDER.length})` +
                 (project.updatedAt ? ` (since ${project.updatedAt.slice(0, 10)})` : "") +
                 `\n\n${lines.join("\n")}` +
                 staleBlock +
-                `\n\nRun ${PHASE_COMMAND[project.phase]} to continue · /project goto <phase> to move · ` +
-                `/project rename <name> · /project clear to end the workflow.`,
+                revisitBlock +
+                `\n\n/flow continues · ${PHASE_COMMAND[project.phase]} re-runs this phase · ` +
+                `/project goto <phase> to move · /project rename <name> · /project clear to end the workflow.`,
         });
     },
     "/diff": (ctx) => {

package/dist/headless.js

@@ -25,6 +25,20 @@ import { gatedContentHash, isTrusted } from "./trust/trust.js";
 import { partitionByTrust, serverFingerprint, trustServer } from "./trust/mcpTrust.js";
 import { installCrashHandlers } from "./crash.js";
 import { defaultSandboxMode } from "./shell/sandbox.js";
+/**
+ * Whether a `--prompt` value looks like a slash command.
+ *
+ * Slash commands are dispatched by the interactive UI, which owns the command
+ * layer; headless mode has none, so a `/flow-brainstorm ...` prompt was handed
+ * to the model as literal text. The model then improvised the workflow from the
+ * system prompt — which looks like it worked and does not: no gate stops, no
+ * per-phase modes, no artifact bookkeeping, and it runs until it hits the step
+ * limit. Exported so the check itself is testable without spawning a process
+ * (the e2e suite that would otherwise cover it needs a real CLI run).
+ */
+export function isSlashCommandPrompt(prompt) {
+    return prompt.trimStart().startsWith("/");
+}
 function emit(args, r) {
     if (args.output === "json") {
         console.log(JSON.stringify(r));
@@ -65,6 +79,20 @@ function approveHeadlessMcp(servers, trust, source) {
 export async function runHeadless(args) {
     const startedAt = Date.now();
     const workspace = path.resolve(args.dir);
+    // Refuse rather than silently do something else. See isSlashCommandPrompt.
+    if (isSlashCommandPrompt(args.prompt)) {
+        return finish(args, startedAt, {
+            success: false,
+            result: "",
+            error: `--prompt starts with "/", which is a slash command. Headless mode does not run ` +
+                `slash commands — it sends the text to the model, which would improvise the task ` +
+                `instead of following the command. Run the command in the interactive UI, or ` +
+                `describe the task in plain language here.`,
+            toolCalls: [],
+            usage: { promptTokens: 0, completionTokens: 0, cachedPromptTokens: 0, estimated: false },
+            durationMs: 0,
+        });
+    }
     // Only the user's own global .env is unconditionally trusted; see below.
     loadDotEnv([path.join(CONFIG_DIR, ".env")]);
     // There's no terminal to show the interactive trust prompt, so headless

package/dist/ui/App.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { Box, Static, Text, useApp, useBoxMetrics, useInput, useStderr, useWindowSize, } from "ink";
 import fs from "node:fs";
 import { glob } from "tinyglobby";
@@ -28,6 +28,7 @@ import { StreamViewport } from "./StreamViewport.js";
 import { TextInput } from "./TextInput.js";
 import { TranscriptItem } from "./TranscriptItem.js";
 import { terminalColumns, terminalRows } from "./viewport.js";
+import { fitRow, listRows, ROW_GUTTER, ROW_SEPARATOR, windowList } from "./windowList.js";
 import { BUILTIN_COMMANDS, runCommand } from "../commands/registry.js";
 import { mcpPrompts, mcpResources } from "../mcp/client.js";
 import { useAgent } from "./useAgent.js";
@@ -147,7 +148,7 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
             .catch(() => { });
     }, [workspace]);
     useEffect(refreshFileList, [refreshFileList]);
-    const { items, addItem, clearItems, phase, setPhase, stream, thinking, activity, setActivity, runningPhase, setRunningPhase, workflow, refreshWorkflow, permission, elicitation, inFlight, model, provider, servedModel, totalUsage, totalCost, tasks, setTasks, ctxPct, setCtxPct, tokenBudget, budgetPct, budgetUsed, budgetStopped, resetBudget, setBudgetLimit, branch, planMode, setPlanMode, dryRunMode, killed, killReason, engageKill, releaseKill, acceptEdits, setAcceptEdits, bypassMode, setBypassMode, autoApprovedCount, cycleMode, onAcceptEditsConfirm, onBypassModeConfirm, abortRef, setModelEverywhere, setProviderEverywhere, costReport, runAgent, runWebSearch, onPermissionDecision, onElicitationDecision, onResumeSelect, requestPermission, requestElicitation, persistenceWarningCount, } = useAgent({
+    const { items, addItem, clearItems, phase, setPhase, stream, thinking, activity, setActivity, runningPhase, setRunningPhase, setChained, workflow, refreshWorkflow, permission, elicitation, inFlight, model, provider, servedModel, totalUsage, totalCost, tasks, setTasks, ctxPct, setCtxPct, tokenBudget, budgetPct, budgetUsed, budgetStopped, resetBudget, setBudgetLimit, branch, planMode, setPlanMode, dryRunMode, killed, killReason, engageKill, releaseKill, acceptEdits, setAcceptEdits, bypassMode, setBypassMode, autoApprovedCount, cycleMode, onAcceptEditsConfirm, onBypassModeConfirm, abortRef, setModelEverywhere, setProviderEverywhere, costReport, runAgent, runWebSearch, onPermissionDecision, onElicitationDecision, onResumeSelect, requestPermission, requestElicitation, persistenceWarningCount, } = useAgent({
         agent,
         workspace,
         modelRef,
@@ -226,6 +227,37 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
         ? allCommands.filter((c) => c.name.startsWith(input.trim()))
         : [];
     const selectedCmd = suggestions.length ? Math.min(cmdIndex, suggestions.length - 1) : 0;
+    /**
+     * The suggestion list flattened to rendered lines, so a group heading costs
+     * a row like any other — windowing the commands alone would still let the
+     * headings push real rows off the bottom of the screen.
+     *
+     * `lineOfCmd[i]` is the line `suggestions[i]` landed on. The cursor indexes
+     * commands, because that is what the arrow keys move through; this is what
+     * maps it onto a line.
+     */
+    const suggestionLines = [];
+    const lineOfCmd = [];
+    {
+        // Group headers only earn their keep once more than one category is
+        // actually on screen — once typing has filtered down to a single family,
+        // a lone header is just noise.
+        const showHeaders = new Set(suggestions.map((c) => c.category)).size > 1;
+        let lastCategory;
+        for (const c of suggestions) {
+            if (showHeaders && c.category !== lastCategory) {
+                suggestionLines.push({ kind: "header", label: c.category ?? "Other" });
+                lastCategory = c.category;
+            }
+            lineOfCmd.push(suggestionLines.length);
+            suggestionLines.push({ kind: "cmd", cmd: c });
+        }
+    }
+    // The transcript above is static; this reserves the prompt box, the hint
+    // line and the status line, which is what has to stay visible.
+    const suggestionWindow = windowList(suggestionLines, lineOfCmd[selectedCmd] ?? 0, listRows(rows, 8));
+    // The list is indented by its own paddingLeft, then by the row's marker.
+    const suggestionRowWidth = contentWidth - 2 - ROW_GUTTER;
     // File suggestions while typing an @mention.
     const mentionMatch = phase === "input" && !input.startsWith("/") ? MENTION_RE.exec(input) : null;
     const mentionFragment = mentionMatch ? mentionMatch[2].toLowerCase() : null;
@@ -503,6 +535,7 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
             setPhase,
             setActivity,
             setRunningPhase,
+            setChained,
             refreshWorkflow,
             setCtxPct,
             setTasks,
@@ -685,18 +718,18 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
                                     setInput(v.replace(/\t/g, ""));
                                     setCmdIndex(0);
                                     setFileIndex(0);
-                                }, onSubmit: handleSubmit }, inputKey)] }), suggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [(() => {
-                                // Group headers only earn their keep once more than one
-                                // category is actually on screen — once typing has filtered
-                                // down to a single family, a lone header is just noise.
-                                const showHeaders = new Set(suggestions.map((c) => c.category)).size > 1;
-                                let lastCategory;
-                                return suggestions.map((c, i) => {
-                                    const showHeader = showHeaders && c.category !== lastCategory;
-                                    lastCategory = c.category;
-                                    return (_jsxs(Fragment, { children: [showHeader && _jsx(Text, { dimColor: true, children: c.category ?? "Other" }), _jsxs(Text, { color: i === selectedCmd ? "cyan" : undefined, children: [i === selectedCmd ? "❯ " : "  ", _jsx(Text, { bold: i === selectedCmd, children: c.name }), _jsxs(Text, { dimColor: true, children: [" \u2014 ", c.description] })] })] }, c.name));
-                                });
-                            })(), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter select \u00B7 Enter again to run" })] })), fileSuggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [fileSuggestions.map((f, i) => (_jsxs(Text, { color: i === selectedFile ? "cyan" : undefined, children: [i === selectedFile ? "❯ " : "  ", f] }, f))), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter attach file" })] }))] })), _jsx(Box, { children: _jsx(StatusLine, { killed: killed, killReason: killReason, dryRunMode: dryRunMode, planMode: planMode, acceptEdits: acceptEdits, bypassMode: bypassMode, autoApprovedCount: autoApprovedCount, provider: provider, model: servedModel && servedModel !== model
+                                }, onSubmit: handleSubmit }, inputKey)] }), suggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [suggestionWindow.visible.map((line, i) => {
+                                if (line.kind === "header") {
+                                    return (_jsx(Text, { dimColor: true, wrap: "truncate", children: line.label }, `header:${line.label}`));
+                                }
+                                const c = line.cmd;
+                                const selected = i === suggestionWindow.cursor;
+                                const row = fitRow(c.name, c.description, suggestionRowWidth);
+                                return (_jsxs(Text, { color: selected ? "cyan" : undefined, wrap: "truncate", children: [selected ? "❯ " : "  ", _jsx(Text, { bold: selected, children: row.label }), row.hint ? (_jsxs(Text, { dimColor: true, children: [ROW_SEPARATOR, row.hint] })) : null] }, c.name));
+                            }), suggestionWindow.clipped ? (_jsxs(Text, { dimColor: true, children: ["  ", suggestionWindow.from, "\u2013", suggestionWindow.to, " of ", suggestionWindow.total, " \u00B7 \u2191\u2193 to scroll"] })) : null, _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter insert \u00B7 Esc cancel" })] })), phase === "input" &&
+                        input.startsWith("/") &&
+                        !input.includes(" ") &&
+                        suggestions.length === 0 && (_jsx(Box, { paddingLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["no command matches ", input.trim(), " \u00B7 Esc to clear"] }) })), fileSuggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [fileSuggestions.map((f, i) => (_jsxs(Text, { color: i === selectedFile ? "cyan" : undefined, wrap: "truncate", children: [i === selectedFile ? "❯ " : "  ", f] }, f))), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter attach file" })] }))] })), _jsx(Box, { children: _jsx(StatusLine, { killed: killed, killReason: killReason, dryRunMode: dryRunMode, planMode: planMode, acceptEdits: acceptEdits, bypassMode: bypassMode, autoApprovedCount: autoApprovedCount, provider: provider, model: servedModel && servedModel !== model
                         ? `${model}-${modelDisplaySlug(servedModel)}`
                         : model, workflow: workflow, branch: branch, budgetPct: budgetPct, budgetStopped: budgetStopped, totalCost: totalCost, sandboxActive: (config.sandboxExec ?? defaultSandboxMode()) !== "off" && sandboxAvailable(), persistenceWarningCount: persistenceWarningCount, privacyMode: privacyMode }) })] }));
 }

package/dist/ui/SelectList.js

@@ -1,10 +1,33 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
-import { Box, Text, useInput } from "ink";
-export function SelectList({ items, onSelect, onCancel, }) {
+import { Box, Text, useInput, useWindowSize } from "ink";
+import { terminalColumns, terminalRows } from "./viewport.js";
+import { fitRow, listRows, ROW_GUTTER, ROW_SEPARATOR, windowList } from "./windowList.js";
+/**
+ * The list every picker in the app renders through — the Ctrl+P palette, the
+ * model picker, the permission and trust prompts, the elicitation prompt, and
+ * session resume.
+ *
+ * It measures the terminal itself and windows to fit, so all of those inherit
+ * scrolling and row truncation without passing anything: a list longer than
+ * the screen scrolls with the cursor kept in view, and a long row is cut
+ * instead of wrapping onto a second line. `width`/`maxRows` are there for a
+ * caller that knows its own layout better than the terminal size suggests.
+ */
+export function SelectList({ items, onSelect, onCancel, width, maxRows, reservedRows, }) {
     const [rawIndex, setIndex] = useState(0);
+    const windowSize = useWindowSize();
+    const rows = maxRows ??
+        (reservedRows === undefined
+            ? listRows(terminalRows(windowSize))
+            : listRows(terminalRows(windowSize), reservedRows));
+    // A row also spends ROW_GUTTER columns on its selection marker, and the
+    // border/padding the caller wrapped us in is not ours to know — so leave a
+    // couple of columns of slack rather than assume the terminal's full width.
+    const rowWidth = (width ?? terminalColumns(windowSize) - 4) - ROW_GUTTER;
     // Items can shrink under us (e.g. a live filter above the list).
     const index = items.length ? Math.min(rawIndex, items.length - 1) : 0;
+    const list = windowList(items, index, rows);
     useInput((_input, key) => {
         if (!items.length) {
             if (key.escape && onCancel)
@@ -20,5 +43,8 @@ export function SelectList({ items, onSelect, onCancel, }) {
         else if (key.escape && onCancel)
             onCancel();
     });
-    return (_jsx(Box, { flexDirection: "column", children: items.map((item, i) => (_jsxs(Text, { color: i === index ? "green" : undefined, children: [i === index ? "❯ " : "  ", item.label, item.hint ? _jsxs(Text, { dimColor: true, children: [" \u2014 ", item.hint] }) : null] }, item.value))) }));
+    return (_jsxs(Box, { flexDirection: "column", children: [list.visible.map((item, i) => {
+                const row = fitRow(item.label, item.hint, rowWidth);
+                return (_jsxs(Text, { color: i === list.cursor ? "green" : undefined, wrap: "truncate", children: [i === list.cursor ? "❯ " : "  ", row.label, row.hint ? (_jsxs(Text, { dimColor: true, children: [ROW_SEPARATOR, row.hint] })) : null] }, item.value));
+            }), list.clipped ? (_jsxs(Text, { dimColor: true, children: ["  ", list.from, "\u2013", list.to, " of ", list.total, " \u00B7 \u2191\u2193 to scroll"] })) : null] }));
 }

package/dist/ui/StatusLine.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from "ink";
+import { PHASE_ORDER, phaseIndex } from "../agent/workflow.js";
 import { displayModelId } from "../config/models.js";
 /**
  * The single dim status bar pinned to the bottom of the screen. Keeps only
@@ -17,5 +18,5 @@ export function StatusLine({ killed, killReason, dryRunMode, planMode, acceptEdi
                                 ? "plan"
                                 : acceptEdits
                                     ? `accept-edits (${autoApprovedCount} auto)`
-                                    : "default", " · "] }), displayModelId(provider, model), _jsxs(Text, { color: sandboxActive ? "green" : "red", children: [" ", "\u00B7 ", sandboxActive ? "🔒 sandbox:active" : "🔓 sandbox:inactive"] }), workflow ? (_jsxs(Text, { color: "magenta", children: [" ", "\u00B7 \u2691 ", workflow.name, ":", workflow.phase] })) : (""), branch ? ` · ⎇ ${branch}` : "", budgetStopped || budgetPct >= 80 ? (_jsxs(Text, { color: budgetStopped ? "red" : "yellow", children: [" \u00B7 budget ", budgetPct, "%"] })) : (""), totalCost > 0 ? ` · $${totalCost.toFixed(4)}` : "", persistenceWarningCount > 0 ? (_jsxs(Text, { color: "yellow", children: [" \u00B7 \u26A0 persistence warnings: ", persistenceWarningCount] })) : (""), privacyMode ? _jsx(Text, { color: "cyan", children: " \u00B7 privacy:on" }) : "", " · /diff review · /undo revert · Ctrl+K stop · /status for details"] }));
+                                    : "default", " · "] }), displayModelId(provider, model), _jsxs(Text, { color: sandboxActive ? "green" : "red", children: [" ", "\u00B7 ", sandboxActive ? "🔒 sandbox:active" : "🔓 sandbox:inactive"] }), workflow ? (_jsxs(Text, { color: "magenta", children: [" ", "\u00B7 \u2691 ", workflow.name, " ", phaseIndex(workflow.phase), "/", PHASE_ORDER.length, " ", workflow.phase] })) : (""), branch ? ` · ⎇ ${branch}` : "", budgetStopped || budgetPct >= 80 ? (_jsxs(Text, { color: budgetStopped ? "red" : "yellow", children: [" \u00B7 budget ", budgetPct, "%"] })) : (""), totalCost > 0 ? ` · $${totalCost.toFixed(4)}` : "", persistenceWarningCount > 0 ? (_jsxs(Text, { color: "yellow", children: [" \u00B7 \u26A0 persistence warnings: ", persistenceWarningCount] })) : (""), privacyMode ? _jsx(Text, { color: "cyan", children: " \u00B7 privacy:on" }) : "", " · /diff review · /undo revert · Ctrl+K stop · /status for details"] }));
 }

package/dist/ui/useAgent.js

@@ -103,6 +103,15 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
         runningPhaseRef.current = p;
         setRunningPhaseState(p);
     }, []);
+    /**
+     * True while one command is running several phases back to back. A ref, not
+     * state: the teardown reads it in the same tick the command is still inside,
+     * and nothing renders from it.
+     */
+    const chainedRef = useRef(false);
+    const setChained = useCallback((chained) => {
+        chainedRef.current = chained;
+    }, []);
     /** The active project workflow, for the statusline. Persists between turns. */
     const [workflow, setWorkflow] = useState(() => loadProjectState(workspace));
     const [permission, setPermission] = useState(null);
@@ -400,6 +409,10 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
         setRunningPhase(null);
         if (!ran)
             return;
+        // A chain runs the next phase itself, so naming the command to type would
+        // point at work that is already starting. The chain prints its own plan.
+        if (chainedRef.current)
+            return;
         // Prefer the phase on disk: an autonomous turn may have advanced it past
         // whatever the command started.
         const current = loadProjectState(workspace)?.phase ?? ran;
@@ -407,7 +420,7 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
         addItem({
             kind: "info",
             text: next
-                ? `✓ ${current} phase done — next: ${PHASE_COMMAND[next]} (or /project to review where you are)`
+                ? `✓ ${current} phase done — next: ${PHASE_COMMAND[next]} or /flow (or /project to review where you are)`
                 : `✓ ${current} phase done — the workflow is complete. /project clear ends it.`,
         });
     }, [workspace, addItem, setRunningPhase]);
@@ -606,6 +619,7 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
         setActivity,
         runningPhase,
         setRunningPhase,
+        setChained,
         workflow,
         refreshWorkflow,
         permission,

package/dist/ui/windowList.js

@@ -0,0 +1,100 @@
+import stringWidth from "string-width";
+import { truncateToWidth } from "./inline.js";
+/**
+ * Windowing and width-fitting for every list in the UI: the Ctrl+P palette,
+ * the inline `/` suggestions, the history search, the model picker, and the
+ * permission/trust prompts. They were each written separately and each one
+ * grew its own way of not fitting on screen — some wrapped a long row onto a
+ * second line, and the long ones (a bare `/` is 33 commands plus group
+ * headings) simply ran off the bottom of the terminal with no way to scroll.
+ *
+ * Kept pure and React-free so the arithmetic is testable on its own, and so
+ * the renderers only have to decide what a row looks like, never how much of
+ * it fits.
+ */
+/** Columns the selection marker (`"❯ "` / `"  "`) occupies at the start of a row. */
+export const ROW_GUTTER = 2;
+/** What sits between a row's label and its hint. */
+export const ROW_SEPARATOR = " — ";
+/**
+ * The label keeps at least this many columns before a hint is allowed any
+ * space — below it the label alone is more use than a two-letter stub plus a
+ * truncated hint.
+ */
+const MIN_LABEL = 8;
+/** Under this a hint is dropped outright rather than squeezed to a stub. */
+const MIN_HINT = 8;
+/** Chrome a list should leave alone by default: prompt box, hints, status line. */
+const DEFAULT_RESERVED_ROWS = 10;
+/**
+ * Rows a list may occupy: the terminal, less the chrome around it.
+ *
+ * The floor is deliberately low rather than generous — a very short terminal
+ * should still show a usable list instead of collapsing to nothing, and the
+ * caller can always pass an explicit `maxRows` when it knows its own layout.
+ */
+export function listRows(terminalRows, reserved = DEFAULT_RESERVED_ROWS) {
+    return Math.max(3, Math.floor(terminalRows) - Math.max(0, Math.floor(reserved)));
+}
+/**
+ * The slice of `items` to render, plus where the cursor sits inside it.
+ *
+ * The window is centred on the cursor and then clamped to the ends, which
+ * makes it a pure function of the cursor — there is no scroll offset to carry
+ * between renders, so a list can never get stuck scrolled away from the row
+ * it is highlighting. Centring also means moving within the first page does
+ * not shift the list at all, and the last row is reachable without the window
+ * running off the bottom.
+ */
+export function windowList(items, cursor, maxRows) {
+    const total = items.length;
+    const rows = Math.max(1, Math.floor(maxRows));
+    if (total === 0) {
+        return { visible: [], cursor: 0, from: 0, to: 0, total: 0, clipped: false };
+    }
+    // `cursor` can be stale — items shrink under a live filter — so clamp it
+    // rather than trust it, exactly like the renderers used to do by hand.
+    const at = Math.min(Math.max(Math.floor(cursor), 0), total - 1);
+    const offset = Math.min(Math.max(at - Math.floor(rows / 2), 0), Math.max(0, total - rows));
+    const visible = items.slice(offset, offset + rows);
+    return {
+        visible,
+        cursor: at - offset,
+        from: offset + 1,
+        to: offset + visible.length,
+        total,
+        clipped: visible.length < total,
+    };
+}
+/**
+ * Fit one row into `width` display columns, cutting the *hint* before the
+ * label: the label is what identifies the row, so a long description must
+ * never be the reason a command's name is unreadable. When there is no room
+ * for both, the hint goes entirely.
+ *
+ * `width` is what is left after the gutter, and may be unknown (-1, or 0 from
+ * a terminal that has not reported a size yet) — in which case the row is
+ * returned untouched and the renderer's `wrap="truncate"` backstop takes over.
+ */
+export function fitRow(label, hint, width) {
+    if (width <= 0)
+        return { label, hint };
+    if (!hint)
+        return { label: truncateToWidth(label, width), hint: undefined };
+    const sepWidth = stringWidth(ROW_SEPARATOR);
+    const labelWidth = stringWidth(label);
+    if (width < MIN_LABEL + sepWidth + MIN_HINT) {
+        return { label: truncateToWidth(label, width), hint: undefined };
+    }
+    if (labelWidth + sepWidth + MIN_HINT <= width) {
+        return { label, hint: truncateToWidth(hint, width - labelWidth - sepWidth) };
+    }
+    // The label itself has to give ground, but never below MIN_LABEL's worth of
+    // room for the hint to be worth showing at all.
+    const fittedLabel = truncateToWidth(label, width - sepWidth - MIN_HINT);
+    const rest = width - stringWidth(fittedLabel) - sepWidth;
+    return {
+        label: fittedLabel,
+        hint: rest >= MIN_HINT ? truncateToWidth(hint, rest) : undefined,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kritya",
-  "version": "0.8.45-beta",
+  "version": "0.8.46-beta",
   "description": "Kritya — Superintelligence at your command line",
   "type": "module",
   "publishConfig": {