@bongos/core 1.19.77 → 1.19.79

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.77",
-  "core_contract": "1.19.77",
-  "source_commit": "a20aad3a45d55f5a39b9923d17ec460bfd504630",
+  "core_version": "1.19.79",
+  "core_contract": "1.19.79",
+  "source_commit": "ba59ac00319af3e83900b468e2feac5038806c60",
   "source_ref": "HEAD",
-  "built_at": "2026-08-12T22:40:06.341Z",
+  "built_at": "2026-08-12T22:56:44.247Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 295,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1541,
-  "tree_sha256": "3125b6aac967f4e3e3e323f3572eee2b53307f8f0acfb7699a40202bc966e354",
+  "tree_sha256": "351a95bc990504fb425ec46898380ecd98b6518301c81afc6046244459dd15e0",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2582,7 +2582,7 @@
     {
       "path": "modules/dev-box/box-access.js",
       "mode": "0000644",
-      "sha256": "2afd598f687392b313dc872e73d4e6b61af27ce96d140685268ea5697955d636"
+      "sha256": "8d2dc69a139a5a658866a18527efeb5d9ae989e05883fa6cbd0ea63db0ba9476"
     },
     {
       "path": "modules/dev-box/box-credential.js",
@@ -2597,7 +2597,7 @@
     {
       "path": "modules/dev-box/boxes.js",
       "mode": "0000644",
-      "sha256": "fbf9bb7bd4c70ac81627d7d473a94e98e6976581bc29f60c5342d428a39238cf"
+      "sha256": "a56b75218b3ac3fed0bb495b9c7f41b2794dafa5f3e6ec28cbb21a97e9b25b7b"
     },
     {
       "path": "modules/dev-box/db.js",
@@ -2612,7 +2612,7 @@
     {
       "path": "modules/dev-box/routes/box.js",
       "mode": "0000644",
-      "sha256": "a9f51c0ddc4fc8c558d0c6dde77ffcd3e1b1262a6f14f93c88e1bb3e9093538d"
+      "sha256": "ba75c28d8927ebbda1482f394a0062febc6e32a52863814d00d6ad2a6667a591"
     },
     {
       "path": "modules/discord/CLAUDE.md",
@@ -3402,7 +3402,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "bc1526d068698e489fc2a698c04418e60097f18b56fd5c0dcdb6a6f62bbd1c81"
+      "sha256": "5e7dc6c267384eb3b691f49ec82631425151b97d2208eaf342922bf46146965f"
     },
     {
       "path": "modules/lifecycle/done-when.js",
@@ -3437,7 +3437,7 @@
     {
       "path": "modules/lifecycle/lifecycle.js",
       "mode": "0000644",
-      "sha256": "5c0d0da5d6a8bcfb920bc432558066840e649cbc624e064dc4e55a926a3d8bb4"
+      "sha256": "8f62f50c5a81d649df6b85ef7c89e57a0bf0e8877482693861a4f9cd5cfafe5a"
     },
     {
       "path": "modules/lifecycle/merge-lock.js",
@@ -4057,12 +4057,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ffd10996e222dd7fe49aa05ad7177979e18cb7871ee3666f2cc96c9822e8075e"
+      "sha256": "c96137763abb2061735f0a815401ead7047d116c5eb6dd538178e9e23c9ca0bd"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "3cdd1266637cfb67eed301d96a9f6414d32d98f1d4e9033e20aa6687806526c3"
+      "sha256": "97227cfa1c95b171af85bd2f248f894ebe6f8795cd9364b6dc87180fc00e445e"
     },
     {
       "path": "public-docs/index.html",
@@ -4557,7 +4557,7 @@
     {
       "path": "scripts/gds/box.js",
       "mode": "0000644",
-      "sha256": "41e1a0c0ef56d5cf10cc73124964c114854a12d8dd3de249d4bafcda04dd2106"
+      "sha256": "117b0ed6730e35559356403b50240d0ef5b6ab46752a8cf76de4e0a8ad244d42"
     },
     {
       "path": "scripts/gds/build-bongos.js",
@@ -5687,7 +5687,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "fee8a499a0208f8f825a317e5ab631684bcb2c718dde601e6eab23eda5f2728c"
+      "sha256": "ff17cf82d49bb2e21188381d9621bbf4f5cf61ac3e49b10ea5ea32685d170c14"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -6032,7 +6032,7 @@
     {
       "path": "tests/box_task_scope.mjs",
       "mode": "0000644",
-      "sha256": "e6cb9f94ae75fc9dd9134c85d8074bfe008eadd64eaddb0df2f1d6d851683c36"
+      "sha256": "22a2dc8bdccb9900b642371b85e8cc1785ecfacaf8f7579b042951425d95d794"
     },
     {
       "path": "tests/box_terminal_ssrf.mjs",
@@ -6042,7 +6042,7 @@
     {
       "path": "tests/boxes.mjs",
       "mode": "0000644",
-      "sha256": "8702916e37e8cc08ae0e055b1bc7ea70da71720c51bd2a05df2a4dc598a17f97"
+      "sha256": "5a8d2ca5709f2c4ae5089b53883a5a892beeb6920bacbddbd352b106c4ec0e34"
     },
     {
       "path": "tests/branding.mjs",

package/modules/dev-box/box-access.js

@@ -203,18 +203,33 @@ function sparsePathsForScopeKeys(scopeKeys, moduleScopeMap) {
 // + passed by the route in R94) selects the surface, three ways:
 //   - scopeKeys is a NON-EMPTY array → TASK scope: BASE ∪ the claims' module dirs
 //     (via sparsePathsForScopeKeys + the passed-in `moduleScopeMap`).
-//   - scopeKeys is an EMPTY array     → BASE-only (a live box with no active claim /
-//     no scoped goal — the pre-existing Bongos instance, nothing extra).
+//   - scopeKeys is an EMPTY array     → depends on whether the builder is actually
+//     working (see `hasActiveClaims` below).
 //   - scopeKeys is ABSENT (undefined) → the pre-ADR-0148 RANK fallback (full for
 //     Metic+, else the starter sparse surface). This is the path a vanilla instance
 //     with no lifecycle port takes, and it preserves the old behavior EXACTLY — so
 //     shipping R93 before R94 wires the route changes nothing in production.
 //
+// TASK 1002729 — the empty-array case is NOT one case, it is two, and collapsing
+// them was a live defect. moduleScopeForActiveClaims returns [] both when the
+// builder holds no claim AND when they hold claims whose goals declare no
+// scope_modules (the goal wall is optional; only 13 of 46 goals on the live
+// instance declared one). Treating the second as "no scope" handed a working
+// builder a box with NO modules/ directory at all — less code than the rank
+// fallback would have given a newcomer. On the live fleet that was 247 of 248
+// source grants, including an Archon holding 7 active claims.
+//   - [] + hasActiveClaims true  → RANK fallback. The builder is working; an
+//     undeclared goal wall is a planning gap, and it must not cripple their box.
+//   - [] + hasActiveClaims false → BASE-only, as before (a genuinely unscoped box
+//     — the pre-existing Bongos instance, nothing extra). Least privilege holds.
+// `hasActiveClaims` is optional: omitted (undefined) preserves the old BASE-only
+// reading, so a caller that hasn't been taught the signal is unchanged.
+//
 // Returns one of:
 //   { allowed:false, reason:'BUILDER_INACTIVE' }
 //   { allowed:false, reason:'INSUFFICIENT_RANK', required, actual }
 //   { allowed:true,  scope, spec }
-function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, scopeKeys, moduleScopeMap } = {}) {
+function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, scopeKeys, hasActiveClaims, moduleScopeMap } = {}) {
   if (status && status !== 'active') {
     return { allowed: false, reason: 'BUILDER_INACTIVE' };
   }
@@ -228,11 +243,19 @@ function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, sco
   }
   // Claim-driven task scope (present → the box asks for exactly its work's code).
   if (Array.isArray(scopeKeys)) {
-    const sparsePaths = sparsePathsForScopeKeys(scopeKeys, moduleScopeMap);
-    const scope = scopeKeys.length > 0 ? 'task' : 'base';
-    return { allowed: true, scope, spec: { scope, mode: 'sparse', sparsePaths } };
+    if (scopeKeys.length > 0) {
+      const sparsePaths = sparsePathsForScopeKeys(scopeKeys, moduleScopeMap);
+      return { allowed: true, scope: 'task', spec: { scope: 'task', mode: 'sparse', sparsePaths } };
+    }
+    // Empty. A builder mid-claim whose goals declare no wall gets the rank scope,
+    // NOT a stripped box — the planning gap is not theirs to pay for.
+    if (!hasActiveClaims) {
+      const sparsePaths = sparsePathsForScopeKeys([], moduleScopeMap);
+      return { allowed: true, scope: 'base', spec: { scope: 'base', mode: 'sparse', sparsePaths } };
+    }
   }
-  // No claim signal (no lifecycle port on this instance): the pre-ADR-0148 rank fallback.
+  // No claim signal (no lifecycle port on this instance), or claims with an
+  // undeclared goal wall: the pre-ADR-0148 rank fallback.
   const scope = boxScopeForRank(rank);
   return { allowed: true, scope, spec: cloneSpecForScope(scope) };
 }

package/modules/dev-box/boxes.js

@@ -182,6 +182,10 @@ function selectIdleBoxes(rows, { idleMinutes, nowMs } = {}) {
 
 // Dormant = parked boxes that have been parked longer than dormantDays. These
 // get fully de-provisioned (snapshot deleted too) to reclaim the last cents.
+// Since task 1002726 this is the ONLY automated path that destroys a snapshot —
+// the idle sweep parks and preserves one — so it is the last thing standing
+// between a builder and losing uncommitted work. Task 1002727 gates it on a
+// delivered warning.
 function selectDormantBoxes(rows, { dormantDays, nowMs } = {}) {
   if (!Number.isFinite(dormantDays) || dormantDays <= 0) return [];
   if (!Number.isFinite(nowMs)) return [];
@@ -193,6 +197,40 @@ function selectDormantBoxes(rows, { dormantDays, nowMs } = {}) {
   });
 }
 
+// Task 1002727 — the WARNING window: parked long enough to be heading for
+// reclaim, but not yet reclaimable. A box here gets one heads-up so its builder
+// can wake it (or accept the loss) before the snapshot goes. Boxes already past
+// dormantDays are excluded — they belong to selectDormantBoxes, which refuses to
+// reclaim an unwarned box. Pure; the caller injects nowMs.
+function selectDormantWarnBoxes(rows, { dormantDays, warnLeadDays, nowMs } = {}) {
+  if (!Number.isFinite(dormantDays) || dormantDays <= 0) return [];
+  if (!Number.isFinite(warnLeadDays) || warnLeadDays <= 0) return [];
+  if (!Number.isFinite(nowMs)) return [];
+  const warnAfter = nowMs - Math.max(dormantDays - warnLeadDays, 0) * 86_400_000;
+  const reclaimAfter = nowMs - dormantDays * 86_400_000;
+  return (rows || []).filter((r) => {
+    if (r.state !== 'parked') return false;
+    const p = toMs(r.parked_at);
+    return p != null && p <= warnAfter && p > reclaimAfter;
+  });
+}
+
+// Task 1002727 — was this box already warned during its CURRENT parked interval?
+// box_events is the state store, so this needs no schema change: a
+// 'dormant_warning' row written at or after parked_at is the receipt. Keying on
+// parked_at (rather than just the newest event) means a wake→park cycle re-arms
+// the warning instead of reusing a stale one from a previous park.
+async function hasDormantWarning(db, { boxId, parkedAt } = {}) {
+  if (!boxId || !parkedAt) return false;
+  const { rows } = await db.query(
+    `SELECT 1 FROM box_events
+      WHERE box_id = $1 AND event = 'dormant_warning' AND created_at >= $2
+      LIMIT 1`,
+    [boxId, parkedAt]
+  );
+  return rows.length > 0;
+}
+
 // ---------------------------------------------------------------------------
 // PURE: state-transition legality
 // ---------------------------------------------------------------------------
@@ -834,6 +872,8 @@ module.exports = {
   effectiveActivityMs,
   selectIdleBoxes,
   selectDormantBoxes,
+  selectDormantWarnBoxes,
+  hasDormantWarning,
   // pure — transitions
   TRANSITIONS,
   canTransition,

package/modules/dev-box/routes/box.js

@@ -444,6 +444,7 @@ module.exports = function buildBoxRouter() {
       // NEVER fail the source fetch on a scope-read hiccup — degrade to rank scope.
       const lifecycle = api.resolveOptional('lifecycle');
       let scopeKeys;
+      let hasActiveClaims;
       if (lifecycle && typeof lifecycle.moduleScopeForActiveClaims === 'function') {
         try {
           scopeKeys = await lifecycle.moduleScopeForActiveClaims(req.builder.id);
@@ -452,7 +453,19 @@ module.exports = function buildBoxRouter() {
           scopeKeys = undefined;
         }
       }
-      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, moduleScopeMap: api.moduleScopeMap });
+      // task 1002729 — only needed to disambiguate an EMPTY scope: no claim (BASE)
+      // vs claims whose goals declare no wall (rank scope). Skipped otherwise so
+      // the common path keeps its single query.
+      if (Array.isArray(scopeKeys) && scopeKeys.length === 0
+          && lifecycle && typeof lifecycle.activeClaimCountForBuilder === 'function') {
+        try {
+          hasActiveClaims = (await lifecycle.activeClaimCountForBuilder(req.builder.id)) > 0;
+        } catch (claimErr) {
+          console.error('[gds] source-access claim-count read (non-fatal, → BASE)', claimErr && claimErr.message ? claimErr.message : claimErr);
+          hasActiveClaims = undefined;
+        }
+      }
+      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap });
       const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
       const auditDeny = (reason, extra) =>
         box && boxAccess.recordSourceEvent(pool, {
@@ -548,6 +561,7 @@ module.exports = function buildBoxRouter() {
       // (optional lifecycle port; degrade to rank scope on any hiccup).
       const lifecycle = api.resolveOptional('lifecycle');
       let scopeKeys;
+      let hasActiveClaims;
       if (lifecycle && typeof lifecycle.moduleScopeForActiveClaims === 'function') {
         try {
           scopeKeys = await lifecycle.moduleScopeForActiveClaims(req.builder.id);
@@ -556,7 +570,18 @@ module.exports = function buildBoxRouter() {
           scopeKeys = undefined;
         }
       }
-      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, moduleScopeMap: api.moduleScopeMap });
+      // task 1002729 — same disambiguation as source-access, so this read-only
+      // companion can never report a scope the real fetch wouldn't grant.
+      if (Array.isArray(scopeKeys) && scopeKeys.length === 0
+          && lifecycle && typeof lifecycle.activeClaimCountForBuilder === 'function') {
+        try {
+          hasActiveClaims = (await lifecycle.activeClaimCountForBuilder(req.builder.id)) > 0;
+        } catch (claimErr) {
+          console.error('[gds] /box/scope claim-count read (non-fatal, → BASE)', claimErr && claimErr.message ? claimErr.message : claimErr);
+          hasActiveClaims = undefined;
+        }
+      }
+      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap });
       if (!decision.allowed) {
         return res.fail('SOURCE_ACCESS_REVOKED', 403, {
           reason: decision.reason,

package/modules/lifecycle/db.js

@@ -4756,6 +4756,29 @@ async function moduleScopeForActiveClaims(builderId, deps = {}) {
   return rows.map((r) => r.module_key);
 }
 
+// Task 1002729 — the companion signal moduleScopeForActiveClaims cannot carry.
+// That query INNER JOINs goals and unnests scope_modules, so it returns [] for
+// BOTH "this builder holds no claim" and "this builder holds claims whose goals
+// declare no scope_modules". Those must not be treated alike: the first is a
+// genuinely unscoped box (BASE-only is right), the second is a builder actively
+// working who would be handed a box with no modules/ at all. Live evidence for
+// why this matters: 247 of 248 source grants on the cloudbongos fleet resolved to
+// BASE, including an Archon holding 7 active claims — every one of those claims
+// sat on a goal with scope_modules = {}. Counts CLAIMS, deliberately not joining
+// goals, so it stays true regardless of how the goal wall is (or isn't) declared.
+async function activeClaimCountForBuilder(builderId, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const id = Number(builderId);
+  if (!Number.isInteger(id)) {
+    throw new Error('activeClaimCountForBuilder: builderId must be numeric');
+  }
+  const { rows } = await activePool.query(
+    `SELECT count(*)::int AS n FROM claims WHERE builder_id = $1 AND released_at IS NULL`,
+    [id]
+  );
+  return rows.length ? Number(rows[0].n) : 0;
+}
+
 // task 1642 — every active claim bound to a given CLI session. "Active" is the
 // claims-table convention (released_at IS NULL); there is NO `status` column on
 // claims (a common misread — the task's status lives on `tasks`). Keyed on
@@ -5625,6 +5648,7 @@ module.exports = {
   getClaimPublishedSha, // task 1547 — read the published tip for the reconcile gate
   getActiveClaimsForBuilder,
   moduleScopeForActiveClaims, // goal 1000051 / R92 — dev-box task-scoped source access (ADR 0148 §2)
+  activeClaimCountForBuilder, // task 1002729 — distinguishes "no claim" from "claim with an empty goal wall"
   getActiveClaimsForSession,
   getLastClaimHolder, // --regrade ownership guard (#678)
   getTaskGrade,       // V4.R08 — diff-hash reuse check before grading

package/modules/lifecycle/lifecycle.js

@@ -65,4 +65,7 @@ module.exports = {
   // resolver (goal 1000051 / R92, ADR 0148 §2). Keys only; box-access maps them to
   // git sparse-checkout globs through the doorway `moduleScopeMap`.
   moduleScopeForActiveClaims: (...a) => db.moduleScopeForActiveClaims(...a),
+  // task 1002729 — the "is this builder actually working right now" signal that
+  // lets box-access tell an unscoped box from a crippled one (see db.js).
+  activeClaimCountForBuilder: (...a) => db.activeClaimCountForBuilder(...a),
 };

package/package-lock.json

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

package/package.json

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

package/scripts/gds/box.js

@@ -15,7 +15,8 @@
 //   wake      <builder>   recreate the droplet from its snapshot
 //   deprovision <builder> destroy droplet AND snapshot (full reclaim)
 //   sweep-idle            PARK every active box idle > BOX_IDLE_MINUTES (snapshot kept)
-//   sweep-dormant         deprovision every box parked > BOX_DORMANT_DAYS (pings builder)
+//   sweep-dormant         warn, then deprovision every box parked > BOX_DORMANT_DAYS
+//                         (the ONLY automated path that destroys a snapshot)
 //   status                print the box roster + estimated cost
 //
 // <builder> is a GitHub login or a numeric builder id.
@@ -102,6 +103,8 @@ const CONFIG = {
   baseImage: process.env.BOX_BASE_IMAGE || 'ubuntu-24-04-x64',
   idleMinutes: numEnv('BOX_IDLE_MINUTES', 10),
   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),
   sshKeyIds: (process.env.BOX_SSH_KEY_IDS || '').split(',').map((s) => s.trim()).filter(Boolean),
   dnsHook: process.env.BOX_DNS_HOOK || null,
   tag: process.env.BOX_TAG || 'otb-builder-box',
@@ -1051,27 +1054,71 @@ async function cmdSweepIdle(pool, boxes, { apply }) {
 }
 
 // ---- sweep-dormant ---------------------------------------------------------
+// Task 1002727 — since the idle sweep parks rather than destroys (task 1002726),
+// this is the ONLY automated path that deletes a snapshot, i.e. the only one that
+// can take a builder's uncommitted work. So it warns before it takes: a box
+// entering the warning window gets one heads-up, and a box past the threshold is
+// reclaimed ONLY if that warning was actually delivered during its current parked
+// interval. If it never was — runner downtime, a chat outage, a box that sailed
+// past the window while the sweep was off — the reclaim is DEFERRED and the
+// warning is sent instead. That way "no automated path silently discards work"
+// holds even when the machinery itself misbehaves.
 
 async function cmdSweepDormant(pool, boxes, { apply }) {
   const rows = await boxes.listBoxes(pool, { state: 'parked' });
-  const dormant = boxes.selectDormantBoxes(rows, { dormantDays: CONFIG.dormantDays, nowMs: Date.now() });
-  console.log(`dormant sweep (threshold=${CONFIG.dormantDays}d${apply ? '' : ', dry-run'}): ${dormant.length} of ${rows.length} parked box(es) dormant`);
-  if (dormant.length === 0) { console.log('  nothing dormant — exit clean'); return { reclaimed: 0 }; }
-  const doApi = apply ? makeDo(apply) : null;
-  let reclaimed = 0, errors = 0, pingFailed = 0;
+  const now = Date.now();
+  const dormant = boxes.selectDormantBoxes(rows, { dormantDays: CONFIG.dormantDays, nowMs: now });
+  const warnAt = Math.max(CONFIG.dormantDays - CONFIG.dormantWarnLeadDays, 0);
+  const warning = boxes.selectDormantWarnBoxes(rows, {
+    dormantDays: CONFIG.dormantDays, warnLeadDays: CONFIG.dormantWarnLeadDays, nowMs: now,
+  });
+  console.log(`dormant sweep (reclaim >${CONFIG.dormantDays}d, warn >${warnAt}d${apply ? '' : ', dry-run'}): ${dormant.length} dormant, ${warning.length} entering the warning window, of ${rows.length} parked`);
+  if (dormant.length === 0 && warning.length === 0) { console.log('  nothing dormant — exit clean'); return { reclaimed: 0, warned: 0, deferred: 0 }; }
+  // Built lazily: a sweep that only WARNS must not require a DO token.
+  let doApi = null;
+  const needDo = () => (doApi || (doApi = makeDo(apply)));
+  let reclaimed = 0, errors = 0, pingFailed = 0, warned = 0, deferred = 0;
+
+  const sendWarning = async (box, days) => {
+    const left = Math.max(CONFIG.dormantDays - days, 0);
+    const ping = postReclaimPing(`@${box.github_login} — your dev box has been parked ${days} days. Its saved disk image will be reclaimed in ${left} day(s) to save cost, and anything on it you haven't pushed will be gone with it. Wake it any time with POST /api/gds/box/ensure to keep it.`);
+    if (!ping.ok) { pingFailed++; return false; }
+    await boxes.recordEvent(pool, {
+      boxId: box.id, builderId: box.builder_id, event: 'dormant_warning',
+      detail: `parked ${days}d; reclaim in ${left}d`, actor: 'sweep:dormant',
+    });
+    warned++;
+    return true;
+  };
+
+  for (const box of warning) {
+    const days = Math.round((now - Date.parse(box.parked_at)) / 86400000);
+    if (!apply) { console.log(`  would warn @${box.github_login} (parked ${days}d)`); continue; }
+    if (await boxes.hasDormantWarning(pool, { boxId: box.id, parkedAt: box.parked_at })) continue;
+    const ok = await sendWarning(box, days);
+    console.log(`  ${ok ? '✓ warned' : '✖ warning FAILED for'} @${box.github_login} (parked ${days}d)`);
+  }
+
   for (const box of dormant) {
-    const days = Math.round((Date.now() - Date.parse(box.parked_at)) / 86400000);
+    const days = Math.round((now - Date.parse(box.parked_at)) / 86400000);
     if (!apply) { console.log(`  would reclaim @${box.github_login}'s box (parked ${days}d, snapshot ${box.snapshot_id})`); continue; }
+    // The gate: no receipt, no reclaim. Warn now, let a later sweep take it.
+    if (!(await boxes.hasDormantWarning(pool, { boxId: box.id, parkedAt: box.parked_at }))) {
+      deferred++;
+      const ok = await sendWarning(box, days);
+      console.log(`  ⏸ deferred @${box.github_login} (parked ${days}d) — never warned; ${ok ? 'warning sent, reclaim next sweep' : 'warning FAILED, will retry'}`);
+      continue;
+    }
     try {
-      await deprovisionOne(pool, boxes, doApi, box, { actor: 'sweep:dormant' });
+      await deprovisionOne(pool, boxes, needDo(), box, { actor: 'sweep:dormant' });
       reclaimed++;
-      const ping = postReclaimPing(`@${box.github_login} — your dev box was idle for ${days} days and has been reclaimed to save cost. Queue a fresh one anytime with POST /api/gds/box/ensure (no operator needed); your memory is server-side and unaffected.`);
+      const ping = postReclaimPing(`@${box.github_login} — your dev box was parked for ${days} days and has now been reclaimed to save cost, as warned. Queue a fresh one anytime with POST /api/gds/box/ensure (no operator needed); your memory is server-side and unaffected.`);
       if (!ping.ok) pingFailed++;
       console.log(`  ✓ reclaimed @${box.github_login} (parked ${days}d)${ping.ok ? '' : ' [chat ping failed]'}`);
     } catch (e) { errors++; await markErrorUnlessDestroyed(pool, boxes, box.builder_id, e.message); console.log(`  ✖ @${box.github_login}: ${e.message}`); }
   }
-  console.log(`done — reclaimed=${reclaimed} ping-failed=${pingFailed} errors=${errors} dry-run=${!apply}`);
-  return { reclaimed, errors, pingFailed };
+  console.log(`done — reclaimed=${reclaimed} warned=${warned} deferred=${deferred} ping-failed=${pingFailed} errors=${errors} dry-run=${!apply}`);
+  return { reclaimed, warned, deferred, errors, pingFailed };
 }
 
 // ---- reconcile (source-access clawback) ------------------------------------
@@ -1369,7 +1416,8 @@ Commands:
   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-dormant          deprovision boxes parked > ${CONFIG.dormantDays}d (pings builder)
+  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
                          boxes, rescope graduated ones (ADR 0031 §6, #600)
   reconcile-drift        repair DO⇄DB drift BOTH ways (task 1289): force-delete
@@ -1441,4 +1489,4 @@ async function main() {
 
 if (require.main === module) main();
 
-module.exports = { cmdProvision, deprovisionOne, parkOne, cmdSweepIdle, deleteWithRetry, cmdReconcileDrift, runDnsHook, runDnsHookBlackhole, markErrorUnlessDestroyed, resolveBoxInfraDir, boxInfraCandidates, readCloudInit, BOX_INFRA_TEMPLATE };
+module.exports = { cmdProvision, deprovisionOne, parkOne, cmdSweepIdle, cmdSweepDormant, deleteWithRetry, cmdReconcileDrift, runDnsHook, runDnsHookBlackhole, markErrorUnlessDestroyed, resolveBoxInfraDir, boxInfraCandidates, readCloudInit, BOX_INFRA_TEMPLATE };

package/src/module-api.js

@@ -581,8 +581,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.75 with no explicit bump. run 31637719876. (task 1002620)
 //   1.19.77 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.76 with no explicit bump. run 31647860631. (task 1002620)
+//   1.19.78 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.77 with no explicit bump. run 31648127800. (task 1002620)
+//   1.19.79 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.78 with no explicit bump. run 31648954641. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.77'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.79'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/box_task_scope.mjs

@@ -96,4 +96,74 @@ await test('an inactive builder is denied even with claims in scope', async () =
   assert.equal(inactive.decision.reason, 'BUILDER_INACTIVE');
 });
 
+// =========================================================================
+// Task 1002729 — an EMPTY scope is two different situations, not one
+// =========================================================================
+// The live defect: moduleScopeForActiveClaims returns [] both for "holds no
+// claim" and for "holds claims whose goals declare no scope_modules". Reading
+// both as BASE handed working builders a box with no modules/ at all — 247 of
+// 248 grants on the live fleet, including an Archon with 7 active claims.
+
+// A pool that answers BOTH queries the resolver pair now issues: the
+// claims→goals→scope_modules unnest, and the plain active-claim count.
+function poolReturningWithClaims(moduleKeyRows, claimCount) {
+  const c = makeSqlAwareClient((s) => {
+    if (/FROM claims c/.test(s) && /unnest\(g\.scope_modules\)/.test(s)) return { rows: moduleKeyRows };
+    if (/count\(\*\)/.test(s) && /FROM claims/.test(s)) return { rows: [{ n: claimCount }] };
+    return null;
+  });
+  return { query: (sql, params) => c._client.query(sql, params), connect: c.connect, queries: c._client.queries };
+}
+
+async function specForClaimsWithCount({ builderId = 3, rank = 'metic', status = 'active', moduleKeyRows, claimCount }) {
+  const pool = poolReturningWithClaims(moduleKeyRows, claimCount);
+  const scopeKeys = await db.moduleScopeForActiveClaims(builderId, { pool });
+  const hasActiveClaims = (await db.activeClaimCountForBuilder(builderId, { pool })) > 0;
+  return { scopeKeys, hasActiveClaims, decision: access.decideSourceAccess({ rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: scopeMap }) };
+}
+
+await test('claims held but every goal wall empty → RANK scope, never a stripped box', async () => {
+  // Exactly Lars's live shape: 7 active claims, all on goals with scope_modules={}.
+  const { scopeKeys, hasActiveClaims, decision } = await specForClaimsWithCount({
+    rank: 'archon', moduleKeyRows: [], claimCount: 7,
+  });
+  assert.deepEqual(scopeKeys, [], 'the union query still yields nothing — the goals declare no wall');
+  assert.equal(hasActiveClaims, true, 'but the builder IS working');
+  assert.equal(decision.scope, 'full', 'an Archon mid-claim gets the full surface, not base');
+  assert.equal(decision.spec.mode, 'full');
+  assert.notEqual(decision.scope, 'base', 'the regression this test exists to prevent');
+});
+
+await test('no claims at all → BASE-only is preserved (least privilege holds)', async () => {
+  const { hasActiveClaims, decision } = await specForClaimsWithCount({
+    rank: 'archon', moduleKeyRows: [], claimCount: 0,
+  });
+  assert.equal(hasActiveClaims, false);
+  assert.equal(decision.scope, 'base', 'an idle box is still not handed the repo');
+  assert.deepEqual(decision.spec.sparsePaths, [...BASE]);
+});
+
+await test('a declared goal wall still wins over the rank fallback', async () => {
+  // Claims AND a wall → task scope, exactly as before; the fix must not widen this.
+  const { decision } = await specForClaimsWithCount({
+    rank: 'archon', moduleKeyRows: [{ module_key: 'status-ui' }], claimCount: 2,
+  });
+  assert.equal(decision.scope, 'task', 'a real wall is still honoured, not overridden by rank');
+  assert.deepEqual(decision.spec.sparsePaths, [...BASE, 'modules/status-ui']);
+});
+
+await test('a Thetes mid-claim with no wall gets STARTER, not full — rank still bounds it', async () => {
+  const { decision } = await specForClaimsWithCount({
+    rank: 'thetes', moduleKeyRows: [], claimCount: 1,
+  });
+  assert.equal(decision.scope, 'starter', 'the fallback is rank-bounded; it is not a blanket widen');
+});
+
+await test('activeClaimCountForBuilder rejects a non-numeric builder id', async () => {
+  await assert.rejects(
+    () => db.activeClaimCountForBuilder('not-a-number', { pool: poolReturningWithClaims([], 0) }),
+    /must be numeric/,
+  );
+});
+
 summary();

package/tests/boxes.mjs

@@ -1332,5 +1332,97 @@ await ta('cmdSweepIdle: a box running Claude is never parked mid-session', async
   assert.equal(h.states.length, 0);
 });
 
+console.log('\ntask 1002727 — the dormant sweep warns before it takes:');
+
+const DORMANT_DAY = 86_400_000;
+const parked = (d, extra = {}) => ({
+  id: 9, builder_id: 9, state: 'parked', github_login: 'sleeper', snapshot_id: 's1',
+  parked_at: new Date(NOW - d * DORMANT_DAY).toISOString(), ...extra,
+});
+
+t('selectDormantWarnBoxes: picks boxes in the lead window, not before, not after', () => {
+  const rows = [parked(10), parked(12), parked(15), parked(3)];
+  const warn = boxes.selectDormantWarnBoxes(rows, { dormantDays: 14, warnLeadDays: 3, nowMs: NOW });
+  const days = warn.map((r) => Math.round((NOW - Date.parse(r.parked_at)) / DORMANT_DAY)).sort((a, b) => a - b);
+  assert.deepEqual(days, [12], 'only the box inside [11d, 14d) is warned');
+});
+
+t('selectDormantWarnBoxes: a box already past the threshold is NOT in the warn set', () => {
+  // It belongs to selectDormantBoxes, which refuses to reclaim it unwarned.
+  const warn = boxes.selectDormantWarnBoxes([parked(20)], { dormantDays: 14, warnLeadDays: 3, nowMs: NOW });
+  assert.equal(warn.length, 0);
+});
+
+t('selectDormantWarnBoxes: guards bad inputs', () => {
+  assert.deepEqual(boxes.selectDormantWarnBoxes(null, { dormantDays: 14, warnLeadDays: 3, nowMs: NOW }), []);
+  assert.deepEqual(boxes.selectDormantWarnBoxes([], { dormantDays: 0, warnLeadDays: 3, nowMs: NOW }), []);
+  assert.deepEqual(boxes.selectDormantWarnBoxes([], { dormantDays: 14, warnLeadDays: 0, nowMs: NOW }), []);
+  assert.deepEqual(boxes.selectDormantWarnBoxes([], { dormantDays: 14, warnLeadDays: 3, nowMs: NaN }), []);
+});
+
+await ta('hasDormantWarning: keyed on the CURRENT parked interval, so a re-park re-arms', async () => {
+  const seen = [];
+  const db = { async query(sql, params) { seen.push({ sql, params }); return { rows: [] }; } };
+  const parkedAt = new Date(NOW - 5 * DORMANT_DAY).toISOString();
+  const got = await boxes.hasDormantWarning(db, { boxId: 9, parkedAt });
+  assert.equal(got, false, 'no receipt → not warned');
+  assert.match(seen[0].sql, /dormant_warning/);
+  assert.match(seen[0].sql, /created_at >= \$2/, 'scoped to events AFTER this park, not any historical one');
+  assert.deepEqual(seen[0].params, [9, parkedAt]);
+});
+
+await ta('hasDormantWarning: a missing box id or parked_at is false, never a query', async () => {
+  const db = { async query() { throw new Error('should not query'); } };
+  assert.equal(await boxes.hasDormantWarning(db, { boxId: null, parkedAt: 'x' }), false);
+  assert.equal(await boxes.hasDormantWarning(db, { boxId: 9, parkedAt: null }), false);
+});
+
+await ta('cmdSweepDormant: a box past the threshold that was NEVER warned is DEFERRED, not reclaimed', async () => {
+  // The safety property: even if the warning window was missed entirely (runner
+  // downtime, chat outage), the snapshot is not destroyed on this pass.
+  const box = parked(30);
+  const destroyed = [];
+  const events = [];
+  const fakeBoxes = {
+    async listBoxes() { return [box]; },
+    selectDormantBoxes: boxes.selectDormantBoxes,
+    selectDormantWarnBoxes: boxes.selectDormantWarnBoxes,
+    async hasDormantWarning() { return false; },      // never warned
+    async recordEvent(_db, e) { events.push(e); },
+    async setBoxState() { return {}; },
+    async recordComputeCost() { return 0; },
+    async recordStorageCost() { return 0; },
+    async getBoxByBuilderId() { return { state: 'parked' }; },
+  };
+  const lines = [];
+  const origLog = console.log;
+  console.log = (...a) => lines.push(a.join(' '));
+  let res;
+  try { res = await boxCli.cmdSweepDormant({}, fakeBoxes, { apply: true }); }
+  finally { console.log = origLog; }
+  assert.equal(res.reclaimed, 0, 'NOTHING reclaimed without a delivered warning');
+  assert.equal(res.deferred, 1, 'the reclaim is deferred to a later sweep');
+  assert.equal(destroyed.length, 0);
+  assert.ok(lines.some((l) => /deferred/.test(l)), 'the deferral is logged, not silent');
+});
+
+await ta('cmdSweepDormant: dry-run reclaims and warns nothing', async () => {
+  const fakeBoxes = {
+    async listBoxes() { return [parked(30), parked(12)]; },
+    selectDormantBoxes: boxes.selectDormantBoxes,
+    selectDormantWarnBoxes: boxes.selectDormantWarnBoxes,
+    async hasDormantWarning() { return true; },
+    async recordEvent() { throw new Error('dry-run must not write'); },
+    async setBoxState() { throw new Error('dry-run must not write'); },
+  };
+  const origLog = console.log;
+  console.log = () => {};
+  let res;
+  try { res = await boxCli.cmdSweepDormant({}, fakeBoxes, { apply: false }); }
+  finally { console.log = origLog; }
+  assert.equal(res.reclaimed, 0);
+  assert.equal(res.warned, 0);
+});
+
 console.log(`\nboxes.mjs: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);