@bongos/core 1.19.526 → 1.19.528

package/scripts/gds/session-cost.js

@@ -331,13 +331,13 @@ async function main() {
     if (!transcriptPath) transcriptPath = newestTranscriptFor(cwd);
     if (!transcriptPath || !fs.existsSync(transcriptPath)) {
       // nothing to price — quiet skip
-      process.exit(0);
+      return;
     }
     if (!sessionId) sessionId = path.basename(transcriptPath, '.jsonl');
 
     // No GDS session → nothing to attribute spend to; skip quietly.
     const session = await loadSession();
-    if (!session || !session.token) process.exit(0);
+    if (!session || !session.token) return;
 
     const inter = priceTranscript(transcriptPath);
 
@@ -347,7 +347,7 @@ async function main() {
     const sub = priceSubagents(sessionDir);
 
     const total = inter.total + sub.subagentTotal;
-    if (!(total > 0)) process.exit(0);
+    if (!(total > 0)) return;
 
     // task 1344: split into call-site-tagged, tier-carrying rows; cron sessions
     // are tagged via OTB_COST_CRON_ROUTINE.
@@ -362,7 +362,7 @@ async function main() {
         console.log(`  ${r.source} (${r.source_ref}) $${r.amount_usd.toFixed(4)}  tiers: fresh $${r.tiers.fresh_input_usd} / cache_read $${r.tiers.cache_read_usd} / cache_write $${r.tiers.cache_write_usd} / output $${r.tiers.output_usd}`);
       }
       console.log(`  reconcile: prior-single $${built.priorSingle.toFixed(4)} vs rows-sum $${built.rowsTotal.toFixed(4)} (Δ $${Math.abs(built.priorSingle - built.rowsTotal).toFixed(4)})`);
-      process.exit(0);
+      return;
     }
 
     const api = await cliClient({ allowUnauthenticated: true });
@@ -389,18 +389,21 @@ async function main() {
         console.error(`session-cost: skipped (non-fatal): HTTP ${res.status} for ${r.source}`);
       }
     }
-    process.exit(0);
+    return;
   } catch (err) {
     // Best-effort: never break session exit.
     console.error('session-cost: skipped (non-fatal):', err && err.message ? err.message : err);
-    process.exit(0);
+    return;
   }
 }
 
 // Run only when invoked directly (the SessionEnd hook / CLI). When required by a
 // test, expose the pure-ish helpers without firing the IIFE / network / exit.
 if (require.main === module) {
-  main();
+  // Drain instead of process.exit(): an exit while a socket/child handle is still closing aborts node on
+  // Windows (UV_HANDLE_CLOSING, src\win\async.c) — 59 SessionStart/UserPromptSubmit runs died that way
+  // (task 1003548). The unref'd backstop only fires if a hung request keeps the loop alive.
+  main().catch(() => {}).finally(() => { process.exitCode = 0; setTimeout(() => process.exit(0), 1500).unref(); });
 }
 
 module.exports = {

package/scripts/gds/session-digest.js

@@ -127,12 +127,12 @@ async function main() {
     });
 
     if (!transcriptPath) transcriptPath = newestTranscriptFor(cwd || process.cwd());
-    if (!transcriptPath || !fs.existsSync(transcriptPath)) process.exit(0); // nothing to capture
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) return; // nothing to capture
     if (!sessionId) sessionId = path.basename(transcriptPath, '.jsonl');
 
     // No GDS session → nothing to attribute the digest to; skip quietly.
     const session = await loadSession();
-    if (!session || !session.token) process.exit(0);
+    if (!session || !session.token) return;
 
     // Secret hygiene: buildSessionDigest (ship.js) is the PRIMARY scrubber — it
     // redacts known secret PATTERNS + a high-entropy catch-all (task 1003).
@@ -180,10 +180,13 @@ async function main() {
   } catch (e) {
     console.error('session-digest: skipped —', e && e.message ? e.message : e);
   } finally {
-    process.exit(0);
+    return;
   }
 }
 
-if (require.main === module) main();
+// Drain instead of process.exit(): an exit while a socket/child handle is still closing aborts node on
+// Windows (UV_HANDLE_CLOSING, src\win\async.c) — 59 SessionStart/UserPromptSubmit runs died that way
+// (task 1003548). The unref'd backstop only fires if a hung request keeps the loop alive.
+if (require.main === module) main().catch(() => {}).finally(() => { process.exitCode = 0; setTimeout(() => process.exit(0), 1500).unref(); });
 
 module.exports = { parseHookInput };

package/scripts/gds/ship-check.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// scripts/gds/ship-check.js — run every freshness/fitness check ship.js will run, in one command,
+// BEFORE you ship, and print the healing command for each stale thing.
+//
+// Why (task 1003548): a scan of 140 sessions found builders running these generators and checks by
+// hand 223 times in three days (fitness.js ×84, gen-repo-map ×41, copy-inventory ×42, gen-api-docs
+// ×16, linkify-refs ×13, docs-entropy ×12, gen-file-map ×9, gen-session-index ×6), one Bash call at
+// a time, because a ship that fails preflight costs a grader run. The last 30 days of session logs
+// name a stale generated file in roughly a quarter of all sessions. This is that sequence as one
+// call with one table. It CHANGES NOTHING: every step is a --check; the "fix" column is what to run.
+//
+// Usage:
+//   node scripts/gds/ship-check.js            checks only (fast; no tests)
+//   node scripts/gds/ship-check.js --tests    also run the DB-free unit lane (npm test) and list failures
+//   node scripts/gds/ship-check.js --json
+// Exit 1 when any check is stale/failing, 0 when everything is fresh.
+'use strict';
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Each step: a label, the argv to run (node scripts run with THIS node), the command that heals it,
+// and how to read a non-zero exit. `optional` steps are skipped when their script is absent.
+const STEPS = [
+  { key: 'fitness', label: 'fitness.js (architecture + budgets + freshness gate)', argv: ['scripts/gds/fitness.js'], fix: 'read the ✗ lines above; each names its fix' },
+  { key: 'repo-map', label: 'nested CLAUDE.md symbol blocks fresh', argv: ['scripts/gds/gen-repo-map.js', '--check-block'], fix: 'node scripts/gds/gen-repo-map.js' },
+  { key: 'session-index', label: 'CLAUDE.md §13 session snippet fresh', argv: ['scripts/gds/gen-session-index.js', '--check-block'], fix: 'node scripts/gds/gen-session-index.js' },
+  { key: 'file-map', label: 'docs/file-map.md skills/routines sections fresh', argv: ['scripts/gds/gen-file-map.js', '--check'], fix: 'node scripts/gds/gen-file-map.js (+ a note in docs/file-map.notes.json for a new skill)' },
+  { key: 'api-docs', label: 'docs/api/openapi.json + api-reference fresh', argv: ['scripts/gds/gen-api-docs.js', '--check'], fix: 'node scripts/gds/gen-api-docs.js' },
+  { key: 'copy-registry', label: 'docs/copy-registry.json fresh', argv: ['scripts/gds/copy-inventory.js', '--check'], fix: 'node scripts/gds/copy-inventory.js', optional: true },
+  { key: 'linkify', label: 'no bare #NNN task refs in committed markdown', argv: ['scripts/gds/linkify-refs.js', '--check'], fix: 'node scripts/gds/linkify-refs.js', optional: true },
+  { key: 'skill-lint', label: 'SKILL.md frontmatter parses', argv: ['scripts/gds/skill-lint.js'], fix: 'fix the ✗ lines (description: >- block scalars)' },
+  { key: 'tests', label: 'DB-free unit lane (npm test)', argv: ['scripts/gds/run-unit-tests.js'], fix: 'read the FAIL lines; compare against origin/main before calling any of them environmental', onlyWith: '--tests', slow: true },
+];
+
+function runStep(step, { cwd = REPO_ROOT } = {}) {
+  const script = path.join(cwd, step.argv[0]);
+  if (!fs.existsSync(script)) return { ...step, status: step.optional ? 'skipped' : 'missing', ms: 0, tail: `${step.argv[0]} not present` };
+  const t0 = Date.now();
+  const r = spawnSync(process.execPath, [script, ...step.argv.slice(1)], { cwd, encoding: 'utf8', timeout: step.slow ? 15 * 60 * 1000 : 5 * 60 * 1000, env: { ...process.env, GDS_QUIET: '1' } });
+  const out = ((r.stdout || '') + (r.stderr || '')).trim().split(/\r?\n/);
+  const failing = out.filter((l) => /^\s*(✗|FAIL|not ok|STALE|✘)/.test(l) || /STALE|is stale|would update|failed/i.test(l));
+  return { ...step, status: r.status === 0 ? 'ok' : 'fail', code: r.status, signal: r.signal, ms: Date.now() - t0, tail: (failing.length ? failing : out.slice(-4)).slice(0, 12).join('\n') };
+}
+
+function summarize(results) {
+  const stale = results.filter((r) => r.status === 'fail' || r.status === 'missing');
+  return { ok: stale.length === 0, stale: stale.map((r) => r.key), results };
+}
+
+function format(summary) {
+  const lines = ['ship-check — what ship.js will trip on', ''];
+  for (const r of summary.results) {
+    const mark = r.status === 'ok' ? '✓' : r.status === 'skipped' ? '·' : '✗';
+    lines.push(`${mark} ${r.label}  (${r.ms} ms)`);
+    if (r.status !== 'ok' && r.status !== 'skipped') {
+      for (const t of String(r.tail).split('\n')) lines.push(`    ${t}`);
+      lines.push(`    fix → ${r.fix}`);
+    }
+  }
+  lines.push('');
+  lines.push(summary.ok ? 'all fresh — ship.js preflight should pass; the grader and CI are the remaining gates.' : `${summary.stale.length} stale: ${summary.stale.join(', ')} — heal, commit, re-run.`);
+  return lines.join('\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const steps = STEPS.filter((s) => !s.onlyWith || argv.includes(s.onlyWith));
+  const results = steps.map((s) => runStep(s));
+  const summary = summarize(results);
+  console.log(argv.includes('--json') ? JSON.stringify(summary, null, 1) : format(summary));
+  process.exitCode = summary.ok ? 0 : 1;
+}
+
+module.exports = { STEPS, runStep, summarize, format };
+if (require.main === module) main();

package/scripts/gds/ship-regen.js

@@ -87,12 +87,12 @@ function regenerateRepoMap() {
     console.log('  repo-map regen failed (non-fatal) — CI --check-block backstops the tracked blocks');
     return 'regen-failed';
   }
-  const dirty = gitOk('git status --porcelain src/bongos/CLAUDE.md src/bongos/routes/CLAUDE.md scripts/gds/CLAUDE.md');
+  const dirty = gitOk('git status --porcelain src/bongos/CLAUDE.md src/bongos/routes/CLAUDE.md');
   if (!dirty) {
     console.log('  nested-doc symbol blocks already current — nothing to commit (docs/repo-map.md is gitignored, ADR 0110)');
     return 'current';
   }
-  shellOk('git add src/bongos/CLAUDE.md src/bongos/routes/CLAUDE.md scripts/gds/CLAUDE.md');
+  shellOk('git add src/bongos/CLAUDE.md src/bongos/routes/CLAUDE.md');
   if (shellOk('git commit -m "chore(repo-map): auto-regenerate nested-doc symbol blocks (task 1224)"')) {
     console.log('  committed auto-regenerated nested-doc symbol blocks');
     return 'committed';

package/scripts/gds/skill-lint.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// scripts/gds/skill-lint.js — lint SKILL.md frontmatter the way Claude Code's YAML parser reads it.
+//
+// Why (task 1003548): nine of this repo's fifty skills shipped with an unquoted
+// `description:` that contained ": " (e.g. "on it: (re)connect", "HARD RULE: never").
+// YAML reads a colon-space inside a plain scalar as a new mapping key and the whole
+// frontmatter fails to parse; Claude Code then loads the skill with EVERY field
+// dropped — the name falls back to the folder, the description to the body's first
+// line — and nothing warns. Nothing in CI caught it. This linter reproduces the
+// parser's failure modes without a YAML dependency, so it can run in fitness.js
+// (CI), as a PostToolUse hook on SKILL.md edits, and by hand.
+//
+// It also reports the context cost: the skill listing is budgeted at ~1% of the
+// context window, and a description is resident in EVERY session, so long ones
+// crowd the others out and get truncated (skill routing degrades).
+//
+// NOT A YAML PARSER, on purpose. These are targeted regex checks for the hazards that
+// actually bit us (a plain scalar carrying ": " or " #", an unclosed quote or flow
+// collection, a tab, a continuation line), so the repo gains a CI gate with no new
+// dependency. It can therefore under-report an exotic frontmatter shape. The reference
+// parser is `claude plugin validate .claude`, which uses Claude Code's own YAML reader —
+// run it when a file looks fine here but the skill still loads wrong, and treat its
+// verdict as authoritative over this one.
+//
+// Usage:
+//   node scripts/gds/skill-lint.js                 lint every .claude/skills/*/SKILL.md; exit 1 on any error
+//   node scripts/gds/skill-lint.js <file...>       lint specific files
+//   node scripts/gds/skill-lint.js --hook          PostToolUse mode: read the hook JSON on stdin, lint the
+//                                                  edited file if it is a SKILL.md, print findings, exit 0
+//   node scripts/gds/skill-lint.js --json          machine-readable
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DESC_WARN_CHARS = 400;      // longer than this and the listing entry is likely truncated
+const DESC_HARD_CHARS = 1024;     // Claude Code's own cap on a description
+const LISTING_BUDGET_CHARS = 8000; // ~2k tokens ≈ 1% of a 200k window (names + descriptions, all skills)
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// The YAML plain-scalar hazards that make the WHOLE frontmatter unparseable or
+// silently change a value. Each returns a message or null.
+const PLAIN_SCALAR_CHECKS = [
+  (v) => (/: /.test(v) || /:$/.test(v)) ? 'contains ": " (colon-space) — YAML reads it as a new key and the whole frontmatter fails to parse' : null,
+  (v) => / #/.test(v) ? 'contains " #" — YAML starts a comment there and silently truncates the value' : null,
+  (v) => (/^\[/.test(v) && !/\]$/.test(v)) || (/^\{/.test(v) && !/\}$/.test(v)) ? 'opens a flow sequence/map it never closes on the same line' : null,
+  (v) => /^[\]}>|*&!%@`,]/.test(v) ? `starts with "${v[0]}" — a YAML indicator; the value will not be read as text` : null,
+  (v) => /^-\s/.test(v) ? 'starts with "- " — YAML reads a list, not text' : null,
+];
+
+// Split the leading frontmatter block. Returns null when the file has none.
+function splitFrontmatter(text) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const lines = text.split(eol);
+  if (lines[0] !== '---') return null;
+  const end = lines.indexOf('---', 1);
+  if (end < 0) return null;
+  return { lines: lines.slice(1, end), bodyStart: end + 1, eol };
+}
+
+// Lint one frontmatter block (array of lines). Returns { errors, warnings, fields }.
+// `fields` holds each top-level key's raw value; block scalars are joined.
+function lintFrontmatter(lines) {
+  const errors = [], warnings = [], fields = {};
+  let cur = null, curKind = null; // curKind: 'plain' | 'block' | 'quoted'
+  lines.forEach((ln, i) => {
+    const n = i + 2; // 1-based line number in the file (line 1 is the opening ---)
+    if (!ln.trim()) return;
+    if (/^\t/.test(ln)) { errors.push(`line ${n}: tab indentation — YAML forbids tabs`); return; }
+    const kv = /^([A-Za-z0-9_-]+):(?:\s+(.*))?$/.exec(ln);
+    if (kv && !/^\s/.test(ln)) {
+      cur = kv[1];
+      const v = (kv[2] || '').trim();
+      if (fields[cur] !== undefined) errors.push(`line ${n}: duplicate key "${cur}"`);
+      if (v === '' ) { fields[cur] = ''; curKind = 'nested'; return; }
+      if (/^[>|][+-]?\d*$/.test(v)) { fields[cur] = ''; curKind = 'block'; return; }
+      if (/^(["']).*\1$/.test(v)) { fields[cur] = v.slice(1, -1); curKind = 'quoted'; return; }
+      if (/^["']/.test(v)) { errors.push(`line ${n}: "${cur}" opens a quote it never closes on the same line`); fields[cur] = v; curKind = 'plain'; return; }
+      curKind = 'plain'; fields[cur] = v;
+      for (const chk of PLAIN_SCALAR_CHECKS) { const m = chk(v); if (m) { errors.push(`line ${n}: "${cur}" ${m}. Fix: write it as a block scalar — "${cur}: >-" then the text indented two spaces`); break; } }
+      return;
+    }
+    if (/^\s+\S/.test(ln)) {
+      if (!cur) { errors.push(`line ${n}: indented text before any key`); return; }
+      if (curKind === 'block' || curKind === 'nested') { fields[cur] = (fields[cur] ? fields[cur] + ' ' : '') + ln.trim(); return; }
+      errors.push(`line ${n}: continuation under "${cur}" — a plain value cannot span lines; use "${cur}: >-" with the text indented`);
+      return;
+    }
+    errors.push(`line ${n}: not "key: value" — "${ln.slice(0, 60)}"`);
+  });
+  return { errors, warnings, fields };
+}
+
+// Lint one SKILL.md file's text. `file` is used for the name check and messages.
+function lintSkillFile(text, { file = 'SKILL.md' } = {}) {
+  const dirName = path.basename(path.dirname(file));
+  const fm = splitFrontmatter(text);
+  const res = { file, errors: [], warnings: [], name: null, description: '', listingChars: 0 };
+  if (!fm) { res.errors.push('no YAML frontmatter (the file must start with --- and carry name + description)'); return res; }
+  const { errors, warnings, fields } = lintFrontmatter(fm.lines);
+  res.errors.push(...errors); res.warnings.push(...warnings);
+  const name = fields.name || '', desc = fields.description || '';
+  if (!name) res.errors.push('missing "name"');
+  else if (name !== dirName && dirName !== 'SKILL.md') res.warnings.push(`name "${name}" differs from its folder "${dirName}" — the folder name wins in listings`);
+  if (!desc) res.errors.push('missing or empty "description" — the skill would match on its body text');
+  if (desc.length > DESC_HARD_CHARS) res.errors.push(`description is ${desc.length} chars — over Claude Code's ${DESC_HARD_CHARS}-char cap`);
+  else if (desc.length > DESC_WARN_CHARS) res.warnings.push(`description is ${desc.length} chars — over the ~${DESC_WARN_CHARS} we aim for; every char is resident in every session`);
+  res.name = name || dirName; res.description = desc; res.listingChars = res.name.length + desc.length;
+  return res;
+}
+
+// Every SKILL.md under .claude/skills/ (one level deep).
+function listSkillFiles(root = REPO_ROOT) {
+  const dir = path.join(root, '.claude', 'skills');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => path.join(dir, d.name, 'SKILL.md'))
+    .filter((f) => fs.existsSync(f));
+}
+
+// Lint a set of files; returns per-file results plus the listing total vs budget.
+function lintSkills(files) {
+  const results = files.map((f) => lintSkillFile(fs.readFileSync(f, 'utf8'), { file: f }));
+  const listingChars = results.reduce((a, r) => a + r.listingChars, 0);
+  return { results, listingChars, budgetChars: LISTING_BUDGET_CHARS, overBudget: listingChars > LISTING_BUDGET_CHARS };
+}
+
+function isSkillMd(p) { return /[\\/]\.claude[\\/]skills[\\/][^\\/]+[\\/]SKILL\.md$/.test(String(p || '')); }
+
+function format(report, { relTo = REPO_ROOT } = {}) {
+  const out = [];
+  for (const r of report.results) {
+    const rel = path.relative(relTo, r.file).replace(/\\/g, '/');
+    for (const e of r.errors) out.push(`✗ ${rel}: ${e}`);
+    for (const w of r.warnings) out.push(`! ${rel}: ${w}`);
+  }
+  const errs = report.results.reduce((a, r) => a + r.errors.length, 0);
+  const warns = report.results.reduce((a, r) => a + r.warnings.length, 0);
+  out.push(`skill-lint: ${report.results.length} skill(s), ${errs} error(s), ${warns} warning(s); listing ${report.listingChars} chars (~${Math.round(report.listingChars / 4)} tokens) vs ~${report.budgetChars}-char budget${report.overBudget ? ' — OVER: entries get truncated and routing degrades' : ''}`);
+  return out.join('\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  if (argv.includes('--hook')) {
+    // PostToolUse: stdin carries {tool_input:{file_path}}. Only speak when a SKILL.md was touched.
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (d) => { raw += d; });
+    process.stdin.on('end', () => {
+      try {
+        const j = JSON.parse(raw || '{}');
+        const fp = (j.tool_input && (j.tool_input.file_path || j.tool_input.path)) || '';
+        if (!isSkillMd(fp) || !fs.existsSync(fp)) return;
+        const report = lintSkills([fp]);
+        const r = report.results[0];
+        if (r.errors.length || r.warnings.length) console.log('[skill-lint] ' + format(report).split('\n').slice(0, -1).join('\n[skill-lint] '));
+      } catch (_) { /* a hook never breaks the edit */ }
+      process.exitCode = 0;
+    });
+    return;
+  }
+  const files = argv.filter((a) => !a.startsWith('--'));
+  const report = lintSkills(files.length ? files.map((f) => path.resolve(f)) : listSkillFiles());
+  if (json) console.log(JSON.stringify(report, null, 1)); else console.log(format(report));
+  process.exitCode = report.results.some((r) => r.errors.length) ? 1 : 0;
+}
+
+module.exports = { lintFrontmatter, lintSkillFile, lintSkills, listSkillFiles, splitFrontmatter, isSkillMd, format, DESC_WARN_CHARS, DESC_HARD_CHARS, LISTING_BUDGET_CHARS };
+if (require.main === module) main();

package/scripts/gds/strand-watch.js

@@ -202,6 +202,9 @@ function line(r, { max = 3 } = {}) {
   }[worst.shape] || 'parked mid-pipeline';
   return `Stranded ship${r.strands.length === 1 ? '' : 's'}: ${shown.join('; ')}${more}. `
     + `Worst: ${lead} — ${worst.remedy}. `
+    // Name the skill, not just the diagnosis: 19 of the last 30 days' session logs mention a strand,
+    // and the next claim is refused REBASE_REQUIRED until one is landed or released (task 1003548).
+    + `Run /strand-fix ${worst.id} to walk it. `
     + 'A strand produces no signal of its own; this line is the only one.';
 }
 

package/src/module-api.js

@@ -45,7 +45,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // 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.526'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.528'; // 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/claude_materialize.mjs

@@ -49,6 +49,16 @@ t('bongosify: $CLAUDE_PROJECT_DIR + surrounding quotes are stripped', () => {
   assert.equal(m.bongosify('node "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"'), 'bongos exec scripts/gds/session-cost.js');
 });
 
+t('bongosify: the run-node.sh resolver form (task 1003548) collapses to the same bongos form', () => {
+  const wrap = 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/run-node.sh"';
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"`), 'bongos exec scripts/gds/session-cost.js');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/deploy-divergence.js" --line --timeout-ms 2500`), 'bongos exec scripts/gds/deploy-divergence.js --line --timeout-ms 2500');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/ship.js" 1885`), 'bongos ship 1885');
+  // …and a resolver call whose target is a .claude/hooks/*.js stays instance-local, like the bare-node form.
+  const hook = `${wrap} "$CLAUDE_PROJECT_DIR/.claude/hooks/secret-gate.js"`;
+  assert.equal(m.bongosify(hook), hook);
+});
+
 t('bongosify: a .claude/hooks/ reference is LEFT untouched (instance-local after materialize)', () => {
   const cmd = 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.js"';
   assert.equal(m.bongosify(cmd), cmd);

package/tests/edit_hints.mjs

@@ -0,0 +1,78 @@
+// tests/edit_hints.mjs — the PostToolUse edit-hints hook maps an edited path to the generator it makes
+// stale, reconciles the path shapes Windows hosts hand it, and stays silent on everything else
+// (task 1003548; evidence: a stale generated file in ~a quarter of the last 30 days' sessions).
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HOOK = path.join(ROOT, '.claude', 'hooks', 'edit-hints.js');
+if (!fs.existsSync(HOOK)) {
+  console.log('edit_hints: SKIP — .claude/hooks/ is not materialized in this checkout (package-excluded).');
+  process.exit(0);
+}
+const hints = require(HOOK);
+
+test('each generator input maps to its generator; unrelated paths map to nothing', () => {
+  const cases = [
+    ['modules/hall-ui/public/people.js', 'copy-inventory.js'],
+    ['modules/status-ui/public/index.html', 'copy-inventory.js'],
+    ['src/bongos/auth.js', 'gen-repo-map.js'],
+    ['modules/lifecycle/routes/claims.js', 'gen-api-docs.js'],
+    ['.claude/skills/dev/SKILL.md', 'gen-file-map.js'],
+    ['docs/session-logs/2026-09-03-x.md', 'gen-session-index.js'],
+    ['docs/adr/0236-something.md', 'fitness.js'],
+  ];
+  for (const [p, gen] of cases) {
+    const h = hints.generatorHint(p);
+    assert.ok(h && h.includes(gen), `${p} → expected ${gen}, got ${h}`);
+  }
+  for (const p of ['README.md', 'tests/foo.mjs', 'modules/hall-ui/CLAUDE.md', 'scripts/gds/ship.js']) {
+    assert.equal(hints.generatorHint(p), null, `${p} should be silent`);
+  }
+});
+
+test('rel() reconciles C:\\, C:/ and /c/ shapes between CLAUDE_PROJECT_DIR and file_path', () => {
+  const want = 'modules/hall-ui/public/people.js';
+  assert.equal(hints.rel('C:\\r\\repo\\modules\\hall-ui\\public\\people.js', 'C:\\r\\repo'), want);
+  assert.equal(hints.rel('C:\\r\\repo\\modules\\hall-ui\\public\\people.js', 'C:/r/repo'), want);
+  assert.equal(hints.rel('/c/r/repo/modules/hall-ui/public/people.js', 'C:\\r\\repo'), want);
+  assert.equal(hints.rel('c:/r/repo/modules/hall-ui/public/people.js', 'C:/r/repo/'), want);
+  assert.equal(hints.rel('/home/u/repo/modules/hall-ui/public/people.js', '/home/u/repo'), want);
+});
+
+test('run as a hook: prints one hint for a generator input, nothing for an unrelated file, exit 0 both times', () => {
+  const projectDir = ROOT;
+  const run = (relPath) => spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify({ tool_input: { file_path: path.join(projectDir, ...relPath.split('/')) } }),
+    encoding: 'utf8', timeout: 15000, env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir },
+  });
+  const a = run('modules/hall-ui/public/people.js');
+  assert.equal(a.status, 0, a.stderr);
+  assert.match(a.stdout, /copy-registry\.json is now stale/);
+  assert.match(a.stdout, /copy-inventory\.js/);
+  const b = run('README.md');
+  assert.equal(b.status, 0, b.stderr);
+  assert.equal(b.stdout.trim(), '');
+});
+
+test('run as a hook on a SKILL.md with a broken description: names the line and the fix', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'edit-hints-'));
+  const skill = path.join(tmp, '.claude', 'skills', 'demo', 'SKILL.md');
+  fs.mkdirSync(path.dirname(skill), { recursive: true });
+  fs.writeFileSync(skill, '---\nname: demo\ndescription: Do it: now\n---\nBody\n');
+  const r = spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify({ tool_input: { file_path: skill } }),
+    encoding: 'utf8', timeout: 15000, env: { ...process.env, CLAUDE_PROJECT_DIR: ROOT },
+  });
+  fs.rmSync(tmp, { recursive: true, force: true });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /\[skill-lint\] ✗ .*line 3/);
+  assert.match(r.stdout, /description: >-/);
+});

package/tests/git_merge_regen.mjs

@@ -64,7 +64,7 @@ const MARKERS = /^(<{7}|={7}|>{7})/m;
 }
 
 // ── helpers to build nested-CLAUDE.md fixtures from the real committed file ─────
-const NESTED = 'scripts/gds/CLAUDE.md';
+const NESTED = 'src/bongos/CLAUDE.md'; // scripts/gds left NESTED_DIRS in task 1003548
 const realNested = fs.readFileSync(path.join(repo, NESTED), 'utf8');
 assert.ok(realNested.includes(G.BEGIN) && realNested.includes(G.END), 'fixture file must carry the generated block markers');
 // Replace the INNER block text (keep the BEGIN/END marker lines intact).

package/tests/grader_root_outage.mjs

@@ -0,0 +1,109 @@
+// tests/grader_root_outage.mjs — a grader that could not START must say so, and it
+// must be able to start as root (task 1003574, goal 1000024).
+//
+// THE BUG THIS PINS. #943 added a 'unavailable' panel outcome for a total grader
+// outage, so a builder sees "grader unavailable" instead of a FAIL nobody produced.
+// It worked when every gating worker was an LLM subagent. Then the DETERMINISTIC
+// pseudo-workers (route-rank, permission-path) were appended to the panel — they
+// never spawn a subprocess, so an outage cannot touch them, and one of them passing
+// made `gating.every(isMissingSignal)` permanently false. The outage branch became
+// unreachable: a total subagent outage fell through to the securityLensErrored branch
+// and was recorded as `FAIL · 0/10` with zero issues and every rubric axis null.
+//
+// That shape is indistinguishable from a real rejection in a terminal, and it routes
+// a builder to /grade-recover Branch A — whose prescribed re-grade cannot clear an
+// outage that is deterministic. Observed end-to-end on task 1003280, whose ship was
+// blocked twice by a panel that never ran.
+//
+// Run:  node --test tests/grader_root_outage.mjs
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const grader = require(path.join(ROOT, 'modules', 'grading', 'grader.js'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+// An LLM worker whose subprocess died — no signal at all.
+const errored = (kind) => ({
+  kind, name: kind, specialty: 'x', verdict: 'error', scores: {}, issues: [],
+  notes_md: '', confidence: 0, model: 'claude-sonnet-5', run_ms: 10,
+  error: 'SUBAGENT_NONZERO_EXIT',
+});
+// The deterministic pseudo-worker, exactly as route-rank-check.js stamps it.
+const deterministicPass = (kind = 'route-rank') => ({
+  kind, name: kind, specialty: 'x', verdict: 'pass', scores: {}, issues: [],
+  notes_md: `${kind} pass`, confidence: 1, model: 'deterministic', run_ms: 0, error: null,
+});
+const llmPass = (kind) => ({
+  kind, name: kind, specialty: 'x', verdict: 'pass', scores: { code_quality: 8 }, issues: [],
+  notes_md: '', confidence: 0.8, model: 'claude-sonnet-5', run_ms: 10, error: null,
+});
+
+test('the exact task-1003280 shape: every subagent dead, route-rank passing → unavailable, not fail', () => {
+  const r = grader.aggregatePanel([
+    errored('narc'), errored('quality'), errored('hacker'), errored('efficiency'),
+    deterministicPass('route-rank'),
+  ]);
+  assert.equal(r.signals.panel_outcome, 'unavailable',
+    'a passing deterministic check is not evidence the panel ran');
+  assert.equal(r.passed, false, 'unavailable never auto-passes — it routes to manual-confirm');
+  assert.match(r.notes_md, /GRADER UNAVAILABLE/);
+  // The tell that made this so hard to read in a terminal: no findings at all.
+  assert.equal((r.issues || []).length, 0);
+});
+
+test('two deterministic pseudo-workers do not resurrect the fail either', () => {
+  const r = grader.aggregatePanel([
+    errored('narc'), errored('quality'), errored('hacker'), errored('efficiency'),
+    deterministicPass('route-rank'), deterministicPass('permission-path'),
+  ]);
+  assert.equal(r.signals.panel_outcome, 'unavailable');
+});
+
+test('a DETERMINISTIC FAIL still hard-blocks — the fix does not soften the gate', () => {
+  const detFail = { ...deterministicPass('route-rank'), verdict: 'fail',
+    issues: [{ severity: 'blocker', file: 'r.js', summary: 'ungated write route' }] };
+  const r = grader.aggregatePanel([
+    errored('narc'), errored('quality'), errored('hacker'), errored('efficiency'), detFail,
+  ]);
+  assert.equal(r.signals.panel_outcome, 'fail',
+    'gatingFail is the first branch and must still win over the outage branch');
+  assert.equal(r.passed, false);
+});
+
+test('a real security-lens outage with the rest of the panel alive still hard-blocks (#574 intact)', () => {
+  const r = grader.aggregatePanel([
+    llmPass('narc'), llmPass('quality'), errored('hacker'), llmPass('efficiency'),
+    deterministicPass('route-rank'),
+  ]);
+  assert.equal(r.signals.panel_outcome, 'fail', 'a missing Hacker among live workers is still a block');
+  assert.match(r.notes_md, /SECURITY LENS MISSING/);
+});
+
+test('a healthy panel is unaffected', () => {
+  const r = grader.aggregatePanel([
+    llmPass('narc'), llmPass('quality'), llmPass('hacker'), llmPass('efficiency'),
+    deterministicPass('route-rank'),
+  ]);
+  assert.equal(r.signals.panel_outcome, 'pass');
+  assert.equal(r.passed, true);
+});
+
+// ---- the spawn half -------------------------------------------------------
+
+test('the worker spawn picks a permission mode the CLI accepts as root', () => {
+  const src = read('modules', 'grading', 'grader-subagent.js');
+  // The refusal is euid-based, so the choice must be too.
+  assert.match(src, /process\.getuid\(\) === 0/);
+  assert.match(src, /isRoot \? 'acceptEdits' : 'bypassPermissions'/);
+  // The flag must be passed as the computed value, never the hardcoded wide one.
+  assert.match(src, /'--permission-mode', permissionMode/);
+  assert.doesNotMatch(src, /'--permission-mode', 'bypassPermissions'/);
+  // The tool list is what makes acceptEdits cost nothing: there are no edits.
+  assert.match(src, /'--tools', 'Read'/);
+});

package/tests/hooks_drain.mjs

@@ -20,7 +20,13 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const HOOKS = ['recall-hints', 'rank-change-greeting', 'conductor'].map((n) => path.join(ROOT, '.claude', 'hooks', `${n}.js`));
+const HOOKS = ['recall-hints', 'rank-change-greeting', 'conductor', 'pull-memory', 'edit-hints'].map((n) => path.join(ROOT, '.claude', 'hooks', `${n}.js`));
+// The SessionStart/SessionEnd scripts that did network work and then process.exit()ed — 59 recorded
+// UV_HANDLE_CLOSING aborts in three days (task 1003548). Same contract: exit 0 on their own, no abort.
+// session-digest requires `pg` at load (via db-kernel), so it can only be exercised where node_modules
+// is installed — the CI lane; a bare Windows worktree skips it rather than reporting a phantom fail.
+const hasPg = fs.existsSync(path.join(ROOT, 'node_modules', 'pg'));
+const SCRIPTS = ['fetch-sound-prefs', 'session-cost', ...(hasPg ? ['session-digest'] : [])].map((n) => path.join(ROOT, 'scripts', 'gds', `${n}.js`));
 
 if (!HOOKS.every((p) => fs.existsSync(p))) {
   console.log('hooks_drain: SKIP — .claude/hooks/ is not materialized in this checkout (package-excluded).');
@@ -42,7 +48,7 @@ const payload = JSON.stringify({ session_id: 's1', transcript_path: transcript,
 const env = { ...process.env, HOME, USERPROFILE: HOME, CLAUDE_PROJECT_DIR: ROOT };
 for (const k of Object.keys(env)) if (/_API_BASE$|^OTB_|^CLOUDBONGOS_|^GDS_|^PMS_/.test(k)) delete env[k];
 
-for (const hook of HOOKS) {
+for (const hook of [...HOOKS, ...SCRIPTS]) {
   t(`${path.basename(hook)} exits on its own with 0 and no libuv abort (x3)`, () => {
     for (let i = 0; i < 3; i++) {
       const r = spawnSync(process.execPath, [hook], { input: payload, encoding: 'utf8', timeout: 15000, env });

package/tests/repo_map.mjs

@@ -67,7 +67,7 @@ test('the generated repo map has the ranked global table and real signatures', (
 test('each nested CLAUDE.md carries a delimited generated block with signatures', () => {
   const BEGIN = '<!-- BEGIN GENERATED REPO-MAP';
   const END = '<!-- END GENERATED REPO-MAP -->';
-  for (const dir of ['src/bongos', 'src/bongos/routes', 'scripts/gds']) {
+  for (const dir of ['src/bongos', 'src/bongos/routes']) { // scripts/gds left NESTED_DIRS in task 1003548
     const doc = readFileSync(path.join(ROOT, dir, 'CLAUDE.md'), 'utf8');
     assert.ok(doc.includes(BEGIN), `${dir}/CLAUDE.md should have a generated-block start marker`);
     assert.ok(doc.includes(END), `${dir}/CLAUDE.md should have a generated-block end marker`);