@khanglvm/relay 0.14.1 → 0.15.0

package/README.md

@@ -80,10 +80,11 @@ unchanged; pick whichever surface fits.
 | "Type *done* when finished reviewing" | A Submit button; answers, notes, and inline comments returned as JSON |
 | Feedback = another wall of text | Click any chart point, diagram node, table cell, or sentence to comment — the agent replies and the thread grows on the board |
 
-Everything autosaves in real time (drafts survive timeouts), multiple boards
-run at once, and the package has **zero npm runtime dependencies** — plain
-Node ≥ 18. Browser-side Chart.js, Mermaid, and Viz.js assets are vendored in
-the package and lazy-loaded offline when a board actually needs them.
+Everything autosaves in real time, detached board links keep serving after
+agent timeouts, multiple boards run at once, and the package has **zero npm
+runtime dependencies** — plain Node ≥ 18. Browser-side Chart.js, Mermaid, and
+Viz.js assets are vendored in the package and lazy-loaded offline when a board
+actually needs them.
 
 ## Learn more
 
@@ -92,7 +93,7 @@ the package and lazy-loaded offline when a board actually needs them.
 | `rly help` | every command at a glance |
 | `rly git pick` / `rly git cherry-pick` | choose commit actions and rank the order directly on a board; add `--code` to cherry-pick with split code review and per-hunk Apply/Skip/Hold |
 | `rly git conflict [files…]` | auto-detect unmerged conflict files, or open specific local paths, and return resolved content in `result.blockEdits` |
-| `rly share <board-id>` | activate/list/revoke same-Wi-Fi reviewer or collaborator links for a running browser board |
+| `rly share <board-id>` | activate/list/revoke same-Wi-Fi collaborator, reference-only reviewer, or read-only links for a running browser board |
 | `rly view <file.md> …` | open a quick read-only board that renders local markdown file(s), data files, or PDFs — library-free; great for plans, READMEs, reports, quotes |
 | `rly install --target <agent>` | write relay's rules into an agent's instruction file — `claude` `codex` `cursor` `copilot` `kiro` `windsurf` `cline` `gemini` `opencode` `droid` `agents`; `--all`, `--scope`, `--print`, `--list` |
 | `rly upgrade` | update the CLI **and** refresh the skill in one step (safe around open boards; `--dry-run`, `--cli-only`, `--skill-only`) |
@@ -171,9 +172,13 @@ npm test     # smoke tests with no external services (spawns real servers, fake-
   embedded in the payload.
 - **`pdf` block** — render local `.pdf` files or PDF URLs inline. Local PDFs
   stream from the board server and are never embedded in the page payload.
-- **Durable drafts / rescue** — every autosave mirrors to `localStorage`; a
-  board whose connection drops blocks further input instead of losing it, and
-  `rly rescue <id>` re-serves on the same port so an open tab reconnects.
+- **Durable boards / rescue** — detached boards keep serving after timeout
+  until Submit or `rly stop`; every autosave mirrors to `localStorage`; a board
+  whose connection drops blocks further input instead of losing it, and
+  `rly rescue <id>` re-serves on the same port so an open tab reconnects. Active
+  same-Wi-Fi share links stay tied to the board and survive a same-port re-serve
+  until revoked. Reviewer submissions are isolated, reference-only side reviews
+  that never finish the owner's board; read-only links cannot mutate feedback.
 - Still **zero npm runtime dependencies**, offline, and cross-platform. Vendored
   browser libraries are loaded only for boards that need them.
 
@@ -201,8 +206,8 @@ npm test     # smoke tests with no external services (spawns real servers, fake-
 - **Markdown blocks render GFM tables**; element comments moved to an
   Outline-style right sidebar with inline highlights on commented text.
 - **Seamless timeouts** — a detached board that runs past its deadline keeps
-  serving so you can still submit (it lands as `submitted`); the page shows a
-  calm note instead of disconnecting.
+  serving until Submit or explicit stop, so you can still submit (it lands as
+  `submitted`); the page shows a calm note instead of disconnecting.
 - **`rly upgrade`** — install the latest CLI and refresh the skill in one step.
 - Per-question notes are multi-line textboxes.
 

package/docs/AGENT.md

@@ -75,23 +75,28 @@ results), so partial input is never lost.
 
 Browser boards are local-owner only by default. A same-Wi-Fi phone/tablet/other
 laptop gets a locked page until sharing is explicitly activated. The owner can
-click **Share** at the bottom of the board, or you can manage the same links for
-the user:
+click the topbar **Share** icon, or you can manage the same links for the user:
 
 ```sh
 rly share b-xxxxx                         # list active share roles
-rly share b-xxxxx --role review           # reviewer: add comments only
-rly share b-xxxxx --role collab           # collaborator: edit/comment/submit
+rly share b-xxxxx --role review           # reviewer: answer/comment + submit a side review
+rly share b-xxxxx --role collab           # collaborator: edit/comment/final-submit as owner-authorized
+rly share b-xxxxx --role read             # read-only viewer: no answers/comments/submit
 rly share b-xxxxx --role review --revoke  # revoke one role
 rly share b-xxxxx --revoke --all          # revoke all active links
 ```
 
-Use `review` unless the user explicitly wants the other device to submit as the
-owner. Reviewers cannot change answers, submit, edit comments, or delete
-comments; their autosaves merge new comments into the existing draft.
-Collaborators can edit answers, comment, open allowed local file links, and
-submit. Shared viewers refresh from the live draft when another viewer saves,
-deferred while someone is typing/commenting.
+Use `review` for independent feedback: each browser gets an isolated review
+draft and may answer, comment, and submit, but the submission is stored as a
+**reference-only side review**. It does not finish the board, wake the agent, or
+complete `rly wait`; the owner (or an owner-authorized collaborator) must still
+submit the final answer. `rly result <id>` exposes current side-review drafts and
+submissions on demand under `sideReviews`, clearly marked `referenceOnly:true`.
+Use `read` when the other device should only view the board and existing
+feedback. Read-only viewers cannot answer, comment, edit blocks, open local file
+links, or submit. Collaborators retain owner-authorized edit/comment/final-submit
+permission. Active links keep the same token across a same-port
+`rly reopen`/`rly rescue` until revoked.
 
 ## Inline mode — relay as an MCP App (Claude & Codex apps)
 
@@ -672,12 +677,13 @@ raising `--timeout`.
 For a **detached** board, the `timeout` deadline is *soft*: it hands you a
 `timeout` result (with the autosaved draft) so you regain control, but the
 server stays up and the board stays fully usable — the user can keep
-commenting and still hit Submit. The page tells them you stopped waiting and
-to prompt you afterward. So if you got a `timeout` and the user might still be
-working: re-check later with `rly result <id>` (its status flips to
-`submitted` once they finish), or pass `--on-result` so a late submit
-push-wakes you. A blocking `rly ask` (no `--detach`) still ends hard on
-timeout, since there's no separate waiter to hand back to.
+commenting and still hit Submit. It stays on the same port until Submit or an
+explicit `rly stop`, so don't reopen just because your wait timed out. The page
+tells them you stopped waiting and to prompt you afterward. So if you got a
+`timeout` and the user might still be working: re-check later with `rly result
+<id>` (its status flips to `submitted` once they finish), or pass `--on-result`
+so a late submit push-wakes you. A blocking `rly ask` (no `--detach`) still ends
+hard on timeout, since there's no separate waiter to hand back to.
 
 ## Push-wake — get notified instead of polling
 
@@ -745,7 +751,9 @@ rly rm <id> | --all      # delete saved board(s)
 ```
 
 Multiple boards can run at once (each gets its own port on 127.0.0.1).
-Storage lives in `~/.relay` (override with `RLY_HOME`).
+Detached boards are durable: they keep serving past timeout, `reopen`/`rescue`
+prefer the last port, and active same-Wi-Fi share links keep the same token until
+revoked. Storage lives in `~/.relay` (override with `RLY_HOME`).
 
 ## Live board mutation — `rly update`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "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

@@ -135,6 +135,10 @@ rly wait b-xxxxx --timeout 550       # blocks until submit, prints result JSON
 rly result b-xxxxx                   # non-blocking peek (includes live draft)
 ```
 
+Detached boards are durable: their own timeout hands the agent a `timeout`
+result but keeps the same URL/port serving until Submit or `rly stop`. Do not
+create a new board just because a wait timed out.
+
 For long waits prefer presence-aware waiting over a huge --timeout:
 
 ```sh
@@ -178,23 +182,31 @@ answers and any annotations written so far.
 
 Browser boards are local-owner only by default. A phone/tablet/other laptop on
 the same Wi-Fi gets a locked page until sharing is explicitly activated. The
-owner can click **Share** at the bottom of the board, or an agent can manage the
-same links with `rly share`:
+owner can click the topbar **Share** icon, or an agent can manage the same links
+with `rly share`:
 
 ```sh
 rly share b-xxxxx                         # list active share roles
 rly share b-xxxxx --role review           # activate a reviewer link
 rly share b-xxxxx --role collab           # activate a collaborator link
+rly share b-xxxxx --role read             # activate a read-only link
 rly share b-xxxxx --role review --revoke  # revoke one role
 rly share b-xxxxx --revoke --all          # revoke all active share links
 ```
 
-Use `review` when the other device should add comments only. Reviewers cannot
-change answers, submit, edit comments, or delete comments; their autosaves merge
-new comments into the existing draft. Use `collab` only when the user explicitly
+Use `review` for independent feedback. Each reviewer browser gets an isolated
+draft and can answer, comment, and submit a **reference-only side review**. That
+submission never finishes the board or wakes/completes the waiting agent; the
+owner (or owner-authorized collaborator) must still provide the final answer.
+When the owner asks for current reviewer input, run `rly result <id>` and inspect
+`sideReviews.submissions` plus `sideReviews.drafts`; both are explicitly marked
+reference-only. Use `read` for a view-only link with no answers, comments, block
+edits, local-file opening, or submit. Use `collab` only when the user explicitly
 wants that device to act as the owner: collaborators can edit answers, comment,
-open allowed local file links, and submit. Shared viewers refresh from the live
-draft when another viewer saves, deferred while someone is typing/commenting.
+open allowed local file links, and final-submit. Shared viewers refresh from the
+relevant live draft when another viewer in the same role/session saves.
+Active share links are durable too: they keep the same token across a same-port
+`rly reopen`/`rly rescue` until `rly share --revoke` disables them.
 
 ## Minimal spec
 
@@ -534,7 +546,8 @@ one yesno "Does this match your mental model?" + a textarea for notes.
 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.
+Multiple boards can run concurrently. Detached boards keep serving past timeout;
+use `rly stop` when you actually want to close one.
 
 ### Continue a board — reconnect, NEVER recreate it
 

package/src/cli.js

@@ -761,21 +761,27 @@ async function cmdWaitLoop(id, deadline, opts) {
 
 async function cmdResult(args) {
   const record = mustLoad(args._[0]);
+  const sideReviews = {
+    referenceOnly: true,
+    note: 'Side reviews are reference only. Wait for the board owner (or owner-authorized collaborator) to submit the final answer.',
+    submissions: Array.isArray(record.sideReviews) ? record.sideReviews : [],
+    drafts: record.reviewDrafts && typeof record.reviewDrafts === 'object' ? record.reviewDrafts : {},
+  };
   if (record.result && record.result.finishedAt) {
-    printResult(record.result);
+    printResult({ ...record.result, sideReviews });
     return exitCodeFor(record.result.status);
   }
   const running = loadRunning(record.id);
   if (running && isAlive(running.pid)) {
     // While open, expose the real-time autosaved draft so agents can peek, plus
     // best-effort presence (whether the user is still viewing/focused/active).
-    const out = { status: 'open', boardId: record.id, url: running.url, draft: record.draft ?? null };
+    const out = { status: 'open', boardId: record.id, url: running.url, draft: record.draft ?? null, sideReviews };
     const presence = await fetchPresence(running.url);
     if (presence) out.presence = presence;
     printResult(out); // draft can hold many annotations — sidecar it too
     return 0;
   }
-  printResult({ status: 'lost', boardId: record.id, draft: record.draft ?? null });
+  printResult({ status: 'lost', boardId: record.id, draft: record.draft ?? null, sideReviews });
   return 5;
 }
 
@@ -785,9 +791,10 @@ async function cmdShare(args) {
   if (!running || !isAlive(running.pid)) {
     throw new CliError(`board "${record.id}" is not running. Use \`rly reopen ${record.id} --detach\` first.`, 5);
   }
-  const role = args.all ? 'all' : args.role;
-  if (role !== undefined && !['collab', 'review', 'all'].includes(role)) {
-    throw new CliError('--role must be collab or review.', 4);
+  let role = args.all ? 'all' : args.role;
+  if (role === 'readonly' || role === 'read-only') role = 'read';
+  if (role !== undefined && !['collab', 'review', 'read', 'all'].includes(role)) {
+    throw new CliError('--role must be collab, review, or read.', 4);
   }
   const shareUrl = new URL('/api/share', running.url);
   let res;
@@ -1084,6 +1091,9 @@ the user should view — put it in relay instead of printing it.**
   if it is still open and the user may continue, run \`rly wait\` again. Do not
   use \`--on-result\` as the primary Codex return path; normal Codex CLI sessions
   do not expose a portable inbound API that wakes the current agent turn.
+  Detached boards are durable: a board timeout hands the agent a \`timeout\`
+  result but keeps the same URL/port serving until Submit or \`rly stop\`. Do
+  not create a new board just because a wait timed out.
 - **A plan, structure, architecture, data, or prototype** → a relay board with
   diagram/chart/table/code/image/html blocks — never ASCII diagrams or walls of prose.
 - **"Show me the diff / git diff / these changes"** → \`rly diff\` (runs git diff →
@@ -1097,8 +1107,12 @@ the user should view — put it in relay instead of printing it.**
   option its own visual (\`options[].blocks\`) so the user picks by looking.
 - Same-Wi-Fi sharing is locked by default. When the user wants another device to
   review or co-fill a running board, manage explicit links with \`rly share <id>\`:
-  \`--role review\` creates a comments-only reviewer link, \`--role collab\` creates
-  an edit/comment/submit link, and \`--revoke\` disables active links.
+  \`--role review\` creates an answer/comment link whose submissions are reference-only
+  side reviews (\`rly result\` exposes them but they never complete \`rly wait\`),
+  \`--role collab\` creates an owner-authorized edit/comment/final-submit link,
+  \`--role read\` creates a view-only link, and \`--revoke\` disables active links. Active
+  share links are durable across same-port \`rly reopen\`/\`rly rescue\` until
+  revoked.
 - **There's a purpose-built component for most content — use the MOST SPECIFIC one,
   never plain prose when a block fits.** Blocks: \`table\` (sortable/filterable/CSV,
   load from .csv/.json), \`chart\`, \`kpi\` (stat cards), \`mermaid\`/\`graphviz\`/\`plantuml\`,
@@ -1568,8 +1582,8 @@ async function cmdServeInternal(args) {
     open: args.open !== false,
     timeoutSec: args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : 1800,
     quiet: true,
-    // Detached board: timeout hands back to the agent but keeps serving so the
-    // user can keep commenting and still submit (seamless past the deadline).
+    // Detached board: timeout hands back to the agent but keeps the same
+    // URL/port serving until Submit or explicit stop.
     keepAliveOnTimeout: true,
   });
   await done;
@@ -1605,10 +1619,12 @@ USAGE
                                         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 share <id>                      list active same-Wi-Fi share links for a running board
-  rly share <id> --role review        activate a reviewer link (comments only)
-  rly share <id> --role collab        activate a collaborator link (edit/comment/submit)
+  rly share <id> --role review        reviewer: answer/comment/submit a reference-only side review
+  rly share <id> --role collab        collaborator: edit/comment/final-submit as owner-authorized
+  rly share <id> --role read          activate a read-only viewer link
   rly share <id> --role review --revoke
                                       revoke one share role; use --revoke --all to disable all roles
+                                      active links survive same-port reopen/rescue until revoked
   rly list [--json]                   running boards
   rly open [id]                       re-open the browser tab of a running board
   rly reopen <id> [--replies f.json]  serve a saved board again, prefilled with saved answers
@@ -1643,7 +1659,8 @@ COMMON FLAGS
 
 EXIT CODES   0 submitted/acknowledged · 2 timeout · 3 cancelled · 4 usage · 5 not found
 
-NOTES        answers & annotations autosave in real time (drafts survive timeout/cancel);
+NOTES        detached boards keep serving after timeout until Submit or stop;
+             answers & annotations autosave in real time (drafts survive timeout/cancel);
              submitting auto-closes the tab and unblocks the CLI.
 
 AI AGENTS    run \`rly agent\` for the complete machine-oriented guide.