@hybridlabor-api/aos 4.17.0 → 4.18.0

package/skills/global_config/plan-canvas/scripts/lib/plan-canvas/annotation-schema.js

@@ -0,0 +1,210 @@
+'use strict';
+
+/**
+ * Plan Canvas annotation schema: whitelist normaliser for browser-submitted
+ * annotations. Output is rebuilt field by field; nothing from the input object
+ * is copied through, unknown keys are dropped, types are never coerced.
+ */
+
+const path = require('path');
+
+const MAX_TEXT = 4000;
+const MAX_SHAPES = 16;
+const MAX_POINTS_TOTAL = 2048;
+const MAX_FREEHAND_POINTS = 512;
+const MAX_CLASSES = 12;
+const MAX_CLASS_SCAN = 200;
+const BBOX_LIMIT = 100000;
+const POINT_MIN = -4;
+const POINT_MAX = 5;
+
+const SHAPE_POINTS = {
+  element: [0, 0],
+  text: [0, 0],
+  rect: [2, 2],
+  arrow: [2, 2],
+  freehand: [2, MAX_FREEHAND_POINTS],
+  blur: [2, 2],
+  comment: [1, 1]
+};
+const COLORS = new Set(['red', 'yellow', 'blue', 'green']);
+const TAG_RE = /^[A-Za-z][A-Za-z0-9-]*$/;
+const TAG_MAX = 60;
+const SEGMENT_RE = /^(?:[a-z][a-z0-9-]{0,30}:nth-of-type\([1-9]\d{0,3}\)|html|body|#[A-Za-z0-9_-]{1,64})$/;
+const MAX_SEGMENTS = 12;
+// Copy of bdb-visual-edit's sanitize-element.mjs allowlist; tests keep them in step.
+const SRC_EXTS = new Set(['.jsx', '.tsx', '.js', '.ts', '.vue', '.svelte', '.astro', '.html', '.mdx']);
+const SRC_SKIP_DIRS = new Set(['node_modules', 'dist', 'build']);
+const CONFIG_NAME_RE = /\.config\.[^/]*$/i;
+const CLASS_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const SRC_RE = /^[\w@.-]+(?:\/[\w@.-]+)*\.[A-Za-z0-9]{1,8}:\d{1,6}(?::\d{1,5})?$/;
+const ORIGIN_RE = /^http:\/\/(127\.0\.0\.1|localhost|\[::1\]):(\d{1,5})$/i;
+const LOOPBACK_URL_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+const CONTROL_RE = /[\u0000-\u001f\u007f-\u009f​-‏‪-‮⁦-⁩]/g;
+const WHITESPACE_CONTROL_RE = /[\t\n\r]+/g;
+
+const own = (obj, key) => (obj !== null && typeof obj === 'object' && Object.hasOwn(obj, key) ? obj[key] : undefined);
+const isNum = value => typeof value === 'number' && Number.isFinite(value);
+
+// Tabs and line breaks become one space so multi-line comments stay readable;
+// every other control, bidi and zero-width character is removed.
+function cleanText(value, max = MAX_TEXT) {
+  if (typeof value !== 'string') return '';
+  let out = value.replace(WHITESPACE_CONTROL_RE, ' ').replace(CONTROL_RE, '').slice(0, max);
+  if (/[\ud800-\udbff]$/.test(out)) out = out.slice(0, -1);
+  return out;
+}
+
+// Returns the canonical `http://host:port` for a loopback app origin, else null.
+function normalizeOrigin(value) {
+  if (typeof value !== 'string') return null;
+  const match = ORIGIN_RE.exec(value);
+  if (!match) return null;
+  const port = Number(match[2]);
+  if (port < 1024 || port > 65535) return null;
+  return `http://${match[1].toLowerCase()}:${port}`;
+}
+
+function cleanSrcLoc(value) {
+  if (typeof value !== 'string' || value.length > 240 || !SRC_RE.test(value)) return null;
+  const file = value.slice(0, value.search(/:\d/));
+  if (file.split('/').some(s => s.startsWith('.') || SRC_SKIP_DIRS.has(s))) return null;
+  if (!SRC_EXTS.has(path.extname(file)) || CONFIG_NAME_RE.test(file)) return null;
+  return value;
+}
+
+function cleanAppUrl(value, boundOrigin) {
+  const fallback = boundOrigin || null;
+  if (typeof value !== 'string' || value.length > 2000) return fallback;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'http:' || !LOOPBACK_URL_HOSTS.has(url.hostname) || url.port === '') return fallback;
+    if (!boundOrigin || normalizeOrigin(url.origin) !== boundOrigin) return fallback;
+    const clean = `${url.origin}${url.pathname}`;
+    return clean.length <= 300 ? clean : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function cleanTarget(raw, origin, boundOrigin) {
+  if (origin !== 'app') return { origin: 'canvas', url: null };
+  const target = { origin: 'app', url: cleanAppUrl(own(own(raw, 'target'), 'url'), boundOrigin) };
+  const srcLoc = cleanSrcLoc(own(own(raw, 'target'), 'srcLoc'));
+  if (srcLoc) target.srcLoc = srcLoc;
+  return target;
+}
+
+function cleanClasses(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (let i = 0; i < Math.min(value.length, MAX_CLASS_SCAN) && out.length < MAX_CLASSES; i++) {
+    const c = value[i];
+    if (typeof c === 'string' && CLASS_RE.test(c) && !out.includes(c)) out.push(c);
+  }
+  return out;
+}
+
+// Only the tag:nth-of-type grammar the client generates passes; free text is blanked.
+function cleanSelector(value) {
+  if (typeof value !== 'string' || value.length > 600) return '';
+  const parts = value.split(' > ');
+  return parts.length <= MAX_SEGMENTS && parts.every(p => SEGMENT_RE.test(p)) ? value : '';
+}
+
+function cleanAnchor(raw) {
+  const selector = own(raw, 'selector');
+  if (typeof selector !== 'string') return null;
+  const tag = own(raw, 'tag');
+  const anchor = {
+    selector: cleanSelector(selector),
+    tag: typeof tag === 'string' && TAG_RE.test(tag) ? tag.slice(0, TAG_MAX) : '',
+    snippet: cleanText(own(raw, 'snippet'), 400)
+  };
+  const classes = cleanClasses(own(raw, 'classes'));
+  if (classes.length) anchor.classes = classes;
+  const range = own(raw, 'textRange');
+  if (range !== null && typeof range === 'object') {
+    anchor.textRange = { text: cleanText(own(range, 'text'), 1000) };
+  }
+  return anchor;
+}
+
+const roundTo = (n, digits) => Number(n.toFixed(digits));
+const clampPoint = n => roundTo(Math.min(POINT_MAX, Math.max(POINT_MIN, n)), 4);
+
+// Any malformed shape rejects the whole item: a half-drawn annotation would
+// mislead the agent about what the human marked.
+function cleanShapes(value) {
+  if (!Array.isArray(value) || value.length < 1 || value.length > MAX_SHAPES) return null;
+  const shapes = [];
+  let total = 0;
+  for (const rawShape of value) {
+    const type = own(rawShape, 'type');
+    const limits = typeof type === 'string' && Object.hasOwn(SHAPE_POINTS, type) ? SHAPE_POINTS[type] : null;
+    if (!limits) return null;
+    const shape = { type };
+    if (limits[1] > 0) {
+      const points = own(rawShape, 'points');
+      if (!Array.isArray(points) || points.length < limits[0] || points.length > limits[1]) return null;
+      total += points.length;
+      if (total > MAX_POINTS_TOTAL) return null;
+      shape.points = [];
+      for (const p of points) {
+        if (!Array.isArray(p) || p.length !== 2 || !isNum(p[0]) || !isNum(p[1])) return null;
+        shape.points.push([clampPoint(p[0]), clampPoint(p[1])]);
+      }
+    }
+    const color = own(rawShape, 'color');
+    if (typeof color === 'string' && COLORS.has(color)) shape.color = color;
+    shapes.push(shape);
+  }
+  return shapes;
+}
+
+function cleanViewport(raw) {
+  const w = own(raw, 'w');
+  const h = own(raw, 'h');
+  const dpr = own(raw, 'dpr');
+  if (!isNum(w) || !isNum(h) || !isNum(dpr)) return null;
+  const out = { w: Math.round(w), h: Math.round(h), dpr: roundTo(dpr, 2) };
+  if (out.w < 1 || out.w > BBOX_LIMIT || out.h < 1 || out.h > BBOX_LIMIT || out.dpr < 0.5 || out.dpr > 8) return null;
+  return out;
+}
+
+function cleanPage(raw) {
+  const out = {};
+  for (const k of ['x', 'y', 'w', 'h']) {
+    const n = own(raw, k);
+    if (!isNum(n)) return null;
+    out[k] = Math.round(Math.min(BBOX_LIMIT, Math.max(0, n)));
+  }
+  return out;
+}
+
+/**
+ * @param raw       untrusted annotation object
+ * @param origin    'canvas' | 'app', set by the endpoint, never by the body
+ * @param boundOrigin  the token's bound app origin (app only)
+ * @returns the validated item fields (without id/at/kind) or null
+ */
+function normalizeAnnotation(raw, { origin = 'canvas', boundOrigin = null } = {}) {
+  if (raw === null || typeof raw !== 'object') return null;
+  const text = cleanText(own(raw, 'text'));
+  if (!text) return null;
+  const anchor = cleanAnchor(own(raw, 'anchor'));
+  if (!anchor) return null;
+  const fields = { text, anchor, target: cleanTarget(raw, origin === 'app' ? 'app' : 'canvas', boundOrigin) };
+  if (own(raw, 'shapes') !== undefined) {
+    const shapes = cleanShapes(own(raw, 'shapes'));
+    if (!shapes) return null;
+    fields.shapes = shapes;
+  }
+  const viewport = cleanViewport(own(raw, 'viewport'));
+  if (viewport) fields.viewport = viewport;
+  const page = cleanPage(own(raw, 'page'));
+  if (page) fields.page = page;
+  return fields;
+}
+
+module.exports = { cleanSrcLoc, cleanText, normalizeAnnotation, normalizeOrigin };

package/skills/global_config/plan-canvas/scripts/lib/plan-canvas/route.js

@@ -0,0 +1,10 @@
+'use strict';
+
+function routeFor(item, { planHasComponents = false } = {}) {
+  if (!item || typeof item !== 'object') return 'artifact';
+  if (item.kind === 'annotation' && item.target && item.target.origin === 'app') return 'visual-edit';
+  if (item.kind === 'verdict' && item.verdict === 'approve' && planHasComponents) return 'build';
+  return 'artifact';
+}
+
+module.exports = { routeFor };

package/skills/global_config/plan-canvas/scripts/lib/plan-canvas/sdk.js

@@ -1,239 +1,15 @@
 'use strict';
 
 /**
- * Plan Canvas artifact SDK — the script injected into the reviewed artifact.
- *
- * The artifact runs in a sandboxed iframe without allow-same-origin, so this
- * script can only talk to the chrome via postMessage. It renders all of its
- * own UI inside a shadow root so it never annotates itself and never leaks
- * styles into the artifact.
- *
- * Source: affaan-m/ECC — MIT, see THIRD_PARTY_NOTICES.md
+ * Plan Canvas artifact SDK: the script injected into the reviewed artifact.
+ * The layer itself lives in ./annotate-client (shared with /annotate.js).
+ * Source: affaan-m/ECC (MIT), see THIRD_PARTY_NOTICES.md
  */
 
-function artifactSdkJs() {
-  return `'use strict';
-(() => {
-  if (window.parent === window) return; // only meaningful inside the canvas
-  if (window.__eccPlanCanvasSdk) return;
-  window.__eccPlanCanvasSdk = true;
-
-  let annotate = true;
-  let card = null;
-
-  const post = msg => window.parent.postMessage(msg, '*');
-
-  // --- shadow-root UI host --------------------------------------------
-  const host = document.createElement('div');
-  host.setAttribute('data-ecc-plan-canvas', 'ui');
-  host.style.cssText = 'position:absolute;top:0;left:0;width:0;height:0;z-index:2147483647';
-  const root = host.attachShadow({ mode: 'open' });
-  root.innerHTML = \`
-  <style>
-    :host{all:initial}
-    .hl{position:fixed;pointer-events:none;border:1.5px solid #6885e8;background:rgba(104,133,232,0.12);border-radius:4px;display:none;z-index:2147483646;transition:all .06s ease-out}
-    .selhint{position:absolute;display:none;z-index:2147483647;background:#101218;color:#dfe2e9;border:1px solid #272c3e;border-radius:6px;padding:4px 10px;font:600 11.5px -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;cursor:pointer;box-shadow:0 8px 32px rgba(0,0,0,0.6)}
-    .selhint:hover{border-color:#6885e8}
-    .card{position:absolute;display:none;z-index:2147483647;width:300px;background:#101218;border:1px solid #272c3e;border-radius:8px;box-shadow:0 8px 32px rgba(0,0,0,0.6);font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;color:#dfe2e9}
-    .card h4{margin:0;padding:10px 12px 0;font-size:11px;font-weight:600;text-transform:uppercase;letter-spacing:.05em;color:#80859a}
-    .card .snippet{padding:4px 12px 0;font:10.5px 'SF Mono','Fira Code',monospace;color:#4acbbe;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
-    .card textarea{display:block;width:calc(100% - 24px);margin:8px 12px;min-height:56px;resize:vertical;background:#13161e;border:1px solid #1d2130;border-radius:6px;color:#dfe2e9;font:12.5px -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;padding:7px 9px;outline:none;box-sizing:border-box}
-    .card textarea:focus{border-color:#6885e8}
-    .card .row{display:flex;justify-content:flex-end;gap:8px;padding:0 12px 12px}
-    .card button{border-radius:6px;font:600 11.5px -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;padding:5px 12px;cursor:pointer}
-    .card .cancel{background:none;border:1px solid #1d2130;color:#80859a}
-    .card .cancel:hover{color:#dfe2e9;border-color:#272c3e}
-    .card .queue{background:#6885e8;border:1px solid #6885e8;color:#fff}
-    .card .queue:hover{background:#3d5ab8}
-    .card .keys{padding:0 12px 10px;font-size:9.5px;color:#4c5168}
-  </style>
-  <div class="hl"></div>
-  <button class="selhint" type="button">Annotate selection</button>
-  <div class="card">
-    <h4></h4>
-    <div class="snippet"></div>
-    <textarea placeholder="What should change here?"></textarea>
-    <div class="row">
-      <button class="cancel" type="button">Cancel</button>
-      <button class="queue" type="button">Queue</button>
-    </div>
-    <div class="keys">Enter to queue &middot; Cmd/Ctrl+Enter to queue &amp; send</div>
-  </div>\`;
-  const attach = () => document.body ? document.body.appendChild(host) : null;
-  if (document.body) attach();
-  else document.addEventListener('DOMContentLoaded', attach);
-
-  const hl = root.querySelector('.hl');
-  const selhint = root.querySelector('.selhint');
-  const cardEl = root.querySelector('.card');
-  const cardTitle = cardEl.querySelector('h4');
-  const cardSnippet = cardEl.querySelector('.snippet');
-  const cardText = cardEl.querySelector('textarea');
-
-  // --- selectors & context ---------------------------------------------
-  const esc = v => (window.CSS && CSS.escape) ? CSS.escape(v) : v.replace(/[^a-zA-Z0-9_-]/g, '\\\\$&');
-  function selectorFor(el) {
-    const parts = [];
-    let node = el;
-    for (let depth = 0; node && node.nodeType === 1 && depth < 6; depth++) {
-      if (node.id) { parts.unshift('#' + esc(node.id)); return parts.join(' > '); }
-      const tag = node.tagName.toLowerCase();
-      if (tag === 'body' || tag === 'html') { parts.unshift(tag); break; }
-      let nth = 1;
-      let sib = node;
-      while ((sib = sib.previousElementSibling)) if (sib.tagName === node.tagName) nth++;
-      parts.unshift(tag + ':nth-of-type(' + nth + ')');
-      node = node.parentElement;
-    }
-    return parts.join(' > ');
-  }
-  function snippetFor(el) {
-    return (el.innerText || el.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 200);
-  }
-  const INTERACTIVE = new Set(['button', 'input', 'select', 'textarea', 'option', 'label', 'summary', 'a']);
-  function isInteractive(el) {
-    let node = el;
-    while (node && node.nodeType === 1) {
-      if (INTERACTIVE.has(node.tagName.toLowerCase()) || node.isContentEditable) return true;
-      node = node.parentElement;
-    }
-    return false;
-  }
-  const isOurs = el => el === host || host.contains(el);
-
-  // --- annotation card ---------------------------------------------------
-  function openCard(target) {
-    card = target;
-    cardTitle.textContent = target.kindLabel;
-    cardSnippet.textContent = target.anchor.snippet || target.anchor.selector;
-    cardText.value = '';
-    cardEl.style.display = 'block';
-    const x = Math.min(target.x, window.innerWidth - 320) + window.scrollX;
-    const y = target.y + 12 + window.scrollY;
-    cardEl.style.left = Math.max(8, x) + 'px';
-    cardEl.style.top = y + 'px';
-    cardText.focus();
-  }
-  function closeCard() {
-    card = null;
-    cardEl.style.display = 'none';
-  }
-  function queueCard(sendNow) {
-    if (!card) return;
-    const text = cardText.value.trim();
-    if (!text) { cardText.focus(); return; }
-    post({
-      type: sendNow ? 'pc:queue-and-send' : 'pc:queue',
-      item: { kind: 'annotation', text, anchor: card.anchor }
-    });
-    closeCard();
-  }
-  cardEl.querySelector('.cancel').addEventListener('click', closeCard);
-  cardEl.querySelector('.queue').addEventListener('click', () => queueCard(false));
-  cardText.addEventListener('keydown', e => {
-    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) { e.preventDefault(); queueCard(true); }
-    else if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); queueCard(false); }
-    else if (e.key === 'Escape') closeCard();
-  });
+const { annotateClientJs } = require('./annotate-client');
 
-  // --- element hover / click ---------------------------------------------
-  document.addEventListener('mousemove', e => {
-    if (!annotate || card) { hl.style.display = 'none'; return; }
-    const el = e.target;
-    if (!el || isOurs(el) || el === document.body || el === document.documentElement || isInteractive(el)) {
-      hl.style.display = 'none';
-      return;
-    }
-    const rect = el.getBoundingClientRect();
-    hl.style.display = 'block';
-    hl.style.left = rect.left - 2 + 'px';
-    hl.style.top = rect.top - 2 + 'px';
-    hl.style.width = rect.width + 'px';
-    hl.style.height = rect.height + 'px';
-  }, true);
-
-  document.addEventListener('click', e => {
-    if (!annotate) return;
-    const el = e.target;
-    if (isOurs(el)) return;
-    if (card) { if (!cardEl.contains(e.composedPath()[0])) closeCard(); return; }
-    if (isInteractive(el)) return; // let controls behave natively
-    const selection = window.getSelection();
-    if (selection && !selection.isCollapsed) return; // handled by selection flow
-    if (el === document.body || el === document.documentElement) return;
-    e.preventDefault();
-    e.stopPropagation();
-    hl.style.display = 'none';
-    openCard({
-      kindLabel: 'Annotate <' + el.tagName.toLowerCase() + '>',
-      anchor: { selector: selectorFor(el), tag: el.tagName.toLowerCase(), snippet: snippetFor(el) },
-      x: e.clientX,
-      y: e.clientY
-    });
-  }, true);
-
-  // --- text selection -------------------------------------------------------
-  document.addEventListener('mouseup', e => {
-    if (!annotate || card || isOurs(e.target)) return;
-    setTimeout(() => {
-      const selection = window.getSelection();
-      const text = selection ? String(selection).replace(/\\s+/g, ' ').trim() : '';
-      if (!text || !selection.rangeCount) { selhint.style.display = 'none'; return; }
-      const rect = selection.getRangeAt(0).getBoundingClientRect();
-      selhint.style.display = 'block';
-      selhint.style.left = rect.left + window.scrollX + 'px';
-      selhint.style.top = rect.bottom + 6 + window.scrollY + 'px';
-      selhint.onclick = () => {
-        selhint.style.display = 'none';
-        const anchorNode = selection.anchorNode;
-        const el = anchorNode && anchorNode.nodeType === 1 ? anchorNode : anchorNode && anchorNode.parentElement;
-        openCard({
-          kindLabel: 'Annotate selection',
-          anchor: {
-            selector: el ? selectorFor(el) : 'body',
-            tag: 'text',
-            snippet: text.slice(0, 200),
-            textRange: { text: text.slice(0, 1000) }
-          },
-          x: rect.left,
-          y: rect.bottom
-        });
-      };
-    }, 0);
-  }, true);
-  document.addEventListener('selectionchange', () => {
-    const selection = window.getSelection();
-    if (!selection || selection.isCollapsed) selhint.style.display = 'none';
-  });
-
-  // --- chrome bridge ---------------------------------------------------------
-  window.addEventListener('message', e => {
-    const msg = e.data || {};
-    if (msg.type === 'pc:set-mode') {
-      annotate = Boolean(msg.annotate);
-      if (!annotate) { hl.style.display = 'none'; selhint.style.display = 'none'; closeCard(); }
-    } else if (msg.type === 'pc:restore-scroll') {
-      window.scrollTo(msg.x || 0, msg.y || 0);
-    }
-  });
-  document.addEventListener('keydown', e => {
-    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'i') {
-      e.preventDefault();
-      post({ type: 'pc:toggle-mode' });
-    } else if (e.key === 'Escape' && card) closeCard();
-  }, true);
-
-  let scrollTimer = null;
-  window.addEventListener('scroll', () => {
-    if (scrollTimer) return;
-    scrollTimer = setTimeout(() => {
-      scrollTimer = null;
-      post({ type: 'pc:scroll', x: window.scrollX, y: window.scrollY });
-    }, 150);
-  }, { passive: true });
-
-  post({ type: 'pc:ready' });
-})();`;
+function artifactSdkJs() {
+  return annotateClientJs({ transport: 'postMessage' });
 }
 
 module.exports = { artifactSdkJs };

package/skills/global_config/plan-canvas/scripts/lib/plan-canvas/server.js

@@ -17,8 +17,10 @@ const http = require('http');
 const path = require('path');
 
 const { buildAllowedHostnames, isAllowedFetchSite, isAllowedHostHeader, isAllowedOrigin } = require('../loopback-guard');
+const { createAnnotateHandler } = require('./annotate-server');
 const { renderMarkdown } = require('./markdown');
 const { artifactSdkJs } = require('./sdk');
+const { ensureTrailOnApprove } = require('./trail-on-approve');
 const {
   canvasCss,
   canvasClientJs,
@@ -165,11 +167,23 @@ function createPlanCanvasServer({
   typingExpiryMs = DEFAULT_TYPING_EXPIRY_MS,
   presenceSweepMs = DEFAULT_PRESENCE_SWEEP_MS,
   onIdleShutdown = null,
+  now = Date.now,
   log = () => {}
 } = {}) {
   if (!store) throw new Error('createPlanCanvasServer requires a session store');
 
   const allowedHostnames = buildAllowedHostnames(host);
+  const annotate = createAnnotateHandler({
+    store,
+    version,
+    now,
+    log,
+    onQueued: key => {
+      wake.emit(`wake:${key}`);
+      broadcast(key, 'chat-sync', { chat: store.get(key).chat });
+      broadcastPresence(key);
+    }
+  });
   const wake = new EventEmitter();
   wake.setMaxListeners(0);
   const sseClients = new Map(); // key -> Set<res>
@@ -334,6 +348,7 @@ function createPlanCanvasServer({
       if (!artifactPath) {
         return sendJson(res, 403, { error: 'artifact path is outside the workspace' });
       }
+      const resumed = Boolean(store.findByFile(artifactPath));
       const { session, refused } = store.open(artifactPath, { reopen: Boolean(body.reopen) });
       if (refused) {
         return sendJson(res, 409, {
@@ -348,7 +363,9 @@ function createPlanCanvasServer({
         status: 'open',
         key: session.key,
         file: session.file,
-        url: `/canvas/${session.key}`
+        url: `/canvas/${session.key}`,
+        resumed,
+        viewers: sseClients.get(session.key)?.size || 0
       });
     }
 
@@ -437,16 +454,32 @@ function createPlanCanvasServer({
       return sendJson(res, 200, { status: 'ended', endedBy: 'agent' });
     }
 
-    const sessionMatch = pathname.match(/^\/api\/session\/([a-f0-9]{12})\/(feedback|end|reply|typing)$/);
+    const sessionMatch = pathname.match(/^\/api\/session\/([a-f0-9]{12})\/(feedback|end|reply|typing|resume)$/);
     if (sessionMatch && req.method === 'POST') {
       const [, key, action] = sessionMatch;
       const session = store.get(key);
       if (!session) return sendJson(res, 404, { error: 'unknown session' });
 
+      if (action === 'resume') {
+        if (!fs.existsSync(session.file)) return sendJson(res, 404, { error: 'artifact file no longer exists' });
+        if (!confinedArtifactPath(session.file, workspaceRoot)) {
+          return sendJson(res, 403, { error: 'artifact path is outside the workspace' });
+        }
+        store.open(session.file, { reopen: true });
+        watchSession(session);
+        broadcastPresence(key);
+        res.writeHead(303, { location: `/canvas/${key}` });
+        return res.end();
+      }
+
       if (action === 'feedback') {
         const body = await readJsonBody(req);
         const result = store.queueFeedback(key, body.items, { endSession: Boolean(body.endSession) });
         if (!result) return sendJson(res, 409, { error: 'session already ended' });
+        // Record the trail outcome before waking a parked await so it can report it.
+        if (result.accepted.some(i => i.kind === 'verdict' && i.verdict === 'approve')) {
+          ensureTrailOnApprove({ file: session.file, key, log, onOutcome: outcome => store.setTrailOutcome(key, outcome) });
+        }
         wake.emit(`wake:${key}`);
         broadcast(key, 'chat-sync', { chat: store.get(key).chat });
         if (body.endSession) broadcast(key, 'ended', { endedBy: 'user' });
@@ -584,11 +617,19 @@ function createPlanCanvasServer({
     if (!isAllowedHostHeader(req.headers.host, allowedHostnames)) {
       return sendJson(res, 403, { error: 'forbidden host header' });
     }
+    let url;
+    try {
+      url = new URL(req.url, `http://${req.headers.host}`);
+    } catch {
+      return sendJson(res, 400, { error: 'bad request target' });
+    }
+    const { pathname } = url;
+    // Annotate routes are called from a dev app on another loopback origin, so
+    // they do their own Origin/token checks instead of the same-origin gate.
+    if (annotate.handles(pathname)) return annotate.handle(req, res, url);
     if (!isAllowedOrigin(req.headers.origin, allowedHostnames, boundPort)) {
       return sendJson(res, 403, { error: 'forbidden origin' });
     }
-    const url = new URL(req.url, `http://${req.headers.host}`);
-    const { pathname } = url;
     // The artifact iframe is sandboxed without allow-same-origin, so its script
     // and asset loads arrive as Sec-Fetch-Site: cross-site. Only those read-only
     // static paths may skip the fetch-site check; everything else keeps it.