@bongos/core 1.19.853 → 1.19.855

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.853",
-  "core_contract": "1.19.853",
-  "source_commit": "23d160b78996d913c0510928995bae59a1ae6832",
+  "core_version": "1.19.855",
+  "core_contract": "1.19.855",
+  "source_commit": "ea9bbb312aedb67961f643df3927bd9c3611d451",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T21:14:11.854Z",
+  "built_at": "2026-09-17T21:30:54.480Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 497,
+    "docs_redacted": 498,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2278,
+    "functional_verbatim": 2280,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2801,
-  "tree_sha256": "cfc90395d496db6fa9ae34f98458137adcc184faa73c806f2bfdba99027d74ff",
+  "file_count": 2804,
+  "tree_sha256": "f9cc99e0ebd1bf3f55d448b2204c056c832f6360a4941393b640f1db34e99093",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2019,10 +2019,15 @@
       "mode": "0000644",
       "sha256": "4571564a9bf5ccb08996bd1fae58b69945c6cccbc9ce3b58c634acc087cb7698"
     },
+    {
+      "path": "docs/adr/0306-instance-supervision-is-a-seam-with-systemd-as-the-default.md",
+      "mode": "0000644",
+      "sha256": "00d74b19e9574186fbe354e410f6acd9e84db60f11a550905e95ac9071b89aa6"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "00361bb3425bda49646f676baac8ef458bb3c5c32f128767c269e96985d41ccf"
+      "sha256": "d65a10ca2341a236fb6397a84907ed3cc250f0ea72ea5ec4c3e9bfca6a9d6cb2"
     },
     {
       "path": "docs/api-reference.md",
@@ -2587,7 +2592,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "cd9e820a59b864c0b7c48431cbfe39edfeb421fcb807d24679a768c217373720"
+      "sha256": "e272f0cf7f1826cdfedeb48806e9cec9caf6b926793d5308d5de9e137d47cb76"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2697,7 +2702,7 @@
     {
       "path": "docs/recipes/builder-box-lifecycle.md",
       "mode": "0000644",
-      "sha256": "67d76943773d604d5534b2b8abb5b6aff1d64c7928e4d19a995d4cead2f406f6"
+      "sha256": "dfffcee084534239d8a748b7468409644d9375e952143b0bd09b9c2c7341e844"
     },
     {
       "path": "docs/recipes/claude-design-loop.md",
@@ -2817,7 +2822,7 @@
     {
       "path": "docs/recipes/self-host.md",
       "mode": "0000644",
-      "sha256": "135f3942a01e50af87c4645f8920b25e0b779aac45cb5101b39e62cacfa59168"
+      "sha256": "853761ea1330806204c35bcdda680af64fac1f096be1a1296d9d59ed9d54fabd"
     },
     {
       "path": "docs/recipes/server-bring-up.md",
@@ -7912,12 +7917,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d6109cde0d5b5a6a8667252455ec1221dbcd4891b4937bfd240743990d0a354a"
+      "sha256": "7e2895e4342846fb96f477f37493b4f813d0562e1882a7ce204f54c2787bc815"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "e4c6a0d643d7fbf5c9220a2449763f4cbd0b05594eec7fec5d1fffd7e691c54c"
+      "sha256": "11f9ed62bce433c5f300faa1c4c052b810276df34ec1dcdca2d022a6e04e6370"
     },
     {
       "path": "public-docs/index.html",
@@ -8817,7 +8822,7 @@
     {
       "path": "scripts/gds/provision-config.js",
       "mode": "0000644",
-      "sha256": "b5ec038d150da93b4c54eeb864586a70e46610655ccb5bf10bd1adaa0432a305"
+      "sha256": "d9d76ed5992ea84b347e0dbe37c78dda014df62208772ff00a2987d34ec27059"
     },
     {
       "path": "scripts/gds/provision-core-upgrade.js",
@@ -8834,6 +8839,11 @@
       "mode": "0000644",
       "sha256": "f1ca176ff8cdb8de65940af1e30316db600cb5df529abbc997697abf1cbc2c2d"
     },
+    {
+      "path": "scripts/gds/provision-process.js",
+      "mode": "0000644",
+      "sha256": "210d5135b157363499dc34bb8ac34eb7f661a61d8ba3d23e6a64953e5893559e"
+    },
     {
       "path": "scripts/gds/provision-repo-auth.js",
       "mode": "0000644",
@@ -8847,7 +8857,7 @@
     {
       "path": "scripts/gds/provision-teardown.js",
       "mode": "0000644",
-      "sha256": "df4187852cf0f75a12571607af95782d16f1655aa4314152078cb9ee9b3d0f7c"
+      "sha256": "9722d4099de9596df0e597e7e373c510dea312d8929c231705885e074cb0af12"
     },
     {
       "path": "scripts/gds/provision-units.js",
@@ -8857,7 +8867,7 @@
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "cbf44d415e3c5bb803e68af7b70ebfb08e7d0ab2388cc7f17a114512f29662e8"
+      "sha256": "71d4edd0e5653207a535e6a0febca39a19ba281ffce7f248049b826dc5ab3b84"
     },
     {
       "path": "scripts/gds/publish-credential-check.js",
@@ -9857,7 +9867,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "239294e8e4023ccc05619cd66992afebfceea6453821ec3ee7ceb8cabb540cf7"
+      "sha256": "210e06e3e19060630a7d73a98aeceb948eb47b6690435d5ad8b624b0b1f05bc2"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10424,6 +10434,11 @@
       "mode": "0000644",
       "sha256": "063c94d759fa8a79b8c402145801ae2a4d9863bef591fb5adf57697e15effc39"
     },
+    {
+      "path": "tests/box_sweep_docs.mjs",
+      "mode": "0000644",
+      "sha256": "e56b09e961b0c68ee27a6e5049750cd2828e94d9870ddc7837bf9de44fcaa0b7"
+    },
     {
       "path": "tests/box_sync.mjs",
       "mode": "0000644",
@@ -12732,7 +12747,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "edcb3a67c97291be694f06cf092233dbd78dbb56898547bc6ccb562e7c27da6b"
+      "sha256": "396c26ec06858534e692d0ce1452d1944ea573743e6955df8e5ac22a655bfcdb"
     },
     {
       "path": "tests/provision_caddy_wiring.mjs",

package/docs/adr/0306-instance-supervision-is-a-seam-with-systemd-as-the-default.md

@@ -0,0 +1,61 @@
+# ADR 0306 — Instance supervision is a seam, with systemd as the default
+
+**Status:** accepted · **Date:** 2026-09-17 · **Task:** [task 1003997](https://cloudbongos.com/builders#/task/1003997) (goal 1000106 — BONGOS-V2)
+
+**Related:** [ADR 0111](0111-instance-hosting-provisioning-module.md) (the standup runbook this seam sits inside, and the enqueue-only trust boundary) · [ADR 0128](0128-provisioning-runner-privilege-and-db-auth-model.md) (`PROVISION_SUDO` — the escalation knob this ADR leaves alone) · [ADR 0130](0130-provision-remote-exec-over-ssh.md) (the precedent for adding a dimension to the injected exec seam) · [ADR 0281](0281-an-instance-identity-is-its-own-unix-account-and-pg-role.md) (`User=`/`Group=` is how instance isolation is enforced) · [ADR 0285](0285-a-shared-box-holds-about-twelve-projects-per-gb-and-memory-is-the-wall.md) (every live project is `hosting_shape='standalone'`) · [ADR 0303](0303-provisioning-verifies-the-base-caddyfile-and-never-edits-it.md) (detect-and-refuse rather than auto-edit shared host config)
+
+## Context
+
+`provision-units.js` hardcoded `/etc/systemd/system` in three path functions, and the
+runner reached for `systemctl` inline at fifteen call sites across `provision.js` and
+`provision-teardown.js`. Supervision was not a choice anywhere — it was a string.
+
+That is fine on the boxes we run today: every live project is `hosting_shape='standalone'`
+on a systemd host (ADR 0285). It stops being fine the moment the plane is a container. The
+self-host image runs `USER node`, installs no `sudo`, and boots no systemd, so the standup's
+service step cannot run there at all.
+
+**A directory knob does not fix this.** Pointing the unit path somewhere writable still
+emits `systemctl daemon-reload` into a process namespace where systemd is not PID 1. The
+thing that varies is not *where the unit file goes*; it is *what supervises the process*.
+
+**systemd `--user` was considered and rejected.** It addresses an unprivileged VM — a user
+session bus, `~/.config/systemd/user/` — but a plain container runs no systemd at all, user
+bus included. It would have fixed a shape we do not have while leaving the one we do have
+untouched.
+
+## Decision
+
+**Instance supervision is a seam with two implementations, and systemd is the default.**
+
+A process manager answers four questions about an instance's long-running service: install
+and enable it, restart it, remove it, and install its nightly backup schedule. Those four
+operations move behind `scripts/gds/provision-process.js`; the call sites ask the resolved
+manager rather than composing `systemctl` strings.
+
+**Selection is explicit, then probed, then defaulted:**
+
+1. `PROVISION_PROCESS_MANAGER` when set (an unknown value is a loud error, never a silent fallback);
+2. otherwise systemd when `/run/systemd/system` exists — the same check `sd_booted(3)` makes, and the one systemd itself documents for "was this host booted under systemd";
+3. otherwise supervisord.
+
+**The live box is unchanged by construction.** It boots systemd, so the probe selects
+systemd, and the systemd implementation emits byte-identical commands and unit paths to
+what the inline strings emitted. The existing composition assertions in `tests/provision.mjs`
+are the proof: they pin the exact strings and were not rewritten for this change.
+
+**What the seam deliberately does NOT cover:**
+
+- **Caddy reload.** `systemctl reload caddy` is shared-proxy config, governed by ADR 0303, and the container has no Caddy at all — that is [task 1004017](https://cloudbongos.com/builders#/task/1004017), not this seam.
+- **The dedicated-droplet cloud-init path.** A DigitalOcean droplet always boots systemd; baking unit files into cloud-init stays systemd-specific on purpose.
+- **Per-instance unix accounts.** `useradd` cannot run under `USER node`, so ADR 0281's isolation has no container equivalent yet — [task 1004018](https://cloudbongos.com/builders#/task/1004018).
+
+## Consequences
+
+- **Isolation must be restated per manager.** systemd enforces ADR 0281 with `User=`/`Group=`; supervisord's equivalent is its `user=` directive, and the supervisord implementation sets it from the same `instanceUser(inst)`. A future third manager has to answer this question explicitly or it silently drops the boundary that stops one instance reading a sibling's `/proc/<pid>/environ`.
+
+- **supervisord has no timers, so the nightly backup is skipped there — loudly.** supervisord supervises processes, not schedules. Rather than re-implement cron badly, the supervisord implementation installs no backup schedule and logs the exact `crontab` line an operator can add instead. A container self-host therefore has no automatic DB backup until that is addressed; the skip is visible in the standup log, not silent.
+
+- **The seam is two implementations wide, not N.** It exists because we have two real planes, not as speculative pluggability. A third manager is a new implementation in one file, but nothing is abstracted further in anticipation of one.
+
+- **This alone does not make container standup work.** It removes one of four blockers. The self-host container still has no ingress (task 1004017), no per-instance identity (task 1004018), and a backup directory owned by a hardcoded `APP_USER = 'lars'` ([task 1002719](https://cloudbongos.com/builders#/task/1002719)). Task 1003997's done-when was narrowed to this seam accordingly, so the ledger does not record a self-host story that is not there yet.

package/docs/adr/README.md

@@ -397,3 +397,4 @@ This keeps the decision history honest and traceable.
 | 0303 | [**Provisioning verifies the base Caddyfile, and never edits it** ([task 1002860](https://cloudbongos.com/builders#/task/1002860), goal 1000106, from idea 1000524). The runner assumed the box's `/etc/caddy/Caddyfile` carried the `on_demand_tls` tls-check ask and `import /etc/caddy/sites/*.caddy`, and reloaded with `allowFail` — a box missing either provisioned "successfully" and the instance was unreachable. It now reads Caddy's RESOLVED config (`caddy adapt`: unprivileged, no key access, indifferent to how the directives are written) before touching the box (the ask) and after writing the snippet (the domain is served ⇒ the import reaches it), refusing with the exact line to add, and the reload is loud. Rejected: editing the base file (`on_demand_tls` must sit inside the global block an append cannot place, and a bad write takes down the control plane's own apex); `caddy validate` (loads certificate keys, needs root).](0303-provisioning-verifies-the-base-caddyfile-and-never-edits-it.md) | provisioning / infra |
 | 0304 | [**Routine reads run without a prompt; anything a flag can turn into a write is exact-form** ([task 1003992](https://cloudbongos.com/builders#/task/1003992), goal 1000095). The shipped `.claude/settings.json` pre-allowed six commands, so every `gh pr view` or `git fetch` asked a non-technical builder to approve a command they cannot evaluate. The read-only subset is now pre-allowed — `git status`, `gh pr view/checks/list`, `gh run view/list` and the gds CLIs audited read-only under every flag as prefix rules; `git branch` and `git fetch` as exact forms only, because a flag turns either into a write or an exec — and the instance starter mirrors it rule for rule. `git diff/log/show` get NO rule: the harness already runs their read-only forms unprompted with a flag check, and a prefix rule switched that check off (`--output=<path>` writes anywhere, `diff --no-index` reads deny-listed files — both reproduced in review). A test pins the whole allow-list, that no rule covers a command git-guard blocks, and that no rule covers a write dressed as a read. Rejected: `Bash(git:*)`, prefix-plus-`ask` for diff/log/show (argument patterns are evaded by quoting), prefix rules for fetch/branch, `bypassPermissions` everywhere.](0304-routine-reads-run-without-a-prompt-and-anything-a-flag-can-turn-into-a-write-is-exact-form.md) | GDS / sessions / permissions |
 | 0305 | [**A recipe lives with what it documents** ([task 1002156](https://cloudbongos.com/builders#/task/1002156), goal 1000091, from idea 536 / idea 537). Part A of the 2026-07-10 architecture review, held until the owner confirmed direction. The binary core-vs-instance split in `isPublishable()` has collapsed to one side: all **36** files in `docs/recipes/` and all **4** in `docs/research/` publish, and the denylist rows that once held the instance-local half name files that no longer exist. Worse, it is producing wrong docs — four published recipes document the dev-box that goal 1000091 is deleting, and none of the nine removal tasks covers them ([task 1004013](https://cloudbongos.com/builders#/task/1004013)). The cause is not neglect: **nothing structurally ties a recipe to what it documents**. So the rule is ownership, not portability — a recipe lives in the same deletable unit as its subject. Three classes: core methodology stays in `docs/recipes/`; feature-coupled moves to `modules/<key>/recipes/` and dies with its module; instance-operational stays behind the publish gate. `scripts/` is unchanged (it is the CLI, not documentation with a portability question); `docs/research/` becomes instance-local (situated artifacts, and the likeliest brand-name leak). **The thesis is rejected in its literal form**: a shared recipe is not a NEW asset class parallel to modules but a directory *inside* one, reusing the manifest attribution, submit→review→accept, security accept-gate, default-off enablement and orphaning policy that ADR 0107/0135 already ship — `modules/ui-design/docs/design-contract.md` is the undesigned precedent. Rejected: a parallel registry (a second manifest, queue, attribution model and orphaning policy, to distribute Markdown; Supermarket/Galaxy distribute executables with dependency resolution, which is what a module already is); classify-and-keep-the-binary-split (treats the symptom, restores the local half only until the next module ships a recipe); per-recipe portability front-matter (no build step reads it, no deletion touches it); deleting `docs/research/` (live inputs to open goals). Decides direction only — no file moves; the sweep and a fitness check for a recipe outliving its module are follow-on.](0305-a-recipe-lives-with-what-it-documents.md) | modules / upstreaming |
+| 0306 | [**Instance supervision is a seam, with systemd as the default** ([task 1003997](https://cloudbongos.com/builders#/task/1003997), goal 1000106, F13 from the task-1002718 QA walk). `provision-units.js` hardcoded `/etc/systemd/system` in three path functions and the runner reached for `systemctl` inline at fifteen call sites, so a standup was impossible on any plane without systemd — the self-host image runs `USER node`, installs no `sudo` and boots no systemd. **A directory knob does not fix this**: pointing the unit path somewhere writable still emits `daemon-reload` into a namespace where systemd is not PID 1. What varies is not where the unit file goes, it is what supervises the process. Chosen: four operations (install+enable, install backup schedule, restart, remove) move behind `scripts/gds/provision-process.js`, taking the `{ exec, writeFile, sudoP, log }` io the runbook already threads, so dry-run, remote-ssh and logging behaviour carry over untouched (ADR 0130). Selection is explicit (`PROVISION_PROCESS_MANAGER`, an unknown value throws) → probed (`/run/systemd/system`, the `sd_booted(3)` check) → supervisord. **The live box is unchanged by construction** — it boots systemd, and the systemd implementation emits byte-identical commands; the untouched composition assertions in `tests/provision.mjs` are the proof. Rejected: systemd `--user` units (fix an unprivileged VM we do not have, while a plain container has no user bus either). Consequences: isolation is restated per manager (systemd `User=` → supervisord `user=`, ADR 0281) or it silently drops; supervisord has no timers, so it installs no backup schedule and prints the `crontab` line instead of re-implementing cron; the seam is two implementations wide, not speculatively N. **This removes one of four container blockers** — ingress ([task 1004017](https://cloudbongos.com/builders#/task/1004017)), per-instance identity ([task 1004018](https://cloudbongos.com/builders#/task/1004018)) and the hardcoded backup-dir owner ([task 1002719](https://cloudbongos.com/builders#/task/1002719)) remain, so task 1003997's done-when was narrowed to the seam rather than claiming a self-host story that is not there.](0306-instance-supervision-is-a-seam-with-systemd-as-the-default.md) | infra / provisioning |

package/docs/module-api-changelog.md

@@ -2180,5 +2180,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.851 with no explicit bump. run 35274827497. (task 1002620)
   1.19.853 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.852 with no explicit bump. run 35275456041. (task 1002620)
+  1.19.854 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.853 with no explicit bump. run 35276402271. (task 1002620)
+  1.19.855 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.854 with no explicit bump. run 35277047800. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/builder-box-lifecycle.md

@@ -7,26 +7,30 @@
 Each builder gets **one** box (ADR 0031 §2). Its lifecycle is a small state machine tracked in the `builder_boxes` table:
 
 ```
-                  idle > BOX_IDLE_MINUTES (auto, every 15m)      task 804:
-none ─provision─▶ active ──────────────────────────────▶ destroyed   destroys
-                   ▲  │                                    ▲          droplet
-        wake(manual) │  park(manual)                       │          + snapshot
-                   │  ▼                                    │
-                  parked ── parked > BOX_DORMANT_DAYS ──────┘
-                            (auto, daily)
+none --provision--> active
+                     ^  |
+   wake (manual, or  |  | idle > BOX_IDLE_MINUTES (auto, hourly)
+   on next connect)  |  | park (manual)
+                     |  v
+                    parked --- parked > BOX_DORMANT_DAYS ---> destroyed
+                               (auto, daily, WARNS FIRST)     snapshot deleted
+
+  park keeps the SNAPSHOT (only the droplet is destroyed, to stop billing),
+  so it is reversible with `wake`. Dormant reclaim is the ONLY automated
+  path that destroys a snapshot, and it warns the builder first.
 ```
 
 - **provision** — create + boot a droplet running the [#596](https://example.com/builders#/task/596) devcontainer. **Rank-gated.**
-- **idle deprovision** (auto, every 15 min) — when an `active` box is idle > `BOX_IDLE_MINUTES`, **destroy the droplet AND its snapshot** ([#804](https://example.com/builders#/task/804)). Compute billing stops; nothing is kept. **Not reversible** — the next connect re-provisions a fresh box, and any uncommitted work on the old box is lost (spike [#837](https://example.com/builders#/task/837)).
-- **park** (manual Archon CLI only) — snapshot the droplet then **destroy** it. A powered-off DO droplet still bills; only a destroyed one stops. The snapshot (~$0.30/mo) is the cheap residual you can `wake` from. **No longer automatic** — the idle sweep deprovisions instead of parking ([#804](https://example.com/builders#/task/804)).
+- **idle park** (auto, hourly) — when an `active` box is idle > `BOX_IDLE_MINUTES`, snapshot it and **destroy the droplet only**, keeping the snapshot ([task 1002726](https://example.com/builders#/task/1002726)). Compute billing stops; the box is **reversible** via `wake`. An earlier revision ([task 804](https://example.com/builders#/task/804)) destroyed the snapshot too; that was reverted because it took uncommitted work with it (spike [task 837](https://example.com/builders#/task/837)).
+- **park** (the idle sweep, or an Archon by hand) — snapshot the droplet then **destroy the droplet**. A powered-off DO droplet still bills; only a destroyed one stops. The snapshot (~$0.30/mo) is the cheap residual you can `wake` from.
 - **wake** (manual, on demand) — recreate the droplet from its snapshot. New IP; the `hostname` is repointed via `BOX_DNS_HOOK`.
-- **dormant reclaim** (auto, daily) — destroy the snapshot of a box `parked` > `BOX_DORMANT_DAYS`. Since idle no longer parks, this only catches boxes an Archon **manually** parked.
+- **dormant reclaim** (auto, daily) — destroy the snapshot of a box `parked` > `BOX_DORMANT_DAYS`. This is the **only automated path that destroys a snapshot**, so it **warns the builder first** and defers the reclaim if that warning was never delivered ([task 1002727](https://example.com/builders#/task/1002727)). Its input is whatever the idle sweep parked, plus any manual Archon park.
 
 ### How "idle" is detected
 
-The idle sweep **deprovisions** a box when its `last_activity_at` (else `active_since`) is older than `BOX_IDLE_MINUTES` **and** `claude_active` is not true. Both signals are set by **`infra/box-heartbeat.sh`**, which runs **inside the box** every ~5 min and POSTs `/api/gds/box/heartbeat` *only while the box is in use* — an interactive login session, an established SSH connection, an **open browser terminal** (ttyd websocket, [#1161](https://example.com/builders#/task/1161)), or non-trivial CPU load. Silence = the sweep is free to destroy it.
+The idle sweep **parks** a box when its `last_activity_at` (else `active_since`) is older than `BOX_IDLE_MINUTES` **and** `claude_active` is not true. Both signals are set by **`infra/box-heartbeat.sh`**, which runs **inside the box** every ~5 min and POSTs `/api/gds/box/heartbeat` *only while the box is in use* — an interactive login session, an established SSH connection, an **open browser terminal** (ttyd websocket, [#1161](https://example.com/builders#/task/1161)), or non-trivial CPU load. Silence = the sweep is free to park it.
 
-> ⚠️ **The idle sweep's correctness depends on the box-side heartbeat reaching the server.** If it isn't pinging — no Bongos token on the box yet, a pre-[#1161](https://example.com/builders#/task/1161) script that can't see a browser terminal, or the cron not installed — `last_activity_at` never advances and the sweep falls back to `active_since`, i.e. it measures **uptime**, not activity, and will **destroy** a box someone is actively using. Because the idle path is now a full deprovision (no park to wake from), that wrongly-reaped box also loses uncommitted work (spike [#837](https://example.com/builders#/task/837)).
+> ⚠️ **The idle sweep's correctness depends on the box-side heartbeat reaching the server.** If it isn't pinging — no Bongos token on the box yet, a pre-[#1161](https://example.com/builders#/task/1161) script that can't see a browser terminal, or the cron not installed — `last_activity_at` never advances and the sweep falls back to `active_since`, i.e. it measures **uptime**, not activity, and will **park** a box someone is actively using. Because the idle path keeps the snapshot ([task 1002726](https://example.com/builders#/task/1002726)), that box can be restored with `wake` and no work is lost — it is disruptive, not destructive. The destructive case is the dormant sweep, which warns first ([task 1002727](https://example.com/builders#/task/1002727)).
 >
 > **Live mitigation (2026-06-16):** `BOX_IDLE_MINUTES` is raised to **120** in `/etc/example/box.env` as a soak margin until [#1161](https://example.com/builders#/task/1161)'s browser-terminal heartbeat is verified on a newcomer box; lower it back toward the 10-min default once that's proven.
 
@@ -34,12 +38,14 @@ Two sweeps automate the middle (both mirror `stale-claim-release` — dry-run fi
 
 | Sweep | Cadence | What it does | Threshold |
 |---|---|---|---|
-| `box-idle-suspend` | every 15 min | **deprovision** `active` boxes with no activity — destroy droplet **and** snapshot ([#804](https://example.com/builders#/task/804)); not a park | `BOX_IDLE_MINUTES` (default 10; **currently 120 live**) |
-| `box-dormant-reclaim` | daily | destroy the snapshot of long-`parked` boxes (pings builder). Since idle no longer parks, only catches **manual** Archon parks | `BOX_DORMANT_DAYS` (14) |
+| `box-idle-suspend` | hourly | **park** `active` boxes with no activity — snapshot kept, droplet destroyed ([task 1002726](https://example.com/builders#/task/1002726)); reversible via `wake` | `BOX_IDLE_MINUTES` (default 10; **currently 120 live**) |
+| `box-dormant-reclaim` | daily | destroy the snapshot of long-`parked` boxes — the only automated snapshot delete, and it warns first ([task 1002727](https://example.com/builders#/task/1002727)) | `BOX_DORMANT_DAYS` (14) |
+
+> ⚠️ **Both sweeps are currently `enabled: false`** in `config/scheduled-routines.json` — retired with the dev-box module (goal 1000091, [task 1003886](https://example.com/builders#/task/1003886)). Neither fires; the CLI below still works by hand.
 
 ## Why a self-built sweep (not Coder)
 
-ADR 0031 §9.3, resolved 2026-06-04: Coder needs an always-on control-plane droplet (~$12–24/mo fixed) + ops; a self-built sweep has ≈ $0 fixed cost and rides the existing sweep/timer pattern. See the ADR for the full rationale. (The original sweep snapshotted-and-parked idle boxes; [#804](https://example.com/builders#/task/804) simplified the idle path to a direct deprovision — the snapshot/wake machinery now serves only the manual `park`/`wake` commands.)
+ADR 0031 §9.3, resolved 2026-06-04: Coder needs an always-on control-plane droplet (~$12–24/mo fixed) + ops; a self-built sweep has ≈ $0 fixed cost and rides the existing sweep/timer pattern. See the ADR for the full rationale. (The original sweep snapshotted-and-parked idle boxes; [task 804](https://example.com/builders#/task/804) briefly simplified the idle path to a direct deprovision, and [task 1002726](https://example.com/builders#/task/1002726) reverted it — so the snapshot/wake machinery serves the automatic idle path again, as well as the manual `park`/`wake` commands.)
 
 ## The CLI — `node scripts/gds/box.js`
 
@@ -95,7 +101,7 @@ Put these in `/etc/example/box.env` (chmod 600 — **secrets never go in the rep
 | `BOX_REGION` | `nyc3` | droplet region |
 | `BOX_SIZE` | `s-2vcpu-4gb` | droplet size (4 GB floor — the devcontainer sets a 4 GB Node heap) |
 | `BOX_BASE_IMAGE` | `ubuntu-24-04-x64` | first-provision base image (cloud-init installs Docker + the devcontainer) |
-| `BOX_IDLE_MINUTES` | `10` | idle-**deprovision** threshold (minutes). **Currently overridden to `120` live** as a soak margin — see "How idle is detected". |
+| `BOX_IDLE_MINUTES` | `10` | idle-**park** threshold (minutes). **Currently overridden to `120` live** as a soak margin — see "How idle is detected". |
 | `BOX_DORMANT_DAYS` | `14` | dormant-reclaim threshold |
 | `BOX_SSH_KEY_IDS` | — | comma-list of DO SSH key ids/fingerprints to inject (so you can SSH in) |
 | `BOX_REPO_URL` | — | git URL the cloud-init clones into `/workspace`. The scoped **credential** is [#600](https://example.com/builders#/task/600); no identity is hardcoded. |

package/docs/recipes/self-host.md

@@ -39,7 +39,7 @@ Author `config/branding.json` from the neutral starter — see [the branding con
 
 **Or scaffold it with `bongos init`** ([task #1204](https://example.com/builders#/task/1204)): a short interview (or `bongos init --from spec.json` for a hands-free / CI run) that writes both config files, **seeds your first version + its done-when goal**, and **files the human-only kickoff steps** (register a GitHub OAuth app, first owner sign-in, repo binding, admission) as real tracked tasks — so a fresh instance has a claimable queue on day one instead of an empty hall. It never invents your branding (it points you at the fill prompt for that). Preview the whole plan with `bongos init --dry-run`.
 
-**Production hosting, optional (the `provisioning` module — [ADR 0111](../adr/0111-instance-hosting-provisioning-module.md) §3).** If you enable the `provisioning` module and answer the interview's hosting questions (shape — co-tenant `$0` or a dedicated droplet — bring-your-own domain, credential ref, tier), init turns those answers into a real **provisioning request** (a queued `provision` intent the control-plane runner drains) instead of only filing a manual "production topology" task. **A queued request does nothing until a runner drains it:** on the control plane that is a systemd timer running `node scripts/gds/provision.js run-intents --apply`. This Docker image now carries the tools the scaffold needs — git, and a core it can package out of its own `.git`-less checkout (task 1003995) — but the standup leg still assumes root + systemd, which a container has not got (task 1003997), so on a compose self-host a new project waits indefinitely. The two irreducibly-human legs — the GitHub OAuth app and the first owner sign-in — stay guided/manual. If the module isn't enabled on the target instance, init falls back to the manual production-topology task, so nothing is silently skipped.
+**Production hosting, optional (the `provisioning` module — [ADR 0111](../adr/0111-instance-hosting-provisioning-module.md) §3).** If you enable the `provisioning` module and answer the interview's hosting questions (shape — co-tenant `$0` or a dedicated droplet — bring-your-own domain, credential ref, tier), init turns those answers into a real **provisioning request** (a queued `provision` intent the control-plane runner drains) instead of only filing a manual "production topology" task. **A queued request does nothing until a runner drains it:** on the control plane that is a systemd timer running `node scripts/gds/provision.js run-intents --apply`. This Docker image now carries the tools the scaffold needs — git, and a core it can package out of its own `.git`-less checkout (task 1003995) — and supervision is no longer systemd-only: the runner picks a process manager, falling back to supervisord where systemd is not running (task 1003997, [ADR 0306](../adr/0306-instance-supervision-is-a-seam-with-systemd-as-the-default.md)). Three standup legs still assume a systemd box, so on a compose self-host a new project waits indefinitely: the container has no reverse proxy for a child instance's front door (task 1004017), cannot create the per-instance unix account that isolates one instance from another (task 1004018), and installs its backup dir as a hardcoded founder user (task 1002719). Note supervisord has no timer concept either, so a container-hosted instance gets no automatic DB backup — the standup log prints the `crontab` line to add instead. The two irreducibly-human legs — the GitHub OAuth app and the first owner sign-in — stay guided/manual. If the module isn't enabled on the target instance, init falls back to the manual production-topology task, so nothing is silently skipped.
 
 ## Configuration surface
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.853",
+  "version": "1.19.855",
   "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/provision-config.js

@@ -63,6 +63,10 @@ const CONFIG = {
   // `<db>-<ts>.sql.gz`, so each instance's files + retention prune stay scoped to
   // its own DB. Owned by the app user, mode 0750. (task 2213, productizes 2210.)
   backupDir: process.env.PROVISION_BACKUP_DIR || '/var/backups/gds',
+  // Where supervisord program configs land when supervision is supervisord rather than
+  // systemd (ADR 0306). Unused on a systemd box. No sudo is applied to writes here: the
+  // planes that select supervisord run unprivileged and already own this dir.
+  supervisorConfDir: process.env.PROVISION_SUPERVISOR_CONF_DIR || '/etc/supervisor/conf.d',
   // Dedicated-droplet defaults (only used for hosting_shape='dedicated').
   region: process.env.PROVISION_REGION || 'nyc3',
   baseImage: process.env.PROVISION_BASE_IMAGE || 'ubuntu-24-04-x64',

package/scripts/gds/provision-process.js

@@ -0,0 +1,167 @@
+// scripts/gds/provision-process.js — WHAT SUPERVISES an instance's long-running
+// service, as a seam rather than a hardcoded string (task 1003997, ADR 0306).
+//
+// The standup used to reach for `systemctl` inline at fifteen call sites, which is fine
+// on a systemd box and impossible anywhere else: the self-host image runs USER node with
+// no sudo and boots no systemd at all. Pointing the unit path somewhere writable does not
+// help — what varies is not where the unit file goes, it is what runs the process.
+//
+// A manager answers four questions: install+enable the service, install its nightly
+// backup schedule, restart it, remove it. Each takes the instance row and an `io` of the
+// SAME shape the runbook already threads around — { exec, writeFile, sudoP, log } — so
+// the dry-run, remote-ssh and logging behaviour of makeExec/makeWriteFile carries over
+// untouched (ADR 0130). Nothing here executes anything itself.
+//
+// systemd is the default and its commands are BYTE-IDENTICAL to the strings it replaced;
+// tests/provision.mjs pins them. The live box boots systemd, so it keeps systemd.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { CONFIG, REPO_ROOT } = require('./provision-config.js');
+const { APP_USER, CORE_PKG_DIR, instanceUser, standaloneRoot } = require('./provision-repo.js');
+const {
+  backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath,
+  backupUnitName, serviceUnit, serviceUnitPath,
+} = require('./provision-units.js');
+
+// ── systemd — the default, and what every live box runs ──────────────────────
+const systemd = {
+  key: 'systemd',
+
+  installService(inst, { exec, writeFile, sudoP }) {
+    writeFile(serviceUnitPath(inst), serviceUnit(inst), { mode: 0o644, sudo: true });
+    exec(`${sudoP}systemctl daemon-reload`);
+    exec(`${sudoP}systemctl enable --now ${inst.slug}`);
+  },
+
+  // The backup DIR belongs to this step, not to the runbook: it exists only to serve the
+  // schedule, so a manager that installs no schedule must not create it either.
+  installBackup(inst, { exec, writeFile, sudoP }) {
+    exec(`${sudoP}install -d -o ${APP_USER} -g ${APP_USER} -m 0750 ${CONFIG.backupDir}`);
+    writeFile(backupServicePath(inst), backupService(inst), { mode: 0o644, sudo: true });
+    writeFile(backupTimerPath(inst), backupTimer(inst), { mode: 0o644, sudo: true });
+    exec(`${sudoP}systemctl daemon-reload`);
+    exec(`${sudoP}systemctl enable --now ${backupUnitName(inst)}.timer`);
+    return { installed: true };
+  },
+
+  restartService(inst, { exec, sudoP }) {
+    exec(`${sudoP}systemctl restart ${inst.slug}`);
+  },
+
+  // Teardown. Every step allowFail: a half-provisioned instance must still tear down.
+  // reset-failed is not optional (task 1003940): a removed unit's FAILED state outlives
+  // its file, so without it `systemctl --failed` lists torn-down ghosts for weeks.
+  removeService(inst, { exec, sudoP }) {
+    exec(`${sudoP}systemctl disable --now ${inst.slug}`, { allowFail: true });
+    exec(`${sudoP}rm -f ${serviceUnitPath(inst)}`, { allowFail: true });
+    exec(`${sudoP}systemctl disable --now ${backupUnitName(inst)}.timer`, { allowFail: true });
+    exec(`${sudoP}rm -f ${backupServicePath(inst)} ${backupTimerPath(inst)}`, { allowFail: true });
+    exec(`${sudoP}systemctl daemon-reload`, { allowFail: true });
+    exec(`${sudoP}systemctl reset-failed ${inst.slug}.service ${backupUnitName(inst)}.service`, { allowFail: true });
+  },
+};
+
+// ── supervisord — the container implementation ───────────────────────────────
+// No sudo anywhere: the self-host image runs as an unprivileged user that already owns
+// its conf dir, so escalation would fail rather than help.
+function supervisorConfPath(inst) {
+  return path.posix.join(CONFIG.supervisorConfDir, `${inst.slug}.conf`);
+}
+
+// The ExecStart equivalent, resolved the same way serviceUnit resolves it so the two
+// cannot drift: a standalone runs out of its own pinned core, anything else out of this
+// checkout.
+function programCommand(inst) {
+  return inst.hosting_shape === 'standalone'
+    ? `/usr/bin/node ${CORE_PKG_DIR}/src/platform-server.js`
+    : '/usr/bin/node src/platform-server.js';
+}
+
+function supervisorProgram(inst, { etcBase = CONFIG.etcBase } = {}) {
+  const workDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : REPO_ROOT;
+  return `[program:${inst.slug}]
+; Cloud Bongos instance — ${inst.slug} (provisioned by provision.js, ADR 0306)
+command=${programCommand(inst)}
+directory=${workDir}
+; The isolation systemd spells User=/Group= (ADR 0281). A shared uid would let every
+; instance on this plane read its siblings' /proc/<pid>/environ — every OAuth cred in
+; the env file below. Dropping this line silently removes that boundary.
+user=${instanceUser(inst)}
+environment=HOME="${path.posix.join(etcBase, inst.slug)}",PGDATABASE="${inst.db_name || inst.slug}",PORT="${inst.port}"
+autostart=true
+autorestart=true
+startsecs=3
+stdout_logfile=/var/log/supervisor/${inst.slug}.log
+redirect_stderr=true
+`;
+}
+
+const supervisord = {
+  key: 'supervisord',
+
+  installService(inst, { exec, writeFile }) {
+    writeFile(supervisorConfPath(inst), supervisorProgram(inst), { mode: 0o644 });
+    exec('supervisorctl reread');
+    exec('supervisorctl update');
+    exec(`supervisorctl start ${inst.slug}`);
+  },
+
+  // supervisord supervises processes, not schedules — it has no timer concept. Rather
+  // than re-implement cron badly, install nothing and hand the operator the exact line
+  // (ADR 0306). LOUD on purpose: a self-host with no automatic DB backup must not be a
+  // thing anyone discovers after they need one.
+  installBackup(inst, { log }) {
+    // The env the dump needs is LIFTED from the systemd unit rather than retyped, so the
+    // crontab line and the unit cannot drift and the variable names live in one place.
+    const env = backupService(inst).split('\n')
+      .filter((l) => l.startsWith('Environment='))
+      .map((l) => l.slice('Environment='.length))
+      .join(' ');
+    log(`    (no backup schedule: ${supervisord.key} has no timers — add this to a crontab instead)`);
+    log(`      0 4 * * *  ${env} /bin/bash ${backupScriptPath(inst)}`);
+    return { installed: false, reason: 'supervisord has no timer concept' };
+  },
+
+  restartService(inst, { exec }) {
+    exec(`supervisorctl restart ${inst.slug}`);
+  },
+
+  removeService(inst, { exec }) {
+    exec(`supervisorctl stop ${inst.slug}`, { allowFail: true });
+    exec(`rm -f ${supervisorConfPath(inst)}`, { allowFail: true });
+    exec('supervisorctl reread', { allowFail: true });
+    exec('supervisorctl update', { allowFail: true });
+  },
+};
+
+const MANAGERS = { systemd, supervisord };
+
+// Was this host booted under systemd? /run/systemd/system is the check sd_booted(3)
+// makes and the one systemd documents for exactly this question — it exists only when
+// systemd is PID 1, so a container answers no without us guessing at container-ness.
+function systemdIsBooted(fsImpl) {
+  try { return fsImpl.existsSync('/run/systemd/system'); } catch { return false; }
+}
+
+// Explicit → probed → default. An unrecognised knob value throws rather than falling
+// back: silently supervising an instance a different way than the operator asked is
+// worse than refusing to provision.
+function resolveProcessManager({ env = process.env, fsImpl = fs } = {}) {
+  const want = String(env.PROVISION_PROCESS_MANAGER || '').trim().toLowerCase();
+  if (want) {
+    if (MANAGERS[want]) return MANAGERS[want];
+    throw new Error(`PROVISION_PROCESS_MANAGER=${want} is not a known process manager (${Object.keys(MANAGERS).join(', ')})`);
+  }
+  return systemdIsBooted(fsImpl) ? systemd : supervisord;
+}
+
+module.exports = {
+  resolveProcessManager,
+  supervisorConfPath,
+  supervisorProgram,
+  supervisord,
+  systemd,
+};

package/scripts/gds/provision-teardown.js

@@ -12,7 +12,7 @@
 const path = require('node:path');
 const { CONFIG, REPO_ROOT } = require('./provision-config.js');
 const { dbName, deployKeyPath, deployKeyTitle, parseTargetRef, resolveOwnerGithubToken } = require('./provision-repo.js');
-const { backupServicePath, backupTimerPath, backupUnitName, serviceUnitPath } = require('./provision-units.js');
+const { resolveProcessManager } = require('./provision-process.js');
 const { caddySnippetPath, dnsReleaseEnv } = require('./provision-net.js');
 const apexMod = require('./instance-apex.js');
 const { isReservedHostname } = require('../../modules/provisioning/provisioning.js');
@@ -29,13 +29,8 @@ async function teardownInstance(inst, deps) {
   log(`teardown ${inst.slug} (status=${inst.status})`);
   if (apply) await provisioning.setInstanceStatus(db, inst.id, 'tearing_down');
   if (inst.hosting_shape !== 'dedicated') {
-    boxExec(`${sudoP}systemctl disable --now ${inst.slug}`, { allowFail: true });
-    boxExec(`${sudoP}rm -f ${serviceUnitPath(inst)}`, { allowFail: true });
-    // Stop + remove the nightly backup units too (task 2213; the dir + dumps stay — precious data, like the DB below), then reset-failed (task 1003940): a removed unit's FAILED state outlives its file, so `systemctl --failed` listed torn-down ghosts for weeks.
-    boxExec(`${sudoP}systemctl disable --now ${backupUnitName(inst)}.timer`, { allowFail: true });
-    boxExec(`${sudoP}rm -f ${backupServicePath(inst)} ${backupTimerPath(inst)}`, { allowFail: true });
-    boxExec(`${sudoP}systemctl daemon-reload`, { allowFail: true });
-    boxExec(`${sudoP}systemctl reset-failed ${inst.slug}.service ${backupUnitName(inst)}.service`, { allowFail: true });
+    // Stop + remove the service AND the nightly backup units (task 2213; the dir + dumps stay — precious data, like the DB below). Whoever supervises the instance owns its removal (ADR 0306) — the systemd manager keeps the reset-failed step task 1003940 added, since a removed unit's FAILED state outlives its file and `systemctl --failed` listed torn-down ghosts for weeks.
+    (deps.processManager || resolveProcessManager()).removeService(inst, { exec: boxExec, sudoP });
     // The site snippet standup step 6 wrote: while it stays, Caddy proxies the hostname to
     // a port nothing listens on and every visitor gets a 502 (task 1002897). Not precious.
     boxExec(`${sudoP}rm -f ${caddySnippetPath(inst)}`, { allowFail: true });

package/scripts/gds/provision.js

@@ -53,12 +53,17 @@ const { CONFIG, MANIFEST_UA, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES,
 const { APP_USER, alreadyScaffolded, buildCorePinRefreshCommit, coreCheckoutHasGit, dbCreateCmd, dbName, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd, ensureInstanceUserCmd, generateDbPassword, grantInstanceRepoReadCmd, instanceDbRole, instanceStateDir, instanceUser, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, ownerLoginOf, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
 const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkCaddyWiring, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, shouldFederate, zoneForDomain } = require('./provision-net.js');
+const { resolveProcessManager } = require('./provision-process.js');
 const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.js');
 const { installedCoreVersion, runnerBanner } = require('./runner-drift.js');
 const { teardownInstance } = require('./provision-teardown.js');
 const { disconnectInstance } = require('./provision-disconnect.js');
 const { coreUpgradeInstance, snapshotAllCoreVersions } = require('./provision-core-upgrade.js'); // the owner's deploy door, ADR 0293
 
+// WHAT supervises an instance's service (ADR 0306). systemd on every box we run — the
+// seam exists so a plane without systemd is not a dead end. Injectable for tests.
+const pmFor = (deps) => (deps && deps.processManager) || resolveProcessManager();
+
 function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = null, sshOpts = '' }) {
   // `shown` (task 1003140): what to LOG in place of the command text — for a command
   // that carries a secret (a remote file placement embeds the base64 body), so the
@@ -435,12 +440,11 @@ async function provisionInstance(inst, deps) {
   if (local) boxWriteFile(webEnvPath(inst), webEnvBody(inst, { federation, ownerLogin: await ownerLoginOf(inst, deps.db), dbPassword }), { mode: 0o600, sudo: true });
   else log('    (baked into cloud-init)');
 
-  // ── step 4: systemd unit + enable ─────────────────────────────────────────
-  log('  [service] install + enable systemd unit');
+  // ── step 4: install + enable the instance's service ───────────────────────
+  const pm = pmFor(deps);
+  log(`  [service] install + enable the ${pm.key} service`);
   if (local) {
-    boxWriteFile(serviceUnitPath(inst), serviceUnit(inst), { mode: 0o644, sudo: true });
-    boxExec(`${sudoP}systemctl daemon-reload`);
-    boxExec(`${sudoP}systemctl enable --now ${inst.slug}`);
+    pm.installService(inst, { exec: boxExec, writeFile: boxWriteFile, sudoP, log });
   } else { log('    (unit baked into cloud-init)'); }
 
   // ── step 4b: nightly DB backup — dir + consumer-layout timer/service (task 2213) ──
@@ -451,11 +455,7 @@ async function provisionInstance(inst, deps) {
   // overwrites, `enable --now` is idempotent. Dedicated bakes the same into cloud-init.
   log('  [backup] create backup dir + install + enable nightly DB backup timer');
   if (local) {
-    boxExec(`${sudoP}install -d -o ${APP_USER} -g ${APP_USER} -m 0750 ${CONFIG.backupDir}`);
-    boxWriteFile(backupServicePath(inst), backupService(inst), { mode: 0o644, sudo: true });
-    boxWriteFile(backupTimerPath(inst), backupTimer(inst), { mode: 0o644, sudo: true });
-    boxExec(`${sudoP}systemctl daemon-reload`);
-    boxExec(`${sudoP}systemctl enable --now ${backupUnitName(inst)}.timer`);
+    pm.installBackup(inst, { exec: boxExec, writeFile: boxWriteFile, sudoP, log });
   } else { log('    (backup dir + units baked into cloud-init)'); }
 
   // ── step 5: DNS — Cloudflare A-record UPSERT for the instance's domain (P4) ──
@@ -778,7 +778,7 @@ async function domainAttachInstance(inst, deps) {
     boxWriteFile(webEnvPath(inst), upsertEnvVars(currentEnv, origins), { mode: 0o600, sudo: true });
   }
   log('  [service] restart to pick up the new origins');
-  boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+  pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
 
   // DNS A-record UPSERT — mirrors provisionInstance step 5 (control-plane exec only:
   // the hook needs the Cloudflare token, which never leaves the control plane).
@@ -889,7 +889,7 @@ async function settingsApplyInstance(inst, deps) {
   const current = String((read && read.stdout) || '');
   if (!apply) {
     log(`  [config] would patch ${Object.keys(vars).join(', ')} in ${webEnvPath(inst)} in place (every other line untouched)`);
-    boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
     boxExec(healthzCmd(inst), { allowFail: true });
     log(`  ✓ would restart ${inst.slug} with the new settings (dry-run — nothing ran)`);
     return { ok: true, healthy: null, consumed: null };
@@ -901,7 +901,7 @@ async function settingsApplyInstance(inst, deps) {
     log('  [config] patch the settings lines of web.env in place (creds + origins untouched)');
     boxWriteFile(webEnvPath(inst), upsertEnvVars(current, vars), { mode: 0o600, sudo: true });
     log('  [service] restart so the memoized branding pack re-reads them');
-    boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
   } catch (e) {
     // ok:false, never a throw: the retry re-reads the file (the upsert is
     // idempotent) and restarts again; the instance's status is left alone.
@@ -991,14 +991,14 @@ async function restartInstance(inst, deps) {
     return { ok: false, error: `restart is not automated for a dedicated droplet — run 'systemctl restart ${inst.slug}' on that machine` };
   }
   if (!apply) {
-    boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
     boxExec(healthzCmd(inst), { allowFail: true });
     log(`  ✓ would restart ${inst.slug} and wait for it to answer (dry-run — nothing ran)`);
     return { ok: true, healthy: null };
   }
   try {
     log('  [service] restart');
-    boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
   } catch (e) {
     // ok:false, never a throw — the retry simply restarts again (idempotent).
     return { ok: false, error: `could not restart ${inst.slug}: ${(e && e.message) || e}` };
@@ -1142,7 +1142,7 @@ async function placeManifestCreds(inst, mrow, deps) {
     // it is harmless and heals once the owner grants the permissions + installs.
     appId: creds.appId, appPem: creds.appPem,
   }), { mode: 0o600, sudo: true });
-  boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+  pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
 
   // 4) verify /healthz reports auth_configured=true (only meaningful under --apply).
   //    PATIENT (F23): the child must boot before it can answer; losing this race

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.853'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.855'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/box_sweep_docs.mjs

@@ -0,0 +1,115 @@
+// tests/box_sweep_docs.mjs — the box sweep docs must not invert against box.js
+// a third time (task 1003823).
+//
+// HISTORY, because it is the whole reason this file exists. The idle sweep has
+// changed direction twice:
+//
+//   task 804     — sweep-idle went from park to a direct deprovision, and
+//                  task 1001135 dragged four doc surfaces along with it.
+//   task 1002726 — the CODE went BACK to park-and-keep-the-snapshot, because
+//                  annihilating an idle box took the builder's uncommitted work
+//                  with it. The four doc surfaces were NOT walked back.
+//
+// So for months the routine's own SKILL.md told an agent "your single job is to
+// DESTROY" while cmdSweepIdle called parkOne. The danger is specific and worth
+// naming: an agent that believes it is supposed to destroy, and finds the sweep
+// merely parking, is being invited to reach for `box.js deprovision` to finish a
+// job it was never given — which is the one path that can silently discard a
+// builder's work.
+//
+// This guard is therefore NOT a spell-check. It asserts the one relationship
+// that matters: WHILE cmdSweepIdle parks, the docs may not say it destroys.
+// If a future task legitimately moves the idle path back to a destroy, this test
+// goes green on its own as soon as the code changes — it is pinned to the code,
+// not to a preferred wording.
+
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8');
+
+const BOX_JS = 'scripts/gds/box.js';
+const IDLE_SKILL = '.claude/scheduled-tasks/box-idle-suspend/SKILL.md';
+const DORMANT_SKILL = '.claude/scheduled-tasks/box-dormant-reclaim/SKILL.md';
+const RECIPE = 'docs/recipes/builder-box-lifecycle.md';
+
+// Comments are stripped before scanning prose: each surface deliberately keeps a
+// sentence SAYING which model it used to describe, and a naive substring check
+// would read that history as the claim still being made.
+const stripHtmlComments = (md) => md.replace(/<!--[\s\S]*?-->/g, '');
+
+// The body of cmdSweepIdle, so "what the sweep does" is read from the function
+// itself rather than from a header comment that can rot the same way the docs did.
+function cmdSweepIdleBody() {
+  const src = read(BOX_JS);
+  const start = src.indexOf('async function cmdSweepIdle(');
+  assert.ok(start > 0, `cmdSweepIdle not found in ${BOX_JS} — this guard is reading the wrong file`);
+  const next = src.indexOf('\nasync function ', start + 1);
+  return src.slice(start, next > 0 ? next : src.length);
+}
+
+test('the idle sweep parks — that is the fact the docs are measured against', () => {
+  const body = cmdSweepIdleBody();
+  assert.match(body, /parkOne\(/, 'cmdSweepIdle no longer calls parkOne');
+  assert.doesNotMatch(body, /deprovisionOne\(/,
+    'cmdSweepIdle calls deprovisionOne — the idle path destroys again. That is allowed, '
+    + 'but the docs below must be rewritten to match BEFORE this guard is relaxed.');
+});
+
+test('no box-sweep doc claims the IDLE sweep destroys, while the code parks', () => {
+  // Sentences that assert a destroy as the idle sweep's OUTCOME. Each pattern is
+  // anchored on the idle path specifically, because "destroy the droplet" is a
+  // true statement about a park (the droplet does go; the snapshot stays) and
+  // "destroy the snapshot" is a true statement about sweep-dormant.
+  const lies = [
+    /idle[- ]deprovision/i,
+    /idle box is fully DESTROYED/i,
+    /destroy the droplet \*\*AND\*\* (?:its )?snapshot/i,
+    /droplet \+ snapshot destroyed/i,
+    /idle no longer feeds it/i,
+    /no longer parks/i,
+    /there is no snapshot to wake from/i,
+    /single job is to DESTROY/i,
+  ];
+
+  for (const file of [IDLE_SKILL, DORMANT_SKILL, RECIPE]) {
+    const prose = stripHtmlComments(read(file));
+    for (const lie of lies) {
+      assert.doesNotMatch(prose, lie,
+        `${file} still describes the pre-task-1002726 destroy model (${lie}). `
+        + 'cmdSweepIdle calls parkOne and keeps the snapshot — see task 1003823.');
+    }
+  }
+});
+
+test('the idle skill quotes the strings the worker actually prints', () => {
+  // Step 3 of the skill orders a VERBATIM relay, so a drifted string here makes
+  // the agent either fabricate a line or stall. These are the three the worker emits.
+  const skill = read(IDLE_SKILL);
+  const body = cmdSweepIdleBody();
+
+  for (const s of ['would park', 'snapshot kept, compute stopped', 'done — parked=']) {
+    assert.ok(body.includes(s), `cmdSweepIdle no longer prints ${JSON.stringify(s)}`);
+    assert.ok(skill.includes(s),
+      `${IDLE_SKILL} does not quote ${JSON.stringify(s)}, which the worker prints and `
+      + 'step 3 tells the agent to relay verbatim.');
+  }
+
+  assert.ok(!/done — deprovisioned=/.test(skill),
+    `${IDLE_SKILL} tells the agent to relay "done — deprovisioned=", a line the worker never emits.`);
+});
+
+test('every surface names sweep-dormant as the only automated snapshot delete', () => {
+  // The safety property box.js implements in prose: full reclaim warns first, so
+  // no automated path takes uncommitted work silently. A reader who misses this
+  // is the reader who reaches for deprovision.
+  for (const file of [IDLE_SKILL, DORMANT_SKILL, RECIPE]) {
+    assert.match(stripHtmlComments(read(file)), /only automated path that destroys a snapshot|only automated snapshot delete/i,
+      `${file} never tells the reader that sweep-dormant is the only automated path that `
+      + 'destroys a snapshot (and that it warns first) — the safety property this subsystem rests on.');
+  }
+});

package/tests/provision.mjs

@@ -34,6 +34,12 @@ const reEsc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 // (the resolution rule itself is covered directly, with an injected probe).
 process.env.PROVISION_GIT_SSH_ALIAS = 'github-deploy';
 
+// Same reasoning for supervision (task 1003997, ADR 0306): the manager is probed from
+// /run/systemd/system when nothing pins it, so pin systemd here — the composition
+// assertions below are about the runbook, not about whether the test box boots systemd.
+// The probe itself is covered directly, with an injected fs.
+process.env.PROVISION_PROCESS_MANAGER = 'systemd';
+
 let passed = 0, failed = 0;
 function t(name, fn) {
   try { fn(); passed++; console.log(`  PASS  ${name}`); }
@@ -576,6 +582,113 @@ t('instanceRepoRemotes: the accept-set a stored remote is validated against, pro
   } finally { process.env.PROVISION_GIT_SSH_ALIAS = saved; }
 });
 
+// ── the process-manager seam (task 1003997, ADR 0306) ───────────────────────
+const PM = createRequire(import.meta.url)('../scripts/gds/provision-process.js');
+
+// A recording io: the same { exec, writeFile, sudoP, log } shape the runbook hands over.
+function recordIo({ sudoP = '' } = {}) {
+  const cmds = [], files = [], logs = [];
+  return {
+    cmds, files, logs, sudoP,
+    exec: (cmd, opts) => cmds.push(opts && opts.allowFail ? `${cmd} [allowFail]` : cmd),
+    writeFile: (p, body, opts) => files.push({ path: p, body, opts }),
+    log: (m) => logs.push(m),
+  };
+}
+const INST = { slug: 'demo', hosting_shape: 'standalone', port: 3003, db_name: 'demo' };
+
+t('resolveProcessManager: explicit knob wins, then the /run/systemd/system probe', () => {
+  const booted = { existsSync: (p) => p === '/run/systemd/system' };
+  const bare = { existsSync: () => false };
+  assert.equal(PM.resolveProcessManager({ env: { PROVISION_PROCESS_MANAGER: 'supervisord' }, fsImpl: booted }).key,
+    'supervisord', 'the knob overrides even a systemd host');
+  assert.equal(PM.resolveProcessManager({ env: {}, fsImpl: booted }).key, 'systemd',
+    'the live box boots systemd, so it keeps systemd');
+  assert.equal(PM.resolveProcessManager({ env: {}, fsImpl: bare }).key, 'supervisord',
+    'a container boots no systemd');
+  assert.throws(() => PM.resolveProcessManager({ env: { PROVISION_PROCESS_MANAGER: 'runit' }, fsImpl: booted }),
+    /PROVISION_PROCESS_MANAGER/, 'an unknown manager is LOUD, never a silent fallback');
+});
+
+t('systemd manager: emits byte-identical commands + unit paths to the inline strings it replaced', () => {
+  const io = recordIo({ sudoP: 'sudo ' });
+  PM.systemd.installService(INST, io);
+  assert.deepEqual(io.cmds, ['sudo systemctl daemon-reload', 'sudo systemctl enable --now demo']);
+  assert.equal(io.files[0].path, '/etc/systemd/system/demo.service');
+  assert.deepEqual(io.files[0].opts, { mode: 0o644, sudo: true });
+
+  const io2 = recordIo({ sudoP: 'sudo ' });
+  PM.systemd.installBackup(INST, io2);
+  // The backup DIR moved in here with the schedule it serves: a manager that installs no
+  // schedule must not create it either. Order is unchanged — dir, units, reload, enable.
+  assert.match(io2.cmds[0], /^sudo install -d -o \S+ -g \S+ -m 0750 /);
+  assert.deepEqual(io2.cmds.slice(1), ['sudo systemctl daemon-reload', 'sudo systemctl enable --now demo-db-backup.timer']);
+  assert.deepEqual(io2.files.map((f) => f.path),
+    ['/etc/systemd/system/demo-db-backup.service', '/etc/systemd/system/demo-db-backup.timer']);
+
+  const io3 = recordIo({ sudoP: 'sudo ' });
+  PM.systemd.restartService(INST, io3);
+  assert.deepEqual(io3.cmds, ['sudo systemctl restart demo']);
+
+  const io4 = recordIo({ sudoP: 'sudo ' });
+  PM.systemd.removeService(INST, io4);
+  assert.deepEqual(io4.cmds, [
+    'sudo systemctl disable --now demo [allowFail]',
+    'sudo rm -f /etc/systemd/system/demo.service [allowFail]',
+    'sudo systemctl disable --now demo-db-backup.timer [allowFail]',
+    'sudo rm -f /etc/systemd/system/demo-db-backup.service /etc/systemd/system/demo-db-backup.timer [allowFail]',
+    'sudo systemctl daemon-reload [allowFail]',
+    'sudo systemctl reset-failed demo.service demo-db-backup.service [allowFail]',
+  ], 'including reset-failed — a removed unit\'s FAILED state outlives its file (task 1003940)');
+});
+
+t('systemd manager: an UNPRIVILEGED run drops the sudo prefix and nothing else', () => {
+  const io = recordIo({ sudoP: '' });
+  PM.systemd.installService(INST, io);
+  assert.deepEqual(io.cmds, ['systemctl daemon-reload', 'systemctl enable --now demo']);
+});
+
+t('supervisord manager: a program config, no systemd, and the ADR 0281 user= carried over', () => {
+  const io = recordIo();
+  PM.supervisord.installService(INST, io);
+  const conf = io.files[0];
+  assert.equal(conf.path, '/etc/supervisor/conf.d/demo.conf');
+  assert.match(conf.body, /^\[program:demo\]$/m);
+  assert.match(conf.body, /^user=/m, 'isolation is restated per manager, never dropped (ADR 0306)');
+  assert.match(conf.body, /platform-server\.js/, 'it runs the same entrypoint the unit did');
+  assert.deepEqual(io.cmds, ['supervisorctl reread', 'supervisorctl update', 'supervisorctl start demo']);
+  assert.ok(!io.cmds.some((c) => /systemctl/.test(c)), 'nothing reaches for systemd');
+
+  const io2 = recordIo();
+  PM.supervisord.restartService(INST, io2);
+  assert.deepEqual(io2.cmds, ['supervisorctl restart demo']);
+
+  const io3 = recordIo();
+  PM.supervisord.removeService(INST, io3);
+  assert.deepEqual(io3.cmds, [
+    'supervisorctl stop demo [allowFail]',
+    'rm -f /etc/supervisor/conf.d/demo.conf [allowFail]',
+    'supervisorctl reread [allowFail]',
+    'supervisorctl update [allowFail]',
+  ]);
+});
+
+t('supervisord manager: installs NO backup schedule and says so with the crontab line', () => {
+  const io = recordIo();
+  const r = PM.supervisord.installBackup(INST, io);
+  assert.equal(r.installed, false, 'supervisord supervises processes, not schedules');
+  assert.deepEqual(io.files, [], 'no unit files invented');
+  assert.deepEqual(io.cmds, [], 'and no scheduler commands either');
+  assert.ok(io.logs.some((l) => /crontab|cron/i.test(l)),
+    'the skip is LOUD and hands the operator the line to add (ADR 0306)');
+  assert.ok(io.logs.some((l) => /db-backup-nightly\.sh/.test(l)), 'naming the actual script');
+  // The env is lifted from the systemd unit, so the line the operator pastes carries the
+  // same DB and dir the timer would have used — and cannot drift from it.
+  const cronLine = io.logs.find((l) => /db-backup-nightly\.sh/.test(l));
+  assert.ok(/_BACKUP_DB=demo\b/.test(cronLine) && /_BACKUP_DIR=\S+/.test(cronLine),
+    'the dump env rides along, taken from the unit rather than retyped');
+});
+
 t('instanceInitSpec: builds a VALID greenfield init spec from the row + owner login', () => {
   const spec = P.instanceInitSpec(
     { slug: 'demo', target_ref: 'example-owner/demo', domain: 'demo.cloudbongos.com', port: 3003 },