@bongos/core 1.23.22 → 1.24.1

package/tests/hall_ai_studio.mjs

@@ -0,0 +1,347 @@
+// tests/hall_ai_studio.mjs — the studio's AI pages, /builders/ai-studio (task
+// 1004921, goal 1000136, ADR 0392), built on option C of the AI Studio options
+// canvas plus the owner's addition: the result's request can be changed and
+// made again.
+//
+// Three halves:
+//   1. The pure rules (ai-studio-lib.js): money in words (sub-cent prices to
+//      four decimals, a balance rounded down), the receipt in its three forms,
+//      the month's summary, the waiting checklist, the route, the reply's safe
+//      markup, and the home's line.
+//   2. The REAL page (ai-studio.js) in a vm over a small fake DOM and a stub
+//      client that answers from the hall-preview fixtures (the same shapes the
+//      ai-studio routes send): each view paints its words, step 3 sends the
+//      request on the card pressed, and "Make it again" sends the CHANGED words
+//      on fresh copies of the earlier uploads, paid the same way.
+//   3. The walls: the page writes through three routes only, never asks for a
+//      key, and the studio home shows its AI door only where the module is on.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PUB = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const FIX = path.join(ROOT, 'scripts', 'hall-preview', 'fixtures');
+const lib = require(path.join(PUB, 'ai-studio-lib.js'));
+const { escapeHtml } = require(path.join(ROOT, 'src', 'html-escape.js'));
+const fixture = (name) => JSON.parse(fs.readFileSync(path.join(FIX, `${name}.json`), 'utf8'));
+// The harness writes relative dates ("@-0.1d"); here every one is an hour ago.
+const HOUR_AGO = new Date(Date.now() - 3600 * 1000).toISOString();
+const dated = (v) => JSON.parse(JSON.stringify(v), (k, x) => (typeof x === 'string' && /^@[-+]/.test(x) ? HOUR_AGO : x));
+
+// ---- 1. the pure rules --------------------------------------------------------
+
+test('money: sub-cent prices keep four decimals, whole cents two, a balance rounds down', () => {
+  assert.equal(lib.usd(42100), '$0.0421');
+  assert.equal(lib.usd(500000), '$0.50');
+  assert.equal(lib.usd(20910000), '$20.91');
+  assert.equal(lib.usd(-2600000), '−$2.60');
+  assert.equal(lib.usd(3100), '$0.0031');
+  assert.equal(lib.balanceUsd(12357900), '$12.35', 'a balance never shows a cent that is not there');
+  assert.equal(lib.balanceUsd(12400000), '$12.40');
+  assert.equal(lib.usd(null), '');
+});
+
+test('the receipt: our key splits the provider and our markup; an own key charges nothing', () => {
+  const done = dated(fixture('ai-studio__requests__done')).request;
+  const ours = lib.receipt(done, 1.08);
+  assert.deepEqual(ours.rows, [['Paid with', 'your balance'], ['OpenRouter', '$0.0390'], ['Our 8%', '$0.0031'], ['You paid', '$0.0421']]);
+  const gemini = lib.receipt(dated(fixture('ai-studio__requests__own')).request, 1.08);
+  assert.deepEqual(gemini.rows, [['Paid with', 'your own Gemini key'], ['Cost', 'not reported']]);
+  assert.match(gemini.note, /We charged nothing/);
+  const openrouter = lib.receipt({ status: 'done', key_source: 'own', provider_cost_micro: 39000 }, 1.08);
+  assert.deepEqual(openrouter.rows, [['Paid with', 'your own OpenRouter key'], ['Cost', '$0.0390']]);
+  assert.deepEqual(lib.receipt(dated(fixture('ai-studio__requests__failed')).request, 1.08).rows, [], 'a failed run has no receipt');
+});
+
+test('the month: added, spent, money back and own-key requests, from the ledger', () => {
+  const bal = dated(fixture('ai-studio__balance'));
+  const sum = lib.monthSummary(bal.ledger, new Date());
+  assert.deepEqual(sum.lines.map((l) => [l.label, l.value]), [
+    ['Added', '+$15.00'],
+    ['Spent on 2 requests', '−$0.0833'],
+    ['Money back from 1 failed request', '$0.50 returned'],
+    ['On your own keys, 1 request', 'free'],
+  ]);
+  const old = lib.monthSummary([{ kind: 'topup', amount_micro: 5000000, created_at: '2001-01-01T00:00:00Z' }], new Date());
+  assert.deepEqual(old.lines, [], 'another month does not count');
+});
+
+test('the waiting lines follow the status and the clock; the clock reads m:ss', () => {
+  assert.deepEqual(lib.waitSteps('queued', 0, 3).map((s) => s.state), ['now', 'later', 'later']);
+  assert.deepEqual(lib.waitSteps('running', 5, 3).map((s) => s.state), ['done', 'now', 'later']);
+  assert.deepEqual(lib.waitSteps('running', lib.ANSWER_AFTER_SEC, 1).map((s) => [s.text, s.state]), [
+    ['Read your file', 'done'], ['Wrote the answer', 'done'], ['Drawing the pictures', 'now'],
+  ]);
+  assert.equal(lib.clock(34), '0:34');
+  assert.equal(lib.clock(75), '1:15');
+});
+
+test('the route, the files, the reply and the home line', () => {
+  assert.deepEqual(lib.routeOf('?request=1002'), { view: 'request', id: '1002' });
+  assert.deepEqual(lib.routeOf('?view=balance&all=1'), { view: 'balance', all: true });
+  assert.deepEqual(lib.routeOf('?step=make&from=7'), { view: 'step', step: 'make', from: '7' });
+  assert.deepEqual(lib.routeOf('?step=nope&from=x'), { view: 'step', step: 'pick', from: null });
+  assert.equal(lib.checkFile({ type: 'image/png', size: 100 }, 0), null);
+  assert.match(lib.checkFile({ type: 'image/svg+xml', size: 100 }, 0), /PNG, JPG/);
+  assert.match(lib.checkFile({ type: 'image/png', size: lib.MAX_IMAGE_BYTES + 1 }, 0), /4 MB/);
+  assert.match(lib.checkFile({ type: 'application/pdf', size: 100 }, lib.MAX_FILES), /up to 6/);
+  assert.equal(lib.replyHtml('Hi **there**\n\n<script>x</script>', escapeHtml), '<p>Hi <b>there</b></p><p>&lt;script&gt;x&lt;/script&gt;</p>');
+  assert.equal(lib.replyHtml('<b>x</b>'), '', 'no escaper, no markup: never unescaped text');
+  assert.equal(lib.homeLine([{ id: '9', status: 'running' }]).href, '/builders/ai-studio?request=9');
+  assert.equal(lib.homeLine([{ id: '9', status: 'done', finished_at: new Date().toISOString() }]).detail, 'your newest pictures are ready');
+  assert.equal(lib.homeLine([]).detail, 'sketches in, ideas and pictures out');
+  assert.equal(lib.againLine(3), 'Change the words and make it again. Same 3 files, paid the same way.');
+});
+
+test('step 3 offers the own key only when one is saved, and says when the balance is short', () => {
+  const keys = fixture('ai-studio__keys');
+  const bal = dated(fixture('ai-studio__balance'));
+  const c = lib.payChoices(keys, bal);
+  assert.deepEqual([c.own.name, c.own.billedBy, c.own.last4, c.left, c.setAside, c.short], ['Gemini', 'Google', '9c1d', '$12.40 left', '$0.50', false]);
+  // OpenRouter wins when both are saved, as keys.chooseKey prefers it. (Built
+  // here: the harness scrubber blanks that provider name out of fixtures.)
+  const both = { keys: [{ provider: 'openrouter', set: true, last4: '4f2a' }, { provider: 'gemini', set: true, last4: '9c1d' }] };
+  assert.deepEqual([lib.ownKey(both).name, lib.ownKey(both).billedBy, lib.ownKey(both).last4], ['OpenRouter', 'OpenRouter', '4f2a']);
+  assert.equal(lib.payChoices({ keys: [] }, bal).own, null);
+  assert.equal(lib.payChoices(keys, { ...bal, balance: { available_micro: 100000, held_micro: 0 } }).short, true);
+  assert.equal(lib.payChoices(keys, { ...bal, balance: null }).payments, false);
+});
+
+// ---- 2. the real page in a vm ------------------------------------------------
+
+// A fake element: enough of the DOM for ai-studio.js. innerHTML is kept as a
+// string, and the elements a view wires are found in that string by id or by
+// data attribute, so a click runs the page's real handler.
+function makeEl(id) {
+  const el = {
+    id, _html: '', value: '', hidden: false, disabled: false, attrs: {}, handlers: {}, children: {},
+    classList: { add() {}, remove() {} },
+    get innerHTML() { return el._html; },
+    set innerHTML(v) { el._html = String(v); el.children = {}; },
+    get innerText() { return el._html.replace(/<[^>]+>/g, ' '); },
+    setAttribute(k, v) { el.attrs[k] = String(v); },
+    getAttribute(k) { return k in el.attrs ? el.attrs[k] : null; },
+    removeAttribute(k) { delete el.attrs[k]; },
+    addEventListener(type, fn) { (el.handlers[type] = el.handlers[type] || []).push(fn); },
+    focus() {},
+    async fire(type, extra = {}) {
+      const ev = { preventDefault() {}, currentTarget: el, target: el, ...extra };
+      for (const fn of el.handlers[type] || []) await fn(ev);
+    },
+    querySelector(sel) {
+      const id2 = /^#([\w-]+)$/.exec(sel);
+      if (id2 && el._html.includes(`id="${id2[1]}"`)) return el.children[sel] || (el.children[sel] = makeEl(id2[1]));
+      if (sel === '[data-head]' && el._html.includes('data-head')) return el.children[sel] || (el.children[sel] = makeEl('head'));
+      return null;
+    },
+    querySelectorAll(sel) {
+      const attr = /^\[(data-[\w-]+)\]$/.exec(sel);
+      if (!attr) return [];
+      const key = `all:${sel}`;
+      if (!el.children[key]) {
+        const re = new RegExp(`${attr[1]}="([^"]*)"`, 'g');
+        el.children[key] = [...el._html.matchAll(re)].map((m) => { const c = makeEl(''); c.attrs[attr[1]] = m[1]; return c; });
+      }
+      return el.children[key];
+    },
+  };
+  return el;
+}
+
+const settle = async () => { for (let i = 0; i < 30; i++) await new Promise((r) => setImmediate(r)); };
+
+function bootPage(search, { routes = {} } = {}) {
+  const els = { 'ais-page': makeEl('ais-page'), 'hall-main': makeEl('hall-main'), 'ais-file': makeEl('ais-file') };
+  const calls = [];
+  const store = new Map();
+  const loc = { search, href: `/builders/ai-studio${search}` };
+  const answers = {
+    'GET /api/bongos/me': { builder: { id: 1 } },
+    'GET /api/bongos/ai-studio/status': { ok: true },
+    'GET /api/bongos/ai-studio/keys': fixture('ai-studio__keys'),
+    'GET /api/bongos/ai-studio/balance': dated(fixture('ai-studio__balance')),
+    'GET /api/bongos/ai-studio/requests': dated(fixture('ai-studio__requests')),
+    'GET /api/bongos/ai-studio/requests/1001': dated(fixture('ai-studio__requests__done')),
+    'GET /api/bongos/ai-studio/requests/1002': dated(fixture('ai-studio__requests__running')),
+    'GET /api/bongos/ai-studio/requests/1003': dated(fixture('ai-studio__requests__failed')),
+    'GET /api/bongos/ai-studio/requests/1004': dated(fixture('ai-studio__requests__own')),
+    'GET /api/bongos/ai-studio/topup/quote': fixture('ai-studio__topup__quote'),
+    'POST /api/bongos/ai-studio/requests': dated(fixture('ai-studio__requests.post')),
+    'POST /api/bongos/ai-studio/topup': fixture('ai-studio__topup.post'),
+    ...routes,
+  };
+  let uploadSeq = 700;
+  const client = {
+    async request(method, url, opts = {}) {
+      calls.push({ method, url, body: opts.body });
+      if (method === 'POST' && url === '/api/bongos/ai-studio/uploads') {
+        uploadSeq += 1;
+        return { ok: true, status: 201, data: { file: { id: String(uploadSeq), role: 'upload', name: opts.body.name, content_type: opts.body.content_type, size_bytes: 10, url: `/api/bongos/ai-studio/files/${uploadSeq}` } } };
+      }
+      const key = `${method} ${url.split('?')[0]}`;
+      if (!(key in answers)) return { ok: false, status: 404, data: { error: { code: 'not_found' } } };
+      const a = answers[key];
+      if (a && a.__status) return { ok: false, status: a.__status, data: a.body };
+      return { ok: true, status: 200, data: a };
+    },
+  };
+  const ctx = {
+    console,
+    URLSearchParams,
+    setTimeout,
+    clearTimeout,
+    setInterval: () => 0,
+    clearInterval: () => {},
+    Date,
+    Promise,
+    document: { getElementById: (id) => els[id] || null, body: makeEl('body') },
+    location: loc,
+    history: {
+      pushState(_s, _t, url) { loc.href = url; loc.search = url.includes('?') ? url.slice(url.indexOf('?')) : ''; },
+      replaceState(_s, _t, url) { loc.href = url; loc.search = url.includes('?') ? url.slice(url.indexOf('?')) : ''; },
+    },
+    sessionStorage: { getItem: (k) => (store.has(k) ? store.get(k) : null), setItem: (k, v) => store.set(k, String(v)) },
+    fetch: async (url) => { calls.push({ method: 'FETCH', url }); return { ok: true, blob: async () => ({ size: 3, type: 'image/png' }) }; },
+    FileReader: class { readAsDataURL() { this.result = 'data:image/png;base64,QUJD'; setImmediate(() => this.onload()); } },
+    addEventListener() {},
+  };
+  ctx.window = ctx;
+  ctx.window.BongosClient = { createClient: () => client };
+  ctx.window.OTB = { toast: () => {}, escapeHtml };
+  vm.createContext(ctx);
+  for (const f of ['studio-lib.js', 'ai-studio-lib.js', 'ai-studio.js']) {
+    const src = f === 'studio-lib.js' ? 'window.OTBStudioLib = { skyAt: () => "night" };' : fs.readFileSync(path.join(PUB, f), 'utf8');
+    vm.runInContext(src, ctx, { filename: f });
+  }
+  return { els, page: els['ais-page'], main: els['hall-main'], calls, loc, store };
+}
+
+test('page: step 1 opens on an earlier request\'s files, carried by address, with Next', async () => {
+  const p = bootPage('?step=pick&from=1001');
+  await settle();
+  assert.match(p.page.innerHTML, /What are you starting from\?/);
+  assert.match(p.page.innerHTML, /hero-sketch\.png/);
+  assert.match(p.page.innerHTML, /mood-board\.pdf/);
+  assert.match(p.page.innerHTML, /3 files ready/);
+  assert.match(p.page.innerHTML, /1 Pick<\/span>/);
+  assert.equal(p.main.getAttribute('data-view'), 'pick');
+});
+
+test('page: step 3 sends the request on the card pressed, with copies of the carried files', async () => {
+  const p = bootPage('?step=make&from=1001');
+  await settle();
+  assert.match(p.page.innerHTML, /How do you want to pay\?/);
+  assert.match(p.page.innerHTML, /Gemini key ending 9c1d/);
+  assert.match(p.page.innerHTML, /Free here\. Google bills you for it directly\./);
+  assert.match(p.page.innerHTML, /Up to \$0\.50 is set aside, and the rest comes back\./);
+  assert.match(p.page.innerHTML, /\$12\.40 left/);
+  const ours = p.page.querySelectorAll('[data-pay]').find((b) => b.getAttribute('data-pay') === 'ours');
+  await ours.fire('click');
+  await settle();
+  const uploads = p.calls.filter((c) => c.method === 'POST' && c.url.endsWith('/ai-studio/uploads'));
+  assert.equal(uploads.length, 3, 'a file goes with one request only, so each carried file is uploaded again');
+  const sent = p.calls.find((c) => c.method === 'POST' && c.url.endsWith('/ai-studio/requests'));
+  assert.equal(sent.body.pay_with, 'ours');
+  assert.equal(JSON.stringify(sent.body.file_ids), JSON.stringify(['701', '702', '703']));
+  assert.equal(p.loc.search, '?request=1002', 'the request\'s own page opens');
+  assert.match(p.page.innerHTML, /usually done in about a minute/);
+  assert.equal(p.main.getAttribute('data-making'), 'on', 'the lamp is on while it runs');
+});
+
+test('page: the result shows the picture, the receipt, and makes it again with the CHANGED words', async () => {
+  const p = bootPage('?request=1001');
+  await settle();
+  const html = p.page.innerHTML;
+  assert.match(html, /class="ais-big" src="\/api\/bongos\/ai-studio\/files\/511"/);
+  assert.match(html, /lit it from the lamp<\/b>/);
+  assert.match(html, /Your request/);
+  assert.match(html, /Same 3 files, paid the same way\./);
+  assert.match(html, /Our 8%/);
+  assert.match(html, /\$0\.0421/);
+  assert.equal(p.main.getAttribute('data-view'), 'result');
+  const box = p.page.querySelector('#ais-again');
+  assert.match(box.value, /^Turn the sketch/, 'the box holds the request as it was sent');
+  box.value = 'Warmer lamp, pinker glow.';
+  await p.page.querySelector('#ais-remake').fire('click');
+  await settle();
+  const sent = p.calls.find((c) => c.method === 'POST' && c.url.endsWith('/ai-studio/requests'));
+  assert.equal(sent.body.prompt, 'Warmer lamp, pinker glow.');
+  assert.equal(sent.body.pay_with, 'ours', 'paid the same way');
+  assert.equal(sent.body.file_ids.length, 3);
+  const fetched = p.calls.filter((c) => c.method === 'FETCH').map((c) => c.url);
+  assert.deepEqual(fetched, ['/api/bongos/ai-studio/files/501', '/api/bongos/ai-studio/files/502', '/api/bongos/ai-studio/files/503'], 'only the uploads are copied, never the outputs');
+});
+
+test('page: "Change files" carries the request\'s files and the edited words into step 1', async () => {
+  const p = bootPage('?request=1004');
+  await settle();
+  assert.match(p.page.innerHTML, /your own Gemini key/);
+  p.page.querySelector('#ais-again').value = 'Same, but at dawn.';
+  await p.page.querySelector('#ais-change').fire('click');
+  await settle();
+  assert.equal(p.loc.search, '?step=pick');
+  assert.match(p.page.innerHTML, /3 files ready/);
+  const draft = JSON.parse(p.store.get('otb.ai-studio.draft'));
+  assert.equal(draft.prompt, 'Same, but at dawn.');
+});
+
+test('page: a failed run says why, shows no receipt, and keeps the request to try again', async () => {
+  const p = bootPage('?request=1003');
+  await settle();
+  assert.match(p.page.innerHTML, /did not answer in time\. You were not charged\./);
+  assert.doesNotMatch(p.page.innerHTML, /ais-receipt/);
+  assert.match(p.page.innerHTML, /Same file, paid the same way\./);
+});
+
+test('page: the balance shows what is left, the card charge before paying, and the month', async () => {
+  const p = bootPage('?view=balance');
+  await settle();
+  const html = p.page.innerHTML;
+  assert.match(html, /\$12\.40<\/span> <span class="ais-soft">left/);
+  assert.match(html, /Add how much\?/);
+  assert.match(html, /Test mode: no real money moves\./);
+  assert.match(html, /Money back from 1 failed request/);
+  assert.equal(p.page.querySelector('#ais-quote').textContent, '$20.00 lands in your balance; your card is charged $20.91.');
+  await p.page.querySelector('#ais-add').fire('click');
+  await settle();
+  const top = p.calls.find((c) => c.method === 'POST' && c.url.endsWith('/ai-studio/topup'));
+  assert.equal(JSON.stringify(top.body), JSON.stringify({ amount_usd: 20 })); // vm-born: compare through JSON
+});
+
+test('page: the module off says so, and calls nothing else', async () => {
+  const p = bootPage('?step=pick', { routes: { 'GET /api/bongos/ai-studio/status': { __status: 404, body: {} } } });
+  await settle();
+  assert.match(p.page.innerHTML, /not switched on for this project/);
+  assert.ok(!p.calls.some((c) => c.url.includes('/ai-studio/keys') || c.method === 'POST'));
+});
+
+// ---- 3. the walls -------------------------------------------------------------
+
+test('walls: the page writes through three routes only, and never asks for a key', () => {
+  const js = fs.readFileSync(path.join(PUB, 'ai-studio.js'), 'utf8');
+  const html = fs.readFileSync(path.join(PUB, 'ai-studio.html'), 'utf8');
+  const writes = [...js.matchAll(/api\.request\('(POST|PUT|PATCH|DELETE)',\s*([^,]+),/g)].map((m) => m[2].trim());
+  assert.ok(writes.length >= 3);
+  for (const w of writes) assert.match(w, /^WRITE_ROUTES\.(upload|request|topup)\(\)$/, `a write outside the allowlist: ${w}`);
+  const block = /const WRITE_ROUTES = Object\.freeze\(\{([\s\S]*?)\}\);/.exec(js)[1];
+  assert.deepEqual([...block.matchAll(/^\s*(\w+):/gm)].map((m) => m[1]), ['upload', 'request', 'topup']);
+  assert.doesNotMatch(js + html, /type="password"|ai-studio\/keys\/|\bkey:\s*[a-z]/i, 'a key is entered only in Settings');
+  assert.match(js, /\/builders\/settings#ai-keys/, 'the page points at Settings for a key');
+});
+
+test('walls: the studio home shows the AI door only where the module is on', () => {
+  const js = fs.readFileSync(path.join(PUB, 'studio.js'), 'utf8');
+  const html = fs.readFileSync(path.join(PUB, 'studio.html'), 'utf8');
+  assert.match(html, /<a class="st-action" id="st-ai" href="\/builders\/ai-studio" hidden>/);
+  assert.match(html, /<span class="st-action__label">Make something with AI<\/span>/);
+  assert.match(html, /id="st-ai-balance"[^>]*hidden/);
+  assert.match(js, /mods\.enabled\['ai-studio'\] !== true\) return;/, 'off by default: a missing flag hides the door');
+  assert.match(js, /loadAi\(\)\]/);
+});

package/tests/hall_page_gate_map.mjs

@@ -74,6 +74,9 @@ const ORACLE = {
   // task 1004321 (BV2.TW10): the tweak editor, on the studio's own tier. Its read
   // is any-builder like the .docx download; every write is the page holder's only.
   '/builders/tweak-editor': 'requireBuilderPage',
+  // task 1004921 (goal 1000136): the studio's AI pages, on the studio's tier.
+  // Every read and write behind it is the viewer's own (the ai-studio routes).
+  '/builders/ai-studio': 'requireBuilderPage',
   '/builders/ideas': 'requireBuilderPage',
   // THE ROOM (task 1004098 / BV2.R03) — a builder's own idea trail. Sign-in and
   // no rank floor, the tier /ideas sits on: there is no permission gate on

package/tests/hall_studio_home.mjs

@@ -129,7 +129,7 @@ function heldClock(h, m) {
   return Held;
 }
 
-function bootStudio({ answers = {}, signedIn = true, at = null, body = BODY, rank = 'metic', queue = null } = {}) {
+function bootStudio({ answers = {}, signedIn = true, at = null, body = BODY, rank = 'metic', queue = null, search = '' } = {}) {
   const root = augment(makeEl('body', {}));
   root.innerHTML = body;
   const byId = (id) => walk(root, (c) => (c.id === id ? c : null));
@@ -166,7 +166,7 @@ function bootStudio({ answers = {}, signedIn = true, at = null, body = BODY, ran
   const windowObj = {
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     BongosClient: { createClient: () => client },
-    location: { host: 'builders.cloudbongos.com', hostname: 'builders.cloudbongos.com', protocol: 'https:', search: '', pathname: '/studio', assign: (u) => { out.navigated = u; } },
+    location: { host: 'builders.cloudbongos.com', hostname: 'builders.cloudbongos.com', protocol: 'https:', search, pathname: '/studio', assign: (u) => { out.navigated = u; } },
     localStorage: { getItem: () => null, setItem() {} },
     addEventListener() {},
     scrollTo() {},
@@ -702,6 +702,65 @@ try {
     assert.match(down.el('st-panel-body').innerHTML, /could not be read just now/);
   });
 
+  await test('the full-page reader: a doc at ?note=N and the list at ?view=site, in place of the room, never a dialog', async () => {
+    const note = {
+      id: 31, page_title: 'Projects', page_id: 'site:projects', author_name: 'Ana', status: 'filed', submitted_at: day(1),
+      body_md: ['# Map', 'The labels <b>overlap</b>.', '- one', '- two', '![shot](/api/bongos/page-notes/images/4)', '![evil](https://example.com/x.png)'].join('\n'),
+    };
+    const s = bootStudio({ search: '?note=31', answers: { ...HOME, 'GET /page-notes/31': ok({ note, ideas: [{ id: 7, title: 'Fix the map' }] }) } });
+    await s.settle();
+    assert.equal(s.el('st-doc').hidden, false);
+    assert.ok(s.html.classList.contains('st-reading'), 'the room steps aside');
+    assert.equal(s.el('st-doc-title').textContent, 'Projects');
+    const b = s.el('st-doc-body').innerHTML;
+    assert.match(b, /Ana · /);
+    assert.match(b, /<h3>Map<\/h3>/);
+    assert.match(b, /<li>one<\/li><li>two<\/li>/);
+    assert.match(b, /The labels &lt;b&gt;overlap&lt;\/b&gt;/, 'the doc is escaped');
+    assert.match(b, /<img class="st-doc__img" src="\/api\/bongos\/page-notes\/images\/4"/, 'its own pictures are drawn');
+    assert.doesNotMatch(b, /<img[^>]*example\.com/, 'any other picture stays text');
+    assert.match(b, /It became 1 idea/);
+    assert.match(b, /href="\/#\/idea\/7"/);
+
+    const gone = bootStudio({ search: '?note=99', answers: HOME });
+    await gone.settle();
+    assert.match(gone.el('st-doc-body').innerHTML, /could not be opened/);
+
+    const rows = [{ id: 31, page_id: 'site:projects', page_path: '/projects', page_title: 'Projects', status: 'filed', idea_count: 2, submitted_at: day(1), author_name: 'Ana', excerpt: 'Map labels overlap.', link: '/builders/studio?note=31' }];
+    const list = bootStudio({ search: '?view=site', answers: { ...HOME, 'GET /page-notes/site': ok({ notes: rows }) } });
+    await list.settle();
+    assert.equal(list.el('st-doc-title').textContent, 'From the live site');
+    assert.match(list.el('st-doc-body').innerHTML, /st-doc-list__row" href="\/builders\/studio\?note=31"/);
+
+    const plain = bootStudio({ answers: HOME });
+    await plain.settle();
+    assert.equal(plain.el('st-doc').hidden, true, 'no link, no reader');
+    assert.ok(!plain.html.classList.contains('st-reading'));
+  });
+
+  await test('the overview: the two summary rows sit in the quiet Overview, the three things to do in the actions', () => {
+    const nc = HTML.replace(/<!--[\s\S]*?-->/g, '');
+    const actions = /<div class="st-actions">([\s\S]*?)\n        <\/div>/.exec(nc)[1];
+    const glance = /<div class="st-glance"[^>]*>([\s\S]*?)\n        <\/div>/.exec(nc)[1];
+    for (const id of ['st-resume', 'st-flow', 'studio-approvals']) assert.match(actions, new RegExp(`id="${id}"`), `${id} is an action`);
+    for (const id of ['st-status', 'st-site']) {
+      assert.match(glance, new RegExp(`id="${id}"`), `${id} is an overview row`);
+      assert.doesNotMatch(actions, new RegExp(`id="${id}"`), `${id} is not among the actions`);
+    }
+    const css = fs.readFileSync(new URL('../modules/hall-ui/public/studio.css', import.meta.url), 'utf8');
+    assert.match(css, /\.st-resume::after,\s*\.st-action::after \{/, 'Resume and the doors share the arrow');
+  });
+
+  await test('the reader stands in for the side sheet: craft-mode keeps it shut on the Studio, and a signed-out link says why', async () => {
+    const craft = fs.readFileSync(new URL('../modules/hall-ui/public/craft-mode.js', import.meta.url), 'utf8');
+    assert.match(craft, /getAttribute\('data-page'\) === 'studio'/);
+    assert.match(HTML, /<body[^>]*data-page="studio"/, 'the marker craft-mode reads is on the page');
+    const out = bootStudio({ search: '?note=31', signedIn: false, answers: {} });
+    await out.settle();
+    assert.match(out.el('st-doc-body').innerHTML, /Sign in to read page reviews/);
+    assert.equal(out.requests.some((r) => r.url.includes('/page-notes/')), false, 'nothing is asked for while signed out');
+  });
+
   await test('the markup: one h1 (the greeting), the tally and four doors, the libs before the page, the full-screen switch', () => {
     const nc = HTML.replace(/<!--[\s\S]*?-->/g, '');
     assert.equal((nc.match(/<h1\b/g) || []).length, 1);

package/tests/home_attention_cards.mjs

@@ -35,7 +35,7 @@ const STUBS = `
     return d ? { ok: true, status: 200, data: d } : { ok: false, status: 404, data: null };
   } }) };
   window.OTBKit = { esc: (s) => String(s), fmtAbsDate: () => 'Oct 1' };
-  window.OTBBlockersLib = { blockerFacts: (b) => ({ titleHtml: '<a class="ginbox__goal">' + b.title + '</a>', factsHtml: '', noteHtml: '' }) };
+  window.OTBBlockersLib = { blockerFacts: (b) => ({ titleHtml: '<a class="ginbox__goal">' + b.title + '</a>', factsHtml: '', noteHtml: '' }), humanKind: () => 'task' };
   window.OTB = {
     escapeHtml: (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;'),
     toast() {}, rankLabel: (r) => r,

package/tests/human_signal.mjs

@@ -0,0 +1,141 @@
+// tests/human_signal.mjs — HUMAN TASK / HUMAN DECISION, the one human signal
+// (task 1004922, owner 2026-10-28).
+//
+// Whatever waits on a person says so with a person, the same two words in the
+// hall (a badge drawn by hall-ask.js) and in every AI chat (a marker line the
+// Conductor teaches Claude and AGENTS.md/GEMINI.md teach every other model).
+// The two halves must say the same words, so this file holds them together.
+//
+// Run:  node tests/human_signal.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ask = require('../modules/hall-ui/public/hall-ask.js');
+const conductor = require('../.claude/hooks/conductor.js');
+const blockersLib = require('../modules/hall-ui/public/blockers-lib.js');
+const read = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); console.log(`  PASS  ${name}`); passed += 1; }
+  catch (e) { console.log(`  FAIL  ${name}\n        ${e.message}`); failed += 1; }
+}
+
+const TASK = '🙋 **HUMAN TASK:**';
+const DECISION = '🔀 **HUMAN DECISION:**';
+
+t('an ask card is a HUMAN DECISION unless told otherwise', () => {
+  const h = ask.html({ q: 'Let Ana join?', where: 'A goal', opts: [{ label: 'Let them in' }] });
+  assert.match(h, /hhuman--decision/);
+  assert.match(h, />HUMAN DECISION</);
+  assert.doesNotMatch(h, /HUMAN TASK/);
+  assert.match(h, /A goal/, 'the where line still reads beside the badge');
+});
+
+t('a card for something a person must DO is a HUMAN TASK', () => {
+  const h = ask.html({ q: 'Blocker', human: 'task', opts: [{ label: 'Resolve it' }] });
+  assert.match(h, /hhuman--task/);
+  assert.match(h, />HUMAN TASK</);
+  assert.doesNotMatch(h, /HUMAN DECISION/);
+});
+
+t('a card with no where line carries the badge on its own line, not as an eyebrow', () => {
+  const h = ask.html({ q: 'Blocker', human: 'task' });
+  assert.match(h, /class="hask__human"><span class="hhuman hhuman--task"/);
+  assert.doesNotMatch(h, /hask__where/, 'the Blockers page dropped its repeated eyebrow (task 1004824)');
+});
+
+t('human:false drops the badge and keeps the old dot', () => {
+  const h = ask.html({ q: 'x', where: 'w', human: false });
+  assert.doesNotMatch(h, /hhuman/);
+  assert.match(h, /hask__dot/);
+});
+
+t('an unknown kind draws nothing rather than a wrong signal', () => {
+  assert.equal(ask.human('maybe'), '');
+  assert.equal(ask.human(undefined), '');
+});
+
+t('the badge is a drawn person, never an emoji (voice V4)', () => {
+  for (const k of ['task', 'decision']) {
+    const b = ask.human(k);
+    assert.match(b, /<svg[^>]*aria-hidden="true"/);
+    assert.doesNotMatch(b, /\p{Extended_Pictographic}/u, `${k} badge carries an emoji`);
+  }
+});
+
+t('an Awaiting UAT row is a HUMAN TASK', () => {
+  assert.match(read('modules/hall-ui/public/criterion-uat-ui.js'), /awaiting_uat' && ask \? ask\.human\('task'\)/);
+});
+
+// task 1004946: a blocker's own stored ask says whether it is a task or a choice.
+// The six asks open on the live hub on 2026-10-28, cut to their option keys.
+const opts = (...keys) => ({ ask: { options: keys.map((key) => ({ key, label: key })) } });
+const LIVE = [
+  ['1000193 V2 or V3 or hold', opts('v2', 'v3', 'hold'), 'decision'],
+  ['1000194 bucket or copy or leave', opts('bucket', 'copy', 'none'), 'decision'],
+  ['1000195 set it up / not yet', opts('yes', 'later'), 'task'],
+  ['1000196 do it / not yet', opts('do', 'later'), 'task'],
+  ['1000197 restart / not yet', opts('yes', 'later'), 'task'],
+  ['1000198 scope or split', opts('scope', 'split'), 'decision'],
+];
+
+t('a blocker with two or more real options is a HUMAN DECISION; do-it-or-not-yet is a HUMAN TASK', () => {
+  for (const [name, b, want] of LIVE) assert.equal(blockersLib.humanKind(b), want, name);
+});
+
+t('a blocker with no ask, or only deferrals, is a HUMAN TASK', () => {
+  assert.equal(blockersLib.humanKind({}), 'task');
+  assert.equal(blockersLib.humanKind({ ask: null }), 'task');
+  assert.equal(blockersLib.humanKind(null), 'task');
+  assert.equal(blockersLib.humanKind(opts('do')), 'task');
+  assert.equal(blockersLib.humanKind(opts('later', 'not_yet', 'wait')), 'task');
+});
+
+t('the Blockers page and Home both ask the one rule, never their own', () => {
+  assert.match(read('modules/hall-ui/public/blockers.js'), /human: lib\.humanKind\(b\)/);
+  assert.match(read('modules/hall-ui/public/goal-inbox.js'), /human: lib\.humanKind\(b\),\s*\n\s*where: 'Waiting on the project owner'/);
+});
+
+t('the rendered blocker card wears the badge the rule picks', () => {
+  for (const [name, b, want] of LIVE) {
+    const h = ask.html({ q: name, human: blockersLib.humanKind(b) });
+    assert.match(h, new RegExp(`hhuman--${want}`), name);
+  }
+});
+
+t('the Conductor teaches both markers on a session\'s first prompt, and only then', () => {
+  const first = conductor.evaluateTriggers({ firstPrompt: true }).find((a) => a.id === 'human-signal');
+  assert.ok(first, 'no human-signal advisory on the first prompt');
+  assert.ok(first.text.includes(TASK) && first.text.includes(DECISION), first.text);
+  assert.ok(!conductor.evaluateTriggers({ firstPrompt: false }).some((a) => a.id === 'human-signal'));
+});
+
+t('the one-time human line does not count toward the block fingerprint, so prompt two is still a repeat', () => {
+  const first = conductor.evaluateTriggers({ firstPrompt: true, interaction: { inject: true, contract: 'P' } });
+  const second = conductor.evaluateTriggers({ firstPrompt: false, interaction: { inject: true, contract: 'P' } });
+  assert.equal(conductor.fingerprint(first), conductor.fingerprint(second));
+});
+
+t('an ask is a decision, so the ask-shape reminder wears the decision mark', () => {
+  const a = conductor.evaluateTriggers({ prompt: 'file a blocker' }).find((x) => x.id === 'ask-shape');
+  assert.equal(a.icon, '🔀');
+});
+
+t('every other model reads the same two markers', () => {
+  for (const f of ['AGENTS.md', 'GEMINI.md', 'docs/voice.md']) {
+    const s = read(f);
+    assert.ok(s.includes(TASK) || s.includes('`🙋 **HUMAN TASK:**`'), `${f} lacks the task marker`);
+    assert.ok(s.includes(DECISION), `${f} lacks the decision marker`);
+  }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exitCode = failed ? 1 : 0;

package/tests/install_script_reader.mjs

@@ -0,0 +1,51 @@
+// tests/install_script_reader.mjs
+//
+// task 1004924 — the one-line installers (/downloads/bongos/install.sh and
+// install.ps1) were read from disk and re-substituted on EVERY request, a sync
+// read blocking the event loop. src/bongos-downloads.js installScriptReader reads
+// and substitutes each once per process; serve-internal mounts the routes on it.
+//
+// Its own file, not tests/bongos_downloads.mjs: that file needs the host-only
+// config/bongos-cli.json and exits as HOST-TOPOLOGY-SKIP on the neutral core, so
+// a case added there never runs here or in core CI.
+//
+// Run:  node tests/install_script_reader.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { installScriptReader } = require('../src/bongos-downloads.js');
+const { test, summary } = makeRunner();
+
+await test('substitutes the pinned origin, and reads each script from disk once', () => {
+  const reads = [];
+  const read = installScriptReader({
+    readFile: (name) => { reads.push(name); return `BASE=__GDS_API_BASE__\nAGAIN=__GDS_API_BASE__/x\n# ${name}`; },
+    origin: 'https://hub.example',
+  });
+  for (let i = 0; i < 25; i++) {
+    assert.equal(read('bongos-install.sh'), 'BASE=https://hub.example\nAGAIN=https://hub.example/x\n# bongos-install.sh');
+    assert.match(read('bongos-install.ps1'), /^BASE=https:\/\/hub\.example\n/);
+  }
+  assert.deepEqual(reads, ['bongos-install.sh', 'bongos-install.ps1'], 'one disk read per script, not one per request');
+});
+
+await test('a missing script is null (the route 404s), and is not re-read either', () => {
+  let n = 0;
+  const read = installScriptReader({ readFile: () => { n++; throw Object.assign(new Error('nope'), { code: 'ENOENT' }); }, origin: 'https://o' });
+  assert.equal(read('bongos-install.sh'), null);
+  assert.equal(read('bongos-install.sh'), null);
+  assert.equal(n, 1);
+});
+
+await test('serve-internal mounts the installer routes on the memoised reader', () => {
+  const src = readFileSync(new URL('../src/bongos/serve-internal.js', import.meta.url), 'utf8');
+  assert.match(src, /const readBongosInstallScript = installScriptReader\(\{/);
+  assert.doesNotMatch(src, /\.split\('__GDS_API_BASE__'\)/, 'no per-request read + split left in the route file');
+  assert.equal((src.match(/readBongosInstallScript\('bongos-install\.(sh|ps1)'\)/g) || []).length, 2, 'both installer routes use it');
+});
+
+summary();