session-orchestrator 5.1.0 → 5.3.0

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.1.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.1.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 */ }
@@ -618,8 +645,20 @@ async function main() {
   //     Dead-by-age relaxation (relaxDeadByAge/assumeDeadBeforeMs, #731 — used by the
   //     historical migration CLI) is NEVER passed here: a foreign lock that is live
   //     at hook-time is, by definition, a real active session, not stale history.
+  //     `ownSessionIsEnding` (#1376) rides the SAME `isRecordedSession`
+  //     attestation as `duration_ms` / `semantic_session_id` above, for the
+  //     same reason: it is a claim made ON BEHALF of the recorded session, and
+  //     a foreign terminating window that inherited this repo's
+  //     `current-session.json` identity (#863 defect (b)) must never make it.
+  //     With the attestation false the core keeps its blanket own-live-lock
+  //     skip, so the #863 behaviour is preserved exactly where #863 applied.
   try {
-    const res = await backfillAbandonedSession({ repoRoot: projectRoot, sessionId, semanticSessionId });
+    const res = await backfillAbandonedSession({
+      repoRoot: projectRoot,
+      sessionId,
+      semanticSessionId,
+      ownSessionIsEnding: isRecordedSession,
+    });
     await emitBackfillOutcome('abandoned', res, { sessionId, semanticSessionId });
   } catch { /* best-effort — never block teardown */ }
 
@@ -627,7 +666,7 @@ async function main() {
   //      above and to THIS session's own id: it reads STATE.md directly and
   //      repairs a PAST session whose `status: completed` was set (by hand or
   //      otherwise) without session-end's Phase 3.7 ever writing the matching
-  //      sessions.jsonl record — the exact state `commands/close.md`'s
+  //      sessions.jsonl record — the exact state `skills/close/SKILL.md`'s
   //      Pre-Check then reads as "already finalized" forever after. Cheap
   //      no-op on the overwhelmingly common path (STATE.md status is
   //      'active'/'paused'/'idle', or the record already exists).
@@ -818,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));
+}

package/hooks/on-session-start.mjs

@@ -36,8 +36,6 @@ import { randomUUID } from 'node:crypto';
 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-start')) process.exit(0);
 
 import { emitEvent, eventsFilePath } from '../scripts/lib/events.mjs';
 import { maybeRotate } from '../scripts/lib/events-rotation.mjs';
@@ -54,6 +52,7 @@ import { detectColdStart, consumeMarker } from '../scripts/lib/cold-start-detect
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { readTelemetryState, resolveConsent, isCiEnv } from '../scripts/lib/telemetry/consent.mjs';
 import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 // SSOT for the "is this a re-entry into the same logical session?" question
 // (#1091). Defined in the lock-bootstrap leaf module, which this hook already
 // loads, so the preservation branch below and the lock force-refresh gate can
@@ -453,8 +452,10 @@ async function resolveSessionId(input, projectRoot) {
     // observe. A naive full overwrite of current-session.json drops the
     // `last_wave` / `last_batch` markers written mid-session by
     // post-tool-batch-wave-signal.mjs, which makes the next PostToolBatch
-    // re-read last_wave as absent→0 and re-emit a duplicate
-    // orchestrator.wave.started{N} with no intervening wave.completed.
+    // re-read last_wave as absent→0 and RE-OPEN wave N mid-wave, re-stamping
+    // wave_start_sha and so moving the #980 files_changed start point. (Until
+    // 2026-09-19 it also re-emitted a duplicate wave.started{N}; that event
+    // has since been removed.)
     //
     // Three cases, exactly one of which preserves nothing:
     //   'raw-id'   — same-logical-session source AND the recorded raw
@@ -764,8 +765,12 @@ async function main() {
   // v3.1.0 env-aware banner (opt-out via enable-host-banner: false in Session Config).
   // The ask-via-tool nudge rides the same opt-out flag — both are coordinator
   // reminders shown at session start; users who silence one expect silence.
+  // Hoisted because the cold-start DISPLAY below rides the same opt-out (#1133)
+  // and `bannerData` is not a usable proxy for it: `emitHostBanner()` returns
+  // null on its own error paths, which would silently re-open the nudge.
+  const hostBannerEnabled = await isHostBannerEnabled(projectRoot);
   let bannerData = null;
-  if (await isHostBannerEnabled(projectRoot)) {
+  if (hostBannerEnabled) {
     bannerData = await emitHostBanner(projectRoot);
     // Always-on nudge: a user decision has three legitimate forms and AUQ-001
     // routes between them in order — operator verb first (nothing is blocked
@@ -795,7 +800,14 @@ async function main() {
         enabled: coldStartCfg.enabled !== false,
       });
       if (decision.shouldEmit) {
-        pushBanner(decision.bannerLines.join('\n'));
+        // #1133 — the DISPLAY rides the enable-host-banner opt-out like every
+        // other start-of-session emitter ("users who silence one expect
+        // silence"). The one-shot marker consumption below does NOT: the
+        // opt-out silences the display, never the measurement or the state
+        // transition. Consuming it unconditionally is what keeps the nudge
+        // one-shot for an operator who has banners off — otherwise it re-arms
+        // on every start forever.
+        if (hostBannerEnabled) pushBanner(decision.bannerLines.join('\n'));
         if (decision.markerPath) {
           await consumeMarker(decision.markerPath).catch(() => false);
         }
@@ -1219,6 +1231,14 @@ async function main() {
   // Size-based rotation of events.jsonl (#251). Session-start is the single
   // rotation trigger — per-append overhead is rejected design. Any failure
   // is swallowed: rotation must NEVER block the hook.
+  //
+  // #1401 — the DURABLE record of a rotation is no longer this block. Until
+  // 2026-09-19 the only evidence a rotation had happened was the `console.error`
+  // below, and this hook's stderr is discarded by the harness: a rotation and a
+  // DELETED archive were byte-identical from outside. `maybeRotate()` now writes
+  // an `orchestrator.events.rotated` record as the first line of the new active
+  // file, so the ledger carries its own break whatever happens to this stderr
+  // line. The line stays as an operator convenience only — never as the record.
   try {
     let rotCfg = { enabled: true, 'max-size-mb': 10, 'max-backups': 5 };
     try {
@@ -1234,7 +1254,13 @@ async function main() {
       enabled: rotCfg.enabled !== false,
     });
     if (result.rotated) {
-      console.error(`events-rotation: archived ${result.archivedAs} (${result.sizeBefore} bytes)`);
+      const pruned = result.pruned?.length ? `, pruned ${result.pruned.length}` : '';
+      const ledger = result.recordWritten ? '' : ' [WARN: rotation record NOT written]';
+      console.error(
+        `events-rotation: archived ${result.archivedAs} ` +
+          `(${result.sizeBefore} bytes, ${result.lines ?? '?'} lines, ` +
+          `${result.firstTs ?? 'unknown'} → ${result.lastTs ?? 'unknown'}${pruned})${ledger}`,
+      );
     }
   } catch (err) {
     console.error(`events-rotation: skipped (${err?.message ?? err})`);
@@ -1245,7 +1271,18 @@ async function main() {
 // flushBanner() runs here too so a throw partway through main() still surfaces
 // whatever was already collected; it is idempotent, so the normal path (which
 // flushes at the end of main) does not double-emit.
-main().catch(() => {}).finally(() => {
-  flushBanner();
-  process.exit(0);
-});
+//
+// Entry guard (#1298 P7): every harness execs this file as the node script
+// (`sh run-node.sh <this file>` → `exec node "$@"`), so argv[1] IS this module
+// on every real path. A bare `import()` — a probe, a test, a curious agent —
+// must not run main() against the live repo: incident W4-FX1 overwrote
+// `.orchestrator/current-session.json` exactly that way.
+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-start')) process.exit(0);
+  main().catch(() => {}).finally(() => {
+    flushBanner();
+    process.exit(0);
+  });
+}