premanmcp 1.1.6 → 1.1.8

package/bin/agent.js

@@ -84,12 +84,13 @@ 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";
+// The alternate screen buffer is deliberately not used, and the sequences for
+// it are deliberately not defined, so that reaching for one is a decision
+// rather than an autocomplete. It gave a session a screen of its own -- a
+// second `preman` could not be scrolled back into the first -- by holding
+// exactly one screen and keeping no history, which meant a reply that ran past
+// the top of the window could not be scrolled back to either. A transcript is
+// the wrong thing to put in a buffer that forgets.
 const SHOW_CURSOR = "\u001b[?25h";
 const RELEASE_REGION = "\u001b[r";
 
@@ -217,6 +218,188 @@ export function artifactLine(artifact) {
   return url ? `${truncate(label, 72)} — ${url}` : truncate(label, 100);
 }
 
+/**
+ * The route an endpoint sits on, normalised so two saved requests that hit the
+ * same place collapse onto one line.
+ *
+ * The same rule the app groups by, deliberately: a workspace that reads as 84
+ * routes in the browser and 284 rows here is two different answers to one
+ * question. A saved URL is often a template (`{{baseUrl}}/v1/users`) rather
+ * than something `URL` will parse, which is why the fallback strips the
+ * template head by hand instead of giving up.
+ */
+export function endpointRoutePath(endpoint) {
+  const raw = String(endpoint?.url || endpoint?.name || "/").trim();
+  let path = raw;
+  try {
+    path = new URL(raw).pathname || "/";
+  } catch {
+    path = raw.replace(/^\{\{[^}]+\}\}/, "").split(/[?#]/, 1)[0] || "/";
+  }
+  if (!path.startsWith("/")) path = `/${path}`;
+  return path.length > 1 ? path.replace(/\/+$/, "") : path;
+}
+
+// The three buckets the server counts in and the model writes its reply from.
+// Matching them exactly is what keeps "87 failing" in the prose and the heading
+// above the rows from being two different numbers.
+const FAILING_RUNS = new Set(["failed", "error", "fail"]);
+const PASSING_RUNS = new Set(["passed", "pass", "ok", "success"]);
+
+/** Which of the three buckets a last-run status falls in. */
+export function endpointBucket(lastRun) {
+  const status = String(lastRun || "").trim().toLowerCase();
+  if (!status) return "untested";
+  if (FAILING_RUNS.has(status)) return "failing";
+  if (PASSING_RUNS.has(status)) return "passing";
+  return "untested";
+}
+
+// Failing first because it is the only bucket anybody acts on, then untested,
+// then passing -- the order the model already writes its own summary in.
+const BUCKET_ORDER = ["failing", "untested", "passing"];
+const BUCKET_LABELS = { failing: "Failing", untested: "Untested", passing: "Passing" };
+const METHOD_ORDER = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+
+const methodRank = (method) => {
+  const at = METHOD_ORDER.indexOf(String(method || "GET").trim().toUpperCase());
+  return at === -1 ? METHOD_ORDER.length : at;
+};
+
+/**
+ * Every endpoint the turn returned, once, as routes.
+ *
+ * A list of 284 arrives as thirteen separate tool calls, because the tool caps
+ * a page at 25 rows and the model pages through it. Ids are deduplicated
+ * because overlapping pages are a model's decision and not a thing to render
+ * twice; routes are collapsed because that is what turns request history back
+ * into an API. A route whose saved requests disagree about their last run
+ * takes the worst of them, since "one of these is failing" is the fact worth
+ * putting on a line somebody is scanning for failures.
+ */
+export function mergeEndpoints(artifacts = []) {
+  const seen = new Set();
+  const endpoints = [];
+  // The furthest page reached in each sweep the model made. A turn that lists
+  // everything is several sweeps -- one per status -- and every page but the
+  // last of each carries has_more, so believing all of them would claim the
+  // catalogue was cut short on exactly the turns that read all of it.
+  const sweeps = new Map();
+  let saved = 0;
+
+  for (const artifact of artifacts) {
+    saved = Math.max(saved, Number(artifact?.total_count) || 0);
+    const key = `${artifact?.status ?? ""}|${artifact?.query ?? ""}`;
+    const offset = Number(artifact?.offset) || 0;
+    const reached = offset + (artifact?.endpoints?.length || 0);
+    const furthest = sweeps.get(key);
+    if (!furthest || offset >= furthest.offset) {
+      sweeps.set(key, {
+        offset,
+        more: Boolean(artifact?.has_more) || (Number(artifact?.matched_count) || 0) > reached,
+      });
+    }
+    for (const endpoint of artifact?.endpoints || []) {
+      const id = String(endpoint?.id ?? "");
+      if (id && seen.has(id)) continue;
+      if (id) seen.add(id);
+      endpoints.push(endpoint);
+    }
+  }
+
+  const routes = new Map();
+  const counts = { failing: 0, untested: 0, passing: 0 };
+  for (const endpoint of endpoints) {
+    const method = String(endpoint?.method || "GET").trim().toUpperCase();
+    const path = endpointRoutePath(endpoint);
+    const bucket = endpointBucket(endpoint?.last_run);
+    counts[bucket] += 1;
+    const key = `${method} ${path}`;
+    const found = routes.get(key);
+    if (!found) {
+      routes.set(key, { method, path, bucket, count: 1 });
+      continue;
+    }
+    found.count += 1;
+    if (BUCKET_ORDER.indexOf(bucket) < BUCKET_ORDER.indexOf(found.bucket)) found.bucket = bucket;
+  }
+
+  const ordered = [...routes.values()].sort(
+    (left, right) => methodRank(left.method) - methodRank(right.method) || left.path.localeCompare(right.path)
+  );
+  return { endpoints, routes: ordered, counts, saved, more: [...sweeps.values()].some((s) => s.more) };
+}
+
+/**
+ * The endpoints of a turn, drawn for a terminal.
+ *
+ * Until now this surface printed the artifact's title and dropped its payload,
+ * so a request to list 284 endpoints produced thirteen lines reading "showing
+ * 51-75 of 197" and not one endpoint. The model's reply said the list was
+ * above, and in the app it is -- the card renders the rows. Here there is no
+ * card and no page to send anybody to: the transcript is the whole surface, so
+ * the rows have to land in it.
+ *
+ * Piped output is a different contract and gets a different shape: one line per
+ * endpoint, ungrouped and never truncated, because on the other end of a pipe
+ * this is something being grepped rather than read.
+ */
+export function endpointsBlock(artifacts, { columns = 80, live = true, paint } = {}) {
+  const ink = paint || makePaint(false);
+  const { endpoints, routes, counts, saved, more } = mergeEndpoints(artifacts);
+  if (!endpoints.length) return "";
+
+  if (!live) {
+    const lines = endpoints.map((endpoint) => {
+      const method = String(endpoint?.method || "GET").trim().toUpperCase();
+      const where = String(endpoint?.url || "").trim() || endpointRoutePath(endpoint);
+      return `  ${endpointBucket(endpoint?.last_run).padEnd(8)} ${method.padEnd(7)} ${where}`;
+    });
+    return `${lines.join("\n")}\n`;
+  }
+
+  const shown = endpoints.length;
+  const head = [`${shown} endpoint${shown === 1 ? "" : "s"}`];
+  if (saved > shown) head[0] = `${shown} of ${saved} endpoints`;
+  if (routes.length !== shown) head.push(`${routes.length} route${routes.length === 1 ? "" : "s"}`);
+  for (const bucket of BUCKET_ORDER) {
+    if (counts[bucket]) head.push(`${counts[bucket]} ${bucket}`);
+  }
+
+  const width = Math.max(24, columns);
+  // Truncated before it is painted, not after: the colour runs are bytes that
+  // `truncate` would count and cut through, and half an escape sequence on a
+  // narrow window is a terminal left in the wrong colour.
+  const lines = [
+    `  ${ink.bold("Endpoints")} ${ink.dim(`\u00b7 ${truncate(head.join(" \u00b7 "), Math.max(8, width - 14))}`)}`,
+  ];
+  const method = Math.min(7, Math.max(...routes.map((route) => route.method.length)));
+  const room = Math.max(8, width - 6 - method - 2);
+
+  for (const bucket of BUCKET_ORDER) {
+    const group = routes.filter((route) => route.bucket === bucket);
+    if (!group.length) continue;
+    lines.push("", `  ${ink.bold(BUCKET_LABELS[bucket])} ${ink.dim(`(${counts[bucket]})`)}`);
+    for (const route of group) {
+      // A hollow mark for untested, because "no run yet" is an absence rather
+      // than a result, and a filled dot in any colour reads as one.
+      const dot =
+        bucket === "failing" ? ink.red("\u25cf") : bucket === "passing" ? ink.green("\u25cf") : ink.dim("\u25cb");
+      const also = route.count > 1 ? ink.dim(` (${route.count})`) : "";
+      lines.push(`    ${dot} ${ink.dim(route.method.padEnd(method))}  ${truncate(route.path, room)}${also}`);
+    }
+  }
+
+  // Said once, at the end, rather than thirteen times on the way: the model
+  // stopped paging before the catalogue ran out, and the rest is a command
+  // away rather than a page in a browser this session cannot open.
+  if (more) {
+    const rest = `More were not fetched. ${cliInvocation()} endpoints list for the rest.`;
+    lines.push("", `  ${ink.dim(truncate(rest, width - 2))}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
 /** The permission questions in a finished turn, in the order they were asked. */
 export function permissionQuestions(artifacts = []) {
   return (Array.isArray(artifacts) ? artifacts : []).filter(
@@ -268,6 +451,13 @@ function makePaint(enabled) {
  */
 export function createRenderer({ stream = process.stdout, paint, live } = {}) {
   const isLive = live ?? Boolean(stream.isTTY);
+  // Whether there is a window here, which is a different question from whether
+  // it may be coloured. `NO_COLOR=1` is a widespread way of saying "no colour",
+  // and it used to reach layout as "this is a pipe" -- so somebody who set it
+  // and sat down at a terminal got the shape meant for `grep`. Colour is the
+  // palette's business; how wide the window is and whether rows may be grouped
+  // and clipped is this.
+  const isTerminal = Boolean(stream.isTTY);
   const ink = paint || makePaint(isLive);
   let timer = null;
   let frame = 0;
@@ -277,6 +467,8 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
   let stallTick = 0;
   let wroteReply = false;
   let atLineStart = true;
+  // Endpoint pages, held until the turn has something else to say.
+  let pages = [];
 
   function stopStall() {
     if (!stall) return false;
@@ -312,6 +504,26 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
     stream.write(`${CLEAR_LINE}${tint(`${word}${runOn} ${dots}`)}`);
   }
 
+  /**
+   * Draw the endpoint pages collected so far, as one table.
+   *
+   * Held rather than printed on arrival because a single "list my endpoints"
+   * is thirteen tool calls, and thirteen tables of 25 rows is not a list --
+   * it is the pagination read aloud. Flushed by whatever speaks next, so the
+   * rows still land *above* the reply that refers to them.
+   */
+  function flushPages() {
+    if (!pages.length) return;
+    const held = pages;
+    pages = [];
+    const block = endpointsBlock(held, { columns: stream.columns || 80, live: isTerminal, paint: ink });
+    if (!block) return;
+    clearSpinner();
+    if (!atLineStart) stream.write("\n");
+    stream.write(block);
+    atLineStart = true;
+  }
+
   function draw() {
     if (!isLive || !label) return;
     const spin = FRAMES[frame % FRAMES.length];
@@ -347,8 +559,16 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
       }
     },
     artifact(item) {
+      // Endpoint pages are the one artifact whose payload is the point, and
+      // they arrive one page at a time, so they are collected rather than
+      // drawn. Everything else is a card this surface summarises in a line.
+      if (item && item.type === "endpoints" && Array.isArray(item.endpoints)) {
+        pages.push(item);
+        return;
+      }
       const line = artifactLine(item);
       if (!line) return;
+      flushPages();
       clearSpinner();
       if (!atLineStart) stream.write("\n");
       stream.write(`  ${ink.cyan("●")} ${line}\n`);
@@ -357,6 +577,7 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
     delta(text) {
       const chunk = String(text ?? "");
       if (!chunk) return;
+      flushPages();
       clearSpinner();
       if (!wroteReply) {
         stream.write("\n");
@@ -373,18 +594,23 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
       this.delta(body);
     },
     note(text) {
+      flushPages();
       clearSpinner();
       if (!atLineStart) stream.write("\n");
       stream.write(`${ink.dim(String(text))}\n`);
       atLineStart = true;
     },
     error(text) {
+      flushPages();
       clearSpinner();
       if (!atLineStart) stream.write("\n");
       stream.write(`${ink.red(String(text))}\n`);
       atLineStart = true;
     },
     end() {
+      // The backstop: a turn that listed endpoints and then said nothing at
+      // all still has to put them on the screen.
+      flushPages();
       clearSpinner();
       if (!atLineStart) stream.write("\n");
       if (wroteReply) stream.write("\n");
@@ -705,7 +931,14 @@ export function holdTerminal({ stream = process.stdout, footer = () => "" } = {}
     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}`));
+    // No `ESC[?1049l` here any more, and its absence is load-bearing rather
+    // than tidying. The session never enters the alternate screen, so leaving
+    // it would be addressed to a buffer nobody is on -- and the sequence is
+    // not inert: it restores the cursor as DECRC does, from the same saved
+    // slot the dock writes the transcript's position into with `ESC7`. Sent on
+    // the shell's own screen it would drag the cursor back up into the
+    // transcript and print the resume footer over the conversation.
+    if (live) safely(() => stream.write(`${RELEASE_REGION}${SHOW_CURSOR}${CLEAR_TITLE}`));
     safely(() => {
       const text = footer();
       if (text) stream.write(text);
@@ -829,6 +1062,11 @@ export function createDock({
   // 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,
@@ -838,6 +1076,82 @@ export function createDock({
   /** 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?
    *
@@ -983,16 +1297,32 @@ export function createDock({
   return {
     live,
 
-    /** Reserve the bottom rows and remember where the transcript is. */
-    enable() {
+    /**
+     * 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;
-      stream.write("\n".repeat(DOCK_ROWS));
+      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[${floor()};1H`);
+      stream.write(`\u001b[${at.row};${at.column}H`);
       stream.write("\u001b7");
       frame();
     },
@@ -1023,12 +1353,18 @@ export function createDock({
      */
     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();
     },
 
@@ -1096,10 +1432,18 @@ export function createDock({
       painted = null;
       if (!roomy()) return;
       stream.write(`\u001b[1;${floor()}r`);
-      // The transcript's saved position, re-anchored rather than replaced. A
-      // mid-line `delta` resumed at column 1 of the floor row before this, so a
-      // sentence in flight during a window drag was orphaned.
-      stream.write(`\u001b[${floor()};1H`);
+      // 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();
     },
@@ -1122,9 +1466,35 @@ export function createDock({
       }
       if (!open) return;
       open = false;
+      at = null;
       const { rows } = size();
       stream.write("\u001b[r");
-      stream.write(`\u001b[${rows};1H\u001b[2K`);
+      // Every row the furniture owned, not just the last one. On the alternate
+      // screen clearing one row was enough because leaving the buffer threw the
+      // whole screen away; on the shell's own screen the chrome is real output,
+      // and a composer box and a status strip left sitting under the final
+      // prompt are the last thing the session shows.
+      //
+      // Guarded on having painted, because that is the only thing that says
+      // these rows were ever the dock's. In a window too short to dock in
+      // nothing is drawn at all -- the session is a plain prompt -- and erasing
+      // four rows of a five-row window there would take somebody's transcript
+      // with it. Clamped to the live window for the same reason `resize` is:
+      // after a shrink, `painted.rows` names rows that no longer exist.
+      if (painted) {
+        const bottom = Math.min(painted.rows, rows);
+        const top = Math.max(1, bottom - DOCK_ROWS + 1);
+        for (let row = top; row <= bottom; row += 1) {
+          stream.write(`\u001b[${row};1H\u001b[2K`);
+        }
+        // Carry on immediately below the transcript rather than at the bottom
+        // of the window, so the resume footer and the shell prompt follow the
+        // conversation instead of a gap where the dock used to be.
+        stream.write(`\u001b[${top};1H`);
+      } else {
+        stream.write(`\u001b[${rows};1H\u001b[2K`);
+      }
+      painted = null;
       stream.write(CLEAR_TITLE);
     },
   };
@@ -1626,10 +1996,27 @@ export async function agentCommand(commandArgs = [], { authenticate = authentica
     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);
+  // The session shares the shell's screen rather than taking one of its own.
+  //
+  // It used to enter the alternate screen, the way a full-screen app does, and
+  // that cost the one thing a chat transcript needs: the alternate buffer keeps
+  // no history, so a reply that ran past the top of the window was not scrolled
+  // away, it was discarded. There was nothing to scroll back to in any
+  // terminal, because the buffer holds exactly one screen.
+  //
+  // On the shell's own screen the transcript is ordinary output, so the wheel,
+  // Page Up, find and select-to-copy all work on a conversation the way they
+  // work on any other command's output. Keeping the composer docked costs none
+  // of it: the dock's scrolling region starts at row 1, and a region whose top
+  // margin is the first row is the case where a terminal pushes the lines it
+  // scrolls past into the scrollback instead of dropping them.
+  //
+  // What this gives up is what the alternate screen was for -- a new session
+  // can now be scrolled back into a finished one. That is the trade every
+  // other command makes with its own output, and it is the cheaper way round:
+  // scrolling into an old session is something a reader can see and scroll out
+  // of, and a transcript that cannot be scrolled at all is not.
+  const interactive = 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.
@@ -1643,15 +2030,11 @@ export async function agentCommand(commandArgs = [], { authenticate = authentica
       // 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 "";
+      if (!interactive || !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}`);
-
-  process.stdout.write(banner({ paint, workspace, backend: backendUrl(args), conversation }));
-
   const dock = createDock({
     stream: process.stdout,
     paint,
@@ -1660,7 +2043,15 @@ export async function agentCommand(commandArgs = [], { authenticate = authentica
   const prompt = `${paint.caret("\u276f")} `;
   const rl = createInterface({ input: process.stdin, output: process.stdout, prompt });
   dock.attach(rl);
+  // No start row, because there is no cleared screen to start at the top of any
+  // more. Told nothing, the dock makes room by scrolling the shell up by its
+  // own height and carries on at the floor -- which keeps whatever was on the
+  // screen before, the prompt the session was launched from included, instead
+  // of erasing it. The banner still goes through the dock rather than around
+  // it, which is what keeps the two in step.
   dock.enable();
+
+  dock.write(banner({ paint, workspace, backend: backendUrl(args), conversation }));
   const onResize = () => dock.resize();
   process.stdout.on("resize", onResize);
 

package/bin/connect/pairing.js

@@ -51,6 +51,32 @@ async function verifyKey(args, apiKey) {
   return { pairCode: "", pairingId: "", stale: result.status_code === 401 };
 }
 
+/**
+ * Redeem the pair code from this terminal.
+ *
+ * The link used to be closed by the agent calling `preman_status`, but the MCP
+ * server is a pure bridge now and defines no such tool, so nothing has made this
+ * call since. This terminal holds both halves anyway — the key and the code it
+ * just minted — so it closes the link itself rather than waiting for a call that
+ * no longer happens. Failure is not fatal: the config is already written.
+ */
+export async function redeemPairCode(args, agent, apiKey, pairCode) {
+  if (!pairCode) return false;
+  const result = await callBackendJson(args, "POST", "/workbench/coding-agent/heartbeat", {
+    token: apiKey,
+    json: {
+      pair_code: pairCode,
+      agent: agent.id,
+      project_path: process.cwd(),
+      source: "premanmcp",
+    },
+  });
+  if (!result.ok) {
+    process.stdout.write(`Note: could not close the link (${result.status_code}).\n`);
+  }
+  return Boolean(result.ok);
+}
+
 /** Whichever of the two ways to learn the backend still accepts this key. */
 export async function checkKeyAndPair(args, agent, apiKey) {
   return args.has("--no-pair")

package/bin/connect.js

@@ -49,7 +49,7 @@ import {
   renderCodexToml,
   verifyWrittenConfig,
 } from "./connect/configs.js";
-import { checkKeyAndPair, refreshStaleCredentials } from "./connect/pairing.js";
+import { checkKeyAndPair, redeemPairCode, refreshStaleCredentials } from "./connect/pairing.js";
 import {
   autoCheckIn,
   lastLine,
@@ -258,6 +258,8 @@ export async function connectCommand(commandArgs) {
     );
   }
 
+  const redeemed = await redeemPairCode(args, agent, apiKey, pairCode);
+
   // A non-interactive run can still be handed the credential up front, so this
   // stays reachable; the prompt inside only fires when there is a TTY, and by
   // then onboarding is done.
@@ -273,6 +275,7 @@ export async function connectCommand(commandArgs) {
     serverConfig,
     projectInstall,
     pairingId,
+    preLinked: redeemed,
   });
   // The agent goes back to the caller because `onboard` runs steps after this one
   // that need to know which agent to drive, and asking twice is a question we
@@ -394,7 +397,7 @@ async function establishCheckIn(
   args,
   agent,
   apiKey,
-  { serverName, written, serverConfig, projectInstall = false, pairingId = "" }
+  { serverName, written, serverConfig, projectInstall = false, pairingId = "", preLinked = false }
 ) {
   const notes = [];
   // Both set only when this directory redirects the agent: where it can be
@@ -402,6 +405,9 @@ async function establishCheckIn(
   let elsewhere = null;
   let blockedHere = "";
   const done = (linked) => ({ linked, blockedHere });
+  // Already linked by the terminal that wrote the config: nothing to self-test
+  // into, no window to open, and no check-in to wait for.
+  if (preLinked) return done(true);
   const ticker = pollTicker();
   const say = (text) => {
     ticker.end();

package/bin/eval.js

@@ -470,6 +470,18 @@ export function runDir(cwd, job) {
   return path.join(cwd, "artifacts", "results", String(job.suite), String(job.run));
 }
 
+/**
+ * Where the suite's own output lands — the parent of every run directory.
+ *
+ * Only ever joined with a name from `SUITE_ARTIFACTS`. The same directory also
+ * holds assert-ai's versioned `artifacts/<stage>/v0001/` tree, which nothing
+ * reads back and which a device walking the directory would start uploading;
+ * naming the files explicitly is what keeps that out.
+ */
+export function suiteDir(cwd, job) {
+  return path.join(cwd, "artifacts", "results", String(job.suite));
+}
+
 /**
  * The four stages as one activity list, current stage active, earlier ones done.
  *
@@ -522,6 +534,21 @@ export const RUN_ARTIFACTS = [
   "artifacts.json",
 ];
 
+/**
+ * The files that describe the bank rather than one run.
+ *
+ * These are the cases themselves and the rubric they are scored against, and
+ * they live one level up from the run directory because every run of the suite
+ * shares them. Without them the store holds verdicts with no record of what was
+ * asked: the dashboard can say "case 3 failed" and cannot say what case 3 was.
+ *
+ * No scope is sent with an upload. The server derives it from the filename
+ * (`eval_runner_artifacts.scope_of`), files these under the suite rather than
+ * the run, and applies its own write-once rule — so a second run of the same
+ * suite offers them again and the server declines to rewrite history.
+ */
+export const SUITE_ARTIFACTS = ["taxonomy.json", "test_set.jsonl"];
+
 /**
  * Upload the artifacts that changed since last time.
  *
@@ -536,10 +563,15 @@ export const RUN_ARTIFACTS = [
  * success and the next tick retries.
  */
 export async function syncArtifacts(job, cwd, sent, { call, log = () => {}, lease } = {}) {
-  const dir = runDir(cwd, job);
+  // Both sets on the same tick, not the suite files at the end: `systematize`
+  // and `test_set` finish before the first case does, so a run that dies
+  // halfway would otherwise publish scores for cases it never published.
+  const sources = [
+    ...RUN_ARTIFACTS.map((name) => [name, path.join(runDir(cwd, job), name)]),
+    ...SUITE_ARTIFACTS.map((name) => [name, path.join(suiteDir(cwd, job), name)]),
+  ];
   let uploaded = 0;
-  for (const name of RUN_ARTIFACTS) {
-    const file = path.join(dir, name);
+  for (const [name, file] of sources) {
     let mark;
     try {
       const stat = statSync(file);
@@ -561,7 +593,18 @@ export async function syncArtifacts(job, cwd, sent, { call, log = () => {}, leas
     form.set("lease_token", lease);
     form.set("name", name);
     form.set("file", new Blob([body]), name);
-    const result = await call(`/workbench/coding-agent/local-runner/evals/${job.id}/artifacts`, form);
+    // A refused upload and an unsendable one are the same situation to this
+    // loop -- the file is still on disk, unrecorded in `sent`, and the next
+    // tick will offer it again. They are not the same to `callBackendJson`,
+    // which answers the first and *throws* the second, so without this a
+    // backend that blinks mid-run takes the run's process down with it.
+    let result;
+    try {
+      result = await call(`/workbench/coding-agent/local-runner/evals/${job.id}/artifacts`, form);
+    } catch (error) {
+      log(`upload of ${name} could not be sent: ${error.message}; will retry`);
+      continue;
+    }
     if (result.status_code === 409) return { uploaded, lost: true };
     if (!result.ok) {
       log(`upload of ${name} answered ${result.status_code}; will retry`);
@@ -629,6 +672,39 @@ export function readProgress(cwd, job) {
  * Returns "" when there is nothing wrong, so the caller can tell "fine" from
  * "unreadable".
  */
+/**
+ * What this run alone did, out of counters that belong to the whole invocation.
+ *
+ * The adapter is opened once and every run in the batch shares it, so its
+ * counters are lifetime totals -- which is the honest thing for them to be, and
+ * the wrong thing to hand a guard asking about one run. Read as totals they
+ * fail a run for the run before it: a batch where the first eval made one tool
+ * call and the second legitimately made none reported "the agent made 1 tool
+ * call(s) and none of them reached the transcript" against the second, quoting
+ * the first one's number. The same arithmetic hides the opposite fault --
+ * `reached` never returns to zero after any run reaches the agent, so a later
+ * run where every single turn failed cannot be caught at all.
+ *
+ * Subtracting rather than resetting: `adapterStats()` is the adapter's own
+ * lifetime record and other readers rely on it being exactly that. Zeroing
+ * shared state from inside one run would also be wrong the day two overlap.
+ *
+ * `lastFailure` is passed through rather than differenced. It is a string, and
+ * the most recent one is the useful one whenever `failures` moved at all.
+ */
+export function statsSince(baseline, stats) {
+  if (!stats) return stats;
+  if (!baseline) return stats;
+  const since = (key) => Math.max(0, Number(stats[key] || 0) - Number(baseline[key] || 0));
+  return {
+    ...stats,
+    turns: since("turns"),
+    reached: since("reached"),
+    failures: since("failures"),
+    toolCalls: since("toolCalls"),
+  };
+}
+
 export function missingToolEvidence(dir, stats) {
   const forwarded = Number(stats?.toolCalls);
   if (!Number.isFinite(forwarded) || forwarded <= 0) return "";
@@ -903,6 +979,10 @@ export async function executeEvalRun(
   // Before the harness starts, not after it ends: a run that dies mid-way would
   // otherwise leave its last steps to appear under whichever run came next.
   stepFeed.reset();
+  // Same reason, for the counters that cannot be reset because the adapter they
+  // belong to is shared with every other run in this batch. See `statsSince`.
+  const adapterBaseline = adapterStats();
+  const baselineAt = adapterBaseline ? { ...adapterBaseline } : null;
 
   const timeout = Math.min(RUN_TIMEOUT_MS, RUN_TIMEOUT_CAP_MS);
   const child = spawn(python.command, [...python.argv, HARNESS_PATH, "run", "--config", laid.configPath], {
@@ -965,6 +1045,15 @@ export async function executeEvalRun(
         // before it spends an uplink on artifacts nobody will accept.
         const synced = await syncArtifacts(job, laid.cwd, sent, { call, log, lease });
         if (synced.lost) return lose("lease rejected an upload");
+      } catch (error) {
+        // Nothing this tick reports is worth the run for. It is liveness: the
+        // stages and steps somebody watching sees, and a copy of artifacts the
+        // final sync sends again anyway. Nobody awaits this callback, so an
+        // escaping rejection is an *unhandled* one, and Node's answer to that
+        // is to end the process -- killing a harness mid-stage, skipping the
+        // completion callback, and leaving the run to sit until its lease
+        // lapses. A logged tick and a live run is the better trade.
+        log(`eval ${job.id}: progress tick failed (${error.message}); the run continues`);
       } finally {
         ticking = false;
       }
@@ -1022,7 +1111,7 @@ export async function executeEvalRun(
     // Turns are counted rather than failures, because a run where the agent
     // answered some of the time is a real measurement of a flaky agent and
     // deciding otherwise here would throw away the finding.
-    const stats = adapterStats();
+    const stats = statsSince(baselineAt, adapterStats());
     // `reached` rather than `turns`: the adapter counts a turn when it starts
     // one, so a run where every turn failed has as many turns as cases.
     if (stats && (stats.reached ?? stats.turns) === 0 && stats.failures > 0) {

package/bin/runner.js

@@ -869,6 +869,19 @@ export async function runnerLoop(
             try {
               if (kind === "eval") await runLeasedEval(args, state, job, { log, headless });
               else await executeJob(args, state, job, { log, fullAccess });
+            } catch (error) {
+              // Attribution, not recovery. Both executors report their own
+              // failures and return; a throw escaping one is a bug in it, and
+              // letting it reach the stream's catch below labels that bug
+              // `stream dropped` -- blaming the network for something that
+              // happened on this machine, which is the wrong place to look and
+              // the reason the last one took all evening to find.
+              //
+              // Counted as an attempt below rather than halting the batch. A
+              // crash that stopped the loop silently is what the caller then
+              // reports as a finished run, which is the failure this is here
+              // to stop being invisible.
+              log(`${kind} ${job.id} failed unexpectedly: ${error?.stack || error.message}`);
             } finally {
               busy = false;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "PreMan CLI and stdio proxy for PreMan's hosted MCP server",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "test": "npm run build && npm run test:proxy",
     "test:proxy": "node --test scripts/smoke-proxy.mjs",
     "test:connect": "node scripts/smoke-connect.mjs",
+    "test:connect-heartbeat": "node scripts/smoke-connect-heartbeat.mjs",
     "test:node": "node --test --test-timeout=90000 scripts/smoke-account.mjs scripts/smoke-agent-session.mjs scripts/smoke-agent-dock.mjs scripts/smoke-terminal-lifecycle.mjs scripts/smoke-cli-entrypoint.mjs scripts/smoke-cli-update.mjs scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-eval.mjs scripts/smoke-eval-behaviors.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-onboard-opening.mjs scripts/smoke-local-detect.mjs scripts/smoke-agent-target.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs scripts/smoke-desktop-session.mjs scripts/smoke-api-tools.mjs scripts/smoke-tests-workbench.mjs scripts/smoke-bin-scope.mjs scripts/smoke-shared-errors.mjs scripts/smoke-process-title.mjs scripts/smoke-predict.mjs",
     "test:dmg": "node --test --test-timeout=300000 scripts/smoke-install-desktop-volume.mjs"
   },