spectater 0.1.0 → 0.2.0

package/src/server.js

@@ -4,7 +4,6 @@ import { readFile } from 'node:fs/promises';
 import http from 'node:http';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
-import { startControl } from './control.js';
 import { feedback, feedbackMarkdown } from './storage.js';
 import { watchChange } from './watch.js';
 
@@ -15,16 +14,50 @@ const assets = new Map([
   ['/favicon.svg', ['../web/favicon.svg', 'image/svg+xml']],
 ]);
 const shell = await readFile(new URL('../web/index.html', import.meta.url), 'utf8');
+const headers = {
+  'Content-Security-Policy':
+    "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'Referrer-Policy': 'no-referrer',
+  'Cache-Control': 'no-store',
+};
+export const MAX_WAIT_MS = 3_600_000;
 
+async function readJson(request) {
+  let bytes = 0;
+  const chunks = [];
+  for await (const chunk of request) {
+    bytes += chunk.length;
+    if (bytes > 65536) {
+      const error = new Error('Request exceeds 64 KiB.');
+      error.statusCode = 413;
+      throw error;
+    }
+    chunks.push(chunk);
+  }
+  const input = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+  if (!input || typeof input !== 'object' || Array.isArray(input))
+    throw new Error('Expected a JSON object.');
+  return input;
+}
+
+/**
+ * Serves one review to the browser (capability in the URL fragment) and to agent commands
+ * (`/agent/*`, same capability). `onIdle` fires after `idleTimeout` ms with no browser stream
+ * and no waiting agent; `onStop` fires after an agent stop request is answered.
+ */
 export async function startServer(review, options = {}) {
+  const { watch = true, idleTimeout = 0, onIdle = () => {}, onStop = () => {} } = options;
   const capability = randomBytes(32).toString('hex');
   const route = `/review/${encodeURIComponent(review.view().change)}`;
   let origin;
-  let listeners = 0;
   let watchStatus = { automatic: false };
   let watcher,
     stopping = false,
-    watcherTask = Promise.resolve();
+    watcherTask = Promise.resolve(),
+    waiter = null,
+    idleTimer;
   const clients = new Set();
   const broadcast = (event) => {
     for (const client of clients) {
@@ -34,6 +67,31 @@ export async function startServer(review, options = {}) {
       } else client.write(`${JSON.stringify(event)}\n`);
     }
   };
+  const touch = () => {
+    clearTimeout(idleTimer);
+    if (!stopping && idleTimeout > 0 && !clients.size && !waiter)
+      idleTimer = setTimeout(onIdle, idleTimeout);
+  };
+  const presence = () => {
+    broadcast({ type: 'presence', listeners: waiter ? 1 : 0 });
+    touch();
+  };
+  const finishWait = (target, result) => {
+    if (!target || waiter !== target) return;
+    waiter = null;
+    clearTimeout(target.timer);
+    if (!target.response.destroyed) target.response.end(JSON.stringify(result));
+    presence();
+  };
+  const deliver = async (target) => {
+    try {
+      const batch = await review.deliver();
+      if (batch) finishWait(target, { status: 'batch', batch });
+      else if (review.state.endedAt) finishWait(target, { status: 'ended' });
+    } catch (error) {
+      finishWait(target, { status: 'error', error: error.message });
+    }
+  };
   const reportWatch = (event) => {
     watchStatus = { automatic: event.automatic, watchError: event.error };
     broadcast(event);
@@ -46,25 +104,67 @@ export async function startServer(review, options = {}) {
           await watcher?.close();
           watcher = undefined;
           reportWatch({ type: 'watch', automatic: false });
-        } else if (!watcher && options.watch !== false)
-          watcher = await watchChange(review, reportWatch);
+        } else if (!watcher && watch) watcher = await watchChange(review, reportWatch);
       })
       .catch((error) => reportWatch({ type: 'watch', automatic: false, error: error.message }));
     return watcherTask;
   };
+  const refresh = () => (watcher ? watcher.retry() : review.refresh());
   const unsubscribe = review.subscribe((event) => {
     if (['refresh', 'activity', 'lifecycle'].includes(event.type)) broadcast(event);
-    if (event.type === 'lifecycle') void syncWatcher();
+    if (event.type === 'lifecycle') {
+      void syncWatcher();
+      // Re-check through deliver so a final Send & End batch reaches the waiter before ended.
+      if (event.ended && waiter) void deliver(waiter);
+    }
+    if (event.type === 'batch' && waiter) void deliver(waiter);
   });
+
+  const agent = {
+    status: () => ({
+      status: 'active',
+      url,
+      ended: Boolean(review.state.endedAt),
+      listening: Boolean(waiter),
+    }),
+    refresh: async () => ({ status: 'refreshed', revision: (await refresh()).revision }),
+    end: async () => {
+      await review.mutate({ action: 'end', revision: review.state.revision });
+      return { status: 'ended' };
+    },
+    resume: async () => {
+      await review.mutate({ action: 'resume', revision: review.state.revision });
+      return { status: 'resumed' };
+    },
+    reply: async (input) => ({
+      status: 'recorded',
+      ...(await review.recordActivity(input.batch, input)),
+    }),
+    stop: () => {
+      setImmediate(onStop);
+      return { status: 'stopping' };
+    },
+  };
+
+  function wait(input, response) {
+    const timeout = input.timeout ?? 540_000;
+    if (!Number.isInteger(timeout) || timeout < 0 || timeout > MAX_WAIT_MS)
+      throw new Error(`timeout must be 0–${MAX_WAIT_MS} ms.`);
+    if (waiter && !input.takeover) return { status: 'listener_active' };
+    finishWait(waiter, { status: 'listener_replaced' });
+    response.writeHead(200, { ...headers, 'Content-Type': 'application/json; charset=utf-8' });
+    const target = { response };
+    waiter = target;
+    presence();
+    response.once('close', () => finishWait(target, { status: 'disconnected' }));
+    // Queued feedback wins over a zero timeout, so the timer starts after the first delivery check.
+    void deliver(target).then(() => {
+      if (waiter === target)
+        target.timer = setTimeout(() => finishWait(target, { status: 'timeout' }), timeout);
+    });
+  }
+
   const server = http.createServer(async (request, response) => {
-    const headers = {
-      'Content-Security-Policy':
-        "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
-      'X-Content-Type-Options': 'nosniff',
-      'X-Frame-Options': 'DENY',
-      'Referrer-Policy': 'no-referrer',
-      'Cache-Control': 'no-store',
-    };
     const send = (code, data, type = 'application/json') => {
       response.writeHead(code, { ...headers, 'Content-Type': `${type}; charset=utf-8` });
       response.end(type === 'application/json' ? JSON.stringify(data) : data);
@@ -100,10 +200,14 @@ export async function startServer(review, options = {}) {
           'Content-Type': 'application/x-ndjson; charset=utf-8',
         });
         response.write(
-          `${JSON.stringify({ type: 'ready', revision: review.state.revision, listeners, ...watchStatus })}\n`,
+          `${JSON.stringify({ type: 'ready', revision: review.state.revision, listeners: waiter ? 1 : 0, ...watchStatus })}\n`,
         );
         clients.add(response);
-        response.once('close', () => clients.delete(response));
+        touch();
+        response.once('close', () => {
+          clients.delete(response);
+          touch();
+        });
         return;
       }
       if (request.method === 'GET' && url.pathname === `${route}/state`)
@@ -117,37 +221,33 @@ export async function startServer(review, options = {}) {
         url.pathname.startsWith(`${route}/batch/`) && url.pathname.slice(`${route}/batch/`.length);
       if (request.method === 'GET' && batchMatch && /^[a-f0-9-]{36}$/.test(batchMatch))
         return send(200, { markdown: feedbackMarkdown(feedback(review.state, batchMatch)) });
+      const operation = url.pathname.startsWith('/agent/') && url.pathname.slice('/agent/'.length);
+      const browserMutation = [`${route}/refresh`, `${route}/action`].includes(url.pathname);
       if (
         request.method !== 'POST' ||
-        ![`${route}/refresh`, `${route}/action`].includes(url.pathname)
+        !(browserMutation || operation === 'wait' || Object.hasOwn(agent, operation))
       )
         return send(404, { error: 'Unknown route.' });
       if (
-        request.headers.origin !== origin ||
+        (browserMutation && request.headers.origin !== origin) ||
         request.headers['content-type'] !== 'application/json'
       )
         return send(403, { error: 'Mutation requires this review origin and JSON.' });
-      let bytes = 0;
-      const chunks = [];
-      for await (const chunk of request) {
-        bytes += chunk.length;
-        if (bytes > 65536) {
-          send(413, { error: 'Request exceeds 64 KiB.' });
-          request.resume();
-          return;
-        }
-        chunks.push(chunk);
-      }
-      const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
-      if (!input || typeof input !== 'object' || Array.isArray(input))
-        throw new Error('Expected a JSON object.');
-      if (url.pathname.endsWith('/refresh')) {
-        const state = watcher ? await watcher.retry() : await review.refresh();
-        return send(200, { ...state, ...watchStatus });
+      const input = await readJson(request);
+      if (operation === 'wait') {
+        const refused = wait(input, response);
+        if (refused) send(200, refused);
+        return;
       }
+      if (operation) return send(200, await agent[operation](input));
+      if (url.pathname.endsWith('/refresh'))
+        return send(200, { ...(await refresh()), ...watchStatus });
       return send(200, await review.mutate(input));
     } catch (error) {
-      send(/conflict/i.test(error.message) ? 409 : 400, { error: error.message });
+      if (response.headersSent) return;
+      send(error.statusCode || (/conflict/i.test(error.message) ? 409 : 400), {
+        error: error.message,
+      });
     }
   });
   server.requestTimeout = 20000;
@@ -159,34 +259,20 @@ export async function startServer(review, options = {}) {
   });
   origin = `http://127.0.0.1:${server.address().port}`;
   const url = `${origin}${route}#${capability}`;
-  let control;
-  try {
-    control = await startControl(
-      review,
-      url,
-      (count) => {
-        listeners = count;
-        broadcast({ type: 'presence', listeners });
-      },
-      () => (watcher ? watcher.retry() : review.refresh()),
-    );
-  } catch (error) {
-    unsubscribe();
-    server.closeAllConnections();
-    server.close();
-    throw error;
-  }
   await syncWatcher();
+  touch();
   return {
     url,
     origin,
     route,
     async close() {
       stopping = true;
+      clearTimeout(idleTimer);
       unsubscribe();
+      finishWait(waiter, { status: 'stopped' });
+      await new Promise((resolve) => setImmediate(resolve));
       await watcherTask;
       await watcher?.close();
-      await control.close();
       for (const client of clients) client.end();
       clients.clear();
       server.closeAllConnections();
@@ -198,8 +284,8 @@ export async function startServer(review, options = {}) {
   };
 }
 
+const openers = { darwin: 'open', linux: 'xdg-open' };
 export async function openBrowser(url, run = promisify(execFile), platform = process.platform) {
-  if (platform !== 'darwin')
-    throw new Error('Automatic opening is verified only on macOS; use the printed URL.');
-  await run('open', [url], { timeout: 10000, maxBuffer: 65536 });
+  if (!openers[platform]) throw new Error('Automatic opening supports macOS and Linux only.');
+  await run(openers[platform], [url], { timeout: 10000, maxBuffer: 65536 });
 }

package/src/storage.js

@@ -1,17 +1,15 @@
 import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
-import { chmod, lstat, mkdir, open, realpath, rename, unlink } from 'node:fs/promises';
+import { chmod, link, lstat, mkdir, open, realpath, rename, unlink } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { hash, within } from './discovery.js';
-import { readLimited } from './files.js';
+import { readFileLimited, readLimited } from './files.js';
 
 export function stateDirectory() {
   if (process.env.SPECTATER_STATE_DIR) return path.resolve(process.env.SPECTATER_STATE_DIR);
   if (process.platform === 'darwin')
     return path.join(os.homedir(), 'Library', 'Application Support', 'SpecTater');
-  if (process.platform === 'win32')
-    return path.join(process.env.LOCALAPPDATA || os.homedir(), 'SpecTater');
   return path.join(
     process.env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state'),
     'spectater',
@@ -56,6 +54,11 @@ function validate(state, id) {
     (typeof state.endedAt !== 'string' || !Number.isFinite(Date.parse(state.endedAt)))
   )
     throw new Error('Corrupt review completion metadata.');
+  if (
+    state.endRequestedAt !== undefined &&
+    (typeof state.endRequestedAt !== 'string' || !Number.isFinite(Date.parse(state.endRequestedAt)))
+  )
+    throw new Error('Corrupt review completion metadata.');
   for (const [key, snapshot] of Object.entries(state.snapshots)) {
     if (
       typeof snapshot.source !== 'string' ||
@@ -97,7 +100,10 @@ function validate(state, id) {
       typeof b.id !== 'string' ||
       b.sequence !== i + 1 ||
       typeof b.submittedAt !== 'string' ||
-      !Array.isArray(b.entries)
+      !Array.isArray(b.entries) ||
+      (b.message !== undefined &&
+        (typeof b.message !== 'string' || !b.message.trim() || b.message.length > 10000)) ||
+      (!b.entries.length && b.message === undefined)
     )
       throw new Error('Corrupt feedback batch. Restore a valid copy.');
   });
@@ -212,6 +218,25 @@ export async function loadState(directory, id) {
   }
 }
 
+export function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+// A lock is abandoned only when it names a process that no longer exists.
+async function abandoned(lock) {
+  try {
+    const { pid } = JSON.parse(new TextDecoder().decode(await readFileLimited(lock, 1024)));
+    return Number.isSafeInteger(pid) && pid > 0 && !alive(pid);
+  } catch {
+    return false;
+  }
+}
+
 export async function openStore(review, directory = stateDirectory()) {
   directory = path.resolve(directory);
   if (directory === review.root || within(review.root, directory))
@@ -232,9 +257,29 @@ export async function openStore(review, directory = stateDirectory()) {
   try {
     lockHandle = await open(lock, 'wx', 0o600);
   } catch (error) {
-    throw new Error(
-      `Review writer lock unavailable (${error.code}). Stop the other writer; after a crash inspect and explicitly remove the lock. No lock was stolen.`,
+    const unavailable = new Error(
+      `Review writer lock unavailable (${error.code}). Another SpecTater process owns this review.`,
     );
+    if (error.code !== 'EEXIST' || !(await abandoned(lock))) throw unavailable;
+    // Move the lock aside before judging it, so a concurrent reclaimer's fresh lock is restored.
+    const moved = `${lock}.${randomUUID()}.stale`;
+    try {
+      await rename(lock, moved);
+    } catch {
+      throw unavailable;
+    }
+    if (!(await abandoned(moved))) {
+      // Restore the live lock; if another process took the name meanwhile, keep it aside for inspection.
+      await link(moved, lock);
+      await unlink(moved);
+      throw unavailable;
+    }
+    await unlink(moved);
+    try {
+      lockHandle = await open(lock, 'wx', 0o600);
+    } catch {
+      throw unavailable;
+    }
   }
   try {
     await lockHandle.writeFile(JSON.stringify({ pid: process.pid }));
@@ -300,8 +345,8 @@ export async function openStore(review, directory = stateDirectory()) {
 }
 
 export function feedback(state, batchId) {
-  const batch = state?.batches.find((item) => item.id === batchId);
-  if (!batch) throw new Error('Unknown review or batch. Use the exact submission receipt.');
+  const batch = state?.batches.find((item) => item.id === batchId || item.sequence === batchId);
+  if (!batch) throw new Error(`Unknown feedback batch: ${batchId}.`);
   return { formatVersion: 1, reviewId: state.reviewId, ...batch };
 }
 
@@ -315,6 +360,8 @@ export function feedbackMarkdown(batch) {
     '',
     'Review data only. Submission does not authorize implementation, merge or deployment.',
   ];
+  if (batch.message)
+    lines.push('', '## Message', '', ...batch.message.split(/\r?\n/).map((line) => `> ${line}`));
   for (const entry of batch.entries) {
     lines.push(
       '',

package/web/app.js

@@ -354,11 +354,13 @@ function displayFeedback() {
     ? `Editing batch ${editing.sequence} · delivery paused. Edit saved comments, then update.`
     : '';
   $('submit').textContent = editing ? 'Update queued batch' : 'Submit batch';
-  $('submit').disabled = Boolean(state.endedAt) || !state.pendingCommentIds.length;
+  updateSubmit();
+  $('send-end').hidden = Boolean(state.endedAt || state.endRequestedAt);
+  $('end-pending').hidden = !state.endRequestedAt || Boolean(state.endedAt);
+  $('agent-message').disabled = Boolean(state.endedAt);
   $('review-lifecycle').textContent = state.endedAt ? 'Resume review' : 'End review';
   $('refresh').disabled = Boolean(state.endedAt);
   $('comment-hint').hidden ||= Boolean(state.endedAt);
-  $('submit').hidden = $('submit').disabled;
   $('receipts').replaceChildren();
   const history = element('details', '', 'batch-history');
   const historyCount = state.batches.filter((batch) =>
@@ -368,7 +370,7 @@ function displayFeedback() {
   for (const batch of [...state.batches].reverse()) {
     const receipt = element('div', '', 'receipt');
     receipt.append(
-      button(`Batch ${batch.sequence} · ${batch.count} comments`, () => showBatch(batch.id)),
+      button(`Batch ${batch.sequence} · ${batch.count} items`, () => showBatch(batch.id)),
     );
     const activity = state.activity?.[batch.id];
     const queue = state.queue?.[batch.id];
@@ -452,24 +454,26 @@ async function loadComparison(id) {
   }
 }
 async function operation(fn) {
-  if (busy) return;
+  if (busy) return false;
   busy = true;
   document.body.setAttribute('aria-busy', 'true');
   try {
     await fn();
+    return true;
   } catch (error) {
     announce(error.message, true);
     if ($('comment-popover').matches(':popover-open')) {
       $('composer-error').textContent = error.message;
       $('composer-error').hidden = false;
     }
+    return false;
   } finally {
     busy = false;
     document.body.setAttribute('aria-busy', 'false');
   }
 }
 async function action(input) {
-  await operation(async () => {
+  return operation(async () => {
     acceptState(await api('action', { ...input, revision: state.revision }));
     if (input.action === 'comment' || input.action === 'edit') {
       $('comment').value = '';
@@ -478,6 +482,7 @@ async function action(input) {
       persistDraft();
     }
     if (input.action === 'delete') undoDeletedId = input.id;
+    if (input.action === 'submit') $('agent-message').value = '';
     if (input.action === 'end') closeComposer();
     display();
     announce(
@@ -486,7 +491,11 @@ async function action(input) {
         : input.action === 'resume'
           ? 'Review resumed.'
           : input.action === 'submit'
-            ? 'Batch saved.'
+            ? state.endedAt
+              ? 'Review ended.'
+              : input.end
+                ? 'Batch saved. The review ends once the agent receives it.'
+                : 'Batch saved.'
             : input.action === 'cancel-batch'
               ? 'Submission cancelled. Comments kept.'
               : input.action === 'edit-batch'
@@ -495,14 +504,16 @@ async function action(input) {
                   ? 'Comment deleted.'
                   : 'Saved.',
     );
-    if (input.action === 'submit') await showBatch(state.batches.at(-1).id, false);
+    if (input.action === 'submit' && state.batches.length)
+      await showBatch(state.batches.at(-1).id, false);
   });
 }
 async function showBatch(id, open = true) {
   try {
     $('export').value = (await api(`batch/${id}`)).markdown;
+    const batch = state.batches.find((item) => item.id === id);
     $('retrieval-command').textContent =
-      `spectater feedback --review ${state.reviewId} --batch ${id} --format markdown --history`;
+      `spectater feedback ${state.change} --batch ${batch.sequence} --format markdown`;
     $('export-details').hidden = false;
     $('export-details').open = open;
   } catch (error) {
@@ -599,10 +610,14 @@ document.addEventListener('keyup', (event) => {
   )
     captureSelection();
 });
+function saveComment() {
+  if (editingId) return action({ action: 'edit', id: editingId, body: $('comment').value });
+  if (selection) return action({ action: 'comment', ...selection, body: $('comment').value });
+  return false;
+}
 $('comment-form').addEventListener('submit', (event) => {
   event.preventDefault();
-  if (editingId) action({ action: 'edit', id: editingId, body: $('comment').value });
-  else if (selection) action({ action: 'comment', ...selection, body: $('comment').value });
+  void saveComment();
 });
 $('comment').addEventListener('input', persistDraft);
 $('comment-popover').addEventListener('toggle', updateDraftButton);
@@ -615,7 +630,32 @@ $('review-lifecycle').addEventListener('click', () => {
   if (!state.endedAt) editingId = undefined;
   void action({ action: state.endedAt ? 'resume' : 'end' });
 });
-$('submit').addEventListener('click', () => action({ action: 'submit' }));
+function updateSubmit() {
+  $('submit').disabled =
+    Boolean(state.endedAt) || !(state.pendingCommentIds.length || $('agent-message').value.trim());
+}
+function submit(end = false) {
+  const message = $('agent-message').value.trim();
+  return action({ action: 'submit', ...(message ? { message } : {}), ...(end ? { end } : {}) });
+}
+$('submit').addEventListener('click', () => submit());
+$('send-end').addEventListener('click', () => {
+  if ($('comment').value)
+    return announce('Save or clear the unsaved draft before ending the review.', true);
+  void submit(true);
+});
+$('agent-message').addEventListener('input', updateSubmit);
+$('agent-message').addEventListener('keydown', (event) => {
+  if (event.key !== 'Enter' || event.shiftKey || event.isComposing) return;
+  event.preventDefault();
+  if (!$('submit').disabled) void submit();
+});
+$('comment').addEventListener('keydown', async (event) => {
+  if (event.key !== 'Enter' || event.shiftKey || event.isComposing) return;
+  event.preventDefault();
+  if ($('save').disabled || !(await saveComment())) return;
+  if ((event.metaKey || event.ctrlKey) && !$('submit').disabled) await submit();
+});
 $('refresh').addEventListener('click', () =>
   operation(async () => {
     acceptState(await api('refresh', {}));

package/web/index.html

@@ -98,7 +98,20 @@
         </details>
         <div class="submission">
           <p id="queue-editing" class="note" hidden></p>
-          <button id="submit" type="button" hidden>Submit batch</button>
+          <label for="agent-message">Message to agent</label>
+          <textarea
+            id="agent-message"
+            rows="2"
+            maxlength="10000"
+            placeholder="Optional. Enter sends; Shift+Enter adds a line."
+          ></textarea>
+          <div class="submit-actions">
+            <button id="submit" type="button" disabled>Submit batch</button
+            ><button id="send-end" type="button">Send &amp; End</button>
+          </div>
+          <p id="end-pending" class="note" hidden>
+            Ending after the agent receives the final batch.
+          </p>
           <div id="receipts"></div>
           <button id="review-lifecycle" type="button">End review</button>
           <details id="export-details" hidden>
@@ -135,7 +148,7 @@
           rows="3"
           maxlength="10000"
           required
-          placeholder="Add a comment…"
+          placeholder="Add a comment… Enter saves; Cmd/Ctrl+Enter saves and submits."
         ></textarea>
         <button id="save" type="submit" disabled>Save comment</button>
       </form>

package/web/style.css

@@ -411,6 +411,18 @@ textarea::placeholder {
 .submission {
   margin-top: var(--space-6);
 }
+.submission label {
+  display: block;
+  font-size: var(--text-xs);
+  color: var(--muted);
+  margin-bottom: var(--space-1);
+}
+.submit-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  margin: var(--space-2) 0;
+}
 .receipt {
   margin: var(--space-3) 0;
 }

package/SECURITY.md

@@ -1,11 +0,0 @@
-# Security
-
-SpecTater is a local tool. Verified platforms and limits are documented in README.md.
-
-Do not disclose vulnerabilities, secrets or private artifact content in a public issue. Use GitHub's private vulnerability reporting for this repository when available. Otherwise contact the maintainer privately through the contact information on their GitHub profile before sharing technical details.
-
-The implementation runs locally on loopback and serves only the selected change manifest. A per-process capability authorizes review requests; Host/Origin checks and CSP restrict browser access. Raw HTML remains escaped, external images do not load, and the reader never writes canonical Markdown. These boundaries do not isolate the process from local users who can modify it or its files.
-
-Review snapshots may contain private source. Storage is owner-only outside the repository, remains until explicit removal, and is never uploaded by SpecTater. Keep capability URLs and review-state files private. Do not commit state, browser profiles or exported private feedback. File, request and state size limits fail visibly; no automatic retention cleanup runs.
-
-Contract and browser tests exercise filesystem escape, active Markdown, foreign requests, bounded native reads, queue/lifecycle races and persistence failures. See [the security pass](docs/security-review.md) for the source-review scope and the independent release-review finding. Automated tests do not replace review.