@bongos/core 1.19.78 → 1.19.80

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "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.80",
+  "core_contract": "1.19.80",
+  "source_commit": "e9830526a46cd238c6ea856406a1bcde6fcb6e4f",
   "source_ref": "HEAD",
-  "built_at": "2026-08-12T22:44:08.133Z",
+  "built_at": "2026-08-12T23:02:51.567Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 295,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1225,
+    "functional_verbatim": 1226,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1541,
-  "tree_sha256": "96bcb5ac17be8a28801e81faab41c95d0b6b2bfee4cd4919231a9b2e0ac6a8a9",
+  "file_count": 1542,
+  "tree_sha256": "8efe860e490a9f9bca1f3739c652e205e29d50643e86361a1eb631f7474a1ba9",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -37,7 +37,7 @@
     {
       "path": ".claude/skills/builder-box/SKILL.md",
       "mode": "0000644",
-      "sha256": "a24e22a6e7102654d71a255210b260d2c2c0dd9047a5bab128fa3e44c6b511c9"
+      "sha256": "d8bfc9298bbb136742147e83d2500b9cb0961fec35ca15dc3cb773c9ecdf8b4b"
     },
     {
       "path": ".claude/skills/builder-claim/SKILL.md",
@@ -2597,7 +2597,7 @@
     {
       "path": "modules/dev-box/boxes.js",
       "mode": "0000644",
-      "sha256": "fbf9bb7bd4c70ac81627d7d473a94e98e6976581bc29f60c5342d428a39238cf"
+      "sha256": "a56b75218b3ac3fed0bb495b9c7f41b2794dafa5f3e6ec28cbb21a97e9b25b7b"
     },
     {
       "path": "modules/dev-box/db.js",
@@ -2982,7 +2982,7 @@
     {
       "path": "modules/hall-ui/public/box-panel.js",
       "mode": "0000644",
-      "sha256": "d4b32aa4382100a7e60cc83e83ef23ba34dac0ff759143286b2deaebb8f56cb1"
+      "sha256": "3834d4aac8cb7ebc604973e145f396d0893b4cf62abc530f2027c491b31c625d"
     },
     {
       "path": "modules/hall-ui/public/brand-apply.js",
@@ -4057,12 +4057,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "7829011d4ec272839d524b9e2f9449e16c18ff635378e52490091cb025cefe3f"
+      "sha256": "b7e3e581321a968a2978affc8766e5bc9ec8f412f0c3e7a94c47916138724de9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b179d0a0a83c292a353548cceac274dba29e8e296c62565244cc4d2fc81e6951"
+      "sha256": "283e5a12a702be6937db0eb28a69775e3cb6b760ae217b3824d65ba7feb6743b"
     },
     {
       "path": "public-docs/index.html",
@@ -4467,7 +4467,7 @@
     {
       "path": "scripts/gds/api.js",
       "mode": "0000644",
-      "sha256": "e2df5d6f4436595aee60d338198c0c577c82490856ba4f5cd051ca48dc6a710d"
+      "sha256": "8f7332da44883801fb4674747c9e9a60e485353b36df6bebe1db8fc1ebd3558f"
     },
     {
       "path": "scripts/gds/api.ps1",
@@ -4557,7 +4557,7 @@
     {
       "path": "scripts/gds/box.js",
       "mode": "0000644",
-      "sha256": "41e1a0c0ef56d5cf10cc73124964c114854a12d8dd3de249d4bafcda04dd2106"
+      "sha256": "117b0ed6730e35559356403b50240d0ef5b6ab46752a8cf76de4e0a8ad244d42"
     },
     {
       "path": "scripts/gds/build-bongos.js",
@@ -4617,7 +4617,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "6c42a8ee151ba5e12475e50b0d113d306fd01c5c95100f131713fb3abeaa4e62"
+      "sha256": "e86444334085b00ff4256fcb6bf15e5f443dc75bdcbf8ca6eb87f0b41fcd3230"
     },
     {
       "path": "scripts/gds/code.js",
@@ -5687,7 +5687,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "65dcc9e68f955842239c2c9d4f26e77c920ede6e79608347758ca7d6d71fb5e4"
+      "sha256": "e85465ed2f13494396cf2d74bad0c8a2b6e52d42d48c493a3d0dcf4694f6072e"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -6042,7 +6042,7 @@
     {
       "path": "tests/boxes.mjs",
       "mode": "0000644",
-      "sha256": "8702916e37e8cc08ae0e055b1bc7ea70da71720c51bd2a05df2a4dc598a17f97"
+      "sha256": "5a8d2ca5709f2c4ae5089b53883a5a892beeb6920bacbddbd352b106c4ec0e34"
     },
     {
       "path": "tests/branding.mjs",
@@ -6129,6 +6129,11 @@
       "mode": "0000644",
       "sha256": "b9258f690d5dc7c87bcbb12d510b3071a38669777ae9a92a99e683e76ea15e83"
     },
+    {
+      "path": "tests/cli_exit_no_abort.mjs",
+      "mode": "0000644",
+      "sha256": "7bc4d54d29458c70cd545aecac1ca1f7b8cc13d7b1dacaa90a8c2184ef553304"
+    },
     {
       "path": "tests/cli_lib_formatters.mjs",
       "mode": "0000644",

package/.claude/skills/builder-box/SKILL.md

@@ -7,7 +7,7 @@ You are showing a builder the status of **their own** dev box and helping them g
 
 ## Background
 
-The per-builder box lifecycle (ADR 0031 §2) auto-suspends when idle (snapshot-and-park) and recreates on demand, so a builder's box is often `parked` between sessions — that's normal and cheap, not a problem. The read API:
+The per-builder box lifecycle (ADR 0031 §2) auto-suspends when idle (snapshot-and-park) and recreates on demand, so a builder's box is often `parked` between sessions — that's normal and cheap, not a problem. **The idle sweep parks; it does not destroy** (task 1002726 — it *did* destroy droplet and snapshot for a long stretch, so a builder who remembers losing work that way is remembering something real that is now fixed). Full reclaim happens only after `BOX_DORMANT_DAYS` (14) parked, and **only after a warning was actually delivered** — an unwarned box is deferred, not reclaimed (task 1002727). The read API:
 - `GET /api/gds/box/me` → the caller's box: `state`, `scope`, `ip`, `hostname`, cost, activity timestamps.
 - `GET /api/gds/box/ssh-key` → the caller's registered SSH keys (fingerprints + labels).
 - `GET /api/gds/box/terminal` → the caller's active box's browser-terminal `url` + basic-auth `credential` (the Chromebook/browser on-ramp, ADR 0038), once the box has published them.
@@ -26,7 +26,8 @@ The per-builder box lifecycle (ADR 0031 §2) auto-suspends when idle (snapshot-a
    - **state = `none`** → they have no box yet. On a Mac/Windows: run `/builder-connect` (registers their SSH key + installs the Desktop file). To actually create the box hands-off, `POST /api/gds/box/ensure` queues the auto-provision (no operator CLI needed). *(The old path — ask an operator to `box.js onboard <login>` — still works but is no longer required.)*
    - **state = `active`** → box is up at `hostname` (`ip`). They can connect from Claude Desktop → Code → Environment → "Example Dev Box". For a browser/Chromebook (ADR 0038), the terminal comes from the web: `GET /api/gds/box/terminal` returns a `url` + a basic-auth `credential` (username `otb`, password = <redacted>; open the url, enter them, then type `claude` in the terminal. No SSH needed.
      - **Live game preview — the sandbox (ADR 0044).** If `/box/terminal` returns a `url` (i.e. the box is on the named tunnel), the builder also has a private live preview of the game running on their own box, at the **same hostname with `term-` swapped for `sandbox-`** — e.g. terminal `https://term-<login>.example.com` → preview `https://sandbox-<login>.example.com`. It serves their working copy of the game (degraded — fully playable, no saved state), so they can review changes in a browser **without shipping to prod**. The loop: edit in the terminal → run **`/builder-stage`** (or `box-preview restart`) → refresh the preview tab. Staging via `/builder-stage` also records the review marker that `/builder-ship`'s sandbox-first gate checks (#927, ADR 0046) — on a dev box, game changes are staged + reviewed on the sandbox before they ship to the main game. `box-preview status` shows whether it's up + the URL; `box-preview logs` tails the server. (No preview on a quick-tunnel box — that path can't carry the game port; it needs the named tunnel.)
-   - **state = `parked`** → idle-suspended (cheap, expected). It wakes on demand: `POST /api/gds/box/ensure` queues the wake and it's back in ~1 min (no operator needed). Reassure them their data is safe in the snapshot.
+   - **state = `parked`** → idle-suspended (cheap, expected). It wakes on demand: `POST /api/gds/box/ensure` queues the wake and it's back in ~1 min (no operator needed). Their data IS safe in the snapshot — say so plainly, and mean it: the idle path preserves the filesystem, and the only thing that deletes the snapshot warns them first with days of lead time.
+   - **state = `destroyed`** → the box is genuinely gone, and so is anything uncommitted on it. This is NOT the idle path — it means they closed it themselves, an operator deprovisioned it, or it sat parked past the dormancy window after being warned. `POST /box/ensure` gives them a **fresh** box, not their old one; don't imply otherwise.
    - **state = `provisioning` / `waking`** → in flight; check back in a minute.
    - **state = `error`** → flag it to an operator (don't try to fix infra from here).
    - **SSH keys** → list the fingerprints + labels. If empty, they haven't connected yet → `/builder-connect`. They can remove a stale key with `DELETE /api/gds/box/ssh-key/:id` (own-scoped).

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/hall-ui/public/box-panel.js

@@ -299,23 +299,43 @@
         schedulePoll(5000);
         return;
       }
-      // No open intent and not active/provisioning/waking. Two cases:
-      //   • destroyed → the builder HAD a box that is now gone — they closed it, or
-      //     it was auto-stopped after ~10 min idle, which tears down the tunnel + its
-      //     DNS. Opening the old terminal/sandbox URL then fails with a raw browser
-      //     "can't find the server" error and no explanation (idea #295). Don't leave
-      //     them staring at a bare button: say what happened + offer to turn it back on.
+      // No open intent and not active/provisioning/waking. Three cases:
+      //   • parked → asleep after the idle sweep, filesystem preserved (task 1002726).
+      //     Reachable again as of that task; offer a wake, and say the files are safe.
+      //   • destroyed → the builder HAD a box that is now gone — they closed it, an
+      //     operator deprovisioned it, or it passed the dormancy window after being
+      //     warned. Either way the tunnel + DNS are torn down, so opening the old
+      //     terminal/sandbox URL fails with a raw browser "can't find the server" and
+      //     no explanation (idea #295). Don't leave them staring at a bare button.
       //   • none → never had a box (first run). Keep the clean first-run button.
       closeTermWindow();
       stopPoll();
       enableOpenBtn(null);
+      // task 1002728 — PARKED is a real, reachable state again since task 1002726
+      // made the idle sweep park instead of destroy. Before that it could never
+      // happen, so there was no branch for it and a parked box fell through to
+      // the first-run "Request dev box" screen — which reads as "your box is
+      // gone" at the exact moment the box and its files are safe.
+      if (state === 'parked') {
+        setRequestBtn(true, 'Wake my box');
+        setOut('<p class="setup__box-msg">Your dev box is asleep — wake it below.</p>'
+          + '<p class="setup__box-close-hint">It was put to sleep after a couple of hours idle so it stops '
+          + 'costing money. <strong>Your files are kept</strong>, including anything you had not committed — '
+          + 'waking it brings the box back as you left it, in about a minute. A sleeping box has no terminal '
+          + 'or live-preview URL, so an old link will fail to load until it is awake.</p>'
+          + '<p class="setup__box-close-hint">If it stays asleep for a couple of weeks we clean it up to save '
+          + 'cost, but you will get a warning first with several days to wake it.</p>');
+        return;
+      }
       if (state === 'destroyed') {
         setRequestBtn(true, 'Turn box back on');
         setOut('<p class="setup__box-msg">Your dev box is stopped — turn it back on below.</p>'
-          + '<p class="setup__box-close-hint">Boxes auto-stop after about 10 minutes idle to save cost '
-          + '(or when you close one). A stopped box has no terminal or live-preview URL, so an old '
-          + 'link will fail to load. Turning it back on takes about a minute. '
-          + '<strong>Anything not committed or shipped on the old box is gone</strong> — commit early next time.</p>'
+          + '<p class="setup__box-close-hint">This happens when you close a box yourself, or after it has been '
+          + 'asleep long enough to be cleaned up (you are warned first). A stopped box has no terminal or '
+          + 'live-preview URL, so an old link will fail to load. Turning it back on takes about a minute, and '
+          + 'gives you a <strong>fresh</strong> box — <strong>anything not committed or shipped on the old one '
+          + 'is gone</strong>. (Going idle no longer does this: an idle box is put to sleep with your files '
+          + 'intact.)</p>'
           + '<p class="setup__box-close-hint">The box you turn on has a <strong>new identity</strong>. If Claude '
           + 'Desktop says <strong>&ldquo;Host denied&rdquo;</strong> or asks for a password when reconnecting, fully quit '
           + 'and reopen Desktop (it re-pins your box automatically) or press <strong>Repair</strong> — do not keep turning '

package/package-lock.json

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

@@ -18,7 +18,7 @@
 // on a 2xx, 1 on any non-2xx or transport error, 2 on bad invocation.
 
 const fs = require('node:fs');
-const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanceAndExit } = require('./cli-lib');
+const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanceAndExit, cliExit } = require('./cli-lib');
 
 
 (async () => {
@@ -62,7 +62,7 @@ const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanc
     res = await api.request(method, relPath, body != null ? { body } : {});
   } catch (e) {
     console.error(`api: request failed: ${e.message}`);
-    process.exit(1);
+    return cliExit(1); // task 1002734: never process.exit() after a request
   }
   if (!quiet) console.error(`${method} ${urlPath} → ${res.status}`);
   // task 1501: on a dev box the baked session is box-scoped (ADR 0053) and every
@@ -79,5 +79,9 @@ const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanc
   if (res.data !== undefined && res.data !== null) {
     console.log(JSON.stringify(res.data, null, 2));
   }
-  process.exit(res.ok ? 0 : 1);
+  // task 1002734: process.exit() here aborted node 5/5 on Windows —
+  // "Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c"
+  // — AFTER the JSON had already printed, so every caller that checks the exit code
+  // read a successful command as a failure. Set the code and let the loop drain.
+  cliExit(res.ok ? 0 : 1);
 })();

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/scripts/gds/cli-lib.js

@@ -115,6 +115,20 @@ function hallBase(base = API_BASE) {
 // buys these one-shot processes nothing, so route requests through a dispatcher
 // with keep-alive effectively disabled (mirrors cf-tunnel.js's dispatcher
 // pattern). Degrades to the default dispatcher if undici can't be required.
+//
+// task 1002734 — THIS ALONE IS NOT ENOUGH, and the measurements say so: with the
+// dispatcher wired in and undici resolving fine, `node scripts/gds/api.js GET
+// /tasks/<id>` still aborted 5/5 on Windows 11 / Node 24. The dispatcher removes
+// one contributing handle; the actual trigger is calling process.exit() at all
+// while the request machinery is still tearing down. A minimal synthetic
+// fetch-then-exit does NOT reproduce, so it takes the real stack (the dynamic ESM
+// client import + the Agent + any child spawn / consumed stdin) to line up — which
+// is exactly why hunting the single guilty handle is a dead end.
+//
+// The rule for every CLI here: after a request, DO NOT call process.exit().
+// Set process.exitCode and return, and let the loop drain — see cliExit below.
+// Verified: the pre-push gate went 8/8 aborting to 0/8 on that change alone
+// (task 1002725), and api.js 5/5 to 0/5 (this task).
 let _noKeepAliveDispatcher;
 let _noKeepAliveTried = false;
 function noKeepAliveDispatcher() {
@@ -127,6 +141,19 @@ function noKeepAliveDispatcher() {
   return _noKeepAliveDispatcher;
 }
 
+// cliExit(code) — the post-request replacement for process.exit(code). Records the
+// exit status and lets node exit naturally once the loop drains, which is what
+// keeps the UV_HANDLE_CLOSING abort above from firing. Callers must `return` after
+// calling it: unlike process.exit() it does NOT stop execution.
+//
+// Gotcha (learned in task 1002725): a hard exit MASKS leaked timers/handles. Once a
+// CLI exits naturally, anything still armed — an uncleared setTimeout, an open
+// interval — keeps the process alive. Clear them, or the CLI hangs instead of
+// crashing.
+function cliExit(code = 0) {
+  process.exitCode = code;
+}
+
 async function readSessionFile(p) {
   try {
     const raw = await fsp.readFile(p, 'utf8');
@@ -760,6 +787,7 @@ module.exports = {
   resolveQuiet,
   readSessionToken,
   apiCall,
+  cliExit,
   cliClient,
   requireSession,
   printUnauthGuidanceAndExit,

package/src/module-api.js

@@ -583,8 +583,12 @@ 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)
+//   1.19.80 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.79 with no explicit bump. run 31649366675. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.78'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.80'; // 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);

package/tests/cli_exit_no_abort.mjs

@@ -0,0 +1,135 @@
+// tests/cli_exit_no_abort.mjs — the GDS CLIs must not abort natively on exit
+// (task 1002734; the pre-push twin of this is tests/pre_push_hook.mjs, task 1002725).
+//
+// THE BUG. On Windows + Node 24, calling process.exit() after the CLI has made a
+// request aborts the process before it can exit cleanly:
+//
+//   Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 76
+//
+// `node scripts/gds/api.js GET /tasks/<id>` reproduced this 5/5: the JSON printed
+// correctly and THEN the process died with exit 127, so every caller that checks an
+// exit code — CI, shell scripts, the ship pipeline — read a successful command as a
+// failure. Setting process.exitCode and letting the loop drain took it to 0/6.
+//
+// A no-keep-alive undici dispatcher was already wired into cli-lib for this exact
+// assertion and was NOT sufficient on its own; only dropping the hard exit fixed it.
+//
+// NETWORK-FREE, but not server-free. The failure cases point the CLI at a dead
+// localhost port; the success case runs a throwaway stub server in its own process.
+// Both matter: the crash is in the TEARDOWN, and a 200 tears down more machinery than
+// a refused connection — the wild repro was a successful call.
+//
+// Run:  node --test tests/cli_exit_no_abort.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { spawnSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const API = path.join(ROOT, 'scripts', 'gds', 'api.js');
+const CLI_LIB = path.join(ROOT, 'scripts', 'gds', 'cli-lib.js');
+const DEAD_BASE = 'http://127.0.0.1:9'; // discard port — connection refused, instantly
+
+// The native abort prints this and nothing else can be relied on; it is NOT a
+// JS-level error, so it never appears as a caught exception.
+const ABORT_RE = /Assertion failed|UV_HANDLE_CLOSING/i;
+
+function runApi(args, env = {}) {
+  return spawnSync(process.execPath, [API, ...args], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    env: { ...process.env, GDS_API_BASE: DEAD_BASE, ...env },
+  });
+}
+
+test('api.js does not abort natively when a request fails', () => {
+  const r = runApi(['GET', '/api/gds/me', '--quiet']);
+  assert.doesNotMatch(r.stderr || '', ABORT_RE, `native abort on the request-failure path:\n${r.stderr}`);
+  assert.equal(r.status, 1, `a failed request must exit 1, not ${r.status} (127 = the abort)`);
+  assert.match(r.stderr, /request failed/i);
+});
+
+test('api.js reports a usage error without aborting (pre-request path)', () => {
+  const r = runApi(['GET']); // missing path
+  assert.doesNotMatch(r.stderr || '', ABORT_RE);
+  assert.equal(r.status, 2, 'bad invocation is exit 2');
+});
+
+test('api.js exit code survives repeated runs (the abort was intermittent-looking)', () => {
+  // The synthetic minimal case (bare fetch + process.exit) does NOT reproduce, so a
+  // single green run proves little — the real stack has to line up. Run it enough
+  // times that a reintroduced hard exit shows up rather than slipping through.
+  for (let i = 0; i < 5; i++) {
+    const r = runApi(['GET', '/api/gds/me', '--quiet']);
+    assert.doesNotMatch(r.stderr || '', ABORT_RE, `run ${i + 1} aborted natively`);
+    assert.equal(r.status, 1, `run ${i + 1} exited ${r.status}`);
+  }
+});
+
+// The SUCCESS teardown is the path that actually aborted in the wild: api.js printed
+// its JSON and then died at exit 127. A failed request tears down less machinery, so
+// the failure cases above cannot cover this. Serve a real 200 — still no external
+// network — and assert the clean exit 0.
+//
+// The stub MUST run in its own process. An in-process http.createServer here would
+// deadlock: spawnSync blocks this process's event loop, so the server could never
+// accept the child's connection and the test would hang forever.
+const STUB_SRC = `
+const http = require('node:http');
+const s = http.createServer((q, r) => {
+  r.writeHead(200, { 'Content-Type': 'application/json' });
+  r.end(JSON.stringify({ ok: true, builder: { id: 1, rank: 'archon' } }));
+});
+s.listen(0, '127.0.0.1', () => console.log('PORT=' + s.address().port));
+`;
+
+function startStub() {
+  const proc = spawn(process.execPath, ['-e', STUB_SRC], { stdio: ['ignore', 'pipe', 'ignore'] });
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    const timer = setTimeout(() => { proc.kill(); reject(new Error('stub server did not report a port')); }, 10_000);
+    proc.stdout.on('data', (d) => {
+      buf += d.toString();
+      const m = buf.match(/PORT=(\d+)/);
+      if (m) { clearTimeout(timer); resolve({ proc, port: Number(m[1]) }); }
+    });
+    proc.on('error', (e) => { clearTimeout(timer); reject(e); });
+  });
+}
+
+test('api.js exits 0 after a SUCCESSFUL request — the path that aborted in the wild', async () => {
+  const { proc, port } = await startStub();
+  try {
+    for (let i = 0; i < 3; i++) {
+      const r = runApi(['GET', '/api/gds/me', '--quiet'], { GDS_API_BASE: `http://127.0.0.1:${port}` });
+      assert.doesNotMatch(r.stderr || '', ABORT_RE, `run ${i + 1} aborted natively after a 200:\n${r.stderr}`);
+      assert.equal(r.status, 0, `a successful request must exit 0, got ${r.status} (127 = the abort); stderr: ${r.stderr}`);
+      assert.match(r.stdout, /"ok"/, 'the JSON body must still reach stdout');
+    }
+  } finally {
+    proc.kill();
+  }
+});
+
+test('cli-lib exports cliExit — the documented replacement for a post-request exit', async () => {
+  const mod = await import(`file://${CLI_LIB.split(path.sep).join('/')}`);
+  const cliExit = mod.default?.cliExit ?? mod.cliExit;
+  assert.equal(typeof cliExit, 'function', 'cliExit must be exported for the CLI sweep to adopt');
+});
+
+test('api.js routes its post-request exits through cliExit, not process.exit', () => {
+  const src = fs.readFileSync(API, 'utf8');
+  // The two surviving process.exit() calls are the pre-request guards (usage + body
+  // parse), which run before any network work and are safe. Everything after the
+  // request must use cliExit.
+  const afterRequest = src.slice(src.indexOf('let res;'));
+  const stripped = afterRequest.replace(/\/\/[^\n]*/g, '');
+  assert.ok(
+    !/process\.exit\s*\(/.test(stripped),
+    'no process.exit() may remain after the request is issued — that is what aborts node on Windows'
+  );
+  assert.match(afterRequest, /cliExit\(/, 'the post-request paths must set the exit code via cliExit');
+});