@khanglvm/relay 0.3.0 → 0.4.0

package/README.md

@@ -356,6 +356,17 @@ Exit codes: `0` submitted/acknowledged · `2` timeout · `3` cancelled ·
 
 Storage: `~/.relay` (override with `RLY_HOME`). Boards bind to `127.0.0.1` only.
 
+## Presence, push-wake & diagram co-editing (v0.4)
+
+While a board is open the page reports user activity; `rly result <id>`
+includes `presence` ({visible, focused, secondsSinceActivity}) and
+`rly wait <id> --while-active --idle-grace 180` keeps waiting while the user
+is demonstrably engaged instead of dying on a fixed timer. For pushes,
+`--on-result '<cmd>'` (on ask/show/reopen/reuse) and `rly wait --notify-cmd`
+execute your command with the result JSON on stdin the moment the board
+finishes. Mermaid blocks with `"editable": true` let the user edit the diagram
+source with live preview — their version returns as `result.blockEdits`.
+
 ## Agent skill (Claude Code, Codex, …)
 
 A universal [SKILL.md](skills/relay/SKILL.md) is bundled:

package/docs/AGENT.md

@@ -321,6 +321,53 @@ annotation IDs cause a `CliError` (exit 4) listing valid IDs.
 The UI shows agent and user replies as a thread under each comment — agent replies
 use an accent chip, user replies use a muted chip.
 
+## Presence — is the user still there?
+
+While a board is open, the page reports activity (visibility, focus, idle
+time). Use it instead of guessing timeouts:
+
+```sh
+rly result b-xxxxx     # open board → includes "presence":
+                       #   {open, seen, visible, focused, secondsSinceActivity, secondsSincePing}
+rly wait b-xxxxx --timeout 550 --while-active --idle-grace 180
+```
+
+`--while-active` keeps extending the wait as long as the user is demonstrably
+active (page visible/focused and interaction within `--idle-grace` seconds,
+default 180); once they go idle it returns the normal `wait-timeout` JSON,
+with `presence` attached so you can decide what to do next. Prefer this over
+raising `--timeout`.
+
+## Push-wake — get notified instead of polling
+
+```sh
+rly ask --file spec.json --detach --on-result 'curl -s -X POST localhost:9999/wake -d @-'
+rly wait b-xxxxx --notify-cmd 'touch /tmp/board-done'
+```
+
+`--on-result` (on ask/show/reopen/reuse) runs your shell command the moment
+the board reaches a terminal status — submitted, acknowledged, timeout, or
+cancelled — with the full result JSON piped to stdin and `RLY_BOARD_ID`,
+`RLY_STATUS`, `RLY_URL` in the environment. `--notify-cmd` does the same from
+a `wait` that obtains a terminal result. Write a file your harness watches,
+hit a webhook — whatever wakes you.
+
+## Editable diagrams — let the user redraw your mermaid
+
+Add `"editable": true` to any mermaid block. The user gets an "Edit diagram"
+button with live-preview source editing (syntax errors shown inline without
+destroying the last good render; Reset restores your original). Their edited
+source returns in the result:
+
+```json
+"blockEdits": { "b2": "graph TD; A-->B; B-->C[their new step]" }
+```
+
+Diff it against your original to see exactly what the user changed. Recipe:
+propose an architecture as an editable mermaid block + a `yesno` "Does this
+match your mental model?" + a `textarea` for anything the diagram can't say.
+Edits autosave with the draft, so they survive reloads and timeouts too.
+
 ## Managing boards
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Browser-based question boards with rich blocks (markdown, charts, mermaid, tables, code, sandboxed HTML) and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, wait for submit, read answers as JSON.",
   "keywords": [
     "ai-agents",

package/skills/relay/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: relay
-description: Ask the user interactive questions in a browser board (single/multi choice, yes-no, free text, scale) and/or present rich content blocks (markdown, mermaid diagrams, graphviz, plantuml, uml, charts, interactive tables, code, sandboxed HTML), then wait for Submit and read JSON answers plus element-level annotations. PROACTIVELY use whenever you would otherwise (a) call a native ask-user/question tool with 2+ questions or options that need explanation, (b) describe a UI/design/plan/architecture in prose that a visual would show better — draft diagrams (mermaid, graphviz, plantuml), charts, and interactive tables as native blocks, or (c) hand-roll an HTML file or local server to demo an idea - relay replaces all three. Triggers - clarify requirements before ambiguous work, choose between approaches, plan approval, design/UX feedback, mockup or prototype review, compare alternatives, survey, metrics review, "ask the user", "show the user", "which do you prefer", "get feedback", diagram, chart, data table, architecture overview, metrics, dependency graph, sequence diagram, class diagram, uml, graphviz, plantuml. Skip only for a single trivial yes/no confirmation.
+description: Show the user anything visual in an interactive browser board - repo/file structures, architecture diagrams (mermaid, graphviz, plantuml, uml), charts, sortable data tables, code, prototypes - and/or ask structured questions (single/multi choice, yes-no, free text, scale), then wait for Submit and read JSON answers plus element-level comments and user-edited diagrams. PROACTIVELY use whenever you would otherwise (a) draw an ASCII tree/table/diagram in the terminal or describe a structure/design/plan in prose - render it as interactive blocks instead, (b) call a native ask-user/question tool with 2+ questions or options that need explanation, or (c) hand-roll an HTML file or local server to demo an idea - relay replaces all three. Triggers - show me the structure, repo/project/folder structure, file tree, directory layout, codebase map, architecture overview, dependency graph, sequence/class diagram, uml, visualize, diagram, chart, data table, metrics review, mockup or prototype review, plan approval, design/UX feedback, compare alternatives, let the user edit the diagram, clarify requirements before ambiguous work, survey, "ask the user", "show the user", "which do you prefer", "get feedback". Skip only for a single trivial yes/no confirmation.
 ---
 
 # relay (`rly`)
@@ -45,6 +45,19 @@ rly wait b-xxxxx --timeout 550       # blocks until submit, prints result JSON
 rly result b-xxxxx                   # non-blocking peek (includes live draft)
 ```
 
+For long waits prefer presence-aware waiting over a huge --timeout:
+
+```sh
+rly wait b-xxxxx --timeout 550 --while-active --idle-grace 180
+# keeps extending while the user is demonstrably viewing/typing on the board;
+# returns wait-timeout promptly once they are idle/gone (presence included)
+rly result b-xxxxx        # while open also shows presence {visible, focused, secondsSinceActivity}
+```
+
+Push-wake instead of polling: add --on-result '<shell cmd>' to ask/show/reopen
+(or --notify-cmd on wait) - the command runs the moment the board finishes,
+with the full result JSON on stdin and RLY_BOARD_ID/RLY_STATUS/RLY_URL in env.
+
 Blocking mode (`rly ask --file spec.json --timeout 1800`, no --detach) is fine
 ONLY when your shell tool has no execution time limit.
 
@@ -168,6 +181,14 @@ numbers, followed by a `table` block for the raw data; at least one question
 asking what to act on. In the intro, tell the user they can click chart points
 and table cells to comment on specific values.
 
+## Diagram co-editing (user edits your diagram)
+
+Add "editable": true to a mermaid block: the user gets an Edit button with
+live-preview source editing. Their version comes back as
+result.blockEdits["<blockId>"] - diff it against your original to see what
+they changed. Recipe: propose an architecture as an editable mermaid block +
+one yesno "Does this match your mental model?" + a textarea for notes.
+
 ## Reuse & management
 
 `rly history` (saved boards) · `rly spec <id>` (print spec to modify) ·

package/skills/relay/examples/diagram-coedit.json

@@ -0,0 +1,15 @@
+{
+  "title": "Architecture review — redraw it if I got it wrong",
+  "intro": "Below is my proposed architecture. If it doesn't match your mental model, click 'Edit diagram' and change it directly — I'll read your version.",
+  "blocks": [
+    {
+      "type": "mermaid",
+      "editable": true,
+      "code": "graph TD; client[Web Client] --> api[API Gateway]; api --> auth[Auth Service]; api --> core[Core Service]; core --> db[(Postgres)]; core --> queue[[Job Queue]]"
+    }
+  ],
+  "questions": [
+    { "id": "match", "type": "yesno", "label": "Does this match your mental model (after your edits, if any)?", "required": true },
+    { "id": "notes", "type": "textarea", "label": "Anything the diagram can't express?", "placeholder": "constraints, scaling concerns, naming…" }
+  ]
+}

package/src/cli.js

@@ -28,6 +28,7 @@ const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'),
 const VALUED_FLAGS = new Set([
   'file', 'html', 'html-file', 'title', 'intro', 'timeout', 'port',
   'submit-label', 'height', 'limit', 'target', 'id', 'replies',
+  'on-result', 'notify-cmd', 'idle-grace',
 ]);
 
 function camel(key) {
@@ -71,6 +72,44 @@ function printJson(obj) {
   process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
 }
 
+// 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
+// --on-result hook. Failures are swallowed; a 30s kill timer caps a hung cmd.
+function runNotifyCmd(cmd, result) {
+  if (typeof cmd !== 'string' || !cmd.trim()) return;
+  try {
+    const child = spawn('/bin/sh', ['-c', cmd], {
+      env: {
+        ...process.env,
+        RLY_BOARD_ID: result.boardId || '',
+        RLY_STATUS: result.status || '',
+        RLY_URL: result.url || '',
+      },
+      stdio: ['pipe', 'ignore', 'ignore'],
+    });
+    child.on('error', () => {});
+    try {
+      child.stdin.write(JSON.stringify(result));
+      child.stdin.end();
+    } catch {
+      // best effort
+    }
+    const killTimer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // already gone
+      }
+    }, 30000);
+    killTimer.unref();
+    child.on('close', () => clearTimeout(killTimer));
+    child.unref();
+  } catch {
+    // swallow — push-wake is best effort
+  }
+}
+
 function exitCodeFor(status) {
   return { submitted: 0, acknowledged: 0, open: 0, timeout: 2, cancelled: 3 }[status] ?? 1;
 }
@@ -146,6 +185,15 @@ async function runOrDetach(record, args) {
   const port = args.port !== undefined ? Number.parseInt(args.port, 10) || 0 : 0;
   const open = args.open !== false;
 
+  // Push-wake: persist the agent's --on-result command on the record so BOTH
+  // the inline runBoard path and the detached __serve path pick it up (the
+  // detached server reads record.onResult from disk). Runtime concern only —
+  // not part of the spec.
+  if (typeof args.onResult === 'string' && args.onResult.trim()) {
+    record.onResult = args.onResult;
+    saveBoard(record);
+  }
+
   if (args.detach) {
     const child = spawn(
       process.execPath,
@@ -313,25 +361,52 @@ async function cmdUpdate(args) {
   return 0;
 }
 
+// Best-effort fetch of /api/presence for a running board. Returns the parsed
+// presence object, or null on any failure / timeout (500ms cap via
+// AbortController). Never throws.
+async function fetchPresence(url) {
+  if (!url) return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 500);
+  try {
+    const res = await fetch(new URL('/api/presence', url), { signal: controller.signal });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function cmdWait(args) {
   const id = args._[0];
-  if (!id) throw new CliError('usage: rly wait <board-id> [--timeout <sec>]');
+  if (!id) throw new CliError('usage: rly wait <board-id> [--timeout <sec>] [--while-active] [--idle-grace <sec>] [--notify-cmd <cmd>]');
   const timeoutSec = args.timeout !== undefined ? Math.max(1, Number.parseInt(args.timeout, 10) || 1) : 3600;
-  const deadline = Date.now() + timeoutSec * 1000;
+  const whileActive = args.whileActive === true;
+  const idleGrace = args.idleGrace !== undefined ? Math.max(0, Number.parseInt(args.idleGrace, 10) || 0) : 180;
+  const notifyCmd = typeof args.notifyCmd === 'string' && args.notifyCmd.trim() ? args.notifyCmd : null;
+  let deadline = Date.now() + timeoutSec * 1000;
   mustLoad(id);
+
+  // Push-wake: run the agent's --notify-cmd after a TERMINAL result, then print.
+  const finishResult = (result) => {
+    if (notifyCmd) runNotifyCmd(notifyCmd, result);
+    printJson(result);
+    return exitCodeFor(result.status);
+  };
+
   while (Date.now() < deadline) {
     const record = mustLoad(id);
     if (record.result && record.result.finishedAt) {
-      printJson(record.result);
-      return exitCodeFor(record.result.status);
+      return finishResult(record.result);
     }
     const running = loadRunning(id);
     if (!running || !isAlive(running.pid)) {
       await sleep(700); // the result write may be racing the process exit
       const again = loadBoard(id);
       if (again?.result?.finishedAt) {
-        printJson(again.result);
-        return exitCodeFor(again.result.status);
+        return finishResult(again.result);
       }
       printJson({
         status: 'lost',
@@ -341,17 +416,93 @@ async function cmdWait(args) {
       });
       return 5;
     }
+    if (Date.now() >= deadline) break;
     await sleep(400);
   }
-  printJson({
+
+  // Deadline hit while the board is still OPEN. Fetch presence (cheaply).
+  const running = loadRunning(id);
+  const presence = running && isAlive(running.pid) ? await fetchPresence(running.url) : null;
+
+  // --while-active: if the user is present + recently active, EXTEND and keep
+  // waiting (repeat indefinitely while they stay active).
+  if (
+    whileActive &&
+    presence &&
+    presence.seen &&
+    (presence.visible || presence.focused) &&
+    presence.secondsSinceActivity < idleGrace
+  ) {
+    deadline = Date.now() + Math.min(idleGrace, 120) * 1000;
+    return cmdWaitLoop(id, deadline, { whileActive, idleGrace, notifyCmd });
+  }
+
+  const out = {
     status: 'wait-timeout',
     boardId: id,
     hint: `board is still open — run \`rly wait ${id}\` again, or \`rly result ${id}\` to peek at the live draft`,
-  });
+  };
+  if (presence) out.presence = presence;
+  printJson(out);
+  return 2;
+}
+
+// Continuation loop for `rly wait --while-active` after a deadline extension.
+// Identical waiting logic to cmdWait's main loop, then re-evaluates presence;
+// extends again while the user stays active, otherwise emits wait-timeout.
+async function cmdWaitLoop(id, deadline, opts) {
+  const { whileActive, idleGrace, notifyCmd } = opts;
+  const finishResult = (result) => {
+    if (notifyCmd) runNotifyCmd(notifyCmd, result);
+    printJson(result);
+    return exitCodeFor(result.status);
+  };
+  while (Date.now() < deadline) {
+    const record = mustLoad(id);
+    if (record.result && record.result.finishedAt) {
+      return finishResult(record.result);
+    }
+    const running = loadRunning(id);
+    if (!running || !isAlive(running.pid)) {
+      await sleep(700);
+      const again = loadBoard(id);
+      if (again?.result?.finishedAt) {
+        return finishResult(again.result);
+      }
+      printJson({
+        status: 'lost',
+        boardId: id,
+        draft: again?.draft ?? null,
+        error: 'board server exited without writing a result',
+      });
+      return 5;
+    }
+    if (Date.now() >= deadline) break;
+    await sleep(400);
+  }
+  const running = loadRunning(id);
+  const presence = running && isAlive(running.pid) ? await fetchPresence(running.url) : null;
+  if (
+    whileActive &&
+    presence &&
+    presence.seen &&
+    (presence.visible || presence.focused) &&
+    presence.secondsSinceActivity < idleGrace
+  ) {
+    const next = Date.now() + Math.min(idleGrace, 120) * 1000;
+    return cmdWaitLoop(id, next, opts);
+  }
+  const out = {
+    status: 'wait-timeout',
+    boardId: id,
+    hint: `board is still open — run \`rly wait ${id}\` again, or \`rly result ${id}\` to peek at the live draft`,
+  };
+  if (presence) out.presence = presence;
+  printJson(out);
   return 2;
 }
 
-function cmdResult(args) {
+async function cmdResult(args) {
   const record = mustLoad(args._[0]);
   if (record.result && record.result.finishedAt) {
     printJson(record.result);
@@ -359,8 +510,12 @@ function cmdResult(args) {
   }
   const running = loadRunning(record.id);
   if (running && isAlive(running.pid)) {
-    // While open, expose the real-time autosaved draft so agents can peek.
-    printJson({ status: 'open', boardId: record.id, url: running.url, draft: record.draft ?? null });
+    // 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 presence = await fetchPresence(running.url);
+    if (presence) out.presence = presence;
+    printJson(out);
     return 0;
   }
   printJson({ status: 'lost', boardId: record.id, draft: record.draft ?? null });
@@ -643,9 +798,13 @@ USAGE
   rly ask -q "Deploy?::yesno" -q "!Env::single::dev,staging,prod"
                                       quick inline questions ("!" = required, label::type::options)
   rly ask ... --detach                no blocking: prints {boardId,url} now; collect via \`rly wait <id>\`
+  rly ask ... --on-result "<cmd>"     push-wake: run <cmd> when the board finishes (result JSON on stdin)
   rly show --html-file viz.html       visualization-only board (submit button = acknowledge)
   rly wait <id> [--timeout 3600]      block until board finishes, print result JSON
-  rly result <id>                     result/status now (includes live autosaved draft while open)
+                                      --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)
+  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
   rly reopen <id> [--replies f.json]  serve a saved board again, prefilled with saved answers
@@ -706,7 +865,7 @@ export async function main(argv) {
       case 'wait':
         return await cmdWait(parseArgs(rest));
       case 'result':
-        return cmdResult(parseArgs(rest));
+        return await cmdResult(parseArgs(rest));
       case 'list':
         return cmdList(parseArgs(rest));
       case 'open':

package/src/server.js

@@ -2,6 +2,7 @@ import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { loadBoard, saveBoard, saveRunning, removeRunning, loadPref, savePref } from './store.js';
 import { openUrl } from './open.js';
@@ -80,6 +81,7 @@ function buildPage(record, rev) {
         comment: record.draft.comment || '',
         notes: record.draft.notes || {},
         annotations: record.draft.annotations || [],
+        blockEdits: record.draft.blockEdits || {},
       }
     : null;
   const boot = { boardId: record.id, spec: clientSpec, prefill, pref: loadPref(), vendor, rev };
@@ -130,6 +132,24 @@ function sanitizeAnnotations(value) {
   return out;
 }
 
+// Validates + sanitizes an incoming blockEdits map (from draft/submit).
+// Keeps only string-keyed entries with string values <= 20000 chars; caps at
+// 50 entries; drops invalid entries. Returns {} when nothing valid is present.
+function sanitizeBlockEdits(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return {};
+  const out = {};
+  let n = 0;
+  for (const key of Object.keys(value)) {
+    if (n >= 50) break;
+    if (typeof key !== 'string') continue;
+    const v = value[key];
+    if (typeof v !== 'string' || v.length > 20000) continue;
+    out[key] = v;
+    n++;
+  }
+  return out;
+}
+
 // Resolves an html block body by id from the board or any question scope.
 function findHtmlBlock(spec, blockId) {
   const scan = (blocks) => (Array.isArray(blocks) ? blocks.find((b) => b && b.id === blockId && b.type === 'html') : undefined);
@@ -214,6 +234,47 @@ function readBody(req, limit = 5 * 1024 * 1024) {
   });
 }
 
+// Push-wake: run the agent's own local shell command after a board finishes.
+// The full result JSON is written to the command's stdin; RLY_BOARD_ID /
+// RLY_STATUS / RLY_URL are exported. Failures are swallowed (best effort) —
+// only a stderr note when not quiet. A 30s kill timer prevents a hung command
+// from keeping the process alive.
+function runOnResult(cmd, result, { quiet = false } = {}) {
+  if (typeof cmd !== 'string' || !cmd.trim()) return;
+  try {
+    const child = spawn('/bin/sh', ['-c', cmd], {
+      env: {
+        ...process.env,
+        RLY_BOARD_ID: result.boardId || '',
+        RLY_STATUS: result.status || '',
+        RLY_URL: result.url || '',
+      },
+      stdio: ['pipe', 'ignore', 'ignore'],
+    });
+    child.on('error', () => {
+      if (!quiet) process.stderr.write(`[relay] --on-result command failed to spawn\n`);
+    });
+    try {
+      child.stdin.write(JSON.stringify(result));
+      child.stdin.end();
+    } catch {
+      // best effort — stdin may already be gone
+    }
+    const killTimer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // already gone
+      }
+    }, 30000);
+    killTimer.unref();
+    child.on('close', () => clearTimeout(killTimer));
+    child.unref();
+  } catch {
+    if (!quiet) process.stderr.write(`[relay] --on-result command failed to run\n`);
+  }
+}
+
 // Serves one board on 127.0.0.1 and resolves `done` when it finishes
 // (submitted / acknowledged / timeout / cancelled). The result is also
 // persisted into the board record so `rly wait` / `rly result` can read it
@@ -233,6 +294,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         comment: record.result.comment || '',
         notes: record.result.notes || {},
         annotations: record.result.annotations || [],
+        blockEdits: record.result.blockEdits || {},
         updatedAt: new Date().toISOString(),
       };
     }
@@ -248,6 +310,8 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   let rev = 1;
   let status = 'open';
   let finished = false;
+  // Latest client presence ping (null until the first ping arrives).
+  let presence = null;
   let resolveDone;
   const done = new Promise((r) => {
     resolveDone = r;
@@ -264,6 +328,31 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         sendJson(res, 200, { id: record.id, spec: record.spec, draft: record.draft, result: record.result });
       } else if (req.method === 'GET' && pathname === '/api/status') {
         sendJson(res, 200, { status, rev });
+      } else if (req.method === 'POST' && pathname === '/api/ping') {
+        const body = JSON.parse((await readBody(req)) || '{}');
+        // Validate body shape: visible/focused booleans, idleMs finite >= 0.
+        if (
+          typeof body.visible === 'boolean' &&
+          typeof body.focused === 'boolean' &&
+          Number.isFinite(body.idleMs) &&
+          body.idleMs >= 0
+        ) {
+          presence = { atMs: Date.now(), visible: body.visible, focused: body.focused, idleMs: body.idleMs };
+        }
+        sendJson(res, 200, { ok: true });
+      } else if (req.method === 'GET' && pathname === '/api/presence') {
+        if (!presence) {
+          sendJson(res, 200, { open: true, seen: false });
+        } else {
+          sendJson(res, 200, {
+            open: true,
+            seen: true,
+            visible: presence.visible,
+            focused: presence.focused,
+            secondsSinceActivity: Math.round((Date.now() - presence.atMs + presence.idleMs) / 1000),
+            secondsSincePing: Math.round((Date.now() - presence.atMs) / 1000),
+          });
+        }
       } else if (req.method === 'POST' && pathname === '/api/update') {
         if (req.headers['x-relay-token'] !== token) return sendJson(res, 403, { error: 'forbidden' });
         const body = JSON.parse((await readBody(req)) || '{}');
@@ -311,6 +400,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
           comment: typeof body.comment === 'string' ? body.comment : '',
           notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
           annotations: sanitizeAnnotations(body.annotations),
+          blockEdits: sanitizeBlockEdits(body.blockEdits),
           updatedAt: new Date().toISOString(),
         };
         saveBoard(record);
@@ -328,6 +418,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
           comment: typeof body.comment === 'string' ? body.comment : '',
           notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
           annotations: sanitizeAnnotations(body.annotations),
+          blockEdits: sanitizeBlockEdits(body.blockEdits),
         });
       } else {
         sendJson(res, 404, { error: 'not found' });
@@ -363,6 +454,10 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     if (finished) return;
     finished = true;
     status = partial.status;
+    // blockEdits: from this submit, else fall back to the autosaved draft
+    // (timeout/cancel). null when there are none.
+    const editsRaw = partial.blockEdits ?? (record.draft?.blockEdits || {});
+    const blockEdits = editsRaw && Object.keys(editsRaw).length ? editsRaw : null;
     const result = {
       status: partial.status,
       boardId: record.id,
@@ -373,6 +468,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
       comment: partial.comment ?? '',
       notes: partial.notes ?? null,
       annotations: partial.annotations ?? (record.draft?.annotations || []),
+      blockEdits,
       createdAt: record.createdAt,
       finishedAt: new Date().toISOString(),
       durationMs: Date.now() - startedAt,
@@ -384,6 +480,8 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     }
     record.result = result;
     saveBoard(record);
+    // Push-wake: run the agent's local command for EVERY terminal status.
+    runOnResult(record.onResult, result, { quiet });
     removeRunning(record.id);
     if (timer) clearTimeout(timer);
     process.removeListener('SIGINT', onSignal);

package/src/spec.js

@@ -89,6 +89,7 @@ function normalizeBlock(rawBlock, id, cwd, where) {
     const code = asStr(rawBlock.code);
     if (!code.trim()) throw new CliError(`${where}: mermaid block needs a non-empty "code" string.`);
     const block = { id, type: 'mermaid', code };
+    if (rawBlock.editable === true) block.editable = true;
     if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
     return block;
   }
@@ -367,6 +368,7 @@ const BLOCK_SCHEMA = {
       type: { type: 'string', enum: BLOCK_TYPES },
       md: { type: 'string', description: 'markdown: built-in mini renderer (no external library). Text selections are commentable.' },
       code: { type: 'string', description: 'mermaid: diagram source (e.g. "graph TD; A-->B"); plantuml: the @startuml…@enduml source; code: the source to display.' },
+      editable: { type: 'boolean', description: 'mermaid: when true, render an "Edit diagram" toggle so the user can edit the diagram source live. The edited source is returned in result.blockEdits[<blockId>].' },
       dot: { type: 'string', description: 'graphviz: DOT source (e.g. "digraph { a -> b }"). Rendered offline via vendored Viz.js; nodes and edges are individually commentable.' },
       server: { type: 'string', description: 'plantuml: PlantUML server base URL (http(s)). Defaults to https://www.plantuml.com/plantuml. Diagrams render via this server (needs network).' },
       lang: { type: 'string', description: 'code block: language hint for display.' },
@@ -398,7 +400,7 @@ export const SPEC_SCHEMA = {
   title: 'relay board spec',
   type: 'object',
   description:
-    'A relay board. Renders an optional intro, board-level blocks, then questions (each with optional per-question blocks), then a submit button. The result JSON contains "answers", "comment", per-question "notes", and "annotations" (element-level comments the user attached to any block — see the annotation shape below).',
+    'A relay board. Renders an optional intro, board-level blocks, then questions (each with optional per-question blocks), then a submit button. The result JSON contains "answers", "comment", per-question "notes", "annotations" (element-level comments the user attached to any block — see the annotation shape below), and "blockEdits" (a map blockId→edited source for any editable mermaid block the user changed, null when none).',
   properties: {
     title: { type: 'string', description: 'Board title (default "Relay")' },
     intro: { type: 'string', description: 'Intro text shown under the title. Newlines preserved.' },
@@ -455,6 +457,12 @@ export const SPEC_SCHEMA = {
       description:
         'Returned in the result (not part of the input spec). Element-level comments the user attached to blocks. Each: {id, questionId|null, blockId|null, target:{kind:"chart-element"|"mermaid-node"|"table-cell"|"text"|"html-element", …}, text, createdAt}.',
     },
+    blockEdits: {
+      type: 'object',
+      readOnly: true,
+      description:
+        'Returned in the result (not part of the input spec). A map blockId→edited mermaid source for any editable mermaid block the user changed. null when the user made no edits. Read result.blockEdits[<blockId>] for the user\'s edited diagram source.',
+    },
   },
   anyOf: [{ required: ['questions'] }, { required: ['blocks'] }, { required: ['html'] }, { required: ['htmlFile'] }],
 };

package/src/ui/annotate.js

@@ -200,6 +200,7 @@
   function refreshBadges() {
     for (const b of badges) b.remove();
     badges = [];
+    if (torndown) return;
     registered = registered.filter((r) => r.el.isConnected);
     for (const entry of registered) {
       const count = matching(entry.info).length;
@@ -500,7 +501,32 @@
     renderSummaries();
   }
 
+  // Remove every floating element (pin, badges, popover, selection button)
+  // and stop reacting — called when the board reaches its submitted screen so
+  // nothing leaks over it (they live on <body> with elevated z-index).
+  let torndown = false;
+  function teardown() {
+    torndown = true;
+    try {
+      closePopover();
+    } catch {
+      // popover may not be open
+    }
+    hidePin();
+    hideSelBtn();
+    for (const b of badges) b.remove();
+    badges = [];
+    registered = [];
+    if (dom) {
+      dom.pin.remove();
+      dom.selBtn.remove();
+      dom.pop.remove();
+      dom = null;
+    }
+  }
+
   function register(targetEl, info) {
+    if (torndown) return;
     ensureDom();
     targetEl.classList.add('ann-target');
     const entry = { el: targetEl, info };
@@ -511,14 +537,17 @@
   }
 
   function enableTextSelection(rootEl, baseInfo) {
+    if (torndown) return;
     ensureDom();
     rootEl.addEventListener('mouseup', () => {
+      if (torndown) return;
       // defer: the selection settles after mouseup
       setTimeout(() => maybeShowSelBtn(rootEl, baseInfo), 0);
     });
   }
 
   function openExternal(info, anchorEl) {
+    if (torndown) return;
     openPopover(info, anchorEl);
   }
 
@@ -532,5 +561,5 @@
     renderSummaryInto(target);
   }
 
-  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, renderSummary };
+  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, renderSummary, teardown };
 })();

package/src/ui/app.js

@@ -82,6 +82,10 @@
     notes: {},
     comment: '',
     annotations: (boot.prefill && boot.prefill.annotations) || [],
+    // Editable-mermaid edits: blockId -> edited source. Seeded from the live
+    // draft so a reload/reopen restores the user's edited diagram. Mutated via
+    // the blocks ctx.onBlockEdit callback below; returned in payload().
+    blockEdits: (boot.prefill && boot.prefill.blockEdits) || {},
   };
   let submitted = false;
 
@@ -147,7 +151,13 @@
       const n = typeof state.notes[q.id] === 'string' ? state.notes[q.id].trim() : '';
       if (n) notes[q.id] = n;
     }
-    return { answers, comment: (state.comment || '').trim(), notes, annotations: state.annotations };
+    return {
+      answers,
+      comment: (state.comment || '').trim(),
+      notes,
+      annotations: state.annotations,
+      blockEdits: state.blockEdits,
+    };
   }
 
   // ---------- real-time autosave ----------
@@ -174,6 +184,44 @@
     }
   }
 
+  // ---------- presence / awareness ----------
+  // Track the last time the user interacted with the page so the agent (via
+  // /api/presence) can tell whether someone is still actively viewing the board
+  // and keep waiting instead of timing out. Every existing 3s heartbeat tick
+  // also POSTs /api/ping {visible, focused, idleMs}; pinging stops after submit.
+  let lastInteractionAt = Date.now();
+  let lastMoveAt = 0;
+  function noteInteraction() {
+    lastInteractionAt = Date.now();
+  }
+  window.addEventListener('pointerdown', noteInteraction, { passive: true });
+  window.addEventListener('keydown', noteInteraction, { passive: true });
+  window.addEventListener('scroll', noteInteraction, { passive: true });
+  window.addEventListener('touchstart', noteInteraction, { passive: true });
+  // pointermove fires continuously — throttle to at most once per second.
+  window.addEventListener('pointermove', () => {
+    const now = Date.now();
+    if (now - lastMoveAt >= 1000) {
+      lastMoveAt = now;
+      lastInteractionAt = now;
+    }
+  }, { passive: true });
+
+  function pingPresence() {
+    if (submitted) return;
+    fetch('/api/ping', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        visible: !document.hidden,
+        focused: document.hasFocus(),
+        idleMs: Date.now() - lastInteractionAt,
+      }),
+    }).catch(() => {
+      // presence is best-effort — a failed ping must never surface to the user
+    });
+  }
+
   // ---------- annotations ----------
   // RelayAnnotate owns the live annotation list; mirror it into state on every
   // change so payload()/autosave/submit carry it exactly like answers.
@@ -188,13 +236,25 @@
     });
   }
 
-  // ctx for RelayBlocks.render — theme()/htmlSrc per the shared contract.
+  // Editable-mermaid: record (or clear) the user's edit for a block, then
+  // autosave. A null/empty code clears the entry (block matches the original
+  // again — e.g. after Reset), so payload()/draft carry only real divergences.
+  function onBlockEdit(blockId, codeOrNull) {
+    if (codeOrNull === null || codeOrNull === undefined) delete state.blockEdits[blockId];
+    else state.blockEdits[blockId] = codeOrNull;
+    scheduleSave();
+  }
+
+  // ctx for RelayBlocks.render — theme()/htmlSrc per the shared contract, plus
+  // the editable-mermaid plumbing (edits map + onBlockEdit callback).
   function blockCtx(questionId) {
     return {
       theme: effectiveTheme,
       htmlSrc: (blockId) => '/html/b/' + encodeURIComponent(blockId) + '?theme=' + effectiveTheme(),
       questionId: questionId == null ? null : questionId,
       annotate: Annotate,
+      edits: state.blockEdits,
+      onBlockEdit,
     };
   }
 
@@ -517,6 +577,15 @@
 
   function showDone(closing) {
     stopHeartbeat();
+    // Annotation pins/badges/popover float on <body> with elevated z-index —
+    // remove them so they don't leak over the submitted screen.
+    if (window.RelayAnnotate && typeof RelayAnnotate.teardown === 'function') {
+      try {
+        RelayAnnotate.teardown();
+      } catch {
+        // best effort
+      }
+    }
     app.replaceChildren(
       el('div', { class: 'done' },
         el('div', { class: 'mark' }, '✓'),
@@ -608,6 +677,8 @@
   let misses = 0;
   let reloading = false;
   let hb = setInterval(async () => {
+    // Piggyback presence on the heartbeat (best-effort; no-ops after submit).
+    pingPresence();
     try {
       const r = await fetch('/api/status', { cache: 'no-store' });
       if (!r.ok) throw new Error('bad status');

package/src/ui/blocks.css

@@ -169,6 +169,69 @@
 .blk-mermaid .node,
 .blk-mermaid .edgeLabel { cursor: default; }
 
+/* ---------- editable mermaid (diagram editor) ---------- */
+.blk-mermaid-edit { margin-top: 8px; }
+.blk-edit-btn {
+  appearance: none;
+  background: transparent;
+  border: 1px solid var(--border);
+  border-radius: 7px;
+  color: var(--muted);
+  font-family: var(--sans);
+  font-size: 0.78rem;
+  padding: 4px 10px;
+  cursor: pointer;
+  transition: color 150ms var(--ease), border-color 150ms var(--ease);
+}
+.blk-edit-btn:hover,
+.blk-edit-btn.is-open { color: var(--accent); border-color: var(--accent); }
+.blk-editor { margin-top: 8px; }
+.blk-editor[hidden] { display: none; }
+.blk-editor-ta {
+  display: block;
+  width: 100%;
+  box-sizing: border-box;
+  min-height: 120px;
+  resize: vertical;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--fg);
+  background: var(--bg-sunken);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 10px 12px;
+}
+.blk-editor-ta:focus {
+  outline: none;
+  border-color: var(--accent);
+}
+.blk-editor-row {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-top: 8px;
+}
+.blk-editor-reset {
+  appearance: none;
+  background: transparent;
+  border: 1px solid var(--border);
+  border-radius: 7px;
+  color: var(--muted);
+  font-family: var(--sans);
+  font-size: 0.78rem;
+  padding: 4px 10px;
+  cursor: pointer;
+  transition: color 150ms var(--ease), border-color 150ms var(--ease);
+}
+.blk-editor-reset:hover { color: var(--accent); border-color: var(--accent); }
+.blk-editor-status {
+  font-family: var(--sans);
+  font-size: 0.78rem;
+  color: var(--muted);
+}
+.blk-editor-status.has-error { color: var(--muted); }
+
 /* ---------- graphviz (offline, vendored Viz.js) ---------- */
 .blk-graphviz {
   overflow: auto;

package/src/ui/blocks.js

@@ -554,16 +554,133 @@
   const mermaidRegistry = [];
   const chartRegistry = [];
 
+  // Effective code = the user's edit if present, else the authored block.code.
+  // Used by the initial render, the editor's live preview, and the theme
+  // re-render registry path so an edit survives a theme toggle.
+  function effectiveMermaidCode(entry) {
+    const { block, ctx, blockId } = entry;
+    const edited = ctx.edits ? ctx.edits[blockId] : undefined;
+    if (edited !== undefined && edited !== null) return edited;
+    // The live editor keeps entry.code as the source of truth; if the host's
+    // ctx.edits hasn't been updated yet but the user has diverged from the
+    // original, preserve that divergence (don't snap back to block.code).
+    if (entry.code !== undefined && entry.code !== (block.code || '')) return entry.code;
+    return block.code || '';
+  }
+
   function renderMermaid(block, ctx, blockId) {
     const container = el('div', { class: 'blk-mermaid' });
     const entry = { container, block, ctx, blockId };
+    entry.code = effectiveMermaidCode(entry);
     mermaidRegistry.push(entry);
+
+    if (!block.editable) {
+      drawMermaid(entry);
+      return container;
+    }
+
+    // Editable: wrap the diagram + an editor below it. The wrapper is what the
+    // dispatcher appends; the registry still tracks `container` (the diagram).
+    const wrap = el('div', { class: 'blk-mermaid-wrap' });
+    wrap.append(container);
+    wrap.append(buildMermaidEditor(entry));
     drawMermaid(entry);
-    return container;
+    return wrap;
   }
 
-  function drawMermaid(entry) {
-    const { container, block, ctx, blockId } = entry;
+  // Editor: toggle button + collapsible panel (textarea + Reset + status line).
+  // Live re-render is debounced 600ms; errors show inline WITHOUT destroying the
+  // last good diagram. Each accepted change calls ctx.onBlockEdit(blockId, code)
+  // (null when the value matches the original block.code again).
+  function buildMermaidEditor(entry) {
+    const { block, ctx, blockId, container } = entry;
+    const original = block.code || '';
+
+    const toggleBtn = el('button', { type: 'button', class: 'blk-edit-btn' }, 'Edit diagram');
+    const panel = el('div', { class: 'blk-editor', hidden: '' });
+
+    const ta = el('textarea', { class: 'blk-editor-ta', spellcheck: 'false' });
+    ta.value = entry.code;
+
+    const status = el('div', { class: 'blk-editor-status' }, '');
+    const resetBtn = el('button', { type: 'button', class: 'blk-editor-reset' }, 'Reset');
+    const row = el('div', { class: 'blk-editor-row' }, resetBtn, status);
+    panel.append(ta, row);
+
+    let open = false;
+    toggleBtn.addEventListener('click', () => {
+      open = !open;
+      panel.hidden = !open;
+      toggleBtn.classList.toggle('is-open', open);
+      if (open) ta.focus();
+    });
+
+    let timer = null;
+    function reportEdit(code) {
+      // Only report a real divergence; equal-to-original clears the edit (null).
+      try {
+        if (code === original) ctx.onBlockEdit(blockId, null);
+        else ctx.onBlockEdit(blockId, code);
+      } catch {
+        // host callback failures must not break editing
+      }
+    }
+
+    // Try to render `code`; on success swap the diagram + re-register annotation
+    // targets (via drawMermaid) and report the edit; on failure keep the last
+    // good diagram and show the error inline.
+    function applyCode(code) {
+      previewMermaid(entry, code)
+        .then(() => {
+          status.textContent = '';
+          status.classList.remove('has-error');
+          entry.code = code;
+          reportEdit(code);
+        })
+        .catch((err) => {
+          status.textContent = 'diagram error: ' + (err && err.message ? err.message : String(err));
+          status.classList.add('has-error');
+        });
+    }
+
+    ta.addEventListener('input', () => {
+      if (timer) clearTimeout(timer);
+      const code = ta.value;
+      timer = setTimeout(() => applyCode(code), 600);
+    });
+
+    resetBtn.addEventListener('click', () => {
+      if (timer) { clearTimeout(timer); timer = null; }
+      ta.value = original;
+      applyCode(original);
+    });
+
+    return el('div', { class: 'blk-mermaid-edit' }, toggleBtn, panel);
+  }
+
+  // Render `code` for the editor preview WITHOUT mutating entry.code on failure.
+  // Resolves once the diagram is swapped into the container (annotation targets
+  // re-registered by drawMermaid); rejects with the render error so the caller
+  // can show it inline and keep the last good diagram.
+  function previewMermaid(entry, code) {
+    const prev = entry.code;
+    entry.code = code;
+    return new Promise((resolve, reject) => {
+      drawMermaid(entry, { onDone: resolve, onError: reject });
+    }).catch((err) => {
+      entry.code = prev;
+      throw err;
+    });
+  }
+
+  function drawMermaid(entry, hooks) {
+    const { container, ctx, blockId } = entry;
+    const onError = hooks && hooks.onError ? hooks.onError : null;
+    const onDone = hooks && hooks.onDone ? hooks.onDone : null;
+    const fail = (err) => {
+      if (onError) onError(err);
+      else showMermaidErr(container, err);
+    };
     loadMermaid().then((mermaid) => {
       try {
         mermaid.initialize({
@@ -575,7 +692,7 @@
         // ignore re-init issues
       }
       const id = 'rly-mmd-' + (++mermaidSeq);
-      const code = block.code || '';
+      const code = entry.code !== undefined ? entry.code : effectiveMermaidCode(entry);
       const onSvg = (svg) => {
         container.innerHTML = svg;
         const svgEl = container.querySelector('svg');
@@ -593,24 +710,26 @@
             svgEl.style.maxWidth = '100%';
           }
         }
-        if (!ctx.annotate) return;
-        const nodes = container.querySelectorAll('.node, .edgeLabel');
-        nodes.forEach((g) => {
-          ctx.annotate.register(g, {
-            blockId,
-            questionId: ctx.questionId,
-            target: {
-              kind: 'mermaid-node',
-              nodeId: g.id || '',
-              text: (g.textContent || '').trim().slice(0, 120),
-            },
+        if (ctx.annotate) {
+          const nodes = container.querySelectorAll('.node, .edgeLabel');
+          nodes.forEach((g) => {
+            ctx.annotate.register(g, {
+              blockId,
+              questionId: ctx.questionId,
+              target: {
+                kind: 'mermaid-node',
+                nodeId: g.id || '',
+                text: (g.textContent || '').trim().slice(0, 120),
+              },
+            });
           });
-        });
+        }
+        if (onDone) onDone();
       };
       try {
         const ret = mermaid.render(id, code);
         if (ret && typeof ret.then === 'function') {
-          ret.then((r) => onSvg(r.svg)).catch((err) => showMermaidErr(container, err));
+          ret.then((r) => onSvg(r.svg)).catch((err) => fail(err));
         } else if (ret && ret.svg) {
           onSvg(ret.svg);
         } else if (typeof ret === 'string') {
@@ -620,9 +739,9 @@
           mermaid.render(id, code, (svg) => onSvg(svg));
         }
       } catch (err) {
-        showMermaidErr(container, err);
+        fail(err);
       }
-    }).catch((err) => showMermaidErr(container, err));
+    }).catch((err) => fail(err));
   }
 
   // Live theme toggle: re-render mermaid diagrams with the new mermaid theme
@@ -630,6 +749,8 @@
   function onThemeChange() {
     for (const entry of mermaidRegistry) {
       try {
+        // re-render with the effective code so an edit survives the toggle
+        entry.code = effectiveMermaidCode(entry);
         drawMermaid(entry);
       } catch {
         // keep the previous svg on failure
@@ -844,6 +965,11 @@
       htmlSrc: ctx && ctx.htmlSrc ? ctx.htmlSrc : (id) => '/html/b/' + id,
       questionId: ctx && ctx.questionId !== undefined ? ctx.questionId : null,
       annotate: ctx && ctx.annotate ? ctx.annotate : null,
+      // editable-mermaid plumbing: edits maps blockId -> edited code; onBlockEdit
+      // reports an accepted change (or null to clear back to the original).
+      edits: ctx && ctx.edits ? ctx.edits : {},
+      onBlockEdit:
+        ctx && typeof ctx.onBlockEdit === 'function' ? ctx.onBlockEdit : () => {},
     };
     for (const block of list) {
       if (!block || !block.type) continue;