clearotron 0.3.2-beta.11 → 0.3.2-beta.12

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

@@ -381,7 +381,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 +546,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/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 ───────────
@@ -699,7 +699,57 @@ 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);
 
 
 child = spawn(argv[0], argv.slice(1), {
@@ -741,7 +791,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 +806,10 @@ 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);
   // 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 ? 1 : 0));
 });

package/shared/client-door.mjs

@@ -134,6 +134,26 @@ export function demoTokenSecret(base, io) {
  * cannot type, and it names the demo's base so the verb reads that demo's secret and guest list. An
  * install moved with `--base` is named too, for its guest list; the default install needs neither.
  */
+/**
+ * What an account key is for, in the owner's words (2026-09-19), printed first by every command that
+ * hands one over. ONE COPY: `key issue` and `connect --base` both print it, and a second copy of an
+ * approved sentence is the one that drifts. `reset` is the passphrase command as the caller composes it.
+ */
+export function keyPurposeLine({ email, brand, reset }) {
+  return `This key lets an AI assistant act as ${email} through ${brand}'s client door. `
+    + `It is not a portal sign-in; the portal uses the passphrase (${reset}).`;
+}
+
+/**
+ * The command that connects an assistant to a running DEMO: it mints the key and names the client door
+ * in one step, so nobody issues a key by hand (owner, 2026-09-19). A demo keeps its own secret and guest
+ * list in its folder, which is why the folder is named.
+ */
+export function demoConnectCommand({ prefix = "", base }) {
+  const q = (d) => (/\s/.test(d) ? `"${d}"` : d);
+  return `${prefix}clearotron connect --base ${q(base)}`;
+}
+
 export function keyIssueCommand({ prefix = "", demo = false, user = null, base = null, defaultBase = null } = {}) {
   const q = (d) => (/\s/.test(d) ? `"${d}"` : d);
   const who = demo && user ? user : "<email>";

package/shared/parent-watch.mjs

@@ -0,0 +1,33 @@
+// 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
+//
+// NOTICE WHEN THE PROCESS THAT STARTED US IS GONE.
+//
+// `npx clearotron demo` runs as npm → `sh -c clearotron demo …` → the launcher → the demo. A TERM to the
+// pid a shell hands back for a backgrounded `npx …` reaches npm, npm passes it to that `sh`, and `sh` exits
+// without passing it on. The launcher is reparented and the demo runs on, holding its three ports, with
+// nothing saying so. Measured on npm 10.9.8, 2026-09-18. Neither npm nor that `sh` is ours to change, and
+// a process is told nothing when its parent dies on Linux or macOS, so the launcher asks: its parent pid
+// changes the moment it is reparented, to init or to the nearest subreaper.
+//
+// A process whose parent is already init when it starts (started under `setsid`, or by a service manager
+// that exits) never sees its parent pid change, so this never fires for it.
+
+/**
+ * Call `onGone` once, the first time this process's parent pid differs from the one it had when this was
+ * called. Returns a function that stops watching. The timer never keeps the process alive on its own.
+ */
+export function watchParent(onGone, { intervalMs = 1000, parentPid = () => process.ppid } = {}) {
+  const first = parentPid();
+  let fired = false;
+  const timer = setInterval(() => {
+    if (fired) return;
+    const now = parentPid();
+    if (now === first) return;
+    fired = true;
+    clearInterval(timer);
+    onGone({ was: first, now });
+  }, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}

package/shared/running-start.mjs

@@ -13,9 +13,9 @@
 // record whose process is gone is read as absent, and `status` asks the portal itself before saying the
 // product is up. Three answers, all honest: up; started but not answering; not running.
 
-import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 /**
  * Where the records live: one file per serving process, beside the settings and the revocation list.
@@ -37,9 +37,14 @@ export function pidAlive(pid) {
 /**
  * Record one serving start. Returns the function that removes the record; calling it twice is harmless,
  * so the caller can hang it on both its own shutdown and the process's `exit`.
+ *
+ * THE FOLDERS THIS RECORD MADE GO WITH IT, when nothing else is in them. On a home that had none, the
+ * demo's record created `~/.config/clearotron/running` and its parent, and a clean stop left both behind
+ * under a banner saying nothing of the demo was left (measured 2026-09-19). A folder that was already
+ * there, or that holds anything else, stays: `rmdirSync` removes only an empty directory.
  */
 export function recordRunning(rec, { dir = runningDir() } = {}) {
-  mkdirSync(dir, { recursive: true });
+  const made = mkdirSync(dir, { recursive: true });
   const file = join(dir, `${rec.pid}.json`);
   const tmp = `${file}.tmp`;
   writeFileSync(tmp, `${JSON.stringify(rec, null, 2)}\n`, { mode: 0o600 });
@@ -49,6 +54,12 @@ export function recordRunning(rec, { dir = runningDir() } = {}) {
     if (gone) return;
     gone = true;
     try { rmSync(file, { force: true }); } catch { /* already gone */ }
+    if (made) {
+      for (let d = dir; ; d = dirname(d)) {
+        try { rmdirSync(d); } catch { break; }   // not empty, or gone: either way, not ours to take
+        if (d === made) break;
+      }
+    }
   };
 }
 

package/shared/scope.mjs

@@ -259,7 +259,7 @@ export const TOOL_SCOPES = {
 // The ONLY artifact a user (report-link) token may read via read_artifact — THE report (one report;
 // clientSummary was a second version by another name and is retired from client reach — the file
 // remains an internal cover-note source ops tokens may read). Everything else
-// (narrative, audit, run.jsonl, skepticFlags, lisaEyeReview, matterContext, caseLaw, register axes,
+// (narrative, audit, run.jsonl, skepticFlags, seniorEyeReview, matterContext, caseLaw, register axes,
 // status.json, …) is internal and stays sealed from a user token.
 // Exported so the server's Resources surface (ListResources/ReadResource) gates to the SAME set.
 /**
@@ -833,7 +833,7 @@ export function resolveScope({ local = false, innerToken = null, email = null, f
         throw new Error("forbidden: client account access is not enabled on this door");
       return { kind: "account", runId: null, sub: t.sub, verbs: null, ...personScope(t.sub, t.accounts) };
     }
-    if (t.scope !== "user") throw new Error("forbidden: the client surface accepts only a run-scoped user token or an account key");
+    if (t.scope !== "user") throw new Error(`forbidden: the client surface accepts only a run-scoped user token or an account key${otherDoor("staff")}`);
     return { kind: "user", runId: t.runId, sub: t.sub, verbs: null, accounts: null }; // run-bound — accounts moot
   }
   if (local) return { kind: "ops", runId: null, sub: "local", verbs: null, accounts: "*" };
@@ -842,7 +842,7 @@ export function resolveScope({ local = false, innerToken = null, email = null, f
     // An account key belongs to the CLIENT door and nowhere else. Falling through would land it in the
     // `user` arm below with runId:null — a "run-bound" scope bound to no run, which every run-pinning check
     // downstream would then wave through. Refuse it here instead.
-    if (t.scope === "account") throw new Error("forbidden: an account key is only accepted on the client surface");
+    if (t.scope === "account") throw new Error(`forbidden: an account key is only accepted on the client surface${otherDoor("client")}`);
     return t.scope === "ops"
       ? { kind: "ops", runId: null, sub: t.sub, verbs: t.verbs, accounts: t.accounts ?? "*" }
       : { kind: "user", runId: t.runId, sub: t.sub, verbs: null, accounts: null }; // run-bound — accounts moot
@@ -866,6 +866,25 @@ export function resolveScope({ local = false, innerToken = null, email = null, f
   throw new Error("forbidden: no run-scoped token and not a firm-staff identity — refusing (internal read-all requires proven firm staff)");
 }
 
+/**
+ * WHERE THE OTHER DOOR IS, for the refusal that turns a key away from the wrong one: " (client surface:
+ * <address>)", or nothing when this process was not told. A key refused as "only accepted on the client
+ * surface" read as a permissions problem, and the next thing a reader did was the wrong thing; the demo's
+ * own output led an assistant to the staff door with an account key (measured on a published beta,
+ * 2026-09-19). Each door is handed the other's port and host by `start` and by the shared unit settings,
+ * under the names the other door listens on. The client door's public address, when one is set, is the
+ * one a remote assistant can reach, so it wins. A wildcard bind is named as loopback, where a reader on
+ * this machine reaches it. PURE given its env.
+ */
+export function otherDoor(which, env = process.env) {
+  const [url, host, port] = which === "client"
+    ? [env.CLEAROTRON_CLIENT_MCP_URL, env.CLIENT_MCP_HTTP_HOST, env.CLIENT_MCP_HTTP_PORT]
+    : [null, env.TRADEMARK_MCP_HTTP_HOST, env.TRADEMARK_MCP_HTTP_PORT];
+  const at = String(url ?? "").trim() || (String(port ?? "").trim()
+    ? `http://${!host || host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${String(port).trim()}/mcp` : "");
+  return at ? ` (${which} surface: ${at})` : "";
+}
+
 // The ENFORCEMENT chokepoint. Returns the (possibly run-pinned) args to dispatch, or throws an Error the
 // CallTool handler surfaces as an MCP error. ops ⇒ everything. user/internal ⇒ no write tools. user ⇒ also
 // no cross-run tool, and every run-scoped call is PINNED to the token's bound run (a mismatching explicit