session-orchestrator 5.2.0 → 5.4.0

package/scripts/autopilot.mjs

@@ -14,6 +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 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).
  *
@@ -32,9 +36,10 @@
  *   "/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';
 
 import {
   runLoop,
@@ -47,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
@@ -55,6 +60,14 @@ import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
 
 const argv = process.argv.slice(2);
 
+/**
+ * Plugin root, resolved from THIS file's own location (`<root>/scripts/autopilot.mjs`
+ * → `<root>`) and never from an env var. The driver is spawned unattended from an
+ * arbitrary cwd, so `--plugin-dir` must name the plugin that owns this very file;
+ * an env-var read would point wherever the operator's shell last happened to point.
+ */
+const PLUGIN_ROOT = resolve(fileURLToPath(new URL('.', import.meta.url)), '..');
+
 const hasHeadless = argv.includes('--headless');
 const hasVerbose = argv.includes('--verbose');
 
@@ -69,7 +82,7 @@ const flagsForParse = argv.filter(
   (a) => a !== '--headless' && a !== '--verbose'
 );
 
-const { maxSessions, maxHours, confidenceThreshold, dryRun } = parseFlags(flagsForParse);
+const { maxSessions, maxHours, confidenceThreshold, maxTokens, dryRun } = parseFlags(flagsForParse);
 
 // ---------------------------------------------------------------------------
 // Session Config (parsed once, shared by thresholds + decay readers)
@@ -84,10 +97,7 @@ const { maxSessions, maxHours, confidenceThreshold, dryRun } = parseFlags(flagsF
  */
 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],
@@ -175,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.
+ * 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.
  *
- * 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.
- *
- * @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)`);
   }
-  const parsed = JSON.parse(lines[lines.length - 1]);
-  const normalized = normalizeSession(parsed);
-  return {
+  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 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;
 }
 
 // ---------------------------------------------------------------------------
@@ -256,22 +265,30 @@ 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
       ? ['ignore', 'pipe', 'pipe']
       : ['ignore', 'inherit', 'inherit'];
 
+    // `session` is a RESERVED terminal-only built-in name under `claude -p`: the
+    // bare `/session <mode>` form answers "/session isn't available in this
+    // environment." and the child exits having done nothing (measured 2026-09-16,
+    // claude 2.1.273 — `commands/session.md` § Headless). Only the namespaced form
+    // resolves, and only when the plugin that defines it is on `--plugin-dir`.
     const child = spawn(
       'claude',
-      ['-p', `/session ${mode}`],
+      ['-p', `/session-orchestrator:session ${mode}`, '--plugin-dir', PLUGIN_ROOT, '--session-id', childSessionId],
       {
         env: { ...process.env, AUTOPILOT_RUN_ID: autopilotRunId },
         stdio: childStdio,
@@ -294,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);
 }
 
 /**
@@ -372,12 +383,18 @@ async function main() {
     maxSessions,
     maxHours,
     confidenceThreshold,
+    maxTokens,
     dryRun,
     modeSelector,
     sessionRunner,
     resourceEvaluator,
     peerCounter,
     abortSignal: controller.signal,
+    // STALL_TIMEOUT progress marker. `autopilot.jsonl` is written ONCE per
+    // invocation (after the loop), so its mtime belongs to the PREVIOUS run and
+    // fired the kill-switch after iteration 1; the session.lock heartbeat is
+    // refreshed while a session is alive. See stall-sampler.mjs § PRECEDENCE.
+    sessionLockPath: resolve('.orchestrator/session.lock'),
     runId: autopilotRunId,
     branch: branch ?? undefined,
   });

package/scripts/backfill-abandoned-sessions.mjs

@@ -2,7 +2,8 @@
 /**
  * backfill-abandoned-sessions.mjs — one-time historical migration CLI (#724 C1).
  *
- * Scans `.orchestrator/metrics/events.jsonl` for every distinct
+ * Scans `.orchestrator/metrics/events.jsonl` — and every rotated archive
+ * beside it (#1414) — for every distinct
  * `orchestrator.session.started` UUID that has no counterpart in
  * `.orchestrator/metrics/sessions.jsonl`, bridges each to its semantic id via
  * `orchestrator.session.lock.acquired` where available, and synthesizes a
@@ -41,7 +42,7 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
-import { emitEvent } from './lib/events.mjs';
+import { SCAN_CHUNK_BYTES, emitEvent, listEventSourcesNewestFirst } from './lib/events.mjs';
 import { getProjectDir } from './lib/platform.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { isLockLive, readLock } from './lib/session-lock.mjs';
@@ -125,7 +126,7 @@ function readJsonl(filePath) {
  * @returns {Array<{ sessionId: string, semanticSessionId: string|null }>}
  */
 export function planSessions({ repoRoot }) {
-  const events = readJsonl(path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl'));
+  const eventsPath = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
 
   // Two independent UUID -> semantic bridges (#1167). `lock.acquired` is the
   // original one, but a session that LOST the lock-acquire race never emits it;
@@ -137,29 +138,130 @@ export function planSessions({ repoRoot }) {
   // lock.acquired keeps precedence — it is the older, mode-carrying attestation.
   const semanticFromLock = new Map();
   const semanticFromEnded = new Map();
-  for (const ev of events) {
-    if (typeof ev.session_id !== 'string' || typeof ev.semantic_session_id !== 'string') continue;
-    if (ev.event === LOCK_ACQUIRED) semanticFromLock.set(ev.session_id, ev.semantic_session_id);
-    else if (ev.event === SESSION_ENDED) semanticFromEnded.set(ev.session_id, ev.semantic_session_id);
+  const seen = new Set();
+  /** Distinct `session.started` ids in FIRST-SEEN (chronological) order. */
+  const startedIds = [];
+
+  // #1414 — the whole history, OLDEST SOURCE FIRST, streamed line by line. The
+  // previous `readJsonl` of the active file alone missed every session whose
+  // `session.started` had been rotated into `_archive/`; reading the same
+  // sources through `readEventsWithRotations` instead would have loaded up to
+  // ~60 MB into memory on a path that runs at SESSION START
+  // (`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()) {
+    forEachJsonlRecord(source.path, (ev) => {
+      if (!ev || typeof ev !== 'object') return;
+      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) {
+          semanticFromEnded.set(ev.session_id, ev.semantic_session_id);
+        }
+      }
+      if (ev.event !== SESSION_STARTED || typeof ev.session_id !== 'string') return;
+      if (seen.has(ev.session_id)) return;
+      seen.add(ev.session_id);
+      startedIds.push(ev.session_id);
+    });
   }
+
+  // Resolved AFTER the pass, never during it: a `lock.acquired` / `session.ended`
+  // bridge may sit later in the stream (or in a later source) than the
+  // `session.started` it names, and deciding mid-stream would mint a synthetic
+  // id for a session whose semantic id was two lines further on.
   const semanticByUuid = new Map([...semanticFromEnded, ...semanticFromLock]);
 
   const runningIds = readRunningSessionIds(repoRoot);
 
-  const seen = new Set();
   const plan = [];
-  for (const ev of events) {
-    if (ev.event !== SESSION_STARTED || typeof ev.session_id !== 'string') continue;
-    if (seen.has(ev.session_id)) continue;
-    seen.add(ev.session_id);
-    const semanticSessionId = semanticByUuid.get(ev.session_id) ?? null;
-    if (runningIds.has(ev.session_id)
+  for (const sessionId of startedIds) {
+    const semanticSessionId = semanticByUuid.get(sessionId) ?? null;
+    if (runningIds.has(sessionId)
       || (semanticSessionId !== null && runningIds.has(semanticSessionId))) continue;
-    plan.push({ sessionId: ev.session_id, semanticSessionId });
+    plan.push({ sessionId, semanticSessionId });
   }
   return plan;
 }
 
+/**
+ * Stream one JSONL file, handing every PARSED record to `onRecord` in file
+ * order — without ever holding the file in memory (#1414).
+ *
+ * MISSING (ENOENT) → silent no-op; UNREADABLE → a stderr WARN, same split as
+ * {@link readJsonl} (#1188: a missing ledger is the fresh-repo case, an
+ * unreadable one used to read as "no records" and made every count below
+ * silently wrong). Malformed lines are skipped, as in the full-read path.
+ *
+ * A line split across a chunk boundary is CARRIED as a BUFFER, so neither a
+ * record nor a multibyte character is ever cut in half — the 0x0A byte cannot
+ * occur inside a UTF-8 continuation sequence.
+ *
+ * @param {string} filePath
+ * @param {(record: object) => void} onRecord
+ */
+function forEachJsonlRecord(filePath, onRecord) {
+  const emit = (buf) => {
+    const text = buf.toString('utf8').trim();
+    if (!text) return;
+    try {
+      onRecord(JSON.parse(text));
+    } catch {
+      /* skip malformed */
+    }
+  };
+
+  let fd;
+  try {
+    fd = fs.openSync(filePath, 'r');
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write(
+        `⚠ backfill-abandoned-sessions: cannot read ${filePath} ` +
+          `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+          'treating as EMPTY, counts below are floors\n',
+      );
+    }
+    return;
+  }
+  try {
+    const size = fs.fstatSync(fd).size;
+    const buf = Buffer.alloc(SCAN_CHUNK_BYTES);
+    let pos = 0;
+    let carry = Buffer.alloc(0);
+    while (pos < size) {
+      const n = fs.readSync(fd, buf, 0, SCAN_CHUNK_BYTES, pos);
+      if (n <= 0) break;
+      pos += n;
+      const block =
+        carry.length > 0
+          ? Buffer.concat([carry, buf.subarray(0, n)])
+          : Buffer.from(buf.subarray(0, n));
+      let start = 0;
+      let idx = block.indexOf(0x0a, start);
+      while (idx !== -1) {
+        emit(block.subarray(start, idx));
+        start = idx + 1;
+        idx = block.indexOf(0x0a, start);
+      }
+      carry = block.subarray(start);
+    }
+    if (carry.length > 0) emit(carry);
+  } catch (err) {
+    process.stderr.write(
+      `⚠ backfill-abandoned-sessions: cannot read ${filePath} ` +
+        `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+        'treating as EMPTY, counts below are floors\n',
+    );
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
 /**
  * The id(s) naming the session THIS process is, when that session holds the
  * live lock — else the empty set (#1376). Never throws: an unreadable lock,
@@ -551,7 +653,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/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);