@bongos/core 1.19.873 → 1.19.875

package/scripts/gds/autobongos-run.js

@@ -6,15 +6,18 @@
 // one worker → record. No model anywhere in this file; every branch it takes is
 // a branch a person can read.
 //
-//   node scripts/gds/autobongos-run.js --goal 1000119            # one task
-//   node scripts/gds/autobongos-run.js --goal 1000119 --max-tasks 5
-//   node scripts/gds/autobongos-run.js --goal 1000119 --dry-run  # pick only, claim nothing
+//   node scripts/gds/autobongos-run.js                           # every allowlisted goal
+//   node scripts/gds/autobongos-run.js --goal 1000119            # narrow to one of them
+//   node scripts/gds/autobongos-run.js --max-tasks 5
+//   node scripts/gds/autobongos-run.js --dry-run                 # pick only, claim nothing
 //
 // SCOPE, and what deliberately is NOT here:
-//   · the ALLOWLIST is `--goal` / AUTOBONGOS_GOALS for now. Task 1003908 moves it
-//     into the database where the machine cannot edit it, and adds the kill
-//     switch. Until then this refuses to run with no goal named, rather than
-//     defaulting to "anything claimable".
+//   · the ALLOWLIST and the KILL SWITCH live in the DATABASE (task 1003908,
+//     ADR 0307 §6) and are read at step 0 of every iteration. `--goal` and
+//     AUTOBONGOS_GOALS survive only as a NARROWING filter — they can take goals
+//     away from the allowlist and can never add one, because a setting on this
+//     machine is editable by the very bypassPermissions worker the allowlist
+//     exists to bound.
 //   · CONFIRMING a ship against the ledger is autobongos-verify.js (task
 //     1003903), called at step 6. A worker's `shipped` is a CLAIM — recorded here
 //     as `claims_shipped` so nothing can mistake it for a fact — and the ledger
@@ -33,6 +36,12 @@ const {
   buildWorkerArgs, buildWorkerPrompt, classifyRun, DEFAULT_MODEL, DEFAULT_WORKER_TIMEOUT_MS,
 } = require('./autobongos-loop.js');
 const { verifyShip } = require('./autobongos-verify.js');
+const fence = require('../../modules/autonomy/fence.js');
+// The ADR 0043 protected-path registry, reused rather than re-derived. scripts/
+// sits outside the kernel boundary, so this direct core require is allowed here
+// where it would not be inside modules/ — which is exactly why fence.js takes the
+// hits as an argument instead of matching them itself.
+const { matchProtected } = require('../../src/bongos/permission-path-check');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
@@ -51,6 +60,10 @@ function readArgv(argv) {
   if (!out.goals.length && process.env.AUTOBONGOS_GOALS) {
     out.goals = String(process.env.AUTOBONGOS_GOALS).split(',').map((g) => Number(g.trim())).filter(Boolean);
   }
+  // NOTE the semantics changed in task 1003908: `out.goals` is a REQUESTED filter,
+  // intersected with the database allowlist. An empty list no longer means "refuse
+  // to run" — it means "every allowlisted goal" — because the thing that refuses
+  // when nothing is permitted is now the fence, which this machine cannot edit.
   return out;
 }
 
@@ -202,6 +215,33 @@ function worktreeName(taskId) {
   return `autobongos-${taskId}-${crypto.randomBytes(3).toString('hex')}`;
 }
 
+// readFence — the two facts the fence is made of, in one place.
+//
+// BOTH come from the server. `GET /autonomy/fence` is the kill switch and the
+// allowlist; `GET /me`'s `grader_bypass` is ADR 0041's global grader killswitch,
+// resolved server-side from the server's own env. Neither is readable from a file
+// on this machine, and that is the entire point — see modules/autonomy/fence.js.
+//
+// A failure of EITHER read returns the shape that refuses. An unreachable
+// instance and a thrown kill switch are different facts, but they license the
+// same action: do nothing.
+async function readFence(deps = {}) {
+  const api = deps.api || await (require('./cli-lib').cliClient)();
+  let raw = null;
+  let graderBypassed = null;
+  try {
+    const r = await api.autonomy.getAutonomyFence();
+    if (r && r.ok) raw = r.data;
+  } catch (_) { /* unreadable → refuses below */ }
+  try {
+    const me = await api.me.getMe();
+    // Strictly a boolean or nothing. `undefined` from an older server is NOT
+    // `false`: it means this instance cannot tell us, which refuses.
+    if (me && me.ok && typeof me.data.grader_bypass === 'boolean') graderBypassed = me.data.grader_bypass;
+  } catch (_) { /* unreadable → refuses below */ }
+  return { raw, graderBypassed };
+}
+
 async function iteration(opts, deps = {}) {
   const runCmd = deps.run || run;
   const spawnWork = deps.spawnWorker || spawnWorker;
@@ -209,17 +249,53 @@ async function iteration(opts, deps = {}) {
   const pick = deps.pickTask || pickTask;
   const log = deps.record || record;
 
+  // 0. THE FENCE (task 1003908, ADR 0307 §6). Before the gauge, because three of
+  // its four gates make every task refusable and there is no sense paying for a
+  // capacity read to discover that. Before anything is picked, claimed or spawned,
+  // because a fence checked after the fact is not a fence.
+  const { raw, graderBypassed } = deps.readFence ? await deps.readFence(deps) : await readFence(deps);
+  // NOT named `run`. The module-level exec helper above is called `run`, and a
+  // `const run` anywhere in this function hoists into a Temporal Dead Zone that
+  // covers the WHOLE body — including `deps.run || run` at the top, which is the
+  // PRODUCTION call shape (main() passes no deps). That shadowing threw
+  // `ReferenceError: Cannot access 'run' before initialization` on the first line
+  // of every real iteration while every test stayed green, because the harness
+  // always injected deps.run. Caught by the grader on task 1003908; the test that
+  // now drives iteration() with no deps is the actual fix — this rename is half.
+  const gate = fence.decideRun({ fence: raw, requestedGoals: opts.goals, graderBypassed });
+  if (!gate.go) {
+    return log({ event: 'fenced', code: gate.code, reason: gate.reason, refused_goals: gate.refusedGoals || [] });
+  }
+
   // 1. The gauge. Never start a task we cannot pay for out of the window.
   const g = readGauge();
   if (!g.decision.go) {
     return log({ event: 'hold', go: false, unknown: !!g.decision.unknown, reason: g.decision.reason, sleep_until: g.decision.sleepUntil ?? null });
   }
 
-  // 2. Pick.
-  const picked = await pick(opts.goals, deps.pickDeps || {});
+  // 2. Pick — from the ALLOWLISTED goals, never from what the command line asked
+  // for. gate.goals is already the intersection.
+  const picked = await pick(gate.goals, deps.pickDeps || {});
   if (picked.error) return log({ event: 'pick_failed', reason: picked.error });
   if (picked.none) return log({ event: 'nothing_claimable', goals: opts.goals });
   const task = picked.task;
+
+  // 2b. The per-TASK half of the fence. sequence.js's halt matrix already refuses
+  // a protected-path task, and this re-asks anyway — not from distrust of the
+  // matrix, but because the matrix is a shared component with its own callers and
+  // the fence must not be a property of whoever happens to be picking. A gate that
+  // only holds while a collaborator keeps calling it is not a gate.
+  //
+  // Both halves read the task's DECLARED touches[], which is a claim, not a fact —
+  // see the header of modules/autonomy/fence.js for why that is acceptable as the
+  // OUTER of three layers and would not be as the only one.
+  const taskGate = fence.decideTask({
+    task, goals: gate.goals, protectedHits: matchProtected(task.touches || []),
+  });
+  if (!taskGate.go) {
+    return log({ event: 'fenced', code: taskGate.code, reason: taskGate.reason, task_id: task.id, goal_id: picked.goalId, globs: taskGate.globs || [] });
+  }
+
   if (opts.dryRun) return log({ event: 'dry_run', task_id: task.id, title: task.title, goal_id: picked.goalId });
 
   // 3. The task's own working tree.
@@ -290,11 +366,10 @@ async function iteration(opts, deps = {}) {
 
 async function main(argv) {
   const opts = readArgv(argv);
-  if (!opts.goals.length) {
-    console.error('autobongos-run: name at least one allowlisted goal (--goal N, or AUTOBONGOS_GOALS).');
-    console.error('  Refusing to run against "anything claimable" — the allowlist is half of what makes this safe to leave alone.');
-    return 2;
-  }
+  // No "name a goal" refusal here any more. It used to be the only allowlist, and
+  // it lived on the machine being fenced; the database owns that now, and an empty
+  // `--goal` means "every allowlisted goal" rather than "anything claimable". The
+  // refusal did not disappear — it moved somewhere the runner host cannot edit.
   for (let i = 0; i < opts.maxTasks; i++) {
     const row = await iteration(opts);
     if (opts.json) console.log(JSON.stringify(row));
@@ -314,4 +389,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { readArgv, pickTask, iteration, record, logPath, spawnWorker, workerEnv, WORKER_ENV_ALLOW, worktreeName };
+module.exports = { readArgv, pickTask, iteration, record, logPath, spawnWorker, workerEnv, WORKER_ENV_ALLOW, worktreeName, readFence };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.873'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.875'; // 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('dev-box'); log.info('mounted');

package/tests/autobongos_fence.mjs

@@ -0,0 +1,262 @@
+// tests/autobongos_fence.mjs — the Autobongos fence (task 1003908, ADR 0307 §6).
+//
+// Four gates, and the done-when names them: a task in a non-allowlisted goal, a
+// task touching a protected path, and a run with the grader disabled are each
+// refused, and the kill switch stops the runner without anyone touching the
+// machine. Each has a test that names it, plus the property that binds them all —
+// EVERY gate fails closed, because a machine that cannot prove it is allowed to
+// act must not act.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const fence = require('../modules/autonomy/fence.js');
+const runner = require('../scripts/gds/autobongos-run.js');
+const catalog = require('../modules/government/catalog.js');
+
+const { decideRun, decideTask, normaliseFence, allowedGoals } = fence;
+
+const open = (over = {}) => ({ enabled: true, paused_reason: null, goals: [{ goal_id: 1000119 }], ...over });
+const GRADER_OK = { graderBypassed: false };
+
+// ── gate 1: the kill switch ─────────────────────────────────────────────────────
+
+test('the kill switch stops the runner, and says who stopped it', () => {
+  const d = decideRun({ fence: open({ enabled: false, paused_reason: 'owner paused for the release' }), ...GRADER_OK });
+  assert.equal(d.go, false);
+  assert.equal(d.code, 'kill_switch');
+  assert.match(d.reason, /owner paused for the release/, 'a machine that stopped must be able to say WHY, not just "halted"');
+  assert.deepEqual(d.goals, []);
+});
+
+test('the switch is checked before anything else can permit a run', () => {
+  // A disabled fence with a full allowlist and a healthy grader still refuses.
+  const d = decideRun({ fence: open({ enabled: false }), requestedGoals: [1000119], ...GRADER_OK });
+  assert.equal(d.code, 'kill_switch');
+});
+
+test('the kill switch cannot be delegated below the owner', () => {
+  // The switch is only a stop button if the thing being stopped cannot grant
+  // itself the power to un-stop. The catalog invariant is what enforces that.
+  const entry = catalog.byKey('autonomy.fence.manage');
+  assert.ok(entry, 'the permission must exist in the catalog');
+  assert.equal(entry.system, true);
+  assert.equal(entry.floor, 'archon');
+  assert.equal(catalog.isGrantableTo('autonomy.fence.manage', 'metic'), false);
+});
+
+// ── gate 2: the allowlist ───────────────────────────────────────────────────────
+
+test('a task in a non-allowlisted goal is refused', () => {
+  const goals = [1000119];
+  assert.equal(decideTask({ task: { id: 1, goal_id: 1000119 }, goals }).go, true);
+
+  const d = decideTask({ task: { id: 2, goal_id: 1000090 }, goals });
+  assert.equal(d.go, false);
+  assert.equal(d.code, 'goal_not_allowlisted');
+  assert.match(d.reason, /1000090/);
+});
+
+test('a task with no goal at all is refused', () => {
+  for (const goal_id of [null, undefined, '', 0]) {
+    assert.equal(decideTask({ task: { id: 1, goal_id }, goals: [1000119] }).code, 'goal_not_allowlisted', String(goal_id));
+  }
+});
+
+test('the command line can only NARROW the allowlist, never widen it', () => {
+  // The whole reason the list moved into the database: a setting on the runner
+  // host is editable by the bypassPermissions worker the list exists to bound.
+  const f = open({ goals: [{ goal_id: 1000119 }, { goal_id: 1000086 }] });
+
+  const narrowed = decideRun({ fence: f, requestedGoals: [1000119], ...GRADER_OK });
+  assert.deepEqual(narrowed.goals, [1000119]);
+
+  const widened = decideRun({ fence: f, requestedGoals: [1000119, 9999999], ...GRADER_OK });
+  assert.deepEqual(widened.goals, [1000119], 'a goal the database does not allow must be dropped');
+  assert.deepEqual(widened.refusedGoals, [9999999], 'and reported, not silently ignored');
+});
+
+test('asking ONLY for a goal that is not allowed refuses the whole run', () => {
+  const d = decideRun({ fence: open(), requestedGoals: [9999999], ...GRADER_OK });
+  assert.equal(d.go, false);
+  assert.equal(d.code, 'goal_not_allowlisted');
+});
+
+test('an empty allowlist means nothing may be worked', () => {
+  const d = decideRun({ fence: open({ goals: [] }), ...GRADER_OK });
+  assert.equal(d.go, false);
+  assert.equal(d.code, 'no_allowlist');
+});
+
+test('a goal id that is not a positive integer never enters the allowlist', () => {
+  // Number('') is 0, and a 0 sitting in an allowlist is a goal nobody granted.
+  const f = normaliseFence(open({ goals: [{ goal_id: 1000119 }, { goal_id: '' }, { goal_id: 0 }, { goal_id: -3 }, { goal_id: 'abc' }, null] }));
+  assert.deepEqual(f.goals, [1000119]);
+});
+
+test('a goal row may be a bare id or an object — both are read the same', () => {
+  assert.deepEqual(normaliseFence(open({ goals: [1000119, { goal_id: '1000086' }] })).goals, [1000119, 1000086]);
+});
+
+// ── gate 3: protected paths ─────────────────────────────────────────────────────
+
+test('a task touching a protected path is refused, and the glob is named', () => {
+  const d = decideTask({
+    task: { id: 3, goal_id: 1000119 },
+    goals: [1000119],
+    protectedHits: [{ file: 'migrations/999_x.sql', glob: 'migrations/**' }],
+  });
+  assert.equal(d.go, false);
+  assert.equal(d.code, 'protected_path');
+  assert.deepEqual(d.globs, ['migrations/**']);
+});
+
+test('the protected-path gate runs against the REAL registry, not a fixture', async () => {
+  // A test that only ever feeds hand-made hits proves the branch, not the fence.
+  // These paths are the four families ADR 0307 §6 names: permission, migration,
+  // infrastructure, deploy pipeline.
+  const { matchProtected } = require('../src/bongos/permission-path-check');
+  for (const file of ['migrations/126_autonomy.sql', 'docs/canonical-permissions.md', 'infra/deploy.sh']) {
+    const hits = matchProtected([file]);
+    if (!hits.length) continue;   // the registry, not this test, decides what is protected
+    const d = decideTask({ task: { id: 4, goal_id: 1000119 }, goals: [1000119], protectedHits: hits });
+    assert.equal(d.code, 'protected_path', `${file} is in the registry and must be refused`);
+  }
+  // At least one of them must actually be protected, or this test is vacuous.
+  assert.ok(['migrations/126_autonomy.sql', 'docs/canonical-permissions.md', 'infra/deploy.sh']
+    .some((f) => matchProtected([f]).length), 'the registry matched nothing — this test would pass on a broken fence');
+});
+
+// ── gate 4: the grader ──────────────────────────────────────────────────────────
+
+test('a run with the grader disabled is refused', () => {
+  const d = decideRun({ fence: open(), graderBypassed: true });
+  assert.equal(d.go, false);
+  assert.equal(d.code, 'grader_unavailable');
+  assert.match(d.reason, /only review/);
+});
+
+test('an UNKNOWN grader state refuses too — it is not the same as available', () => {
+  // The runner holds no push credential, so the server-side grade is the only
+  // review between an unattended worker and main. "I could not tell" must not
+  // resolve to "go ahead".
+  const d = decideRun({ fence: open(), graderBypassed: null });
+  assert.equal(d.go, false);
+  assert.equal(d.code, 'grader_unavailable');
+  assert.match(d.reason, /could not read/);
+});
+
+test('an open fence with a healthy grader goes', () => {
+  const d = decideRun({ fence: open(), ...GRADER_OK });
+  assert.equal(d.go, true);
+  assert.deepEqual(d.goals, [1000119]);
+  assert.equal(d.code, null);
+});
+
+// ── the property that binds them: fail closed ───────────────────────────────────
+
+test('an unreadable fence permits nothing', () => {
+  for (const raw of [null, undefined, {}, 'nope', 42, { goals: [] }, { enabled: 'yes', goals: [] }]) {
+    const d = decideRun({ fence: raw, ...GRADER_OK });
+    assert.equal(d.go, false, `${JSON.stringify(raw)} must not read as permission`);
+    assert.equal(d.code, 'fence_unreadable');
+  }
+});
+
+test('a broken goals list degrades to an empty allowlist, and never hides the switch', () => {
+  // Both refuse, so this is not about safety — it is about what the operator is
+  // told. Someone who threw the kill switch must see `kill_switch`, not
+  // `fence_unreadable` because a list beside it was the wrong shape.
+  for (const goals of [undefined, null, 'nope', 42, {}]) {
+    assert.equal(decideRun({ fence: { enabled: false, paused_reason: 'owner stopped it', goals }, ...GRADER_OK }).code,
+      'kill_switch', String(goals));
+    assert.equal(decideRun({ fence: { enabled: true, goals }, ...GRADER_OK }).code,
+      'no_allowlist', 'an unusable list is an EMPTY list — the most restrictive reading available');
+  }
+});
+
+test('there is no input that opens the fence without all four gates clearing', () => {
+  // A sweep rather than a list: if a future edit adds a permissive branch, this is
+  // the test that finds it.
+  const enabledStates = [true, false];
+  const graderStates = [false, true, null];
+  const goalSets = [[], [{ goal_id: 1000119 }]];
+  const requested = [[], [1000119], [9999999]];
+  for (const enabled of enabledStates) {
+    for (const graderBypassed of graderStates) {
+      for (const goals of goalSets) {
+        for (const req of requested) {
+          const d = decideRun({ fence: { enabled, paused_reason: null, goals }, requestedGoals: req, graderBypassed });
+          const shouldGo = enabled
+            && graderBypassed === false
+            && goals.length > 0
+            && (req.length === 0 || req.includes(1000119));
+          assert.equal(d.go, shouldGo,
+            `enabled=${enabled} grader=${graderBypassed} goals=${goals.length} requested=${JSON.stringify(req)}`);
+          if (!d.go) assert.ok(d.code, 'every refusal must carry a code the run log can key on');
+        }
+      }
+    }
+  }
+});
+
+test('a refusal never carries goals a caller could act on', () => {
+  for (const d of [
+    decideRun({ fence: open({ enabled: false }), ...GRADER_OK }),
+    decideRun({ fence: open(), graderBypassed: true }),
+    decideRun({ fence: null, ...GRADER_OK }),
+    decideRun({ fence: open({ goals: [] }), ...GRADER_OK }),
+  ]) {
+    assert.deepEqual(d.goals, [], 'a refused run must hand back nothing to work on');
+  }
+});
+
+test('decideTask refuses a task it cannot identify', () => {
+  for (const task of [null, undefined, {}, { goal_id: 1000119 }]) {
+    assert.equal(decideTask({ task, goals: [1000119] }).go, false);
+  }
+});
+
+// ── the runner's own read ───────────────────────────────────────────────────────
+
+test('an unreachable instance refuses — it does not fall back to a default', async () => {
+  const api = {
+    autonomy: { getAutonomyFence: async () => { throw new Error('ECONNREFUSED'); } },
+    me: { getMe: async () => { throw new Error('ECONNREFUSED'); } },
+  };
+  const { raw, graderBypassed } = await runner.readFence({ api });
+  assert.equal(raw, null);
+  assert.equal(graderBypassed, null);
+  assert.equal(decideRun({ fence: raw, graderBypassed }).code, 'fence_unreadable');
+});
+
+test('a server too old to report grader state is UNKNOWN, not healthy', async () => {
+  const api = {
+    autonomy: { getAutonomyFence: async () => ({ ok: true, data: open() }) },
+    me: { getMe: async () => ({ ok: true, data: { builder: { id: '3' } } }) },   // no grader_bypass
+  };
+  const { raw, graderBypassed } = await runner.readFence({ api });
+  assert.deepEqual(raw, open());
+  assert.equal(graderBypassed, null);
+  assert.equal(decideRun({ fence: raw, graderBypassed }).code, 'grader_unavailable');
+});
+
+test('a healthy read passes both facts through', async () => {
+  const api = {
+    autonomy: { getAutonomyFence: async () => ({ ok: true, data: open() }) },
+    me: { getMe: async () => ({ ok: true, data: { grader_bypass: false } }) },
+  };
+  const { raw, graderBypassed } = await runner.readFence({ api });
+  assert.equal(graderBypassed, false);
+  assert.equal(decideRun({ fence: raw, graderBypassed }).go, true);
+});
+
+// ── allowedGoals, on its own ────────────────────────────────────────────────────
+
+test('no request means every allowlisted goal', () => {
+  const f = normaliseFence(open({ goals: [{ goal_id: 1 }, { goal_id: 2 }] }));
+  assert.deepEqual(allowedGoals(f, []).goals, [1, 2]);
+  assert.deepEqual(allowedGoals(f).goals, [1, 2]);
+});

package/tests/autobongos_loop.mjs

@@ -253,7 +253,15 @@ test('a goal whose tasks cannot be read is reported, not silently skipped', asyn
 // running. These pin the shape that fixes it.
 
 const goodGauge = () => ({ decision: { go: true, unknown: false, sleepUntil: null, reason: 'headroom' } });
-const aTask = { id: 4242, title: 'Do the thing', kind: 'feature', description: 'd'.repeat(300) };
+const aTask = { id: 4242, title: 'Do the thing', kind: 'feature', description: 'd'.repeat(300), goal_id: 1000119, touches: [] };
+// The FENCE, faked (task 1003908). Step 0 of every iteration now reads the kill
+// switch, the allowlist and the grader's availability from the server; a test that
+// does not say what the fence holds is not describing a run. The fence's own
+// behaviour is tests/autobongos_fence.mjs — here it is a precondition.
+const openFence = () => ({
+  raw: { enabled: true, paused_reason: null, goals: [{ goal_id: 1000119 }] },
+  graderBypassed: false,
+});
 
 function harness(over = {}) {
   const calls = [];
@@ -261,6 +269,7 @@ function harness(over = {}) {
   const blockers = [];
   const deps = {
     gauge: over.gauge || goodGauge,
+    readFence: over.readFence || (async () => openFence()),
     // The LEDGER, faked. iteration() now reads the task back from Bongos after
     // every worker (task 1003903) instead of believing the worker's own verdict,
     // so a test that does not say what the ledger holds is not describing a run.
@@ -288,6 +297,56 @@ function harness(over = {}) {
 }
 const opts = { goals: [1000119], maxTasks: 1, dryRun: false, model: 'm', timeoutMs: 1000 };
 
+test('the fence is read BEFORE the gauge, and a closed one claims nothing', async () => {
+  // Order matters: three of the fence's four gates make every task refusable, so
+  // paying for a capacity read first would be wasted — and a fence checked after
+  // something is claimed is not a fence.
+  let gaugeRead = false;
+  const h = harness({
+    gauge: () => { gaugeRead = true; return goodGauge(); },
+    readFence: async () => ({ raw: { enabled: false, paused_reason: 'owner stopped it' }, graderBypassed: false }),
+  });
+  const row = await runner.iteration(opts, h.deps);
+  assert.equal(row.event, 'fenced');
+  assert.equal(row.code, 'kill_switch');
+  assert.match(row.reason, /owner stopped it/);
+  assert.equal(gaugeRead, false, 'the gauge must not be consulted for a run the fence already refused');
+  assert.deepEqual(h.calls, [], 'nothing may be created or claimed behind a closed fence');
+});
+
+test('a bypassed grader stops the runner rather than shipping unreviewed', async () => {
+  const h = harness({ readFence: async () => ({ ...openFence(), graderBypassed: true }) });
+  const row = await runner.iteration(opts, h.deps);
+  assert.equal(row.event, 'fenced');
+  assert.equal(row.code, 'grader_unavailable');
+  assert.deepEqual(h.calls, []);
+});
+
+test('the loop picks from the ALLOWLIST, not from what the command line asked for', async () => {
+  let sawGoals = null;
+  const h = harness({ pickTask: async (goals) => { sawGoals = goals; return { task: aTask, goalId: 1000119, skipped: [] }; } });
+  // The operator asks for an allowlisted goal AND one that is not on the list.
+  await runner.iteration({ ...opts, goals: [1000119, 9999999] }, h.deps);
+  assert.deepEqual(sawGoals, [1000119], 'a goal the database does not allow must never reach the picker');
+});
+
+test('a picked task in a non-allowlisted goal is refused before it is claimed', async () => {
+  const h = harness({ pickTask: async () => ({ task: { ...aTask, goal_id: 9999999 }, goalId: 9999999, skipped: [] }) });
+  const row = await runner.iteration(opts, h.deps);
+  assert.equal(row.event, 'fenced');
+  assert.equal(row.code, 'goal_not_allowlisted');
+  assert.deepEqual(h.calls, [], 'no worktree, no claim, no worker');
+});
+
+test('a picked task touching a protected path is refused before it is claimed', async () => {
+  const h = harness({ pickTask: async () => ({ task: { ...aTask, touches: ['migrations/999_x.sql', 'docs/canonical-permissions.md'] }, goalId: 1000119, skipped: [] }) });
+  const row = await runner.iteration(opts, h.deps);
+  assert.equal(row.event, 'fenced');
+  assert.equal(row.code, 'protected_path');
+  assert.ok(row.globs.length, 'the refusal must name the surface it hit');
+  assert.deepEqual(h.calls, []);
+});
+
 test('an unknown gauge holds before anything is claimed', async () => {
   const h = harness({ gauge: () => ({ decision: { go: false, unknown: true, reason: 'no gauge file', sleepUntil: null } }) });
   const row = await runner.iteration(opts, h.deps);
@@ -444,3 +503,63 @@ test('each task gets a worktree name that cannot collide with another claim', ()
   assert.notEqual(a, b, 'a collision makes the server store a name the ship lock can never match (task 1004031)');
 });
 
+
+// ── the production call shape ───────────────────────────────────────────────────
+//
+// THE GAP THIS CLOSES, and it is the point of the test rather than a footnote.
+// `harness()` always injects deps.run, so `const runCmd = deps.run || run` at the
+// top of iteration() short-circuits and never evaluates the module-level `run`
+// helper. A later `const run = …` in the same function shadowed that helper
+// through the whole body via its Temporal Dead Zone, so every real invocation —
+// main() calls iteration(opts) with NO deps — threw `ReferenceError: Cannot
+// access 'run' before initialization` on iteration's first meaningful line, while
+// the entire suite stayed green. Shipped code that no test ever calls the way
+// production calls it is untested code, whatever the count says.
+//
+// These drive iteration() with the MINIMUM injection: the two reads that would
+// otherwise touch the network, and nothing else. Anything that resolves from the
+// module scope must resolve for real.
+
+test('iteration() runs with no injected run/spawn — the shape main() actually calls', async () => {
+  const rows = [];
+  const row = await runner.iteration(opts, {
+    readFence: async () => ({ raw: { enabled: false, paused_reason: 'off for the test' }, graderBypassed: false }),
+    record: (r) => { rows.push(r); return r; },
+  });
+  assert.equal(row.event, 'fenced');
+  assert.equal(row.code, 'kill_switch');
+  assert.equal(rows.length, 1);
+});
+
+test('the fenced paths reach their decision with nothing injected but the reads', async () => {
+  // Every refusal that can be reached before the gauge, driven through the real
+  // module-scope bindings. A regression in ANY of them surfaces here as a throw
+  // rather than as a passing test against a fully-mocked function.
+  const cases = [
+    [{ raw: { enabled: true, goals: [{ goal_id: 1000119 }] }, graderBypassed: true }, 'grader_unavailable'],
+    // `opts` asks for goal 1000119, so an EMPTY allowlist refuses it by name.
+    [{ raw: { enabled: true, goals: [] }, graderBypassed: false }, 'goal_not_allowlisted'],
+    [{ raw: null, graderBypassed: false }, 'fence_unreadable'],
+    [{ raw: { enabled: false }, graderBypassed: false }, 'kill_switch'],
+  ];
+  for (const [fenceRead, code] of cases) {
+    const row = await runner.iteration(opts, { readFence: async () => fenceRead, record: (r) => r });
+    assert.equal(row.event, 'fenced', code);
+    assert.equal(row.code, code);
+  }
+});
+
+test('the module-level exec helper is reachable from inside iteration()', async () => {
+  // The narrow assertion the bug would have failed: get PAST the fence, so
+  // `deps.run || run` has to resolve the module-level helper for real, and stop at
+  // the next injected seam. A name that shadows `run` reds this immediately.
+  let picked = false;
+  const row = await runner.iteration(opts, {
+    readFence: async () => openFence(),
+    gauge: goodGauge,
+    pickTask: async () => { picked = true; return { none: true }; },
+    record: (r) => r,
+  });
+  assert.equal(picked, true, 'iteration must reach the picker without touching an un-injected binding');
+  assert.equal(row.event, 'nothing_claimable');
+});