create-pmos 0.5.0 → 0.6.0

package/workspace/lib/harness-parse.js

@@ -0,0 +1,222 @@
+'use strict';
+/**
+ * harness-parse — the five scrollback-derived signals for the harness tower.
+ * PRD: planning/prd/workspace-harness-tower-prd.md (R3). Rubric dimension 1 is a VETO.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────
+ * VENDOR COUPLING — READ THIS BEFORE CHANGING ANYTHING HERE.
+ *
+ * Owner: the PM (wawan). There is no upstream contract behind any of this.
+ *
+ * Every signal below is derived by reading the raw bytes ONE VENDOR'S CLI (Claude Code)
+ * happened to print into a PTY. Claude Code renders its TUI in place with cursor motion; we
+ * are reading a byte ring, not a screen. The markers we anchor on (`⏺` for a block, `⎿` for
+ * tool output) are that CLI's presentation, not an API. When Anthropic restyles the terminal
+ * UI, these parsers degrade — and because the PM ratified FIVE of them over the recommended
+ * one (pm-decisions.md, 2026-07-25), a single restyle can degrade five surfaces at once.
+ *
+ * What to check when output looks wrong:
+ *   1. Do `⏺` / `⎿` still prefix blocks and tool results? (BLOCK / RESULT below)
+ *   2. Are tool calls still `Name(args)` and MCP still `server - tool (MCP)`? (TOOL_CALL / MCP_CALL)
+ *   3. Does the CLI still print a context percentage at all? (CONTEXT_PCT)
+ * If (1) breaks, everything here returns its failure state — which is the correct behaviour,
+ * not a bug to paper over.
+ *
+ * THE RULE THAT MAKES THIS SAFE TO SHIP: every signal has a FAILURE STATE that the UI draws.
+ * A parser that cannot read must say so. It must never return an empty string, a zero, or a
+ * plausible-looking value — a monitoring surface that guesses is worse than one that is absent.
+ * `missing[signal]` carries the reason, and the client renders it verbatim.
+ *
+ * REVERSAL CONDITION (pre-agreed, pm-decisions.md): if two or more of these break in one CLI
+ * update, or any one is found rendering a value where it should have rendered a failure, scope
+ * reverts to parser 1 alone and the rest are deleted.
+ *
+ * INPUT MUST ALREADY BE SCRUBBED. Callers pass text through server.js's `scrub()` first —
+ * ANSI stripped and secrets redacted (D08). Scrollback holds whatever the agent printed, so a
+ * verbatim "last words" line could otherwise put a token on screen.
+ * ─────────────────────────────────────────────────────────────────────────────────────────
+ */
+
+// Claude Code's block markers. Everything in this file anchors on these two glyphs.
+const BLOCK = /^\s*⏺\s+(.+)$/;              // an assistant block: prose OR a tool call
+const RESULT = /^\s*⎿/;                      // tool output under a call
+const TOOL_CALL = /^([A-Z][A-Za-z0-9_]*)\(/; // Read(…), Bash(…), Write(…)
+const MCP_CALL = /^(\S+)\s+-\s+(\S+)/;       // pmos - save_spec (MCP)
+const CONTEXT_PCT = /context[^\n%]{0,24}?(\d{1,3})\s*%|(\d{1,3})\s*%\s+context/i;
+const MODEL = /\bclaude-(?:opus|sonnet|haiku|fable)[\w.-]*/i;
+const EFFORT = /\beffort[:\s]+(low|medium|high|xhigh|max)\b/i;
+
+// Only the tail is parsed. The ring holds 200 KB; re-reading all of it for every session on
+// every broadcast is waste. The consequence is stated honestly in the UI: tool counts are
+// "recent", not "for the whole run", because a ring cannot promise the whole run anyway.
+const TAIL_BYTES = 32_768;
+
+const NOT_CLAUDE = 'only claude sessions are parsed';
+const UNREADABLE = "can't read its output — no recognisable Claude Code blocks";
+
+/** Split the scrubbed tail into lines, dropping a partial first line. */
+function tailLines(scrubbed) {
+  const tail = scrubbed.length > TAIL_BYTES ? scrubbed.slice(scrubbed.length - TAIL_BYTES) : scrubbed;
+  const lines = tail.split(/\r?\n/);
+  if (scrubbed.length > TAIL_BYTES) lines.shift();   // first line is mid-sentence; never quote it
+  return lines;
+}
+
+/** Is this block line a tool call rather than prose? */
+function isToolCall(body) {
+  return TOOL_CALL.test(body) || /\(MCP\)/.test(body);
+}
+
+/** Name a tool call for counting. Returns null when the body is prose. */
+function toolName(body) {
+  const direct = body.match(TOOL_CALL);
+  if (direct) return direct[1];
+  if (/\(MCP\)/.test(body)) {
+    const mcp = body.match(MCP_CALL);
+    if (mcp) return `${mcp[1]}/${mcp[2]}`;
+    return 'mcp';
+  }
+  return null;
+}
+
+/**
+ * Parser 1 — the agent's own last words, verbatim.
+ * No paraphrase: a summary would be another model call per session, and a paraphrase that
+ * drifts from what the agent actually said is the defect the leg-A grilling caught.
+ */
+function lastWords(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const m = lines[i].match(BLOCK);
+    if (!m || isToolCall(m[1])) continue;
+    const parts = [m[1].trim()];
+    // prose wraps onto indented continuation lines; stop at the next marker or a blank line
+    for (let j = i + 1; j < lines.length; j++) {
+      const nxt = lines[j];
+      if (!nxt.trim() || BLOCK.test(nxt) || RESULT.test(nxt) || /^\s*[❯>]\s/.test(nxt)) break;
+      if (!/^\s{1,6}\S/.test(nxt)) break;
+      parts.push(nxt.trim());
+    }
+    const text = parts.join(' ').replace(/\s+/g, ' ').trim();
+    if (text) return text;
+  }
+  return null;
+}
+
+/** Parser 3 — tool counts across the retained tail. */
+function toolCounts(lines) {
+  const counts = {};
+  let total = 0;
+  for (const line of lines) {
+    const m = line.match(BLOCK);
+    if (!m) continue;
+    const name = toolName(m[1]);
+    if (!name) continue;
+    counts[name] = (counts[name] || 0) + 1;
+    total++;
+  }
+  return total ? { counts, total } : null;
+}
+
+/** Parser 4 — model + effort, only if the CLI printed them. Never guessed. */
+function modelInfo(text) {
+  const m = text.match(MODEL);
+  if (!m) return null;
+  const e = text.match(EFFORT);
+  return { model: m[0], effort: e ? e[1].toLowerCase() : null };
+}
+
+/**
+ * Parser 5 — context utilisation.
+ * Reported ONLY as a percentage the CLI itself printed. We never compute one: the window size
+ * is not in the scrollback, and a percentage of an unknown denominator is not a quantity
+ * (PRD R3). If the CLI never printed one, this signal is absent — which is the common case.
+ */
+function contextPct(text) {
+  const m = text.match(CONTEXT_PCT);
+  if (!m) return null;
+  const raw = Number(m[1] != null ? m[1] : m[2]);
+  if (!Number.isFinite(raw) || raw < 0 || raw > 100) return null;
+  return { pct: raw, source: 'printed by the CLI' };
+}
+
+/**
+ * Parse the four scrollback signals for one session.
+ * Parser 2 (quiet timing) is NOT here — it is a server-side timestamp (`lastOutputAt`), not a
+ * parse, which is why it is the only one of the five that cannot lie about what it read.
+ *
+ * @param {string} scrubbed  buffer already through scrub() — ANSI stripped, secrets redacted
+ * @param {string} agent     'claude' | 'codex' | 'shell'
+ * @returns {{lastWords:string|null, tools:object|null, model:object|null, context:object|null,
+ *            missing:Record<string,string>}}
+ */
+function parseHarness(scrubbed, agent) {
+  const out = { lastWords: null, tools: null, model: null, context: null, missing: {} };
+
+  if (agent !== 'claude') {
+    out.missing.lastWords = `can't read its last words — ${NOT_CLAUDE}`;
+    out.missing.tools = NOT_CLAUDE;
+    out.missing.model = NOT_CLAUDE;
+    out.missing.context = NOT_CLAUDE;
+    return out;
+  }
+
+  const text = String(scrubbed || '');
+  const lines = tailLines(text);
+  const anyBlock = lines.some((l) => BLOCK.test(l));
+
+  if (!anyBlock) {
+    // The single most important branch in this file: nothing recognisable was found, so every
+    // signal says so. This is what the forced-failure test exercises.
+    out.missing.lastWords = UNREADABLE;
+    out.missing.tools = 'no recognisable tool calls in the retained scrollback';
+    out.missing.model = 'the CLI has not printed a model name';
+    out.missing.context = 'the CLI has not printed a context percentage';
+    return out;
+  }
+
+  out.lastWords = lastWords(lines);
+  if (!out.lastWords) out.missing.lastWords = "can't read its last words — no prose block yet";
+
+  out.tools = toolCounts(lines);
+  if (!out.tools) out.missing.tools = 'no tool calls in the retained scrollback';
+
+  const tailText = lines.join('\n');
+  out.model = modelInfo(tailText);
+  if (!out.model) out.missing.model = 'the CLI has not printed a model name';
+
+  out.context = contextPct(tailText);
+  if (!out.context) out.missing.context = 'the CLI has not printed a context percentage';
+
+  return out;
+}
+
+/**
+ * Parser 2 — quiet timing, derived from a timestamp rather than a parse.
+ * `quiet` means EXACTLY "no bytes for >= QUIET_AFTER_MS". It does NOT mean "waiting on you":
+ * quiescence proves quiet, not waiting (PRD R1). The word in the UI must stay "quiet".
+ *
+ * `failed` deliberately does not exist. The server knows only working|exited; deriving failure
+ * by grepping scrollback for "error" would install a watermelon generator in the product whose
+ * thesis is anti-watermelon.
+ */
+function deriveState(state, lastOutputAt, now) {
+  if (state === 'exited') return { state: 'exited', quietMs: null };
+  if (!lastOutputAt) return { state: 'working', quietMs: null };   // no timestamp ⇒ no claim
+  const quietMs = Math.max(0, now - lastOutputAt);
+  return quietMs >= module.exports.QUIET_AFTER_MS
+    ? { state: 'quiet', quietMs }
+    : { state: 'working', quietMs };
+}
+
+module.exports = {
+  parseHarness,
+  deriveState,
+  // Provisional, and knowingly so. It must exceed the longest gap a WORKING claude session can
+  // go without emitting a byte; the spinner redraws continuously, so real gaps are sub-second.
+  // 30s is a deliberate over-estimate: a false "quiet" is the failure that matters, because the
+  // whole feature exists to stop the PM mistaking blocked for busy. Needs one field measurement
+  // (the byte rate of a working session) to tighten — carried as an open question in the PRD.
+  QUIET_AFTER_MS: 30_000,
+  TAIL_BYTES,
+  _internal: { lastWords, toolCounts, modelInfo, contextPct, tailLines, isToolCall, toolName },
+};

package/workspace/lib/preview-kind.js

@@ -0,0 +1,98 @@
+/* preview-kind — the SINGLE classifier the reader trusts (workspace-reader-preview).
+ *
+ * One source of truth for "what can the reader do with this file", used on BOTH sides:
+ *   - server.js requires it (readTextDoc allowlist, /api/asset MIME, tree() kind flag)
+ *   - the browser loads it as /lib/preview-kind.js before app.js (window.PreviewKind)
+ * so the tree flag, the read endpoints, and the renderer can never disagree (R1/R2/R8).
+ *
+ * The one security-critical function is isRepoRelativeSrc(): it decides whether a markdown
+ * image renders inline (repo-relative, served through the guarded /api/asset) or stays
+ * downgraded to alt-text (remote / data: / any scheme). That single boolean is the
+ * no-remote-image-beacon invariant (R4) — a poisoned `![](https://evil/beacon)` must never
+ * cause a fetch on view. It is pure, so it is unit-tested directly.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PreviewKind = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+  // Textual formats that ARE markdown — rendered through the markdown pipeline. `.skill` is
+  // markdown + YAML frontmatter, so it renders like any concept doc (R1).
+  const MARKDOWN_EXT = new Set(['md', 'markdown', 'mdown', 'mkd', 'mdx', 'skill']);
+
+  // Textual formats shown as ESCAPED source (never executed, R2). Broad on purpose — every entry
+  // is escaped text, so breadth adds no risk (PRD open-question resolved: broad allowlist).
+  const TEXT_EXT = new Set([
+    'txt', 'text', 'log', 'csv', 'tsv', 'json', 'jsonc', 'json5', 'ndjson',
+    'yaml', 'yml', 'toml', 'ini', 'cfg', 'conf', 'config', 'properties', 'env', 'example',
+    'xml', 'rss', 'atom', // NB: .svg is classified 'image' (IMAGE_MIME, checked first) — it renders, not source
+    'sh', 'bash', 'zsh', 'fish', 'ps1', 'bat',
+    'js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx', 'css', 'scss', 'sass', 'less',
+    'sql', 'py', 'rb', 'go', 'rs', 'java', 'kt', 'kts', 'c', 'h', 'cc', 'cpp', 'hpp',
+    'cs', 'php', 'pl', 'pm', 'lua', 'r', 'swift', 'scala', 'clj', 'ex', 'exs', 'erl',
+    'diff', 'patch', 'lock', 'gitignore', 'gitattributes', 'editorconfig', 'npmrc', 'nvmrc',
+    'dockerfile', 'makefile', 'gradle', 'graphql', 'gql', 'proto', 'tf', 'hcl',
+  ]);
+
+  const HTML_EXT = new Set(['html', 'htm']);
+
+  // Raster/vector formats servable through /api/asset as an <img>. Loaded via <img>, SVG scripts
+  // do not execute; /api/asset additionally sends nosniff + a script-blocking CSP for direct hits.
+  const IMAGE_MIME = {
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+    webp: 'image/webp', svg: 'image/svg+xml', avif: 'image/avif', bmp: 'image/bmp',
+    ico: 'image/x-icon', apng: 'image/apng',
+  };
+
+  // Extension-less files that are really text (open as source).
+  const TEXT_BASENAMES = new Set(['dockerfile', 'makefile', 'license', 'licence', 'authors',
+    'notice', 'copying', 'changelog', 'procfile', 'brewfile', 'gemfile', 'rakefile', 'vagrantfile']);
+
+  /** lowercase extension without the dot; '' when there is none. Dotfiles (.gitignore) → 'gitignore'. */
+  function extOf(name) {
+    const base = String(name || '').split(/[\\/]/).pop().toLowerCase();
+    if (!base) return '';
+    const dot = base.lastIndexOf('.');
+    if (dot < 0) return '';           // no dot at all
+    if (dot === 0) return base.slice(1); // dotfile: whole thing after the leading dot
+    return base.slice(dot + 1);
+  }
+
+  /** name/path → 'markdown' | 'text' | 'html' | 'image' | 'inert'. */
+  function previewKind(name) {
+    const base = String(name || '').split(/[\\/]/).pop().toLowerCase();
+    const ext = extOf(base);
+    if (MARKDOWN_EXT.has(ext)) return 'markdown';
+    if (HTML_EXT.has(ext)) return 'html';
+    // an image extension wins over its text twin (.svg) only when there is a real extension;
+    // opening an .svg as a DOC still shows source (TEXT_EXT), inline ![]() treats it as an image.
+    if (Object.prototype.hasOwnProperty.call(IMAGE_MIME, ext)) return 'image';
+    if (TEXT_EXT.has(ext)) return 'text';
+    if (!ext && TEXT_BASENAMES.has(base)) return 'text';
+    return 'inert';
+  }
+
+  /** image MIME for /api/asset, or null when the extension is not an allowlisted image. */
+  function imageMime(name) {
+    return IMAGE_MIME[extOf(name)] || null;
+  }
+
+  /** a markdown-body kind served as escaped source (vs. rendered markdown). */
+  function isTextSource(kind) { return kind === 'text'; }
+
+  /** THE no-beacon invariant (R4). true ⇒ inline via the guarded /api/asset; false ⇒ downgrade
+   *  to alt-text and never fetch. Anything with a scheme (http:, https:, data:, blob:, mailto:),
+   *  protocol-relative //host, or a bare #anchor is treated as NON-repo-relative. */
+  function isRepoRelativeSrc(src) {
+    const s = String(src == null ? '' : src).trim();
+    if (!s) return false;
+    if (s.startsWith('#')) return false;          // an in-page anchor is not an image file
+    if (/^\/\//.test(s)) return false;            // protocol-relative → remote
+    if (/^[a-zA-Z][a-zA-Z0-9+.\-]*:/.test(s)) return false; // any URI scheme (http:, data:, blob:, mailto:)
+    return true;                                  // a plain relative / root-relative repo path
+  }
+
+  return { previewKind, imageMime, isTextSource, isRepoRelativeSrc, extOf,
+    MARKDOWN_EXT, TEXT_EXT, HTML_EXT, IMAGE_MIME };
+});

package/workspace/lib/rate-limit.js

@@ -0,0 +1,26 @@
+'use strict';
+/*
+ * A tiny, pure token-bucket rate limiter (D64 / pivot-workspace-first, Track A3).
+ *
+ * The WS control messages that SPAWN shells ({t:'new'}, {t:'respawn'}) and FEED a PTY ({t:'input'})
+ * are the abuse surface if the socket is ever reached by something hostile. A per-connection bucket
+ * bounds that abuse while staying invisible to a human at an interactive terminal: the input bucket
+ * is sized so ordinary typing (and normal pastes) never trip it, and the spawn bucket allows a small
+ * burst then drips.
+ *
+ * Pure + time-injectable so the limiter is unit-testable without sleeping. No I/O, no globals.
+ */
+function createBucket(capacity, refillPerSec, now = Date.now()) {
+  return { capacity, tokens: capacity, refillPerSec, last: now };
+}
+
+// Try to spend `n` tokens. Refills continuously from elapsed wall-time. Returns true if allowed.
+function take(bucket, n = 1, now = Date.now()) {
+  const elapsed = Math.max(0, now - bucket.last) / 1000;
+  bucket.tokens = Math.min(bucket.capacity, bucket.tokens + elapsed * bucket.refillPerSec);
+  bucket.last = now;
+  if (bucket.tokens >= n) { bucket.tokens -= n; return true; }
+  return false;
+}
+
+module.exports = { createBucket, take };

package/workspace/lib/remote-access.js

@@ -0,0 +1,235 @@
+'use strict';
+/*
+ * Remote (tailnet) access — the transport half of workspace-remote-tailnet.
+ *
+ * D62 is the locked security boundary: the workspace server owns real PTYs running the PM's
+ * Claude subscription, so it must NEVER be reachable from a public interface. This module makes
+ * "reach the SAME local server from my phone" possible over a PRIVATE Tailscale tailnet only:
+ *
+ *   1. Bind resolution — default is loopback ONLY (unchanged). With the opt-in remote flag on, the
+ *      server binds loopback PLUS the machine's own tailnet IPv4 (Tailscale CGNAT 100.64.0.0/10)
+ *      and NOTHING else. Any requested bind that is not loopback and not in 100.64.0.0/10 (e.g.
+ *      0.0.0.0, ::, a LAN or public IP) makes resolveBinds REFUSE — the server won't start. There
+ *      is no code path that yields a public bind address.
+ *   2. Token guard — when bound beyond loopback a bearer token is REQUIRED. Every non-loopback peer
+ *      (HTTP request or WS upgrade) must present it; loopback peers stay token-free for local dev.
+ *      Comparison is constant-time. The token is generated if not supplied and printed ONCE at
+ *      startup — never logged thereafter, and request headers are never logged (D08).
+ *
+ * Pure and side-effect-light so the guard logic is unit-testable without a live tailnet peer.
+ */
+const crypto = require('crypto');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+const LOOPBACK = '127.0.0.1';
+
+// Strip an IPv4-mapped IPv6 prefix (::ffff:100.64.0.1) so one matcher handles both stacks.
+function unmap(addr) { return String(addr || '').replace(/^::ffff:/i, ''); }
+
+function parseIPv4(addr) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(unmap(addr));
+  if (!m) return null;
+  const o = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  return o.some((n) => n > 255) ? null : o;
+}
+
+// Loopback = 127.0.0.0/8 (IPv4) or ::1 (IPv6). These peers are token-exempt.
+function isLoopbackAddr(addr) {
+  if (!addr) return false;
+  if (unmap(addr) === '::1') return true;
+  const o = parseIPv4(addr);
+  return !!o && o[0] === 127;
+}
+
+// The Tailscale tailnet lives in the CGNAT block 100.64.0.0/10 → first octet 100, second 64..127.
+// This is the ONLY non-loopback range the server is ever permitted to bind or trust.
+function isTailnetIp(addr) {
+  const o = parseIPv4(addr);
+  return !!o && o[0] === 100 && o[1] >= 64 && o[1] <= 127;
+}
+
+// Discover this machine's own tailnet IPv4. Prefers `tailscale ip -4`; falls back to scanning the
+// network interfaces for a 100.64.0.0/10 address; honours an explicit PMOS_TAILNET_IP override.
+// Injectable deps keep it testable and keep the spawn out of the non-remote (default/test) path.
+function detectTailnetIp({ env = process.env, netInterfaces = os.networkInterfaces, exec = spawnSync } = {}) {
+  const override = (env.PMOS_TAILNET_IP || '').trim();
+  if (override) return isTailnetIp(override) ? override : null;   // an explicit non-tailnet override is a mistake, not a fallback
+  try {
+    const r = exec('tailscale', ['ip', '-4'], { encoding: 'utf8', timeout: 4000 });
+    if (r && r.status === 0 && r.stdout) {
+      const ip = String(r.stdout).trim().split(/\s+/).find((x) => isTailnetIp(x));
+      if (ip) return ip;
+    }
+  } catch { /* tailscale not installed — fall through to the interface scan */ }
+  let ifaces = {};
+  try { ifaces = netInterfaces() || {}; } catch { ifaces = {}; }
+  for (const list of Object.values(ifaces)) {
+    for (const ni of (list || [])) {
+      const fam = ni && ni.family;
+      if ((fam === 'IPv4' || fam === 4) && isTailnetIp(ni.address)) return ni.address;
+    }
+  }
+  return null;
+}
+
+function remoteRequested(env) {
+  return env.PMOS_REMOTE === 'tailnet'
+    || env.PMOS_BIND_TAILNET === '1' || env.PMOS_BIND_TAILNET === 'true' || env.PMOS_BIND_TAILNET === 'yes';
+}
+
+// The one function that decides what the server may bind. Fail-closed: anything that is not
+// loopback or a tailnet address REFUSES (the server exits), so a public bind is unreachable by
+// construction. Returns {remote, binds, token, tailnetIp, generated} or {remote, refused:<msg>}.
+function resolveBinds({ env = process.env, detect = detectTailnetIp } = {}) {
+  if (!remoteRequested(env)) {
+    return { remote: false, binds: [LOOPBACK], token: null, tailnetIp: null, generated: false };
+  }
+  // An explicit bind address, when given, must itself be loopback or tailnet — never public.
+  const requested = (env.PMOS_BIND_ADDR || '').trim();
+  if (requested && !isLoopbackAddr(requested) && !isTailnetIp(requested)) {
+    return { remote: true, refused:
+      `refusing to bind "${requested}": only loopback or a Tailscale tailnet address (100.64.0.0/10) is permitted — never a public/default-route interface (D62).` };
+  }
+  const ip = (requested && isTailnetIp(requested)) ? requested : detect({ env });
+  if (!ip) {
+    return { remote: true, refused:
+      'PMOS_REMOTE=tailnet is set but no Tailscale tailnet address (100.64.0.0/10) was found. Start Tailscale (`tailscale up`) or set PMOS_TAILNET_IP to your tailnet IP. Refusing to bind any non-tailnet interface (D62).' };
+  }
+  if (!isTailnetIp(ip)) {   // belt-and-suspenders: detect must only ever yield a tailnet IP
+    return { remote: true, refused:
+      `refusing to bind "${ip}": not within the tailnet range 100.64.0.0/10 — never a public interface (D62).` };
+  }
+  const supplied = (env.PMOS_TOKEN || '').trim();
+  const token = supplied || crypto.randomBytes(32).toString('base64url');
+  return { remote: true, binds: [LOOPBACK, ip], token, tailnetIp: ip, generated: !supplied };
+}
+
+// ── Token extraction ──────────────────────────────────────────────────────────────────
+// HTTP: Authorization: Bearer <t>. (Node lowercases header names.)
+function extractHttpToken(headers = {}) {
+  const h = headers.authorization || headers.Authorization || '';
+  const m = /^Bearer\s+(.+)$/i.exec(String(h));
+  return m ? m[1].trim() : null;
+}
+// WS upgrade: a browser cannot set headers on a WebSocket, so accept, in order, an Authorization
+// header (non-browser clients), a ?token=/?access_token= query param, or a `bearer,<t>` subprotocol.
+function extractWsToken(req = {}) {
+  const headers = req.headers || {};
+  const fromHeader = extractHttpToken(headers);
+  if (fromHeader) return fromHeader;
+  try {
+    const u = new URL(req.url || '', 'http://localhost');
+    const q = u.searchParams.get('token') || u.searchParams.get('access_token');
+    if (q) return q.trim();
+  } catch { /* malformed URL → no token */ }
+  const proto = headers['sec-websocket-protocol'];
+  if (proto) {
+    const parts = String(proto).split(',').map((s) => s.trim()).filter(Boolean);
+    const i = parts.findIndex((p) => /^bearer$/i.test(p));
+    if (i >= 0 && parts[i + 1]) return parts[i + 1];
+  }
+  return null;
+}
+
+// ── Origin / Host allowlist (D64 / pivot-workspace-first, Track A1) ─────────────────────
+// The threat: the server owns real PTYs and, for loopback peers, is token-EXEMPT. Without an
+// Origin/Host check, any website the PM has open in their browser can open a WebSocket to
+// ws://127.0.0.1:<port> and send {t:'new'}+{t:'input'} to spawn a shell and type into it — a
+// cross-origin-localhost / DNS-rebinding remote-code-execution vector. These predicates close it:
+//   • a same-origin browser fetch/WS (served BY this server) sends an Origin equal to the Host it
+//     arrived on — allowed;
+//   • a cross-site page sends its OWN (foreign) Origin — rejected;
+//   • a DNS-rebinding attack forces a foreign Host header — rejected (the Host hostname must be
+//     loopback/localhost or a tailnet address, never an attacker's domain);
+//   • a native client / curl sends no Origin — allowed here, then still gated by the token guard.
+// Port-agnostic on purpose: the server may listen on any port, so an Origin is compared to the Host
+// it arrived on (true same-origin) rather than to a hard-coded port. Header VALUES are never logged.
+function hostnameOf(authority) {
+  let h = String(authority == null ? '' : authority).trim().toLowerCase();
+  if (!h) return '';
+  const scheme = h.indexOf('://');
+  if (scheme !== -1) h = h.slice(scheme + 3);
+  if (h[0] === '[') { const i = h.indexOf(']'); return i === -1 ? h.slice(1) : h.slice(1, i); }
+  return h.split('/')[0].split(':')[0];
+}
+function authorityOf(value) {
+  let h = String(value == null ? '' : value).trim().toLowerCase();
+  if (!h || h === 'null') return '';
+  const scheme = h.indexOf('://');
+  if (scheme !== -1) h = h.slice(scheme + 3);
+  return h.split('/')[0];   // host[:port]
+}
+function hostnameAllowed(authority, binds) {
+  const h = hostnameOf(authority);
+  if (!h) return false;
+  if (h === 'localhost') return true;
+  if (isLoopbackAddr(h)) return true;
+  for (const b of (binds || [])) if (isTailnetIp(b) && unmap(h) === unmap(b)) return true;
+  return false;
+}
+// The single decision, called from BOTH the HTTP guard and the WS-upgrade guard. Returns true when
+// the request is allowed to proceed (it may still be rejected by the token guard afterwards).
+function checkHostOrigin({ origin, host, binds }) {
+  // 1. If a Host header is present, its hostname must be loopback/localhost/tailnet (anti-rebinding).
+  if (host != null && host !== '') {
+    if (!hostnameAllowed(host, binds)) return false;
+  }
+  // 2. If an Origin header is present, it must be same-origin with the Host it arrived on, and its
+  //    hostname must itself be in the allowlist. "null"/opaque/garbage Origins are rejected.
+  if (origin != null && origin !== '') {
+    const oa = authorityOf(origin);
+    if (!oa) return false;
+    const ha = authorityOf(host);
+    if (ha && oa !== ha) return false;               // cross-origin → reject
+    if (!hostnameAllowed(oa, binds)) return false;   // Host absent but Origin foreign → reject
+  }
+  return true;
+}
+function isAllowedOrigin(origin, { host, binds } = {}) { return checkHostOrigin({ origin, host, binds }); }
+
+// Constant-time token comparison. Length is checked first (timingSafeEqual throws on a length
+// mismatch); a differing length is already a non-match, so this leaks nothing useful.
+function tokenMatches(presented, expected) {
+  if (!expected || !presented) return false;
+  const a = Buffer.from(String(presented));
+  const b = Buffer.from(String(expected));
+  if (a.length !== b.length) return false;
+  try { return crypto.timingSafeEqual(a, b); } catch { return false; }
+}
+
+// The single authorization decision, PEER-based (what matters is where the request came FROM, not
+// which listener it hit). Loopback is always exempt; every non-loopback peer must present a valid
+// bearer token. Fail-closed: with no token configured, a non-loopback peer is rejected.
+function authorize({ remoteAddress, presentedToken, expectedToken }) {
+  if (isLoopbackAddr(remoteAddress)) return true;
+  return tokenMatches(presentedToken, expectedToken);
+}
+
+// The startup banner lines. This is the ONE place a token may be printed, and ONLY a freshly
+// GENERATED token — a token supplied via PMOS_TOKEN is the PM's own secret and is never echoed.
+// Nothing here (or anywhere in this module) logs request headers (D08).
+function startupLines(bind, port) {
+  if (!bind || !bind.remote) {
+    return [`pmos workspace server — http://${LOOPBACK}:${port}  (loopback only, D62)`];
+  }
+  const lines = [
+    'pmos workspace server — REMOTE (tailnet) mode',
+    `  local:   http://${LOOPBACK}:${port}`,
+    `  tailnet: http://${bind.tailnetIp}:${port}   (private WireGuard net, device-authenticated, never public — D62)`,
+  ];
+  if (bind.generated) {
+    lines.push(`  token (generated — shown ONCE, copy it now): ${bind.token}`);
+    lines.push('  attach with header  Authorization: Bearer <token>   or query  ?token=<token>');
+  } else {
+    lines.push('  token: using PMOS_TOKEN from the environment (not shown)');
+  }
+  lines.push('  loopback requests are token-free; every tailnet request must present the token.');
+  return lines;
+}
+
+module.exports = {
+  LOOPBACK, isLoopbackAddr, isTailnetIp, detectTailnetIp, remoteRequested,
+  resolveBinds, extractHttpToken, extractWsToken, tokenMatches, authorize, startupLines,
+  checkHostOrigin, isAllowedOrigin, hostnameAllowed,
+};

package/workspace/lib/review-gate.js

@@ -0,0 +1,39 @@
+'use strict';
+/*
+ * CANONICAL Review-Gate pass rule — the single source of truth (D64 / pivot-workspace-first, Track D2).
+ *
+ * The rule is:  an explicit verdict DECIDES (pass iff it starts with "pass"); the score is a
+ * fallback used ONLY when no verdict was recorded (score >= 0.85).
+ *
+ * AMENDED 2026-07-26 (blind-plant round 2 finding). The rule was previously
+ * `verdict ILIKE 'pass%' OR score >= 0.85`, and that disjunction was a real leniency hole: a run the
+ * evaluator explicitly FAILED still passed the gate if its weighted score happened to clear 0.85.
+ * Round 2 hit it live — specimen `be58` came back verdict=FAIL score=0.93 and the old rule counted it
+ * pass-side, overriding a FAIL issued under the two-axis rule ("a FAIL on either axis cannot become a
+ * PASS"). A gate whose plumbing can overturn its own judge is not a gate. See
+ * planning/evals/blind-plants/2026-07-26-round2/RESULTS.md.
+ *
+ * Note the fix is NOT a blunt OR->AND: that would wrongly fail a legitimate `PASS` verdict carrying no
+ * recorded score. Verdict-authoritative-with-score-fallback preserves every other case and changes
+ * exactly the one that was broken.
+ *
+ * It was previously duplicated verbatim across SQL views, TS, the workspace JS, and metrics.py, so a
+ * change in one place silently drifted the others. It now lives HERE and is mirrored in exactly one
+ * other place — kit/scripts/metrics.py's `review_gate_pass()` — with a comment pointing back here.
+ * kit/fixtures/test_parsers.py runs BOTH implementations against kit/fixtures/review-gate-pass-rule.json
+ * and fails CI if they ever disagree, so the mirror can never drift unnoticed.
+ */
+const PASS_VERDICT_PREFIX = 'pass';   // ILIKE 'pass%' → lowercased startsWith('pass')
+const SCORE_THRESHOLD = 0.85;
+
+// A recorded verdict is AUTHORITATIVE: the run passes iff that verdict starts with "pass"
+// (PASS / PASS-WITH-FINDINGS / …). An explicit FAIL is never overridden by a high score.
+// Only when NO verdict was recorded (null / "" / whitespace) does the numeric score decide.
+function isReviewPass(verdict, score) {
+  const v = String(verdict == null ? '' : verdict).trim().toLowerCase();
+  if (v) return v.startsWith(PASS_VERDICT_PREFIX);
+  const s = Number(score);
+  return Number.isFinite(s) && s >= SCORE_THRESHOLD;
+}
+
+module.exports = { isReviewPass, PASS_VERDICT_PREFIX, SCORE_THRESHOLD };