@khanglvm/relay 0.13.0 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "keywords": [
     "ai-agents",

package/skills/relay/SKILL.md

@@ -417,6 +417,18 @@ the matching `answers` value (e.g. `answers.approach = "a"` but
 `notes.approach = "actually B"` → the user means B). Reconcile them before
 generating output. The same channels appear under `draft` on timeout/cancel.
 
+**Don't let your shell truncate the result.** A board with several annotations
+prints a large JSON blob, and most agent shell tools cap stdout — so you silently
+get only the first few annotations and miss the rest. Two rules:
+
+- **Never pipe `rly wait`/`rly result` through `head`/`tail`/`sed`** (or any
+  output cap). That's exactly how annotations get dropped.
+- The full result is **always written to a file**, surfaced as the FIRST field
+  of the output: `"resultFile": "~/.relay/boards/<id>.result.json"`. If the
+  output looks cut off (or to be safe on any board with annotations), **read
+  that file with your file tool** instead of trusting stdout — it's the complete,
+  untruncated payload.
+
 ### Reply to annotations (agent → user conversation)
 
 ```sh
@@ -472,9 +484,31 @@ one yesno "Does this match your mental model?" + a textarea for notes.
 `rly history` (saved boards) · `rly spec <id>` (print spec to modify) ·
 `rly reuse <id>` (re-run blank) · `rly reopen <id>` (re-open with saved
 answers prefilled) · `rly reopen <id> --replies file.json` (add agent replies) ·
+`rly rescue <id>` (re-serve a dropped board on its ORIGINAL port) ·
 `rly list` / `rly open` / `rly stop <id>` · `rly rm <id>`.
 Multiple boards can run concurrently.
 
+### Continue a board — reconnect, NEVER recreate it
+
+When the user refers to a board that already exists — a URL/port ("the board on
+`127.0.0.1:59926`"), "the board from yesterday", "reopen it", "it disconnected"
+— do **NOT** run `rly ask`/`rly show`. A fresh board lands on a **new port**,
+**strands the user's open tab** on the dead one, and **loses their comments**.
+Find the real board and reconnect it:
+
+1. **Identify it** — `rly list` (running) and `rly history` (saved) print each
+   board's id, title, and url/port. Match by what the user said (port, title).
+2. **Tab still open but "connection lost"** (server died / machine slept) →
+   `rly rescue <id>`. Re-serves on the SAME port so that tab reconnects on its
+   own and re-flushes any comments it buffered — no new tab, no lost input.
+3. **Want a fresh tab** with prior answers prefilled → `rly reopen <id>` (also
+   reuses the board's last port, so an old tab still reconnects).
+4. `rly reuse <id>` is the ONLY "make a new board from this one" path — use it
+   solely for a deliberately blank re-run, never to "continue" or "reconnect".
+
+Rule of thumb: **an existing board is reconnected (`rescue`/`reopen`), never
+re-asked.** Only call `rly ask`/`rly show` for a genuinely new question.
+
 ### Live mutation — `rly update`
 
 Push a new spec to a running board. The page reloads and prefills answers from the

package/src/cli.js

@@ -15,6 +15,7 @@ import {
   loadRunning,
   removeRunning,
   isAlive,
+  saveResultFile,
   HOME,
 } from './store.js';
 import { runBoard } from './server.js';
@@ -76,6 +77,17 @@ function printJson(obj) {
   process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
 }
 
+// Print a terminal result. A board with many annotations produces a large JSON
+// payload, and an agent's shell harness commonly truncates long stdout — so the
+// agent silently misses annotations past the cut. We write the FULL result to a
+// sidecar file and surface its path FIRST (`resultFile`), so even a truncated
+// stdout shows where the complete payload is; the agent reads that file with its
+// file tool. Falls back to a plain print if the sidecar can't be written.
+function printResult(result) {
+  const resultFile = result && result.boardId ? saveResultFile(result.boardId, result) : null;
+  printJson(resultFile ? { resultFile, ...result } : result);
+}
+
 // Push-wake for `rly wait --notify-cmd`: run the agent's local shell command
 // once a TERMINAL result lands. Result JSON goes to the command's stdin;
 // RLY_BOARD_ID / RLY_STATUS / RLY_URL are exported. Same shape as the server's
@@ -225,7 +237,7 @@ async function runOrDetach(record, args) {
 
   const { done } = await runBoard({ id: record.id, port, open, timeoutSec });
   const result = await done;
-  printJson(result);
+  printResult(result);
   return exitCodeFor(result.status);
 }
 
@@ -349,7 +361,10 @@ async function cmdReopen(args) {
     printJson({ status: 'open', boardId: record.id, url: running.url, note: 'already running — browser re-opened' });
     return 0;
   }
-  return runOrDetach(record, args);
+  // Reuse the board's last port (unless the user forced one) so a tab still open
+  // from a previous run reconnects on its own instead of being stranded on a
+  // dead port. runBoard falls back to a random port if it's been taken.
+  return runOrDetach(record, { ...args, port: args.port ?? record.lastPort });
 }
 
 // Rescue a board whose browser tab is still open but disconnected (its server
@@ -487,7 +502,7 @@ async function cmdWait(args) {
   // Push-wake: run the agent's --notify-cmd after a TERMINAL result, then print.
   const finishResult = (result) => {
     if (notifyCmd) runNotifyCmd(notifyCmd, result);
-    printJson(result);
+    printResult(result);
     return exitCodeFor(result.status);
   };
 
@@ -503,7 +518,7 @@ async function cmdWait(args) {
       if (again?.result?.finishedAt) {
         return finishResult(again.result);
       }
-      printJson({
+      printResult({
         status: 'lost',
         boardId: id,
         draft: again?.draft ?? null,
@@ -549,7 +564,7 @@ async function cmdWaitLoop(id, deadline, opts) {
   const { whileActive, idleGrace, notifyCmd } = opts;
   const finishResult = (result) => {
     if (notifyCmd) runNotifyCmd(notifyCmd, result);
-    printJson(result);
+    printResult(result);
     return exitCodeFor(result.status);
   };
   while (Date.now() < deadline) {
@@ -564,7 +579,7 @@ async function cmdWaitLoop(id, deadline, opts) {
       if (again?.result?.finishedAt) {
         return finishResult(again.result);
       }
-      printJson({
+      printResult({
         status: 'lost',
         boardId: id,
         draft: again?.draft ?? null,
@@ -600,7 +615,7 @@ async function cmdWaitLoop(id, deadline, opts) {
 async function cmdResult(args) {
   const record = mustLoad(args._[0]);
   if (record.result && record.result.finishedAt) {
-    printJson(record.result);
+    printResult(record.result);
     return exitCodeFor(record.result.status);
   }
   const running = loadRunning(record.id);
@@ -610,10 +625,10 @@ async function cmdResult(args) {
     const out = { status: 'open', boardId: record.id, url: running.url, draft: record.draft ?? null };
     const presence = await fetchPresence(running.url);
     if (presence) out.presence = presence;
-    printJson(out);
+    printResult(out); // draft can hold many annotations — sidecar it too
     return 0;
   }
-  printJson({ status: 'lost', boardId: record.id, draft: record.draft ?? null });
+  printResult({ status: 'lost', boardId: record.id, draft: record.draft ?? null });
   return 5;
 }
 
@@ -1377,6 +1392,8 @@ USAGE
                                       --while-active [--idle-grace 180]: keep waiting past the deadline
                                         while the user is still viewing/focused & recently active
                                       --notify-cmd "<cmd>": run <cmd> on a terminal result (JSON on stdin)
+                                      NB: also writes the FULL result to "resultFile" (first field) —
+                                        read that file if your shell truncates stdout; never pipe to head/tail
   rly result <id>                     result/status now (includes live autosaved draft + presence while open)
   rly list [--json]                   running boards
   rly open [id]                       re-open the browser tab of a running board

package/src/server.js

@@ -693,9 +693,25 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     }
   });
 
+  // Bind the requested port (reopen/rescue reuse the board's last port so a
+  // still-open tab reconnects). If that port was grabbed by another process in
+  // the meantime, fall back to a random free one rather than failing to boot.
   await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(port, '127.0.0.1', resolve);
+    const bind = (p, allowFallback) => {
+      const onErr = (e) => {
+        if (allowFallback && e && e.code === 'EADDRINUSE' && p !== 0) {
+          bind(0, false); // desired port busy → random free one
+        } else {
+          reject(e);
+        }
+      };
+      server.once('error', onErr);
+      server.listen(p, '127.0.0.1', () => {
+        server.removeListener('error', onErr);
+        resolve();
+      });
+    };
+    bind(port, true);
   });
   const actualPort = server.address().port;
   const url = `http://127.0.0.1:${actualPort}/`;

package/src/store.js

@@ -53,9 +53,25 @@ export function loadBoard(id) {
   }
 }
 
+// Write the full result to its own file (just the result, not the whole board
+// record with its bulky spec). An agent's shell may truncate `rly wait`/`result`
+// stdout for a board with many annotations — this file is the complete payload
+// it can read with a file tool instead. Returns the path (null on failure).
+export function saveResultFile(id, result) {
+  try {
+    ensureDirs();
+    const p = path.join(BOARDS_DIR, `${id}.result.json`);
+    fs.writeFileSync(p, JSON.stringify(result, null, 2));
+    return p;
+  } catch {
+    return null;
+  }
+}
+
 export function deleteBoard(id) {
   try {
     fs.unlinkSync(boardPath(id));
+    try { fs.unlinkSync(path.join(BOARDS_DIR, `${id}.result.json`)); } catch { /* no sidecar */ }
     return true;
   } catch {
     return false;
@@ -66,7 +82,7 @@ export function listBoards(limit = 20) {
   ensureDirs();
   const records = [];
   for (const f of fs.readdirSync(BOARDS_DIR)) {
-    if (!f.endsWith('.json')) continue;
+    if (!f.endsWith('.json') || f.endsWith('.result.json')) continue; // skip result sidecars
     try {
       records.push(JSON.parse(fs.readFileSync(path.join(BOARDS_DIR, f), 'utf8')));
     } catch {