clearotron 0.3.2-beta.11 → 0.3.2-beta.13

package/scripts/repo-writes.mjs

@@ -119,3 +119,45 @@ export function explainRepoWrites(rows) {
     "  touching the tree to tell the two apart.)",
   ];
 }
+
+// ── the home the run executes as ────────────────────────────────────────────────────────────────────
+//
+// THE SAME RULE, ONE FOLDER OUT. The suite is documented as offline with no side effects, and a fresh
+// clone's run left `~/trademark/telemetry/trademark-mcp-access.jsonl` behind (measured 2026-09-19, one
+// line per run): a test spawned the stdio server with the real home, and `doctor` on that machine then
+// reported the client door's access log as being written. These are the product's own folders under a
+// home: the pool, workspace, queue and telemetry, and the settings, records and revocation list. A run
+// leaves them as it found them. The rest of a home — npm's cache, a browser's profile — belongs to the
+// tools a run uses, and is theirs to write.
+
+/** The product's own folders under a home, relative to it. */
+export const HOME_DATA = Object.freeze(["trademark", join(".config", "clearotron")]);
+
+/** Every path under the home's product folders, stamped. A folder that does not exist is not walked. */
+export function snapshotHome(home) {
+  const out = new Map();
+  for (const rel of HOME_DATA) {
+    const p = join(resolve(home), rel);
+    let isDir = false;
+    try { isDir = lstatSync(p).isDirectory(); } catch { continue; }
+    if (!isDir) { out.set(p, "not-a-directory"); continue; }
+    out.set(p, "dir");
+    for (const [k, v] of snapshotRepo(p)) out.set(k, v);
+  }
+  return out;
+}
+
+/** What a reader is told when a run wrote under the home's product folders. */
+export function explainHomeWrites(rows, home) {
+  return [
+    "",
+    `[test-run] THIS RUN WROTE UNDER THE HOME IT RAN AS (${home}), in the product's own folders:`,
+    ...rows,
+    "",
+    "  A test that starts a product command hands it a HOME under its own temp directory. Without one, the",
+    "  command reads and writes the pool, queue, telemetry and settings of whoever runs the suite.",
+    "",
+    "  (A service of this account writing there while the run was in flight prints this too. Run again",
+    "  with HOME set to an empty temp directory to tell the two apart.)",
+  ];
+}

package/scripts/report-sections-render-check.mjs

@@ -0,0 +1,245 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+// report-sections-render-check.mjs — the report's section strip sits under the Reads and shows how far the
+// reader has got, measured in a real browser.
+//
+//   node scripts/report-sections-render-check.mjs [--shots <dir>] [--keep]
+//
+// THE DEFECT, from the owner on the test instance (2026-09-19): scrolling the report never moved the strip,
+// so "Summary" stayed marked whatever was in view; and with sixteen reads the strip sat BESIDE the Reads, the
+// reads wrapping into two ragged columns while the strip floated at mid-height. His ruling: the strip goes
+// under the Reads on its own full-width row, and it shows PROGRESS. Every section reached so far is marked,
+// none at the top, and scrolling back up un-marks them the same way. A click still jumps.
+//
+// WHAT IS MEASURED: a real renderer's report (the demo's full country search, put through the demo's own
+// publisher and the portal's own embed preparation) inside the real portal build, with twelve reads of one
+// mark. At 1440 and 400 wide, in both themes: the strip's row is under the Reads row; then the page is
+// scrolled so each section's start reaches the bottom of the pinned header, down and back up, and the
+// number of filled entries must equal the number of sections reached. Where each section starts is read
+// from INSIDE the frame, independently of what the document reports to the portal. Last, one entry is
+// pressed and the page must jump to that section and mark it.
+import { spawn, spawnSync } from 'node:child_process'
+import { createServer } from 'node:http'
+import { readFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { join, dirname, extname, normalize } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { reapOnExit } from '../shared/reap-on-exit.mjs'
+import { browserRun } from '../shared/browser-temp-root.mjs'
+import { prepareReportForEmbed } from '../driver/portal-report.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(HERE, '..')
+const DIST = join(ROOT, 'portal-ui', 'dist')
+const keep = process.argv.includes('--keep')
+const argValue = (flag) => (process.argv.includes(flag) ? process.argv[process.argv.indexOf(flag) + 1] : null)
+const shotsDir = argValue('--shots')
+if (!existsSync(join(DIST, 'index.html'))) { console.error(`no build at ${DIST} — run: npm run build:ui`); process.exit(2) }
+if (shotsDir) mkdirSync(shotsDir, { recursive: true })
+
+// ── A REAL REPORT ───────────────────────────────────────────────────────────────────────────────────────
+const pool = mkdtempSync(join(tmpdir(), 'sections-check-'))
+const published = spawnSync(process.execPath, [join(ROOT, 'bin', 'example.mjs'), '--once', '--pool', pool, '--product', 'full-country-search'], { encoding: 'utf8' })
+if (published.status !== 0) { console.error(`the demo publisher failed:\n${published.stderr || published.stdout}`); process.exit(2) }
+const runDir = readdirSync(pool).map((d) => join(pool, d)).find((d) => existsSync(join(d, 'report.html')))
+if (!runDir) { console.error(`the demo publisher wrote no report under ${pool}`); process.exit(2) }
+const prepared = prepareReportForEmbed(readFileSync(join(runDir, 'report.html'), 'utf8'), {})
+const SECTIONS = prepared.sections.map((s) => s.id)
+if (SECTIONS.length < 4) { console.error(`the report announces ${SECTIONS.length} sections; this check needs a long one`); process.exit(2) }
+
+// ── TWELVE READS OF ONE MARK ────────────────────────────────────────────────────────────────────────────
+const KEY = 'acme'
+const MARK = 'VENQORI'
+const PRODUCTS = [['full-country-search', 'Full country search'], ['knockout-search', 'Knockout search'],
+  ['multi-country-focus-search', 'Multi-country focus search'], ['global-preliminary-search', 'Global preliminary search']]
+const RUNS = Array.from({ length: 12 }, (_, i) => {
+  const [product, productName] = PRODUCTS[i % PRODUCTS.length]
+  const day = String(18 - i).padStart(2, '0')
+  return {
+    account: KEY, kind: 'clearance', state: 'delivered', band: 'Moderate', tone: 'medium', bands: [], marks: [],
+    reportSchema: 2, held: false, report: `/portal/report/tmpa-read-${i + 1}/`, step: null, stepN: null, stepTotal: null,
+    reason: null, failedStage: null, pausedKind: null, resetsAt: null, startedAt: null, queuePos: null,
+    projectKey: null, projectName: null, markName: MARK, title: MARK, date: `2026-09-${day}`,
+    issuedAt: `2026-09-${day}T12:00:00.000Z`, product, productName, runId: `tmpa-read-${i + 1}`,
+  }
+})
+const RUN_ID = RUNS[0].runId
+
+const MIME = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.svg': 'image/svg+xml', '.json': 'application/json', '.png': 'image/png', '.woff2': 'font/woff2' }
+const json = (res, body) => { res.writeHead(200, { 'content-type': 'application/json' }); res.end(JSON.stringify(body)) }
+const file = (res, full) => {
+  if (!existsSync(full)) { res.writeHead(404); res.end('no'); return }
+  res.writeHead(200, { 'content-type': MIME[extname(full)] ?? 'application/octet-stream' })
+  res.end(readFileSync(full))
+}
+const server = createServer((req, res) => {
+  const p = decodeURIComponent(new URL(req.url, 'http://localhost').pathname)
+  if (p === '/portal/api/me') return json(res, { email: 'reader@example-firm.com', permissions: { run: true, manage: false }, access: [{ kind: 'account', account: KEY }], accounts: [KEY], accountNames: { [KEY]: 'Acme' } })
+  if (p === '/portal/admin/roster') return json(res, { customers: [{ key: KEY, name: 'Acme' }] })
+  if (p === '/portal/admin/families') return json(res, { of: {}, names: {} })
+  if (p === '/portal/api/runs') return json(res, { runs: RUNS })
+  if (p === '/portal/api/searches') return json(res, { account: KEY, products: [], recipes: [], read: { available: false, maxBrief: 0, note: null } })
+  if (p === '/portal/api/mcp-access') return json(res, { url: null, keyUrl: null, email: 'reader@example-firm.com', enabled: false, stdio: null, aiConnected: null, offers: [] })
+  if (/^\/portal\/api\/run\/[^/]+\/summary$/.test(p)) return json(res, { summary: [] })
+  // Every read serves the one real document; its own resources resolve against the run directory and the
+  // pool, as they do from a real pool.
+  const inReport = /^\/portal\/report\/[^/]+\/(.*)$/.exec(p)
+  if (inReport) {
+    if (!inReport[1]) { res.writeHead(200, { 'content-type': 'text/html' }); return res.end(prepared.html) }
+    return file(res, join(runDir, normalize(inReport[1]).replace(/^(\.\.[/\\])+/, '')))
+  }
+  if (p.startsWith('/portal/report/')) return file(res, join(pool, normalize(p.slice('/portal/report/'.length)).replace(/^(\.\.[/\\])+/, '')))
+  const base = p.split('?')[0]
+  return file(res, join(DIST, base === '/' || (base.startsWith('/portal') && !base.includes('.')) ? '/index.html' : base.replace(/^\/portal/, '')))
+})
+await new Promise((r) => server.listen(0, '127.0.0.1', r))
+const origin = `http://127.0.0.1:${server.address().port}`
+
+// ── THE BROWSER ────────────────────────────────────────────────────────────────────────────────────────
+const { profile, env: chromeEnv, keep: keepRoot } = browserRun('report-sections-check-')
+if (keep) keepRoot()
+const chrome = spawn('google-chrome', [
+  '--headless=new', '--disable-gpu', '--no-sandbox', '--hide-scrollbars',
+  '--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1',
+  `--user-data-dir=${profile}`, '--window-size=1440,900', '--remote-debugging-port=0', 'about:blank',
+], { stdio: ['ignore', 'ignore', 'pipe'], detached: true, env: chromeEnv })
+reapOnExit(chrome)
+const wsUrl = await new Promise((resolve, reject) => {
+  let devtools = ''
+  const t = setTimeout(() => reject(new Error(`chrome reported no devtools endpoint in 60s:\n${devtools || '(nothing)'}`)), 60000)
+  chrome.stderr.on('data', (c) => { devtools += c; const m = devtools.match(/ws:\/\/[^\s]+/); if (m) { clearTimeout(t); resolve(m[0]) } })
+})
+const ws = new WebSocket(wsUrl)
+let id = 0
+const pending = new Map()
+// The report's frame is sandboxed to an opaque origin, so Chrome runs it as a process of its own and it
+// is not in the page's frame tree. It is attached to as its own target; the newest one is the document on
+// screen.
+let frameSession = null
+ws.addEventListener('message', (e) => {
+  const m = JSON.parse(e.data)
+  if (m.method === 'Target.attachedToTarget' && m.params?.targetInfo?.type === 'iframe') frameSession = m.params.sessionId
+  if (m.id && pending.has(m.id)) { pending.get(m.id)(m); pending.delete(m.id) }
+})
+await new Promise((r) => ws.addEventListener('open', r))
+const send = (method, params = {}) => new Promise((r) => { const i = ++id; pending.set(i, r); ws.send(JSON.stringify({ id: i, method, params })) })
+const { result: targets } = await send('Target.getTargets')
+const page = targets.targetInfos.find((t) => t.type === 'page')
+const { result: sess } = await send('Target.attachToTarget', { targetId: page.targetId, flatten: true })
+const sessionId = sess.sessionId
+const cmd = (method, params) => new Promise((r) => { const i = ++id; pending.set(i, r); ws.send(JSON.stringify({ id: i, sessionId, method, params })) })
+const value = async (expr) => (await cmd('Runtime.evaluate', { expression: expr, awaitPromise: true, returnByValue: true })).result?.result?.value ?? null
+const wait = (ms) => new Promise((r) => setTimeout(r, ms))
+const until = async (expr, ms = 15000) => { const end = Date.now() + ms; while (Date.now() < end) { if (await value(expr)) return true; await wait(100) } return false }
+await cmd('Page.enable')
+await cmd('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true })
+
+// Where each section starts, read inside the frame's own document — not the list it posted to the portal.
+const anchorsInFrame = async () => {
+  if (!frameSession) return null
+  const answer = await new Promise((r) => { const i = ++id; pending.set(i, r); ws.send(JSON.stringify({ id: i, sessionId: frameSession, method: 'Runtime.evaluate',
+    params: { expression: `${JSON.stringify(SECTIONS)}.map((id) => { const el = document.getElementById(id); return el ? Math.round(el.getBoundingClientRect().top + window.scrollY) : null })`, returnByValue: true } })) })
+  return answer.result?.result?.value ?? null
+}
+const strip = () => value(`[...document.querySelectorAll('nav.report-sections .report-section')].map((b) => (b.dataset.reached === 'true' ? 'y' : 'x') + (b.getAttribute('aria-current') === 'true' ? '*' : '')).join(' ')`)
+const filled = (s) => (s ?? '').split(' ').filter((e) => e.startsWith('y')).length
+const current = (s) => (s ?? '').split(' ').findIndex((e) => e.endsWith('*'))
+// Put a document offset at the reading line — the pinned header's bottom, plus the margin a jump lands at.
+const scrollToDocY = async (docY) => {
+  for (let i = 0; i < 6; i++) {
+    const delta = await value(`(() => { const f = document.querySelector('iframe'); const h = document.querySelector('.report-head');
+      const d = f.getBoundingClientRect().top + ${docY} - (h.getBoundingClientRect().bottom + 10);
+      window.scrollTo(0, window.scrollY + d); return d })()`)
+    await wait(250)
+    if (Math.abs(delta ?? 0) < 1) break
+  }
+}
+const atFoot = () => value(`window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2`)
+const atTop = () => value(`window.scrollY <= 0`)
+const shot = async (name) => {
+  if (!shotsDir) return
+  await wait(250)
+  const { result } = await cmd('Page.captureScreenshot', { format: 'png' })
+  writeFileSync(join(shotsDir, name), Buffer.from(result.data, 'base64'))
+}
+
+const fail = []
+const ok = []
+for (const width of [1440, 400]) {
+  await cmd('Emulation.setDeviceMetricsOverride', { width, height: 900, deviceScaleFactor: 1, mobile: width < 600 })
+  for (const theme of ['light', 'dark']) {
+    const at = `${width} ${theme}`
+    await cmd('Page.navigate', { url: `${origin}/portal/` })
+    await value(`(() => { try { localStorage.setItem('cordillera-theme', '${theme}') } catch (e) {} return 1 })()`)
+    await cmd('Page.navigate', { url: `${origin}/portal/result/${RUN_ID}` })
+    if (!(await until(`document.querySelectorAll('nav.report-sections .report-section').length === ${SECTIONS.length} && document.querySelectorAll('.report-nav .pill').length === ${RUNS.length}`))) {
+      fail.push(`${at}: the header never showed ${RUNS.length} reads and ${SECTIONS.length} sections`)
+      continue
+    }
+    await wait(800)
+
+    // THE PLACEMENT: the strip's row is under the Reads row and starts where it starts.
+    const box = await value(`(() => { const r = document.querySelector('.report-nav > div').getBoundingClientRect(); const s = document.querySelector('nav.report-sections').getBoundingClientRect();
+      return { readsBottom: r.bottom, readsLeft: r.left, stripTop: s.top, stripLeft: s.left, stripRight: s.right, navRight: document.querySelector('.report-nav').getBoundingClientRect().right } })()`)
+    if (!box) fail.push(`${at}: the Reads row or the strip is missing`)
+    else if (box.stripTop < box.readsBottom - 1) fail.push(`${at}: the strip (top ${box.stripTop}) is beside the Reads (bottom ${box.readsBottom}), not under them`)
+    else if (Math.abs(box.stripLeft - box.readsLeft) > 1) fail.push(`${at}: the strip starts at ${box.stripLeft}, not where the Reads start (${box.readsLeft})`)
+    else if (Math.abs(box.stripRight - box.navRight) > 1) fail.push(`${at}: the strip's row is not the header's full width`)
+    else ok.push(`${at}: the strip is its own full-width row under the ${RUNS.length} reads`)
+    await value('window.scrollTo(0, 0)')
+    await wait(300)
+    await shot(`sections-${width}-${theme}-top.png`)
+
+    // THE PROGRESS, down and back up. Nothing at the top; one more filled at each section's start.
+    const anchors = await anchorsInFrame()
+    if (!anchors || anchors.some((a) => a === null)) { fail.push(`${at}: could not read where the sections start inside the frame`); continue }
+    const seen = []
+    const expectAt = async (label, want, wantCurrent) => {
+      const s = await strip()
+      seen.push(`${label}=${s}`)
+      if (filled(s) !== want || (wantCurrent !== undefined && current(s) !== wantCurrent)) fail.push(`${at}: at ${label} the strip reads "${s}", expected ${want} filled`)
+    }
+    await expectAt('top', 0, -1)
+    // One step into the document, the first section is reached.
+    await value('window.scrollTo(0, 40)')
+    await wait(300)
+    await expectAt('40px down', 1, 0)
+    const order = [...SECTIONS.keys(), ...[...SECTIONS.keys()].reverse().slice(1)]
+    for (const i of order) {
+      await scrollToDocY(anchors[i])
+      // The first section starts under the header, so reaching its start is the top of the page, where
+      // the owner's rule is that nothing is marked yet.
+      const [top, foot] = [await atTop(), await atFoot()]
+      await expectAt(SECTIONS[i], top ? 0 : foot ? SECTIONS.length : i + 1, top ? -1 : foot ? SECTIONS.length - 1 : i)
+      if (i === 1 && width === 1440) await shot(`sections-${width}-${theme}-two-reached.png`)
+    }
+    // Between two starts, the count is the one behind.
+    await scrollToDocY(Math.round((anchors[1] + anchors[2]) / 2))
+    await expectAt(`between ${SECTIONS[1]} and ${SECTIONS[2]}`, 2, 1)
+    await value('window.scrollTo(0, 0)')
+    await wait(300)
+    await expectAt('top again', 0, -1)
+    if (!fail.some((f) => f.startsWith(at))) ok.push(`${at}: progress followed the scroll both ways — ${seen.join(', ')}`)
+
+    // A CLICK STILL JUMPS, and the section jumped to counts as reached.
+    const target = 2
+    const before = await value('window.scrollY')
+    await value(`document.querySelectorAll('nav.report-sections .report-section')[${target}].click()`)
+    let settled = before, last = -1
+    for (let i = 0; i < 40 && settled !== last; i++) { last = settled; await wait(150); settled = await value('window.scrollY') }
+    const s = await strip()
+    const foot = await atFoot()
+    if (!(settled > before)) fail.push(`${at}: pressing "${SECTIONS[target]}" did not move the page`)
+    else if (filled(s) !== (foot ? SECTIONS.length : target + 1)) fail.push(`${at}: after the jump to "${SECTIONS[target]}" the strip reads "${s}"`)
+    else ok.push(`${at}: a press jumps to "${SECTIONS[target]}" and marks it — ${s}`)
+  }
+}
+
+for (const line of ok) console.log(`  ok   ${line}`)
+for (const line of fail) console.log(`  FAIL ${line}`)
+try { ws.close() } catch { /* going anyway */ }
+try { process.kill(-chrome.pid, 'SIGKILL') } catch { /* already gone */ }
+server.close()
+if (!keep) rmSync(pool, { recursive: true, force: true })
+console.log(fail.length ? `\nreport-sections-render-check: ${fail.length} measurement(s) failed.` : `\nreport-sections-render-check: the strip sits under the reads and follows the reader, both ways, at both widths and both themes.`)
+process.exit(fail.length ? 1 : 0)

package/scripts/report-theme-render-check.mjs

@@ -16,6 +16,12 @@
 // switch is pressed, never an attribute set by hand, and three things must hold on each press: the
 // document took the theme, its background went the right way, and the load id did not change — the page
 // repainted in place rather than reloading.
+//
+// AND ONE SECTION MENU, AT BOTH THEMES. The portal draws the report's section menu in its own header and
+// the frame must carry none. The document served here is shaped as a report rendered before 2026-09-18,
+// with the menu beside the report's header rather than inside it. That is most of the archive, and the
+// shape that left a second menu in the frame, its current item red on red in the dark theme. The probe
+// counts the menus inside the frame; the portal's are counted on the page.
 import { spawn } from 'node:child_process'
 import { createServer } from 'node:http'
 import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs'
@@ -53,7 +59,7 @@ const FRAMEWORK = { framework_key: 'house-triage', title: 'House triage',
 const PROBE = `<script>(function(){
   var id=Math.random().toString(36).slice(2);
   function post(){try{parent.postMessage({themeProbe:1,loadId:id,theme:document.documentElement.getAttribute('data-theme'),
-    bg:getComputedStyle(document.body).backgroundColor},'*');}catch(e){}}
+    bg:getComputedStyle(document.body).backgroundColor,menus:document.querySelectorAll('nav.strip,[data-sec]').length},'*');}catch(e){}}
   new MutationObserver(post).observe(document.documentElement,{attributes:true,attributeFilter:['data-theme']});
   post();
 })();</script>`
@@ -61,7 +67,18 @@ const REPORT = (() => {
   const html = renderKnockoutHtml({ marks: [{ name: MARK, rating: 'Low', classes: [9], basis: 'Nothing identical in the field screened.',
     factors: ['No identical name was found.'], counterFactors: [], mitigation: '', assessment: '', findings: [] }],
     batch: { executiveSummary: 'One name screened.' } }, FRAMEWORK, { runId: RUN_ID, overall: 'Low', identity: { identity: 'Knockout search' }, issuedDate: '2026-09-18' })
-  const served = prepareReportForEmbed(html, {}).html
+  // THE OLD SHAPE: today's menu moved to just after the header's closing tag, where the renderer put it
+  // before 2026-09-18. A document with no menu at all would make the count below prove nothing.
+  const strip = html.match(/<nav class="[^"]*\bstrip\b[^"]*"[^>]*>[\s\S]*?<\/nav>/)?.[0]
+  if (!strip) { console.error('the rendered report has no section menu, so this check could not build the archived shape'); process.exit(2) }
+  const without = html.replace(strip, '')
+  const head = without.indexOf('<div class="rep-stickyhead')
+  const tags = /<\/?div\b[^>]*>/g
+  tags.lastIndex = head
+  let depth = 0, m, close = -1
+  while ((m = tags.exec(without))) { depth += m[0].startsWith('</') ? -1 : 1; if (depth === 0) { close = m.index + m[0].length; break } }
+  if (close < 0) { console.error('the report header has no closing tag, so this check could not build the archived shape'); process.exit(2) }
+  const served = prepareReportForEmbed(without.slice(0, close) + strip + without.slice(close), {}).html
   const at = served.lastIndexOf('</body>')
   return at < 0 ? served + PROBE : served.slice(0, at) + PROBE + served.slice(at)
 })()
@@ -151,9 +168,19 @@ const press = () => value(`(() => { const b = document.querySelector('button[ari
 
 const fail = []
 const ok = []
+// ONE MENU: none in the frame, one in the portal's header, under whichever theme is showing.
+const menus = async (theme, probe) => {
+  const portal = await value(`document.querySelectorAll('nav.report-sections').length`)
+  if (!probe || typeof probe.menus !== 'number') fail.push(`${theme}: the frame never reported its section menus`)
+  else if (probe.menus !== 0) fail.push(`${theme}: the frame carries ${probe.menus} section-menu element(s) beside the portal's own`)
+  else ok.push(`${theme}: no section menu inside the frame`)
+  if (portal !== 1) fail.push(`${theme}: the portal draws ${portal} section menu(s) where it should draw one`)
+  else ok.push(`${theme}: the portal draws the one section menu`)
+}
 const light = await settle('light')
 if (!light || light.theme !== 'light') fail.push(`the embedded report never took the portal's light theme — last report from the frame: ${JSON.stringify(light)}`)
 else ok.push(`light: the report took the portal's theme, ground ${light.bg} (luminance ${luminance(light.bg)?.toFixed(2)})`)
+await menus('light', light)
 await shot('report-light.png')
 
 if (!(await press())) fail.push('the portal\'s theme switch is not on the Result screen')
@@ -165,6 +192,7 @@ else {
   if (light && dark.loadId !== light.loadId) fail.push('the report reloaded to change theme — it must repaint in place')
   else ok.push('dark: repainted in place, the same load of the document')
 }
+await menus('dark', dark)
 await shot('report-dark.png')
 
 await press()
@@ -178,5 +206,5 @@ for (const line of fail) console.log(`  FAIL ${line}`)
 try { ws.close() } catch { /* going anyway */ }
 try { process.kill(-chrome.pid, 'SIGKILL') } catch { /* already gone */ }
 server.close()
-console.log(fail.length ? `\nreport-theme-render-check: ${fail.length} measurement(s) failed.` : `\nreport-theme-render-check: the embedded report follows the portal's theme, in place.`)
+console.log(fail.length ? `\nreport-theme-render-check: ${fail.length} measurement(s) failed.` : `\nreport-theme-render-check: the embedded report follows the portal's theme in place, under the portal's one section menu.`)
 process.exit(fail.length ? 1 : 0)

package/scripts/settings-render-check.mjs

@@ -148,6 +148,10 @@ const sessionId = sess.sessionId
 const cmd = (method, params = {}) => new Promise((r) => { const i = ++id; pending.set(i, r); ws.send(JSON.stringify({ id: i, sessionId, method, params })) })
 await cmd('Page.enable')
 // A probe that throws says so, rather than returning nothing for the assertions after it to misread.
+// A value pasted into code the page evaluates, as a JavaScript string or object literal. JSON.stringify
+// alone leaves `<`, `>`, `/` and the two line separators as they are; escaped, they read the same once
+// parsed and cannot close or break the code they are pasted into.
+const jsLiteral = (v) => JSON.stringify(v).replace(/[<>\/\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`)
 const evalIn = async (expr) => {
   const r = (await cmd('Runtime.evaluate', { expression: expr, awaitPromise: true, returnByValue: true })).result
   if (r?.exceptionDetails) console.error(`  ! a probe threw: ${r.exceptionDetails.exception?.description ?? r.exceptionDetails.text}`)
@@ -184,7 +188,7 @@ async function reload(ready, what) {
 }
 
 async function setTheme(theme) {
-  await evalIn(`(() => { document.documentElement.setAttribute('data-theme', ${JSON.stringify(theme)}); try { localStorage.setItem('cordillera-theme', ${JSON.stringify(theme)}) } catch {} return true })()`)
+  await evalIn(`(() => { document.documentElement.setAttribute('data-theme', ${jsLiteral(theme)}); try { localStorage.setItem('cordillera-theme', ${jsLiteral(theme)}) } catch {} return true })()`)
   await sleep(250)
 }
 
@@ -381,7 +385,10 @@ const SPEC = {
   caseLawGap: 'Until these are set up, a Full country search still runs and its report discloses the case-law gap instead of reporting no adverse case law.',
   adminLine: 'To change the address, the permissions or the companies on it, contact your Clearotron administrator.',
   blurLine: 'On the top bar. It covers every mark and company on screen, and an open report whole. It stays as you left it on this computer.',
-  reset: 'Lost the passphrase? Run clearotron passphrase --reset on the machine running this portal. It mints a new one and prints it once.',
+  // The sign-in page's wording is the owner's, approved 2026-09-19 and used verbatim.
+  identity: (email) => `This Clearotron has one user: ${email}. Enter its passphrase.`,
+  reset: 'The passphrase was printed once when this Clearotron first started. Lost it? Run clearotron passphrase --reset on the machine running this portal. It prints a new one, once, for the same user.',
+  key: 'A key from clearotron key issue is for an AI assistant, not for this page.',
   addPeople: 'To add people, put it behind a login system such as your company single sign-on. How to set that up',
 }
 
@@ -543,18 +550,18 @@ for (const theme of ['light', 'dark']) {
     await setTheme(theme)
     const closed = (await evalIn(signInProbe)) ?? {}
     out[`${label}-closed-${theme}`] = closed
-    ok(closed.heading === 'Sign in' && closed.identity === `Clearotron portal, as ${EMAIL}.` && closed.field && closed.button === 'Sign in',
-      `the card keeps its heading, identity line, field and button (saw ${JSON.stringify({ h: closed.heading, id: closed.identity, button: closed.button })})`)
-    ok(closed.lead === 'This Clearotron signs in one person: you.' && closed.leadBold, `one bold line under the button (saw ${JSON.stringify(closed.lead)})`)
+    ok(closed.heading === 'Sign in' && closed.identity === SPEC.identity(EMAIL) && closed.field && closed.button === 'Sign in',
+      `the card keeps its heading, names the install's one user, and keeps the field and button (saw ${JSON.stringify({ h: closed.heading, id: closed.identity, button: closed.button })})`)
+    ok(!closed.lead && !closed.leadBold, `the "signs in one person" line is gone from under the button (saw ${JSON.stringify(closed.lead)})`)
     ok(closed.summary === 'Administrator help' && closed.open === false && closed.hintsShown === 0,
       `the administrator's lines sit in a closed "Administrator help" fold (saw ${JSON.stringify({ summary: closed.summary, open: closed.open, shown: closed.hintsShown })})`)
     if (!reset) await capture(`sign-in-help-closed-${theme}`)
     await press('.card details.fold > summary')
     const opened = (await evalIn(signInProbe)) ?? {}
     out[`${label}-open-${theme}`] = opened
-    ok(opened.open === true && opened.hintsShown === 2, `pressing it opens both lines (saw ${JSON.stringify({ open: opened.open, shown: opened.hintsShown })})`)
-    ok(opened.hints[0] === (reset ? SPEC.reset.replace('clearotron passphrase --reset', reset) : SPEC.reset) && opened.hints[1] === SPEC.addPeople,
-      `the fold holds the product's two lines word for word (saw ${JSON.stringify(opened.hints)})`)
+    ok(opened.open === true && opened.hintsShown === 3, `pressing it opens its three lines (saw ${JSON.stringify({ open: opened.open, shown: opened.hintsShown })})`)
+    ok(opened.hints[0] === (reset ? SPEC.reset.replace('clearotron passphrase --reset', reset) : SPEC.reset) && opened.hints[1] === SPEC.key && opened.hints[2] === SPEC.addPeople,
+      `the fold holds the owner's three lines word for word (saw ${JSON.stringify(opened.hints)})`)
     ok(opened.setUp?.text === 'How to set that up' && opened.setUp?.href === LOGIN_IN_FRONT_DOC, `with the "How to set that up" link (saw ${JSON.stringify(opened.setUp)})`)
     ok(opened.codeInside && !opened.overflowsPage && opened.cardWidth <= 420,
       `the reset command stays inside the card at its own width (card ${opened.cardWidth}px, ${opened.codeLines} line(s), inside: ${opened.codeInside})`)

package/scripts/strip-tracker-citations.mjs

@@ -2,15 +2,15 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
 //
-// Removes the internal citation OPENER from comments and prose in the tree (tracker issue 309).
+// Removes the internal citation OPENER from comments and prose in the tree.
 //
 // The form is `tracker issue NNN — ` standing at the head of a sentence, where the citation is not part
 // of what the sentence says but a label in front of it. Stripping the opener leaves the sentence intact:
 //
-//     // tracker issue 1149 — the walk must start at the repository root
+//     // tracker issue NNNN — the walk must start at the repository root
 //     // the walk must start at the repository root
 //
-//     assert.ok(x, "Refs tracker issue 2075 — an absent file is a finding")
+//     assert.ok(x, "Refs tracker issue NNNN — an absent file is a finding")
 //     assert.ok(x, "an absent file is a finding")
 //
 // WHY THE PATTERN LOOKS OVER-SPECIFIED. Three parts of it are load-bearing and each was measured, not
@@ -20,7 +20,7 @@
 //     and the replacement is `$1`, which puts that opener back. Without the group the sweep deletes the
 //     opening quote of every test name it touches, and a broken string literal is a syntax error in the
 //     lucky cases and a changed assertion in the unlucky ones.
-//   · `\s+` AFTER THE SEPARATOR, never `\s*`. `tracker issue 1149-12` is an ITEM suffix, not a citation
+//   · `\s+` AFTER THE SEPARATOR, never `\s*`. `tracker issue NNNN-12` is an ITEM suffix, not a citation
 //     followed by prose: there is no space after its hyphen. `\s*` eats the item number.
 //   · THE `i` FLAG. `Refs tracker issue NNN` is capitalised at the head of a commit-style line and is a
 //     fifth of the corpus.

package/scripts/test-run.mjs

@@ -46,11 +46,11 @@
 // about paths it did not create is how a tidy-up becomes an outage.
 
 import { spawn } from "node:child_process";
-import { mkdtempSync, mkdirSync, rmSync, readdirSync, statSync, existsSync, readFileSync, symlinkSync, copyFileSync, chmodSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, readdirSync, statSync, existsSync, readFileSync, symlinkSync, copyFileSync, chmodSync, writeFileSync, realpathSync } from "node:fs";
 import { delimiter, dirname, join, parse as parsePath, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { tmpdir } from "node:os";
-import { snapshotRepo, repoWrites, explainRepoWrites } from "./repo-writes.mjs";
+import { tmpdir, homedir } from "node:os";
+import { snapshotRepo, repoWrites, explainRepoWrites, snapshotHome, explainHomeWrites } from "./repo-writes.mjs";
 
 
 // ── TAIL — THIS WRAPPER READS BOTH SPELLINGS; IT DOES NOT TRANSLATE THE ENVIRONMENT ───────────
@@ -271,8 +271,8 @@ process.env.CLEAROTRON_DEMO_PROFILES ??= "1";
 // driver/test/*.test.mjs. They are indistinguishable from code defects. An agent who runs the suite on a
 // branch, sees 295 red, and diffs the failing NAMES against a baseline taken the same way sees zero
 // regressions and calls the branch clean — and it is, but roughly 190 tests never executed, and a real
-// regression inside any of them is invisible by exactly that arithmetic. It has already happened: 's
-// first full-suite comparison was taken against a 295-fail baseline.
+// regression inside any of them is invisible by exactly that arithmetic. It has already happened: a
+// full-suite comparison was taken against a 295-fail baseline.
 //
 // So: refuse, name what is missing, and name the command. REFUSE RATHER THAN INSTALL — this wrapper is
 // what CI and scripts/publication-scan.mjs run the suite through, and a wrapper that can start a network
@@ -699,7 +699,88 @@ mkdirSync(process.env.CLEAROTRON_SUITE_TELEMETRY_DIR, { recursive: true });
 // Taken HERE, at the last statement before the child exists, so nothing this runner does to the tree
 // between the two reads can be mistaken for something a test did. The comparison is in `close`, below.
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// ── AND NO PRODUCT COMMAND A TEST STARTS REBUILDS THIS CHECKOUT'S PORTAL BUNDLE ─────────────────────
+//
+// `start` rebuilds `portal-ui/dist` when it is older than `portal-ui/src` — right for a reader whose pull
+// left the bundle behind, and a write into this checkout when a test starts `start` from it. Eight driver
+// files do. On a clone where somebody once built the portal and then pulled, the first of them to run
+// rebuilt the bundle mid-suite and the guard above failed the run; the next run found the bundle fresh and
+// passed (measured 2026-09-18). A fresh clone never sees it: with no bundle there is nothing to rebuild.
+//
+// THE SAME SEAT AS THE ENGINE SHIMS, AND NO PRODUCT CHANGE. `start` runs the bare word `npm`, so a shim at
+// the front of PATH answers it for every child that keeps this PATH. It refuses exactly one command —
+// `npm run build:ui` with this checkout as its working directory — and hands everything else to the npm
+// it found on PATH. `start` reports a refused rebuild and carries on serving, which is its behaviour on
+// any failed build. A child that composes its own PATH walks past this, and the guard above still
+// catches what it writes.
+function onPath(name, pathValue) {
+  for (const d of String(pathValue ?? "").split(delimiter).filter(Boolean)) {
+    const p = join(d, name);
+    try { if (statSync(p).isFile()) return p; } catch { /* not here */ }
+  }
+  return null;
+}
+// COUNTED, because the refusal itself is printed into a child that a test usually captures: the run
+// reports how many rebuilds it turned away, so a stale bundle is named once where a reader can see it.
+let npmShimDir = null;
+if (process.platform !== "win32") {
+  const realNpm = onPath("npm", process.env.PATH);
+  if (realNpm) {
+    const q = (v) => `'${String(v).replaceAll("'", "'\\''")}'`;
+    npmShimDir = join(root, "npm-shim");
+    mkdirSync(npmShimDir, { recursive: true });
+    writeFileSync(join(npmShimDir, "npm"), [
+      "#!/bin/sh",
+      "# Written by scripts/test-run.mjs for one suite run; removed with the run's temp root.",
+      `if [ "$1" = run ] && [ "$2" = build:ui ] && [ "$(pwd -P)" = ${q(realpathSync(REPO_ROOT))} ]; then`,
+      "  echo '[test-run] refused: npm run build:ui in the checkout. A suite run does not rebuild its portal bundle.' >&2",
+      `  echo refused >> ${q(join(npmShimDir, "refused"))}`,
+      "  exit 1",
+      "fi",
+      `exec ${q(realNpm)} "$@"`,
+      "",
+    ].join("\n"), { mode: 0o755 });
+    process.env.PATH = npmShimDir + delimiter + process.env.PATH;
+  }
+}
 const repoBefore = snapshotRepo(REPO_ROOT);
+// AND THE HOME IT RUNS AS, read at the same moment for the same reason (`repo-writes.mjs` says which
+// folders and why). HOME as the child inherits it, which is the home every unpinned product command in
+// the run resolves.
+const RUN_HOME = String(process.env.HOME ?? "").trim() || homedir();
+const homeBefore = snapshotHome(RUN_HOME);
+
+// ── AND NOTHING THE RUN MADE IS LEFT IN THE MACHINE'S TEMP DIRECTORY ────────────────────────────────
+//
+// The run's own root is removed on every exit. What escapes it is a child handed an environment without
+// TMPDIR: it falls back to the machine's temp directory, and nothing removes what it made there. Measured
+// 2026-09-19: fifteen `clearotron-demo-*` directories per `npm test`, from the demo's temporary sample
+// copies, and 36 GB accumulated on one box. Named by the product prefix, so the guard reads only what
+// this product makes; owned by this account, so another user's run is not ours to count.
+//
+// THE OUTERMOST RUN WATCHES THE MACHINE'S TEMP ROOTS. A nested run watches only its own base, and only
+// when a test arms it (CT_TEMP_LEAK_GUARD=1): the runner's own tests drive nested runs while the rest of
+// the suite is working, and a nested guard reading the shared root would count its neighbours' files.
+const LEAK_PREFIXES = Object.freeze(["clearotron-demo-"]);
+const OUTERMOST = !String(process.env.CT_TEST_MACHINE_TMP ?? "").trim();
+const LEAK_ROOTS = OUTERMOST
+  ? [...new Set([MACHINE_TMP, REAL_TMP, ...PLATFORM_TMP].map((p) => resolve(p)))]
+  : String(process.env.CT_TEMP_LEAK_GUARD ?? "") === "1" ? [resolve(REAL_TMP)] : [];
+function tempLeftovers() {
+  const uid = typeof process.getuid === "function" ? process.getuid() : null;
+  const out = new Set();
+  for (const r of LEAK_ROOTS) {
+    let names;
+    try { names = readdirSync(r); } catch { continue; }
+    for (const n of names) {
+      if (!LEAK_PREFIXES.some((p) => n.startsWith(p))) continue;
+      try { if (uid == null || statSync(join(r, n)).uid === uid) out.add(join(r, n)); } catch { /* gone already */ }
+    }
+  }
+  return out;
+}
+const tempBefore = tempLeftovers();
 
 
 child = spawn(argv[0], argv.slice(1), {
@@ -741,7 +822,14 @@ child.on("error", (e) => {
 });
 
 child.on("close", (code, signal) => {
+  let refusedBuilds = 0;
+  try { if (npmShimDir) refusedBuilds = readFileSync(join(npmShimDir, "refused"), "utf8").split("\n").filter(Boolean).length; }
+  catch { /* none refused */ }
   cleanup();
+  if (refusedBuilds) {
+    console.error(`[test-run] turned away ${refusedBuilds} rebuild(s) of this checkout's portal bundle: it is older than`);
+    console.error("  portal-ui/src. `npm run build:ui` brings it current; until then doctor's arms report it stale.");
+  }
   // The exit code IS the result — CI reads it. Never swallow a failure to report a tidy cleanup.
   // A SIGNALLED RUN IS NOT EVIDENCE ABOUT WRITES: it was cancelled mid-flight, so a half-finished
   // fixture proves nothing and re-raising is the honest answer. The guard below never runs on that path.
@@ -749,8 +837,22 @@ child.on("close", (code, signal) => {
 
   const wrote = repoWrites(repoBefore, snapshotRepo(REPO_ROOT), REPO_ROOT);
   if (wrote.length) for (const line of explainRepoWrites(wrote)) console.error(line);
+  const wroteHome = repoWrites(homeBefore, snapshotHome(RUN_HOME), RUN_HOME);
+  if (wroteHome.length) for (const line of explainHomeWrites(wroteHome, RUN_HOME)) console.error(line);
+  const leftInTemp = [...tempLeftovers()].filter((p) => !tempBefore.has(p)).sort();
+  if (leftInTemp.length) {
+    console.error("");
+    console.error(`[test-run] THIS RUN LEFT ${leftInTemp.length} DIRECTOR${leftInTemp.length === 1 ? "Y" : "IES"} IN THE MACHINE'S TEMP DIRECTORY:`);
+    for (const p of leftInTemp) console.error(`  + ${p}`);
+    console.error("");
+    console.error("  A child handed an environment without TMPDIR puts its temporary files in the machine's temp");
+    console.error("  directory, where nothing removes them. Pass `TMPDIR: tmpdir()` in that child's env, so they land");
+    console.error("  in this run's own root, which is removed on every exit.");
+    console.error("");
+    console.error("  (Another run on this account making the same directories at the same time prints this too.)");
+  }
   // THIS MAY TURN A GREEN RUN RED. IT MUST NEVER TURN A RED RUN GREEN — a failing suite keeps its own
   // exit code, because what the tests found matters more than what they wrote while finding it.
   const childCode = code ?? 1;
-  process.exit(childCode !== 0 ? childCode : (wrote.length ? 1 : 0));
+  process.exit(childCode !== 0 ? childCode : (wrote.length || wroteHome.length || leftInTemp.length ? 1 : 0));
 });