create-pmos 0.4.0 → 0.6.0

package/workspace/lib/console-state.js

@@ -0,0 +1,117 @@
+'use strict';
+/*
+ * Read-only console state readers (D64 / pivot-workspace-first, Track B).
+ *
+ * The workspace console surfaces — the "needs you" queue, a radar-style health summary, and a
+ * metrics view — derive ONLY from local file-mode state: the kit's `pmos/state/*.jsonl` and, as a
+ * seed/demo source when no live state exists yet, the committed hosted snapshot under
+ * `planning/data-export/<date>-hosted-snapshot/*.json`. Live file-mode state is ALWAYS preferred.
+ *
+ * HONESTY BY CONSTRUCTION (the anti-watermelon rule): every reader returns a discriminated result —
+ *   { ok:true,  empty:false, source, data }   data present
+ *   { ok:true,  empty:true,  source }          genuinely nothing (calm empty state on the client)
+ *   { ok:false, error }                        a missing source / parse failure — the client MUST
+ *                                              render this RED, never a green "all clear".
+ * A missing DATA source (no live file AND no snapshot) is an ERROR, not an empty — a health surface
+ * that cannot read its inputs is broken, and a broken honesty surface must read red.
+ */
+const fs = require('fs');
+const path = require('path');
+const reviewGate = require('./review-gate');
+
+function loadJson(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { missing: true }; }
+  try { return { ok: true, data: JSON.parse(text) }; }
+  catch { return { ok: false, error: `${path.basename(file)} is not valid JSON — the file-mode source is corrupt, not empty` }; }
+}
+function loadJsonl(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { missing: true }; }
+  const rows = []; let bad = 0;
+  for (const line of text.split('\n')) {
+    const t = line.trim(); if (!t) continue;
+    try { rows.push(JSON.parse(t)); } catch { bad++; }
+  }
+  // A file that is entirely unparseable is corrupt state — surface it red rather than call it empty.
+  if (bad > 0 && rows.length === 0) return { ok: false, error: `every line in ${path.basename(file)} is malformed — corrupt file-mode state` };
+  return { ok: true, data: rows, bad };
+}
+
+function computeMetricsFromRuns(runs) {
+  const corr = runs.map((r) => Number(r.human_corrections) || 0);
+  const total = corr.reduce((a, b) => a + b, 0);
+  const needing = corr.filter((c) => c > 0).length;
+  const n = runs.length;
+  return {
+    total_runs: n,
+    avg_corrections_per_run: n ? +(total / n).toFixed(3) : 0,
+    runs_needing_correction: needing,
+    share_runs_corrected: n ? +(needing / n).toFixed(3) : 0,
+    per_initiative: [],
+  };
+}
+
+// ── metrics: prefer live pmos/state/runs.jsonl; fall back to the snapshot's metrics.json ──
+function metrics({ stateDir, snapshotDir }) {
+  if (stateDir) {
+    const live = loadJsonl(path.join(stateDir, 'runs.jsonl'));
+    if (live.ok) {
+      if (!live.data.length) return { ok: true, empty: true, source: 'file-mode' };
+      return { ok: true, empty: false, source: 'file-mode', data: computeMetricsFromRuns(live.data) };
+    }
+    if (live.ok === false) return { ok: false, error: live.error };
+    // live.missing → fall through to the snapshot
+  }
+  if (!snapshotDir) return { ok: false, error: 'no metrics source — no live runs.jsonl and no hosted snapshot for this workspace' };
+  const snap = loadJson(path.join(snapshotDir, 'metrics.json'));
+  if (snap.missing) return { ok: false, error: 'metrics source missing — neither live runs.jsonl nor the hosted snapshot is present' };
+  if (!snap.ok) return { ok: false, error: snap.error };
+  const m = snap.data || {};
+  return { ok: true, empty: false, source: 'snapshot', data: {
+    total_runs: m.total_runs, avg_corrections_per_run: m.avg_corrections_per_run,
+    runs_needing_correction: m.runs_needing_correction, share_runs_corrected: m.share_runs_corrected,
+    per_initiative: Array.isArray(m.per_initiative) ? m.per_initiative.slice(0, 12) : [],
+  } };
+}
+
+// ── radar: prefer a live pmos/state/radar.json; fall back to the snapshot's radar_all_sections.json ──
+function radar({ stateDir, snapshotDir }) {
+  let src = null, source = null;
+  if (stateDir) {
+    const live = loadJson(path.join(stateDir, 'radar.json'));
+    if (live.ok) { src = live.data; source = 'file-mode'; }
+    else if (live.ok === false) return { ok: false, error: live.error };
+  }
+  if (!src) {
+    if (!snapshotDir) return { ok: false, error: 'no radar source — no live radar.json and no hosted snapshot for this workspace' };
+    const snap = loadJson(path.join(snapshotDir, 'radar_all_sections.json'));
+    if (snap.missing) return { ok: false, error: 'radar source missing — neither live radar.json nor the hosted snapshot is present' };
+    if (!snap.ok) return { ok: false, error: snap.error };
+    src = snap.data; source = 'snapshot';
+  }
+  const d = src || {};
+  const gates = Array.isArray(d.eval_gates) ? d.eval_gates : [];
+  const passing = gates.filter((g) => reviewGate.isReviewPass(g.verdict, g.score)).length;
+  const wms = (Array.isArray(d.watermelons) ? d.watermelons : []).map((w) => ({
+    id: w.id, title: w.title, rag: w.rag,
+    verdict: w.latest_eval_verdict, score: w.latest_eval_score, corrections: w.avg_human_corrections,
+  }));
+  const calRaw = Array.isArray(d.calibration) ? d.calibration[0] : d.calibration;
+  const calibration = calRaw ? {
+    n: calRaw.n, kappa: calRaw.kappa, tnr: calRaw.tnr, status: calRaw.status,
+    meets_d40: !!calRaw.meets_d40_kappa, caveat: calRaw.leakage_caveat || null,
+  } : null;
+  const okr = (Array.isArray(d.okr_pulse) ? d.okr_pulse : []).slice(0, 8).map((o) => ({
+    objective: o.objective, kr: o.kr, progress: o.progress_pct, pulse: o.pulse,
+  }));
+  return { ok: true, empty: false, source, data: {
+    // watermelon flags = anything not green (amber/red) leads; the whole point is to surface drift
+    watermelons: wms,
+    flags: wms.filter((w) => w.rag && String(w.rag).toLowerCase() !== 'green').length,
+    eval_gate: { total: gates.length, passing, pass_rate: gates.length ? +(passing / gates.length).toFixed(3) : null },
+    calibration, okr_pulse: okr,
+  } };
+}
+
+module.exports = { metrics, radar, computeMetricsFromRuns, loadJson, loadJsonl };

package/workspace/lib/file-mode-parse.js

@@ -0,0 +1,58 @@
+'use strict';
+/*
+ * Canonical file-mode state parsers (D64 / pivot-workspace-first, Track D1).
+ *
+ * The workspace server (server.js) and the kit's metrics.py both read the SAME file-mode records —
+ * acceptances.jsonl, evals.jsonl, runs.jsonl, and the leading frontmatter of initiative markdown —
+ * and MUST agree on what a repo declared. Before D64 each had its own inline copy of these parsers,
+ * so they were free to drift. server.js now delegates to this module; metrics.py mirrors it in
+ * Python; kit/fixtures/test_parsers.py runs both against kit/fixtures/** and fails CI on disagreement.
+ */
+const fs = require('fs');
+const reviewGate = require('./review-gate');
+
+// The LEADING YAML-ish frontmatter block ONLY — body text must never be able to fake a declaration.
+// Mirrors metrics.py exactly: `key: value` lines (first value wins), `---` fences and blank lines are
+// skipped, and the FIRST non-frontmatter, non-fence, non-blank line ends the block.
+function parseLeadingFrontmatter(text) {
+  const fm = {};
+  for (const line of String(text == null ? '' : text).split('\n')) {
+    const m = line.match(/^([a-z_]+):\s*(.+?)\s*$/);
+    if (m) { if (!(m[1] in fm)) fm[m[1]] = m[2]; continue; }
+    if (line.trim() && !line.startsWith('---')) break;
+  }
+  return fm;
+}
+function leadingFrontmatter(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return {}; }
+  return parseLeadingFrontmatter(text);
+}
+
+// One JSON object per line; blank lines skipped, torn lines tolerated (dropped), never guessed.
+function readJsonlRows(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); } catch { /* torn line — skipped, mirrors metrics.py */ }
+  }
+  return out;
+}
+
+// The kit's north-star / throughput field: an acceptance counts only when accepted === true.
+function isAccepted(row) { return !!row && row.accepted === true; }
+
+// A declared outcome is DUE when it has an id + outcome_metric and its horizon is past today. A
+// MISSING horizon counts as due (horizon-gaming-by-omission) — identical to metrics.py.
+function outcomeDue(fm, today) {
+  if (!fm || !fm.id || !fm.outcome_metric) return false;
+  return String(fm.outcome_horizon || '0000-00-00') < String(today);
+}
+
+module.exports = {
+  parseLeadingFrontmatter, leadingFrontmatter, readJsonlRows, isAccepted, outcomeDue,
+  isReviewPass: reviewGate.isReviewPass,
+};

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 };