@bongos/core 1.19.650 → 1.19.652

package/scripts/gds/box-infra.js

@@ -62,6 +62,14 @@ const CONFIG = {
   size: process.env.BOX_SIZE || 's-2vcpu-4gb',
   baseImage: process.env.BOX_BASE_IMAGE || 'ubuntu-24-04-x64',
   idleMinutes: numEnv('BOX_IDLE_MINUTES', 10),
+  // task 1003507 — the longest a box may stay active without evidence that a
+  // HUMAN was attached to it. One number bounds both proxies that used to keep a
+  // box alive on their own (a running `claude` process; load above the floor), so
+  // an abandoned session can no longer pin a droplet forever. 12h is deliberately
+  // generous — longer than any interactive session, long enough for a real
+  // overnight autonomous run — because being wrong costs one wake, while having
+  // no cap at all cost $20.21 on a single box.
+  unattendedMaxHours: numEnv('BOX_UNATTENDED_MAX_HOURS', 12),
   dormantDays: numEnv('BOX_DORMANT_DAYS', 14),
   // task 1002727 — how many days BEFORE the reclaim a builder gets warned.
   dormantWarnLeadDays: numEnv('BOX_DORMANT_WARN_LEAD_DAYS', 3),

package/scripts/gds/box.js

@@ -28,7 +28,8 @@
 //
 // Config (env): DO_API_TOKEN (live only), BOX_PROVISION_MIN_RANK (default xenos),
 //   BOX_REGION (nyc3), BOX_SIZE (s-2vcpu-4gb), BOX_BASE_IMAGE (ubuntu-24-04-x64),
-//   BOX_IDLE_MINUTES (10), BOX_DORMANT_DAYS (14), BOX_SSH_KEY_IDS (comma list),
+//   BOX_IDLE_MINUTES (10), BOX_UNATTENDED_MAX_HOURS (12), BOX_DORMANT_DAYS (14),
+//   BOX_SSH_KEY_IDS (comma list),
 //   BOX_DNS_HOOK (optional command, gets BOX_HOSTNAME/BOX_IP in env), BOX_TAG.
 
 const fs = require('node:fs');
@@ -109,6 +110,21 @@ async function preflightCookieStripScope() {
   return scope;
 }
 
+// Lazily-built handles to the heavy dependencies (DB pool, DO/CF clients), so a
+// dry-run or a --help never opens a pool or requires a network client.
+//
+// task 1003507 — this was UNDECLARED. `_deps = {...}` further down is an
+// assignment, which in sloppy mode would have created a global, but
+// `if (_deps)` READS it first, and reading an undeclared identifier is a
+// ReferenceError. So loadDeps() threw on its first call, every time, and every
+// command that reaches makeDo()/makeCf() went with it — including
+// `sweep-idle --apply`, which resolves its DO client before the park loop.
+// The idle sweep therefore could not park ANY box, which is a second and
+// entirely separate reason the abandoned box in this task was never reaped.
+// No test caught it because the only apply:true test relied on the
+// claude_active veto emptying the idle set before makeDo() was reached.
+let _deps = null;
+
 function loadDeps() {
   if (_deps) return _deps;
   // eslint-disable-next-line global-require
@@ -559,6 +575,10 @@ async function parkOne(pool, boxes, doApi, box, { actor }) {
   await boxes.setBoxState(pool, box.builder_id, 'parked', {
     snapshot_id: snapshotId, parked_at: new Date(now),
     droplet_id: null, ip: null, active_since: null,
+    // task 1003507 — the droplet is gone, so there is no `claude` process to
+    // report. Clearing the flag AND its clock here means a wake starts a fresh
+    // session rather than inheriting an expired latch and being reaped at once.
+    claude_active: false, claude_active_since: null,
   });
   await boxes.recordEvent(pool, {
     boxId: box.id, builderId: box.builder_id, event: 'park',
@@ -610,6 +630,10 @@ async function cmdWake(pool, boxes, ref, { apply }) {
     const now = new Date();
     await boxes.setBoxState(pool, builder.id, 'active', {
       droplet_id: String(droplet.id), ip, active_since: now, last_activity_at: now, parked_at: null,
+      // task 1003507 — a woken box has reported nothing yet. Start the latch and
+      // its clock clean so the first real heartbeat sets both, rather than the
+      // box re-entering the sweep carrying a stale claim from its last session.
+      claude_active: false, claude_active_since: null,
     });
     await boxes.recordEvent(pool, { boxId: box.id, builderId: builder.id, event: 'wake', detail: `droplet ${droplet.id} ${ip || ''}`, actor: actorTag() });
     // #602: the box just ended a PARKED interval (snapshot retained) — accrue its
@@ -724,7 +748,7 @@ async function deprovisionOne(pool, boxes, doApi, box, { actor, login, sleepFn }
   if (CONFIG.dnsHook && dnsHost) runDnsHookBlackhole(dnsHost);
   await boxes.setBoxState(pool, box.builder_id, 'destroyed', {
     destroyed_at: new Date(now), droplet_id: null, ip: null, snapshot_id: null,
-    active_since: null, parked_at: null, claude_active: false,
+    active_since: null, parked_at: null, claude_active: false, claude_active_since: null,
     // idea 310: a rebuilt box mints fresh SSH host keys, but the GDS row kept the
     // OLD keys until the new box re-reported (~10 min). In that window GET /box/me
     // served a stale identity and the desktop app pinned the WRONG key — the
@@ -811,18 +835,20 @@ async function cmdDeprovision(pool, boxes, ref, { apply }) {
 
 async function cmdSweepIdle(pool, boxes, { apply }) {
   const rows = await boxes.listBoxes(pool, { state: 'active' });
-  const idle = boxes.selectIdleBoxes(rows, { idleMinutes: CONFIG.idleMinutes, nowMs: Date.now() });
-  console.log(`idle sweep (threshold=${CONFIG.idleMinutes}m${apply ? '' : ', dry-run'}): ${idle.length} of ${rows.length} active box(es) idle`);
+  const sweepNow = Date.now();
+  const sel = { idleMinutes: CONFIG.idleMinutes, nowMs: sweepNow, unattendedMaxHours: CONFIG.unattendedMaxHours };
+  const idle = boxes.selectIdleBoxes(rows, sel);
+  console.log(`idle sweep (threshold=${CONFIG.idleMinutes}m, unattended cap=${CONFIG.unattendedMaxHours}h${apply ? '' : ', dry-run'}): ${idle.length} of ${rows.length} active box(es) idle`);
   if (idle.length === 0) { console.log('  nothing idle — exit clean'); return { parked: 0 }; }
   const doApi = apply ? makeDo(apply) : null;
   let parked = 0, errors = 0;
   for (const box of idle) {
-    const mins = Math.round((Date.now() - (boxes.effectiveActivityMs(box) || Date.now())) / 60000);
-    if (!apply) { console.log(`  would park @${box.github_login}'s box (idle ${mins}m, droplet ${box.droplet_id})`); continue; }
+    const why = boxes.idleReason(box, sel);
+    if (!apply) { console.log(`  would park @${box.github_login}'s box (${why}, droplet ${box.droplet_id})`); continue; }
     try {
       await parkOne(pool, boxes, doApi, box, { actor: 'sweep:idle' });
       parked++;
-      console.log(`  ✓ parked @${box.github_login} (idle ${mins}m — snapshot kept, compute stopped)`);
+      console.log(`  ✓ parked @${box.github_login} (${why} — snapshot kept, compute stopped)`);
     } catch (e) {
       // A park that fails must NOT fall through to a destroy — leaving the box
       // at 'error' with its droplet intact is strictly safer than reclaiming it,
@@ -1058,7 +1084,7 @@ async function cmdReconcileDrift(pool, boxes, { apply }) {
       await teardownEdgeForLogin(g.login, { apply });
       await boxes.setBoxState(pool, g.builderId, 'destroyed', {
         destroyed_at: new Date(nowMs), droplet_id: null, ip: null, snapshot_id: null,
-        active_since: null, parked_at: null, claude_active: false,
+        active_since: null, parked_at: null, claude_active: false, claude_active_since: null,
         host_keys: null, host_keys_at: null,
       });
       if (row) {
@@ -1198,7 +1224,7 @@ Commands:
   deprovision <builder>  destroy droplet AND snapshot (full reclaim)
   run-intents            drain the auto-provision/wake-on-connect queue (#701):
                          execute each pending box_intents row (provision/wake)
-  sweep-idle             park active boxes idle > ${CONFIG.idleMinutes}m
+  sweep-idle             park active boxes idle > ${CONFIG.idleMinutes}m, or unattended > ${CONFIG.unattendedMaxHours}h
   sweep-dormant          warn at ${Math.max(CONFIG.dormantDays - CONFIG.dormantWarnLeadDays, 0)}d, then deprovision boxes parked > ${CONFIG.dormantDays}d
                          (never reclaims a box that was not warned first)
   reconcile              source-access clawback: deprovision below-floor/inactive

package/scripts/gds/ship-land.js

@@ -35,9 +35,37 @@ const { normalizeApiError } = require('./ship-io.js');
 // Only landBailed makes the card say NOT landed. Purely additive: no bail site
 // changes what it DOES, only what it now reports back.
 // ADR 0184: an EMPTY ship has no commit to prove, so it must DECLARE itself.
+// task 1002572 (PART 2): a bail also carries an optional `bailId` — the stable
+// name of WHICH refusal fired, so a caller can route the recoverable ones to the
+// push+PR path instead of stranding. `null` for every un-tagged bail, which keeps
+// them terminal (fail-safe: an untagged bail never gains a silent fallback).
 function landed(o = {}) { return { ok: true, pending: false, reason: null, nextStep: null, noArtifact: o.noArtifact === true, noArtifactReason: o.noArtifactReason || null }; }
 function landPending() { return { ok: false, pending: true, reason: null, nextStep: null }; }
-function landBailed(reason, nextStep = null) { return { ok: false, pending: false, reason, nextStep }; }
+function landBailed(reason, nextStep = null, bailId = null) { return { ok: false, pending: false, reason, nextStep, bailId }; }
+
+// ---------- which bails a PR can still land (task 1002572, part 2) ----------
+//
+// A builder in a SINGLE main checkout can never complete a local merge: the tree
+// that would RECEIVE the merge is the very tree holding the feature branch. That
+// is a property of the machine, not of the work — the branch itself is perfectly
+// landable, just not from here. So that one bail must fall back to the push+PR
+// path (ciLand) rather than parking the task at 'confirmed' unpaid (ADR 0120).
+//
+// Everything else stays LOUD. A merge conflict, a red post-merge smoke, a failed
+// push, an unreachable origin: those are real failures, and a PR would carry the
+// same breakage to main. Membership is opt-in by id for exactly that reason —
+// blanket-converting bails into PRs is the way this fix goes wrong.
+const LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH = 'main-checkout-on-branch';
+const LAND_BAIL_NO_TASK_BRANCH = 'no-task-branch';
+const PR_RECOVERABLE_BAILS = new Set([LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH]);
+
+// landBailRecoverableByPr — PURE. Can this bail still be landed by opening a PR?
+// `no-task-branch` is deliberately NOT in the set: standing on main there is no
+// head branch to open a PR FROM, so the PR path has nothing to offer it (its cure
+// is to go back to the task branch and re-ship, which now works).
+function landBailRecoverableByPr(bailId) {
+  return PR_RECOVERABLE_BAILS.has(bailId);
+}
 
 // The short COMMAND form of strandNextStep (which is prose, sized for the log).
 // The card has room for one command, not a sentence.
@@ -639,6 +667,11 @@ module.exports = {
   ciLand,
   classifyLandOutcome,
   formatPublishFailure,
+  // task 1002572 (PART 2): the bail ids + the pure "can a PR still land this?"
+  // decision, so the single-checkout fallback is opt-in per bail and unit-tested.
+  LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+  LAND_BAIL_NO_TASK_BRANCH,
+  landBailRecoverableByPr,
   landBailed,
   landPending,
   landPendingLines,

package/scripts/gds/ship-merge.js

@@ -1,10 +1,14 @@
 // scripts/gds/ship-merge.js — autoMerge — the merge/regen/push/land chain that puts the branch on main.
 //
 // Carved out of scripts/gds/ship.js by task 1003205 (goal 1000079, the R03
-// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
-// original ship.js lines 2307-2579 unchanged. ship.js remains the facade that
-// re-exports every name and owns the CLI entry point, so the ship contract and
+// de-monolith plan) — a STRUCTURAL move, not a rewrite. ship.js remains the facade
+// that re-exports every name and owns the CLI entry point, so the ship contract and
 // every flag are untouched, and the other scripts that import from it are too.
+//
+// task 1002572 (PART 2) split the entry point in two: `mergeLocally` is the original
+// merge/regen/push/deploy chain, and `autoMerge` is a thin wrapper that routes the one
+// bail a PR can still land — a single checkout whose main worktree holds the feature
+// branch — into the push+PR path instead of stranding the task at 'confirmed'.
 
 'use strict';
 
@@ -13,7 +17,14 @@ const { cleanupMacFinderDupRefs } = require('../../modules/lifecycle/ship-prefli
 const mergeLock = require('../../modules/lifecycle/merge-lock');
 const { buildMergeArgv, gitArgvOk, gitOk, shellOk } = require('./ship-git.js');
 const { mainIsProtected, pushVia, readDeployConfigRaw, resolveDeployMode, resolveDeployTarget, safeBranding, shouldBailOnFetchFailure } = require('./ship-deploy-target.js');
-const { ciLand, landBailed, landed } = require('./ship-land.js');
+const {
+  LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+  LAND_BAIL_NO_TASK_BRANCH,
+  ciLand,
+  landBailRecoverableByPr,
+  landBailed,
+  landed,
+} = require('./ship-land.js');
 const { runSmoke } = require('./ship-grade.js');
 const { currentBranch, mainWorktreeBusy, regenerateApiClient, regenerateApiDocs, regenerateDiagrams, regenerateFileMap, regenerateRepoMap, regenerateSessionIndex } = require('./ship-regen.js');
 const { REPO_ROOT } = require('./ship-state.js');
@@ -23,7 +34,49 @@ function zeroCommitVerdict(commitsAhead, dbOnly) {
   return dbOnly ? 'db-only' : 'refuse';
 }
 
-async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
+// onMainNextStep — PURE. The recovery command for the other half of the
+// single-checkout catch-22 (task 1002572): the builder is standing ON main, so
+// there is no head branch to merge FROM and none to open a PR from either. Since
+// mergeLocally's sibling bail now falls back to the PR path, shipping from the
+// task branch WORKS even in a single checkout — so the cure is "go back to the
+// branch and re-ship", not the circular /merge-mode this used to advise. Only
+// name the branch when it actually exists locally; otherwise fall back to
+// /merge-mode rather than inventing a checkout target.
+function onMainNextStep(taskId, taskBranchExists) {
+  return taskBranchExists
+    ? `git checkout task-${taskId} && node scripts/gds/ship.js ${taskId}`
+    : '/merge-mode';
+}
+
+// localTaskBranchExists — does this checkout still hold the task's own branch? The
+// discriminator onMainNextStep needs, so the advice only names a branch that is
+// really there (a builder who deleted it gets /merge-mode, not a failing checkout).
+function localTaskBranchExists(taskId) {
+  return gitArgvOk(['rev-parse', '--verify', '--quiet', `refs/heads/task-${taskId}`], { stdio: 'ignore' });
+}
+
+// autoMerge — the land entry point. Runs the local merge chain, then (task 1002572
+// PART 2) routes the ONE bail a PR can still land into the push+PR path instead of
+// leaving the task at 'confirmed'. The fallback deliberately sits OUTSIDE
+// mergeLocally: its `finally` releases the shared merge lock and normalizes the main
+// worktree, and the PR poll that follows can run for minutes — holding the lock
+// across it would wedge every other ship on this machine.
+// `deps` is a test seam ONLY — the routing is the whole deliverable and it cannot
+// be reached from a unit test otherwise (mergeLocally needs a real second checkout
+// and an authed gh). Callers pass nothing; the defaults are the real functions.
+async function autoMerge(taskId, valueSummary, opts = {}, deps = {}) {
+  const merge = deps.mergeLocally || mergeLocally;
+  const land = deps.ciLand || ciLand;
+  const branchOf = deps.currentBranch || currentBranch;
+  const outcome = await merge(taskId, valueSummary, opts);
+  if (!landBailRecoverableByPr(outcome && outcome.bailId)) return outcome;
+  const branch = branchOf();
+  console.log('  auto-merge: a local merge is impossible from this checkout, but the branch is still landable —');
+  console.log('  falling back to the push+PR land path. Nothing is stranded; the server lands the PR.');
+  return await land(taskId, branch, valueSummary);
+}
+
+async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
   const branch = currentBranch();
   if (!branch || branch === 'main' || branch === 'HEAD') {
     // task 1002723: an --allow-empty / --db-only ship legitimately runs FROM the
@@ -40,8 +93,15 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
     console.log(`  auto-merge: skipped (current branch is ${branch})`);
     // The merge source IS the current branch, so on main there is nothing to
     // merge. Half of the single-checkout catch-22 this task documents: the other
-    // half is the "main worktree is on <branch>, not main" bail below.
-    return landBailed(`nothing to merge — this checkout is on ${branch}, not a task branch`, '/merge-mode');
+    // half is the "main worktree is on <branch>, not main" bail below, which now
+    // falls back to a PR. This half CANNOT — a PR needs a head branch and there
+    // is none here — so it stays a bail, but with a next step that actually
+    // recovers instead of pointing back at the same dead end (task 1002572).
+    return landBailed(
+      `nothing to merge — this checkout is on ${branch}, not a task branch`,
+      onMainNextStep(taskId, localTaskBranchExists(taskId)),
+      LAND_BAIL_NO_TASK_BRANCH,
+    );
   }
 
   // Refresh the data-driven diagrams before computing commits-ahead, so a
@@ -153,14 +213,17 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
     // The main worktree must currently have main checked out.
     const onMain = gitOk('git rev-parse --abbrev-ref HEAD', { cwd: REPO_ROOT });
     if (onMain !== 'main') {
-      console.log(`  auto-merge: main worktree is on ${onMain}, not main; task stays at confirmed`);
+      console.log(`  auto-merge: main worktree is on ${onMain}, not main — a local merge is impossible here`);
       // The other half of the single-checkout catch-22: the merge target tree is
       // the one holding the feature branch, so there is nowhere to merge INTO.
-      // Name the cure, not just the symptom — this is the bail that used to be
-      // invisible behind "landing automatically".
+      // task 1002572 (PART 2): this is a property of the MACHINE, not of the work
+      // — the branch lands fine via a PR. Tagged PR-recoverable so autoMerge falls
+      // back instead of parking the task at 'confirmed' unpaid. The reason +
+      // nextStep are kept for the case where the fallback itself bails.
       return landBailed(
         `the main checkout is on ${onMain}, not main — work a task in its own worktree so the main checkout stays on main`,
         '/merge-mode',
+        LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
       );
     }
 
@@ -293,5 +356,8 @@ async function autoMerge(taskId, valueSummary, { dbOnly = false } = {}) {
 
 module.exports = {
   autoMerge,
+  // task 1002572 (PART 2): the pure recovery command for a ship run from main —
+  // exported so the "don't point back at the dead end" wording is pinned.
+  onMainNextStep,
   zeroCommitVerdict,
 };

package/scripts/gds/ship.js

@@ -105,6 +105,9 @@ const {
 const {
   classifyLandOutcome,
   formatPublishFailure,
+  LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+  LAND_BAIL_NO_TASK_BRANCH,
+  landBailRecoverableByPr,
   landBailed,
   landPending,
   landPendingLines,
@@ -140,7 +143,7 @@ const {
   isLinkifiableDocPath,
   parseDeletedUpstreamPaths,
 } = require('./ship-preflight-steps.js');
-const { zeroCommitVerdict } = require('./ship-merge.js');
+const { onMainNextStep, zeroCommitVerdict } = require('./ship-merge.js');
 const {
   buildGradePayload,
   buildPriorRoundContext,
@@ -303,6 +306,15 @@ module.exports = {
   // ship unless --db-only is explicitly passed. Exported pure so the gate is
   // unit-tested (has-commits / db-only / refuse) without git.
   zeroCommitVerdict,
+  // task 1002572 (PART 2): the single-checkout land fallback, pure halves only.
+  // landBailRecoverableByPr is the whole decision — which auto-merge bail a PR can
+  // still land (the main checkout holding the branch) versus which are REAL
+  // failures a PR would only carry to main. onMainNextStep is the recovery command
+  // for the other half of the catch-22, where no head branch exists to PR from.
+  LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH,
+  LAND_BAIL_NO_TASK_BRANCH,
+  landBailRecoverableByPr,
+  onMainNextStep,
   // touches[] cleanup [3/8] (task 878): folder-tag derivation, now over the
   // committed diff — exported pure so the regression test can assert it.
   deriveTagsFromPaths,

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.650'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.652'; // 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/boxes.mjs

@@ -170,7 +170,7 @@ t('selectIdleBoxes: guards bad inputs', () => {
   assert.deepEqual(boxes.selectIdleBoxes([], { idleMinutes: 30, nowMs: NaN }), []);
 });
 
-t('selectIdleBoxes: skips boxes where claude_active=true regardless of age', () => {
+t('selectIdleBoxes: with NO cap configured, claude_active=true skips regardless of age (pre-1003507 path)', () => {
   const rows = [
     // Old + claude running → kept alive.
     { state: 'active', github_login: 'clauding', last_activity_at: new Date(NOW - 60 * 60000).toISOString(), claude_active: true },
@@ -183,6 +183,114 @@ t('selectIdleBoxes: skips boxes where claude_active=true regardless of age', ()
   assert.deepEqual(idle.map((r) => r.github_login).sort(), ['idle', 'legacy']);
 });
 
+// --- task 1003507: the unattended cap ---------------------------------------
+//
+// The bug had TWO legs and either one alone kept an abandoned box alive:
+//   (1) claude_active is a latch only a ping can clear, and the sweep honoured it
+//       with no time bound at all -> unreapable at every threshold, forever;
+//   (2) load > 0.2 kept last_activity_at fresh, so the idle clock never expired.
+// The reported box had BOTH, which is why these tests model a FRESH heartbeat:
+// a fix that only bounds (1) leaves the box alive through (2) and looks green
+// against a stale-heartbeat fixture.
+const CAP = 12;
+const HOURS = (n) => n * 60 * 60000;
+const at = (ms) => new Date(ms).toISOString();
+
+// The reported incident, to scale: droplet up 5 days, heartbeat 5 min old, a
+// `claude` process running, nobody attached for 21h.
+const abandonedBox = () => ({
+  state: 'active', github_login: 'abandoned', claude_active: true,
+  claude_active_since: at(NOW - HOURS(21)),
+  last_activity_at: at(NOW - 5 * 60000),
+  last_attached_at: at(NOW - HOURS(21)),
+  active_since: at(NOW - 5 * 24 * 60 * 60000),
+});
+const swept = (rows, over = {}) => boxes.selectIdleBoxes(rows, {
+  idleMinutes: 30, nowMs: NOW, unattendedMaxHours: CAP, ...over,
+}).map((r) => r.github_login);
+
+t('selectIdleBoxes: an unattended box past the cap is reaped even with a FRESH heartbeat', () => {
+  // The regression that matters: last_activity_at is 5 min old, so the ordinary
+  // idle rule can never fire. Only the attachment clock catches this box.
+  assert.deepEqual(swept([abandonedBox()]), ['abandoned']);
+});
+
+t('selectIdleBoxes: a box with a human attached is spared regardless of the cap', () => {
+  assert.deepEqual(swept([{ ...abandonedBox(), last_attached_at: at(NOW - 10 * 60000) }]), []);
+  assert.deepEqual(swept([{ ...abandonedBox(), last_attached_at: at(NOW - HOURS(11)) }]), []);
+});
+
+t('selectIdleBoxes: the cap boundary', () => {
+  assert.deepEqual(swept([{ ...abandonedBox(), last_attached_at: at(NOW - HOURS(12) + 60000) }]), []);
+  assert.deepEqual(swept([{ ...abandonedBox(), last_attached_at: at(NOW - HOURS(12) - 60000) }]), ['abandoned']);
+});
+
+t('selectIdleBoxes: a latched claude_active box that stopped heartbeating is reaped', () => {
+  // Leg (1) on its own: silence cannot clear the flag, so before this fix the
+  // row survived every sweep at every threshold.
+  assert.deepEqual(swept([{
+    state: 'active', github_login: 'zombie', claude_active: true,
+    claude_active_since: at(NOW - 365 * 24 * 60 * 60000),
+    last_activity_at: at(NOW - 365 * 24 * 60 * 60000),
+    last_attached_at: null,
+  }]), ['zombie']);
+});
+
+t('selectIdleBoxes: a box with NO attachment data keeps the old behaviour', () => {
+  // A box still running the pre-1003507 heartbeat never reports `attached`, so
+  // last_attached_at stays NULL. NULL must read as "no data", never as
+  // "unattended" — otherwise this fix parks every un-upgraded box mid-work.
+  // (core_238 deliberately does not backfill the column for the same reason.)
+  assert.deepEqual(swept([{
+    state: 'active', github_login: 'legacy', claude_active: true,
+    claude_active_since: at(NOW - HOURS(2)),
+    last_activity_at: at(NOW - 5 * 60000),
+    last_attached_at: null,
+  }]), []);
+  // ...but it is still reapable the ordinary way once it goes quiet.
+  assert.deepEqual(swept([{
+    state: 'active', github_login: 'legacy2', claude_active: false,
+    last_activity_at: at(NOW - HOURS(1)), last_attached_at: null,
+  }]), ['legacy2']);
+});
+
+t('selectIdleBoxes: omitting the cap preserves the unbounded veto exactly', () => {
+  assert.deepEqual(swept([abandonedBox()], { unattendedMaxHours: undefined }), []);
+  assert.deepEqual(swept([abandonedBox()], { unattendedMaxHours: 0 }), []);
+});
+
+t('attendedRecently: NULL is unknown (true), not unattended', () => {
+  assert.equal(boxes.attendedRecently({ last_attached_at: null }, { nowMs: NOW, unattendedMaxHours: CAP }), true);
+  assert.equal(boxes.attendedRecently({ last_attached_at: at(NOW - HOURS(1)) }, { nowMs: NOW, unattendedMaxHours: CAP }), true);
+  assert.equal(boxes.attendedRecently({ last_attached_at: at(NOW - HOURS(20)) }, { nowMs: NOW, unattendedMaxHours: CAP }), false);
+  // No cap configured -> nothing is ever "unattended".
+  assert.equal(boxes.attendedRecently({ last_attached_at: at(NOW - HOURS(999)) }, { nowMs: NOW }), true);
+});
+
+t('claudeVetoHolds: a true flag with no recorded start is refused', () => {
+  // An unknown latch age is exactly the forever-latch being fixed, so it must
+  // NOT be honoured — core_238 stamps every box that is claude_active on deploy.
+  assert.equal(boxes.claudeVetoHolds(
+    { claude_active: true, claude_active_since: null }, { nowMs: NOW, unattendedMaxHours: CAP }
+  ), false);
+  assert.equal(boxes.claudeVetoHolds(
+    { claude_active: true, claude_active_since: at(NOW - HOURS(2)) }, { nowMs: NOW, unattendedMaxHours: CAP }
+  ), true);
+  assert.equal(boxes.claudeVetoHolds(
+    { claude_active: true, claude_active_since: at(NOW - HOURS(20)) }, { nowMs: NOW, unattendedMaxHours: CAP }
+  ), false);
+  assert.equal(boxes.claudeVetoHolds({ claude_active: false }, { nowMs: NOW, unattendedMaxHours: CAP }), false);
+});
+
+t('idleReason: names the clock that actually selected the box', () => {
+  const opts = { nowMs: NOW, idleMinutes: 30, unattendedMaxHours: CAP };
+  assert.match(boxes.idleReason(abandonedBox(), opts), /unattended 21h/);
+  assert.match(boxes.idleReason({
+    state: 'active', claude_active: false,
+    last_activity_at: at(NOW - HOURS(1)), last_attached_at: at(NOW - 60000),
+  }, opts), /idle 60m/);
+});
+
 t('selectDormantBoxes: picks parked boxes past the dormant threshold', () => {
   const rows = [
     { state: 'parked', github_login: 'gone', parked_at: new Date(NOW - 20 * DAY).toISOString() },
@@ -1264,6 +1372,7 @@ function sweepHarness({ idleRows, parkThrows = null }) {
     async listBoxes() { return idleRows; },
     selectIdleBoxes: boxes.selectIdleBoxes,
     effectiveActivityMs: boxes.effectiveActivityMs,
+    idleReason: boxes.idleReason,
     async setBoxState(_db, _bid, state, patch) { states.push({ state, patch }); return {}; },
     async recordComputeCost() { return 0; },
     async recordEvent(_db, e) { events.push(e); },
@@ -1321,17 +1430,65 @@ await ta('cmdSweepIdle: dry-run reports "would park" and touches nothing', async
   assert.equal(h.states.length, 0, 'no state written in dry-run');
 });
 
-await ta('cmdSweepIdle: a box running Claude is never parked mid-session', async () => {
+await ta('cmdSweepIdle: a box mid-session is never parked', async () => {
+  // Genuinely in use: Claude started 20 min ago and somebody is attached.
   const busy = {
     id: 4, builder_id: 4, state: 'active', droplet_id: '1', github_login: 'busy',
     last_activity_at: new Date(Date.now() - 99 * 3600_000).toISOString(), claude_active: true,
+    claude_active_since: new Date(Date.now() - 20 * 60_000).toISOString(),
+    last_attached_at: new Date(Date.now() - 20 * 60_000).toISOString(),
   };
   const h = sweepHarness({ idleRows: [busy] });
   const res = await boxCli.cmdSweepIdle({}, h.fakeBoxes, { apply: true });
-  assert.equal(res.parked, 0, 'claude_active holds the box open regardless of age');
+  assert.equal(res.parked, 0, 'a live session still holds the box open');
   assert.equal(h.states.length, 0);
 });
 
+await ta('cmdSweepIdle: task 1003507 — a box claiming claude_active for 99h with nobody attached IS parked', async () => {
+  // The reported incident, end to end through the command. Before this task the
+  // sweep skipped the row on claude_active alone and reported 0 idle; it now
+  // parks it (snapshot kept), and the log names the clock that selected it.
+  const abandoned = {
+    id: 5, builder_id: 5, state: 'active', droplet_id: '591743808', github_login: 'abandoned',
+    last_activity_at: new Date(Date.now() - 5 * 60_000).toISOString(),
+    claude_active: true,
+    claude_active_since: new Date(Date.now() - 99 * 3600_000).toISOString(),
+    last_attached_at: new Date(Date.now() - 99 * 3600_000).toISOString(),
+  };
+  const h = sweepHarness({ idleRows: [abandoned] });
+  const lines = [];
+  const origLog = console.log;
+  console.log = (...a) => lines.push(a.join(' '));
+  let res;
+  try {
+    res = await boxCli.cmdSweepIdle({}, h.fakeBoxes, { apply: false });
+  } finally { console.log = origLog; }
+  assert.equal(res.parked, 0, 'dry-run writes nothing');
+  assert.ok(lines.some((l) => /would park .*abandoned/.test(l)), 'the abandoned box is selected');
+  assert.ok(lines.some((l) => /unattended 99h/.test(l)), 'the log names the unattended clock, not the idle one');
+});
+
+await ta('loadDeps: task 1003507 — resolving deps does not throw ReferenceError', async () => {
+  // _deps was UNDECLARED, so loadDeps() threw on its first call and every
+  // command reaching makeDo()/makeCf() died with it — including
+  // `sweep-idle --apply`, which builds its DO client before the park loop, so
+  // the sweep could never park anything. Reached here through the same
+  // apply:true path that hid the bug: the assertion is that we get PAST dep
+  // resolution, whatever the fake DO client then does.
+  const row = {
+    id: 6, builder_id: 6, state: 'active', droplet_id: '1', github_login: 'reap',
+    last_activity_at: new Date(Date.now() - 99 * 3600_000).toISOString(), claude_active: false,
+  };
+  const h = sweepHarness({ idleRows: [row] });
+  const origLog = console.log;
+  console.log = () => {};
+  let err = null;
+  try {
+    await boxCli.cmdSweepIdle({}, h.fakeBoxes, { apply: true });
+  } catch (e) { err = e; } finally { console.log = origLog; }
+  assert.ok(!(err && /_deps is not defined/.test(err.message)), `loadDeps threw: ${err && err.message}`);
+});
+
 console.log('\ntask 1002727 — the dormant sweep warns before it takes:');
 
 const DORMANT_DAY = 86_400_000;