@bongos/core 1.19.78 → 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.78",
-  "core_contract": "1.19.78",
-  "source_commit": "e325ccc071131d7c01dbf333d8f7cd57ae312039",
+  "core_version": "1.19.79",
+  "core_contract": "1.19.79",
+  "source_commit": "ba59ac00319af3e83900b468e2feac5038806c60",
   "source_ref": "HEAD",
-  "built_at": "2026-08-12T22:44:08.133Z",
+  "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": "96bcb5ac17be8a28801e81faab41c95d0b6b2bfee4cd4919231a9b2e0ac6a8a9",
+  "tree_sha256": "351a95bc990504fb425ec46898380ecd98b6518301c81afc6046244459dd15e0",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2597,7 +2597,7 @@
     {
       "path": "modules/dev-box/boxes.js",
       "mode": "0000644",
-      "sha256": "fbf9bb7bd4c70ac81627d7d473a94e98e6976581bc29f60c5342d428a39238cf"
+      "sha256": "a56b75218b3ac3fed0bb495b9c7f41b2794dafa5f3e6ec28cbb21a97e9b25b7b"
     },
     {
       "path": "modules/dev-box/db.js",
@@ -4057,12 +4057,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "7829011d4ec272839d524b9e2f9449e16c18ff635378e52490091cb025cefe3f"
+      "sha256": "c96137763abb2061735f0a815401ead7047d116c5eb6dd538178e9e23c9ca0bd"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b179d0a0a83c292a353548cceac274dba29e8e296c62565244cc4d2fc81e6951"
+      "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": "65dcc9e68f955842239c2c9d4f26e77c920ede6e79608347758ca7d6d71fb5e4"
+      "sha256": "ff17cf82d49bb2e21188381d9621bbf4f5cf61ac3e49b10ea5ea32685d170c14"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -6042,7 +6042,7 @@
     {
       "path": "tests/boxes.mjs",
       "mode": "0000644",
-      "sha256": "8702916e37e8cc08ae0e055b1bc7ea70da71720c51bd2a05df2a4dc598a17f97"
+      "sha256": "5a8d2ca5709f2c4ae5089b53883a5a892beeb6920bacbddbd352b106c4ec0e34"
     },
     {
       "path": "tests/branding.mjs",

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/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.78",
+  "version": "1.19.79",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.78",
+      "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.78",
+  "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

@@ -583,8 +583,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         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.78'; // 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/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);