@bongos/core 1.19.887 → 1.19.889

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.887",
-  "core_contract": "1.19.887",
-  "source_commit": "b874dffd8907b22a633526eddcb279c009c89b40",
+  "core_version": "1.19.889",
+  "core_contract": "1.19.889",
+  "source_commit": "b7871cd73a1ce5f73988d99ef63101a6a2d23050",
   "source_ref": "HEAD",
-  "built_at": "2026-09-19T20:48:51.300Z",
+  "built_at": "2026-09-19T21:23:27.620Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 497,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2264,
+    "functional_verbatim": 2269,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2787,
-  "tree_sha256": "920b5751e940860113c8a2a84ede022e547e1901077f62330213144c8612091b",
+  "file_count": 2792,
+  "tree_sha256": "b7b8bc9e53808070c5d46a211481ceef0dea2c901bc79e2b0dc0871e60c362b1",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2607,7 +2607,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "31fdd25f81e095205720c92ce31100187f7d1c1c89eecc8b9c84f00936350352"
+      "sha256": "01a90a40951ae88d4c36c5fabbaf3debc0e02bcaa9fa8a7b70e247aa5d61d236"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2742,7 +2742,7 @@
     {
       "path": "docs/recipes/gds-db-backup.md",
       "mode": "0000644",
-      "sha256": "b3d6a3e3a400bf593b0f2d671f35cb1a60279f495c8763d311f8cdb68a6d603a"
+      "sha256": "d3e628bc627cb29874e977bf2e93c6557dc72a210506c22515a983f4f513d627"
     },
     {
       "path": "docs/recipes/instance-deploy.md",
@@ -3699,6 +3699,11 @@
       "mode": "0000644",
       "sha256": "4f35f87050a532f26b7c9cd0a9bc6f298ab5c0e15eb1c36ddcdd4d261201291d"
     },
+    {
+      "path": "migrations/core_249_session_token_hash.sql",
+      "mode": "0000644",
+      "sha256": "ae3e405c7e59fbc13e23ae2a4ba945176f2369a150c997d9b8134e49991f273b"
+    },
     {
       "path": "modules/agents/CLAUDE.md",
       "mode": "0000644",
@@ -3732,7 +3737,7 @@
     {
       "path": "modules/agents/lib/validate.js",
       "mode": "0000644",
-      "sha256": "3ff56e388e9ae4cccb09fb072793b5544f771aeae51e8477f8a221f0c78b9515"
+      "sha256": "e9b3c905539a323d74a55f98455204bd46daca2daf49c476324e85684ba7971f"
     },
     {
       "path": "modules/agents/migrations/agents_001_definitions.sql",
@@ -3754,6 +3759,11 @@
       "mode": "0000644",
       "sha256": "31a5ac35536cecd264bc989907f4cf094e050db0b8de85e7e3e7831cf7c25a9d"
     },
+    {
+      "path": "modules/agents/migrations/agents_005_cron_trigger.sql",
+      "mode": "0000644",
+      "sha256": "5d422998b1d53ee015f4a494ccede1adcb1eb90bd501bd28c1d88f9840b87367"
+    },
     {
       "path": "modules/agents/module.json",
       "mode": "0000644",
@@ -7692,12 +7702,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "356149fe3c3c69d00f16886662e5fee0ab51c4be066af64156a2b3bb7e14c69c"
+      "sha256": "d1348f68cd79ad102a381e3d7f90b784d9df605e859269ede84ad859cc831deb"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "9e2d057866feafc0e9606c36335013a47ad55190c03e7beed63d1e592f2fd23a"
+      "sha256": "36e895c05e2aed3f97ce34ae3b3f73b0492fff7185077519068bc69dda6a8fd6"
     },
     {
       "path": "public-docs/index.html",
@@ -8127,7 +8137,7 @@
     {
       "path": "scripts/gds/db-backup-offsite.sh",
       "mode": "0000644",
-      "sha256": "f455e4a6fdd69f0105104752c86099e3a17dad7b4802fa715191cedab9762cd2"
+      "sha256": "97f52f6aff95e1c81e069c1d4228eecb514af6068c810441465b5f5b7ee0f2ce"
     },
     {
       "path": "scripts/gds/demote.js",
@@ -8802,7 +8812,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "8227fe5256b530d22192cd86f3624d52cc1dc34ac82099a8bb9e3d6a28482eb9"
+      "sha256": "a40a90ba6255820130aa6a94ddc314b643177e4a153750dc6290550a75e1a4e8"
     },
     {
       "path": "scripts/gds/runner-drift.js",
@@ -9442,12 +9452,12 @@
     {
       "path": "src/bongos/db-kernel.js",
       "mode": "0000644",
-      "sha256": "1fffc39fb9b70cd009d7d239729a9ff329cd41ca1f35b50b7c9e6b89aa83624e"
+      "sha256": "dd16328ac569aa8c6af09b2700957634e2c6d368d291b015a74a8dc452dc340a"
     },
     {
       "path": "src/bongos/db.js",
       "mode": "0000644",
-      "sha256": "e88c470ed9399be2930ec2d925e0864c30e355bf20d89486fb57dbe7561f6d78"
+      "sha256": "def84475a0470dafb894e7ca3f96f9db27cea78964f90ac3e81ed748fe9efa48"
     },
     {
       "path": "src/bongos/github-repos.js",
@@ -9702,7 +9712,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "309fd0ddeb0185da023052aaab8967162dbdb833ade7226f49e1636440146e83"
+      "sha256": "541b09991f4858b3255f250ef7e52e86b0d561ec69d058e74bc218fe1a104932"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9844,6 +9854,11 @@
       "mode": "0000644",
       "sha256": "eea8f9e0bdf2c84fabc81e16c30e4026a7a336c1e705d614e68b805957b9b74a"
     },
+    {
+      "path": "tests/agents_cron_trigger.mjs",
+      "mode": "0000644",
+      "sha256": "be78fa37657214c39a4880d2e1b44a1647c8b509d63262ca9a4a334431d7bdde"
+    },
     {
       "path": "tests/agents_event_router.mjs",
       "mode": "0000644",
@@ -9877,7 +9892,7 @@
     {
       "path": "tests/agents_validate.mjs",
       "mode": "0000644",
-      "sha256": "9376185bc6e11571b050dcf61a993faf780cea66aa4c0844d114b1cb738043e2"
+      "sha256": "164059d69fabbd5dd70a29b29c524b5359f0346b71091e73a5e4fafa5dbc0804"
     },
     {
       "path": "tests/agents_write_routes.mjs",
@@ -10082,7 +10097,7 @@
     {
       "path": "tests/auth_session_expiry_db.mjs",
       "mode": "0000644",
-      "sha256": "880cbfa0304ab037db980f22471a2b46bcdbad0e7dca57af359402dbb068d6a4"
+      "sha256": "89730864ff5aa36271582c7e2717bf434bc84cbc20b615026005a1ef662ff31c"
     },
     {
       "path": "tests/auth_session_ttl.mjs",
@@ -11347,7 +11362,7 @@
     {
       "path": "tests/government_live_proof.mjs",
       "mode": "0000644",
-      "sha256": "6d829af6ef71bfa744a4ff457a4766b5cce021f317661579b06ecfc14298a523"
+      "sha256": "ca29425b30e726e6a7e939b008f0e5ca71877fa88fdcbfe1bf6356482f47c1e8"
     },
     {
       "path": "tests/government_live_proof_shape.mjs",
@@ -12362,7 +12377,7 @@
     {
       "path": "tests/own_session_revoke.mjs",
       "mode": "0000644",
-      "sha256": "34ae2846e314ad4ba732a40257fb81f7b4e4be3e81e3b6d1f478c3bb0690f23d"
+      "sha256": "ff24d3753a52a64f426e0602bc2411aad13c1426c2bc0774b7618a1d20cebfad"
     },
     {
       "path": "tests/package_core.mjs",
@@ -13224,6 +13239,16 @@
       "mode": "0000644",
       "sha256": "a630ac72981f230e8aa6609152765c13e8928ac329cb0ff3fe615371f31208d2"
     },
+    {
+      "path": "tests/session_token_hash.mjs",
+      "mode": "0000644",
+      "sha256": "ff4cea59acb15ce383d9346793206865f0aababc5e2f4144c957bb93d45f62b4"
+    },
+    {
+      "path": "tests/session_token_hash_db.mjs",
+      "mode": "0000644",
+      "sha256": "4a757c27f11cde314649e46ab24e51600d24c2f503f1aa7f055cdb4fa60ea6ce"
+    },
     {
       "path": "tests/session_type.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2248,5 +2248,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.885 with no explicit bump. run 35467975408. (task 1002620)
   1.19.887 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.886 with no explicit bump. run 35468511941. (task 1002620)
+  1.19.888 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.887 with no explicit bump. run 35468948342. (task 1002620)
+  1.19.889 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.888 with no explicit bump. run 35470239834. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/gds-db-backup.md

@@ -46,8 +46,33 @@ gds-db-offsite.timer ──→ gds-db-offsite.service ──→ db-backup-offsit
 - **It does not take its own `pg_dump`.** It uploads the newest `/var/backups/gds/<db>-*.sql.gz` that the local nightly already produced. Runs at 05:00 UTC — one hour after the 04:00 local dump — so the copy is same-day-fresh.
 - **Bucket layout:** objects land under the `gds-offsite/` key prefix in the Space.
 - **Retention:** 4 weekly copies (`GDS_OFFSITE_KEEP=4` — ~1 month), pruned oldest-first under that prefix. Sub-1 MB each.
-- **Credentials** live at `/etc/example/spaces.env` (chmod 600, owned by `lars`), never in the repo (ADR 0022). Required vars: `SPACES_KEY`, `SPACES_SECRET`, `SPACES_BUCKET`, `SPACES_REGION`, `SPACES_ENDPOINT`. systemd injects them via `EnvironmentFile`; a manual run sources the same file.
-- **Dependency:** `python3` + the `boto3` module on the droplet. The script fails loudly if either is missing.
+- **Credentials** live at `/etc/example/spaces.env` (chmod 600, owned by `lars`), never in the repo (ADR 0022). Required vars: `SPACES_KEY`, `SPACES_SECRET`, `SPACES_BUCKET`, `SPACES_REGION`, `SPACES_ENDPOINT`, `GDS_OFFSITE_AGE_RECIPIENT`. systemd injects them via `EnvironmentFile`; a manual run sources the same file.
+- **Dependency:** `age`, plus `python3` + the `boto3` module on the droplet. The script fails loudly if any is missing.
+- **The uploaded object is encrypted** (`<db>-<date>.sql.gz.age`) and the retention count applies to those. Any legacy plaintext `.sql.gz` object still under the prefix is **deleted on the next run**, outside the retention count — see below.
+
+#### Offsite dumps are encrypted (task [#1003372](https://cloudbongos.com/builders#/task/1003372), audit A1)
+
+Until this task the weekly job uploaded the raw `pg_dump`. A dump is not merely "a backup": it is every secret the platform holds, in one file, on storage the platform does not own — OAuth credentials, the GitHub App private key, and (before `core_249`) every builder's live session bearer in plaintext. A breach of the Space, a mis-set bucket ACL or a leaked read-only S3 key was a total compromise with no trace in any log we keep.
+
+The dump is now encrypted with [`age`](https://github.com/FiloSottile/age) **to a public key**, so the droplet can produce backups it cannot itself read. That asymmetry is the point: an attacker who owns the droplet already has the live database, but they do not also get the archive of every previous state, and they cannot decrypt what is already in the Space. **Keep the private key off the server.**
+
+```bash
+# ONE-TIME, on a machine that is NOT the server:
+age-keygen -o bongos-backup.key      # store safe + OFFLINE — this is the only way back
+# it prints:  Public key: age1xxxxxxxx...
+```
+
+Add the **public** key to `/etc/example/spaces.env` as `GDS_OFFSITE_AGE_RECIPIENT=age1...`.
+
+> **Without a recipient the job refuses to run**, and does not fall back to a plaintext upload — that fallback is the vulnerability, and a silent one, since a backup that "worked" looks identical either way. A failing timer is visible in `systemctl status gds-db-offsite.timer`; an unencrypted dump in a bucket is visible to nobody until it matters. **If offsite backups stop after this deploy, this is why** — set the recipient.
+>
+> **The first successful run also PURGES every unencrypted `.sql.gz` already in the Space**, unconditionally and outside the retention count. Encrypting from here on does nothing about the copies already up there, and retaining four of them "for safety" would retain the finding. Local nightly dumps on the droplet are untouched, so this removes copies, never the last copy.
+
+To restore an offsite object:
+
+```bash
+age -d -i bongos-backup.key <db>-<date>.sql.gz.age | gunzip | psql <db>
+```
 
 > **History:** an earlier task ([#7](https://example.com/builders#/task/7)) shipped a `scripts/backup.sh` + `/etc/cron.d/otb-backup` daily-to-Spaces cron that was forgotten and never worked (empty credentials, no Space, no log). [#415](https://example.com/builders#/task/415) retired it and replaced it with the systemd unit above. If you find any trace of `otb-backup.cron`, `scripts/backup.sh`, or `~/.config/otb/spaces.env` on a host, it's dead — remove it.
 >
@@ -65,6 +90,9 @@ SPACES_SECRET=...
 SPACES_BUCKET=otb-gds-backups
 SPACES_REGION=nyc3
 SPACES_ENDPOINT=https://nyc3.digitaloceanspaces.com
+# The age PUBLIC key from `age-keygen`, generated OFF this box (see above).
+# Without it the job refuses to run rather than upload plaintext.
+GDS_OFFSITE_AGE_RECIPIENT=age1...
 ENV
 sudo chmod 600 /etc/example/spaces.env
 

package/migrations/core_249_session_token_hash.sql

@@ -0,0 +1,103 @@
+-- core_249 — builder_sessions stores a HASH of the bearer, never the bearer
+-- (task 1003372, audit ref A1 from the 2026-08-29 security audit, goal 1000084).
+--
+-- forward-unsafe: drops builder_sessions.token and makes token_hash NOT NULL.
+-- Both are the point of the migration, not incidental to it. The whole finding is
+-- that the plaintext bearer is READABLE AT REST, so a version of this that kept the
+-- column would not fix anything; and the NOT NULL is what stops a future writer
+-- inserting a session no lookup can ever match. Neither is reversible, and neither
+-- should be: rolling back to code that reads `token` finds it gone, but a variant
+-- that merely emptied the column would leave that code finding NULL and signing
+-- everyone out just the same — so the unsafety is in the rollback direction only,
+-- and is identical either way. Forward, nobody is signed out: the backfill below
+-- derives every existing row's hash from the plaintext before the column goes.
+--
+-- WHAT WAS WRONG. `token` held the live bearer in plaintext, NOT NULL UNIQUE and
+-- INDEXED. Every row was a directly replayable credential for the builder it
+-- belonged to — Archons included — so ANY read of this table was a complete
+-- takeover of every account holding a session. That is the exact credential the
+-- whole ADR 0016 trust boundary rests on: the server re-resolves authority per
+-- request from a token, so a token IS the authority. `token_hash` had zero
+-- occurrences repo-wide before this migration.
+--
+-- A read of the table is not hypothetical. The offsite dump was uploaded
+-- unencrypted (same task, `scripts/gds/db-backup-offsite.sh`), and a co-tenant
+-- Postgres role reached this table across tenants until task 1003369 split the
+-- unix accounts. Hashing at rest is what makes those reads worthless rather than
+-- catastrophic.
+--
+-- WHY A BACKFILL AND NOT A FORCED RE-AUTH. The hash is computable from the
+-- plaintext we already hold, so every live session survives the change: the row
+-- keeps working and its holder notices nothing. The alternative — ship the code
+-- and let sessions re-mint — would sign out every builder and every dev box on
+-- deploy day to reach a state this statement reaches for free. Migration 035 and
+-- core_243 both reasoned this way in their own direction: do not put a policy
+-- change on the backs of the people holding live sessions when it lands.
+--
+-- WHY sha256 WITH NO EXTENSION. Postgres 16 (docs/architecture.md) carries
+-- `sha256(bytea)` as a built-in, so the backfill needs no pgcrypto — one less
+-- extension to have installed on a box before a migration will run. It is the
+-- same digest `db-kernel.js` computes in Node, so a row backfilled here and a row
+-- minted by the code resolve identically.
+--
+-- WHY A FAST HASH IS THE RIGHT ONE. A session token is 256 bits of CSPRNG, not a
+-- password: there is no dictionary to run and nothing to slow an attacker down,
+-- so bcrypt/argon would buy nothing and cost a KDF on every authenticated
+-- request. The same reasoning is written out at
+-- `modules/platform-identity/platform-identity.js` (`sha256hex`), which hashes
+-- its client secrets and authorization codes for exactly this reason.
+--
+-- WHY THE PLAINTEXT COLUMN IS DROPPED, NOT NULLED. Nulling it would leave a dead
+-- column that still has to be kept empty by every future writer, and it buys no
+-- rollback safety: rolling back to code that reads `token` finds it NULL and
+-- signs everyone out either way. Dropping it is the honest end state, and the
+-- unique index moves to `token_hash` so the uniqueness guarantee is unbroken.
+--
+-- WHAT THIS DOES NOT CHANGE. Expiry is untouched. ADR 0294 (CLI sessions do not
+-- expire) and ADR 0206 (no absolute ceiling) both stand exactly as written; this
+-- migration does not read, write or reason about `expires_at`. The audit also
+-- asked for refresh-on-use to stop and an absolute lifetime to be added — both are
+-- decisions those two ADRs have already taken the other way, with the owner as
+-- decider, AFTER this audit was filed. Changing them is not this task's to do.
+--
+-- IDEMPOTENT. The whole body is guarded on the plaintext column still existing,
+-- so a second run is a no-op rather than an error about a column that is gone.
+
+BEGIN;
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_name = 'builder_sessions' AND column_name = 'token'
+  ) THEN
+
+    ALTER TABLE builder_sessions ADD COLUMN IF NOT EXISTS token_hash text;
+
+    -- Every live row keeps working: the hash is derived from the bearer already
+    -- stored, so no holder is signed out by this deploy.
+    UPDATE builder_sessions
+       SET token_hash = encode(sha256(token::bytea), 'hex')
+     WHERE token_hash IS NULL;
+
+    -- The invariant the lookup depends on. Enforced only after the backfill has
+    -- given every existing row a value.
+    ALTER TABLE builder_sessions ALTER COLUMN token_hash SET NOT NULL;
+
+    -- Carries over `token`'s UNIQUE: two sessions may not share a bearer, and the
+    -- hash is what the lookup now keys on, so it needs the same index the
+    -- plaintext had for the same reason.
+    CREATE UNIQUE INDEX IF NOT EXISTS ux_builder_sessions_token_hash
+      ON builder_sessions (token_hash);
+
+    DROP INDEX IF EXISTS idx_builder_sessions_token;
+    ALTER TABLE builder_sessions DROP COLUMN token;
+
+  END IF;
+END
+$$;
+
+COMMENT ON COLUMN builder_sessions.token_hash IS
+  'SHA-256 hex of the bearer token. The plaintext is NEVER stored (core_249, audit A1): it exists only in the response that mints it and in the client that holds it. lookupSession hashes the presented bearer and keys on this column, so a read of this table yields nothing replayable.';
+
+COMMIT;

package/modules/agents/lib/validate.js

@@ -48,8 +48,31 @@
 const EVENT_CATALOG = Object.freeze(['task.shipped', 'idea.graded.full']);
 
 // Mirrors agents_definitions_trigger_type_chk. 'event' consumes the catalog above;
-// 'on-demand' is the historian shape (a builder asks, the agent answers).
-const TRIGGER_TYPES = Object.freeze(['event', 'on-demand']);
+// 'on-demand' is the historian shape (a builder asks, the agent answers); 'cron'
+// fires on a cadence and consumes CADENCES below (task 1004008, agents_005).
+const TRIGGER_TYPES = Object.freeze(['event', 'on-demand', 'cron']);
+
+// The cadence vocabulary a 'cron' trigger may declare, in trigger_spec.cadence.
+//
+// DUPLICATED FROM scripts/gds/routine-schedule.js ON PURPOSE, for the reason
+// RANK_ORDER below is duplicated: a module may require only src/module-api.js
+// (ADR 0083), so it cannot reach into scripts/. The two copies are kept honest by
+// tests/agents_cron_trigger.mjs, which reads routine-schedule.js's own CADENCES +
+// isUniformDivisor and asserts this file agrees — a drifting copy fails there
+// rather than at some future tick.
+//
+// N MUST DIVIDE 60 for the sub-hourly form. A cron step restarts each hour, so
+// only a divisor yields a uniform period: `*/15` fires :00 :15 :30 :45 always,
+// but `*/7` fires :00…:56 then waits 4 — a "7min" cadence that is not one.
+const CADENCES = Object.freeze(['hourly', 'daily', 'weekly', 'monthly']);
+const SUBHOURLY_RE = /^([1-9]\d*)min$/;
+function isCadence(name) {
+  if (CADENCES.includes(name)) return true;
+  const m = SUBHOURLY_RE.exec(String(name == null ? '' : name));
+  if (!m) return false;
+  const n = Number(m[1]);
+  return Number.isInteger(n) && n > 0 && n < 60 && 60 % n === 0;
+}
 
 // Mirrors agents_definitions_model_tier_chk. No 'main' tier by design — an agent
 // is a subagent, never the main session.
@@ -222,6 +245,29 @@ function validateAgentDefinition(obj, opts = {}) {
     }
   }
 
+  // --- the cadence, fail-closed, the same shape as the event catalog above ----
+  // agents_005's CHECK pins that a cron definition HAS a non-empty cadence; the
+  // vocabulary is pinned here, because the sub-hourly rule is a predicate and a
+  // CHECK spelling it out would be a second copy free to drift.
+  //
+  // The reach is deliberately the EVENT BLOCK'S reach, no more: an UNWIRED
+  // cadence is refused wherever it appears, including on a non-cron definition
+  // where it is dead config. A VALID cadence on a non-cron definition is ACCEPTED,
+  // exactly as a wired `event:` on an on-demand definition is — harmless, unread,
+  // and not this validator's call to police. Saying otherwise in a comment would
+  // describe a guard that is not here.
+  if (spec) {
+    const cadence = safeGet(spec, 'cadence');
+    const hasCadenceKey = cadence !== undefined && cadence !== null;
+    if (triggerType === 'cron' && !isNonEmptyString(cadence)) {
+      E('trigger_cadence_missing', 'trigger_spec.cadence',
+        `trigger_spec.cadence: required for a 'cron' trigger — a definition with no cadence can never fire. Named cadences: ${CADENCES.join(', ')}; or a sub-hourly '<N>min' where N divides 60.`);
+    } else if (hasCadenceKey && !isCadence(cadence)) {
+      E('trigger_cadence_unwired', 'trigger_spec.cadence',
+        `trigger_spec.cadence: ${JSON.stringify(cadence)} is not a cadence. Named cadences: ${CADENCES.join(', ')}; or a sub-hourly '<N>min' where N divides 60 (so the declared period and the realized one are the same claim).`);
+    }
+  }
+
   // --- model tier -----------------------------------------------------------
   const rawTier = safeGet(obj, 'model_tier');
   const modelTier = rawTier === undefined || rawTier === null ? 'default' : rawTier;
@@ -355,6 +401,7 @@ function validateAgentDefinition(obj, opts = {}) {
 module.exports = {
   validateAgentDefinition,
   EVENT_CATALOG,
+  CADENCES, isCadence,
   TRIGGER_TYPES,
   MODEL_TIERS,
   RANK_ORDER,

package/modules/agents/migrations/agents_005_cron_trigger.sql

@@ -0,0 +1,78 @@
+-- agents_005_cron_trigger.sql — make 'cron' a trigger type that can exist (task 1004008).
+--
+-- Tasks 1002498 (the cron-router poller) and 1002501 (the cron roster) both ask
+-- for a timer whose each tick SELECTS DUE CRON AGENTS. There are none and there
+-- can be none: agents_001 pinned trigger_type to ('event','on-demand') on BOTH
+-- agents_definitions and agents_runs, and lib/validate.js mirrors it. Build the
+-- poller against that and you get a timer that is correct, tested, and selects
+-- from an empty set by construction — green tests over an unreachable branch,
+-- which is a false claim of coverage rather than coverage. This migration is the
+-- enabling half; the poller is 1002498's and is deliberately NOT built here.
+--
+-- WIDENING A FAIL-CLOSED ENUM IS THE POINT, NOT A WORKAROUND. agents_001's header
+-- calls these enums fail-closed on purpose: "an unwired trigger name is refused,
+-- never silently stored". That rule is kept — 'cron' stops being unwired in the
+-- same change that makes it storable, because lib/validate.js is widened and
+-- constrained alongside. What is still true after this: a trigger name outside
+-- the three is refused at both the validator and the constraint.
+--
+-- BOTH TABLES, AND WHY THE LEDGER MATTERS AS MUCH AS THE DEFINITION. agents_001
+-- constrains trigger_type on agents_runs too. Widen only the definition and a
+-- cron agent could be stored and enabled, and then fail at the moment it fires,
+-- when the ledger insert violates its own CHECK — the worst shape available: a
+-- definition that looks armed and cannot record a single run.
+--
+-- A CRON DEFINITION MUST SAY WHEN. agents_001 already refuses an event definition
+-- with no event name ("a definition that can never fire"). A cron definition with
+-- no cadence is the same defect wearing a different key, so it gets the same
+-- treatment rather than being left for the poller to interpret at tick time.
+-- The cadence VOCABULARY is validated in lib/validate.js, not here: the named set
+-- ('hourly','daily','weekly','monthly') plus the open-ended sub-hourly form
+-- ('15min') is a predicate, and a CHECK that tried to spell the sub-hourly rule —
+-- N must divide 60 — would be a second, drifting copy of it. The constraint
+-- pins the SHAPE (a non-empty cadence key is present); the validator pins the
+-- VALUE. That is the same division agents_001 draws for `event`.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every
+-- object is agents_-prefixed, there is no down-migration, and the filename is
+-- agents_-prefixed (ADR 0108 §5). Idempotent: safe to re-run. No existing row
+-- changes — widening a CHECK can only make rows MORE legal, so nothing that
+-- validates today stops validating.
+
+BEGIN;
+
+DO $$
+BEGIN
+  -- agents_definitions: the three WIRED trigger types.
+  IF EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_definitions_trigger_type_chk') THEN
+    ALTER TABLE agents_definitions DROP CONSTRAINT agents_definitions_trigger_type_chk;
+  END IF;
+  ALTER TABLE agents_definitions ADD CONSTRAINT agents_definitions_trigger_type_chk
+    CHECK (trigger_type IN ('event', 'on-demand', 'cron'));
+
+  -- agents_runs: the same three, so a cron fire can be RECORDED and not only run.
+  IF EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_runs_trigger_type_chk') THEN
+    ALTER TABLE agents_runs DROP CONSTRAINT agents_runs_trigger_type_chk;
+  END IF;
+  ALTER TABLE agents_runs ADD CONSTRAINT agents_runs_trigger_type_chk
+    CHECK (trigger_type IN ('event', 'on-demand', 'cron'));
+
+  -- The twin of agents_definitions_trigger_spec_event_chk: a cron definition
+  -- carries a non-empty cadence, or it is a definition that can never fire.
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_definitions_trigger_spec_cadence_chk') THEN
+    ALTER TABLE agents_definitions ADD CONSTRAINT agents_definitions_trigger_spec_cadence_chk
+      CHECK (trigger_type <> 'cron'
+             OR (trigger_spec ? 'cadence' AND length(trigger_spec ->> 'cadence') > 0));
+  END IF;
+END $$;
+
+-- agents_001 indexes (trigger_type, trigger_spec->>'event') for the event
+-- router's "who wants this event" read. The cron router's read is a different
+-- question — "which cron agents are due" — and it is answered by scanning the
+-- cron rows, which are few. Adding a cadence index now would be indexing for a
+-- query no committed code makes; 1002498 adds one if its poller needs it.
+
+COMMENT ON CONSTRAINT agents_definitions_trigger_type_chk ON agents_definitions IS
+  'The WIRED trigger vocabulary (task 1004008 added cron). Mirrored by TRIGGER_TYPES in modules/agents/lib/validate.js — widen both together or the two disagree about what can exist.';
+
+COMMIT;

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.887",
+  "version": "1.19.889",
   "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",