session-orchestrator 5.2.0 → 5.3.0

package/hooks/config-protection.mjs

@@ -42,8 +42,7 @@
  */
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('config-protection')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
@@ -512,4 +511,13 @@ async function main() {
 }
 
 // Fail-open on ANY uncaught error — a guard bug must never block a legit edit.
-main().catch(() => { try { emitAllow(); } catch { process.exit(0); } });
+// Entry guard (#1393): run only when this file IS the script node was invoked
+// with — every harness path execs it (`sh run-node.sh <this file>`). A bare
+// `import()` (a probe, a test, a curious agent) must neither run main() nor
+// tear the importing process down. The profile gate sits INSIDE the guard for
+// that second reason: at module top level its `process.exit(0)` exited every
+// process that merely imported this hook.
+if (isMainModule(import.meta.url)) {
+  if (!shouldRunHook('config-protection')) process.exit(0);
+  main().catch(() => { try { emitAllow(); } catch { process.exit(0); } });
+}

package/hooks/cwd-change-restore.mjs

@@ -27,8 +27,7 @@
 import path from 'node:path';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('cwd-change-restore')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { atomicMutateJson } from './_lib/atomic-json.mjs';
@@ -108,4 +107,13 @@ async function main() {
 }
 
 // Exit 0 always — informational hook must never block Claude.
-main().catch(() => {}).finally(() => process.exit(0));
+// Entry guard (#1393): run only when this file IS the script node was invoked
+// with — every harness path execs it (`sh run-node.sh <this file>`). A bare
+// `import()` (a probe, a test, a curious agent) must neither run main() nor
+// tear the importing process down. The profile gate sits INSIDE the guard for
+// that second reason: at module top level its `process.exit(0)` exited every
+// process that merely imported this hook.
+if (isMainModule(import.meta.url)) {
+  if (!shouldRunHook('cwd-change-restore')) process.exit(0);
+  main().catch(() => {}).finally(() => process.exit(0));
+}

package/hooks/enforce-commands.mjs

@@ -31,9 +31,44 @@
  */
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
-if (!shouldRunHook('enforce-commands')) process.exit(0);
+// Static for the SAME reason profile-gate.mjs is (#993, see the late-binding
+// block below): a leaf predicate with ZERO repo imports (node:fs + node:url
+// only) that decides whether this hook runs at all. Everything carrying a
+// transitive repo graph stays late-bound inside bootstrap().
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
+/**
+ * sha256(command), auf 16 Hex-Zeichen gekuerzt.
+ *
+ * WORTGLEICH zu `hashCommand()` in `hooks/pre-bash-destructive-guard.mjs:245`
+ * (das seinerseits `loop-guard.mjs` hashArgs() spiegelt). Bewusst dupliziert
+ * statt geteilt: ein Hook darf beim Start nicht an einem weiteren Modul
+ * haengen, das fehlen kann — die drei Zeilen sind billiger als ein
+ * Ladefehler auf dem PreToolUse-Pfad.
+ *
+ * WARUM ES DEN HELFER HIER BRAUCHT (2026-09-19, EventDrop #1140):
+ * Die `foreign_session_ignored`-Nutzlast dieses Hooks trug bis heute das
+ * ROHE Kommando. Gemessen in EventDrop.at: 3.816 Zeilen in der getrackten
+ * `.orchestrator/metrics/events.jsonl` mit rohem `command`, darin 24
+ * distinkte ECHTE Produktions-Share-Codes aus 17 fremden Kundenkonten und
+ * ein protokollierter `select access_pin_hash`. Bei 23 dieser Events ist
+ * der Share-Code die vollstaendige Capability — `/event/<code>` oeffnet das
+ * Album ohne Anmeldung. Das Journal ist getrackt und geht bei jedem Klon mit.
+ * Der Geschwisterhook `pre-bash-destructive-guard.mjs` machte es von Anfang
+ * an richtig und sagt es im eigenen Kopf: „Payload never includes the raw
+ * command — only a truncated sha256 command_hash."
+ *
+ * Der Hash haelt das Ereignis ZAEHLBAR und GRUPPIERBAR — genau die
+ * Eigenschaft, fuer die es laut `docs/scope-collision-guard.md` existiert.
+ * Das rohe Kommando wurde von keinem Konsumenten gelesen.
+ *
+ * @param {string} command
+ * @returns {string}
+ */
+function hashCommand(command) {
+  return crypto.createHash('sha256').update(command).digest('hex').slice(0, 16);
+}
+import crypto from 'node:crypto';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
@@ -298,7 +333,7 @@ async function main() {
             manifest_session: manifestIds,
             own_session: [...ownIds],
             wave: scope.wave,
-            command,
+            command_hash: hashCommand(command),
           },
           { repoRoot: projectRoot },
         );
@@ -430,26 +465,38 @@ function targetInWaveScope(target, allowedPaths, projectRoot) {
 //      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) {
+// Entry guard (#1393): run only when this file IS the script node was invoked
+// with — every harness path execs it (`sh run-node.sh <this file>`). A bare
+// `import()` (a probe, a test, a curious agent) must neither run main() nor
+// tear the importing process down. The profile gate sits INSIDE the guard for
+// that second reason: at module top level its `process.exit(0)` exited every
+// process that merely imported this hook. bootstrap() is inside too — loading
+// the guard sources is work a disabled hook and a bare importer must not do.
+if (isMainModule(import.meta.url)) {
+  // #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
+  if (!shouldRunHook('enforce-commands')) process.exit(0);
+
   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'
-    );
+    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
   }
-  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}`);
-});
+  // 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

@@ -21,7 +21,10 @@
  *       matches the fully realpath-resolved candidate → allow, BEFORE G6.
  *       Runs before G6 so a deliberate out-of-repo grant (e.g. a vault path)
  *       is reachable at all — G6 would otherwise deny every out-of-repo path
- *       without ever consulting allowedPaths. See matchesAbsoluteAllowlist.
+ *       without ever consulting allowedPaths. See matchedAbsoluteGrant.
+ *       (#1398 cond. 4) The matched grant is GRADED through the shared
+ *       `gradeScopeEntry` predicate; an `error` verdict emits ONE WARN and the
+ *       write is still ALLOWED — this gate never denies on a grading verdict.
  *   G5c (#1295) out-of-root carveout for THIS repo's Claude Code auto-memory
  *       directory (`~/.claude/projects/<encoded-repo-path>/memory/`). Harness-
  *       owned, lives outside the working copy, cannot collide with any wave
@@ -68,8 +71,11 @@ 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);
+// Static for the SAME reason profile-gate.mjs is (#993, see the late-binding
+// block below): a leaf predicate with ZERO repo imports (node:fs + node:url
+// only) that decides whether this hook runs at all. Everything carrying a
+// transitive repo graph stays late-bound inside bootstrap().
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // #993 — late-bound repo dependencies
@@ -109,6 +115,12 @@ let readJson;
 let classifyEmptyScope;
 let suggestForEmptyScope;
 let sessionStartedAtMs;
+// #1398 cond. 4 — THE shared grading predicate for an absolute Gate 5b grant,
+// plus the resolver it takes. The hook WARNS on an `error` verdict and never
+// denies on it; see Gate 5b. Both come from the module already bound below —
+// no new module edge, so `hooks/_lib/hook-import-set.json` is unchanged.
+let gradeScopeEntry;
+let canonicalizeGrantPrefix;
 // #1123 — "is this manifest even mine?" (G3b). Process-local identity only
 // (#1194): the repo-global `session.lock` tier is shared by every session in the
 // checkout and would classify a peer's manifest as ours.
@@ -188,7 +200,13 @@ async function bootstrap() {
   ({ resolveProjectDir } = modules.platform);
   ({ findScopeFile, pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
   ({ readJson } = modules.common);
-  ({ classifyEmptyScope, suggestForEmptyScope, sessionStartedAtMs } = modules.scopeGate);
+  ({
+    classifyEmptyScope,
+    suggestForEmptyScope,
+    sessionStartedAtMs,
+    gradeScopeEntry,
+    canonicalizeGrantPrefix,
+  } = modules.scopeGate);
   ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
 }
 
@@ -433,7 +451,52 @@ async function main() {
   // out-of-repo path before allowedPaths is ever consulted. Honour such grants
   // here — matching ONLY absolute entries against the fully realpath-resolved
   // candidate, so relative entries can never be used to escape the repo (REQ-09).
-  if (matchesAbsoluteAllowlist(resolvedPath, allowedPaths)) return emitAllow();
+  //
+  // GRADING (#1398 acceptance condition 4): this gate ALLOWS exactly what it
+  // allowed before — the verdict below is a WARN, never a deny. Until now the
+  // asymmetry was silent: `scripts/validate-wave-scope.mjs` graded these grants
+  // (system-root denylist, home depth + sensitive-subdirectory rule) and NOTHING
+  // called it from code — four prose steps in `skills/wave-executor/` were the
+  // only thing between a manifest and this gate, so a manifest that skipped them
+  // reached here ungraded and the operator never learned that it had.
+  //
+  // Now the same predicate runs HERE, on the grant that actually matched, and an
+  // `error` verdict surfaces as one operator-visible notice. Deliberately not a
+  // deny: this hook runs in every repo on the host, the grant is the
+  // coordinator's own artefact, and turning a live allow into a block on a
+  // pre-flight rule would break working sessions to enforce a policy whose place
+  // is before dispatch. `emitWarn` is an ALLOW that carries a notice (exit 0,
+  // `systemMessage` only) — see `scripts/lib/io.mjs`.
+  //
+  // THE SAME `resolve` THE VALIDATOR PASSES (#1398 cond. 4, closed 2026-09-21).
+  // It was omitted here on the assumption that canonicalisation is too expensive
+  // for a PreToolUse hot path; measuring it refuted that, and the omission was
+  // the last source of a verdict divergence between the two callers of one
+  // predicate (`/tmp/x/**`: `warn` here, `error/non-canonical` there — silent on
+  // exactly the grant that matches nothing at this gate).
+  //
+  // MEASURED 2026-09-21, A/B in one process, 200 repetitions, median:
+  //   - this call site grades ONE grant per Gate 5b hit, never the manifest:
+  //     +0.067 ms, 15 `realpathSync` — 75× under the 5 ms decision threshold;
+  //   - a Gate 5b hit requires an out-of-repo write AND an absolute grant that
+  //     matches it. The live 64-entry manifest of that session carried 0
+  //     absolute entries and therefore cost 0 syscalls: an ordinary in-repo
+  //     write never reaches this line at all.
+  // `canonicalizeGrantPrefix` memoizes per process and never throws (see its
+  // docblock); `gradeScopeEntry` additionally degrades a throwing resolver to
+  // the literal spelling, so the worst case is today's verdict.
+  const matchedGrant = matchedAbsoluteGrant(resolvedPath, allowedPaths);
+  if (matchedGrant !== null) {
+    const grade = gradeScopeEntry(matchedGrant, { resolve: canonicalizeGrantPrefix });
+    if (grade?.verdict === 'error') {
+      return emitWarn(
+        `Gate 5b honoured an out-of-repo grant that scripts/validate-wave-scope.mjs would REFUSE ` +
+          `before dispatch — allowedPaths ${grade.message}. The write to '${resolvedPath}' is ` +
+          `ALLOWED (this gate never denies on a grading verdict); re-validate the manifest.`,
+      );
+    }
+    return emitAllow();
+  }
 
   // Gate 6: path must be inside the project root
   if (!isPathInside(resolvedPath, projectRoot)) {
@@ -774,19 +837,54 @@ function isCoordinatorCarveout(normalizedRel, projectRoot, scopePath) {
  * SECURITY (REQ-09): matches ONLY entries that are themselves absolute, against
  * the fully realpath-resolved candidate — so RELATIVE entries (`**`, `../**`)
  * can NEVER be used to escape the repo. When no absolute entry exists the helper
- * returns false and the caller falls through to Gate 6 unchanged (inert pre-gate).
+ * returns null and the caller falls through to Gate 6 unchanged (inert pre-gate).
  * An absolute entry matches only its own literal (canonical/realpath) subtree;
  * the operator is responsible for supplying a canonical absolute path.
  *
+ * MATCHING IS SHAPE-BLIND HERE; GRADING IS SHARED (#1398 cond. 4). This helper
+ * still decides nothing about whether a grant SHOULD exist: `/Users/<u>/**` and
+ * `/Users/<u>/.ssh/**` match exactly like `/Users/<u>/Projects/vault/**`. What
+ * changed is that the CALLER now runs the ONE grading predicate —
+ * `gradeScopeEntry` in `scripts/lib/scope-gate.mjs`, the same function
+ * `scripts/validate-wave-scope.mjs` turns into an exit-1 refusal — over the grant
+ * this helper returns, and WARNS when it grades `error`.
+ *
+ * ONE PREDICATE, ONE ARGUMENT SHAPE — THE VERDICTS NO LONGER DIFFER (#1398
+ * cond. 4, closed 2026-09-21). Both callers now pass the SAME fs-backed
+ * `resolve` (`canonicalizeGrantPrefix`, exported from
+ * `scripts/lib/scope-gate.mjs`), so only the CONSEQUENCE is asymmetric: the
+ * validator refuses an `error` before dispatch, this gate allows it with a
+ * notice at write time. The history, because the asymmetry was load-bearing for
+ * two fixes, measured 2026-09-20 @ 7e110a2a with the resolver-free call:
+ *   - `/private/etc/**`, `/private/var/**` — the macOS realpaths of the
+ *     denylisted `/etc` and `/var`, i.e. the spellings Gate 5b ACTUALLY matches
+ *     (it matches the realpath-resolved candidate): hook `warn`, validator
+ *     `error`. The notice fired on `/etc/**`, which reaches nothing here, and
+ *     stayed silent on the spelling that reaches everything. CLOSED by listing
+ *     the two aliases literally (`DENIED_ABSOLUTE_ALIAS_ROOTS`), at zero
+ *     syscalls — they still cost nothing and stay.
+ *   - `/tmp/x/**` — hook `warn`, validator `error/non-canonical`: the last
+ *     divergence, 1 of 9 probes, and not closable by any literal list, because
+ *     proving a literal prefix resolves elsewhere IS the realpath call. CLOSED
+ *     by passing the resolver here too, once its cost was measured instead of
+ *     assumed (+0.067 ms per Gate 5b hit; see the call site).
+ * The parity of the two verdict tables is pinned by
+ * `tests/lib/scope-gate.test.mjs` § "hook / validator grading parity", so a NEW
+ * divergence is a red test rather than a comment someone has to notice.
+ *
+ * Returns the MATCHED PATTERN rather than a boolean precisely so the caller has
+ * something to grade: with a bare `true` the grant that opened the gate is
+ * unknowable at the call site, and any notice would have to re-derive it.
+ *
  * @param {string} resolvedPath — fully realpath-resolved candidate (absolute)
  * @param {string[]} allowedPaths — raw allowedPaths array from wave-scope.json
- * @returns {boolean}
+ * @returns {string|null} the first matching absolute entry, or null
  */
-function matchesAbsoluteAllowlist(resolvedPath, allowedPaths) {
+function matchedAbsoluteGrant(resolvedPath, allowedPaths) {
   const abs = allowedPaths.filter((p) => typeof p === 'string' && path.isAbsolute(p));
-  if (abs.length === 0) return false;
+  if (abs.length === 0) return null;
   const normalizedAbs = resolvedPath.split(path.sep).join('/');
-  return abs.some((pat) => pathMatchesPattern(normalizedAbs, pat.split(path.sep).join('/')));
+  return abs.find((pat) => pathMatchesPattern(normalizedAbs, pat.split(path.sep).join('/'))) ?? null;
 }
 
 // ---------------------------------------------------------------------------
@@ -804,29 +902,41 @@ function matchesAbsoluteAllowlist(resolvedPath, allowedPaths) {
 //      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) {
+// Entry guard (#1393): run only when this file IS the script node was invoked
+// with — every harness path execs it (`sh run-node.sh <this file>`). A bare
+// `import()` (a probe, a test, a curious agent) must neither run main() nor
+// tear the importing process down. The profile gate sits INSIDE the guard for
+// that second reason: at module top level its `process.exit(0)` exited every
+// process that merely imported this hook. bootstrap() is inside too — loading
+// the guard sources is work a disabled hook and a bare importer must not do.
+if (isMainModule(import.meta.url)) {
+  // #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
+  if (!shouldRunHook('enforce-scope')) process.exit(0);
+
   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'
-    );
+    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
   }
-  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(
-    'Internal hook error — request blocked for safety',
-    `${e?.message ?? String(e)}`,
-  );
-});
+  // SECURITY-REQ-01 (fail-closed): any unhandled rejection → structured deny, never bare exit 1
+  main().catch((e) => {
+    emitDeny(
+      'Internal hook error — request blocked for safety',
+      `${e?.message ?? String(e)}`,
+    );
+  });
+}

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.2.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.3.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 v5.2.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.3.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/loop-guard.mjs

@@ -25,8 +25,7 @@
  */
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('loop-guard')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
@@ -257,4 +256,13 @@ async function main() {
 }
 
 // Exit 0 always — informational hook must never block Claude (#619).
-main().catch(() => {}).finally(() => process.exit(0));
+// Entry guard (#1393): run only when this file IS the script node was invoked
+// with — every harness path execs it (`sh run-node.sh <this file>`). A bare
+// `import()` (a probe, a test, a curious agent) must neither run main() nor
+// tear the importing process down. The profile gate sits INSIDE the guard for
+// that second reason: at module top level its `process.exit(0)` exited every
+// process that merely imported this hook.
+if (isMainModule(import.meta.url)) {
+  if (!shouldRunHook('loop-guard')) process.exit(0);
+  main().catch(() => {}).finally(() => process.exit(0));
+}

package/hooks/on-session-end.mjs

@@ -31,8 +31,6 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
-if (!shouldRunHook('on-session-end')) process.exit(0);
 
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { getProjectDir } from '../scripts/lib/platform.mjs';
@@ -47,6 +45,7 @@ import {
   OWNER_PROOF_RELPATH,
 } from '../scripts/lib/session-lock.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { deregisterSelf, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
 import { flush } from '../scripts/lib/telemetry/sync.mjs';
@@ -255,21 +254,44 @@ async function readPersistence(projectRoot) {
 }
 
 /**
- * Reduce a `flush()` result to the two-field breadcrumb the event carries.
- *
- * `reason` is normalised to its head token because `flush()` may return
- * `build-error: <message>`, and a raw error message is unbounded free text in a
- * stream whose whole purpose is aggregation by class.
+ * Characters kept from `flush()`'s raw `reason` in the event record.
+ *
+ * NAMED CEILING (BV-004): `flush()` may return `build-error: <message>`, i.e.
+ * unbounded free text, into a stream whose purpose is aggregation. 200 mirrors
+ * the sibling bound in `scripts/lib/session-start-probes.mjs`; the banner
+ * re-bounds to 120 and strips control bytes on its own side, because the ledger
+ * is an untrusted string source for anything that renders it.
+ * REVISIT TRIGGER: a legitimate `flush()` reason longer than 200 characters.
+ */
+const FLUSH_REASON_MAX_CHARS = 200;
+
+/**
+ * Reduce a `flush()` result to the three-field breadcrumb the event carries.
+ *
+ * `reason` is the FULL reason (length-bounded, see FLUSH_REASON_MAX_CHARS) and
+ * `reason_class` is its head token — the part before the first `:` — so an
+ * aggregation by class stays possible without destroying the detail.
+ *
+ * #1392, the defect this shape replaces: `reason` used to BE the head token
+ * (`String(res?.reason ?? 'unknown').split(':')[0]`). All five sandbox
+ * refusals `scripts/lib/telemetry/sync.mjs` produces (`sandbox:temp-root`,
+ * `sandbox:probe-failed`, …) were therefore written as bare `sandbox`, while
+ * the one reader — `scripts/lib/telemetry-flush-health-banner.mjs` — requires
+ * `reason.startsWith('sandbox:')`. The banner could not fire on any record this
+ * emitter ever wrote, and a mute instrument looks exactly like a healthy
+ * channel (HR-105). The cut is irrecoverable at the reader, so the fix belongs
+ * here: persist the full reason, carry the class beside it.
  *
  * @param {{sent?: boolean, queued?: boolean, reason?: string}|null|undefined} res
- * @returns {{outcome: 'sent'|'queued'|'gated'|'skipped', reason: string}}
+ * @returns {{outcome: 'sent'|'queued'|'gated'|'skipped', reason: string, reason_class: string}}
  */
-function classifyFlush(res) {
-  const reason = String(res?.reason ?? 'unknown').split(':')[0];
-  if (res?.sent === true) return { outcome: 'sent', reason };
-  if (res?.queued === true) return { outcome: 'queued', reason };
-  if (reason === 'gated') return { outcome: 'gated', reason };
-  return { outcome: 'skipped', reason };
+export function classifyFlush(res) {
+  const reason = String(res?.reason ?? 'unknown').slice(0, FLUSH_REASON_MAX_CHARS);
+  const reasonClass = reason.split(':')[0];
+  if (res?.sent === true) return { outcome: 'sent', reason, reason_class: reasonClass };
+  if (res?.queued === true) return { outcome: 'queued', reason, reason_class: reasonClass };
+  if (reasonClass === 'gated') return { outcome: 'gated', reason, reason_class: reasonClass };
+  return { outcome: 'skipped', reason, reason_class: reasonClass };
 }
 
 /**
@@ -287,8 +309,9 @@ function classifyFlush(res) {
  * statement) — this function deliberately does not re-implement it, so there is
  * exactly one place where "may we send?" is decided.
  *
- * Always emits `orchestrator.telemetry.flush` with `{ outcome, reason }` and
- * NOTHING else — no payload, no anon_id. Per `.claude/rules/host-resources.md`
+ * Always emits `orchestrator.telemetry.flush` with `{ outcome, reason,
+ * reason_class }` and NOTHING else — no payload, no anon_id. Per
+ * `.claude/rules/host-resources.md`
  * HR-105, a mechanism whose firing rate nothing records cannot be falsified;
  * this event is what makes the flush rate measurable next time.
  *
@@ -305,13 +328,17 @@ async function flushTelemetry(projectRoot) {
       }))
       // `persistence: false` means this session leaves no durable local trace;
       // a telemetry ping is a durable record too, so it honours the same switch.
-      : { outcome: 'skipped', reason: 'persistence-disabled' };
+      // `reason_class` is spelled out on BOTH non-flush() branches so every
+      // record of this event carries the same three keys — a consumer grouping
+      // by class must not have to treat "absent" as a fourth class.
+      : { outcome: 'skipped', reason: 'persistence-disabled', reason_class: 'persistence-disabled' };
   } catch {
-    result = { outcome: 'skipped', reason: 'error' };
+    result = { outcome: 'skipped', reason: 'error', reason_class: 'error' };
   }
 
-  // `result` is passed through verbatim: it holds EXACTLY {outcome, reason}, so
-  // no payload field can leak into the event by accident.
+  // `result` is passed through verbatim: it holds EXACTLY
+  // {outcome, reason, reason_class}, so no payload field can leak into the
+  // event by accident.
   try {
     await emitEvent('orchestrator.telemetry.flush', result);
   } catch { /* observability is best-effort */ }
@@ -830,6 +857,14 @@ async function main() {
 }
 
 // Exit 0 always — informational hook must never block session teardown.
-main()
-  .catch(() => {})
-  .finally(() => process.exit(0));
+// Entry guard (#1298 P7): run only as the node script every harness execs
+// (`sh run-node.sh <this file>`); a bare `import()` must not tear down the
+// live repo's session state.
+if (isMainModule(import.meta.url)) {
+  // #1393: the profile gate sits INSIDE the entry guard — at module top level
+  // its `process.exit(0)` exited every process that merely imported this hook.
+  if (!shouldRunHook('on-session-end')) process.exit(0);
+  main()
+    .catch(() => {})
+    .finally(() => process.exit(0));
+}