@bongos/core 1.19.702 → 1.19.703

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.702",
-  "core_contract": "1.19.702",
-  "source_commit": "3b1a2e8029758a6ee091812baccb9e24fdc4670a",
+  "core_version": "1.19.703",
+  "core_contract": "1.19.703",
+  "source_commit": "f85beb07ce74ab0f248774c68e6d16453aa964c1",
   "source_ref": "HEAD",
-  "built_at": "2026-09-13T03:33:51.903Z",
+  "built_at": "2026-09-13T03:53:32.093Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 477,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2130,
+    "functional_verbatim": 2132,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2631,
-  "tree_sha256": "7bf1dff3812c90015cc9d2476643856d5c6e9e950d26c6859e219c0eab9796b5",
+  "file_count": 2633,
+  "tree_sha256": "4890a8f49b9e7da75dd0e91d122be5cc3c64802bca863b7eae48b237cab5e9b3",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "7458093aecd8dd3fcc7753356a12e995b25663e9251a295c406e4ecc4cc54c27"
+      "sha256": "f777f91ad88b47ff271da5bbc1670507ed77fa105df07e3d15dca6912617baef"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7782,12 +7782,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "1aa096840e001b544038432419a0e07577014954f7cb83d8e19c716704e3f36c"
+      "sha256": "d63e44b7d4f919455708ad0fd9041ef90552639733c506b1fdc06fe2e2ccd12b"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "cee79b868fecce6053d7d04108233e795a92c3635854bea1bf3003b909953e20"
+      "sha256": "ff9eefa1e4c9f66ddd29b8a077ef567602ca79e69ab569b13f72e9221289b2ed"
     },
     {
       "path": "public-docs/index.html",
@@ -7859,6 +7859,11 @@
       "mode": "0000644",
       "sha256": "9c7ef61b64e41ee5dd6d913883e16dfed6d44bd6eefa4960b8dde566a63b5621"
     },
+    {
+      "path": "scripts/gds/agents-sync.js",
+      "mode": "0000644",
+      "sha256": "2e1a55ae7187a8ee970873a108a7989fed121f1ac1f92361d7b9bc61987056a2"
+    },
     {
       "path": "scripts/gds/api.js",
       "mode": "0000644",
@@ -9177,7 +9182,7 @@
     {
       "path": "scripts/migrate.sh",
       "mode": "0000644",
-      "sha256": "0768bf9c9d6368ae673e1e5ac161cfe9bae4d113129f11f8b89afeeef1f9dc1b"
+      "sha256": "669ba0cd4e0c5ad2c7809364e4ac17b24bfa3f8542fae5ba7ec05e9bcf77053f"
     },
     {
       "path": "scripts/migrate_cost_ledger.sh",
@@ -9552,7 +9557,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "be1bd4054da76be7eb7aa62d3e9ee2805de116d811e25043a49bbd4731ad1643"
+      "sha256": "6cb88cea4e61987151e1872011b8667189ef59d03f3999be5950ba716ad9b05e"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9664,6 +9669,11 @@
       "mode": "0000644",
       "sha256": "8cc261471a36e3c447df57b46082997b6a50da3c8ff4b214787ae55ab27cb9ef"
     },
+    {
+      "path": "tests/agents_sync.mjs",
+      "mode": "0000644",
+      "sha256": "96197b8e25d9a8620cd3e02b7c96137d7118543662555c73d74e22a6b6161953"
+    },
     {
       "path": "tests/agents_validate.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1863,5 +1863,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.700 with no explicit bump. run 34735311256. (task 1002620)
   1.19.702 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.701 with no explicit bump. run 34735775228. (task 1002620)
+  1.19.703 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.702 with no explicit bump. run 34736566183. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.702",
+  "version": "1.19.703",
   "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/agents-sync.js

@@ -0,0 +1,448 @@
+#!/usr/bin/env node
+// scripts/gds/agents-sync.js — reconcile .claude/agents/*.md into
+// agents_definitions at deploy (task 1002490, goal 1000038 Phase 1, T6).
+//
+// WHY. The registry is what the spawn path fires from, so it — not the tree — is
+// the operative list. Files-are-source means a committed definition must reach
+// that table on deploy without anyone running anything by hand, and without a
+// deploy ever silently undoing an operator's decision.
+//
+// FOUR RULES, each of which is a way this could go wrong:
+//
+//  1. A `source=db` row is NEVER touched. An instance-authored agent is not in
+//     any file, so a file-driven reconcile that "cleaned up" rows with no
+//     matching file would delete exactly the agents nobody can restore from git.
+//     This script only ever writes rows it owns.
+//
+//  2. `author_rank` is NEVER read from the file, and never taken from git where
+//     it could grant anything. A committed file cannot carry authority (ADR
+//     0016) — writing `author_rank: archon` into frontmatter must buy nothing.
+//     The obvious implementation, "resolve the committer and stamp their live
+//     rank", has the same hole one level down: `git log --format=%ae` reports
+//     the commit AUTHOR, which the committer sets freely with `git config` or
+//     `--author`, so it is attacker-controlled too. Rather than pretend that
+//     value can be trusted, it is denied any power — see stampableAuthorRank:
+//     a definition reaching a PROTECTED module is stamped NULL regardless of
+//     git, which the wall treats as insufficient, so it imports disabled and
+//     arming it becomes an operator act with a real session behind it.
+//
+//  3. The scope wall is RE-RUN here, server-side. The same check runs when a
+//     definition is authored, but that check ran against the author's rank at
+//     authoring time on a machine outside the trust boundary. A definition
+//     scoped onto protected surfaces imports DISABLED and FLAGGED — present in
+//     the registry so it can be seen and fixed, never armed.
+//
+//  4. The sync NEVER ARMS ANYTHING. `enabled` is an operator decision, not a
+//     file one — by exactly the reasoning in rule 2. A new row inserts disabled;
+//     an existing row keeps whatever `enabled` an operator set, unless it is
+//     flagged, in which case it is forced off. So `git push` can add an agent to
+//     the registry and can never switch one on.
+//
+// FAIL-CLOSED IN THE DIRECTION THAT MATTERS. An unresolvable author yields a
+// NULL rank, which the validator treats as insufficient for any protected scope,
+// and which the schema's agents_definitions_armed_needs_author_chk independently
+// refuses to arm. Three layers have to agree before an agent fires; this script
+// is only one of them.
+//
+// Run:  node scripts/gds/agents-sync.js [--dry-run] [--json] [--dir <path>]
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const DEFAULT_DIR = path.join(REPO_ROOT, '.claude', 'agents');
+
+// The module owns the definition grammar; this script is its deploy-time
+// carrier. Requiring the module's own pure validator from the module's own
+// script is the same shape as context-pack.js reading task-classifier.
+const validate = require(path.join(REPO_ROOT, 'modules/agents/lib/validate.js'));
+
+// Validator error codes that mean "the SCOPE is refused", as opposed to "this is
+// not a definition". The distinction is the whole of rule 3: a scope refusal is
+// imported as a flagged row so somebody can SEE it, while a shape error has no
+// row to import — there is no definition there to put in the registry.
+const SCOPE_CODES = Object.freeze(['scope_protected_rank', 'scope_out_of_bounds']);
+
+// Does this definition reach a PROTECTED module? If so, the git-derived author
+// identity is not consulted at all (see below) — which is what makes rule 2 hold
+// against a value the author controls.
+function declaresProtectedScope(candidate, protectedModules = []) {
+  const declared = Array.isArray(candidate?.scope_modules) ? candidate.scope_modules : [];
+  return declared.some((m) => protectedModules.includes(m));
+}
+
+// THE RANK THAT ACTUALLY GETS STAMPED, and the answer to the spoofable-identity
+// problem in lastCommitterLogin above.
+//
+// The naive design — resolve the committer, read their live rank, stamp it — is
+// an escalation path: the committer email is attacker-controlled, so anyone who
+// can land a commit can claim to be an Archon and arm an agent scoped onto the
+// authority surface. Verifying the identity properly would mean a trustworthy
+// server-side record of who authored each file, which this script does not have.
+//
+// So instead of trying to make the input trustworthy, the input is denied any
+// power: WHERE THE RANK COULD GRANT SOMETHING, IT IS NOT TAKEN FROM GIT.
+//
+//   - definition reaches a protected module → rank is NULL, full stop. The wall
+//     then flags it (an unresolved rank is insufficient, never exempt) and it
+//     imports disabled. Arming it is an operator act with a real session behind
+//     it, which is where the authority decision belongs.
+//   - definition reaches nothing protected → the rank gates nothing, so the
+//     hint is recorded as the provenance it is.
+//
+// The result is that spoofing the git identity buys exactly nothing: on the only
+// path where rank matters, no git-derived value is read.
+function stampableAuthorRank(candidate, { gitRank = null, protectedModules = [] } = {}) {
+  if (declaresProtectedScope(candidate, protectedModules)) return null;
+  return gitRank;
+}
+
+// ---- pure core -------------------------------------------------------------
+
+// Split `---\n<yaml>\n---\n<body>` into frontmatter text and body.
+// Deliberately NOT a YAML parser: the definition grammar is a flat map of
+// scalars and simple lists, and pulling a YAML dependency into a deploy script
+// to read four keys would be a supply-chain decision, not a convenience. The
+// validator is the thing that decides whether the result is a definition — this
+// only has to hand it a plain object faithfully.
+function splitFrontmatter(text) {
+  const s = String(text || '');
+  // Tolerates a BOM and CRLF, both of which a Windows-authored file will carry.
+  //
+  // The BOM is stripped BY CODE POINT rather than matched inside the regex. Two
+  // earlier spellings both failed review for the same reason: a literal U+FEFF
+  // in the pattern is invisible, so `/^<BOM>?---/` reads as `/^?---/` — an
+  // apparent no-op quantifier on a zero-width assertion — and an escape can be
+  // re-interpreted back into that literal by tooling on the way to disk. This
+  // form is unambiguous ASCII, and the file now contains no invisible
+  // characters at all. Behaviour that is correct but unreadable is still a
+  // defect; it cost two review rounds here.
+  const withoutBom = s.charCodeAt(0) === 0xFEFF ? s.slice(1) : s;
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(withoutBom);
+  if (!m) return { frontmatter: null, body: s };
+  return { frontmatter: m[1], body: m[2] };
+}
+
+// `key: value` / `key: [a, b]` / `key:\n  - a\n  - b`. Unknown keys are kept —
+// the validator refuses what it does not recognise, and silently dropping a key
+// here would turn a typo into a default instead of an error.
+function parseFrontmatter(fmText) {
+  const out = {};
+  if (typeof fmText !== 'string') return out;
+  const lines = fmText.split(/\r?\n/);
+  let listKey = null;
+  for (const raw of lines) {
+    if (!raw.trim() || /^\s*#/.test(raw)) continue;
+    const item = /^\s*-\s+(.*)$/.exec(raw);
+    if (item && listKey) { out[listKey].push(scalar(item[1])); continue; }
+    const kv = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$/.exec(raw);
+    if (!kv) { listKey = null; continue; }
+    const [, key, rest] = kv;
+    if (rest === '') { listKey = key; out[key] = []; continue; }
+    listKey = null;
+    const inline = /^\[(.*)\]$/.exec(rest.trim());
+    out[key] = inline
+      ? inline[1].split(',').map((p) => scalar(p)).filter((p) => p !== '')
+      : scalar(rest);
+  }
+  return out;
+}
+
+function scalar(raw) {
+  let v = String(raw).trim();
+  // Strip a trailing comment only when the value is not quoted — a persona-ish
+  // string legitimately contains '#'.
+  const quoted = /^(['"])([\s\S]*)\1$/.exec(v);
+  if (quoted) return quoted[2];
+  v = v.replace(/\s+#.*$/, '').trim();
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  return v;
+}
+
+// One file → the candidate object the validator takes. The BODY is the persona:
+// a persona is prose, and prose does not belong in frontmatter.
+function parseAgentFile(text, { name } = {}) {
+  const { frontmatter, body } = splitFrontmatter(text);
+  const fm = parseFrontmatter(frontmatter);
+  const candidate = { ...fm };
+  // The filename is the identity when frontmatter does not override it, so
+  // historian.md is the `historian` agent without having to say so twice.
+  if (!candidate.name && name) candidate.name = name;
+  const persona = String(body || '').trim();
+  if (persona) candidate.persona = persona;
+  // `trigger: event` + `event: task.shipped` is the readable file spelling of
+  // the column pair the schema stores. Mapped here rather than in the validator
+  // so the validator keeps taking exactly the row shape the DB holds.
+  if (candidate.trigger && !candidate.trigger_type) {
+    candidate.trigger_type = candidate.trigger;
+    delete candidate.trigger;
+  }
+  if (candidate.event && !candidate.trigger_spec) {
+    candidate.trigger_spec = { event: candidate.event };
+    delete candidate.event;
+  }
+  return candidate;
+}
+
+/**
+ * Decide what to do with ONE parsed candidate. Pure: no disk, no database, no
+ * git. Returns a plan the caller applies (or prints, under --dry-run).
+ *
+ * Outcomes:
+ *   skip    — not a definition. No row; the reason is reported.
+ *   flagged — a real definition whose SCOPE is refused. Imported disabled, with
+ *             scope_violation set, so it is visible and fixable.
+ *   upsert  — clean. Imported; `enabled` is left to the operator (rule 4).
+ *   protected — a `source=db` row owns this name. Never touched (rule 1).
+ */
+function planOne(candidate, {
+  authorRank: gitRank = null,
+  allowedModules = [],
+  protectedModules = [],
+  existing = null,
+} = {}) {
+  const name = typeof candidate?.name === 'string' ? candidate.name : null;
+  // The caller passes the GIT-DERIVED rank; what gets stamped is whatever
+  // survives stampableAuthorRank, which withholds it entirely on any definition
+  // that reaches a protected module. Everything below uses `authorRank`, so the
+  // spoofable value cannot reach the wall by a path that forgets to launder it.
+  const authorRank = stampableAuthorRank(candidate, { gitRank, protectedModules });
+
+  // Rule 1, checked before anything else: an instance-authored row owns its
+  // name. A file that happens to share it does not get to overwrite it, and
+  // this is reported rather than silent so the collision is visible.
+  if (existing && existing.source === 'db') {
+    return { action: 'protected', name, reason: 'an instance-authored (source=db) row owns this name — the file is ignored' };
+  }
+
+  const verdict = validate.validateAgentDefinition(candidate, {
+    authorRank, allowedModules, protectedModules,
+  });
+
+  if (verdict.ok) {
+    return {
+      action: 'upsert',
+      name,
+      value: verdict.value,
+      authorRank,
+      scopeViolation: null,
+      // Rule 4: never arm. Absent an existing row this is a fresh insert, which
+      // the schema defaults to disabled; on update we carry the operator's own
+      // setting forward untouched.
+      enabled: existing ? existing.enabled === true : false,
+    };
+  }
+
+  const codes = verdict.errors.map((e) => e.code);
+  const scopeOnly = codes.length > 0 && codes.every((c) => SCOPE_CODES.includes(c));
+  if (!scopeOnly) {
+    return { action: 'skip', name, reason: verdict.errors.map((e) => e.message).join(' · ') };
+  }
+
+  // Rule 3. The definition is well-formed; only its scope is refused. To import
+  // it we need the NORMALIZED row, which the validator only returns on success —
+  // so it is re-run with the scope checks satisfied purely to obtain that shape.
+  //
+  // This cannot widen anything: the re-run's verdict is discarded except for
+  // `value`, the row is forced enabled:false with scope_violation set, and the
+  // schema's agents_definitions_flagged_not_armed_chk refuses to store a flagged
+  // row as armed even if this code were wrong.
+  const declaredModules = Array.isArray(candidate.scope_modules) ? candidate.scope_modules : [];
+  const shapeOnly = validate.validateAgentDefinition(candidate, {
+    authorRank: validate.RANK_ORDER[validate.RANK_ORDER.length - 1],
+    allowedModules: [...new Set([...allowedModules, ...declaredModules])],
+    protectedModules: [],
+  });
+  if (!shapeOnly.ok) {
+    // Defensive: the two runs disagreeing means an error that is scope-coded but
+    // not scope-caused. Skipping is the fail-closed answer.
+    return { action: 'skip', name, reason: verdict.errors.map((e) => e.message).join(' · ') };
+  }
+  return {
+    action: 'flagged',
+    name,
+    value: shapeOnly.value,
+    authorRank,
+    scopeViolation: verdict.errors.map((e) => e.message).join(' · '),
+    enabled: false,
+  };
+}
+
+// The whole plan, for a list of { name, candidate } and a lookup of existing
+// rows by name. Pure, so the reconcile's DECISIONS are unit-testable with no
+// database standing up.
+function planSync(files, { existingByName = new Map(), authorRankFor = () => null, allowedModules = [], protectedModules = [] } = {}) {
+  return files.map((f) => ({
+    file: f.file || null,
+    ...planOne(f.candidate, {
+      authorRank: authorRankFor(f.file),
+      allowedModules,
+      protectedModules,
+      existing: existingByName.get(f.candidate?.name) || null,
+    }),
+  }));
+}
+
+// ---- disk + git ------------------------------------------------------------
+
+// An ABSENT directory is a legitimate state, not an error: `.claude/agents/`
+// does not exist in the core tree at all today, and an instance that ships no
+// agents must deploy cleanly. Zero files, exit 0, nothing written.
+function readAgentFiles(dir = DEFAULT_DIR) {
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return names.sort().map((f) => {
+    const full = path.join(dir, f);
+    return {
+      file: path.relative(REPO_ROOT, full).split(path.sep).join('/'),
+      candidate: parseAgentFile(fs.readFileSync(full, 'utf8'), { name: f.replace(/\.md$/, '') }),
+    };
+  });
+}
+
+// The login that last committed a file — a PROVENANCE HINT, and explicitly NOT
+// an authority input. Read `declaresProtectedScope` below before using it.
+//
+// An earlier version of this comment claimed the GitHub noreply address "cannot
+// be spoofed by setting a local git name". THAT WAS WRONG, and it was the more
+// dangerous half of the mistake: `git log --format=%ae` reports the commit
+// AUTHOR, which any committer sets freely with `git config user.email` or
+// `--author`, noreply-shaped values included. Nothing here verifies the address
+// against GitHub. So this value is attacker-controlled, and a comment asserting
+// otherwise invites the next reviewer to skip the one check that matters.
+//
+// It is kept because provenance is genuinely useful where nothing is riding on
+// it. The wall is that it is never consulted where it could grant anything.
+function lastCommitterLogin(file, { runGit = defaultRunGit } = {}) {
+  let out;
+  try { out = runGit(['log', '-1', '--format=%ae%n%an', '--', file]); }
+  catch { return null; }
+  const [email = '', authorName = ''] = String(out || '').split(/\r?\n/);
+  const noreply = /^(?:\d+\+)?([A-Za-z0-9-]+)@users\.noreply\.github\.com$/.exec(email.trim());
+  if (noreply) return noreply[1];
+  return authorName.trim() || null;
+}
+
+function defaultRunGit(args) {
+  return execFileSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });
+}
+
+module.exports = {
+  splitFrontmatter,
+  parseFrontmatter,
+  parseAgentFile,
+  declaresProtectedScope,
+  stampableAuthorRank,
+  planOne,
+  planSync,
+  readAgentFiles,
+  lastCommitterLogin,
+  SCOPE_CODES,
+  DEFAULT_DIR,
+};
+
+// ---- facade ----------------------------------------------------------------
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const dryRun = argv.includes('--dry-run');
+  const asJson = argv.includes('--json');
+  const dirIdx = argv.indexOf('--dir');
+  const dir = dirIdx >= 0 ? argv[dirIdx + 1] : DEFAULT_DIR;
+
+  const files = readAgentFiles(dir);
+  if (files.length === 0) {
+    if (asJson) console.log(JSON.stringify({ ok: true, scanned: 0, plan: [] }));
+    else console.log(`agents-sync: no definitions under ${path.relative(REPO_ROOT, dir) || dir} — nothing to reconcile.`);
+    return 0;
+  }
+
+  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
+  const scopeMap = require(path.join(REPO_ROOT, 'src/bongos/module-scope-map.js'));
+  const allowedModules = scopeMap.moduleKeys();
+  const protectedModules = scopeMap.protectedModules();
+
+  const { rows: existingRows } = await pool.query(
+    'SELECT name, source, enabled FROM agents_definitions'
+  );
+  const existingByName = new Map(existingRows.map((r) => [r.name, r]));
+
+  // ONE git subprocess per file, memoised — `authorRankFor` is called again from
+  // planSync, and re-shelling out there doubled the blocking spawns for an answer
+  // that cannot have changed mid-run.
+  const loginByFile = new Map(files.map((f) => [f.file, lastCommitterLogin(f.file)]));
+  // One query for every distinct committer, not one per file.
+  const logins = [...new Set([...loginByFile.values()].filter(Boolean))];
+  const rankByLogin = new Map();
+  if (logins.length) {
+    const { rows } = await pool.query(
+      'SELECT github_login, rank FROM builders WHERE lower(github_login) = ANY($1)',
+      [logins.map((l) => l.toLowerCase())]
+    );
+    for (const r of rows) rankByLogin.set(String(r.github_login).toLowerCase(), r.rank);
+  }
+  // The git-derived rank. planOne withholds it on any protected-scope definition
+  // (stampableAuthorRank) — this function never decides whether it may be used.
+  const authorRankFor = (file) => {
+    const login = loginByFile.get(file);
+    return login ? (rankByLogin.get(login.toLowerCase()) || null) : null;
+  };
+
+  const plan = planSync(files, { existingByName, authorRankFor, allowedModules, protectedModules });
+
+  if (dryRun) {
+    if (asJson) console.log(JSON.stringify({ ok: true, scanned: files.length, plan }, null, 2));
+    else for (const p of plan) console.log(`  ${p.action.padEnd(9)} ${p.name || p.file}${p.reason ? ` — ${p.reason}` : ''}`);
+    return 0;
+  }
+
+  let upserted = 0;
+  let flagged = 0;
+  for (const p of plan) {
+    if (p.action === 'skip' || p.action === 'protected') {
+      console.error(`agents-sync: ${p.action} ${p.name || p.file} — ${p.reason}`);
+      continue;
+    }
+    const v = p.value;
+    // ON CONFLICT targets the name unique constraint, and the WHERE clause is
+    // rule 1 made structural: a row that turned source=db between the read above
+    // and this write is not overwritten by the race either.
+    await pool.query(
+      `INSERT INTO agents_definitions
+         (name, title, persona, trigger_type, trigger_spec, model_tier,
+          scope_modules, scope_paths, scope_violation, source, provenance,
+          author_rank, source_path, last_synced_at, enabled)
+       VALUES ($1,$2,$3,$4,$5::jsonb,$6,$7,$8,$9,'file','built-in',$10,$11,now(),$12)
+       ON CONFLICT (name) DO UPDATE SET
+         title = EXCLUDED.title, persona = EXCLUDED.persona,
+         trigger_type = EXCLUDED.trigger_type, trigger_spec = EXCLUDED.trigger_spec,
+         model_tier = EXCLUDED.model_tier, scope_modules = EXCLUDED.scope_modules,
+         scope_paths = EXCLUDED.scope_paths, scope_violation = EXCLUDED.scope_violation,
+         author_rank = EXCLUDED.author_rank, source_path = EXCLUDED.source_path,
+         last_synced_at = now(), enabled = EXCLUDED.enabled, updated_at = now()
+       WHERE agents_definitions.source = 'file'`,
+      [v.name, v.title, v.persona, v.trigger_type, JSON.stringify(v.trigger_spec), v.model_tier,
+        v.scope_modules, v.scope_paths, p.scopeViolation, p.authorRank, p.file || null, p.enabled]
+    );
+    if (p.action === 'flagged') flagged += 1; else upserted += 1;
+  }
+  console.log(`agents-sync: ${files.length} file(s) — ${upserted} reconciled, ${flagged} flagged (disabled), `
+    + `${plan.filter((p) => p.action === 'skip').length} skipped, ${plan.filter((p) => p.action === 'protected').length} db-owned.`);
+  return 0;
+}
+
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }).catch((err) => {
+    console.error(`agents-sync: ${err && err.message ? err.message : err}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/migrate.sh

@@ -358,3 +358,26 @@ if [ "${OTB_POST_DEPLOY_CHECK:-0}" = "1" ]; then
     echo "post-deploy: python3 not found — skipping whole-world check" >&2
   fi
 fi
+
+# ---------- post-deploy: reconcile the agent registry (task 1002490) ----------
+#
+# .claude/agents/*.md -> agents_definitions. This runs HERE because migrate.sh is
+# the one deploy-time hook the portable core owns: the droplet's own deploy.sh
+# calls it, and the schema the reconcile writes into is applied a few lines
+# above, so the table is guaranteed to exist by the time this runs.
+#
+# FAIL-OPEN, deliberately. A reconcile that cannot run is a registry that is
+# stale by one deploy; a reconcile that aborts the deploy is an outage. The
+# script itself is already fail-closed in the direction that matters (an
+# unresolvable author, or any protected scope, imports disabled+flagged), so the
+# worst case here is an agent that does not appear until the next deploy.
+#
+# Silent when the module is off: `agents` is default:false, so on most instances
+# there is no table to reconcile into and nothing to say about it.
+if node -e "process.exit(require('./src/modules').isModuleEnabled('agents') ? 0 : 1)" 2>/dev/null; then
+  echo
+  echo "post-deploy: reconciling .claude/agents/ into the agent registry"
+  if ! node scripts/gds/agents-sync.js; then
+    echo "post-deploy: agents-sync failed — the registry is stale by one deploy, not broken" >&2
+  fi
+fi

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.702'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.703'; // 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/agents_sync.mjs

@@ -0,0 +1,338 @@
+// tests/agents_sync.mjs — the deploy-time file↔DB reconcile (task 1002490,
+// goal 1000038 Phase 1, T6).
+//
+// The four rules this script exists to keep, each tested as the FAILURE it
+// prevents rather than as the happy path:
+//
+//   1. a source=db row is never touched      → an instance-authored agent
+//                                              survives a deploy
+//   2. author_rank is never taken from git    → the committer email is
+//      where it could grant                     attacker-controlled, so it is
+//                                               withheld on any protected scope
+//                                               (ADR 0016)
+//   3. a refused SCOPE imports disabled+flagged → visible and fixable, never armed
+//   4. the sync never ARMS anything           → `git push` cannot switch an
+//                                              agent on
+//
+// Pure: no database, no git, no disk except one tmp dir for the absent/present
+// directory cases. The reconcile's DECISIONS are the thing under test.
+//
+// In tests/ rather than modules/agents/tests/ for the same reason as
+// tests/agents_routes.mjs: the module is default:false and module-local tests
+// are discovered only when the module is ENABLED, so they would never run here.
+//
+// Run:  node tests/agents_sync.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const sync = require('../scripts/gds/agents-sync.js');
+const validate = require('../modules/agents/lib/validate.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); console.log(`  PASS  ${name}`); passed += 1; }
+  catch (err) { console.log(`  FAIL  ${name}\n        ${err.message}`); failed += 1; }
+}
+
+const FILE = [
+  '---',
+  'name: historian',
+  'title: The Historian',
+  'trigger: on-demand',
+  'model_tier: routine',
+  'scope_modules: [agents]',
+  '---',
+  '',
+  'You are the historian. Answer with citations.',
+].join('\n');
+
+const def = () => sync.parseAgentFile(FILE, { name: 'historian' });
+
+console.log('\nparsing — the file is a definition, the body is the persona:');
+
+t('frontmatter + body split, with the body as persona', () => {
+  const d = def();
+  assert.equal(d.name, 'historian');
+  assert.equal(d.title, 'The Historian');
+  assert.equal(d.trigger_type, 'on-demand', 'the readable `trigger:` spelling maps to the column');
+  assert.equal(d.model_tier, 'routine');
+  assert.deepEqual(d.scope_modules, ['agents']);
+  assert.match(d.persona, /^You are the historian/);
+  assert.ok(!('trigger' in d), 'the file spelling is consumed, not left to confuse the validator');
+});
+
+t('the FILENAME is the identity when frontmatter omits a name', () => {
+  const d = sync.parseAgentFile('---\ntrigger: on-demand\n---\nbody', { name: 'planner' });
+  assert.equal(d.name, 'planner', 'planner.md is the planner agent without saying so twice');
+});
+
+t('CRLF and a REAL BOM parse — a Windows-authored file is still a definition', () => {
+  // The first draft of this test was named for the BOM and contained none —
+  // only CRLF — so it asserted nothing about the behaviour its name promised.
+  // The second carried a LITERAL U+FEFF, which is invisible and read in review
+  // as no BOM at all. Built from the CODE POINT: unambiguous ASCII in source,
+  // and the charCodeAt assertion below means the fixture cannot quietly lose it
+  // a third time.
+  const withBom = String.fromCharCode(0xFEFF) + '---\r\nname: x\r\ntrigger: on-demand\r\n---\r\nbody';
+  assert.equal(withBom.charCodeAt(0), 0xFEFF, 'the fixture really starts with a BOM');
+  const d = sync.parseAgentFile(withBom, {});
+  assert.equal(d.name, 'x');
+  assert.equal(d.trigger_type, 'on-demand');
+  assert.equal(d.persona, 'body');
+  // And the same file WITHOUT the BOM must still parse — the BOM is optional,
+  // not required, and a regex that demanded it would break every POSIX file.
+  const noBom = sync.parseAgentFile(withBom.slice(1), {});
+  assert.equal(noBom.name, 'x');
+});
+
+t('`event:` becomes the trigger_spec the schema stores', () => {
+  const d = sync.parseAgentFile('---\nname: lens\ntrigger: event\nevent: task.shipped\n---\nb', {});
+  assert.deepEqual(d.trigger_spec, { event: 'task.shipped' });
+  assert.ok(!('event' in d));
+});
+
+t('a file with NO frontmatter yields no definition, and does not throw', () => {
+  const d = sync.parseAgentFile('just prose, no fences', { name: 'loose' });
+  assert.equal(d.name, 'loose');
+  assert.equal(d.trigger_type, undefined, 'nothing is invented from a bare file');
+});
+
+t('an unknown key is KEPT, so a typo is refused rather than defaulted', () => {
+  const d = sync.parseAgentFile('---\nname: x\ntriger: event\n---\nb', {});
+  assert.equal(d.triger, 'event', 'silently dropping it would turn a typo into a default');
+});
+
+console.log('\nrule 1 — a source=db row is never touched:');
+
+t('an instance-authored row owns its name; the file is ignored', () => {
+  const p = sync.planOne(def(), {
+    authorRank: 'archon', allowedModules: ['agents'],
+    existing: { source: 'db', enabled: true },
+  });
+  assert.equal(p.action, 'protected');
+  assert.match(p.reason, /instance-authored/);
+  assert.equal(p.value, undefined, 'no row is produced, so nothing can be written');
+});
+
+t('a source=file row with the same name IS reconciled', () => {
+  const p = sync.planOne(def(), {
+    authorRank: 'archon', allowedModules: ['agents'],
+    existing: { source: 'file', enabled: false },
+  });
+  assert.equal(p.action, 'upsert');
+});
+
+console.log('\nrule 2 — authority comes from the live DB rank, never the file:');
+
+t('a file claiming author_rank cannot promote itself', () => {
+  // The frontmatter says archon; the caller passes the live rank, which is what
+  // the wall consults. If the file could win, writing one line would be a
+  // privilege escalation whose only gate is code review.
+  const claiming = sync.parseAgentFile(
+    '---\nname: x\ntrigger: on-demand\nauthor_rank: archon\nscope_modules: [government]\n---\nbody', {});
+  const p = sync.planOne(claiming, {
+    authorRank: 'xenos', allowedModules: ['government'], protectedModules: ['government'],
+  });
+  assert.equal(p.action, 'flagged', 'the declared rank did not open the protected scope');
+  // NULL, not 'xenos': this definition reaches a protected module, so no
+  // git-derived rank is stamped at all (stampableAuthorRank). The file's claim
+  // loses, and so does the spoofable git value — both by the same rule.
+  assert.equal(p.authorRank, null, 'nothing git-derived is stamped on a protected-scope row');
+  assert.match(p.scopeViolation, /metic\+ author/i);
+});
+
+t('THE ESCALATION PATH: a spoofed git identity cannot arm a protected scope', () => {
+  // git log --format=%ae reports the commit AUTHOR, which any committer sets
+  // with `git config user.email` or `--author` — noreply-shaped values included,
+  // and nothing verifies them against GitHub. So the resolved rank is
+  // attacker-controlled. The wall is that it is never consulted where it could
+  // grant: a definition reaching a protected module is stamped NULL whatever
+  // git said, which the validator treats as insufficient.
+  const d = def(); // scope_modules: [agents]
+  assert.equal(sync.declaresProtectedScope(d, ['agents']), true);
+  assert.equal(sync.stampableAuthorRank(d, { gitRank: 'archon', protectedModules: ['agents'] }), null,
+    'a claimed archon rank must not survive onto a protected-scope definition');
+  const p = sync.planOne(d, {
+    authorRank: 'archon', allowedModules: ['agents'], protectedModules: ['agents'],
+  });
+  assert.equal(p.action, 'flagged', 'so it flags, exactly as an unresolved author would');
+  assert.equal(p.authorRank, null, 'and nothing spoofable is stamped on the row');
+  assert.equal(p.enabled, false);
+});
+
+t('where rank grants nothing, the hint is kept as provenance', () => {
+  // The other side: withholding it everywhere would throw away useful
+  // provenance for no gain, since on an unprotected scope the rank gates nothing.
+  const d = def();
+  assert.equal(sync.stampableAuthorRank(d, { gitRank: 'metic', protectedModules: [] }), 'metic');
+  const p = sync.planOne(d, { authorRank: 'metic', allowedModules: ['agents'], protectedModules: [] });
+  assert.equal(p.action, 'upsert');
+  assert.equal(p.authorRank, 'metic');
+});
+
+t('an UNRESOLVED author is insufficient, not exempt', () => {
+  // A committer who maps to no builder row yields null. Fail-closed: null must
+  // behave like "too low", never like "skip the check".
+  const p = sync.planOne(def(), {
+    authorRank: null, allowedModules: ['agents'], protectedModules: ['agents'],
+  });
+  assert.equal(p.action, 'flagged');
+  assert.equal(p.authorRank, null);
+  assert.equal(p.enabled, false);
+});
+
+console.log('\nrule 3 — a refused scope is IMPORTED, disabled and flagged:');
+
+t('a protected scope below the floor imports flagged, never armed', () => {
+  const p = sync.planOne(def(), {
+    authorRank: 'thetes', allowedModules: ['agents'], protectedModules: ['agents'],
+  });
+  assert.equal(p.action, 'flagged');
+  assert.equal(p.enabled, false, 'the whole point — present, not armed');
+  assert.ok(p.scopeViolation && p.scopeViolation.length > 0, 'the reason is stored so it can be fixed');
+  assert.ok(p.value, 'a flagged row still carries the normalized definition');
+  assert.equal(p.value.name, 'historian');
+});
+
+t('a flagged row keeps its real scope, not a sanitised one', () => {
+  // The re-run that recovers the normalized shape must not be allowed to launder
+  // the scope — what is stored has to be what the file actually asked for, or
+  // the flag names a problem the row no longer shows.
+  const p = sync.planOne(def(), {
+    authorRank: 'thetes', allowedModules: ['agents'], protectedModules: ['agents'],
+  });
+  assert.deepEqual(p.value.scope_modules, ['agents']);
+});
+
+t('a SHAPE error is skipped — there is no definition to import', () => {
+  const p = sync.planOne({ name: 'x', trigger_type: 'telepathy' }, {
+    authorRank: 'archon', allowedModules: ['agents'],
+  });
+  assert.equal(p.action, 'skip');
+  assert.equal(p.value, undefined, 'a partial row must never reach the registry');
+  assert.match(p.reason, /trigger/i);
+});
+
+t('the two are not confused: every SCOPE_CODE is a real validator code', () => {
+  // If a code were renamed in the validator, scope refusals would start being
+  // reported as shape errors and silently stop being imported.
+  const p = validate.validateAgentDefinition(
+    { name: 'x', trigger_type: 'on-demand', persona: 'p', scope_modules: ['nope'] },
+    { authorRank: 'archon', allowedModules: [] }
+  );
+  assert.equal(p.ok, false);
+  assert.ok(p.errors.some((e) => sync.SCOPE_CODES.includes(e.code)),
+    'scope_out_of_bounds must still be spelled the way SCOPE_CODES expects');
+});
+
+console.log('\nrule 4 — the sync never arms anything:');
+
+t('a NEW clean definition inserts DISABLED', () => {
+  const p = sync.planOne(def(), { authorRank: 'archon', allowedModules: ['agents'] });
+  assert.equal(p.action, 'upsert');
+  assert.equal(p.enabled, false, 'arming is an operator act, by the same logic as rule 2');
+});
+
+t("an EXISTING row keeps the operator's own enabled setting", () => {
+  const on = sync.planOne(def(), {
+    authorRank: 'archon', allowedModules: ['agents'], existing: { source: 'file', enabled: true },
+  });
+  assert.equal(on.enabled, true, 'a deploy must not undo an operator switching an agent on');
+  const off = sync.planOne(def(), {
+    authorRank: 'archon', allowedModules: ['agents'], existing: { source: 'file', enabled: false },
+  });
+  assert.equal(off.enabled, false);
+});
+
+t('a flagged row is forced OFF even if it was armed before', () => {
+  // The dangerous ordering: an agent is armed, then its scope is edited to reach
+  // a protected surface. Carrying `enabled` forward would arm the new scope.
+  const p = sync.planOne(def(), {
+    authorRank: 'thetes', allowedModules: ['agents'], protectedModules: ['agents'],
+    existing: { source: 'file', enabled: true },
+  });
+  assert.equal(p.action, 'flagged');
+  assert.equal(p.enabled, false, 'a newly-flagged agent must be disarmed, not left running');
+});
+
+console.log('\nthe absent directory is a legitimate state:');
+
+t('no .claude/agents/ → zero files, no throw', () => {
+  // It does not exist in the core tree at all today, and an instance shipping no
+  // agents must still deploy cleanly.
+  assert.deepEqual(sync.readAgentFiles(path.join(os.tmpdir(), 'agents-sync-absent-xyz')), []);
+});
+
+t('a real directory is read, .md only, sorted', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-sync-'));
+  fs.writeFileSync(path.join(dir, 'zeta.md'), FILE);
+  fs.writeFileSync(path.join(dir, 'alpha.md'), FILE.replace('name: historian', 'name: alpha'));
+  fs.writeFileSync(path.join(dir, 'README.txt'), 'not a definition');
+  const files = sync.readAgentFiles(dir);
+  assert.equal(files.length, 2, 'only .md files are definitions');
+  assert.deepEqual(files.map((f) => f.candidate.name), ['alpha', 'historian'], 'sorted, so a run is reproducible');
+});
+
+console.log('\nplanSync — the whole reconcile, still pure:');
+
+t('one plan entry per file, each carrying its own author rank', () => {
+  const files = [
+    { file: '.claude/agents/a.md', candidate: sync.parseAgentFile(FILE.replace('historian', 'a'), {}) },
+    { file: '.claude/agents/b.md', candidate: sync.parseAgentFile(FILE.replace('historian', 'b'), {}) },
+  ];
+  const plan = sync.planSync(files, {
+    existingByName: new Map([['b', { source: 'db', enabled: true }]]),
+    authorRankFor: (f) => (f.endsWith('a.md') ? 'archon' : 'xenos'),
+    allowedModules: ['agents'],
+    protectedModules: [],
+  });
+  assert.equal(plan.length, 2);
+  assert.equal(plan[0].action, 'upsert');
+  assert.equal(plan[0].authorRank, 'archon', 'rank is resolved PER FILE, not once for the run');
+  assert.equal(plan[1].action, 'protected', 'the db-owned name is left alone');
+});
+
+console.log('\nthe committer mapping — provenance only, and known spoofable:');
+
+t('a GitHub noreply address yields the login; a local name is only a fallback', () => {
+  // Neither form is trustworthy — both come from the commit author, which the
+  // committer sets. The preference is about giving the BEST GUESS at provenance,
+  // not about security; the security is that this value never reaches a decision
+  // (see the escalation-path test above).
+  const login = sync.lastCommitterLogin('x', { runGit: () => '12345+octocat@users.noreply.github.com\nSomeone Else\n' });
+  assert.equal(login, 'octocat', 'the noreply address carries the login and cannot be set locally');
+  // A generic fixture on purpose: a real builder's login baked into a test is
+  // the hardcoded-founder-identity defect audit-authorship.sh exists to catch,
+  // and it caught this line in its first draft.
+  const fallback = sync.lastCommitterLogin('x', { runGit: () => 'someone@example.com\na-builder\n' });
+  assert.equal(fallback, 'a-builder');
+  assert.equal(sync.lastCommitterLogin('x', { runGit: () => { throw new Error('not a repo'); } }), null,
+    'an unreadable history resolves to null, which rule 2 treats as insufficient');
+});
+
+console.log('\nthe reconcile actually RUNS at deploy:');
+
+t('migrate.sh invokes agents-sync, module-gated and fail-open', () => {
+  // A reconcile nothing calls is a script, not a deploy step — review caught
+  // that the first cut shipped the machinery with no caller. migrate.sh is the
+  // one deploy-time hook the portable core owns, and it applies the schema this
+  // writes into a few lines above, so the table exists by the time it runs.
+  const sh = fs.readFileSync(new URL('../scripts/migrate.sh', import.meta.url), 'utf8');
+  assert.match(sh, /scripts\/gds\/agents-sync\.js/, 'the deploy path must call it');
+  assert.match(sh, /isModuleEnabled\('agents'\)/, "gated on the module — it is default:false");
+  // Fail-OPEN: a stale registry is a nuisance, an aborted deploy is an outage,
+  // and the script is already fail-closed about what it imports.
+  assert.match(sh, /agents-sync failed — the registry is stale by one deploy/,
+    'a failed reconcile must not abort the deploy');
+  const call = sh.slice(sh.indexOf('agents-sync'));
+  assert.doesNotMatch(call.slice(0, 200), /exit 1/, 'no exit 1 on the agents-sync path');
+});
+
+console.log(`\nagents_sync: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);