@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/autobongos-service.cmd

@@ -0,0 +1,50 @@
+@echo off
+REM scripts/bongos/autobongos-service.cmd -- what the scheduled task actually runs
+REM (task 1003905). A .cmd, not a direct node invocation, for three reasons the
+REM scheduler cannot do itself.
+REM
+REM 1. THE CHECKOUT IS BROUGHT CURRENT FIRST. A runner pinned to whatever was on
+REM    disk the day it was installed drifts silently, and the first symptom is
+REM    workers building against a stale fence. `git fetch` + `reset --hard` on the
+REM    MAIN checkout only -- worker trees are separate worktrees and are never
+REM    touched here.
+REM 2. OUTPUT IS APPENDED TO ONE FILE the owner can read remotely. The scheduler
+REM    keeps only an exit code, which cannot answer "what was it doing".
+REM 3. A NON-ZERO EXIT IS RETURNED so the scheduler's restart rule can see it.
+REM
+REM The runner itself never exits on failure (task 1003904) -- it backs off and
+REM probes -- so reaching the end of this file at all means something the inner
+REM loop could not survive.
+
+setlocal
+set "REPO=%~dp0..\.."
+set "LOGDIR=%LOCALAPPDATA%\cloudbongos"
+set "LOG=%LOGDIR%\autobongos.log"
+if not exist "%LOGDIR%" mkdir "%LOGDIR%"
+
+cd /d "%REPO%" || exit /b 1
+
+REM THE UPGRADE LOOP (task 1004374). The runner exits 75 when main has moved
+REM past the code it loaded; we refresh and relaunch. Without this --forever
+REM never returns and so never picks up a fix: on the host this ran week-old
+REM code for four days across three landed fixes while the heartbeat reported
+REM it alive. Looping HERE rather than leaning on the scheduler matters,
+REM because MultipleInstances IgnoreNew makes a restart a silent no-op while
+REM the old process is still up.
+:run
+echo. >> "%LOG%"
+echo ==== autobongos starting %DATE% %TIME% ==== >> "%LOG%"
+
+REM Best effort: a fetch that fails must not stop the runner from starting on the
+REM code it already has. Being a commit behind beats not running at all.
+git fetch --quiet origin main >> "%LOG%" 2>&1
+git reset --quiet --hard origin/main >> "%LOG%" 2>&1
+
+node scripts\bongos\autobongos-run.js --forever --json >> "%LOG%" 2>&1
+set EXITCODE=%ERRORLEVEL%
+if "%EXITCODE%"=="75" (
+  echo ==== autobongos relaunching for an upgrade at %DATE% %TIME% ==== >> "%LOG%"
+  goto run
+)
+echo ==== autobongos exited %EXITCODE% at %DATE% %TIME% ==== >> "%LOG%"
+exit /b %EXITCODE%

package/scripts/bongos/autobongos-service.ps1

@@ -0,0 +1,270 @@
+# scripts/bongos/autobongos-service.ps1 -- install the Autobongos runner so it
+# outlives the reboot (task 1003905, ADR 0307 section 5).
+#
+#   powershell -ExecutionPolicy Bypass -File scripts\bongos\autobongos-service.ps1 install
+#   powershell -ExecutionPolicy Bypass -File scripts\bongos\autobongos-service.ps1 status
+#   powershell -ExecutionPolicy Bypass -File scripts\bongos\autobongos-service.ps1 digest
+#   powershell -ExecutionPolicy Bypass -File scripts\bongos\autobongos-service.ps1 start|stop|uninstall
+#
+# WHY TASK SCHEDULER AND NOT A REAL SERVICE. Windows services speak a protocol
+# (SCM handshakes, stop signals) that node does not, so every "node as a service"
+# route needs a third-party wrapper: nssm, winsw, node-windows. Each is a binary
+# to download, verify, update and explain -- a permanent dependency bought for one
+# machine. Task Scheduler is already on the box, runs at boot with no session,
+# survives sign-out, and restarts a crashed task natively. The one thing it does
+# not give is the Services panel, which nobody here needs.
+#
+# WHAT ACTUALLY KEEPS IT ALIVE IS THE INNER LOOP, and that is the important part
+# to understand before reading the RestartCount settings below. `--forever` never
+# returns: it backs off and probes instead of exiting (task 1003904), so the
+# scheduler's restart is the OUTER ring, for the cases the loop cannot survive at
+# all -- a reboot, a power cut, a node crash, an OOM kill. If this ring is doing
+# work regularly, something is wrong that the backoff should have absorbed, and
+# the run log will say so.
+#
+# UNPRIVILEGED ON PURPOSE. It runs as the logged-in user, not SYSTEM: the runner
+# needs that user's git credential, npm config and Claude session, and SYSTEM has
+# none of them. It is also the smaller blast radius for a process that spawns
+# workers with blanket bypassPermissions. (INSTALLING it is the one step that
+# needs an elevated shell of that same user -- see Assert-Prereqs, task 1004177.)
+
+[CmdletBinding()]
+param(
+  [Parameter(Position = 0)]
+  [ValidateSet('install', 'uninstall', 'start', 'stop', 'status', 'digest')]
+  [string]$Action = 'status',
+
+  # The checkout to run from. Defaults to the repo this script lives in, so the
+  # common case needs no argument and cannot point at the wrong tree by typo.
+  [string]$RepoRoot,
+
+  [string]$TaskName = 'Autobongos'
+)
+
+$ErrorActionPreference = 'Stop'
+
+if (-not $RepoRoot) {
+  $RepoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+}
+$LogDir = Join-Path $env:LOCALAPPDATA 'cloudbongos'
+$LogFile = Join-Path $LogDir 'autobongos.log'
+$Wrapper = Join-Path $RepoRoot 'scripts\bongos\autobongos-service.cmd'
+
+# Is this shell elevated (Run as administrator)? Its own function so the tests
+# can stand it in: the check is Windows-only, and CI runs on Linux.
+function Test-Elevated {
+  $id = [Security.Principal.WindowsIdentity]::GetCurrent()
+  return ([Security.Principal.WindowsPrincipal]$id).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+}
+
+# REGISTERING vs RUNNING (task 1004177). The task RUNS as this user, unelevated
+# (-RunLevel Limited): that is what reaches the user's git credential and Claude
+# session, and it is load-bearing. But REGISTERING a task with an S4U principal
+# needs an elevated shell -- unelevated, Register-ScheduledTask fails with a bare
+# "Access is denied" (0x80070005) that says nothing about why. Elevating the SAME
+# account keeps $env:USERNAME, so the principal below is still this user. So
+# install -- and only install -- checks, and says so in words, before trying.
+$ElevationNeeded = @(
+  'install needs an elevated shell: registering a task that runs whether or not you are signed in (the S4U logon type) requires Administrator.',
+  'Open PowerShell with "Run as administrator" AS THIS SAME USER and run install again. The task still RUNS as you, unelevated (-RunLevel Limited) -- only the registration needs admin.',
+  'Do NOT install it as SYSTEM or another admin account: the runner needs your git credential and Claude session, and SYSTEM has neither.'
+) -join ' '
+
+function Assert-Prereqs {
+  param([switch]$ForInstall)
+  if (-not (Test-Path (Join-Path $RepoRoot 'scripts\bongos\autobongos-run.js'))) {
+    throw "No autobongos-run.js under $RepoRoot -- pass -RepoRoot <path to the checkout>."
+  }
+  if ($ForInstall -and -not (Test-Elevated)) { throw $ElevationNeeded }
+  foreach ($exe in @('node', 'git', 'claude')) {
+    if (-not (Get-Command $exe -ErrorAction SilentlyContinue)) {
+      # Named, not guessed at: a runner that starts without `claude` on PATH will
+      # spawn-fail every worker and look like a mysterious outage in the log.
+      throw "'$exe' is not on PATH for this user. The runner needs node, git and claude."
+    }
+  }
+}
+
+function Show-Status {
+  $t = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+  if (-not $t) { Write-Host "not installed  (task '$TaskName' does not exist)"; return }
+  $info = Get-ScheduledTaskInfo -TaskName $TaskName
+  Write-Host "task       : $TaskName"
+  Write-Host "state      : $($t.State)"
+  Write-Host "last run   : $($info.LastRunTime)  (result $($info.LastTaskResult))"
+  Write-Host "next run   : $($info.NextRunTime)"
+  Write-Host "log        : $LogFile"
+  if (Test-Path $LogFile) {
+    Write-Host "log size   : $([math]::Round((Get-Item $LogFile).Length / 1KB)) KB"
+    Write-Host ''
+    Write-Host '--- last 15 lines ---'
+    Get-Content $LogFile -Tail 15
+  } else {
+    Write-Host 'log        : (not written yet)'
+  }
+  Write-Host ''
+  Write-Host 'The scheduler only says whether the PROCESS is up. Whether the runner'
+  Write-Host 'is actually working is the hall: it reads the heartbeat this posts.'
+}
+
+# --- stop, and say what actually happened (task 1004375) -----------------------
+#
+# Stop-ScheduledTask returns as soon as the scheduler has been ASKED. It does not
+# wait, and it does not report whether the process went away -- and on the host
+# it did not: the runner, started under the S4U logon type, sat in a session the
+# interactive user could not terminate, survived Stop-ScheduledTask AND a
+# Stop-Process -Force, while this script printed "stopped". Because the task is
+# MultipleInstances IgnoreNew, a following `start` then no-ops against the old
+# process, and the pair reads as a clean restart that changed nothing.
+#
+# So 'stop' now reads the runner's own pid from the heartbeat it writes
+# (autobongos-run.js writeHeartbeat -> <config dir>\autobongos-heartbeat.json),
+# asks the scheduler to stop, POLLS for that pid to exit, and reports one of four
+# outcomes. It never says "stopped" about a process it has not watched exit.
+
+# Where the runner writes its heartbeat: asked of the RUNNER, via its own
+# exported heartbeatPath(), not re-derived here. That function is the only
+# definition -- AUTOBONGOS_HEARTBEAT_FILE first, then the branding pack's config
+# dir, then the repo root -- and a second copy of it in PowerShell would drift
+# from the file the runner actually writes, which is the exact bug this fixes.
+# Only if node itself cannot answer does this fall back to the repo-root name.
+function Get-HeartbeatFile {
+  $fromRunner = $null
+  try {
+    $run = Join-Path $RepoRoot 'scripts\bongos\autobongos-run.js'
+    $fromRunner = & node -e "process.stdout.write(String(require(process.argv[1]).heartbeatPath()))" $run
+  } catch { $fromRunner = $null }
+  if ($fromRunner) { return [string]$fromRunner }
+  return (Join-Path $RepoRoot '.autobongos-heartbeat.json')
+}
+
+# The pid the runner recorded, or $null when there is no file or no usable pid.
+function Read-RunnerPid([string]$HeartbeatFile) {
+  if (-not $HeartbeatFile -or -not (Test-Path $HeartbeatFile)) { return $null }
+  try { $hb = Get-Content -Raw -Path $HeartbeatFile | ConvertFrom-Json } catch { return $null }
+  $n = 0
+  if ($hb -and [int]::TryParse([string]$hb.pid, [ref]$n) -and $n -gt 0) { return $n }
+  return $null
+}
+
+# Alive AND node: a heartbeat left behind by a crash can name a pid that Windows
+# has since handed to some unrelated process, and that must not read as "the
+# runner is still running".
+function Test-RunnerAlive([int]$ProcessId) {
+  $p = Get-Process -Id $ProcessId -ErrorAction SilentlyContinue
+  return [bool]($p -and $p.ProcessName -eq 'node')
+}
+
+# Outcome is one of:
+#   stopped        -- the pid was alive, and was watched to exit
+#   still_running  -- the pid was alive and is STILL alive after the wait
+#   not_running    -- the heartbeat's pid was already gone before the stop
+#   unknown        -- no pid to check, so nothing can be claimed either way
+# StopTask is injectable so tests/autobongos_service_ps1.mjs can drive the real
+# polling against a real process without a scheduled task.
+function Invoke-RunnerStop {
+  param(
+    [string]$HeartbeatFile,
+    [int]$TimeoutSeconds = 20,
+    [scriptblock]$StopTask = { Stop-ScheduledTask -TaskName $TaskName }
+  )
+  $runnerPid = Read-RunnerPid $HeartbeatFile
+  $wasAlive = [bool]($runnerPid -and (Test-RunnerAlive $runnerPid))
+  & $StopTask
+  if (-not $runnerPid) { return [pscustomobject]@{ Outcome = 'unknown'; Pid = $null; Waited = 0 } }
+  if (-not $wasAlive) { return [pscustomobject]@{ Outcome = 'not_running'; Pid = $runnerPid; Waited = 0 } }
+  $started = Get-Date
+  $deadline = $started.AddSeconds($TimeoutSeconds)
+  while ((Test-RunnerAlive $runnerPid) -and ((Get-Date) -lt $deadline)) { Start-Sleep -Milliseconds 250 }
+  $waited = [int][math]::Round(((Get-Date) - $started).TotalSeconds)
+  $outcome = if (Test-RunnerAlive $runnerPid) { 'still_running' } else { 'stopped' }
+  return [pscustomobject]@{ Outcome = $outcome; Pid = $runnerPid; Waited = $waited }
+}
+
+function Format-StopReport($Result, [string]$HeartbeatFile) {
+  $p = $Result.Pid
+  switch ($Result.Outcome) {
+    'stopped' {
+      "stopped '$TaskName' -- runner pid $p has exited (watched, not assumed)."
+      'That is for now only: the next boot starts it again. To keep the runner from'
+      'working, use the kill switch in the hall (/builders/gate) -- it survives a'
+      'reboot and nothing running on this machine can undo it.'
+    }
+    'still_running' {
+      "NOT STOPPED: asked Task Scheduler to stop '$TaskName', but runner pid $p is still running after $($Result.Waited)s."
+      'It may be under a different logon session (the task runs as S4U), which this'
+      'shell cannot end -- Stop-Process from here fails the same way.'
+      "Remedy: from an elevated (Administrator) PowerShell run   taskkill /F /PID $p"
+      'or reboot the machine. Until it exits, `start` does nothing: the task will not'
+      'launch a second copy over a live one (MultipleInstances IgnoreNew).'
+    }
+    'not_running' {
+      "'$TaskName' was not running: runner pid $p from the heartbeat had already exited."
+    }
+    default {
+      "asked Task Scheduler to stop '$TaskName', but CANNOT CONFIRM the runner exited:"
+      "no runner pid in $HeartbeatFile. Check   Get-Process node   before assuming it stopped."
+    }
+  }
+}
+
+# Dot-sourced (the tests do this to reach the functions above), stop here: the
+# switch below is the command-line entry point and must not run on a load.
+if ($MyInvocation.InvocationName -eq '.') { return }
+
+switch ($Action) {
+  'install' {
+    Assert-Prereqs -ForInstall
+    New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
+
+    # NOT $action: PowerShell variable names are CASE-INSENSITIVE, so $action IS the
+    # $Action parameter above, and its [ValidateSet]/[string] attributes stay attached
+    # to the variable. Assigning a task-action object to it throws "the value
+    # MSFT_TaskExecAction is not a valid value for the Action variable" and install
+    # fails every time, on every machine. Same trap as the `run` shadow in task 1003908.
+    $taskAction = New-ScheduledTaskAction -Execute $Wrapper -WorkingDirectory $RepoRoot
+    # AtStartup covers the cold reboot the done-when actually names. AtLogOn is
+    # NOT used: it would wait for someone to sign in, which is the one thing that
+    # must not be required.
+    $trigger = New-ScheduledTaskTrigger -AtStartup
+    $principal = New-ScheduledTaskPrincipal -UserId "$env:USERDOMAIN\$env:USERNAME" -LogonType S4U -RunLevel Limited
+    $settings = New-ScheduledTaskSettingsSet `
+      -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
+      -StartWhenAvailable `
+      -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) `
+      -ExecutionTimeLimit ([TimeSpan]::Zero) `
+      -MultipleInstances IgnoreNew
+    # ExecutionTimeLimit ZERO = never kill it. The default is three days, and a
+    # daemon silently executed after three days is exactly the invisible death
+    # this whole task exists to prevent.
+    # MultipleInstances IgnoreNew = the scheduler will not start a second copy
+    # over a live one; the heartbeat file is the second guard, inside the runner.
+
+    Register-ScheduledTask -TaskName $TaskName -Action $taskAction -Trigger $trigger `
+      -Principal $principal -Settings $settings -Force | Out-Null
+
+    Write-Host "installed '$TaskName' -- starts at boot, restarts on crash, logs to $LogFile"
+    Write-Host ''
+    Write-Host 'Start it now with:   .\scripts\bongos\autobongos-service.ps1 start'
+    Write-Host 'Then confirm from the hall (/builders/gate) that it is checking in.'
+  }
+  'uninstall' {
+    Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+    Write-Host "removed '$TaskName'. The log at $LogFile is left in place."
+  }
+  'digest' {
+    # The night in one page (task 1003906). On the box for convenience; the same
+    # five answers are what the Gate page and a mailed digest would carry.
+    & node (Join-Path $RepoRoot 'scripts\bongos\autobongos-digest.js') @args
+  }
+  'start'  { Start-ScheduledTask -TaskName $TaskName; Write-Host "started '$TaskName'" }
+  'stop'   {
+    $hbFile = Get-HeartbeatFile
+    $result = Invoke-RunnerStop -HeartbeatFile $hbFile
+    Format-StopReport $result $hbFile | ForEach-Object { Write-Host $_ }
+    # Non-zero when the process outlived the stop, so a script driving this
+    # (a restart, a maintenance step) cannot carry on as if it had worked.
+    if ($result.Outcome -eq 'still_running') { exit 1 }
+  }
+  default  { Show-Status }
+}

package/scripts/bongos/autobongos-tweak-lane.js

@@ -0,0 +1,262 @@
+// scripts/bongos/autobongos-tweak-lane.js — the Autobongos tweak lane: pick the
+// oldest submitted page round and hand it to a worker (task 1004679 / BV2.TW19c,
+// ADR 0371 D1, D2, D4, D6, D7).
+//
+// WHY. An artist who presses submit with nobody at a terminal waits forever. The
+// runner already wakes on a cadence, holds a fence and ships through the normal
+// grade, so the lane is a step INSIDE its iteration (D1), before ordinary work,
+// fed by the same derived state the studio shows (D2: open_round.state ===
+// 'submitted', oldest task id first). Everything a person's /tweak does still
+// happens; the worker runs `/tweak --page <id> --unattended` (task 1004678).
+//
+// THE RULES, each its own refusal so a run-log row can say which one held:
+//   lane_off            tweak.autopickup is off (D3) — the lane is silent
+//   lane_at_cap         this month's marked claims reached the cap (D5)
+//   lane_rank_too_low   the runner's builder is below Metic (D4) — reported ONCE
+//   round_waits_for_person  this runner already applied the round twice (D6.2)
+//   round_failed_unchanged  the last apply failed and the round has not moved (D6.3)
+//   page_unknown / protected_path / needs_host_access   the fence over the
+//                       PAGE'S files (D7) — the setting replaces only the goal
+//                       allowlist, so decideTask is asked with the round's own goal
+//
+// The server holds the cap, the per-round limit, the artist gate and the file
+// rule again (tasks 1004677, 1004678). This file is the runner not ASKING for
+// what would be refused, so a quiet machine does not spend a worker learning it.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const fence = require('../../modules/autonomy/fence');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const LANE_RANK_FLOOR = 'metic';
+// D6.2, the same number the server refuses a third marked claim at.
+const MAX_AUTO_APPLIES_PER_ROUND = 2;
+const MAX_ROUNDS_READ_PER_PASS = 10;
+// The runner's own tree names (autobongos-run.js worktreeName). Restated rather
+// than required: requiring the runner here would be a cycle.
+const RUNNER_TREE_RE = /^autobongos-\d+-[0-9a-f]{6}$/;
+// The fence refusals that are about the goal allowlist and nothing else: the lane
+// runs past them (D3). The kill switch, a paused builder and the grader stop do not.
+const GOAL_ONLY_CODES = new Set(['goal_not_allowlisted', 'no_allowlist', 'no_builder_scope']);
+
+// ---- pure ------------------------------------------------------------------
+
+// The lane as a whole: may it try at all this pass?
+function decideLane({ settings, rank, state = {} }) {
+  if (!settings || typeof settings !== 'object') return { go: false, code: 'lane_unreadable', quiet: true, reason: 'could not read the tweak auto-pickup setting' };
+  if (settings.mode !== 'on') return { go: false, code: 'lane_off', quiet: true, reason: 'tweak auto-pickup is off for this project' };
+  const remaining = Number.isFinite(Number(settings.remaining_this_month))
+    ? Number(settings.remaining_this_month) : Number(settings.cap) - Number(settings.used_this_month);
+  if (!(remaining > 0)) return { go: false, code: 'lane_at_cap', reason: `this month's ${settings.cap} automatic page tweaks are used up — rounds wait for a person` };
+  const { RANK_TIER } = require('../../src/module-api'); // the one rank map (lazy: only when the lane is on)
+  if (!(RANK_TIER[rank] >= RANK_TIER[LANE_RANK_FLOOR])) {
+    const once = !state.laneRankReported;
+    state.laneRankReported = true;
+    return { go: false, code: 'lane_rank_too_low', quiet: !once, reason: `the runner's builder is ${rank || 'of unknown rank'}; applying a page tweak needs Metic or higher` };
+  }
+  return { go: true };
+}
+
+// The submitted rounds, oldest first (D2).
+function submittedRounds(pagesBody) {
+  const out = [];
+  for (const p of (pagesBody && pagesBody.pages) || []) {
+    const r = p && p.open_round;
+    if (r && r.state === 'submitted' && /^[1-9][0-9]*$/.test(String(r.task_id))) out.push({ pageId: p.id, taskId: String(r.task_id) });
+  }
+  return out.sort((a, b) => Number(a.taskId) - Number(b.taskId));
+}
+
+// How many times THIS runner applied the round: its claims from a runner tree.
+function autoAppliesByRunner(claims) {
+  return (claims || []).filter((c) => c && RUNNER_TREE_RE.test(String(c.worktree_name || ''))).length;
+}
+
+function pageFiles(inventory, pageId) {
+  const page = ((inventory && inventory.pages) || []).find((p) => p && p.id === pageId);
+  return page ? [...(page.files || []), ...(page.states_files || [])] : null;
+}
+
+// One round: may the lane take it?
+function decideRound({ task, claims, files, failedAt, matchProtected }) {
+  if (autoAppliesByRunner(claims) >= MAX_AUTO_APPLIES_PER_ROUND) {
+    return { go: false, code: 'round_waits_for_person', reason: `applied automatically ${MAX_AUTO_APPLIES_PER_ROUND} times already — waiting for a person` };
+  }
+  if (failedAt !== undefined && failedAt === task.updated_at) {
+    return { go: false, code: 'round_failed_unchanged', reason: 'the last automatic apply failed and the round has not changed since' };
+  }
+  if (!files || !files.length) return { go: false, code: 'page_unknown', reason: 'the page inventory does not list this page\'s files' };
+  return fence.decideTask({
+    task: { ...task, touches: files },
+    goals: task.goal_id == null ? [] : [task.goal_id],
+    protectedHits: matchProtected(files),
+  });
+}
+
+function buildTweakPrompt({ task, pageId }) {
+  return [
+    `You are an unattended Autobongos worker applying ONE page tweak: task ${task.id}, page ${pageId}.`,
+    'The round is already claimed in this worktree with the auto_pickup mark.',
+    `Read modules/copy-desk/skills/tweak/SKILL.md and follow its "Unattended mode" for: /tweak --page ${pageId} --unattended`,
+    'Never ask a question. On any halt, run the tweak-halt.js line the skill names and stop.',
+    'Never pass --skip-grade, --force or --allow-empty. Your finish line is WAITING FOR THE ARTIST.',
+  ].join('\n');
+}
+
+// After the worker: what the LEDGER says happened to the round. A held pass at
+// completed is the success; a released round is a halt (no blocker: the round
+// already carries its note, and D6.3 keeps the lane off it until it moves).
+function tweakOutcome({ task, grade }) {
+  const status = task && task.status;
+  if (status === 'completed' && grade && grade.passed === true) return { shape: 'waiting_for_artist', ok: true };
+  if (status === 'ready' || status === 'backlog') return { shape: 'tweak_halted', ok: false, failed: true };
+  return { shape: 'other', ok: false };
+}
+
+// ---- reads -----------------------------------------------------------------
+
+function readInventory(root = REPO_ROOT) {
+  return JSON.parse(fs.readFileSync(path.join(root, 'docs', 'page-inventory.json'), 'utf8'));
+}
+
+async function readRound(api, taskId) {
+  const r = await api.tasks.getTasksId({ id: Number(taskId), query: { include: 'claims,grade' } });
+  if (!r || !r.ok || !r.data || !r.data.task) return null;
+  return { task: r.data.task, claims: r.data.claims || [], grade: r.data.grade || null };
+}
+
+// pickRound — the lane's one call per iteration. Returns { round } to work,
+// or { none, code, reason, quiet?, skipped[] }.
+async function pickRound(deps) {
+  const { api, state, matchProtected } = deps;
+  let settings = null;
+  try { const r = await api.projectSettings.getProjectSettingsTweakAutopickup(); if (r && r.ok) settings = r.data; } catch (_) { /* unreadable */ }
+  let rank = deps.rank;
+  if (rank === undefined) {
+    try { const me = await api.me.getMe(); rank = me && me.ok ? me.data.builder?.rank : null; } catch (_) { rank = null; }
+  }
+  const lane = decideLane({ settings, rank, state });
+  if (!lane.go) return { none: true, ...lane, skipped: [] };
+
+  let pages = null;
+  try { const r = await api.copyDesk.getCopyDeskPages(); if (r && r.ok) pages = r.data; } catch (_) { /* unreadable */ }
+  if (!pages) return { none: true, code: 'lane_unreadable', reason: 'could not read the studio\'s page list', skipped: [] };
+  let inventory = null;
+  try { inventory = (deps.readInventory || readInventory)(); } catch (_) { inventory = null; }
+
+  const skipped = [];
+  const failed = state.tweakFailed || new Map();
+  // Bounded: a backlog of rounds the lane must skip costs at most this many reads a pass.
+  for (const { pageId, taskId } of submittedRounds(pages).slice(0, MAX_ROUNDS_READ_PER_PASS)) {
+    const round = await (deps.readRound || readRound)(api, taskId);
+    if (!round) { skipped.push({ id: taskId, page_id: pageId, code: 'round_unreadable' }); continue; }
+    const files = pageFiles(inventory, pageId);
+    const d = decideRound({ task: round.task, claims: round.claims, files, failedAt: failed.get(taskId), matchProtected });
+    if (!d.go) { skipped.push({ id: taskId, page_id: pageId, code: d.code }); continue; }
+    return { round: { task: round.task, pageId, files } };
+  }
+  return { none: true, code: 'lane_empty', quiet: true, reason: 'no submitted page round the lane may take', skipped };
+}
+
+// Is the lane's switch on? Asked only when the fence refused on goals alone, so a
+// runner with no allowlist and the lane off reports "fenced" exactly as before.
+// Unreadable answers no.
+async function laneSwitchOn(api) {
+  try {
+    const client = api || await (require('./cli-lib').cliClient)();
+    const r = await client.projectSettings.getProjectSettingsTweakAutopickup();
+    return !!(r && r.ok && r.data && r.data.mode === 'on');
+  } catch (_) { return false; }
+}
+
+// ---- the iteration step ----------------------------------------------------
+
+// The codes a lane refusal is logged under. A quiet one (off, nothing to do, the
+// rank refusal after its first report) writes no row, so an idle lane costs the
+// run log nothing.
+function laneRow(got) {
+  return { event: 'tweak_lane', code: got.code, reason: got.reason, skipped: got.skipped || [] };
+}
+
+// workRound — tree, marked claim, one worker, then the ledger. `d` carries the
+// runner's own helpers (runCmd, spawnWork, worktreeName, log, api) so this file
+// adds a lane, not a second way to run a worker.
+async function workRound({ round, opts, state }, d) {
+  const { task, pageId } = round;
+  const id = String(task.id);
+  const node = process.execPath;
+  const failedAt = async () => {
+    const after = await (d.readRound || readRound)(d.api, id).catch(() => null);
+    if (!state.tweakFailed) state.tweakFailed = new Map();
+    state.tweakFailed.set(id, after && after.task ? after.task.updated_at : task.updated_at);
+    return after;
+  };
+  const name = d.worktreeName(task.id);
+  const made = await d.runCmd(node, [path.join('scripts', 'bongos', 'worktree.js'), 'add', name, '--base', 'origin/main']);
+  if (!made.ok) return d.log({ event: 'worktree_failed', lane: 'tweak', task_id: task.id, page_id: pageId, worktree: name });
+  const treePath = path.join(REPO_ROOT, '.claude', 'worktrees', name);
+  const claimed = await d.runCmd(node, [path.join(REPO_ROOT, 'scripts', 'bongos', 'claim.js'), id, '--auto-pickup'], { cwd: treePath });
+  if (!claimed.ok) {
+    await d.runCmd(node, [path.join('scripts', 'bongos', 'worktree.js'), 'remove', name]);
+    await failedAt();
+    return d.log({ event: 'claim_failed', lane: 'tweak', task_id: task.id, page_id: pageId, worktree: name, reason: String(claimed.stderr || claimed.stdout || '').slice(0, 400) });
+  }
+  const started = Date.now();
+  // The grade cap (task 1004536) holds here as on ordinary work: the run's own
+  // grade ledger, read after the worker, never the worker's word.
+  const gradeLedger = d.gradeLedgerPath ? d.gradeLedgerPath(task.id) : null;
+  const capCheck = d.gradeCapReader ? await d.gradeCapReader({ api: d.api, taskId: task.id, ledger: gradeLedger }) : null;
+  const res = await d.spawnWork({ task, model: opts.model, timeoutMs: opts.timeoutMs, cwd: treePath, gradeLedger, capCheck, prompt: buildTweakPrompt({ task, pageId }), deps: d.spawnDeps || {} });
+  const grades = capCheck ? await capCheck() : null;
+  if (gradeLedger) { try { fs.rmSync(gradeLedger, { force: true }); } catch (_) { /* its counts travel in the row */ } }
+  let after = await (d.readRound || readRound)(d.api, id).catch(() => null);
+  const capped = !!(grades && grades.exhausted);
+  if (after && after.task && (after.task.status === 'active' || (capped && after.task.status === 'completed' && !(after.grade && after.grade.passed === true)))) {
+    // Left held, or the grade cap reached: release with the fixed note (ADR 0371 D8).
+    await d.runCmd(node, [path.join(REPO_ROOT, 'scripts', 'bongos', 'tweak-halt.js'), id, '--code', capped ? 'grade_failed' : 'worker_stopped'], { cwd: treePath });
+    after = await (d.readRound || readRound)(d.api, id).catch(() => null);
+  }
+  const out = after ? tweakOutcome(after) : { shape: 'unreadable', ok: false };
+  if (!out.ok) await failedAt();
+  return d.log({
+    event: 'worked', lane: 'tweak', task_id: task.id, title: task.title, page_id: pageId, worktree: name,
+    outcome: out.shape, ledger_status: after && after.task ? after.task.status : null,
+    ...(grades && (grades.graded || grades.outages) ? { grade_rounds: grades.graded, grade_outages: grades.outages, grade_cap_reached: capped } : {}),
+    session_id: (res && res.sessionId) || null, duration_s: Math.round((Date.now() - started) / 1000),
+    // A read that fails stops the run, as an unreadable ledger does for ordinary work.
+    ...(out.shape === 'unreadable' ? { event: 'verify_halt' } : {}),
+  });
+}
+
+// tweakLaneStep — the runner's call. Returns a run-log row when the lane did
+// something this pass (worked, refused a claim, dry run), else null and the
+// iteration goes on to ordinary work.
+async function tweakLaneStep({ opts, state }, d) {
+  const got = await (d.pickRound || pickRound)({ api: d.api, state, matchProtected: d.matchProtected, readInventory: d.readInventory, readRound: d.readRound, rank: d.rank });
+  if (got.none) {
+    if (!got.quiet) d.log(laneRow(got));
+    return null;
+  }
+  if (opts.dryRun) return d.log({ event: 'dry_run', lane: 'tweak', task_id: got.round.task.id, page_id: got.round.pageId });
+  return workRound({ round: got.round, opts, state }, d);
+}
+
+module.exports = {
+  GOAL_ONLY_CODES,
+  laneSwitchOn,
+  tweakLaneStep,
+  workRound,
+  MAX_AUTO_APPLIES_PER_ROUND,
+  LANE_RANK_FLOOR,
+  decideLane,
+  submittedRounds,
+  autoAppliesByRunner,
+  pageFiles,
+  decideRound,
+  buildTweakPrompt,
+  tweakOutcome,
+  readRound,
+  pickRound,
+};