session-orchestrator 3.20.0 → 3.22.0

package/hooks/on-stop.mjs

@@ -8,7 +8,10 @@
  *
  * Part of v3.0.0 Windows-native migration. Issue #141.
  *
- * Exit codes: 0 always (informational hooks must never block).
+ * Exit codes: 0 always (informational hooks must never block) — including when
+ * node_modules is absent: zx is imported lazily and a missing package degrades
+ * to one rate-limited stderr line instead of an ERR_MODULE_NOT_FOUND stack on
+ * every turn end (GH Kanevry/session-orchestrator#63).
  *
  * JSONL format (`.orchestrator/metrics/events.jsonl`) — emitted via the canonical
  * `emitEvent()` so the JSONL record and the optional Clank webhook always carry the
@@ -18,8 +21,7 @@
  */
 
 import path from 'node:path';
-import { promises as fs } from 'node:fs';
-import { $ } from 'zx';
+import { promises as fs, statSync, writeFileSync } from 'node:fs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 // #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
@@ -27,7 +29,7 @@ if (!shouldRunHook('on-stop')) process.exit(0);
 
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
-import { deregisterSelf, logSweepEvent } from '../scripts/lib/session-registry.mjs';
+import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { updateHeartbeat } from '../scripts/lib/session-lock.mjs';
 
 // ---------------------------------------------------------------------------
@@ -87,17 +89,87 @@ function discriminate(input) {
   return 'stop';
 }
 
+// ---------------------------------------------------------------------------
+// dependency degradation (GH Kanevry/session-orchestrator#63)
+// ---------------------------------------------------------------------------
+//
+// zx is loaded LAZILY. A static `import { $ } from 'zx'` fails at MODULE LOAD
+// time when node_modules is absent (interrupted install, EPERM sandbox, half-
+// synced plugin cache), so the harness prints a 10-frame ERR_MODULE_NOT_FOUND
+// stack on EVERY turn end with no hint that `npm install` is the fix. This
+// mirrors the missing-`node` degradation in hooks/run-node.sh (§5): one
+// actionable stderr line per 6h window, then carry on with reduced features.
+
+/** Rate-limit window for the dependencies-missing warning — mirrors run-node.sh's 6h TTL. */
+const DEP_WARN_TTL_MS = 6 * 60 * 60 * 1000;
+
+/** Plugin root (the directory that owns package.json / node_modules). */
+const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
+
+/**
+ * Marker path for the dependencies-missing warning. Deliberately a DIFFERENT
+ * name from run-node.sh's `session-orchestrator-node-missing-*`: sharing one
+ * marker would let a missing-node warning mask a missing-deps warning (and
+ * vice versa), leaving the operator with half a diagnostic.
+ * @returns {string}
+ */
+function depWarnMarkerPath() {
+  // `||` alone falls back only on falsy values — a whitespace-only TMPDIR is
+  // truthy and would yield a garbage path (see .claude/rules/development.md).
+  const tmpDir = (process.env.TMPDIR || '').trim() || '/tmp';
+  const user = (process.env.USER || '').trim() || 'uid';
+  return path.join(tmpDir, `session-orchestrator-deps-missing-${user}`);
+}
+
+/**
+ * Print ONE actionable stderr line telling the operator to run `npm install`,
+ * at most once per DEP_WARN_TTL_MS. Marker mtime is the clock, exactly like
+ * run-node.sh's `find -mmin +360` check. Best-effort throughout: a marker we
+ * cannot stat is treated as expired (warn), a marker we cannot write means the
+ * next invocation warns again — noisier, never silent-broken.
+ */
+function warnDependenciesMissingOnce() {
+  const marker = depWarnMarkerPath();
+  try {
+    if (Date.now() - statSync(marker).mtimeMs < DEP_WARN_TTL_MS) return;
+  } catch { /* missing / unreadable marker → treat as expired */ }
+  try { writeFileSync(marker, ''); } catch { /* best-effort */ }
+  process.stderr.write(
+    `session-orchestrator: dependencies missing — run 'npm install' in ${PLUGIN_ROOT}. `
+    + 'Hook features degraded (this warning is rate-limited to once per 6h).\n',
+  );
+}
+
+/**
+ * Load zx's `$` lazily. Returns null when the package is not installed (after
+ * emitting the rate-limited advisory). Any OTHER import failure is re-thrown —
+ * a corrupt zx install is not a missing-dependency problem and must not be
+ * mislabelled as one.
+ * @returns {Promise<Function|null>}
+ */
+async function loadZx() {
+  try {
+    return (await import('zx')).$;
+  } catch (err) {
+    if (err?.code !== 'ERR_MODULE_NOT_FOUND') throw err;
+    warnDependenciesMissingOnce();
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // git helpers
 // ---------------------------------------------------------------------------
 
 /**
  * Returns { commit, branch } from the git repo at projectRoot, or null values
- * if git is unavailable or the directory is not a git repo.
+ * if git is unavailable, zx is not installed, or the directory is not a git repo.
  * @param {string} projectRoot — working directory for git commands
  * @returns {Promise<{commit:string|null, branch:string|null}>}
  */
 async function gitInfo(projectRoot) {
+  const $ = await loadZx();
+  if ($ === null) return { commit: null, branch: null };
   $.verbose = false;
   $.quiet = true;
   const opts = projectRoot ? { cwd: projectRoot } : {};
@@ -180,16 +252,59 @@ async function handleStop(input) {
 
   const sessionId = await resolveSessionId(input, projectRoot);
 
-  // v3.1.0 multi-session registry (#169) — best-effort deregister. Missing
-  // entry is fine (zombie sweep handles crashed sessions). Failures are logged
-  // to sweep.log for observability but never re-thrown (hook must remain silent).
+  // v3.1.0 multi-session registry (#169), corrected in #1047 — REFRESH the
+  // registry entry here; never remove it.
+  //
+  // Stop fires at TURN end, not session end (see the file docblock). The
+  // original #169 wiring called deregisterSelf() here, so every assistant turn
+  // deleted this session's registry entry while the session was still live:
+  // measured on this host as 1 surviving entry (dead PID) against 12 live
+  // sockets, with sweep.log recording deletions of sessions aged 72/335/351/369
+  // minutes. Epic #583 fixed exactly this class for `.orchestrator/session.lock`
+  // (release → updateHeartbeat, below); the host registry never got the same
+  // correction. Deregistration now lives in hooks/on-session-end.mjs, which
+  // fires at the real end of the session.
+  //
+  // CODEX CAVEAT — stated here because THIS file runs on Codex and the file
+  // that owns deregistration does not. `hooks-codex.json` wires SessionStart +
+  // Stop but no SessionEnd (the Codex contract rejects the event), so on that
+  // bridge a session registers and never deregisters: its entry persists until
+  // sweepZombies() reaps it at the next SessionStart, up to `thresholdMin`
+  // (default 60 min). Accepted deliberately — it is the same path crash and
+  // Ctrl-C already take on every platform, and it is safe precisely BECAUSE
+  // the heartbeat below now advances, so a live session never ages into the
+  // sweep. Do NOT add a platform-detecting deregister branch here; that is the
+  // two-teardown-paths shape Epic #583 removed from the lock.
+  // (pi is unaffected: hooks-pi.json maps session_shutdown to on-session-end.mjs.
+  //  Cursor is unaffected: it wires no SessionStart, so it never registers.)
+  //
+  // Failures are logged to sweep.log for observability but never re-thrown
+  // (hook must remain silent and non-blocking).
   if (sessionId) {
     try {
-      await deregisterSelf(sessionId);
+      // heartbeat() returns null when no entry exists — a SILENT no-op that
+      // would otherwise make the loss permanent for the rest of the session
+      // (e.g. after a zombie sweep, or a harness UUID rotation with no fresh
+      // SessionStart). We do NOT re-register here: this hook has no access to
+      // the entry's platform / mode / host_class, and a re-registration would
+      // reset started_at to now — fabricating a session age instead of
+      // reporting one. Emit an observability breadcrumb instead, so the miss
+      // is visible in sweep.log rather than invisible. One line per turn while
+      // the entry is absent; that volume IS the signal, and the next
+      // SessionStart's registerSelf() ends it.
+      const refreshed = await heartbeat(sessionId);
+      if (refreshed === null) {
+        logSweepEvent({
+          event: 'heartbeat-missing',
+          session_id: sessionId,
+          error: 'no registry entry to refresh at turn end',
+        });
+      }
     } catch (err) {
-      // Deregistration failed — emit an observability breadcrumb to sweep.log.
-      // Do NOT throw, do NOT write to stderr: the hook is informational-only.
-      logSweepEvent({ event: 'deregister-failed', session_id: sessionId, error: err?.message ?? String(err) });
+      // Refresh failed at the fs layer — emit an observability breadcrumb to
+      // sweep.log. Do NOT throw, do NOT write to stderr: the hook is
+      // informational-only.
+      logSweepEvent({ event: 'heartbeat-failed', session_id: sessionId, error: err?.message ?? String(err) });
     }
 
     // Epic #583 W5-F1c — refresh session.lock heartbeat on every turn-end.

package/hooks/post-bash-write-verify.mjs

@@ -154,6 +154,13 @@ import { readFileSync, mkdirSync, writeFileSync, renameSync, realpathSync, statS
 import { readStdin, writeStdoutLineSync } from '../scripts/lib/io.mjs';
 import { resolveProjectDir } from '../scripts/lib/platform.mjs';
 import { findScopeFile, pathMatchesPattern } from '../scripts/lib/hardening.mjs';
+// #1057 — `sessionAgeMs` and its private `clockAgeMs` helper MOVED to the lib so
+// hooks/enforce-scope.mjs can read the same session clock without a hook->hook
+// import. Re-exported below, so this hook's public surface — and
+// tests/hooks/post-bash-write-verify.test.mjs, which imports the named export —
+// is unchanged. Two byte-identical copies of a clock is exactly the one-fact-two-
+// copies class this repo keeps paying for.
+import { sessionAgeMs } from '../scripts/lib/scope-gate.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -538,30 +545,6 @@ function readDirtyPaths(repoRoot) {
   }
 }
 
-/**
- * Age in ms of one session clock: a JSON file carrying an ISO start timestamp.
- *
- * Never throws. Absent / unparseable / non-string / non-ISO ⇒ null. A NEGATIVE
- * age (timestamp in the future) is also null rather than a negative number —
- * see `sessionAgeMs` for why that matters once two clocks are combined.
- *
- * @param {string} file  absolute path to the JSON file
- * @param {string} field name of the ISO-timestamp property
- * @param {number} now
- * @returns {number|null}
- */
-function clockAgeMs(file, field, now) {
-  try {
-    const parsed = JSON.parse(readFileSync(file, 'utf8'));
-    const startedAt = Date.parse(parsed?.[field]);
-    if (!Number.isFinite(startedAt)) return null;
-    const age = now - startedAt;
-    return age >= 0 ? age : null;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Milliseconds since the current session started, or null when unknown — the
  * MINIMUM of two independently-written session clocks (#957 finding 2):
@@ -634,14 +617,7 @@ function clockAgeMs(file, field, now) {
  * @param {number} [now]
  * @returns {number|null}
  */
-export function sessionAgeMs(repoRoot, now = Date.now()) {
-  const dir = path.join(repoRoot, '.orchestrator');
-  const ages = [
-    clockAgeMs(path.join(dir, 'current-session.json'), 'timestamp', now),
-    clockAgeMs(path.join(dir, 'session.lock'), 'started_at', now),
-  ].filter((age) => age !== null);
-  return ages.length > 0 ? Math.min(...ages) : null;
-}
+export { sessionAgeMs };
 
 /** @returns {object|null} */
 function readSnapshot(file) {