session-orchestrator 5.3.0 → 5.5.0

package/scripts/autopilot.mjs

@@ -14,7 +14,10 @@
  *   --max-sessions=N            Max iterations (1..50, default 5).
  *   --max-hours=H               Max wall-clock hours (0.5..24.0, default 4.0).
  *   --confidence-threshold=0.X  Mode confidence gate (0.0..1.0, default 0.85).
- *   --max-tokens=N              Cumulative output-token budget (0..10000000, default 500000; 0 disables).
+ *   --max-tokens=N              Cumulative token budget (0..10000000, default 0 = off). Counts
+ *                               SUBAGENT output tokens only (sessions.jsonl total_token_output,
+ *                               else total_tokens — both subagent-only; coordinator tokens are
+ *                               not counted). One deep session measured ~450k.
  *   --dry-run                   Emit a single record without spawning sessions.
  *   --verbose                   Pipe child process stdio (instead of inherit).
  *
@@ -33,7 +36,7 @@
  *   "/autopilot Loop Command (Phase C)" (#277/#271; archived in the private Meta-Vault)
  */
 
-import { readFileSync, existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { spawnSync, spawn } from 'node:child_process';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -49,7 +52,7 @@ import { selectMode } from './lib/mode-selector.mjs';
 import { probe, evaluate, DEFAULT_RESOURCE_THRESHOLDS } from './lib/resource-probe.mjs';
 import { detectPeers } from './lib/session-registry.mjs';
 import { normalizeSession } from './lib/session-schema.mjs';
-import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
+import { isBackfillStub, readCanonicalSessions } from './lib/sessions-canonical.mjs';
 
 // ---------------------------------------------------------------------------
 // CLI-level flag extraction
@@ -94,10 +97,7 @@ const { maxSessions, maxHours, confidenceThreshold, maxTokens, dryRun } = parseF
  */
 function loadConfig() {
   try {
-    const scriptPath = resolve(
-      new URL('.', import.meta.url).pathname,
-      'parse-config.mjs'
-    );
+    const scriptPath = fileURLToPath(new URL('parse-config.mjs', import.meta.url));
     const result = spawnSync(
       process.execPath,
       [scriptPath],
@@ -185,50 +185,49 @@ const branch = detectBranch();
 const SESSIONS_JSONL_PATH = resolve('.orchestrator/metrics/sessions.jsonl');
 
 /**
- * Set of the DISTINCT session identities currently recorded in sessions.jsonl.
- * Empty set when the file is missing or unreadable.
- *
- * Identities, not lines (#1167): the ledger is append-only, so one physical
- * session can occupy two lines (an abandoned stub plus the authoritative
- * record that supersedes it, or the systemic double-stub pair). The
- * pre/post comparison below asks "did the session I just spawned record
- * itself?", and a raw line count answers that question wrong in BOTH
- * directions — a duplicate pair looks like two sessions, while a supersede
- * append (+1 line, −1 stub) leaves a canonical COUNT unchanged. Comparing the
- * id SETS is immune to both.
+ * Read the child's canonical record by its raw harness UUID, independent of
+ * semantic session IDs and peer append order. Zero or multiple matches throw;
+ * only the unique record supplies normalized fields and finite token usage.
  *
- * @returns {Set<string>}
+ * A unique record that is a BACKFILL STUB throws too (#1457 F2): a stub is a
+ * placeholder some backfill wrote because the child never closed — no waves,
+ * agents or token totals. Its usage is UNKNOWN, not 0, and its empty
+ * agent_summary/effectiveness would blind the post-session kill-switches as
+ * well, so it fails closed like the zero-match case above: the loop records
+ * kill_switch=failed-wave with a detail naming the stub, instead of counting a
+ * healthy 0-token iteration that silently undercounts --max-tokens.
+ * @returns {{session_id: string, agent_summary?: object, effectiveness?: object,
+ *   usage?: {output_tokens?: number, total_tokens?: number}}}
  */
-function readSessionIds() {
-  if (!existsSync(SESSIONS_JSONL_PATH)) return new Set();
-  const ids = new Set();
-  for (const rec of readCanonicalSessions({ filePath: SESSIONS_JSONL_PATH })) {
-    if (typeof rec.session_id === 'string' && rec.session_id.length > 0) {
-      ids.add(rec.session_id);
-    }
+function readOwnSession(childSessionId) {
+  const own = readCanonicalSessions({ filePath: SESSIONS_JSONL_PATH }).filter((r) => r.raw_session_id === childSessionId);
+  if (own.length === 0) {
+    throw new Error(
+      `no session record carries raw_session_id=${childSessionId} (the child wrote none, or none stamped ` +
+        'with its raw id) — refusing to fall back to the ledger tail (#1457)'
+    );
   }
-  return ids;
-}
-
-/**
- * Read the last non-empty line from sessions.jsonl, parse it, run it through
- * normalizeSession, and project to the sessionRunner return shape.
- *
- * @returns {{session_id: string, agent_summary?: object, effectiveness?: object}}
- */
-function readTailSession() {
-  const raw = readFileSync(SESSIONS_JSONL_PATH, 'utf8');
-  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
-  if (lines.length === 0) {
-    throw new Error('sessions.jsonl is empty after session completed');
+  if (own.length > 1) {
+    throw new Error(`ambiguous: ${own.length} canonical records carry raw_session_id=${childSessionId} (#1457)`);
+  }
+  if (isBackfillStub(own[0])) {
+    throw new Error(
+      `the only record with raw_session_id=${childSessionId} is a backfill stub ` +
+        `(_backfill_source=${own[0]._backfill_source}, no waves/agents/token totals) — token usage unknown, ` +
+        'refusing to count it as a 0-token iteration (#1457 F2)'
+    );
   }
-  const parsed = JSON.parse(lines[lines.length - 1]);
-  const normalized = normalizeSession(parsed);
-  return {
+  const normalized = normalizeSession(own[0]);
+  const result = {
     session_id: normalized.session_id,
     agent_summary: normalized.agent_summary,
     effectiveness: normalized.effectiveness,
   };
+  const usage = {};
+  if (Number.isFinite(normalized.total_token_output)) usage.output_tokens = normalized.total_token_output;
+  if (Number.isFinite(normalized.total_tokens)) usage.total_tokens = normalized.total_tokens;
+  if (Object.keys(usage).length > 0) result.usage = usage;
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -266,13 +265,16 @@ async function modeSelector() {
 
 /**
  * sessionRunner — spawns `claude` with the recommended mode and awaits exit.
- * Verifies that a new sessions.jsonl record was appended before returning.
+ * Sets a fresh raw harness UUID so a peer's later ledger append is never read
+ * as the child's record (emit-session stamps that UUID as `raw_session_id`).
+ * After exit 0, returns its unique canonical record; zero or multiple matches
+ * throw into the loop's failed-wave channel.
  *
  * @param {{mode: string, autopilotRunId: string}} args
  * @returns {Promise<{session_id: string, agent_summary?: object, effectiveness?: object}>}
  */
 async function sessionRunner({ mode, autopilotRunId }) {
-  const preIds = readSessionIds();
+  const childSessionId = randomUUID();
 
   await new Promise((res, rej) => {
     const childStdio = hasVerbose
@@ -286,7 +288,7 @@ async function sessionRunner({ mode, autopilotRunId }) {
     // resolves, and only when the plugin that defines it is on `--plugin-dir`.
     const child = spawn(
       'claude',
-      ['-p', `/session-orchestrator:session ${mode}`, '--plugin-dir', PLUGIN_ROOT],
+      ['-p', `/session-orchestrator:session ${mode}`, '--plugin-dir', PLUGIN_ROOT, '--session-id', childSessionId],
       {
         env: { ...process.env, AUTOPILOT_RUN_ID: autopilotRunId },
         stdio: childStdio,
@@ -309,13 +311,7 @@ async function sessionRunner({ mode, autopilotRunId }) {
     });
   });
 
-  const postIds = readSessionIds();
-  const appeared = [...postIds].some((id) => !preIds.has(id));
-  if (!appeared) {
-    throw new Error('no session record appended');
-  }
-
-  return readTailSession();
+  return readOwnSession(childSessionId);
 }
 
 /**
@@ -404,12 +400,19 @@ async function main() {
   });
 
   const sessionIds = state.sessions.join(', ') || '(none)';
+  // #1498: `tokens_unknown_sessions` (#1487 Pkt 4) reached state, return value
+  // and autopilot.jsonl, but no report showed it — so the token total read as
+  // the whole sum. Printed only when non-zero: then the total is a lower bound.
+  const unknownTokens = state.tokens_unknown_sessions > 0
+    ? ` tokens_unknown_sessions=${state.tokens_unknown_sessions} (the token total is a lower bound)`
+    : '';
   const summary =
     `${state.autopilot_run_id} ` +
     `kill_switch=${state.kill_switch ?? 'none'} ` +
     `iterations=${state.iterations_completed} ` +
     `sessions=[${sessionIds}] ` +
-    `duration=${state.duration_seconds}s`;
+    `duration=${state.duration_seconds}s ` +
+    `tokens=${state.total_tokens_used}${unknownTokens}`;
   process.stdout.write(summary + '\n');
 
   if (state.kill_switch === KILL_SWITCHES.FAILED_WAVE) {

package/scripts/backfill-abandoned-sessions.mjs

@@ -43,6 +43,7 @@ import { parseArgs } from 'node:util';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
 import { SCAN_CHUNK_BYTES, emitEvent, listEventSourcesNewestFirst } from './lib/events.mjs';
+import { ARCHIVE_DIR_NAME, ROTATION_EVENT } from './lib/events-schema.mjs';
 import { getProjectDir } from './lib/platform.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { isLockLive, readLock } from './lib/session-lock.mjs';
@@ -52,6 +53,15 @@ const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
 const SESSION_ENDED = 'orchestrator.session.ended';
 
+/**
+ * Events-ledger window for the #1401 census (`scripts/lib/events-retention-banner.mjs`):
+ * `null` — {@link planSessions} takes every `session.started` ever written as a
+ * candidate, so no day count bounds it (`DEFAULT_TTL_HOURS` is a minimum AGE,
+ * not a window). A pruned history yields fewer candidates; the run summary says
+ * so as `history_gaps` (#1498).
+ */
+export const REQUIRED_EVENTS_WINDOW_DAYS = null;
+
 /**
  * Default cap on how many candidates may reach the (expensive) shared core in a
  * single run. Only the SessionStart path passes a limit; the CLI stays uncapped.
@@ -59,6 +69,25 @@ const SESSION_ENDED = 'orchestrator.session.ended';
  */
 export const SESSION_START_LIMIT = 25;
 
+/**
+ * Total wall-clock budget, per SessionStart run, for scanning the ROTATED
+ * ledger on behalf of candidates whose events left the active file (#1498).
+ * ONE deadline shared by every candidate; a candidate it leaves unread is
+ * `skipped-history-unread` and retried by the next start — recorded ones drop
+ * out through the sessions.jsonl pre-filter, so the backlog drains.
+ *
+ * Named ceiling (BV-004): at ≈0.55-0.8 ms per MB per candidate (measured
+ * 2026-10-02, see `gatherSessionEvents` in `session-close-backfill.mjs`) a full
+ * default ledger (6 × 10 MB) fits ~10-15 scans per start. Measured the same
+ * day over 58 MB with 25 archived candidates (dry run, load ~5): unbudgeted
+ * 1.41 s; budget 0 — planning and active-file reads only — 0.55 s; budget 500
+ * 0.83-0.84 s, 10 candidates answered and 15 deferred. A single scan longer
+ * than the budget — a ledger past ~600 MB — never completes here; the CLI path
+ * is unbudgeted and still records it. Revisit if `skipped-history-unread`
+ * appears on more than a few consecutive starts of one repo.
+ */
+export const SESSION_START_ARCHIVE_SCAN_BUDGET_MS = 500;
+
 /**
  * Read a JSONL file into parsed objects; MISSING (ENOENT) → `[]` silently,
  * UNREADABLE (EACCES/EISDIR/…) → `[]` with a stderr WARN (#1188); malformed
@@ -126,6 +155,23 @@ function readJsonl(filePath) {
  * @returns {Array<{ sessionId: string, semanticSessionId: string|null }>}
  */
 export function planSessions({ repoRoot }) {
+  return planWithGaps({ repoRoot }).plan;
+}
+
+/**
+ * {@link planSessions} plus the count of rotation tombstones whose archive is
+ * not one of the sources read (#1498). Pruned history used to shrink the plan
+ * silently; non-zero `historyGaps` says the candidate count is a floor.
+ *
+ * The check is `readEventsWithRotations` rule 1 (`scripts/lib/events.mjs`):
+ * resolved by BASENAME against this ledger's own `_archive/` (#1411), and a
+ * file that exists but is not a source (renamed out of `ARCHIVE_NAME_RE`)
+ * counts as a gap too — existence is not reading (#1423).
+ *
+ * @param {{ repoRoot: string }} args
+ * @returns {{ plan: Array<{ sessionId: string, semanticSessionId: string|null }>, historyGaps: number }}
+ */
+function planWithGaps({ repoRoot }) {
   const eventsPath = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
 
   // Two independent UUID -> semantic bridges (#1167). `lock.acquired` is the
@@ -150,9 +196,17 @@ export function planSessions({ repoRoot }) {
   // (`hooks/on-session-start.mjs` → `backfillOnSessionStart`). Reversing the
   // newest-first source list keeps first-seen order chronological, exactly as
   // the single-file read produced it.
-  for (const source of [...listEventSourcesNewestFirst({ filePath: eventsPath })].reverse()) {
+  const sources = listEventSourcesNewestFirst({ filePath: eventsPath });
+  const read = new Set(sources.map((s) => s.path));
+  const archiveDir = path.join(path.dirname(eventsPath), ARCHIVE_DIR_NAME);
+  let historyGaps = 0;
+  for (const source of [...sources].reverse()) {
     forEachJsonlRecord(source.path, (ev) => {
       if (!ev || typeof ev !== 'object') return;
+      if (ev.event === ROTATION_EVENT && typeof ev.archived_as === 'string' && ev.archived_as.length > 0
+        && !read.has(path.join(archiveDir, path.basename(ev.archived_as)))) {
+        historyGaps += 1;
+      }
       if (typeof ev.session_id === 'string' && typeof ev.semantic_session_id === 'string') {
         if (ev.event === LOCK_ACQUIRED) semanticFromLock.set(ev.session_id, ev.semantic_session_id);
         else if (ev.event === SESSION_ENDED) {
@@ -181,7 +235,7 @@ export function planSessions({ repoRoot }) {
       || (semanticSessionId !== null && runningIds.has(semanticSessionId))) continue;
     plan.push({ sessionId, semanticSessionId });
   }
-  return plan;
+  return { plan, historyGaps };
 }
 
 /**
@@ -365,6 +419,10 @@ function cheapRecordId({ sessionId, semanticSessionId }) {
  *   those ancient candidates exhaust the whole budget before the run ever
  *   reaches the genuinely-abandoned recent ones. Measured on a copy of this
  *   repo's live store: first-seen order → backfilled 0, truncated true.
+ * @param {number|null} [args.archiveScanBudgetMs=null]
+ *   #1498 — total budget for rotated-ledger scans across the whole run, turned
+ *   into ONE deadline before the first candidate. Candidates it leaves unread
+ *   count as `skipped.skipped-history-unread`. `null` (CLI default) = unbounded.
  * @returns {Promise<object>} aggregate summary
  */
 export async function runMigration({
@@ -373,13 +431,17 @@ export async function runMigration({
   assumeDeadBeforeMs = null,
   limit = null,
   newestFirst = false,
+  archiveScanBudgetMs = null,
 }) {
-  const planned = planSessions({ repoRoot });
+  const { plan: planned, historyGaps } = planWithGaps({ repoRoot });
   const plan = newestFirst ? [...planned].reverse() : planned;
   const summary = {
     repoRoot,
     mode: apply ? 'apply' : 'dry-run',
     total: plan.length,
+    // #1498: rotated archives the ledger names but no longer holds. Non-zero ⇒
+    // sessions they recorded are not candidates and `total` is a floor.
+    history_gaps: historyGaps,
     backfilled: 0,
     would_backfill: 0,
     dead_by_age: 0,
@@ -397,6 +459,10 @@ export async function runMigration({
   // here so the dry-run total matches what --apply actually writes.
   const projected = new Set();
 
+  const archiveScanDeadlineMs = Number.isFinite(archiveScanBudgetMs)
+    ? Date.now() + archiveScanBudgetMs
+    : null;
+
   for (const item of plan) {
     // -- Cheap pre-filter: already recorded → skip WITHOUT entering the core --
     const known = cheapRecordId(item);
@@ -423,6 +489,7 @@ export async function runMigration({
       dryRun: !apply,
       relaxDeadByAge: true,
       assumeDeadBeforeMs,
+      archiveScanDeadlineMs,
     });
     switch (res.action) {
       case 'backfilled':
@@ -529,16 +596,21 @@ async function emitBackfillCompleted(repoRoot, item, res) {
  * @param {object} args
  * @param {string} args.repoRoot
  * @param {number|null} [args.limit=SESSION_START_LIMIT]
+ * @param {number|null} [args.archiveScanBudgetMs=SESSION_START_ARCHIVE_SCAN_BUDGET_MS]
  * @returns {Promise<object|null>} the summary, or null when disabled/failed
  */
-export async function backfillOnSessionStart({ repoRoot, limit = SESSION_START_LIMIT } = {}) {
+export async function backfillOnSessionStart({
+  repoRoot,
+  limit = SESSION_START_LIMIT,
+  archiveScanBudgetMs = SESSION_START_ARCHIVE_SCAN_BUDGET_MS,
+} = {}) {
   try {
     // Escape hatch for operators who never want ledger writes at session start.
     if (process.env.SO_DISABLE_STARTUP_BACKFILL === '1') return null;
     if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
     // newestFirst is mandatory here — see runMigration's param docs for the
     // measured failure (budget burned on ancient already-recorded candidates).
-    const summary = await runMigration({ repoRoot, apply: true, limit, newestFirst: true });
+    const summary = await runMigration({ repoRoot, apply: true, limit, newestFirst: true, archiveScanBudgetMs });
     // The telemetry flush rides the SAME start-time trigger, for the same reason
     // the backfill does — see flushTelemetryOnSessionStart.
     await flushTelemetryOnSessionStart(repoRoot);
@@ -596,6 +668,9 @@ function renderHuman(summary) {
   lines.push(`Backfill abandoned sessions — ${summary.mode}`);
   lines.push(`  repo:            ${summary.repoRoot}`);
   lines.push(`  sessions seen:   ${summary.total}`);
+  if (summary.history_gaps > 0) {
+    lines.push(`  history gaps:    ${summary.history_gaps} rotated archive(s) no longer readable — sessions seen is a floor`);
+  }
   if (summary.mode === 'apply') {
     lines.push(`  backfilled:      ${summary.backfilled}`);
   } else {
@@ -653,7 +728,7 @@ async function main() {
 
   // --apply is an explicit opt-in; absent it (or with --dry-run) we never write.
   const apply = values.apply === true && values['dry-run'] !== true;
-  const repoRoot = values['repo-root'] || getProjectDir();
+  const repoRoot = path.resolve(values['repo-root'] || getProjectDir());
 
   let assumeDeadBeforeMs = null;
   if (typeof values['assume-dead-before'] === 'string' && values['assume-dead-before'].length > 0) {

package/scripts/backfill-learnings-from-vault.mjs

@@ -43,8 +43,9 @@
  * a record that never left.
  *
  * Idempotence: dry-run is pure (reads only). `--apply` re-checks store+archive
- * membership per record immediately before appending, so a second `--apply`
- * appends nothing and a later dry-run reports 0 orphans.
+ * membership and appends inside ONE store-lock section (`withLearningsLock`),
+ * so a second `--apply` — sequential or concurrent — appends nothing and a
+ * later dry-run reports 0 orphans.
  *
  * NOTE on discovery: every file here is read through `node:fs`, never grep — a
  * single NUL byte makes a tracked file invisible to grep (silent skip, exit 1,
@@ -70,7 +71,7 @@ import { parseSessionConfig } from './lib/config.mjs';
 import { subjectToSlug, parseFrontmatter } from './lib/vault-mirror/utils.mjs';
 import { kebab } from './lib/learnings/kebab.mjs';
 import { validateLearning } from './lib/learnings/schema.mjs';
-import { appendLearning, isBackupOf } from './lib/learnings/io.mjs';
+import { appendLearning, isBackupOf, withLearningsLock } from './lib/learnings/io.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_RULES_DIR = '.claude/rules';
@@ -907,28 +908,54 @@ export async function main(argv = [], deps = {}) {
     });
   }
 
-  // ── Apply (append-only, re-checked) ──────────────────────────────────────
+  // ── Apply (append-only, re-checked under the store lock) ─────────────────
   let applied = 0;
   let skippedAlreadyPresent = 0;
   if (apply) {
-    for (const r of records) {
-      if (r.status !== 'orphan' || !r.restorable || !r.record) continue;
-      // Re-check membership at apply time — this is what makes a second
-      // --apply a no-op rather than a duplicate append.
-      if (idsInStore(storeAbs).has(r.learning_id) || idsInStore(archiveAbs).has(r.learning_id)) {
-        skippedAlreadyPresent += 1;
-        r.applied = false;
-        continue;
-      }
-      try {
-        await appendLearning(storeAbs, r.record);
-        applied += 1;
-        r.applied = true;
-      } catch (err) {
-        r.applied = false;
-        r.apply_error = err.message;
-        process.stderr.write(`backfill-learnings-from-vault: append failed for ${r.learning_id}: ${err.message}\n`);
-      }
+    const candidates = records.filter((r) => r.status === 'orphan' && r.restorable && r.record);
+    const failApply = (r, err) => {
+      r.applied = false;
+      r.apply_error = err.message;
+      process.stderr.write(`backfill-learnings-from-vault: append failed for ${r.learning_id}: ${err.message}\n`);
+    };
+    try {
+      // The membership re-check and the append are ONE critical section
+      // (#1487 item 12): checked outside the lock, two concurrent --apply runs
+      // — or one racing a session-end append — both saw "absent" and both
+      // appended. One section for the whole loop, not one per record: a single
+      // acquisition and a single read of store + archive instead of N of each.
+      // Hold time is linear in N small appends — fine for the tens of orphans a
+      // backfill restores; revisit (per-record sections) if a run ever holds
+      // the lock near the 10 s other writers wait. Archive movers (sweep/prune)
+      // also write under this lock, so the archive read is consistent too.
+      // appendLearning() re-enters the held lock (reentrant per async call
+      // chain, io.mjs).
+      await withLearningsLock(storeAbs, async () => {
+        const present = new Set([...idsInStore(storeAbs), ...idsInStore(archiveAbs)]);
+        for (const r of candidates) {
+          // This is what makes a second --apply a no-op rather than a
+          // duplicate append; `present.add` below covers two rules naming one id.
+          if (present.has(r.learning_id)) {
+            skippedAlreadyPresent += 1;
+            r.applied = false;
+            continue;
+          }
+          try {
+            await appendLearning(storeAbs, r.record);
+            applied += 1;
+            r.applied = true;
+            present.add(r.learning_id);
+          } catch (err) {
+            failApply(r, err);
+          }
+        }
+      });
+    } catch (err) {
+      // Lock not acquired (LearningsLockError), its directory not creatable, or
+      // a store read failed inside the section: no candidate still unhandled
+      // was written. Surface it per record, like any other append failure,
+      // instead of reporting a silent success.
+      for (const r of candidates) if (r.applied === undefined) failApply(r, err);
     }
   }
 

package/scripts/baseline-archetypes.mjs

@@ -10,7 +10,7 @@ export async function main(argv = process.argv.slice(2)) {
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
     if (arg === '--help' || arg === '-h') {
-      process.stdout.write('Usage: node scripts/baseline-archetypes.mjs [--repo PATH] [--archetype ID]\nOffline, read-only JSON lookup. Exit 0: public/private; exit 2: invalid configuration or contract.\n');
+      process.stdout.write('Usage: node scripts/baseline-archetypes.mjs [--repo PATH] [--archetype ID]\nOffline, read-only JSON lookup. Exit 0: public/private; exit 2: invalid configuration or contract.\nExit 2 reason producer-missing: the baseline directory exists but has no scripts/archetype-manifest.mjs exporter.\n');
       return 0;
     }
     if (!['--repo', '--archetype'].includes(arg) || !argv[index + 1] || argv[index + 1].startsWith('--')) {

package/scripts/check-package-manager.mjs

@@ -25,6 +25,11 @@
 //            (warn locally; upgraded to a hard failure under CI)
 //        c1  pnpm-lock.yaml must NOT be tracked in git
 //        c2  package-lock.json MUST be tracked in git
+//   3. Husky activation (#1458, advisory only — never affects `ok`/exit code):
+//        h1  `.husky/` exists but git core.hooksPath is not `.husky/_` — the
+//            `prepare: husky` script never ran because ignore-scripts=true,
+//            so commit-msg/pre-commit/pre-push are inactive. Warns locally
+//            and recommends `npx husky`; silent under CI.
 //
 // SCOPE GUARD:
 //   This script only guards the REPOSITORY ROOT package.json. If invoked
@@ -64,8 +69,8 @@
 // on any dependency install).
 
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { dirname, isAbsolute, join, posix, resolve } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { isMainModule } from './lib/is-main-module.mjs';
 
@@ -266,11 +271,53 @@ export function parseCiEnv(value) {
   return !['', '0', 'false', 'no'].includes(normalized);
 }
 
+/** One-line stderr WARN for an inactive Husky install (#1458). */
+export const HUSKY_INACTIVE_WARNING =
+  '⚠ check-package-manager: git core.hooksPath is not set to .husky/_ — Husky hooks (commit-msg, pre-commit, pre-push) are INACTIVE in this clone because .npmrc ignore-scripts=true skips the prepare script (#1458). Run: npx husky';
+
+/**
+ * Advisory check (#1458): `.npmrc` `ignore-scripts=true` (SEC-020) means the
+ * `prepare: husky` script never runs on `npm ci`, so a fresh clone has no
+ * `core.hooksPath` and every Husky hook is silently inactive. This only
+ * REPORTS the state — it never runs `npx husky`, never writes git config and
+ * never affects the guard's `ok`/exit code. Silent under CI.
+ * @param {string} repoRoot
+ * @param {{ env?: NodeJS.ProcessEnv, ci?: boolean }} [opts] — `env` is also
+ *   passed to the git subprocess (lets tests isolate from global git config).
+ * @returns {{ hooksPath: string, active: boolean, skipped: 'ci'|'no-husky-dir'|null }}
+ */
+export function checkHuskyHooksPath(repoRoot, { env = process.env, ci } = {}) {
+  if (ci ?? parseCiEnv(env.CI)) return { hooksPath: '', active: false, skipped: 'ci' };
+  if (!existsSync(join(repoRoot, '.husky'))) {
+    return { hooksPath: '', active: false, skipped: 'no-husky-dir' };
+  }
+
+  let hooksPath;
+  try {
+    hooksPath = execFileSync('git', ['-C', repoRoot, 'config', '--get', 'core.hooksPath'], {
+      encoding: 'utf8',
+      env,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    // Non-zero exit (key unset) or git unavailable — treat as unset.
+    hooksPath = '';
+  }
+
+  const norm = hooksPath.replace(/\\/g, '/').replace(/\/+$/, '');
+  const active =
+    norm !== '' &&
+    (isAbsolute(hooksPath) ? norm.endsWith('/.husky/_') : posix.normalize(norm) === '.husky/_');
+
+  return { hooksPath, active, skipped: null };
+}
+
 /**
  * Runs the full guard and returns a plain-object result. Pure(ish) — the
  * only side effects are read-only fs/git calls. Never throws or exits.
- * @param {{ cwd?: string, ci?: boolean, allowMissingNodeModules?: boolean, repoRoot?: string }} [opts]
- * @returns {{ ok: boolean, ci: boolean, skipped: boolean, repoRoot: string, findings: Array<{code: string, severity: string, effectiveSeverity: string, message: string}> }}
+ * `hooks` carries the advisory Husky check (#1458); it never affects `ok`.
+ * @param {{ cwd?: string, ci?: boolean, allowMissingNodeModules?: boolean, repoRoot?: string, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ ok: boolean, ci: boolean, skipped: boolean, repoRoot: string, findings: Array<{code: string, severity: string, effectiveSeverity: string, message: string}>, hooks?: { hooksPath: string, active: boolean, skipped: 'ci'|'no-husky-dir'|null } }}
  */
 export function runPackageManagerGuard(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
@@ -302,7 +349,9 @@ export function runPackageManagerGuard(opts = {}) {
 
   const ok = !findings.some((f) => f.effectiveSeverity === 'error');
 
-  return { ok, ci, skipped: false, repoRoot, findings };
+  const hooks = checkHuskyHooksPath(repoRoot, { env: opts.env ?? process.env, ci });
+
+  return { ok, ci, skipped: false, repoRoot, findings, hooks };
 }
 
 // ---------------------------------------------------------------------------
@@ -332,6 +381,9 @@ CHECKS
         (warn locally; upgraded to a hard failure under CI, fail-closed)
     c1  pnpm-lock.yaml must NOT be tracked in git
     c2  package-lock.json MUST be tracked in git
+  Husky activation (advisory, never changes the exit code; silent under CI):
+    h1  .husky/ exists but git core.hooksPath is not .husky/_ (#1458) —
+        run \`npx husky\` once (ignore-scripts=true skips \`prepare\`)
 
 OPTIONS
   --allow-missing-node-modules  Document that node_modules may not exist yet
@@ -412,6 +464,11 @@ if (isMain) {
 
   const result = runPackageManagerGuard({ allowMissingNodeModules: opts.allowMissingNodeModules });
 
+  // Advisory only (#1458) — never changes the exit code.
+  if (result.hooks && !result.hooks.active && result.hooks.skipped === null) {
+    console.error(HUSKY_INACTIVE_WARNING);
+  }
+
   if (opts.json) {
     console.log(JSON.stringify(result));
     process.exit(result.ok ? 0 : 1);

package/scripts/codex-install.mjs

@@ -93,6 +93,9 @@ function runCodex(args) {
   const result = spawnSync('codex', args, {
     encoding: 'utf8',
     timeout: CODEX_COMMAND_TIMEOUT_MS,
+    // 'codex plugin list --available --json' exceeds the 1 MiB default once a
+    // few marketplaces are registered (measured 2026-09-22: 2.19 MB → ENOBUFS).
+    maxBuffer: 64 * 1024 * 1024,
   });
 
   if (result.error) {