@bongos/core 1.20.79 → 1.20.81

package/tests/autonomy_builder_scope.mjs

@@ -0,0 +1,474 @@
+// tests/autonomy_builder_scope.mjs — each builder's own runner scope, and the
+// project-level runner permissions (task 1004501).
+//
+// Owner ruling, 2026-10-01: every builder picks which work THEIR runner takes; a
+// builder who has picked nothing gets NO autonomous work; who may run a runner at
+// all is a project permission (`autonomy.run`); and the owner can pause one
+// builder's runner without throwing the master switch. The server composes all of
+// it into the fence the runner reads, so the runner stays dumb and cannot widen
+// its own fence.
+//
+// The pure composition is driven directly; the routes are driven as REAL requests
+// through the assembled router with only the auth gates stubbed (the
+// autonomy_fence_priority precedent); the SQL runs against a stubbed pool.
+//
+// DB-free, no network. Run:  node --test tests/autonomy_builder_scope.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 req = createRequire(import.meta.url);
+const express = req('express');
+const { attachFail } = req(path.join(ROOT, 'src/bongos/middleware/error-envelope.js'));
+const fence = req(path.join(ROOT, 'modules/autonomy/fence.js'));
+const cadence = req(path.join(ROOT, 'modules/autonomy/cadence.js'));
+
+const PROJECT = Object.freeze({
+  enabled: true, paused_reason: null, priority_goal_id: 1000118,
+  updated_at: '2026-10-01T09:53:08.874Z', updated_by: '3',
+  goals: [{ goal_id: 1000118, note: 'bug squash' }, { goal_id: 1000090, note: null }],
+});
+
+// ── the pure composition ─────────────────────────────────────────────────────
+
+test('picks NARROW the project allowlist and can never add to it', () => {
+  const f = fence.effectiveFence({ project: PROJECT, scope: { goals: [1000090, 4242] }, mayRun: true });
+  assert.equal(f.enabled, true);
+  assert.deepEqual(f.goals.map((g) => g.goal_id), [1000090], 'a picked goal the project does not allow is dropped');
+  assert.equal(f.priority_goal_id, null, 'the priority is not in the picks, so there is none');
+  assert.deepEqual(f.project, PROJECT, 'the owner page still gets the unnarrowed fence');
+});
+
+test('a builder who has picked nothing gets NO goals (owner ruling), never the whole allowlist', () => {
+  for (const scope of [null, { goals: [] }]) {
+    const f = fence.effectiveFence({ project: PROJECT, scope, mayRun: true });
+    assert.deepEqual(f.goals, [], `scope=${JSON.stringify(scope)}`);
+    const d = fence.decideRun({ fence: f, graderBypassed: false });
+    assert.equal(d.go, false);
+    assert.equal(d.code, 'no_builder_scope');
+    assert.match(d.reason, /Settings/, 'the runner log says where to fix it');
+  }
+});
+
+test('the three stops win in the order an operator asks "why is it idle"', () => {
+  const off = fence.effectiveFence({ project: { ...PROJECT, enabled: false, paused_reason: 'night off' }, scope: { goals: [1000118], owner_paused: true }, mayRun: false });
+  assert.equal(off.stop_code, 'kill_switch', 'the project switch stops everyone first');
+  assert.equal(fence.decideRun({ fence: off, graderBypassed: false }).code, 'kill_switch');
+
+  const noPerm = fence.effectiveFence({ project: PROJECT, scope: { goals: [1000118], owner_paused: true }, mayRun: false });
+  assert.equal(noPerm.enabled, false);
+  assert.equal(noPerm.stop_code, 'not_permitted', 'then whether this builder may run at all');
+  assert.equal(fence.decideRun({ fence: noPerm, graderBypassed: false }).code, 'not_permitted');
+
+  const paused = fence.effectiveFence({ project: PROJECT, scope: { goals: [1000118], owner_paused: true, owner_paused_reason: 'too many PRs' }, mayRun: true });
+  assert.equal(paused.stop_code, 'builder_paused', 'then the owner’s pause on this builder');
+  const d = fence.decideRun({ fence: paused, graderBypassed: false });
+  assert.equal(d.code, 'builder_paused');
+  assert.match(d.reason, /too many PRs/);
+});
+
+test('anything but an explicit true for autonomy.run refuses', () => {
+  for (const mayRun of [undefined, null, 'true', 1]) {
+    assert.equal(fence.effectiveFence({ project: PROJECT, scope: { goals: [1000118] }, mayRun }).enabled, false, String(mayRun));
+  }
+});
+
+test('a permitted, unpaused builder with picks gets exactly their picks, priority first', () => {
+  const f = fence.effectiveFence({ project: PROJECT, scope: { goals: [1000090, 1000118] }, mayRun: true });
+  const d = fence.decideRun({ fence: f, graderBypassed: false });
+  assert.equal(d.go, true);
+  assert.deepEqual(d.goals, [1000118, 1000090]);
+  assert.equal(d.priorityGoal, 1000118);
+});
+
+test('a pick or a pause moves updated_at, so it wakes a runner waiting on the fence', () => {
+  const later = '2026-10-02T00:00:00.000Z';
+  assert.equal(fence.effectiveFence({ project: PROJECT, scope: { goals: [], updated_at: later }, mayRun: true }).updated_at, later);
+  assert.equal(fence.effectiveFence({ project: PROJECT, scope: null, mayRun: true }).updated_at, new Date(PROJECT.updated_at).toISOString());
+});
+
+test('an unreadable project fence stays unreadable', () => {
+  assert.equal(fence.effectiveFence({ project: null, scope: { goals: [1] }, mayRun: true }), null);
+});
+
+test('a fence from a server that predates the split still reads as the kill switch', () => {
+  const d = fence.decideRun({ fence: { enabled: false, paused_reason: 'x', goals: [] }, graderBypassed: false });
+  assert.equal(d.code, 'kill_switch');
+  const odd = fence.decideRun({ fence: { enabled: false, stop_code: 'something_new', goals: [] }, graderBypassed: false });
+  assert.equal(odd.code, 'kill_switch', 'an unknown stop code is never a way to open the fence');
+});
+
+test('cadence treats a per-builder stop like the kill switch: stopped, not a fault', () => {
+  for (const code of ['builder_paused', 'not_permitted']) {
+    assert.equal(cadence.classifyEvent({ event: 'fenced', code, reason: 'r' }).class, 'stopped', code);
+  }
+  assert.equal(cadence.classifyEvent({ event: 'fenced', code: 'no_builder_scope', reason: 'r' }).class, 'quiet');
+});
+
+// ── the routes ───────────────────────────────────────────────────────────────
+
+const permStub = (key) => {
+  const mw = (_req, _res, next) => next();
+  mw.permKey = key;
+  return mw;
+};
+// The session fold (task 1002556) rides requireBuilder as req.rawPermissionKeys;
+// null = the session row did not carry it. Mutable so one test can drive both.
+let sessionKeys = null;
+const passBuilder = (reqq, _res, next) => { reqq.builder = { id: 7, rank: 'metic' }; reqq.rawPermissionKeys = sessionKeys; next(); };
+
+function autonomyRouter() {
+  const api = req(path.join(ROOT, 'src/module-api.js'));
+  const saved = { b: api.requireBuilder, p: api.requirePermission };
+  api.requireBuilder = passBuilder;
+  api.requirePermission = permStub;
+  const routePath = req.resolve(path.join(ROOT, 'modules/autonomy/routes/autonomy.js'));
+  delete req.cache[routePath];
+  try {
+    return req(routePath)();
+  } finally {
+    api.requireBuilder = saved.b;
+    api.requirePermission = saved.p;
+  }
+}
+
+async function serve(router) {
+  const app = express();
+  app.use(express.json());
+  app.use(attachFail);
+  app.use(router);
+  const server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  return { base: `http://127.0.0.1:${server.address().port}`, close: () => server.close() };
+}
+
+const send = (base, method, p, body) => fetch(`${base}${p}`, {
+  method, headers: { 'content-type': 'application/json' }, body: body === undefined ? undefined : JSON.stringify(body),
+});
+
+function gateOf(router, p, method) {
+  const layer = router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]);
+  assert.ok(layer, `${method.toUpperCase()} ${p} is registered`);
+  return layer.route.stack.map((s) => s.handle.permKey).filter(Boolean);
+}
+
+test('the gates: picks behind autonomy.run, the pause and the owner view behind the owner-only atom', () => {
+  const router = autonomyRouter();
+  assert.deepEqual(gateOf(router, '/autonomy/me/goals', 'put'), ['autonomy.run']);
+  assert.deepEqual(gateOf(router, '/autonomy/builders/:builderId/pause', 'post'), ['autonomy.fence.manage']);
+  assert.deepEqual(gateOf(router, '/autonomy/runners/all', 'get'), ['autonomy.fence.manage']);
+  assert.deepEqual(gateOf(router, '/autonomy/fence', 'get'), [], 'the fence read stays any-builder: a runner must always learn it should stop');
+});
+
+test('GET /autonomy/fence answers with the CALLER’s fence, asking the permission of the government port', async () => {
+  const api = req(path.join(ROOT, 'src/module-api.js'));
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = { rf: db.readFence, rs: db.readBuilderScope, ro: api.resolveOptional };
+  const asked = [];
+  let holds = true;
+  db.readFence = async () => PROJECT;
+  db.readBuilderScope = async (id) => { asked.push(['scope', id]); return { goals: [1000090], owner_paused: false, updated_at: null }; };
+  api.resolveOptional = (name) => (name === 'government'
+    ? { builderHasPermissions: async (id, keys) => { asked.push(['perm', id, keys]); return holds; } }
+    : saved.ro(name));
+  const s = await serve(autonomyRouter());
+  try {
+    let r = await send(s.base, 'GET', '/autonomy/fence');
+    assert.equal(r.status, 200);
+    let body = await r.json();
+    assert.equal(body.enabled, true);
+    assert.deepEqual(body.goals.map((g) => g.goal_id), [1000090]);
+    assert.equal(body.project.goals.length, 2);
+    assert.deepEqual(asked, [['scope', 7], ['perm', 7, ['autonomy.run']]], 'scope and permission are the SESSION builder’s');
+
+    holds = false;
+    body = await (await send(s.base, 'GET', '/autonomy/fence')).json();
+    assert.equal(body.enabled, false);
+    assert.equal(body.stop_code, 'not_permitted');
+
+    api.resolveOptional = () => ({ builderHasPermissions: async () => { throw new Error('resolver down'); } });
+    body = await (await send(s.base, 'GET', '/autonomy/fence')).json();
+    assert.equal(body.enabled, false, 'a resolver that throws turns the fence OFF, never on');
+
+    api.resolveOptional = () => null;
+    body = await (await send(s.base, 'GET', '/autonomy/fence')).json();
+    assert.equal(body.enabled, false, 'no government port: off');
+  } finally {
+    s.close();
+    db.readFence = saved.rf; db.readBuilderScope = saved.rs; api.resolveOptional = saved.ro;
+  }
+});
+
+test('the fence read answers autonomy.run from the session fold, adding NO query to the runner’s every-iteration read', async () => {
+  const api = req(path.join(ROOT, 'src/module-api.js'));
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = { rf: db.readFence, rs: db.readBuilderScope, ro: api.resolveOptional };
+  let resolves = 0;
+  const folded = [];
+  db.readFence = async () => PROJECT;
+  db.readBuilderScope = async () => ({ goals: [1000118], owner_paused: false, updated_at: null });
+  api.resolveOptional = () => ({
+    effectivePermissions: (keys) => { folded.push(keys); return keys; },
+    builderHasPermissions: async () => { resolves += 1; return true; },
+  });
+  const s = await serve(autonomyRouter());
+  try {
+    sessionKeys = ['autonomy.run', 'task.claim'];
+    let body = await (await send(s.base, 'GET', '/autonomy/fence')).json();
+    assert.equal(body.enabled, true);
+    assert.equal(resolves, 0, 'the fold answered — no DB resolve');
+    assert.deepEqual(folded, [['autonomy.run', 'task.claim']]);
+
+    sessionKeys = ['task.claim'];
+    body = await (await send(s.base, 'GET', '/autonomy/fence')).json();
+    assert.equal(body.stop_code, 'not_permitted', 'the fold says not held, and that is the answer');
+    assert.equal(resolves, 0);
+
+    sessionKeys = null;
+    body = await (await send(s.base, 'GET', '/autonomy/fence')).json();
+    assert.equal(resolves, 1, 'no fold on the session: the resolve is the fallback, as in requirePermission');
+  } finally {
+    s.close();
+    sessionKeys = null;
+    db.readFence = saved.rf; db.readBuilderScope = saved.rs; api.resolveOptional = saved.ro;
+  }
+});
+
+test('GET /autonomy/runners/all attaches the server’s health verdict to every builder’s runner', async () => {
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = db.readAllRunnerScopes;
+  db.readAllRunnerScopes = async () => [
+    { builder_id: '3', goals: [1000118], owner_paused: false, runners: [{ host: 'winbox', last_seen_at: new Date().toISOString(), last_event: 'cadence' }] },
+    { builder_id: '9', goals: [], owner_paused: true, runners: [] },
+  ];
+  const s = await serve(autonomyRouter());
+  try {
+    const r = await send(s.base, 'GET', '/autonomy/runners/all');
+    assert.equal(r.status, 200);
+    const { builders } = await r.json();
+    assert.equal(builders.length, 2);
+    assert.equal(builders[0].runners[0].health.state, 'alive');
+    assert.deepEqual(builders[1].runners, []);
+
+    db.readAllRunnerScopes = async () => { throw new Error('db down'); };
+    assert.equal((await send(s.base, 'GET', '/autonomy/runners/all')).status, 503, 'unreadable is a 503, never an empty list');
+  } finally {
+    s.close();
+    db.readAllRunnerScopes = saved;
+  }
+});
+
+test('PUT /autonomy/me/goals writes the session builder’s picks and refuses a goal the project does not allow', async () => {
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = db.setBuilderGoals;
+  const seen = [];
+  let answer = { goals: [1000090, 1000118] };
+  db.setBuilderGoals = async (args) => { seen.push(args); return answer; };
+  const s = await serve(autonomyRouter());
+  try {
+    let r = await send(s.base, 'PUT', '/autonomy/me/goals', { goal_ids: [1000118, '1000090'] });
+    assert.equal(r.status, 200);
+    assert.deepEqual(await r.json(), { goals: [1000090, 1000118] });
+    assert.deepEqual(seen[0], { builderId: 7, goalIds: [1000118, 1000090] });
+
+    answer = { goals: [] };
+    r = await send(s.base, 'PUT', '/autonomy/me/goals', { goal_ids: [] });
+    assert.equal(r.status, 200, 'an empty list is a real answer: "my runner takes no work"');
+
+    answer = { notAllowed: [4242] };
+    r = await send(s.base, 'PUT', '/autonomy/me/goals', { goal_ids: [4242] });
+    assert.equal(r.status, 409);
+    assert.match((await r.json()).error.message, /4242/);
+
+    const before = seen.length;
+    for (const bad of [{ goal_ids: 'x' }, { goal_ids: [0] }, { goal_ids: [-3] }, { goal_ids: ['abc'] }]) {
+      r = await send(s.base, 'PUT', '/autonomy/me/goals', bad);
+      assert.equal(r.status, 400, JSON.stringify(bad));
+    }
+    assert.equal(seen.length, before, 'a malformed list never reaches the database');
+  } finally {
+    s.close();
+    db.setBuilderGoals = saved;
+  }
+});
+
+test('POST /autonomy/builders/:id/pause pauses THAT builder, keeps the reason only while paused', async () => {
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = db.setBuilderPause;
+  const seen = [];
+  db.setBuilderPause = async (args) => { seen.push(args); return { builder_id: String(args.builderId), owner_paused: args.paused }; };
+  const s = await serve(autonomyRouter());
+  try {
+    let r = await send(s.base, 'POST', '/autonomy/builders/42/pause', { paused: true, reason: 'too many PRs' });
+    assert.equal(r.status, 200);
+    assert.deepEqual(seen[0], { builderId: 42, paused: true, reason: 'too many PRs', byBuilderId: 7 });
+    db.setBuilderPause = async () => null;
+    r = await send(s.base, 'POST', '/autonomy/builders/999999/pause', { paused: true });
+    assert.equal(r.status, 404, 'no such builder: refused, never an orphan row');
+    r = await send(s.base, 'POST', '/autonomy/builders/nope/pause', { paused: true });
+    assert.equal(r.status, 400);
+    r = await send(s.base, 'POST', '/autonomy/builders/42/pause', {});
+    assert.equal(r.status, 400, 'paused is required');
+  } finally {
+    s.close();
+    db.setBuilderPause = saved;
+  }
+});
+
+// ── the SQL ──────────────────────────────────────────────────────────────────
+
+function stubClient(replies) {
+  const calls = [];
+  const client = { query: async (sql, params) => { calls.push({ sql, params }); return replies.shift() || { rows: [] }; }, release: () => { calls.push({ sql: 'RELEASE' }); } };
+  return { client, calls };
+}
+
+test('setBuilderGoals writes nothing when any goal is not allowlisted, and replaces the list otherwise', async () => {
+  const api = req(path.join(ROOT, 'src/module-api.js'));
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = api.pool.connect;
+  try {
+    let s = stubClient([{}, { rows: [{ goal_id: '1000118' }] }]);
+    api.pool.connect = async () => s.client;
+    assert.deepEqual(await db.setBuilderGoals({ builderId: 7, goalIds: [1000118, 4242] }), { notAllowed: [4242] });
+    assert.ok(s.calls.some((c) => c.sql === 'ROLLBACK'));
+    assert.ok(!s.calls.some((c) => /INSERT INTO autonomy_builder_goals|DELETE FROM autonomy_builder_goals/.test(c.sql)), 'nothing is written');
+    assert.equal(s.calls.at(-1).sql, 'RELEASE');
+
+    s = stubClient([{}, { rows: [{ goal_id: '1000118' }, { goal_id: '1000090' }] }]);
+    api.pool.connect = async () => s.client;
+    assert.deepEqual(await db.setBuilderGoals({ builderId: 7, goalIds: [1000118, 1000090, 1000118] }), { goals: [1000090, 1000118] });
+    const sqls = s.calls.map((c) => c.sql);
+    assert.ok(sqls.some((q) => /DELETE FROM autonomy_builder_goals WHERE builder_id = \$1/.test(q)));
+    assert.ok(sqls.some((q) => /INSERT INTO autonomy_builder_goals/.test(q)));
+    assert.ok(sqls.some((q) => /INSERT INTO autonomy_builder_scope/.test(q)), 'the scope row is bumped so a waiting runner wakes');
+    assert.ok(sqls.includes('COMMIT'));
+
+    s = stubClient([{}]);
+    api.pool.connect = async () => s.client;
+    assert.deepEqual(await db.setBuilderGoals({ builderId: 7, goalIds: [] }), { goals: [] });
+    assert.ok(!s.calls.some((c) => /INSERT INTO autonomy_builder_goals/.test(c.sql)), 'an empty list clears and inserts nothing');
+  } finally {
+    api.pool.connect = saved;
+  }
+});
+
+test('readBuilderScope: null for a builder with no row and no picks; picks only while still allowlisted', async () => {
+  const api = req(path.join(ROOT, 'src/module-api.js'));
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = api.pool.query;
+  const sqls = [];
+  let scopeRows = []; let goalRows = [];
+  api.pool.query = async (sql) => { sqls.push(sql); return { rows: /autonomy_builder_scope/.test(sql) ? scopeRows : goalRows }; };
+  try {
+    assert.equal(await db.readBuilderScope(7), null);
+    assert.ok(sqls.some((q) => /JOIN autonomy_allowed_goals/.test(q)));
+    scopeRows = [{ owner_paused: true, owner_paused_reason: 'r', owner_paused_by: '3', updated_at: 't' }];
+    goalRows = [{ goal_id: '1000118' }];
+    assert.deepEqual(await db.readBuilderScope(7), { goals: [1000118], owner_paused: true, owner_paused_reason: 'r', owner_paused_by: '3', updated_at: 't' });
+  } finally {
+    api.pool.query = saved;
+  }
+});
+
+test('readAllRunnerScopes: a builder with picks and no runner, and one with a runner and no picks, both appear', async () => {
+  const api = req(path.join(ROOT, 'src/module-api.js'));
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = api.pool.query;
+  const sqls = [];
+  api.pool.query = async (sql, params) => {
+    sqls.push({ sql, params });
+    if (/FROM autonomy_builder_scope/.test(sql)) return { rows: [{ builder_id: '4', owner_paused: true, owner_paused_reason: 'too many PRs', updated_at: 't' }] };
+    if (/FROM autonomy_builder_goals/.test(sql)) return { rows: [{ builder_id: '3', goal_id: '1000118' }, { builder_id: '4', goal_id: '1000090' }] };
+    if (/FROM autonomy_runner_heartbeat/.test(sql)) return { rows: [{ builder_id: '9', host: 'pc9', working_task_id: '5', working_goal_id: null, last_seen_at: 't' }] };
+    if (/FROM builders/.test(sql)) return { rows: [{ id: '3', github_login: 'b3', display_name: 'Three', rank: 'archon' }, { id: '9', github_login: 'b9', display_name: 'Nine', rank: 'metic' }] };
+    return { rows: [] };
+  };
+  try {
+    const out = await db.readAllRunnerScopes();
+    const by = Object.fromEntries(out.map((b) => [b.builder_id, b]));
+    assert.deepEqual(Object.keys(by).sort(), ['3', '4', '9']);
+    assert.deepEqual(by['3'].goals, [1000118], 'picks only, no runner');
+    assert.deepEqual(by['3'].runners, []);
+    assert.equal(by['3'].display_name, 'Three');
+    assert.equal(by['4'].owner_paused, true);
+    assert.equal(by['4'].owner_paused_reason, 'too many PRs');
+    assert.equal(by['4'].display_name, undefined, 'no builders row: no name, and still listed');
+    assert.deepEqual(by['9'].goals, [], 'a runner and no picks');
+    assert.equal(by['9'].runners[0].host, 'pc9');
+    assert.equal(by['9'].runners[0].working_task_id, '5');
+    const beat = sqls.find((c) => /FROM autonomy_runner_heartbeat/.test(c.sql)).sql;
+    assert.match(beat, /PARTITION BY builder_id/, 'the cap is per builder, so a busy builder cannot push a quiet one out');
+    assert.match(beat, /rn <= 20/);
+    assert.deepEqual(sqls.find((c) => /FROM builders/.test(c.sql)).params[0].slice().sort(), ['3', '4', '9']);
+  } finally {
+    api.pool.query = saved;
+  }
+});
+
+test('setBuilderPause writes only for a builder that exists', async () => {
+  const api = req(path.join(ROOT, 'src/module-api.js'));
+  const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+  const saved = api.pool.query;
+  let seen = null;
+  api.pool.query = async (sql, params) => { seen = { sql, params }; return { rows: [] }; };
+  try {
+    assert.equal(await db.setBuilderPause({ builderId: 999, paused: true, reason: 'x', byBuilderId: 3 }), null);
+    assert.match(seen.sql, /WHERE EXISTS \(SELECT 1 FROM builders WHERE id = \$1\)/);
+    assert.deepEqual(seen.params, [999, true, 'x', 3]);
+    await db.setBuilderPause({ builderId: 4, paused: false, reason: 'ignored', byBuilderId: 3 });
+    assert.equal(seen.params[2], null, 'the reason is kept only while paused');
+  } finally {
+    api.pool.query = saved;
+  }
+});
+
+// ── the schema and the permission ────────────────────────────────────────────
+
+const sqlOf = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8').split('\n').filter((l) => !l.trim().startsWith('--')).join('\n');
+
+test('the migration ties every pick to the allowlist and drops it when the goal is revoked', () => {
+  const sql = sqlOf('modules/autonomy/migrations/autonomy_005_builder_scope.sql');
+  assert.match(sql, /CREATE TABLE IF NOT EXISTS autonomy_builder_goals/);
+  assert.match(sql, /REFERENCES autonomy_allowed_goals \(goal_id\) ON DELETE CASCADE/);
+  assert.match(sql, /PRIMARY KEY \(builder_id, goal_id\)/);
+  assert.match(sql, /owner_paused\s+boolean NOT NULL DEFAULT false/);
+});
+
+test('autonomy.run is an operational Metic permission, granted to Metic and Archon', () => {
+  const { PERMISSIONS: CATALOG } = req(path.join(ROOT, 'modules/government/catalog.js'));
+  const entry = (CATALOG || []).find((p) => p.key === 'autonomy.run');
+  assert.ok(entry, 'in the catalog');
+  assert.equal(entry.system, false, 'composable into a custom rank — it cannot widen the fence');
+  assert.equal(entry.floor, 'metic');
+  const fm = (CATALOG || []).find((p) => p.key === 'autonomy.fence.manage');
+  assert.equal(fm.system, true, 'the fence itself stays the owner’s alone');
+  const grant = sqlOf('modules/government/migrations/government_022_autonomy_run.sql');
+  assert.match(grant, /SELECT 'metic', unnest\(ARRAY\[\s*'autonomy\.run'\s*\]\)/);
+  assert.match(grant, /SELECT 'archon', unnest\(ARRAY\[\s*'autonomy\.run'\s*\]\)/);
+});
+
+// ── the pages ────────────────────────────────────────────────────────────────
+
+test('the owner page draws the PROJECT fence and pauses one builder; the settings panel writes the caller’s own picks', () => {
+  const gate = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/gate.js'), 'utf8');
+  assert.match(gate, /fence\.project \|\| fence/, 'the switch panel must not draw the owner’s own narrowed picks as the project list');
+  assert.match(gate, /\/autonomy\/runners\/all/);
+  assert.match(gate, /\/autonomy\/builders\/\$\{encodeURIComponent\(id\)\}\/pause/);
+  const html = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/gate.html'), 'utf8');
+  assert.match(html, /id="fence-builders"/);
+
+  const panel = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings-autobongos.js'), 'utf8');
+  assert.match(panel, /'PUT', `\$\{API\}\/autonomy\/me\/goals`/);
+  assert.match(panel, /scope\.may_run !== true/, 'a builder who may not run is told so instead of shown a form');
+  assert.match(panel, /'GET', `\$\{API\}\/goals`/, 'goals are named from the list this builder can already see');
+  assert.match(panel, /goalLabel\(g\.goal_id\)/);
+  const settings = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings.html'), 'utf8');
+  assert.match(settings, /id="autobongos-scroll"/);
+  assert.match(settings, /settings-autobongos\.js/);
+});

package/tests/autonomy_fence_priority.mjs

@@ -204,7 +204,9 @@ test('the migration ties the priority to the allowlist and clears it on revoke',
 
 test('the gate page renders the priority, lists it first, and posts to the priority route', () => {
   const src = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/gate.js'), 'utf8');
-  assert.match(src, /renderFenceGoals\(fence\.goals, fence\.priority_goal_id\)/, 'the page must pass the priority it read');
+  // The PROJECT fence's priority (task 1004501): GET /autonomy/fence now answers
+  // with the caller's narrowed fence, and the switch panel draws `project`.
+  assert.match(src, /renderFenceGoals\(project\.goals, project\.priority_goal_id\)/, 'the page must pass the priority it read');
   assert.match(src, /sendJson\('POST', '\/autonomy\/fence\/priority', \{ goal_id: goalId \}\)/);
   assert.match(src, /Make priority/);
   assert.match(src, /Clear priority/);

package/tests/core_update_banner.mjs

@@ -21,8 +21,10 @@ const CU = require_(path.join(ROOT, 'src/bongos/core-update.js'));
 // through it rather than reaching past it into internals that no route uses.
 // `store` is per-call so the unit assertions never share the module's own cache.
 const freshStore = () => ({ at: 0, versions: [], ok: false, inflight: null });
-const verdictFor = (running, available, channel) =>
-  CU.readCoreUpdate({ running, channel, store: freshStore(), fetch: async () => ({ ok: true, versions: available }) });
+// `released` is the registry's `latest` label. It defaults to the newest version listed, which is
+// what it was before merges published as candidates (task 1004298); the candidate tests pass it.
+const verdictFor = (running, available, channel, released = available[available.length - 1]) =>
+  CU.readCoreUpdate({ running, channel, store: freshStore(), fetch: async () => ({ ok: true, versions: available, released }) });
 const SHELL = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/shell.js'), 'utf8');
 
 // ── the verdict ────────────────────────────────────────────────────────────────
@@ -53,6 +55,40 @@ test('a prerelease ahead is not offered', async () => {
   assert.equal(v.behind, false);
 });
 
+// ── only released versions are offered (task 1004298, ADR 0361) ──────────────────
+
+test('a candidate newer than the release is NOT offered; the release is', async () => {
+  const v = await verdictFor('1.19.861', ['1.19.861', '1.19.865', '1.19.871'], undefined, '1.19.865');
+  assert.equal(v.latest, '1.19.865', 'the newest RELEASED version, not the newest published');
+  assert.equal(v.behind, true);
+});
+
+test('a project already on the release is current, however many candidates follow it', async () => {
+  const v = await verdictFor('1.19.865', ['1.19.865', '1.19.870', '1.19.871'], undefined, '1.19.865');
+  assert.equal(v.behind, false);
+  assert.equal(v.latest, null);
+  assert.equal(v.reading, 'ok');
+});
+
+test('the platform hall, running ahead of the release, reads current — never "behind" a version older than it', async () => {
+  const v = await verdictFor('1.19.871', ['1.19.865', '1.19.871'], undefined, '1.19.865');
+  assert.equal(v.behind, false);
+});
+
+test('a registry that names no release is NO ANSWER, never the newest candidate', async () => {
+  const v = await verdictFor('1.19.861', ['1.19.861', '1.19.871'], undefined, null);
+  assert.equal(v.reading, 'no_answer');
+  assert.equal(v.latest, null);
+});
+
+test('the packument\'s `latest` label is what bounds the offer', async () => {
+  const v = await CU.readCoreUpdate({
+    running: '1.19.861', store: freshStore(),
+    get: fakeGet((res) => { res._body = JSON.stringify({ 'dist-tags': { latest: '1.19.865', next: '1.19.871' }, versions: { '1.19.861': {}, '1.19.865': {}, '1.19.871': {} } }); }),
+  });
+  assert.equal(v.latest, '1.19.865');
+});
+
 test('NO ANSWER is not "up to date" — the distinction the banner turns on', async () => {
   // A registry that cannot be reached, and a box that cannot name its own core:
   // two different roads to the same must-say-nothing state.
@@ -96,7 +132,7 @@ test('a real packument is parsed, and its newest version reaches the verdict', a
   // Drives the ACTUAL https parsing path, only the socket is fake.
   const v = await CU.readCoreUpdate({
     running: '1.19.861', store: freshStore(),
-    get: fakeGet((res) => { res._body = JSON.stringify({ versions: { '1.19.861': {}, '1.19.871': {} } }); }),
+    get: fakeGet((res) => { res._body = JSON.stringify({ 'dist-tags': { latest: '1.19.871' }, versions: { '1.19.861': {}, '1.19.871': {} } }); }),
   });
   assert.equal(v.reading, 'ok');
   assert.equal(v.latest, '1.19.871');
@@ -120,7 +156,7 @@ test('the cache spares the registry a second read inside the TTL', async () => {
 test('concurrent cold-cache reads make ONE outbound call, not one each', async () => {
   const store = freshStore();
   let calls = 0;
-  const fetch = () => { calls++; return new Promise((r) => setTimeout(() => r({ ok: true, versions: ['1.19.871'] }), 5)); };
+  const fetch = () => { calls++; return new Promise((r) => setTimeout(() => r({ ok: true, versions: ['1.19.871'], released: '1.19.871' }), 5)); };
   const args = { running: '1.19.861', store, fetch, now: () => 1 };
   const all = await Promise.all([CU.readCoreUpdate(args), CU.readCoreUpdate(args), CU.readCoreUpdate(args)]);
   assert.equal(calls, 1, 'three simultaneous cold reads share one registry call');
@@ -179,7 +215,7 @@ test('a real request through the assembled router returns the verdict, not a 500
 
   // Warm the module's OWN cache through the public door, so the route's own
   // dependency-free call is served from it and the test never touches the network.
-  await CU.readCoreUpdate({ running: '1.19.861', fetch: async () => ({ ok: true, versions: ['1.19.861', '1.19.871'] }) });
+  await CU.readCoreUpdate({ running: '1.19.861', fetch: async () => ({ ok: true, versions: ['1.19.861', '1.19.871'], released: '1.19.871' }) });
   const express = r2('express');
   const app = express();
   app.use(r2(routePath)());

package/tests/core_upgrade_runner.mjs

@@ -1416,7 +1416,14 @@ console.log('\nthe project\'s own update rule (task 1004445):');
 const realChannel = require('../scripts/gds/update-channel.js');
 const withRealChannel = (over) => {
   const d = makeDeps(over);
-  d.updateChannel = { ...realChannel, listAvailableVersions: () => ({ ok: true, versions: over.available }) };
+  // readReleaseTags is stubbed too: the real one shells out to npm. `released` defaults to the newest
+  // version listed, which is what `latest` was before candidates (task 1004298).
+  const released = over.released !== undefined ? over.released : over.available[over.available.length - 1];
+  d.updateChannel = {
+    ...realChannel,
+    listAvailableVersions: () => ({ ok: true, versions: over.available }),
+    readReleaseTags: () => (released ? { ok: true, released, tags: { latest: released } } : { ok: false, error: 'no latest label', released: null, tags: {} }),
+  };
   return d;
 };
 
@@ -1528,5 +1535,63 @@ await t('the drain loop writes the class beside the sentence (behaviour: tests/p
   assert.match(src, /SET failure_class = \$2, failure_reason = \$3/);
 });
 
+console.log('\nwho is offered a candidate (task 1004298, ADR 0361):');
+
+await t('the platform hall (control-plane) is moved to a candidate newer than the release', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1083', available: ['1.19.1081', '1.19.1082', '1.19.1083'], released: '1.19.1082' });
+  const r = await R.coreUpgradeInstance(inst({ hosting_shape: 'control-plane' }), d, intent({ target_version: '1.19.1083' }));
+  assert.ok(!(r.error && /not a published|unknown version|outside/.test(r.error)), `the candidate must be admitted: ${r.error}`);
+  assert.ok(d.ran.some((c) => /upgrade\.js/.test(c) && /--to 1\.19\.1083/.test(c)), 'the upgrade was invoked for the candidate');
+});
+
+await t('any other project is refused a candidate the owner has not released', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1081', available: ['1.19.1081', '1.19.1082', '1.19.1083'], released: '1.19.1082' });
+  const r = await R.coreUpgradeInstance(inst({ hosting_shape: 'co-tenant', slug: 'demo' }), d, intent({ target_version: '1.19.1083' }));
+  assert.equal(r.ok, false);
+  assert.ok(!d.ran.some((c) => /upgrade\.js/.test(c)), 'and nothing was run');
+});
+
+await t('…and takes the released version', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1082', available: ['1.19.1081', '1.19.1082', '1.19.1083'], released: '1.19.1082' });
+  const r = await R.coreUpgradeInstance(inst({ hosting_shape: 'co-tenant', slug: 'demo' }), d, intent({ target_version: '1.19.1082' }));
+  assert.ok(d.ran.some((c) => /upgrade\.js/.test(c) && /--to 1\.19\.1082/.test(c)), `the release was invoked: ${r.error}`);
+});
+
+await t('a project that follows releases is offered nothing when the registry names no release', async () => {
+  const queries = [];
+  await R.snapshotCoreVersions(inst({ hosting_shape: 'co-tenant', slug: 'demo' }), withRealChannel({ served: '1.19.1081', available: ['1.19.1081', '1.19.1083'], released: null, queries }));
+  const q = queries.find((x) => /provisioning_core_version_snapshot/.test(x.sql));
+  assert.equal(q.params[3], null, 'no recommended version on a guess');
+});
+
+await t('the snapshot offers a tenant the release and the platform hall the newest candidate', async () => {
+  const available = ['1.19.1081', '1.19.1082', '1.19.1083'];
+  const offered = async (hosting_shape) => {
+    const queries = [];
+    await R.snapshotCoreVersions(inst({ hosting_shape, slug: hosting_shape }), withRealChannel({ served: '1.19.1081', available, released: '1.19.1082', queries }));
+    return queries.find((x) => /provisioning_core_version_snapshot/.test(x.sql)).params[3];
+  };
+  assert.equal(await offered('co-tenant'), '1.19.1082');
+  assert.equal(await offered('control-plane'), '1.19.1083');
+});
+
+await t('a pass over several projects reads the released label ONCE, not once per project', async () => {
+  const d = withRealChannel({ served: '1.19.1081', available: ['1.19.1081', '1.19.1082', '1.19.1083'], released: '1.19.1082', queries: [] });
+  let reads = 0;
+  const real = d.updateChannel.readReleaseTags;
+  d.updateChannel.readReleaseTags = (...a) => { reads++; return real(...a); };
+  for (const slug of ['a', 'b', 'c']) await R.snapshotCoreVersions(inst({ hosting_shape: 'co-tenant', slug }), d);
+  assert.equal(reads, 1, `three projects, one npm view — read ${reads} times`);
+});
+
+await t('a FAILED label read is not kept: the next project asks again', async () => {
+  const d = withRealChannel({ served: '1.19.1081', available: ['1.19.1081', '1.19.1083'], released: null, queries: [] });
+  let reads = 0;
+  const real = d.updateChannel.readReleaseTags;
+  d.updateChannel.readReleaseTags = (...a) => { reads++; return real(...a); };
+  for (const slug of ['a', 'b']) await R.snapshotCoreVersions(inst({ hosting_shape: 'co-tenant', slug }), d);
+  assert.equal(reads, 2);
+});
+
 console.log(`\ncore_upgrade_runner: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);