session-orchestrator 3.19.0 → 3.20.0

package/hooks/enforce-commands.mjs

@@ -35,17 +35,159 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 if (!shouldRunHook('enforce-commands')) process.exit(0);
 
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 
-import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
-import { resolveProjectDir } from '../scripts/lib/platform.mjs';
-import {
-  findScopeFile,
-  commandMatchesBlocked,
-  suggestForCommandBlock,
-  extractBashWriteTargets,
-  pathMatchesPattern,
-} from '../scripts/lib/hardening.mjs';
-import { readJson } from '../scripts/lib/common.mjs';
+// ---------------------------------------------------------------------------
+// #993 — late-bound repo dependencies
+//
+// These used to be STATIC imports. A SyntaxError in any of them failed at ESM
+// LINK time, before the first statement here ran: node exited 1 with 0 bytes on
+// stdout, and the `main().catch(...)` handler at the bottom of this file was
+// structurally unreachable (it only covers runtime errors inside `main()`).
+// Under the exit-0 PreToolUse protocol (#906) that crash is, on the only
+// decision-bearing channel, INDISTINGUISHABLE from an explicit `emitAllow()` —
+// the guard failed open and SILENTLY. This is the sibling defect #992 fixed for
+// pre-bash-destructive-guard; #993 generalises the same repair here.
+//
+// Binding them late (dynamic `import()` inside `bootstrap()`, below) turns that
+// link-time crash into a catchable runtime error, which is what makes the
+// GUARD INACTIVE banner in `_lib/guard-source-loader.mjs` reachable at all.
+//
+// `profile-gate.mjs` stays static on purpose — it has ZERO imports of its own
+// and gates whether this hook runs at all.
+// ---------------------------------------------------------------------------
+/** @type {typeof import('../scripts/lib/io.mjs').readStdin} */ let readStdin;
+/** @type {typeof import('../scripts/lib/io.mjs').emitAllow} */ let emitAllow;
+/** @type {typeof import('../scripts/lib/io.mjs').emitDeny} */ let emitDeny;
+/** @type {typeof import('../scripts/lib/io.mjs').emitWarn} */ let emitWarn;
+let resolveProjectDir;
+let readJson;
+let findScopeFile;
+let extractBashWriteTargets;
+let pathMatchesPattern;
+/**
+ * The `command-blocker.mjs` namespace, imported DIRECTLY (not via the
+ * hardening.mjs barrel — which does not carry the `headFallback` recovery, and
+ * which transitively imports command-blocker via scope-gate.mjs, so it fails
+ * anyway when command-blocker breaks). Mirrors the direct binding in
+ * pre-bash-destructive-guard / sessions-ledger-guard. Held as ONE object so the
+ * required-export list lives in exactly one place: the `requires` array on the
+ * `blocker` spec passed to `armGuard`.
+ *
+ * @type {Record<string, Function>|null}
+ */
+let blocker = null;
+
+/**
+ * Module labels `armGuard` recovered from HEAD because the working-tree copy
+ * failed (parse error OR shape check). Non-empty ⇒ this hook is armed against
+ * COMMITTED source. Surfaced on the visible stdout channel by {@link flushNotices}
+ * (#1001) — the stderr DEGRADED banner alone is discarded under the exit-0
+ * protocol, which made a degraded ALLOW indistinguishable from a healthy one.
+ *
+ * @type {string[]}
+ */
+let degradedLabels = [];
+
+const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
+
+/** This hook's name — threaded into the guard banner (#993: no hard-wired literal). */
+const HOOK_NAME = 'enforce-commands';
+
+/**
+ * The consequence block spliced VERBATIM into the DEGRADED and GUARD INACTIVE
+ * banners (#993), naming the enforcement this hook's outage stops applying.
+ */
+const GUARD_CONSEQUENCE = {
+  degraded: [
+    '    Consequence: command enforcement IS still armed, but it is evaluating the',
+    '    COMMITTED (HEAD) command-blocker — any uncommitted change to it is NOT in effect.',
+  ],
+  inactive: [
+    '    Consequence: blocked Bash commands (rm -rf, git push --force, git reset',
+    '    --hard, and the wave blockedCommands list) are NOT being screened. This is',
+    '    a BROKEN GUARD, not a policy decision — do not route around it, repair it.',
+  ],
+};
+
+/**
+ * Project dir for banner keying, resolved WITHOUT `platform.mjs` — that module
+ * is one of the ones that may have failed to load.
+ *
+ * @returns {string}
+ */
+function bannerProjectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * Bind every repo dependency late, making a load failure VISIBLE (GUARD INACTIVE
+ * banner) instead of a silent exit-1 / 0-byte disarm. Throws on any load failure;
+ * the entry-point catch banners.
+ *
+ * `hardening.mjs` is bound (no headFallback — it carries relative imports) for
+ * `findScopeFile` / `extractBashWriteTargets` / `pathMatchesPattern`; the two
+ * command-matching primitives come from the direct `blocker` namespace, which is
+ * the only entry that opts into the `git show HEAD:` recovery. Because hardening
+ * transitively imports command-blocker (via scope-gate.mjs), a broken command-blocker
+ * fails hardening FIRST (it arms before the headFallback entry) — so that case
+ * degrades straight to GUARD INACTIVE, git or no git.
+ *
+ * @returns {Promise<void>}
+ */
+async function bootstrap() {
+  const lib = (...seg) => pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', ...seg)).href;
+
+  const { armGuard } = await import('./_lib/guard-source-loader.mjs');
+  const { modules, degraded } = await armGuard(
+    {
+      io: { specifier: lib('io.mjs') },
+      platform: { specifier: lib('platform.mjs') },
+      common: { specifier: lib('common.mjs') },
+      hardening: { specifier: lib('hardening.mjs') },
+      blocker: {
+        specifier: lib('command-blocker.mjs'),
+        headFallback: true,
+        requires: ['commandMatchesBlocked', 'suggestForCommandBlock'],
+      },
+    },
+    {
+      hookName: HOOK_NAME,
+      repoRoot: PLUGIN_ROOT,
+      projectDir: bannerProjectDir(),
+      consequence: GUARD_CONSEQUENCE,
+    }
+  );
+
+  ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
+  ({ resolveProjectDir } = modules.platform);
+  ({ readJson } = modules.common);
+  ({ findScopeFile, extractBashWriteTargets, pathMatchesPattern } = modules.hardening);
+  blocker = modules.blocker;
+  degradedLabels = degraded;
+}
+
+/**
+ * Flush the aggregated allow-with-notice channel (#1001).
+ *
+ * Notices raised during gate evaluation accumulate in `notices` and are emitted
+ * ONCE, here, on the VISIBLE stdout channel via `emitWarn` (allow-with-notice) —
+ * else a plain `emitAllow`. Both exit 0 and never return, so this is always the
+ * LAST statement on an allow path.
+ *
+ * Why aggregate instead of `emitWarn`-ing inline at the degraded site: `emitWarn`
+ * is `@returns never` (scripts/lib/io.mjs), so an inline call before the G6
+ * blocked-pattern loop would exit BEFORE any pattern was matched — turning every
+ * would-be DENY into an ALLOW-with-notice for the whole degraded session. A deny,
+ * when it fires, exits via `emitDeny` and these notices are simply dropped: DENY
+ * wins, and armGuard's stderr banner remains for CI/debug.
+ *
+ * @param {string[]} notices
+ * @returns {never}
+ */
+function flushNotices(notices) {
+  return notices.length > 0 ? emitWarn(notices.join('\n')) : emitAllow();
+}
 
 // Fallback safety list — applied when scope.blockedCommands is empty.
 // Keep in sync with hooks/enforce-commands.sh; v3 additions (#138, SECURITY-REQ-07)
@@ -71,11 +213,29 @@ async function main() {
   const command = input?.tool_input?.command;
   if (typeof command !== 'string' || command.length === 0) return emitAllow();
 
+  // #1001 — aggregated allow-with-notice channel, opened only AFTER G1/G2 (a
+  // non-Bash tool call or an empty command is not this hook's business, and must
+  // stay a bare allow so the notice does not ride every unrelated tool call).
+  // Flushed ONCE at the end of whichever allow path is taken; see flushNotices
+  // for why an inline emitWarn here would disarm the G6 deny below.
+  const notices = [];
+  // A guard armed from HEAD (working-tree module unparseable or shape-invalid) is
+  // a visible-channel concern: the DEGRADED banner rides stderr only, which exit 0
+  // discards. armGuard already fired that banner once per session; surface it on
+  // stdout too so a degraded ALLOW is not silently indistinguishable from a
+  // healthy one.
+  if (degradedLabels.length > 0) {
+    notices.push(
+      `${HOOK_NAME}: DEGRADED — guard module(s) loaded from HEAD, not your working tree ` +
+        `(${degradedLabels.join(', ')}); uncommitted changes to them are NOT in effect. See #992.`
+    );
+  }
+
   const projectRoot = resolveProjectDir();
 
   // G3 — no scope file → allow
   const scopePath = findScopeFile(projectRoot);
-  if (!scopePath) return emitAllow();
+  if (!scopePath) return flushNotices(notices);
 
   // SECURITY-REQ-08: read scope file exactly once; use the parsed object
   // for all subsequent gate checks.
@@ -106,30 +266,35 @@ async function main() {
   }
 
   // G4 — gate disabled → allow
-  if (!gateOn) return emitAllow();
+  if (!gateOn) return flushNotices(notices);
   // G5 — enforcement "off" → allow
-  if (enforcement === 'off') return emitAllow();
+  if (enforcement === 'off') return flushNotices(notices);
 
   // G6 — determine which list to check
   const useFallback = blockedCommands.length === 0;
   const patternsToCheck = useFallback ? FALLBACK_BLOCKED : blockedCommands;
 
   for (const pattern of patternsToCheck) {
-    if (commandMatchesBlocked(command, pattern)) {
+    if (blocker.commandMatchesBlocked(command, pattern)) {
       const prefix = useFallback
         ? 'Blocked by fallback safety list'
         : 'Blocked command';
       const reason = `${prefix}: '${pattern}' found in command`;
-      const suggestion = suggestForCommandBlock(pattern);
+      const suggestion = blocker.suggestForCommandBlock(pattern);
       if (enforcement === 'strict') {
         return emitDeny(reason, suggestion);
       }
-      return emitWarn(`${reason} — ${suggestion}`);
+      // Aggregated, not inline: when the guard is DEGRADED the notice list is
+      // non-empty and both lines ride ONE envelope (a second emitWarn would be
+      // unreachable — emitWarn never returns). Undegraded, notices is empty and
+      // this stays the single-line warn it has always been.
+      notices.push(`${reason} — ${suggestion}`);
+      return flushNotices(notices);
     }
   }
 
   // G7 — no match → allow
-  return emitAllow();
+  return flushNotices(notices);
 }
 
 /**
@@ -181,6 +346,40 @@ function targetInWaveScope(target, allowedPaths, projectRoot) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Entry point (#993)
+//
+// TWO distinct failure classes, two distinct handlers — do NOT merge them:
+//
+//   1. LOAD failure (`bootstrap()` throws): the guard never armed. Under the
+//      exit-0 protocol a bare exit-1 crash with 0 bytes of stdout is, on the
+//      only decision-bearing channel, indistinguishable from an allow. Now it
+//      exits 0 (still fail-OPEN — a broken module must not brick the session,
+//      and emitDeny itself may be the module that failed to load) but SAYS SO,
+//      loudly: GUARD INACTIVE.
+//   2. RUNTIME failure inside `main()`: pre-existing behaviour, unchanged. The
+//      guard armed and then tripped over a specific command; that fails CLOSED
+//      via emitDeny (SECURITY-REQ-01). The two paths MUST stay separate.
+// ---------------------------------------------------------------------------
+try {
+  await bootstrap();
+} catch (loadError) {
+  try {
+    const { emitGuardInactiveBanner } = await import('./_lib/guard-source-loader.mjs');
+    // hookName is threaded explicitly (#993 — no hard-wired literal in the loader).
+    emitGuardInactiveBanner({ hookName: HOOK_NAME, error: loadError, consequence: GUARD_CONSEQUENCE });
+  } catch {
+    // Last resort: even the banner helper failed to load. Emit unconditionally —
+    // repeated noise beats a silent disarm.
+    process.stderr.write(
+      '🚨 enforce-commands: GUARD INACTIVE — module load failed ' +
+        `(${String(loadError?.message || loadError).split('\n')[0]}). ` +
+        'Blocked Bash commands are NOT being screened. See issue #993.\n'
+    );
+  }
+  process.exit(0); // fail-open, but no longer fail-silent
+}
+
 // SECURITY-REQ-01 (F-03): top-level try/catch — never let exit 1 leak.
 main().catch((e) => {
   emitDeny('Internal hook error — request blocked for safety', `${e?.message || e}`);

package/hooks/enforce-scope.mjs

@@ -48,20 +48,110 @@
 
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
+import { pathToFileURL } from 'node:url';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 // #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
 if (!shouldRunHook('enforce-scope')) process.exit(0);
 
-import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
-import { isPathInside, relativeFromRoot } from '../scripts/lib/path-utils.mjs';
-import { resolveProjectDir } from '../scripts/lib/platform.mjs';
-import {
-  findScopeFile,
-  pathMatchesPattern,
-  suggestForScopeViolation,
-} from '../scripts/lib/hardening.mjs';
-import { readJson } from '../scripts/lib/common.mjs';
+// ---------------------------------------------------------------------------
+// #993 — late-bound repo dependencies
+//
+// These used to be STATIC imports. A SyntaxError in any of them failed at ESM
+// LINK time, before the first statement here ran: node exited 1 with 0 bytes on
+// stdout, and the `main().catch(...)` handler at the bottom of this file was
+// structurally unreachable. Under the exit-0 PreToolUse protocol (#906) that
+// crash is, on the only decision-bearing channel, INDISTINGUISHABLE from an
+// explicit `emitAllow()` — the guard failed open and SILENTLY. This is the
+// sibling defect #992 fixed for pre-bash-destructive-guard; #993 generalises the
+// same repair here.
+//
+// Binding them late (dynamic `import()` inside `bootstrap()`, below) turns that
+// link-time crash into a catchable runtime error, which is what makes the
+// GUARD INACTIVE banner in `_lib/guard-source-loader.mjs` reachable at all.
+//
+// BANNER-ONLY (#993 D1): this hook consumes ZERO command-blocker symbols, so no
+// module here opts into the `git show HEAD:` fallback — every load failure
+// degrades straight to GUARD INACTIVE, never DEGRADED.
+//
+// `profile-gate.mjs` and `node:*` builtins stay static — they cannot be the
+// broken repo module.
+// ---------------------------------------------------------------------------
+/** @type {typeof import('../scripts/lib/io.mjs').readStdin} */ let readStdin;
+/** @type {typeof import('../scripts/lib/io.mjs').emitAllow} */ let emitAllow;
+/** @type {typeof import('../scripts/lib/io.mjs').emitDeny} */ let emitDeny;
+/** @type {typeof import('../scripts/lib/io.mjs').emitWarn} */ let emitWarn;
+let isPathInside;
+let relativeFromRoot;
+let resolveProjectDir;
+let findScopeFile;
+let pathMatchesPattern;
+let suggestForScopeViolation;
+let readJson;
+
+const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
+
+/** This hook's name — threaded into the guard banner (#993: no hard-wired literal). */
+const HOOK_NAME = 'enforce-scope';
+
+/**
+ * The consequence block spliced VERBATIM into the GUARD INACTIVE banner (#993),
+ * naming the enforcement this hook's outage stops applying. No `degraded` block:
+ * this hook has no headFallback module, so it can never DEGRADE — only go INACTIVE.
+ */
+const GUARD_CONSEQUENCE = {
+  inactive: [
+    '    Consequence: Edit/Write/MultiEdit scope enforcement is OFF — writes',
+    '    outside the wave allowedPaths (and outside the project root) are NOT',
+    '    being blocked. This is a BROKEN GUARD, not a policy decision — do not',
+    '    route around it, repair it.',
+  ],
+};
+
+/**
+ * Project dir for banner keying, resolved WITHOUT `platform.mjs` — that module
+ * is one of the ones that may have failed to load.
+ *
+ * @returns {string}
+ */
+function bannerProjectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * Bind every repo dependency late, making a load failure VISIBLE (GUARD INACTIVE
+ * banner) instead of a silent exit-1 / 0-byte disarm. Throws on any load failure;
+ * the entry-point catch banners. No entry opts into headFallback — this hook is
+ * banner-only (#993 D1).
+ *
+ * @returns {Promise<void>}
+ */
+async function bootstrap() {
+  const lib = (...seg) => pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', ...seg)).href;
+
+  const { armGuard } = await import('./_lib/guard-source-loader.mjs');
+  const { modules } = await armGuard(
+    {
+      io: { specifier: lib('io.mjs') },
+      pathUtils: { specifier: lib('path-utils.mjs') },
+      platform: { specifier: lib('platform.mjs') },
+      hardening: { specifier: lib('hardening.mjs') },
+      common: { specifier: lib('common.mjs') },
+    },
+    {
+      hookName: HOOK_NAME,
+      repoRoot: PLUGIN_ROOT,
+      projectDir: bannerProjectDir(),
+      consequence: GUARD_CONSEQUENCE,
+    }
+  );
+
+  ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
+  ({ isPathInside, relativeFromRoot } = modules.pathUtils);
+  ({ resolveProjectDir } = modules.platform);
+  ({ findScopeFile, pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
+  ({ readJson } = modules.common);
+}
 
 async function main() {
   // SECURITY-REQ-01: null-guard empty stdin — treat as allow (no input = not a real hook call)
@@ -264,6 +354,40 @@ function matchesAbsoluteAllowlist(resolvedPath, allowedPaths) {
   return abs.some((pat) => pathMatchesPattern(normalizedAbs, pat.split(path.sep).join('/')));
 }
 
+// ---------------------------------------------------------------------------
+// Entry point (#993)
+//
+// TWO distinct failure classes, two distinct handlers — do NOT merge them:
+//
+//   1. LOAD failure (`bootstrap()` throws): the guard never armed. Under the
+//      exit-0 protocol a bare exit-1 crash with 0 bytes of stdout is, on the
+//      only decision-bearing channel, indistinguishable from an allow. Now it
+//      exits 0 (still fail-OPEN — a broken module must not brick the session,
+//      and emitDeny itself may be the module that failed to load) but SAYS SO:
+//      GUARD INACTIVE. Banner-only — no headFallback module here (#993 D1).
+//   2. RUNTIME failure inside `main()`: pre-existing behaviour, unchanged. The
+//      guard armed and then tripped over a specific path; that fails CLOSED via
+//      emitDeny (SECURITY-REQ-01). The two paths MUST stay separate.
+// ---------------------------------------------------------------------------
+try {
+  await bootstrap();
+} catch (loadError) {
+  try {
+    const { emitGuardInactiveBanner } = await import('./_lib/guard-source-loader.mjs');
+    // hookName is threaded explicitly (#993 — no hard-wired literal in the loader).
+    emitGuardInactiveBanner({ hookName: HOOK_NAME, error: loadError, consequence: GUARD_CONSEQUENCE });
+  } catch {
+    // Last resort: even the banner helper failed to load. Emit unconditionally —
+    // repeated noise beats a silent disarm.
+    process.stderr.write(
+      '🚨 enforce-scope: GUARD INACTIVE — module load failed ' +
+        `(${String(loadError?.message || loadError).split('\n')[0]}). ` +
+        'Edit/Write/MultiEdit scope enforcement is OFF. See issue #993.\n'
+    );
+  }
+  process.exit(0); // fail-open, but no longer fail-silent
+}
+
 // SECURITY-REQ-01 (fail-closed): any unhandled rejection → structured deny, never bare exit 1
 main().catch((e) => {
   emitDeny(

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.19.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.20.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.19.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.20.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/on-session-start.mjs

@@ -458,12 +458,15 @@ async function main() {
   let bannerData = null;
   if (await isHostBannerEnabled(projectRoot)) {
     bannerData = await emitHostBanner(projectRoot);
-    // Always-on nudge: user decisions must go through AskUserQuestion, not inline
-    // markdown lists. The coordinator chat stream is dense and prose questions
-    // are reliably missed. Full rationale + exceptions in .claude/rules/ask-via-tool.md.
+    // Always-on nudge: a user decision has three legitimate forms and AUQ-001
+    // routes between them in order — operator verb first (nothing is blocked
+    // while the operator picks his moment), then derive-and-report from Session
+    // Config / STATE.md / git, and only then the tool. The banner carries the
+    // ORDER, not an absolute; full routing + exceptions in
+    // .claude/rules/ask-via-tool.md.
     try {
       console.log(JSON.stringify({
-        systemMessage: '🎯 User decisions → AskUserQuestion tool. Inline choice lists = bug (.claude/rules/ask-via-tool.md).',
+        systemMessage: '🎯 Decide: operator verb (/go) > derive+report > AUQ if blocking (.claude/rules/ask-via-tool.md).',
       }));
     } catch { /* best effort */ }
   }