@bongos/core 1.24.95 → 1.24.96

package/modules/hall-ui/records/home-runner.md

@@ -0,0 +1,19 @@
+# Your runner on Home's towers — send it, see it, recall it (task 1005243, goal 1000142)
+
+Covers: `home-runner.js` (new), the tower pick and runner marker in `home-city-draw.js` / `home-city.css`, the visor's card (`visor.js` `OTBVisor.focus`, `visor.css` `.visor__focus*`), and the read `GET /api/bongos/autonomy/me/goals/:goalId/stats` (`modules/autonomy`). Game mode only.
+
+## What it settled
+
+- **The owner's brief (2026-11-12):** putting your Autobongos runner to work should feel like putting a builder on a building in a base-building game, and stay uncluttered. In game mode you tap a tower on Home (a tower is a goal), the visor offers **Send runner here**, and the tower then carries your runner. Tap it again for what it has done there and **Recall runner**.
+- **One tower at a time (owner, 2026-11-12).** Sending sets your goal picks to that one goal (`PUT /autonomy/me/goals`) and switches on any of your devices that are stopped (`POST /autonomy/runners/:host/run`). Recall switches them off and leaves the pick. Several picks made in Settings are "working on several goals": no tower carries the marker until you send it somewhere.
+- **ADR 0403 kept:** the scene only gets picked (the tower is lit and edged in the accent); the words and the one button are the visor's. `OTBVisor.focus({ title, status, lines, lead: { label, run }, onClose })` is the general mechanism: a scene's pick puts a small card on the glass and its action takes the accent button; Escape (or the card's Esc mark, or a tap on open ground) closes it before the options menu sees the press, and the character's own main action comes back. This answers ADR 0403 §4's open question for one action.
+- **Who sees it:** only a viewer the server says may run a runner (`GET /autonomy/fence` → `scope.may_run`, the `autonomy.run` atom). Signed out, without the atom, or in classic mode a tower stays the plain link to its goal and nothing is new.
+- **The marker** is the agent's robot face in the accent colour (yours, not anyone's agent), ringed by its state: working (accent ring that turns, CSS only, stilled by the hall's reduced-motion rule), starting, resting (dotted info ring), ready (soft ring), recalled (faded). It replaces the agent face `/home/city` would draw on that tower. Tapping it picks its tower.
+- **The numbers are the ledger's**, never the runner's own report: tasks the caller's runner shipped in that goal (`claims.autonomous` + outcome `shipped`), the tokens their sessions took (`session_records.total_tokens`), their average length, and the goal's `ready`/`active` tasks. Time left is that count × the average and is shown only when there is an average ("about 3 h"); with no runner history there it promises no time. The device's face (Running, Resting until 12:31 · 42 min, Device is off…) is `runner-button.js` `buttonState`, the same decision the Settings card draws.
+- **Not yet:** the percent of your Claude usage limit. That number lives only on the runner's PC; task 1005244 has the runner report it in its check-in.
+
+## Looking at it
+
+`hall-preview-fixture` in `.claude/launch.json` (port 4602, `--fixture-me`; the plain preview borrows the live `/me`, whose character may not be the Artisan). Set `localStorage hall-game=on`, `OTBCraftMode.setCharacter('artisan')`, and edit `autonomy__fence.json` / `autonomy__runners.json` to a project that allows goals (the checked-in fence has the switch off and no goals, which renders "Closed to runners" — a real state). The harness reads fixtures per request, so `OTBHomeRunner.refresh()` picks a change up without a restart. Fixtures added: `autonomy__me__goals__stats.json`, `autonomy__me__goals.put.json`.
+
+Tests: `tests/home_runner.mjs` (the card and marker decisions, run for real), `tests/autonomy_runner_goal_stats.mjs` (the read and route), `tests/hall_visor.mjs` (the card on the glass, its button, Escape order).

package/modules/hall-ui/records/visor.md

@@ -42,6 +42,10 @@ The glass was redrawn to the owner's mock-up "Cloud city: in the visor, minimal"
 - **Scenes.** The top arc, the notch and the place sit inside the top 64px (`--visor-arc`; the segments under them take the inset to 88px, `--visor-inset-top`), so no scene's top row is struck through. Home no longer shifts its greeting row left (there is no pill top-right to clear). The city's door rises above the foot row at every width, because the accent button is centred where the door stood. The sky's `visor-on` offsets are unchanged.
 - **Looking at it.** The stand-in scene in `tests/hall_visor.mjs` over the hall's real sheets; put a bright gradient behind it to check midday.
 
+## A scene's pick on the glass (task 1005243)
+
+`OTBVisor.focus({ key, title, status: { text, tone }, lines, lead: { label, run }, onClose })` puts a small card above the accent button (the night panel between two strong hairlines, like the sheet) and hands `lead` the accent button while it is up; `focus(null)` takes both away. Escape closes it in capture before the options menu, but never while the sheet is open. First user: Home's towers and your runner (`records/home-runner.md`).
+
 ## What it settled (task 1005148)
 
 - **The first look (2026-11-10, five mock-up rounds; replaced by the minimal visor above).** A quiet layout with "hairline instruments" from the helmet round: thin curved visor lines across the top, bottom and both sides, a small centre cross, and a compass of nine slanted cells along the top line with the one salmon marker under its centre. No tracker or radar (tried and dropped), no clipped corners: the pills stay round (DESIGN.md "pill or nothing"). No glow (DESIGN.md's rejected near-black-plus-neon HUD). The frame is one SVG in a 1000×1000 box stretched over the stage with non-scaling strokes, so it is a hairline at every size.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.95",
+  "version": "1.24.96",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.24.95",
+      "version": "1.24.96",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.95",
+  "version": "1.24.96",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -11683,5 +11683,11 @@
       "id": "1005218",
       "text": "The three characters have a new look: space-faring aliens made of two animals each, drawn at a larger size. Each has its own colour, and in the game the visor now takes your character's colour and shows your character wearing"
     }
+  ],
+  "1.24.96": [
+    {
+      "id": "1005243",
+      "text": "In game mode, tap a goal tower on Home to send your Autobongos runner there with one visor button; the tower then shows your runner at work, and tapping it shows tasks done, tokens used, time left and a Recall button."
+    }
   ]
 }

package/scripts/hall-preview/server.js

@@ -112,6 +112,8 @@ let liveWhy = null;
 // me__recent-ships.json. Query strings are ignored when matching. Id-bearing
 // paths fall back to the generic names below so one fixture serves any id.
 const FIXTURE_FALLBACKS = [
+  // Home's runner card (task 1005243): one goal's runner numbers, the same for every goal
+  [/^autonomy\/me\/goals\/\d+\/stats$/, 'autonomy__me__goals__stats'],
   [/^goals\/\d+\/conflicts$/, 'goals__conflicts'],
   [/^goals\/\d+\/dependency-forest$/, 'goals__dependency-forest'],
   [/^goals\/\d+\/requests$/, 'goals__requests'],
@@ -221,6 +223,8 @@ const CANNED_WRITES = [
   ['POST', /^auth\/runner-code\/issue$/, 'auth__runner-code__issue.post'],
   ['POST', /^me\/sessions\/revoke$/, 'me__sessions__revoke.post'],
   ['DELETE', /^autonomy\/runners\/[^/]+$/, 'autonomy__runners.delete'],
+  // Home's runner card (task 1005243): Send runner here writes the one pick.
+  ['PUT', /^autonomy\/me\/goals$/, 'autonomy__me__goals.put'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.95'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.96'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/autonomy_runner_goal_stats.mjs

@@ -0,0 +1,92 @@
+// tests/autonomy_runner_goal_stats.mjs — one goal, seen from the caller's runner
+// (task 1005243): the numbers the game's runner card on Home shows.
+//
+// The route is driven as a REAL request through the assembled router with only the
+// auth gates stubbed, and the SQL against a stubbed pool (the
+// autonomy_builder_scope precedent). DB-free, no network.
+// Run:  node --test tests/autonomy_runner_goal_stats.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const req = createRequire(import.meta.url);
+const express = req('express');
+const { attachFail } = req(path.join(ROOT, 'src/bongos/middleware/error-envelope.js'));
+const api = req(path.join(ROOT, 'src/module-api.js'));
+const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+
+const permStub = (key) => { const mw = (_q, _s, next) => next(); mw.permKey = key; return mw; };
+const passBuilder = (q, _s, next) => { q.builder = { id: 7, rank: 'metic' }; next(); };
+
+function router() {
+  const saved = { b: api.requireBuilder, p: api.requirePermission };
+  api.requireBuilder = passBuilder;
+  api.requirePermission = permStub;
+  const p = req.resolve(path.join(ROOT, 'modules/autonomy/routes/autonomy.js'));
+  delete req.cache[p];
+  try { return req(p)(); } finally { api.requireBuilder = saved.b; api.requirePermission = saved.p; }
+}
+async function serve(r) {
+  const app = express();
+  app.use(express.json()); app.use(attachFail); app.use(r);
+  const server = app.listen(0);
+  await new Promise((ok) => server.once('listening', ok));
+  return { base: `http://127.0.0.1:${server.address().port}`, close: () => server.close() };
+}
+async function withPool(answer, fn) {
+  const saved = api.pool.query;
+  const calls = [];
+  api.pool.query = async (sql, params) => { calls.push({ sql, params }); return answer(sql, params); };
+  try { return await fn(calls); } finally { api.pool.query = saved; }
+}
+
+test('the read counts only the caller\'s RUNNER claims that shipped in that goal, and their sessions\' tokens', async () => {
+  await withPool(() => ({ rows: [{ tasks_done: 7, tokens: '4820000', avg_s: '2280.4', tasks_left: 5 }] }), async (calls) => {
+    const out = await db.readRunnerGoalStats(7, 1000090);
+    assert.deepEqual(out, { tasks_done: 7, tokens: 4820000, avg_task_seconds: 2280, tasks_left: 5 });
+    const { sql, params } = calls[0];
+    assert.deepEqual(params, [7, 1000090], 'scoped to the caller and the goal');
+    assert.match(sql, /c\.autonomous/, 'a runner\'s claim, not a person\'s');
+    assert.match(sql, /c\.outcome = 'shipped'/, 'shipped, by the ledger');
+    assert.match(sql, /sr\.builder_id = \$1/, 'only the caller\'s sessions');
+    assert.match(sql, /status IN \('ready', 'active'\)/, 'what is left is what a runner could still take');
+  });
+});
+
+test('a goal not opened to runners tells no count of what is left', async () => {
+  await withPool(() => ({ rows: [{ tasks_done: 0, tokens: '0', avg_s: null, tasks_left: null }] }), async () => {
+    assert.equal((await db.readRunnerGoalStats(7, 9)).tasks_left, null);
+  });
+});
+
+test('nothing done yet reads as zeros and no average, never a made-up pace', async () => {
+  await withPool(() => ({ rows: [{ tasks_done: 0, tokens: '0', avg_s: null, tasks_left: 3 }] }), async () => {
+    assert.deepEqual(await db.readRunnerGoalStats(7, 1), { tasks_done: 0, tokens: 0, avg_task_seconds: null, tasks_left: 3 });
+  });
+});
+
+test('GET /autonomy/me/goals/:id/stats: behind autonomy.run, the caller\'s own, a bad id refused', async () => {
+  const r = router();
+  const layer = r.stack.find((l) => l.route && l.route.path === '/autonomy/me/goals/:goalId/stats' && l.route.methods.get);
+  assert.ok(layer, 'the route is registered');
+  assert.deepEqual(layer.route.stack.map((s) => s.handle.permKey).filter(Boolean), ['autonomy.run']);
+  const s = await serve(r);
+  try {
+    await withPool(() => ({ rows: [{ tasks_done: 2, tokens: 1000, avg_s: 600, tasks_left: 1 }] }), async (calls) => {
+      const ok = await fetch(`${s.base}/autonomy/me/goals/1000090/stats`);
+      assert.equal(ok.status, 200);
+      assert.deepEqual(await ok.json(), { goal_id: 1000090, tasks_done: 2, tokens: 1000, avg_task_seconds: 600, tasks_left: 1 });
+      assert.deepEqual(calls[0].params, [7, 1000090], 'keyed by the session\'s builder, never the request');
+      const bad = await fetch(`${s.base}/autonomy/me/goals/abc/stats`);
+      assert.equal(bad.status, 400);
+    });
+    await withPool(() => { throw new Error('db down'); }, async () => {
+      const down = await fetch(`${s.base}/autonomy/me/goals/5/stats`);
+      assert.equal(down.status, 503);
+    });
+  } finally { s.close(); }
+});

package/tests/hall_visor.mjs

@@ -271,6 +271,26 @@ test('Escape closes one layer, top first: the sheet, then the scene\'s pick, the
   await ctx.close();
 });
 
+test('a scene\'s pick: the card is on the glass, its action takes the accent button, Escape closes it first (task 1005243)', { skip }, async () => {
+  const { ctx, page, errors } = await open();
+  await page.evaluate(() => OTBVisor.focus({ key: 'runner:2', title: 'Area 2', status: { text: 'Running', tone: 'ok' }, lines: ['7 tasks done here'],
+    lead: { label: 'Recall runner', run() { window.led = (window.led || 0) + 1; } }, onClose() { window.unpicked = true; } }));
+  const g = await page.evaluate(() => ({
+    title: document.querySelector('.visor__focus-title').textContent,
+    status: document.querySelector('.visor__focus-status').textContent,
+    main: document.querySelector('.visor__main').textContent,
+    takes: getComputedStyle(document.querySelector('.visor__focus')).pointerEvents,
+  }));
+  assert.deepEqual(g, { title: 'Area 2', status: 'Running', main: 'Recall runner', takes: 'auto' });
+  await page.click('[data-visor-lead]');
+  assert.equal(await page.evaluate(() => window.led), 1, 'the accent button runs the scene\'s action');
+  await page.keyboard.press('Escape');
+  const s = await page.evaluate(() => ({ focus: OTBVisor.focused(), unpicked: window.unpicked, picked: window.picked, menu: window.optionsOpened, main: document.querySelector('.visor__main').textContent }));
+  assert.deepEqual(s, { focus: null, unpicked: true, picked: true, menu: 0, main: 'Goal skyG' }, 'the card took the press; the character\'s own button is back');
+  assert.deepEqual(errors, []);
+  await ctx.close();
+});
+
 test('a lead scene action is the first key hint, and its click and its key run it (task 1005209)', { skip }, async () => {
   const { ctx, page, errors } = await open();
   await page.evaluate(() => OTBVisor.scene({ name: 'test', place: 'Test city', actions: [{ label: 'Decide 2 in a row', key: 'd', bind: true, lead: true, run() { window.decided = (window.decided || 0) + 1; } }] }));

package/tests/home_runner.mjs

@@ -0,0 +1,115 @@
+// tests/home_runner.mjs — your Autobongos runner on Home's city (task 1005243).
+//
+// The decision is pure (home-runner.js cardFor / stateOf), so it runs here for
+// real against the same runner-button.js the Settings card draws from. The page
+// wiring is pinned by its source: the scene paints the pick, every button is the
+// visor's (ADR 0403), and only a viewer the server says may run gets any of it.
+// Run:  node --test tests/home_runner.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const require = createRequire(import.meta.url);
+const R = require(path.join(HALL, 'home-runner.js'));
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+
+const NOW = Date.parse('2026-11-12T10:00:00Z');
+const seen = new Date(NOW - 20000).toISOString();
+const fenceOf = (picks, allowed = [1, 2, 3], extra = {}) => ({ enabled: true, goals: picks, scope: { may_run: true, goals: picks }, project: { enabled: true, goals: allowed }, ...extra });
+const dev = (o = {}) => ({ host: 'pc', run_requested: true, run_changed_at: new Date(NOW - 3600e3).toISOString(), last_seen_at: seen, health: { state: 'alive', workingTaskId: null }, ...o });
+const STATS = { tasks_done: 7, tokens: 4820000, avg_task_seconds: 2280, tasks_left: 5 };
+const card = (o) => R.cardFor({ goal: { id: 2, title: 'Area 2' }, nowMs: NOW, titleOf: (g) => `Area ${g}`, stats: STATS, ...o });
+
+test('no permission to run, or no fence read: no card, the tower stays a link', () => {
+  assert.equal(card({ runners: [dev()], fence: null }), null);
+  assert.equal(card({ runners: [dev()], fence: { ...fenceOf([]), scope: { may_run: false, goals: [] } } }), null);
+});
+
+test('no runner set up yet: the card offers setting one up', () => {
+  const c = card({ runners: [], fence: fenceOf([]) });
+  assert.equal(c.lead.act, 'setup');
+  assert.equal(c.status.text, 'No runner yet');
+});
+
+test('a goal the project has not opened to runners: no send, only the goal', () => {
+  const c = card({ runners: [dev()], fence: fenceOf([], [1, 3]) });
+  assert.equal(c.lead.act, 'open');
+  assert.match(c.lines[0], /not opened this goal to runners/);
+});
+
+test('your runner is elsewhere or resting: Send runner here, with what it did here and what is left', () => {
+  const away = card({ runners: [dev()], fence: fenceOf([1]) });
+  assert.deepEqual(away.lead, { label: 'Send runner here', act: 'send' });
+  assert.equal(away.status.text, 'Your runner is at Area 1');
+  assert.deepEqual(away.lines, ['7 tasks done here · 4.8M tokens', '5 tasks ready · about 3 h for your runner']);
+  const off = card({ runners: [dev({ run_requested: false })], fence: fenceOf([]) });
+  assert.equal(off.status.text, 'Your runner is resting');
+  assert.equal(off.lead.act, 'send');
+});
+
+test('your runner is here and on: its device face, the numbers, and Recall runner', () => {
+  const work = card({ runners: [dev({ health: { state: 'alive', workingTaskId: '9' } })], fence: fenceOf([2]) });
+  assert.deepEqual(work.lead, { label: 'Recall runner', act: 'recall' });
+  assert.deepEqual([work.status.text, work.status.tone], ['Running', 'ok']);
+  assert.equal(work.lines[0], 'Working on task 9.');
+  const rest = card({ runners: [dev({ health: { state: 'alive', workingTaskId: null, holdUntil: new Date(NOW + 42 * 60e3).toISOString() } })], fence: fenceOf([2]) });
+  assert.match(rest.status.text, /^Resting until .+ · 42 min$/);
+  assert.equal(rest.lead.act, 'recall');
+});
+
+test('recalled here: it says so and offers to send it back', () => {
+  const c = card({ runners: [dev({ run_requested: false })], fence: fenceOf([2]) });
+  assert.equal(c.status.text, 'Recalled');
+  assert.equal(c.lead.act, 'send');
+});
+
+test('nothing done yet: no invented numbers; nothing ready: says so', () => {
+  const c = card({ runners: [dev()], fence: fenceOf([1]), stats: { tasks_done: 0, tokens: 0, avg_task_seconds: null, tasks_left: 0 } });
+  assert.deepEqual(c.lines, ['Nothing ready to build here right now.']);
+  const noPace = card({ runners: [dev()], fence: fenceOf([1]), stats: { tasks_done: 0, tokens: 0, avg_task_seconds: null, tasks_left: 4 } });
+  assert.deepEqual(noPace.lines, ['4 tasks ready'], 'no time is promised without a pace to measure it by');
+});
+
+test('the marker\'s state follows the device; several picks are not one tower', () => {
+  assert.equal(R.stateOf({ runners: [dev({ health: { state: 'alive', workingTaskId: '9' } })], fence: fenceOf([2]), nowMs: NOW }), 'working');
+  assert.equal(R.stateOf({ runners: [dev({ run_requested: false })], fence: fenceOf([2]), nowMs: NOW }), 'off');
+  assert.equal(R.stateOf({ runners: [dev({ health: { state: 'alive', holdUntil: new Date(NOW + 60e3).toISOString() } })], fence: fenceOf([2]), nowMs: NOW }), 'resting');
+  assert.equal(R.assignedGoal(fenceOf([2])), '2');
+  assert.equal(R.assignedGoal(fenceOf([1, 2])), null);
+});
+
+test('numbers read like a person would say them', () => {
+  assert.equal(R.tokensText(4820000), '4.8M tokens');
+  assert.equal(R.tokensText(340400), '340k tokens');
+  assert.equal(R.aboutText(5 * 2280), 'about 3 h');
+  assert.equal(R.aboutText(1200), 'about 20 min');
+  assert.equal(R.aboutText(3 * 86400), 'about 3 days');
+  assert.equal(R.aboutText(0), '');
+});
+
+test('source: the scene paints the pick, the visor holds every button (ADR 0403), the writes are Settings\' routes', () => {
+  const src = read('home-runner.js');
+  assert.match(src, /OTBVisor\.focus/, 'the card and its button are the visor\'s');
+  assert.doesNotMatch(src, /createElement\(['"]button/, 'no button is drawn in the scene');
+  assert.match(src, /scope\.may_run === true/, 'only a viewer the server says may run');
+  assert.match(src, /dataset\.game === 'on'/, 'game mode only: in classic a tower stays a link');
+  for (const route of ["'PUT', '/autonomy/me/goals'", '/autonomy/runners/${encodeURIComponent(r.host)}/run', '/autonomy/me/goals/${encodeURIComponent(picked)}/stats']) assert.ok(src.includes(route), route);
+  const draw = read('home-city-draw.js');
+  assert.match(draw, /'data-goal': a\.id/, 'every tower names its goal');
+  assert.match(draw, /hc-tower--picked/);
+  const html = read('index.html');
+  const at = (f) => html.indexOf(`/builders/${f}`);
+  assert.ok(at('runner-button.js') > 0 && at('runner-button.js') < at('home-runner.js') && at('home-runner.js') < at('home-city.js'), 'runner-button.js, then home-runner.js, before home-city.js');
+});
+
+test('source: the marker moves only in CSS, and the hall\'s reduced-motion rule stills it', () => {
+  const css = read('home-city.css');
+  assert.match(css, /\.hc-runner--working \.hc-runner__ring \{[^}]*animation: hc-turn/);
+  assert.doesNotMatch(read('home-runner.js'), /requestAnimationFrame|setInterval/, 'no motion in script');
+});