@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/egress_canary.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env tsx
+/**
+ * Egress canary run — road-to-free-hands-a-paid-head-checks step 1.3.
+ *
+ * Planted synthetic values — credentials, personal data and internal
+ * identifiers — are placed in the payload, in the system prompt and in rule
+ * text a payload could quote, and sent through `ask_transport` to an
+ * OpenAI-compatible mock on loopback that records every body it receives. No
+ * network, synthetic values only.
+ *
+ * Each canary × placement is reported as:
+ *   replaced       — it left as a placeholder;
+ *   refused        — the final check refused the call, with its reason;
+ *   not-detectable — it left in clear and no rule in the final check sees it
+ *                    on its own (identifier rows have not landed for it);
+ * and `leaked` lists any canary the final check WOULD refuse on its own that
+ * still reached the mock in clear. Zero observed leaks is a test result, never
+ * a guarantee.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { askOnce } from './ask_transport.js';
+import { _OpenAICompatibleClient, type ExternalAIClient } from './ai_council/clients.js';
+import { councilEgress, resetCouncilEgress } from './ai_council/council_egress.js';
+
+export interface Canary {
+    readonly id: string;
+    readonly class: 'credential' | 'personal' | 'internal';
+    readonly value: string;
+}
+
+/**
+ * Synthetic: no value below belongs to anyone or opens anything. Prefixes are
+ * assembled from parts so the rule table stays the one place that spells one.
+ */
+export const CANARIES: readonly Canary[] = [
+    { id: 'anthropic-key', class: 'credential', value: `${'s' + 'k-' + 'ant-' + 'api03-'}${'CANARYx7Qm2LwZp9Rt4Vn8Kd3Hs6Jf1Bg5'.repeat(2)}AA` }, // secret-allow: synthetic canary, assembled from parts, opens nothing
+    { id: 'github-pat', class: 'credential', value: 'gh' + 'p_' + 'CANARY0a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5' }, // secret-allow: synthetic canary, assembled from parts, opens nothing
+    { id: 'huggingface-token', class: 'credential', value: 'h' + 'f_' + 'CANARYabcdefghijklmnopqrstuvwxyzABCD' }, // secret-allow: synthetic canary, assembled from parts, opens nothing
+    { id: 'aws-access-key', class: 'credential', value: 'AK' + 'IA' + 'CANARY7Q2W3E4R5T' },
+    { id: 'email', class: 'personal', value: 'max.mustermann.canary' + '@' + 'galawork-kunde.de' },
+    { id: 'iban', class: 'personal', value: 'DE89' + '3704' + '0044' + '0532' + '0130' + '00' },
+    { id: 'phone', class: 'personal', value: '+49 170' + ' 1234567' },
+    { id: 'repo-path', class: 'internal', value: '/Users/canary-owner/projects/galawork/secret-module' },
+    { id: 'internal-host', class: 'internal', value: 'billing-db.canary.internal' },
+];
+
+export const PLACEMENTS = ['payload', 'system', 'rule-text'] as const;
+export type Placement = (typeof PLACEMENTS)[number];
+
+export interface CanaryRow {
+    canary: string;
+    class: Canary['class'];
+    placement: Placement;
+    outcome: 'replaced' | 'refused' | 'not-detectable';
+    placeholder?: string;
+    reason?: string;
+}
+
+export interface CanaryReport {
+    rows: CanaryRow[];
+    leaked: string[];
+}
+
+const MOCK = `
+const http = require('node:http');
+const fs = require('node:fs');
+const out = process.argv[1];
+const server = http.createServer((req, res) => {
+  let body = '';
+  req.on('data', (d) => (body += d));
+  req.on('end', () => {
+    fs.appendFileSync(out, JSON.stringify(body) + '\\n');
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify({ model: 'mock', choices: [{ message: { content: 'ok' } }], usage: { prompt_tokens: 1, completion_tokens: 1 } }));
+  });
+});
+server.listen(0, '127.0.0.1', () => process.stdout.write(String(server.address().port) + '\\n'));
+`;
+
+async function startMock(recordFile: string): Promise<{ port: number; stop: () => void }> {
+    const child = spawn(process.execPath, ['-e', MOCK, recordFile], { stdio: ['ignore', 'pipe', 'inherit'] });
+    const port = await new Promise<number>((resolve, reject) => {
+        child.stdout.once('data', (d: Buffer) => resolve(Number(d.toString().trim())));
+        child.once('exit', (code) => reject(new Error(`mock exited ${code}`)));
+    });
+    return { port, stop: () => child.kill() };
+}
+
+function placeIn(placement: Placement, value: string): { system: string; prompt: string } {
+    const base = 'Summarise the given text in one line.';
+    if (placement === 'system') return { system: `You are a summariser. Context id: ${value}.`, prompt: base };
+    if (placement === 'rule-text') {
+        return { system: 'You are a summariser.', prompt: `${base}\n\nQuoted rule:\n> Contact the owner at ${value} before editing.` };
+    }
+    return { system: 'You are a summariser.', prompt: `${base}\n\nText: the job failed while reading ${value}.` };
+}
+
+function readBodies(file: string): string[] {
+    if (!fs.existsSync(file)) return [];
+    return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l) as string);
+}
+
+/**
+ * `identifiers: true` is the `protect` mode, the one free hands send under: the
+ * final check then refuses identifiers as well as credentials.
+ */
+export async function runEgressCanary(opts: { readonly identifiers: boolean } = { identifiers: true }): Promise<CanaryReport> {
+    resetCouncilEgress(opts);
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'egress-canary-'));
+    const recordFile = path.join(dir, 'bodies.jsonl');
+    const mock = await startMock(recordFile);
+    const rows: CanaryRow[] = [];
+    const leaked: string[] = [];
+    try {
+        const client = new _OpenAICompatibleClient({ model: 'mock', api_key: 'mock-key', base_url: `http://127.0.0.1:${mock.port}/v1` });
+        for (const canary of CANARIES) {
+            const detectable = councilEgress().check(canary.value);
+            for (const placement of PLACEMENTS) {
+                const before = readBodies(recordFile).length;
+                const { system, prompt } = placeIn(placement, canary.value);
+                await askOnce(prompt, { members: [client as unknown as ExternalAIClient], systemPrompt: system, auditDir: null });
+                const sent = readBodies(recordFile).slice(before);
+                const row: CanaryRow = { canary: canary.id, class: canary.class, placement, outcome: 'not-detectable' };
+                if (sent.length === 0) {
+                    row.outcome = 'refused';
+                    row.reason = detectable !== null ? `${detectable.reason} (${detectable.what})` : 'refused before send';
+                } else if (sent.some((b) => b.includes(canary.value))) {
+                    if (detectable !== null) leaked.push(`${canary.id}@${placement}`);
+                    row.outcome = 'not-detectable';
+                } else {
+                    row.outcome = 'replaced';
+                    row.placeholder = sent.join('').match(/__[A-Z]+_\d+_[a-z0-9]+__/)?.[0] ?? 'placeholder';
+                }
+                rows.push(row);
+            }
+        }
+    } finally {
+        resetCouncilEgress();
+        mock.stop();
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    return { rows, leaked };
+}
+
+async function main(): Promise<number> {
+    const report = await runEgressCanary();
+    for (const r of report.rows) {
+        const extra = r.outcome === 'refused' ? ` — ${r.reason}` : r.outcome === 'replaced' ? ` — ${r.placeholder}` : '';
+        process.stdout.write(`${r.canary.padEnd(18)} ${r.class.padEnd(10)} ${r.placement.padEnd(9)} ${r.outcome}${extra}\n`);
+    }
+    if (report.leaked.length > 0) {
+        process.stderr.write(`❌  egress_canary: ${report.leaked.length} detectable canary(ies) reached the mock in clear: ${report.leaked.join(', ')}\n`);
+        return 1;
+    }
+    process.stdout.write(`✅  egress_canary: no detectable canary left in clear (${report.rows.length} placements). A test result, never a guarantee.\n`);
+    return 0;
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+    void main().then((code) => process.exit(code));
+}

package/src/scripts/egress_sender_census.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env tsx
+/**
+ * egress_sender_census.ts — regenerate the sender census in
+ * docs/contracts/egress-placeholders-v1.md from the tree, or report that the
+ * committed copy has drifted from it.
+ *
+ *   ./scripts-run src/scripts/egress_sender_census           # exit 1 on drift or an undeclared sender
+ *   ./scripts-run src/scripts/egress_sender_census --write   # rewrite the region
+ *
+ * Every sender must be `asserted`, `fixed-corpus` or `uncovered` with a reason
+ * (step 3.4); a module with no answer fails the census whether or not the
+ * committed table is current.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { renderTable, SCAN_ROOTS, scanSenders, undeclared } from './_lib/egress_sender_scan.js';
+
+const HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(HERE), '..', '..');
+
+export const DOC_REL = 'docs/contracts/egress-placeholders-v1.md';
+export const BEGIN_MARKER = '<!-- BEGIN egress-sender-census (generated) -->';
+export const END_MARKER = '<!-- END egress-sender-census -->';
+
+export function renderRegion(repoRoot: string): string {
+    return [
+        '> Generated by `egress_sender_census`. Do not edit between the markers;',
+        '> regenerate with `./scripts-run src/scripts/egress_sender_census --write`.',
+        '',
+        `Scanned: ${SCAN_ROOTS.map((r) => `\`${r}/\``).join(', ')}, TypeScript and shell, tests excluded.`,
+        'A module whose endpoint is computed at runtime **and** whose send shape the',
+        'scanner does not recognise is absent from this table; that residual is why',
+        '`unclassified` exists. `content` stays `undeclared` until the module carries an',
+        '`egress-content:` marker, and `engine` counts a direct import of a function that detects or replaces',
+        '(`detect`, `findSpans`, `replaceSpans`, `replaceValues`); importing a table constant does not count.',
+        '`coverage` is what the module\'s marker claims (`asserted` only for a module that imports the final',
+        'check, `council_egress.ts`); `undeclared` fails the census.',
+        '',
+        renderTable(scanSenders(repoRoot)),
+    ].join('\n');
+}
+
+export function extractRegion(doc: string): string | null {
+    const begin = doc.indexOf(BEGIN_MARKER);
+    const end = doc.indexOf(END_MARKER);
+    if (begin === -1 || end === -1 || end < begin) return null;
+    return doc.slice(begin + BEGIN_MARKER.length, end).trim();
+}
+
+export function spliceRegion(doc: string, region: string): string {
+    const begin = doc.indexOf(BEGIN_MARKER);
+    const end = doc.indexOf(END_MARKER);
+    if (begin === -1 || end === -1 || end < begin) {
+        throw new Error(`egress_sender_census: markers missing in ${DOC_REL}`);
+    }
+    return `${doc.slice(0, begin)}${BEGIN_MARKER}\n${region}\n${doc.slice(end)}`;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), repoRoot: string = ROOT): number {
+    const docPath = path.join(repoRoot, DOC_REL);
+    const doc = fs.readFileSync(docPath, 'utf-8');
+    const region = renderRegion(repoRoot);
+    const missing = undeclared(scanSenders(repoRoot));
+    if (missing.length > 0) {
+        process.stderr.write('egress_sender_census: a sender has no coverage — mark it `egress-content:` with a reason:\n');
+        for (const r of missing) process.stderr.write(`  · ${r.module}: ${r.reason}\n`);
+        if (!argv.includes('--write')) return 1;
+    }
+    if (argv.includes('--write')) {
+        fs.writeFileSync(docPath, spliceRegion(doc, region));
+        process.stdout.write(`egress_sender_census: wrote ${DOC_REL}\n`);
+        return missing.length > 0 ? 1 : 0;
+    }
+    const committed = extractRegion(doc);
+    if (committed !== region.trim()) {
+        process.stderr.write(
+            `egress_sender_census: the census in ${DOC_REL} differs from the tree — ` +
+                'run ./scripts-run src/scripts/egress_sender_census --write\n',
+        );
+        return 1;
+    }
+    process.stdout.write('egress_sender_census: census matches the tree\n');
+    return 0;
+}
+
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/external_sources_denylist.json

@@ -75,7 +75,18 @@
     "\\bopen-gsd\\b",
     "\\bgsd-core\\b",
     "\\bgsd-build\\b",
-    "\\bget-shit-done\\b"
+    "\\bget-shit-done\\b",
+    "\\bblazity\\b",
+    "blazity/atlas",
+    "\\bpacifio\\b",
+    "pacifio/atlas",
+    "\\bagulli\\b",
+    "\\batlas-agents\\b",
+    "\\batlasgo\\b",
+    "\\bariga\\b",
+    "\\bclaudecowork\\b",
+    "\\btryatlas\\b",
+    "\\batlasengine\\b"
   ],
   "_deny_digests_README": "DORMANT (road-to-source-silence Phase 1.1). HMAC-SHA256 digests of the deny set, derived from the gitignored private master by src/scripts/build_source_digests.ts. It is EMPTY on purpose: the plaintext `deny` array above stays in force and is not deleted. Provisioning the CI secret SOURCE_DENY_KEY, generating production digests, removing the plaintext array and switching CI to strict mode are ONE ATOMIC MAINTAINER CHANGE (AI council 2026-08-28, blocker `where-the-key-lives`, 2/2) — splitting them leaves the gate either failing every run for want of a key or silently degraded to warn mode, which is the failure this whole programme exists to remove. Recipe: docs/maintainers/source-deny-digests.md",
   "deny_digests": [],
@@ -115,19 +126,90 @@
     "agent-os": "collides with our own coined 'Agent-OS primitive' term (universal-skills) — too FP-prone to auto-deny; scrub external 'agent-os' mentions by review.",
     "telegraph-shrink / telegraph-condense": "collide with our own 'telegraph'/'telegraph-condensed' feature vocabulary; the telegraph upstream is guarded via 'caveman' + 'juliusbrussee' instead.",
     "serena": "S8's repo half. A common given name — a bare \\bserena\\b would turn a confidentiality gate into a ban on a person's name in any example or persona. The subject is guarded by the owner token \\boraios\\b plus the owner-qualified 'oraios/serena' instead, which is exactly the standard the pre-existing 'obra/superpowers' row already meets. Measured 2026-09-29: 0 occurrences in 11,598 tracked files, so the exclusion is a policy choice about future prose, not a reaction to a live collision.",
-    "gsd": "S9/S10's shared stem. A three-letter acronym is too collision-prone to deny bare. The two subjects are guarded by the four qualified rows \\bopen-gsd\\b, \\bgsd-core\\b, \\bgsd-build\\b and \\bget-shit-done\\b instead. Note the last one is hyphenated on purpose: the spaced English phrase is ordinary prose and is deliberately NOT denied."
+    "gsd": "S9/S10's shared stem. A three-letter acronym is too collision-prone to deny bare. The two subjects are guarded by the four qualified rows \\bopen-gsd\\b, \\bgsd-core\\b, \\bgsd-build\\b and \\bget-shit-done\\b instead. Note the last one is hyphenated on purpose: the spaced English phrase is ordinary prose and is deliberately NOT denied.",
+    "atlas": "S11-S17's shared repo/product half. A bare \\batlas\\b would collide with the ordinary word already in the tracked tree (a design-canon mention and several archived review diffs, 87 occurrences measured 2026-10-16), and with Atlassian. The seven subjects are guarded by their owner or host tokens instead — \\bblazity\\b, \\bpacifio\\b, \\bagulli\\b, \\batlasgo\\b, \\bariga\\b, \\bclaudecowork\\b, \\btryatlas\\b, \\batlasengine\\b — plus the two owner-qualified rows and the hyphenated \\batlas-agents\\b, which is distinctive on its own."
   },
   "_subjects_README": "Registry of the comparison / scorecard subject set, added 2026-09-29 by road-to-a-denylist-that-sees-every-subject. It exists so that 'a subject was audited' and 'a subject is denied' cannot drift apart again: tests/scripts/external_source_subject_registry.test.ts asserts every `slug` below is matched by at least one `deny` pattern above, and reds when a row is added without its pattern. The slugs live HERE and nowhere else in the tracked tree — this file is the one path skip_paths exempts from its own scan, and it already had to hold these tokens as deny data, so the registry discloses nothing the array above did not. A fixture that named them would be a tracked file publishing exactly what the gate exists to hide, so the test synthesises its corpus from this registry at run time and never commits a resolved name. `id` values are the S1..S10 identifiers the maintainer-held source map uses; they are deliberately opaque here.",
   "subjects": [
-    { "id": "S1", "slug": "graphify-labs/graphify" },
-    { "id": "S2", "slug": "ruvnet/ruflo" },
-    { "id": "S3", "slug": "affaan-m/everything-claude-code" },
-    { "id": "S4", "slug": "obra/superpowers" },
-    { "id": "S5", "slug": "qoderai/better-harness", "note": "Added 2026-09-29. Owner and repo both denied; the repo half is a hyphenated compound, so the ordinary word 'harness' — which this tree uses constantly — is untouched." },
-    { "id": "S6", "slug": "github/spec-kit" },
-    { "id": "S7", "slug": "shanraisshan/claude-code-best-practice", "note": "Added 2026-09-29. The repo half is denied unanchored because the hyphenated triple is distinctive on its own; the spaced phrase 'claude code best practice' is ordinary prose and stays allowed." },
-    { "id": "S8", "slug": "oraios/serena", "note": "Added 2026-09-29. Owner-qualified on purpose — see _excluded_tokens.serena." },
-    { "id": "S9", "slug": "open-gsd/gsd-core", "note": "Added 2026-09-29. Both halves denied with \\b anchors; the bare stem is excluded — see _excluded_tokens.gsd." },
-    { "id": "S10", "slug": "gsd-build/get-shit-done", "note": "Added 2026-09-29. Archived predecessor of S9. Not re-audited, but a name is a name: it is denied on the same terms." }
+    {
+      "id": "S1",
+      "slug": "graphify-labs/graphify"
+    },
+    {
+      "id": "S2",
+      "slug": "ruvnet/ruflo"
+    },
+    {
+      "id": "S3",
+      "slug": "affaan-m/everything-claude-code"
+    },
+    {
+      "id": "S4",
+      "slug": "obra/superpowers"
+    },
+    {
+      "id": "S5",
+      "slug": "qoderai/better-harness",
+      "note": "Added 2026-09-29. Owner and repo both denied; the repo half is a hyphenated compound, so the ordinary word 'harness' — which this tree uses constantly — is untouched."
+    },
+    {
+      "id": "S6",
+      "slug": "github/spec-kit"
+    },
+    {
+      "id": "S7",
+      "slug": "shanraisshan/claude-code-best-practice",
+      "note": "Added 2026-09-29. The repo half is denied unanchored because the hyphenated triple is distinctive on its own; the spaced phrase 'claude code best practice' is ordinary prose and stays allowed."
+    },
+    {
+      "id": "S8",
+      "slug": "oraios/serena",
+      "note": "Added 2026-09-29. Owner-qualified on purpose — see _excluded_tokens.serena."
+    },
+    {
+      "id": "S9",
+      "slug": "open-gsd/gsd-core",
+      "note": "Added 2026-09-29. Both halves denied with \\b anchors; the bare stem is excluded — see _excluded_tokens.gsd."
+    },
+    {
+      "id": "S10",
+      "slug": "gsd-build/get-shit-done",
+      "note": "Added 2026-09-29. Archived predecessor of S9. Not re-audited, but a name is a name: it is denied on the same terms."
+    },
+    {
+      "id": "S11",
+      "slug": "blazity/atlas",
+      "note": "Added 2026-10-16 by round inbox-2026-10-t. Guarded by the owner or host token, never the bare shared word - see _excluded_tokens.atlas."
+    },
+    {
+      "id": "S12",
+      "slug": "pacifio/atlas",
+      "note": "Added 2026-10-16 by round inbox-2026-10-t. Guarded by the owner or host token, never the bare shared word - see _excluded_tokens.atlas."
+    },
+    {
+      "id": "S13",
+      "slug": "agulli/atlas-agents",
+      "note": "Added 2026-10-16 by round inbox-2026-10-t. Guarded by the owner or host token, never the bare shared word - see _excluded_tokens.atlas."
+    },
+    {
+      "id": "S14",
+      "slug": "ariga/atlas",
+      "note": "Added 2026-10-16 by round inbox-2026-10-t. Guarded by the owner or host token, never the bare shared word - see _excluded_tokens.atlas."
+    },
+    {
+      "id": "S15",
+      "slug": "claudecowork.im/atlas",
+      "note": "Added 2026-10-16 by round inbox-2026-10-t. Guarded by the owner or host token, never the bare shared word - see _excluded_tokens.atlas."
+    },
+    {
+      "id": "S16",
+      "slug": "tryatlas.cc/atlas",
+      "note": "Added 2026-10-16 by round inbox-2026-10-t. Guarded by the owner or host token, never the bare shared word - see _excluded_tokens.atlas."
+    },
+    {
+      "id": "S17",
+      "slug": "atlasengine.dev/atlas-engine",
+      "note": "Added 2026-10-16 by round inbox-2026-10-t. Guarded by the owner or host token, never the bare shared word - see _excluded_tokens.atlas."
+    }
   ]
 }

package/src/scripts/generate_catalog.ts

@@ -32,8 +32,12 @@ export const CATALOG_MD = path.join(REPO_ROOT, 'docs', 'skills-catalog.md');
 // re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL) anchored with .match (start only).
 // JS \s matches newlines like Python's, so `\s*\n` and `(.*?)` (DOTALL → [\s\S]).
 const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---/;
-// re.compile(r"^name:\s*(.+?)\s*$", re.MULTILINE)
-const NAME_RE = /^name:[^\S\n]*(.+?)[^\S\n]*$/m;
+// Was re.compile(r"^name:\s*(.+?)\s*$", re.MULTILINE) in the retired Python,
+// which captured the quotes a YAML-quoted `name:` carries and rendered them
+// into the catalogue row and its link. The optional `"?` mirrors DESC_RE and
+// strips ONE pair of surrounding quotes; the retired source is gone, so this
+// is a deliberate deviation from it rather than a parity break.
+const NAME_RE = /^name:[^\S\n]*"?(.+?)"?[^\S\n]*$/m;
 // re.compile(r"^description:\s*\"?(.+?)\"?\s*$", re.MULTILINE)
 const DESC_RE = /^description:[^\S\n]*"?(.+?)"?[^\S\n]*$/m;
 

package/src/scripts/generate_owned_digest.ts

@@ -0,0 +1,163 @@
+#!/usr/bin/env tsx
+/**
+ * Writes `agents/roadmaps-owned.md`: one row per active, parked (`later/`) and
+ * stub roadmap, naming what each one owns, so an intake session can shortlist
+ * an existing owner before it writes a new file.
+ *
+ * The row holds only fields that change rarely — slug, directory, frontmatter
+ * status, and the first sentence of `## Goal` (the H1 when there is none) — so
+ * a checkbox flip or a new note never changes the digest. Paths are left out on
+ * purpose: they churn with every edit and citation frequency is not ownership.
+ *
+ * The digest is a shortlist, never an owner decision: a reader confirms a
+ * candidate by opening its roadmap. Over budget is a failure, never a
+ * truncation, because a dropped tail row would hide an owner by sort order.
+ *
+ * Usage:
+ *     tsx src/scripts/generate_owned_digest.ts            # rewrite in place
+ *     tsx src/scripts/generate_owned_digest.ts --check    # exit 1 when stale or over budget
+ *     tsx src/scripts/generate_owned_digest.ts --out PATH # write elsewhere
+ *
+ * Exit codes: 0 written / in sync · 1 stale or over budget · 2 usage.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { is_roadmap_candidate as isRoadmapCandidate, parse_frontmatter as parseFrontmatter } from '../agent-src/scripts/update_roadmap_progress.js';
+import { gpt_tokens } from './_lib/token_count.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export const DIGEST = 'agents/roadmaps-owned.md';
+export const GENERATOR = 'src/scripts/generate_owned_digest.ts';
+export const ROADMAPS = 'agents/roadmaps';
+/** `''` is the active top level. Order is the row order. */
+export const DIRS = ['', 'later', 'stubs'] as const;
+export const MAX_WORDS = 20;
+export const BUDGET_TOKENS = 10_000;
+
+export type Dir = (typeof DIRS)[number];
+
+export interface Entry {
+    readonly slug: string;
+    readonly dir: Dir;
+    readonly status: string;
+    readonly owns: string;
+}
+
+function plain(s: string): string {
+    return s
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .replace(/\*\*|__/g, '')
+        .replace(/(^|[\s(])[*_]([^*_\s][^*_]*?)[*_](?=[\s).,;:]|$)/g, '$1$2')
+        .replace(/\|/g, '\\|')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+function firstSentence(paragraph: string): string {
+    const body = paragraph.replace(/^\s*(?:[-*+]|\d+\.)\s+/, '');
+    const m = /^([\s\S]*?[.!?])(?=\s+[A-Z`(*"']|\s*$)/.exec(body);
+    return m?.[1] ?? body;
+}
+
+function capWords(s: string, max: number): string {
+    const words = s.split(' ').filter((w) => w !== '');
+    return words.length <= max ? words.join(' ') : `${words.slice(0, max).join(' ')} …`;
+}
+
+/** What a roadmap owns, in at most {@link MAX_WORDS} words. */
+export function describe(text: string): string {
+    const goal = /^## Goal[^\n]*\n+([\s\S]*?)(?:\n\s*\n|\n## |(?![\s\S]))/m.exec(text);
+    const source = goal?.[1]?.trim() ? firstSentence(goal[1]) : (/^# +(?:Roadmap: *|Stub: *)?(.+?)\s*$/m.exec(text)?.[1] ?? '');
+    return capWords(plain(source), MAX_WORDS) || '—';
+}
+
+export function entryOf(dir: Dir, file: string, text: string): Entry {
+    const status = parseFrontmatter(text)['status']?.trim();
+    return { slug: file.replace(/\.md$/, ''), dir, status: status !== undefined && status !== '' ? status : '—', owns: describe(text) };
+}
+
+export function collect(root: string = REPO_ROOT): Entry[] {
+    const out: Entry[] = [];
+    for (const dir of DIRS) {
+        const abs = path.join(root, ROADMAPS, dir);
+        if (!fs.existsSync(abs)) continue;
+        for (const file of fs.readdirSync(abs).sort()) {
+            if (!file.endsWith('.md') || !isRoadmapCandidate(file)) continue;
+            const full = path.join(abs, file);
+            if (!fs.statSync(full).isFile()) continue;
+            out.push(entryOf(dir, file, fs.readFileSync(full, 'utf8')));
+        }
+    }
+    return out;
+}
+
+export function render(entries: readonly Entry[]): string {
+    return [
+        '<!-- GENERATED by `./scripts-run src/scripts/generate_owned_digest`; edit the roadmaps, never this file. -->',
+        '',
+        '# What each roadmap owns',
+        '',
+        // No row count in the header: every landing or archive would change that one line,
+        // and two branches changing it always conflict where row edits rarely do.
+        'A shortlist for intake: one row per active, parked (`later/`) and stub roadmap.',
+        '`owns` is the first sentence of the file\'s `## Goal`, or its title when it has none, capped at',
+        `${String(MAX_WORDS)} words. A row is a candidate, never an owner decision: open the roadmap to confirm it,`,
+        'and keep the full search — this file only adds candidates to it.',
+        '',
+        '| slug | dir | status | owns |',
+        '|---|---|---|---|',
+        ...entries.map((e) => `| ${e.slug} | ${e.dir === '' ? 'active' : e.dir} | ${e.status} | ${e.owns} |`),
+        '',
+    ].join('\n');
+}
+
+export function overBudget(text: string, budget: number = BUDGET_TOKENS): string | null {
+    const t = gpt_tokens(text);
+    return t.tokens > budget ? `${DIGEST} is ${String(t.tokens)} tokens${t.exact ? '' : ' (estimated)'}, over its ${String(budget)}-token budget — shorten the goals or reopen the budget; the generator never truncates` : null;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), root: string = REPO_ROOT): number {
+    let check = false;
+    let out: string | null = null;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--check') check = true;
+        else if (argv[i] === '--out' && argv[i + 1] !== undefined) out = argv[++i] as string;
+        else {
+            process.stderr.write(`unknown argument: ${String(argv[i])}\nusage: generate_owned_digest [--check | --out PATH]\n`);
+            return 2;
+        }
+    }
+    const text = render(collect(root));
+    const over = overBudget(text);
+    if (over !== null) {
+        process.stderr.write(`${over}\n`);
+        return 1;
+    }
+    const file = path.join(root, DIGEST);
+    if (check) {
+        const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+        if (current === text) return 0;
+        process.stderr.write(`${DIGEST} is ${current === null ? 'missing' : 'stale'} — run ./scripts-run ${GENERATOR.replace(/\.ts$/, '')}\n`);
+        return 1;
+    }
+    fs.writeFileSync(out ?? file, text);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exitCode = main();
+}