premanmcp 1.1.5 → 1.1.7

package/bin/agent.js

@@ -0,0 +1,2043 @@
+/**
+ * `preman` — the PreMan agent, in a terminal session.
+ *
+ * The agent already exists and already has every PreMan tool: it is the one
+ * behind the workbench chat. What it did not have was a terminal. A developer
+ * who lives in a shell had to open the app, or drive PreMan indirectly through
+ * another vendor's coding agent over MCP, to ask it anything.
+ *
+ * So this is the workbench conversation rendered for a terminal, over the SSE
+ * contract that surface already speaks
+ * (`POST /workbench/conversations/{id}/messages/stream`). Nothing about the
+ * agent, its tools, or its approval rules lives here — this module only turns
+ * `status`/`artifact`/`delta`/`done` events into lines and reads lines back.
+ * A capability added to chat shows up here on its next reply with no change.
+ *
+ * Two deliberate consequences of it being *the same conversation*:
+ *   - It is durable and shared with the app. `/app` opens the very session you
+ *     are typing into, and work started here is visible there.
+ *   - Cancelling stops this renderer, not the turn. The server has no idea a
+ *     reader walked away, so we say that rather than claiming an abort.
+ */
+
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { createSseParser } from "./runner.js";
+import {
+  authenticateTerminal,
+  backendUrl,
+  callBackendJson,
+  cliInvocation,
+  describeFailure,
+  frontendUrl,
+  hasKeyAvailable,
+  makeArgs,
+  openUrl,
+  packageVersion,
+  resolveApiKey,
+  truncate,
+} from "./shared.js";
+
+export const AGENT_HELP = `
+Agent session options:
+  --continue            Resume your most recent conversation
+  --conversation <id>   Resume one conversation by id
+  --workspace <id>      Workspace to work in. Defaults to your primary workspace
+  --print               Send the message given on the command line, then exit
+  --no-color            Disable ANSI colour
+`;
+
+const SLASH_HELP = `Commands:
+  /help                 Show this list
+  /new                  Start a fresh conversation
+  /conversations        List recent conversations
+  /resume <id>          Switch to another conversation
+  /eval                 Measure your agent against the behaviours you turned on
+  /eval list            Everything measurable, and what is switched on
+  /eval on|off <what>   Switch behaviours on or off, by number or by id
+  /eval defaults        Pick a few that suit this project, and switch them on
+  /eval doctor          Check this machine can run evals before starting one
+  /app                  Open this conversation in the PreMan app
+  /clear                Clear the screen
+  /exit                 Leave (Ctrl+D does the same)
+
+Anything else you type goes to the PreMan agent.`;
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const FRAME_MS = 80;
+
+// Something to watch between pressing enter and the first word of an answer.
+// The server only sends `status` once it has work to name, which can be a
+// while, and an empty terminal in that gap reads as a session that has hung.
+const THINKING = [
+  "locking in",
+  "testing",
+  "on it",
+  "thinking",
+  "digging in",
+  "wiring up",
+  "reading along",
+];
+const THINK_MS = 220;
+const CLEAR_LINE = "\r\u001b[2K";
+const CLEAR_SCREEN = "\u001b[2J\u001b[H";
+
+// The alternate screen buffer: what makes a session a place rather than a
+// stretch of shell output. Entering gives it a screen of its own, so a second
+// `preman` cannot be scrolled back into the first; leaving hands back the
+// screen the shell had, untouched, the way `vim` and `htop` do.
+const ENTER_ALT = "\u001b[?1049h";
+const LEAVE_ALT = "\u001b[?1049l";
+const SHOW_CURSOR = "\u001b[?25h";
+const RELEASE_REGION = "\u001b[r";
+
+// How long a first Ctrl+C stays armed. Long enough to be a deliberate second
+// press, short enough that one an hour ago cannot quit the session.
+const QUIT_WINDOW_MS = 2000;
+
+// The mark -- the PreMan "P", its bowl a closed ring with the figure standing
+// in the counter -- and the width it needs. Traced from the brand asset the
+// dashboard ships (PreMan-Dashboard/public/preman-logo-mark.png) rather than
+// drawn by eye: the PNG is cropped to its ink and resampled to a half-block
+// mosaic, two square pixels stacked per cell, which is the one glyph family
+// that keeps the logo's aspect honest in a terminal cell. Twelve columns is
+// the smallest size at which the ring still closes and the head stays clear
+// of the stem; below it the counter fills in and the figure reads as a smudge.
+//
+// Still far narrower than the window, so the session's own details sit beside
+// the mark rather than below a banner nobody reads twice. A terminal too
+// narrow even for this gets the plain bold name.
+const LOGO = [
+  "  \u2584\u2588\u2588\u2588\u2588\u2588\u2588\u2584",
+  "\u2584\u2588\u2588\u2580    \u2580\u2588\u2588\u2584",
+  "\u2588\u2588   \u2588\u2588   \u2588\u2588",
+  "\u2588\u2588   \u2580\u2580  \u2584\u2588\u2588",
+  "\u2588\u2588 \u2584\u2588  \u2584\u2588\u2588\u2588",
+  "\u2588\u2588 \u2588\u2588  \u2580\u2580",
+  "\u2588\u2588 \u2588\u2588",
+  "\u2588\u2588 \u2588\u2588",
+];
+const LOGO_WIDTH = 12;
+
+// The docked composer, held at the bottom of the window while the transcript
+// scrolls above it: the input line boxed between two rules, then the status
+// strip. The lower rule is what separates what you are typing from the state
+// underneath it, rather than letting the two run together.
+const DOCK_ROWS = 4;
+
+// What the terminal calls the agent it is talking to. The server decides which
+// provider actually answers, so this is a product name, not a model id.
+const MODEL_NAME = "PreMan Dawg 1.0";
+
+// The tab name. Without this an editor's terminal list labels the session by
+// its foreground process, which is `node` -- true, and useless next to three
+// other tabs running the same binary. OSC 0 sets both icon and window title;
+// clearing it on the way out hands naming back to the shell.
+const TITLE = "preman";
+const SET_TITLE = `\u001b]0;${TITLE}\u0007`;
+const CLEAR_TITLE = "\u001b]0;\u0007";
+
+// Flags that consume the token after them, so a positional message is not
+// mistaken for a flag value (`preman "check /users" --workspace abc`).
+const VALUE_FLAGS = new Set([
+  "--backend",
+  "--frontend",
+  "--api-key",
+  "--key",
+  "--workspace",
+  "--conversation",
+]);
+
+/** The words that were not flags — the one-shot message, if there is one. */
+export function positionals(raw = []) {
+  const out = [];
+  for (let i = 0; i < raw.length; i += 1) {
+    const token = String(raw[i]);
+    if (token.startsWith("-")) {
+      if (VALUE_FLAGS.has(token)) i += 1;
+      continue;
+    }
+    out.push(token);
+  }
+  return out;
+}
+
+/** `/resume abc` -> {name: "resume", rest: "abc"}; anything else -> null. */
+export function parseSlash(line) {
+  const text = String(line || "").trim();
+  if (!text.startsWith("/")) return null;
+  const [word, ...rest] = text.slice(1).split(/\s+/);
+  return { name: word.toLowerCase(), rest: rest.join(" ").trim() };
+}
+
+// `llm` is the provider footer the app renders in a corner, and `intents` are
+// replay steps for an editor this surface does not have. Both are noise in a
+// transcript; note intents are surfaced separately because they carry words.
+const SILENT_ARTIFACTS = new Set(["llm", "intents"]);
+
+const ARTIFACT_LABELS = {
+  endpoints: "Endpoints",
+  hosted_mcp: "Hosted MCP",
+  connect_link: "Connect",
+  handoff: "Task queued",
+  report: "Test results",
+  test_report: "Test results",
+  stress_report: "Stress results",
+  test_scenarios: "Scenarios",
+  test_campaign: "Campaign",
+  agent_brief: "Investigation brief",
+  prd_document: "Document",
+  needs_api_key: "Action needed",
+  members: "Team",
+};
+
+function artifactUrl(artifact) {
+  for (const key of ["url", "manage_url", "install_url", "app_url"]) {
+    const value = artifact[key];
+    if (typeof value === "string" && /^https?:\/\//.test(value)) return value;
+  }
+  return "";
+}
+
+/**
+ * One line for a card the app would draw.
+ *
+ * Returns "" for anything this surface deliberately does not show, so callers
+ * filter on the return value rather than repeating the skip rules.
+ */
+export function artifactLine(artifact) {
+  if (!artifact || typeof artifact !== "object") return "";
+  const type = String(artifact.type || "");
+  if (!type || SILENT_ARTIFACTS.has(type)) return "";
+  const label =
+    String(artifact.title || "").trim() || ARTIFACT_LABELS[type] || type.replace(/_/g, " ");
+  const url = artifactUrl(artifact);
+  return url ? `${truncate(label, 72)} — ${url}` : truncate(label, 100);
+}
+
+/** The permission questions in a finished turn, in the order they were asked. */
+export function permissionQuestions(artifacts = []) {
+  return (Array.isArray(artifacts) ? artifacts : []).filter(
+    (item) =>
+      item &&
+      item.type === "permission_question" &&
+      Array.isArray(item.options) &&
+      item.options.length
+  );
+}
+
+function colourEnabled(args) {
+  if (args.has("--no-color") || args.has("--no-colour")) return false;
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return Boolean(process.stdout.isTTY);
+}
+
+function makePaint(enabled) {
+  const wrap = (code) => (text) =>
+    enabled ? `\u001b[${code}m${text}\u001b[0m` : String(text);
+  return {
+    green: wrap("32"),
+    red: wrap("31"),
+    yellow: wrap("33"),
+    cyan: wrap("36"),
+    white: wrap("97"),
+    caret: wrap("1;97"),
+    // The band a submitted message sits on, so a glance separates what was
+    // asked from what came back. A background rather than a colour, because
+    // the text is the customer's own words and recolouring those makes them
+    // look like output from something. 256-colour: a terminal without it drops
+    // the band and prints the line plainly, which is the old behaviour rather
+    // than a broken one.
+    band: wrap("48;5;236"),
+    lime: wrap("92"),
+    dim: wrap("2"),
+    bold: wrap("1"),
+  };
+}
+
+/**
+ * The live transcript for one turn.
+ *
+ * Tool activity is a spinner on a single rewritten line, because a turn that
+ * runs eight tools would otherwise leave eight stale "Running…" lines in the
+ * scrollback above an answer that made them all irrelevant. Everything that
+ * outlives the turn — cards, the reply — is printed normally and scrolls.
+ */
+export function createRenderer({ stream = process.stdout, paint, live } = {}) {
+  const isLive = live ?? Boolean(stream.isTTY);
+  const ink = paint || makePaint(isLive);
+  let timer = null;
+  let frame = 0;
+  let label = "";
+  let stall = null;
+  let stallWord = 0;
+  let stallTick = 0;
+  let wroteReply = false;
+  let atLineStart = true;
+
+  function stopStall() {
+    if (!stall) return false;
+    clearInterval(stall);
+    stall = null;
+    return true;
+  }
+
+  function clearSpinner() {
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+    const stalled = stopStall();
+    if (isLive && (label || stalled)) stream.write(CLEAR_LINE);
+    label = "";
+  }
+
+  /**
+   * The stall animation: a word whose last letter runs on, then trailing dots.
+   * Both lengths move on every tick so it reads as something in progress
+   * rather than a frozen string, and the word itself changes every few beats.
+   */
+  function drawStall() {
+    if (!isLive) return;
+    const word = THINKING[stallWord % THINKING.length];
+    const last = word.slice(-1);
+    const runOn = last.repeat(2 + (stallTick % 3));
+    const dots = ".".repeat(1 + ((stallTick + 1) % 3));
+    stallTick += 1;
+    if (stallTick % 9 === 0) stallWord += 1;
+    const tint = ink.lime || ink.green;
+    stream.write(`${CLEAR_LINE}${tint(`${word}${runOn} ${dots}`)}`);
+  }
+
+  function draw() {
+    if (!isLive || !label) return;
+    const spin = FRAMES[frame % FRAMES.length];
+    frame += 1;
+    const room = Math.max(20, (stream.columns || 80) - 4);
+    stream.write(`${CLEAR_LINE}${ink.cyan(spin)} ${ink.dim(truncate(label, room))}`);
+  }
+
+  return {
+    /** Start stalling. Called on submit, before the stream says anything. */
+    thinking() {
+      if (!isLive || stall || timer || label) return;
+      drawStall();
+      stall = setInterval(drawStall, THINK_MS);
+      stall.unref?.();
+    },
+    status(text) {
+      const next = String(text || "").trim();
+      if (!next) return;
+      if (!isLive) {
+        // Piped output keeps every step: it is usually a log somebody reads
+        // after the fact, where the sequence is the whole value.
+        stream.write(`${ink.dim(`... ${next}`)}\n`);
+        return;
+      }
+      // A named step is better than a guess, so it replaces the stall.
+      if (stopStall()) stream.write(CLEAR_LINE);
+      label = next;
+      draw();
+      if (!timer) {
+        timer = setInterval(draw, FRAME_MS);
+        timer.unref?.();
+      }
+    },
+    artifact(item) {
+      const line = artifactLine(item);
+      if (!line) return;
+      clearSpinner();
+      if (!atLineStart) stream.write("\n");
+      stream.write(`  ${ink.cyan("●")} ${line}\n`);
+      atLineStart = true;
+    },
+    delta(text) {
+      const chunk = String(text ?? "");
+      if (!chunk) return;
+      clearSpinner();
+      if (!wroteReply) {
+        stream.write("\n");
+        wroteReply = true;
+      }
+      stream.write(chunk);
+      atLineStart = chunk.endsWith("\n");
+    },
+    /** Print the persisted reply when the provider never streamed one. */
+    fallback(text) {
+      if (wroteReply) return;
+      const body = String(text || "").trim();
+      if (!body) return;
+      this.delta(body);
+    },
+    note(text) {
+      clearSpinner();
+      if (!atLineStart) stream.write("\n");
+      stream.write(`${ink.dim(String(text))}\n`);
+      atLineStart = true;
+    },
+    error(text) {
+      clearSpinner();
+      if (!atLineStart) stream.write("\n");
+      stream.write(`${ink.red(String(text))}\n`);
+      atLineStart = true;
+    },
+    end() {
+      clearSpinner();
+      if (!atLineStart) stream.write("\n");
+      if (wroteReply) stream.write("\n");
+      atLineStart = true;
+      wroteReply = false;
+    },
+  };
+}
+
+async function backendCall(args, method, route, options) {
+  const result = await callBackendJson(args, method, route, options);
+  if (!result.ok) throw new Error(describeFailure(result, `${method} ${route} failed`));
+  return result;
+}
+
+/**
+ * Stream one turn, handing every SSE payload to `onEvent`.
+ *
+ * The request is abandoned by signal rather than by dropping the reader, so a
+ * cancelled turn does not leave a half-read response holding the socket open.
+ */
+export async function streamTurn({
+  backend,
+  token,
+  workspaceId,
+  conversationId,
+  content,
+  signal,
+  onEvent,
+}) {
+  const url = new URL(
+    `workbench/conversations/${encodeURIComponent(conversationId)}/messages/stream`,
+    `${backend}/`
+  );
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "text/event-stream",
+    Authorization: `Bearer ${token}`,
+  };
+  if (workspaceId) headers["x-workspace-id"] = workspaceId;
+
+  const resp = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ content, surface: "chat" }),
+    signal,
+  });
+
+  if (!resp.ok || !resp.body) {
+    const text = await resp.text().catch(() => "");
+    let detail = text;
+    try {
+      detail = describeFailure(JSON.parse(text), text);
+    } catch {
+      // Not JSON -- an upstream proxy page, most likely. Show what arrived.
+    }
+    throw new Error(`${resp.status} ${truncate(detail || "chat stream failed", 300)}`);
+  }
+
+  const push = createSseParser((_event, data) => onEvent(data));
+  const decoder = new TextDecoder();
+  for await (const chunk of resp.body) push(decoder.decode(chunk, { stream: true }));
+}
+
+/** Render one turn end to end. Returns the `done` payload, or null. */
+async function runTurn({
+  args,
+  token,
+  workspaceId,
+  conversationId,
+  content,
+  renderer,
+  paint,
+  ask,
+  say,
+  onNote,
+  register,
+}) {
+  const controller = new AbortController();
+  let done = null;
+  let cancelled = false;
+  const onSigint = () => {
+    cancelled = true;
+    controller.abort();
+  };
+  // Both doors again: `register` is the session's -- a keystroke readline ate
+  // reaches the turn through it -- and the signal handler is for the one-shot
+  // and `--print` paths, where there is no session and no readline at all.
+  register?.({ abort: onSigint });
+  process.on("SIGINT", onSigint);
+
+  renderer.thinking?.();
+
+  try {
+    await streamTurn({
+      backend: backendUrl(args),
+      token,
+      workspaceId,
+      conversationId,
+      content,
+      signal: controller.signal,
+      onEvent: (event) => {
+        const type = String(event?.type || "");
+        if (type === "status") {
+          renderer.status(event.label);
+          // The spinner is transient by design, so the strip is where the work
+          // stays readable while it happens.
+          if (onNote) onNote(event.label);
+        }
+        else if (type === "artifact") renderer.artifact(event.artifact);
+        else if (type === "delta") renderer.delta(event.text);
+        else if (type === "intents") {
+          // Replay steps belong to the editor. The `note` ones are prose the
+          // agent wrote for a person, so those are the only ones worth a line.
+          for (const intent of event.intents || []) {
+            if (intent?.type === "note" && intent.text) renderer.note(`  ${intent.text}`);
+          }
+        } else if (type === "error") renderer.error(`PreMan: ${event.message || "turn failed"}`);
+        else if (type === "done") done = event;
+      },
+    });
+  } catch (error) {
+    if (cancelled) {
+      renderer.note(
+        "  Stopped following this turn. PreMan is still working on it -- /app to watch it there."
+      );
+    } else {
+      renderer.error(`  ${error.message}`);
+    }
+  } finally {
+    process.off("SIGINT", onSigint);
+    register?.(null);
+  }
+
+  if (done?.turn) renderer.fallback(done.turn.content);
+  renderer.end();
+  if (onNote) onNote("");
+  if (done?.turn && !cancelled) {
+    await askPermissions({
+      args,
+      token,
+      questions: permissionQuestions(done.turn.artifacts),
+      paint,
+      ask,
+      say,
+    });
+  }
+  return done;
+}
+
+/**
+ * Put a permission confirmation to the person at the keyboard.
+ *
+ * The option id is a signed token carrying the permission, the scope and the
+ * words it was asked about, so a client can only answer with something the
+ * server minted -- there is nothing here to get wrong except which option was
+ * pressed. Skipping is always available and is not a "no": an unanswered
+ * question can be asked again, a declined one is settled.
+ */
+async function askPermissions({ args, token, questions, paint, ask, say }) {
+  if (!questions.length || !process.stdin.isTTY) return;
+  // In a docked session readline is already live and owns stdin, so a second
+  // interface here would fight it for keystrokes. `ask` is that one reader
+  // lent out for a question; without it (the one-shot path) we open our own.
+  const borrowed = typeof ask === "function";
+  const write = say || ((text) => process.stdout.write(text));
+  const rl = borrowed ? null : createInterface({ input: process.stdin, output: process.stdout });
+  const readAnswer = borrowed ? ask : (text) => rl.question(text);
+  try {
+    for (const question of questions) {
+      write(`\n${paint.yellow("PreMan needs a decision")}\n`);
+      if (question.prompt) write(`  ${question.prompt}\n`);
+      question.options.forEach((option, index) => {
+        write(`  ${paint.bold(String(index + 1))}. ${option.label}\n`);
+      });
+      write(paint.dim("  Enter to skip\n"));
+      const answer = String((await readAnswer("  > ")) || "").trim();
+      const picked = question.options[Number.parseInt(answer, 10) - 1];
+      if (!picked) {
+        write(paint.dim("  Left unanswered.\n"));
+        continue;
+      }
+      const result = await callBackendJson(args, "POST", "/workbench/permissions/answer", {
+        token,
+        json: { option_id: picked.id },
+      });
+      write(
+        result.ok
+          ? `  ${paint.green("✓")} ${picked.label}\n`
+          : `  ${paint.red(describeFailure(result, "could not record that answer"))}\n`
+      );
+    }
+  } finally {
+    if (rl) rl.close();
+  }
+}
+
+async function resolveWorkspace(args, token) {
+  const explicit = args.value("--workspace", "");
+  const result = await backendCall(args, "GET", "/workbench/workspace", {
+    token,
+    headers: explicit ? { "x-workspace-id": explicit } : undefined,
+  });
+  const workspace = result.workspace || {};
+  return {
+    id: String(workspace.id || explicit || ""),
+    name: String(workspace.name || "Personal"),
+  };
+}
+
+async function newConversation(args, token, workspaceId) {
+  const result = await backendCall(args, "POST", "/workbench/conversations", {
+    token,
+    json: { title: "Terminal session", surface: "chat" },
+    headers: workspaceId ? { "x-workspace-id": workspaceId } : undefined,
+  });
+  return { id: String(result.id), title: String(result.title || "Terminal session") };
+}
+
+async function listConversations(args, token, workspaceId) {
+  const result = await backendCall(args, "GET", "/workbench/conversations", {
+    token,
+    headers: workspaceId ? { "x-workspace-id": workspaceId } : undefined,
+  });
+  return Array.isArray(result.conversations) ? result.conversations : [];
+}
+
+async function openConversation(args, token, conversationId) {
+  const result = await backendCall(
+    args,
+    "GET",
+    `/workbench/conversations/${encodeURIComponent(conversationId)}`,
+    { token }
+  );
+  return { id: String(result.id), title: String(result.title || "Conversation") };
+}
+
+/**
+ * Which conversation this session types into.
+ *
+ * A new one by default, because a terminal session is a new piece of work far
+ * more often than it is a continuation, and a fresh transcript is the one thing
+ * a scrollback cannot give back.
+ */
+async function resolveConversation(args, token, workspaceId) {
+  const explicit = args.value("--conversation", "");
+  if (explicit) return openConversation(args, token, explicit);
+  if (args.has("--continue") || args.has("-c")) {
+    const [latest] = await listConversations(args, token, workspaceId);
+    if (latest) return { id: String(latest.id), title: String(latest.title || "Conversation") };
+  }
+  return newConversation(args, token, workspaceId);
+}
+
+/**
+ * The mark, or the plain name when the window is too narrow for it.
+ *
+ * Monochrome, like the brand asset it is traced from: bold only, so the mark
+ * takes the terminal's own foreground rather than a hue of its own. That is
+ * the one choice that cannot come out invisible -- a fixed black disappears on
+ * a dark theme and a fixed white disappears on a light one, and a terminal
+ * does not say which it is. Bold also means there is no colour depth to
+ * negotiate, so the mark looks the same in a 16-colour terminal as in a
+ * truecolor one.
+ */
+export function logo(paint, columns) {
+  const width = columns || 80;
+  if (width < LOGO_WIDTH + 2) return paint.bold("PreMan");
+  return LOGO.map((row) => paint.bold(row)).join("\n");
+}
+
+/**
+ * Hold the terminal, and give it back whatever happens to this process.
+ *
+ * A session takes three things that outlive it if nobody puts them back: the
+ * alternate screen, a scrolling region, and the window title. Until now the
+ * only thing that returned them was a `finally` around the read loop, which
+ * covers a clean exit and nothing else -- not SIGTERM, not the tab being
+ * closed, not an exception thrown from a callback rather than from the loop
+ * body. And the damage is not self-correcting: the next `preman` sets its
+ * region on top of the live one, so a shell keeps its clipped bottom rows
+ * until something writes `ESC[r`.
+ *
+ * So restoration is one idempotent routine with every exit wired to it. The
+ * order inside it is the part that matters: the teardowns registered by the
+ * session run first, while the screen they are writing to is still the one
+ * they painted; then the region is released; then the alternate screen is left,
+ * because releasing margins after switching buffers would leave them set on the
+ * shell's screen -- `ESC[?1049h` does not save or reset them.
+ *
+ * `exit` is registered too, as the last resort, which is why every write here
+ * is synchronous and every step is wrapped: an exit handler that throws turns a
+ * clean shutdown into a crash, and a stream that has already closed is an
+ * ordinary state at that point rather than an error.
+ */
+export function holdTerminal({ stream = process.stdout, footer = () => "" } = {}) {
+  const live = Boolean(stream.isTTY);
+  const teardown = [];
+  const installed = [];
+  let restored = false;
+  // Who answers Ctrl+C. Null until the session has a keyboard of its own, and
+  // the default until then is the only safe one: put the terminal back and go.
+  let interrupted = null;
+
+  const safely = (fn) => {
+    try {
+      fn();
+    } catch {
+      // Nothing here can be reported anywhere useful: the screen is mid-repair
+      // and stderr may be the same broken terminal.
+    }
+  };
+
+  function restore() {
+    // Re-entrant on purpose. A second signal arriving while the first is being
+    // handled is normal -- somebody pressing Ctrl+C twice, or a SIGHUP landing
+    // behind a SIGTERM -- and the second must not replay half a teardown.
+    if (restored) return;
+    restored = true;
+    for (const fn of teardown.splice(0)) safely(fn);
+    if (live) safely(() => stream.write(`${RELEASE_REGION}${LEAVE_ALT}${SHOW_CURSOR}${CLEAR_TITLE}`));
+    safely(() => {
+      const text = footer();
+      if (text) stream.write(text);
+    });
+  }
+
+  const on = (event, handler) => {
+    process.on(event, handler);
+    installed.push([event, handler]);
+  };
+
+  return {
+    live,
+
+    /** Something to put back before the screen is handed over. */
+    onTeardown(fn) {
+      if (typeof fn === "function") teardown.push(fn);
+    },
+
+    /**
+     * Wire the deaths this process can see.
+     *
+     * SIGINT is deliberately not here: it is a conversation with the person at
+     * the keyboard rather than a death, and the session owns that. Everything
+     * else is the same answer -- put the terminal back, then die the way the
+     * signal says, because a process killed by SIGTERM should exit 143 and not
+     * pretend it finished.
+     */
+    watch() {
+      // SIGINT is installed here rather than left to the session because of the
+      // gap in between: from the moment the alternate screen is entered until
+      // readline exists, a press is the tty's own SIGINT and Node's default
+      // action kills the process by signal -- which does not run an `exit`
+      // handler, so the terminal was left on the alternate screen with no
+      // region released and no line saying what had happened. It is a window a
+      // few milliseconds wide, and it was the one death that did not restore.
+      on("SIGINT", () => {
+        if (interrupted) {
+          interrupted();
+          return;
+        }
+        restore();
+        process.exit(130);
+      });
+      on("SIGTERM", () => {
+        restore();
+        process.exit(143);
+      });
+      on("SIGHUP", () => {
+        restore();
+        process.exit(129);
+      });
+      const fatal = (error) => {
+        restore();
+        const message = error instanceof Error ? error.stack || error.message : String(error);
+        safely(() => process.stderr.write(`[preman] ${message}\n`));
+        process.exit(1);
+      };
+      on("uncaughtException", fatal);
+      on("unhandledRejection", fatal);
+      on("exit", () => restore());
+      return this;
+    },
+
+    /**
+     * Hand Ctrl+C to the session, now that there is somebody to answer it.
+     *
+     * Lent rather than added, so the two never both fire: a dispatcher that
+     * quits and a default that exits 130 would race to restore the same screen.
+     */
+    onInterrupt(fn) {
+      interrupted = typeof fn === "function" ? fn : null;
+    },
+
+    restore,
+
+    /** Give the terminal back and stop listening. Safe to call twice. */
+    release() {
+      restore();
+      for (const [event, handler] of installed.splice(0)) process.off(event, handler);
+    },
+  };
+}
+
+/**
+ * Hold the composer at the bottom of the window.
+ *
+ * A terminal has one cursor, so "input pinned below, transcript scrolling
+ * above" is not two panes — it is a scrolling region (DECSTBM) covering every
+ * row but the last two, plus the discipline of always leaving the cursor
+ * inside that region when a turn is printing. The bottom two rows sit outside
+ * the region, so nothing the agent writes can scroll them away.
+ *
+ * The reason this can be done with readline at all is that reading and
+ * printing never overlap here: the loop awaits a line, *then* runs the turn.
+ * So the composer only has to be live while `question` is pending, and the
+ * submitted line is echoed into the transcript on the way past -- otherwise it
+ * would vanish when the input row is cleared for the next prompt.
+ *
+ * Not a TTY (a pipe, `--print`, CI) means none of this applies and every method
+ * is a no-op, which keeps piped output byte-for-byte what it was.
+ */
+export function createDock({
+  stream = process.stdout,
+  input = process.stdin,
+  paint,
+  status = "",
+} = {}) {
+  const live = Boolean(stream.isTTY);
+  let open = false;
+  let rl = null;
+  // The keypress listener that keeps the furniture alive while somebody types,
+  // held so it can be taken off again -- a session that ends with a listener
+  // still on stdin keeps the process alive after the dock is gone.
+  let typing = null;
+  let queued = false;
+  let dirty = false;
+  let label = status;
+  let note = "";
+  // The window size the furniture was last drawn at. A resize has to erase the
+  // old rows before painting new ones, and after the event they are no longer
+  // derivable from the terminal -- it has already reflowed.
+  let painted = null;
+  // Where the transcript has got to, in screen coordinates. The terminal keeps
+  // this too, in its saved cursor, and that copy is the one the writes use --
+  // but a resize destroys it, so it is mirrored here to be put back. Null means
+  // nobody knows: before `enable`, and after any stretch the dock did not paint.
+  let at = null;
+
+  const size = () => ({
+    columns: stream.columns || 80,
+    rows: stream.rows || 24,
+  });
+
+  /** Last row the transcript may use; everything below belongs to the dock. */
+  const floor = () => Math.max(1, size().rows - DOCK_ROWS);
+
+  /**
+   * Follow the transcript's cursor through a chunk.
+   *
+   * The terminal is tracking the same thing in its saved cursor and does it
+   * perfectly, so this exists for one moment only: a resize, after which that
+   * saved position no longer means anything and the dock has to name a row to
+   * carry on from. It used to name the floor, which is why a session that had
+   * printed ten lines onto a fifty-row window jumped to the bottom of it and
+   * scrolled the banner away to say the eleventh.
+   *
+   * Only the finals that move the cursor are read. The erases and the colour
+   * runs that make up most of a transcript leave it exactly where it was, and
+   * a sequence this does not recognise is likelier to be one of those than a
+   * jump -- so the unknown case is "no movement" rather than a guess.
+   */
+  function advance(chunk) {
+    if (!at) return;
+    const { columns } = size();
+    const limit = floor();
+    let { row, column } = at;
+    // At the floor the region scrolls under the cursor rather than moving it:
+    // everything already printed goes up a row and the cursor stays put.
+    const down = () => {
+      if (row < limit) row += 1;
+    };
+    const text = String(chunk);
+    for (let i = 0; i < text.length; i += 1) {
+      const ch = text[i];
+      if (ch === "\u001b") {
+        const next = text[i + 1];
+        if (next === "[") {
+          let j = i + 2;
+          while (j < text.length && !/[@-~]/.test(text[j])) j += 1;
+          const params = text.slice(i + 2, j);
+          const final = text[j];
+          if (final === "H" || final === "f") {
+            const [r, c] = params.split(";");
+            row = Math.min(Math.max(Number(r) || 1, 1), limit);
+            column = Math.min(Math.max(Number(c) || 1, 1), columns);
+          } else if (final === "G") {
+            column = Math.min(Math.max(Number(params) || 1, 1), columns);
+          }
+          i = j;
+          continue;
+        }
+        if (next === "]") {
+          while (i < text.length && text[i] !== "\u0007") i += 1;
+          continue;
+        }
+        i += 1;
+        continue;
+      }
+      if (ch === "\r") {
+        column = 1;
+        continue;
+      }
+      if (ch === "\n") {
+        // ONLCR: stdout to a terminal turns a bare newline into CR+LF, so the
+        // column goes back to one. Modelling it as a pure index down would
+        // stair-step every line of the transcript to the right.
+        column = 1;
+        down();
+        continue;
+      }
+      if (ch === "\u0007") continue;
+      // Deferred wrap, the way a terminal does it: the glyph in the last column
+      // leaves the cursor on that column, and the *next* one moves the line on.
+      if (column > columns) {
+        column = 1;
+        down();
+      }
+      column += 1;
+    }
+    at = { row, column };
+  }
+
+  /**
+   * Is there a window here to dock in at all?
+   *
+   * Four reserved rows and no check against the window's height meant a short
+   * one produced arithmetic rather than layout: three rows emitted
+   * `ESC[0;1H` and two emitted `ESC[-1;1H`, a malformed CSI whose bytes some
+   * terminals print. Below the floor the dock simply does not paint -- the
+   * session falls back to being a plain prompt, which is what it already is on
+   * a pipe -- and `resize` brings it back the moment the window can hold it.
+   */
+  const roomy = () => size().rows >= DOCK_ROWS + 2;
+
+  /** The rule above the composer. */
+  function chrome() {
+    const { columns, rows } = size();
+    painted = { columns, rows };
+    stream.write(`\u001b[${rows - 3};1H\u001b[2K${paint.dim("\u2500".repeat(columns))}`);
+  }
+
+  /**
+   * The rule under the composer, and the status strip under that.
+   *
+   * These are painted *after* the composer rather than with the rule above it,
+   * because readline redraws its line with an erase-to-end-of-screen: anything
+   * written below the input row before `prompt()` is wiped the moment the
+   * prompt refreshes, which left the session showing a bare rule above the
+   * caret and nothing -- no lower rule, no model name -- beneath it.
+   */
+  function under() {
+    const { columns, rows } = size();
+    const strip = note ? `${label} \u00b7 ${note}` : label;
+    stream.write(`\u001b[${rows - 1};1H\u001b[2K${paint.dim("\u2500".repeat(columns))}`);
+    const tint = paint.lime || paint.dim;
+    stream.write(`\u001b[${rows};1H\u001b[2K${tint(truncate(strip, columns))}`);
+  }
+
+  /**
+   * Put the composer back under the cursor readline thinks it has.
+   *
+   * `prompt(true)` is what redraws the prompt *and* whatever has been typed so
+   * far, which is the whole point: a line half-typed while the agent was
+   * talking has to survive every write that happened underneath it.
+   */
+  function composer() {
+    const { rows } = size();
+    stream.write(`\u001b[${rows - 2};1H\u001b[2K`);
+    // A closed readline is the ordinary state on the way out: quitting mid-turn
+    // closes it while the answer is still arriving, and every fragment after
+    // that would ask it to redraw a prompt it no longer has. Node answers that
+    // with a throw, which surfaced as a bare "readline was closed" on a session
+    // that had in fact just done what it was told.
+    if (rl && !rl.closed) rl.prompt(true);
+    under();
+    caret();
+  }
+
+  /**
+   * Put the cursor back where the typist left it.
+   *
+   * The furniture below the composer is addressed absolutely, and readline goes
+   * on typing wherever the cursor was last put -- so every repaint has to end
+   * by handing the position back.
+   */
+  function caret() {
+    const { columns, rows } = size();
+    const at = (rl && !rl.closed ? rl.getCursorPos?.() : null) || { rows: 0, cols: 0 };
+    // Bounded by the window, not pinned to the composer's row: a line long
+    // enough to wrap genuinely occupies the rows under it -- readline drew it
+    // there -- so the caret has to follow it or the next keystroke lands
+    // somewhere else entirely. What this stops is the row running off the
+    // bottom of the screen, which is where an unbounded offset sent it.
+    const row = Math.min(rows, Math.max(1, rows - 2 + Math.max(0, at.rows || 0)));
+    const column = Math.min(Math.max(1, (at.cols || 0) + 1), Math.max(1, columns));
+    stream.write(`\u001b[${row};${column}H`);
+  }
+
+  /**
+   * Repaint the furniture, at most once a tick.
+   *
+   * A streamed reply arrives as dozens of fragments a second and every one of
+   * them used to repaint two full-width rules, the status strip, readline's
+   * line and the cursor -- six hundred bytes of scenery per token on a wide
+   * window, for a screen that looks identical each time. That is the shape of
+   * the corruption seen in real sessions: lines arriving with their middles
+   * missing, which is what an emulator does when it cannot keep up.
+   *
+   * So the transcript is written immediately -- it is the thing somebody is
+   * reading -- and the scenery is marked dirty and painted once when the tick
+   * drains. Callers that change what the furniture *says* still paint
+   * synchronously, because their contract is that the change is on screen when
+   * they return.
+   */
+  function repaint() {
+    if (!open || dirty) return;
+    dirty = true;
+    setImmediate(() => {
+      dirty = false;
+      if (!open) return;
+      frame();
+    });
+  }
+
+  /** Every row of furniture, in the order the terminal needs them. */
+  function frame() {
+    if (!roomy()) return;
+    chrome();
+    composer();
+  }
+
+  function listen() {
+    if (!live || typing) return;
+    // Typing is the other thing that erases the furniture, and it was the
+    // hole this dock had: `write`, `resize` and the rest all repaint, but a
+    // keystroke goes straight into readline, which redraws its line with an
+    // erase-to-end-of-screen and takes the lower rule and the status strip
+    // with it. Nothing here is told, so the rows stayed blank until the next
+    // event -- which is why the bottom line vanished mid-sentence and came
+    // back when the agent next said something.
+    //
+    // readline has no "I have just redrawn" hook, so the repaint rides the
+    // keypress that caused it. This listener is registered after readline's
+    // own, so it runs after the line has been redrawn, and it is coalesced
+    // to one repaint per tick: a pasted line is hundreds of keypresses, and
+    // repainting a full-width rule for each of them is a lot of bytes to
+    // send a terminal for one visual result.
+    typing = () => {
+      if (!open || queued) return;
+      queued = true;
+      setImmediate(() => {
+        queued = false;
+        // `roomy` for the same reason every other painter checks it: a window
+        // too short to hold the dock is one where these rows do not exist, and
+        // painting them anyway was the one path that could still address row
+        // zero after the floor was added.
+        if (!open || !roomy()) return;
+        under();
+        caret();
+      });
+    };
+    input?.on?.("keypress", typing);
+  }
+
+  return {
+    live,
+
+    /**
+     * Reserve the bottom rows and remember where the transcript is.
+     *
+     * `row` is where the transcript has got to on a screen the caller knows the
+     * state of -- a session that has just cleared the screen and printed a
+     * banner knows exactly that. Without it the screen is assumed to be full,
+     * which is the honest reading when the dock is coming back up after
+     * something else owned the terminal: scroll to make room for the furniture
+     * and carry on at the floor.
+     */
+    enable({ row } = {}) {
+      if (!live || open) return;
+      open = true;
+      listen();
+      stream.write(SET_TITLE);
+      // Whatever a previous life left here says nothing about this screen.
+      at = null;
+      if (!roomy()) return;
+      if (row == null) {
+        stream.write("\n".repeat(DOCK_ROWS));
+        at = { row: floor(), column: 1 };
+      } else {
+        at = { row: Math.min(Math.max(1, row), floor()), column: 1 };
+      }
+      stream.write(`\u001b[1;${floor()}r`);
+      stream.write(`\u001b[${at.row};${at.column}H`);
+      stream.write("\u001b7");
+      frame();
+    },
+
+    attach(readline) {
+      rl = readline;
+      listen();
+    },
+
+    /** Repaint furniture and composer, e.g. after the prompt text changes. */
+    refresh() {
+      if (!open) return;
+      frame();
+    },
+
+    setStatus(text) {
+      label = text;
+      if (open) frame();
+    },
+
+    /**
+     * Every byte of transcript goes through here.
+     *
+     * The saved cursor (DECSC/DECRC) is the transcript's own position, which
+     * matters because a streamed reply arrives as fragments with no newline —
+     * forcing column 1 between them would overprint the line instead of
+     * continuing it. So: restore, write, save, then repaint the furniture.
+     */
+    write(chunk) {
+      if (!open || !roomy()) {
+        // Nothing is following the cursor down a screen the dock does not own,
+        // so whatever was tracked is now a guess. Said rather than kept: a
+        // window that grows back is better off assuming the transcript filled
+        // it than resuming at a row from before it went blind.
+        at = null;
+        stream.write(chunk);
+        return;
+      }
+      // One write rather than three: the restore, the chunk and the save are a
+      // single sequence to the terminal, so nothing can land between them.
+      stream.write(`\u001b8${chunk}\u001b7`);
+      advance(chunk);
+      repaint();
+    },
+
+    /** Leave the same trail a normal REPL would for a line just submitted. */
+    echo(text) {
+      if (!open) return;
+      // Plain inside the band, deliberately: every painter here ends with a
+      // reset, and a reset mid-line takes the background off with it -- a
+      // half-highlighted row reads as a rendering fault. Padded to the window
+      // so the band is a row rather than a highlight around the words. A line
+      // long enough to wrap carries the background across every row it takes,
+      // the last of them ending where the words do, because the band opens
+      // once and closes once and the terminal wraps what is between.
+      const { columns } = size();
+      const line = `\u276f ${text}`;
+      const pad = " ".repeat(Math.max(0, columns - printable(line)));
+      this.write(`${paint.band(`${line}${pad}`)}\n`);
+    },
+
+    /** A stdout stand-in for the renderer, so its writes land in the region. */
+    proxy() {
+      if (!open) return stream;
+      const dock = this;
+      return {
+        write(chunk) {
+          dock.write(chunk);
+          return true;
+        },
+        get isTTY() {
+          return stream.isTTY;
+        },
+        get columns() {
+          return stream.columns;
+        },
+        get rows() {
+          return stream.rows;
+        },
+      };
+    },
+
+    /**
+     * Follow a resize.
+     *
+     * Dragging a window edge fires this many times a second, and each event
+     * arrives *after* the terminal has already reflowed -- so the rows the
+     * furniture was last drawn on are now ordinary content sitting in the
+     * scrollback. Painting the new chrome without erasing the old is what
+     * smears rules and carets down the screen. Releasing the region first is
+     * what makes the old rows addressable at all: inside a scrolling region
+     * the bottom rows cannot be cursored to.
+     */
+    resize() {
+      if (!open) return;
+      stream.write(RELEASE_REGION);
+      if (painted) {
+        // Only the rows the furniture was on. It used to erase from there to
+        // the end of the screen, which is fine when a window shrinks and
+        // destroys live transcript when it grows: the rows between the old
+        // dock and the new floor hold the answer somebody is reading.
+        const top = Math.max(1, Math.min(painted.rows, size().rows) - DOCK_ROWS + 1);
+        for (let row = top; row <= Math.min(painted.rows, size().rows); row++) {
+          stream.write(`\u001b[${row};1H\u001b[2K`);
+        }
+      }
+      painted = null;
+      if (!roomy()) return;
+      stream.write(`\u001b[1;${floor()}r`);
+      // Where the transcript actually is, clamped into the new window -- not
+      // the floor, which is what this used to say. Naming the floor meant every
+      // drag of a window edge moved the transcript to the bottom of it, so the
+      // next line printed scrolled the region and the banner climbed a row
+      // towards the top and off. On a session that had barely started, that is
+      // the whole screen going blank above a reply pinned to the bottom.
+      const { columns } = size();
+      at = {
+        row: Math.min(Math.max(1, at?.row ?? floor()), floor()),
+        column: Math.min(Math.max(1, at?.column ?? 1), columns),
+      };
+      stream.write(`\u001b[${at.row};${at.column}H`);
+      stream.write("\u001b7");
+      frame();
+    },
+
+    /** What the agent is doing right now, shown on the strip during a turn. */
+    setNote(text) {
+      note = String(text || "");
+      if (open) frame();
+    },
+
+    /** Give the rows back, or the shell prompt inherits a clipped screen. */
+    disable() {
+      // The listener goes first and outside the open check: `attach` arms it,
+      // and a dock that was attached and never enabled would otherwise keep a
+      // `keypress` listener on stdin for the life of the process -- which is
+      // the hazard this method exists to prevent, arriving by another door.
+      if (typing) {
+        input?.off?.("keypress", typing);
+        typing = null;
+      }
+      if (!open) return;
+      open = false;
+      at = null;
+      const { rows } = size();
+      stream.write("\u001b[r");
+      stream.write(`\u001b[${rows};1H\u001b[2K`);
+      stream.write(CLEAR_TITLE);
+    },
+  };
+}
+
+/** Printable width, ignoring the colour codes wrapped around the text. */
+function printable(text) {
+  return [...text.replace(/\u001b\[[0-9;]*m/g, "")].length;
+}
+
+/**
+ * Set two blocks of rows side by side, the left one padded to its own width.
+ *
+ * Measuring has to ignore the escape codes: `paint.bold(row)` is several
+ * bytes longer than the glyphs it wraps, and padding to `.length` would step
+ * the right-hand column in and out by that much on every row.
+ */
+function beside(left, right, gap = 3) {
+  const width = Math.max(...left.map(printable));
+  const rows = [];
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const mark = left[i] ?? "";
+    const detail = right[i] ?? "";
+    if (!detail) {
+      rows.push(mark);
+      continue;
+    }
+    rows.push(`${mark}${" ".repeat(width - printable(mark) + gap)}${detail}`);
+  }
+  return rows;
+}
+
+export function banner({ paint, workspace, backend, conversation, columns }) {
+  const version = packageVersion();
+  const cli = cliInvocation();
+  const width = columns ?? process.stdout.columns ?? 80;
+  const details = [
+    `${paint.bold("PreMan")}${version ? paint.dim(` v${version}`) : ""}`,
+    paint.dim(`${workspace.name} - ${backend.replace(/^https?:\/\//, "")}`),
+  ];
+  if (conversation?.title) details.push(paint.dim(`Conversation: ${conversation.title}`));
+  const mark = logo(paint, width).split("\n");
+  // Side by side while both fit; stacked when the window is too narrow, which
+  // is the same answer the wordmark used to give -- just at a far lower bar.
+  const widest = Math.max(...details.map(printable));
+  const lines =
+    width >= LOGO_WIDTH + 3 + widest ? beside(mark, details) : [...mark, "", ...details];
+  lines.push(
+    "",
+    "Ask PreMan to discover endpoints, generate and run tests, or deploy a hosted MCP.",
+    paint.dim(`/help for commands - /exit to leave - ${cli} --help for the rest of the CLI`),
+    ""
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Read a line, resolving to null when stdin ends (EOF, a pipe, Ctrl+D).
+ *
+ * Both guards are for the same moment: stdin running out while a turn was in
+ * flight. By the time we ask again the interface is already closed, so a
+ * `close` listener registered now would never fire and `question` rejects
+ * outright -- which used to surface as a bare "readline was closed" error on a
+ * session that had in fact just ended normally.
+ */
+async function nextLine(rl, prompt) {
+  if (rl.closed) return null;
+  const closed = new Promise((resolve) => rl.once("close", () => resolve(null)));
+  try {
+    return await Promise.race([rl.question(prompt), closed]);
+  } catch {
+    return null;
+  }
+}
+
+/** The catalog of what this account can measure, with its on/off state. */
+async function behaviorCatalog(args, token) {
+  const result = await callBackendJson(args, "GET", "/eval-behaviors", { token });
+  if (!result.ok) {
+    throw new Error(
+      `could not read what this account measures (${result.status_code}): ${describeFailure(result)}`
+    );
+  }
+  return result;
+}
+
+/**
+ * One line per behaviour: number, state, id, and what it is.
+ *
+ * Numbered because the catalog is fifty-odd entries deep and
+ * `library:explicit_constraint_violation_failures` is not something anybody is
+ * going to type correctly at a prompt. The number is the row's position in this
+ * same response, so `/eval on 12` re-reads the catalog and counts to twelve --
+ * the list is files that ship with the deployment plus this account's own
+ * entries, so it is the same twelve unless the account changed in between.
+ */
+function behaviorLines(catalog, paint) {
+  const rows = catalog.behaviors || [];
+  if (!rows.length) return [paint.dim("  nothing in the catalog for this account.")];
+  const width = Math.max(...rows.map((entry) => String(entry.id).length));
+  const digits = String(rows.length).length;
+  return rows.map((entry, index) => {
+    const number = paint.dim(String(index + 1).padStart(digits));
+    const mark = entry.enabled ? paint.green("●") : paint.dim("○");
+    const id = String(entry.id).padEnd(width);
+    const title = entry.title || entry.name || "";
+    const source = entry.source ? paint.dim(` (${entry.source})`) : "";
+    return `  ${number} ${mark} ${entry.enabled ? id : paint.dim(id)}  ${title}${source}`;
+  });
+}
+
+/**
+ * Work out which behaviours somebody meant.
+ *
+ * Four ways of saying it, because both the ids and the list are long: `12`,
+ * `3-7`, `all`, and any text that names one -- the full id, the bare name, or
+ * enough of either to be unambiguous. `sycophancy` is one behaviour;
+ * `failures` is thirty, and thirty is reported as ambiguous rather than picking
+ * the first, because what follows spends a provider bill per behaviour.
+ */
+export function pickBehaviors(rows, tokens) {
+  const picked = new Map();
+  const unknown = [];
+  const ambiguous = [];
+  const take = (entry) => {
+    if (entry) picked.set(entry.id, entry);
+  };
+
+  for (const raw of tokens) {
+    const token = String(raw || "").trim();
+    if (!token) continue;
+
+    if (token.toLowerCase() === "all") {
+      rows.forEach(take);
+      continue;
+    }
+
+    const range = /^(\d+)\s*-\s*(\d+)$/.exec(token);
+    if (range) {
+      const [from, to] = [Number(range[1]), Number(range[2])];
+      const [low, high] = from <= to ? [from, to] : [to, from];
+      let hit = false;
+      for (let n = low; n <= high; n++) {
+        if (rows[n - 1]) {
+          take(rows[n - 1]);
+          hit = true;
+        }
+      }
+      if (!hit) unknown.push(token);
+      continue;
+    }
+
+    if (/^\d+$/.test(token)) {
+      const entry = rows[Number(token) - 1];
+      if (entry) take(entry);
+      else unknown.push(token);
+      continue;
+    }
+
+    const needle = token.toLowerCase();
+    const exact = rows.find(
+      (entry) =>
+        String(entry.id).toLowerCase() === needle ||
+        String(entry.name || "").toLowerCase() === needle
+    );
+    if (exact) {
+      take(exact);
+      continue;
+    }
+    const matches = rows.filter(
+      (entry) =>
+        String(entry.id).toLowerCase().includes(needle) ||
+        String(entry.title || "").toLowerCase().includes(needle)
+    );
+    if (matches.length === 1) take(matches[0]);
+    else if (matches.length) ambiguous.push({ token, matches });
+    else unknown.push(token);
+  }
+
+  // Catalog order, not the order the words were typed: what gets switched on is
+  // then reported in the same order as the numbered list it was read off.
+  const at = new Map(rows.map((entry, index) => [entry.id, index]));
+  return {
+    picked: [...picked.values()].sort((a, b) => at.get(a.id) - at.get(b.id)),
+    unknown,
+    ambiguous,
+  };
+}
+
+/**
+ * Turn behaviours on and off without leaving the terminal.
+ *
+ * The catalog, the toggles and the custom descriptions are all already HTTP --
+ * the dashboard has no privileged path to them. What was missing was a way to
+ * reach them from here, which is why `/eval` could only ever report that
+ * nothing was switched on and then send you to a web page to fix it.
+ */
+async function manageBehaviors(argv, { args, token, paint, say }) {
+  const [sub, ...rest] = argv;
+
+  if (sub === "list") {
+    const catalog = await behaviorCatalog(args, token);
+    const on = (catalog.behaviors || []).filter((entry) => entry.enabled).length;
+    say(`${on} of ${(catalog.behaviors || []).length} switched on\n`);
+    say(`${behaviorLines(catalog, paint).join("\n")}\n`);
+    say(
+      paint.dim(
+        `  /eval on 3 12 or /eval on sycophancy to switch those on, /eval to run what is on\n\n`
+      )
+    );
+    return;
+  }
+
+  if (sub === "on" || sub === "off") {
+    if (!rest.length) {
+      say(paint.dim(`Usage: /eval ${sub} <number, range, id or all>\n\n`));
+      return;
+    }
+    const enabled = sub === "on";
+    const catalog = await behaviorCatalog(args, token);
+    const { picked, unknown, ambiguous } = pickBehaviors(catalog.behaviors || [], rest);
+
+    for (const { token: word, matches } of ambiguous) {
+      const names = matches.slice(0, 4).map((entry) => entry.id).join(", ");
+      const more = matches.length > 4 ? `, and ${matches.length - 4} more` : "";
+      say(`${paint.yellow(`${word} matches ${matches.length}:`)} ${names}${more}\n`);
+    }
+    for (const word of unknown) say(`${paint.yellow(`nothing here is called ${word}`)}\n`);
+
+    if (!picked.length) {
+      say(paint.dim("  /eval list to see the numbers\n\n"));
+      return;
+    }
+
+    await applyToggles(picked, enabled, { args, token, paint, say });
+    return;
+  }
+
+  if (sub === "defaults") {
+    await switchOnDefaults({ args, token, paint, say });
+    return;
+  }
+
+  say(paint.dim("Usage: /eval [doctor|list|defaults|on <what>|off <what>|--only <id>]\n\n"));
+}
+
+/**
+ * Switch a selection on or off, one PUT each, saying what happened to each.
+ *
+ * One request per behaviour because that is the contract the dashboard uses
+ * too -- there is no bulk toggle, and inventing one here would be a second
+ * place the rule "a toggle is refused for an id not in the catalog" is
+ * enforced. A row already in the state being asked for is said and not sent,
+ * so a selection of twelve does not report twelve changes when it made two.
+ */
+async function applyToggles(picked, enabled, { args, token, paint, say }) {
+  const word = enabled ? "on" : "off";
+  let changed = 0;
+  for (const entry of picked) {
+    if (Boolean(entry.enabled) === enabled) {
+      say(paint.dim(`  ${entry.id} already ${word}\n`));
+      continue;
+    }
+    const result = await callBackendJson(
+      args,
+      "PUT",
+      `/eval-behaviors/${encodeURIComponent(entry.id)}`,
+      { token, json: { enabled } }
+    );
+    if (!result.ok) {
+      say(`${paint.red(describeFailure(result, `could not switch ${entry.id} ${word}`))}\n`);
+      continue;
+    }
+    changed += 1;
+    say(`${paint.green("✓")} ${entry.id} switched ${word}\n`);
+  }
+  if (changed && enabled) say(paint.dim("  /eval to run what is on\n"));
+  say("\n");
+}
+
+/**
+ * What to send when asking which behaviours suit this project.
+ *
+ * "Which of fifty behaviours matter here" cannot be answered from an account
+ * id, so something has to describe the agent under test. These are the files a
+ * project already uses to say what it is, bounded hard: a README's prose, a
+ * package or project description, and the directory's own name. Nothing is read
+ * that a repository does not publish about itself -- no source, no env files --
+ * because this text leaves the machine.
+ */
+export function projectBlurb(root = process.cwd()) {
+  const read = (name) => {
+    try {
+      return readFileSync(join(root, name), "utf8");
+    } catch {
+      return "";
+    }
+  };
+
+  const parts = [`Directory: ${basename(root)}`];
+
+  try {
+    const pkg = JSON.parse(read("package.json") || "{}");
+    if (pkg.name || pkg.description) {
+      parts.push(`Package: ${[pkg.name, pkg.description].filter(Boolean).join(" - ")}`);
+    }
+  } catch {
+    // A package.json that does not parse says nothing about the project.
+  }
+
+  const described = /^\s*description\s*=\s*["'](.+?)["']/m.exec(read("pyproject.toml"));
+  if (described) parts.push(`Project: ${described[1]}`);
+
+  const readme = read("README.md") || read("readme.md");
+  if (readme) {
+    const prose = readme
+      .replace(/```[\s\S]*?```/g, "")
+      .split("\n")
+      // Badges and raw HTML are a header rather than a description, and on a
+      // lot of READMEs they are most of the first screen.
+      .filter((line) => !/^\s*[[!<]/.test(line))
+      .join("\n")
+      .trim();
+    if (prose) parts.push(`README:\n${prose.slice(0, 1500)}`);
+  }
+
+  return parts.join("\n\n").slice(0, 3500);
+}
+
+/**
+ * Ask which behaviours suit this project, then switch them on.
+ *
+ * Two requests, deliberately not one: `/eval-behaviors/recommend` chooses and
+ * the existing toggle applies, so an enabled behaviour is always something this
+ * client asked for by id rather than something a model turn left behind. The
+ * shortlist is printed with its reasons before it is applied, because "a model
+ * picked these" is a claim the person paying for the runs should be able to
+ * read and disagree with.
+ */
+async function switchOnDefaults({ args, token, paint, say }) {
+  say(paint.dim("Reading this project and choosing what to measure...\n"));
+  const advice = await callBackendJson(args, "POST", "/eval-behaviors/recommend", {
+    token,
+    json: { project: projectBlurb(), limit: 5 },
+  });
+  if (!advice.ok) {
+    say(`${paint.red(describeFailure(advice, "could not work out what to switch on"))}\n\n`);
+    return;
+  }
+
+  const picks = advice.behaviors || [];
+  if (!picks.length) {
+    say(paint.dim("Nothing in the catalog for this account.\n\n"));
+    return;
+  }
+
+  // Which of the two produced this list, said plainly: a curated fallback
+  // presented as a reading of this project would be a claim nobody made.
+  say(
+    advice.source === "model"
+      ? `${picks.length} to start with, chosen for this project:\n`
+      : `${picks.length} to start with. Nothing read this project -- no eval provider ` +
+          `key on this account -- so these are the usual first few:\n`
+  );
+  for (const pick of picks) {
+    const why = pick.reason ? paint.dim(` - ${pick.reason}`) : "";
+    say(`  ${pick.title || pick.id}${why}\n    ${paint.dim(pick.id)}\n`);
+  }
+  say("\n");
+
+  await applyToggles(picks, true, { args, token, paint, say });
+}
+
+/**
+ * Run an eval from inside a session.
+ *
+ * The dock comes down for the duration and goes back up after, which is not
+ * cosmetic: `eval.js` spawns the Python harness as a child process inheriting
+ * this terminal's stdout. A child writing to fd 1 cannot be funnelled through
+ * `dock.write`, so leaving the scrolling region in place would let harness
+ * output shred the composer. Readline is paused for the same reason -- the
+ * harness may want the keyboard, and two readers on stdin is one too many.
+ *
+ * `/eval` is `preman test --agent`, deliberately: the behaviours, the account
+ * and the run history are the same ones, and a session is a place to start one
+ * from, not a second way to define what a run means.
+ */
+export async function runEval(rest, { args, token, dock, rl, paint, say, running }) {
+  const argv = String(rest || "").trim().split(/\s+/).filter(Boolean);
+  const sub = argv[0];
+
+  // Reading and toggling are plain HTTP, so they stay in the docked transcript
+  // rather than taking the screen the way a harness run has to.
+  if (sub === "list" || sub === "on" || sub === "off" || sub === "defaults") {
+    try {
+      await manageBehaviors(argv, { args, token, paint, say });
+    } catch (error) {
+      say(`${paint.red(error?.message || String(error))}\n\n`);
+    }
+    return;
+  }
+
+  const doctor = sub === "doctor";
+
+  // Starting a run with nothing switched on used to end at an error naming a
+  // web page. The catalog is right here, so show it and say which words fix it.
+  if (!doctor) {
+    try {
+      const catalog = await behaviorCatalog(args, token);
+      const on = (catalog.behaviors || []).filter((entry) => entry.enabled);
+      if (!on.length) {
+        say(`${paint.yellow("Nothing is switched on, so there is nothing to measure.")}\n`);
+        say(`${behaviorLines(catalog, paint).join("\n")}\n`);
+        say(paint.dim("  /eval defaults to pick a few that suit this project and switch them on\n"));
+        say(paint.dim("  /eval on 3 12 to switch those two on, then /eval to run\n\n"));
+        return;
+      }
+    } catch (error) {
+      say(`${paint.red(error?.message || String(error))}\n\n`);
+      return;
+    }
+  }
+
+  dock.disable();
+  rl.pause();
+  // Readline's `pause` stops stdin flowing and leaves the tty in raw mode, so
+  // for the length of a run the terminal generated no signals and a Ctrl+C sat
+  // in the buffer until the run ended -- pressed, ignored, then delivered at
+  // the one moment it was no longer wanted. Out of raw mode the keystroke is a
+  // real SIGINT again, and the session's interrupt handler can stop the run.
+  const wasRaw = Boolean(process.stdin.isRaw);
+  if (wasRaw) process.stdin.setRawMode?.(false);
+  running?.(true);
+  try {
+    const { agentTestCommand, evalCommand } = await import("./eval.js");
+    const runner = await import("./runner.js");
+    const deps = {
+      makeArgs,
+      runnerLoop: runner.runnerLoop,
+      saveRunnerState: runner.saveRunnerState,
+      readRunnerState: runner.readRunnerState,
+      deviceId: runner.deviceId,
+    };
+    if (doctor) await evalCommand(argv, deps);
+    else await agentTestCommand(argv, deps);
+  } catch (error) {
+    process.stdout.write(`${paint.red(error?.message || String(error))}\n`);
+  } finally {
+    running?.(false);
+    if (wasRaw) process.stdin.setRawMode?.(true);
+    rl.resume();
+    dock.enable();
+  }
+}
+
+export async function agentCommand(commandArgs = [], { authenticate = authenticateTerminal } = {}) {
+  const args = makeArgs(commandArgs);
+  if (args.has("--help") || args.has("-h")) {
+    process.stdout.write(`Usage: ${cliInvocation()} [message]\n${AGENT_HELP}\n${SLASH_HELP}\n`);
+    return;
+  }
+
+  const paint = makePaint(colourEnabled(args));
+
+  // Signing in is part of starting a session, not a separate command somebody
+  // has to know about first -- this is the whole first-run path for `preman`.
+  // The walk that also installs the app and wires integrations is still there;
+  // it is offered rather than imposed, because somebody who typed `preman` to
+  // ask a question should get to ask it.
+  if (!hasKeyAvailable(args)) {
+    process.stdout.write("Let's connect your PreMan account first.\n\n");
+    await authenticate(args);
+    process.stdout.write(
+      `\n${paint.dim(`Want the desktop app and integrations too? Run \`${cliInvocation()} onboard\`.`)}\n\n`
+    );
+  }
+  const token = resolveApiKey(args);
+  if (!token) throw new Error(`No PreMan API key. Run \`${cliInvocation()} login\`.`);
+
+  const workspace = await resolveWorkspace(args, token);
+  let conversation = await resolveConversation(args, token, workspace.id);
+
+  const oneShot = positionals(args.raw).join(" ").trim();
+  const live = colourEnabled(args) && Boolean(process.stdout.isTTY);
+  const renderer = createRenderer({ paint, live });
+
+  if (oneShot) {
+    await runTurn({
+      args,
+      token,
+      workspaceId: workspace.id,
+      conversationId: conversation.id,
+      content: oneShot,
+      renderer,
+      paint,
+    });
+    // `--print` is the scriptable form: one message, one reply, exit. Without
+    // it a message on the command line is simply how the session opens.
+    if (args.has("--print") || args.has("-p") || !process.stdin.isTTY) return;
+  }
+
+  // The session's own screen, entered before anything is printed so the banner
+  // lands at the top of it. A terminal that does not understand the sequence
+  // ignores it and gets exactly what it got before.
+  const fullScreen = Boolean(process.stdout.isTTY);
+
+  // Watching before the screen is taken, not after: the handlers have to be up
+  // for every moment the terminal is in a state somebody else has to live with.
+  //
+  // What a person needs after the screen is handed back is the one line that
+  // returns them to this conversation. Read at restore time rather than
+  // captured, because `/new` and `/resume` change which conversation that is.
+  const hold = holdTerminal({
+    stream: process.stdout,
+    footer: () => {
+      // A conversation whose id never arrived stringifies to "undefined", and a
+      // resume line naming that is worse than no resume line.
+      const id = String(conversation?.id || "");
+      if (!fullScreen || !id || id === "undefined") return "";
+      return `${paint.dim("Resume this session with:")}\n  ${cliInvocation()} --conversation ${id}\n`;
+    },
+  }).watch();
+
+  if (fullScreen) process.stdout.write(`${ENTER_ALT}${CLEAR_SCREEN}`);
+
+  const dock = createDock({
+    stream: process.stdout,
+    paint,
+    status: `${MODEL_NAME} \u00b7 ${basename(process.cwd())}`,
+  });
+  const prompt = `${paint.caret("\u276f")} `;
+  const rl = createInterface({ input: process.stdin, output: process.stdout, prompt });
+  dock.attach(rl);
+  // The screen was just cleared, so the transcript starts at the top of it and
+  // the dock is told so. The banner then goes through the dock rather than
+  // around it, which is what keeps the two in step: printing it to stdout first
+  // and docking afterwards left the transcript anchored at the bottom of the
+  // window, eleven blank rows below a banner that the first line of the first
+  // reply then scrolled a row closer to the top.
+  dock.enable(fullScreen ? { row: 1 } : undefined);
+
+  dock.write(banner({ paint, workspace, backend: backendUrl(args), conversation }));
+  const onResize = () => dock.resize();
+  process.stdout.on("resize", onResize);
+
+  // Registered rather than left to the `finally`: these have to run on a
+  // SIGTERM and on a callback that threw, which never reach it.
+  hold.onTeardown(() => {
+    // Only reaches anything when a run is open, and the import is already
+    // resolved by then -- the module was loaded to start the run.
+    if (evaluating) void import("./eval.js").then(({ cancelEvalRuns }) => cancelEvalRuns());
+  });
+  hold.onTeardown(() => process.stdout.off("resize", onResize));
+  hold.onTeardown(() => dock.disable());
+  hold.onTeardown(() => rl.close());
+
+  // Everything the session prints goes through the dock, so a half-typed line
+  // survives whatever lands underneath it.
+  const say = (text) => dock.write(text);
+  const docked = dock.live ? createRenderer({ stream: dock.proxy(), paint, live }) : renderer;
+
+  /**
+   * Typing while the agent works is the whole point of the dock, so lines are
+   * queued instead of read one at a time: readline stays live for the entire
+   * session and anything typed mid-turn waits its turn rather than being
+   * echoed into the transcript by the tty.
+   */
+  const queued = [];
+  let borrow = null; // a permission prompt wants this line, not the queue
+  let wake = null; // the pump, parked until something arrives
+  let ended = false;
+
+  const nudge = () => {
+    if (!wake) return;
+    const resume = wake;
+    wake = null;
+    resume();
+  };
+
+  if (dock.live) rl.on("line", (raw) => {
+    const text = String(raw);
+    if (borrow) {
+      const answer = borrow;
+      borrow = null;
+      answer(text);
+      return;
+    }
+    queued.push(text);
+    nudge();
+  });
+
+  if (dock.live) rl.on("close", () => {
+    ended = true;
+    if (borrow) {
+      const answer = borrow;
+      borrow = null;
+      answer(null);
+    }
+    nudge();
+  });
+
+  /**
+   * What Ctrl+C means, which until now was not what the help text said.
+   *
+   * Readline in terminal mode eats `\x03` and emits its own `SIGINT` event --
+   * raw mode has already turned off the tty's own signal generation -- so the
+   * `process.on("SIGINT")` a turn installs to abort its fetch was unreachable
+   * from the keyboard. A press mid-answer therefore cancelled nothing and quit
+   * nothing: it marked the session ended and the shell came back whenever the
+   * answer happened to finish.
+   *
+   * So both doors lead here: readline's event for a keystroke, and a real
+   * signal for `kill -INT` and for the stretches where readline is not reading.
+   * The first press is always the small, recoverable thing that fits what is
+   * happening -- stop the turn, drop the half-typed line, leave the question
+   * unanswered. Quitting takes a second press, because the one thing a person
+   * cannot undo is the session ending under an answer they wanted.
+   */
+  let turn = null; // the in-flight turn's abort handle, when there is one
+  let evaluating = false; // a run is holding a harness child and a socket open
+  let quitting = false;
+  let armed = 0;
+
+  function quit() {
+    quitting = true;
+    ended = true;
+    turn?.abort();
+    if (borrow) {
+      const answer = borrow;
+      borrow = null;
+      answer(null);
+    }
+    nudge();
+    rl.close();
+  }
+
+  function interrupt() {
+    const now = Date.now();
+    const second = now - armed < QUIT_WINDOW_MS;
+    armed = now;
+    if (second) {
+      quit();
+      return;
+    }
+    if (turn) {
+      // The message belongs to `runTurn`, which knows whether the abort landed
+      // mid-answer or between events.
+      turn.abort();
+      return;
+    }
+    if (evaluating) {
+      // Stopping a run is closing what it holds open -- the harness child and
+      // the adapter's socket. The command itself then unwinds normally and the
+      // dock comes back, which is what "back to the prompt" means here.
+      process.stdout.write("\n  Stopping this eval run.\n");
+      void import("./eval.js").then(({ cancelEvalRuns }) => cancelEvalRuns());
+      return;
+    }
+    if (borrow) {
+      const answer = borrow;
+      borrow = null;
+      answer(null);
+      return;
+    }
+    if (!rl.closed && rl.line) {
+      rl.line = "";
+      rl.cursor = 0;
+      dock.refresh();
+      return;
+    }
+    say(paint.dim("  Press Ctrl+C again to exit\n"));
+  }
+
+  rl.on("SIGINT", interrupt);
+  hold.onInterrupt(interrupt);
+  hold.onTeardown(() => hold.onInterrupt(null));
+
+  /** The next typed line, or null once stdin is done and the queue is dry. */
+  async function nextQueued() {
+    for (;;) {
+      if (queued.length) return queued.shift();
+      if (ended) return null;
+      await new Promise((resume) => {
+        wake = resume;
+      });
+    }
+  }
+
+  /** Lend the one reader on stdin to a mid-turn question. */
+  function ask(question) {
+    if (ended) return Promise.resolve(null);
+    return new Promise((answer) => {
+      borrow = answer;
+      rl.setPrompt(question);
+      dock.refresh();
+    }).finally(() => {
+      rl.setPrompt(prompt);
+      dock.refresh();
+    });
+  }
+
+  try {
+    for (;;) {
+      const line = dock.live ? await nextQueued() : await nextLine(rl, prompt);
+      if (line === null || quitting) break;
+      const text = String(line).trim();
+      dock.echo(text);
+      if (!text) continue;
+
+      const slash = parseSlash(text);
+      if (slash) {
+        if (slash.name === "exit" || slash.name === "quit") break;
+        if (slash.name === "help") {
+          say(`${SLASH_HELP}\n\n`);
+          continue;
+        }
+        if (slash.name === "clear") {
+          // The banner comes back with it. On a screen of its own, a cleared
+          // session that says nothing about itself is indistinguishable from a
+          // shell -- and which workspace and conversation this is were the two
+          // things the clear just took away.
+          say(CLEAR_SCREEN);
+          say(banner({ paint, workspace, backend: backendUrl(args), conversation }));
+          continue;
+        }
+        if (slash.name === "new") {
+          conversation = await newConversation(args, token, workspace.id);
+          say(`${paint.dim(`New conversation ${conversation.id}`)}\n\n`);
+          continue;
+        }
+        if (slash.name === "conversations") {
+          const rows = await listConversations(args, token, workspace.id);
+          if (!rows.length) {
+            say(`${paint.dim("No conversations yet.")}\n\n`);
+            continue;
+          }
+          for (const row of rows.slice(0, 15)) {
+            const marker = String(row.id) === conversation.id ? paint.caret("\u276f") : " ";
+            say(`${marker} ${paint.dim(String(row.id))}  ${truncate(row.title || "Untitled", 48)}\n`);
+          }
+          say("\n");
+          continue;
+        }
+        if (slash.name === "resume") {
+          if (!slash.rest) {
+            say(`${paint.dim("Usage: /resume <conversation id>")}\n\n`);
+            continue;
+          }
+          try {
+            conversation = await openConversation(args, token, slash.rest);
+            say(`${paint.dim(`Resumed ${conversation.title}`)}\n\n`);
+          } catch (error) {
+            say(`${paint.red(error.message)}\n\n`);
+          }
+          continue;
+        }
+        if (slash.name === "eval") {
+          await runEval(slash.rest, {
+            args,
+            token,
+            dock,
+            rl,
+            paint,
+            say,
+            running: (on) => {
+              evaluating = on;
+            },
+          });
+          continue;
+        }
+        if (slash.name === "app") {
+          const url = `${frontendUrl(args)}/workbench/${conversation.id}`;
+          openUrl(url);
+          say(`${url}\n\n`);
+          continue;
+        }
+        say(`${paint.dim(`Unknown command ${text}. /help for the list.`)}\n\n`);
+        continue;
+      }
+
+      await runTurn({
+        args,
+        token,
+        workspaceId: workspace.id,
+        conversationId: conversation.id,
+        content: text,
+        renderer: docked,
+        paint,
+        ask: dock.live ? ask : undefined,
+        say: dock.live ? say : undefined,
+        onNote: dock.live ? (text) => dock.setNote(text) : undefined,
+        register: (handle) => {
+          turn = handle;
+        },
+      });
+      turn = null;
+      if (quitting) break;
+    }
+  } finally {
+    // One path, and it is the same one a signal takes: the teardowns are
+    // registered on the hold, so this is only the word that they should run.
+    hold.release();
+  }
+}