session-orchestrator 3.23.0 → 4.0.0

package/hooks/on-session-start.mjs

@@ -42,7 +42,7 @@ if (!shouldRunHook('on-session-start')) process.exit(0);
 import { emitEvent, eventsFilePath } from '../scripts/lib/events.mjs';
 import { maybeRotate } from '../scripts/lib/events-rotation.mjs';
 import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
-import { SO_PLATFORM, resolveProjectDir } from '../scripts/lib/platform.mjs';
+import { getPlatform, resolveProjectDir } from '../scripts/lib/platform.mjs';
 import {
   registerSelf,
   detectPeers,
@@ -124,6 +124,30 @@ function shortSessionId(id) {
   return id.length > 24 ? id.slice(0, 8) : id;
 }
 
+/**
+ * GH#67 — render the provenance marker for ONE mechanically-detected peer.
+ *
+ * `discoverActiveSessions()` annotates registry-sourced peers additively
+ * (`registryOnly` / `lockSuperseded` / `lockOwnerId`); lock-sourced peers carry
+ * none of the three, so they render byte-identically to the pre-GH#67 banner.
+ *
+ * `lockSuperseded: true` means a LIVE lock at THIS root is held by a different
+ * raw session_id than the registry entry — the common cause is a finished task
+ * whose SessionEnd never ran, leaving a fresh-but-orphaned registry record.
+ * It is a HINT, never a verdict: the session lock is advisory, so the entry may
+ * equally be a live peer that lost the acquire race (#1085). The marker is
+ * therefore purely additive — it never removes the peer, and never changes the
+ * count or the WARN decision (HR-106).
+ *
+ * @param {{registryOnly?:boolean, lockSuperseded?:boolean, lockOwnerId?:string|null}} peer
+ * @returns {string} '' for a lock-sourced peer, else a bracketed marker.
+ */
+function supersessionMarker(peer) {
+  if (!peer || peer.registryOnly !== true) return '';
+  if (peer.lockSuperseded === true) return ' [registry-only, superseded]';
+  return ' [registry-only]';
+}
+
 /**
  * Queue the ONE `additionalContext` string for the single end-of-hook flush.
  * Last writer wins; there is deliberately no accumulation, because every
@@ -380,6 +404,19 @@ async function resolveSessionId(input, projectRoot) {
           if (Object.prototype.hasOwnProperty.call(prev, 'last_batch')) {
             preserved.last_batch = prev.last_batch;
           }
+          // #1193 — the final-wave completion marker must survive a
+          // clear/compact too: dropping it re-arms a duplicate SessionEnd
+          // `orchestrator.wave.completed` for a wave already closed.
+          if (Object.prototype.hasOwnProperty.call(prev, 'last_wave_completed')) {
+            preserved.last_wave_completed = prev.last_wave_completed;
+          }
+          // #980 — the OPEN half of the wave-diff pair, written by
+          // post-tool-batch-wave-signal.mjs. Dropping it across a /clear leaves
+          // the running wave with no start point, so the next
+          // `orchestrator.wave.completed` silently omits `files_changed`.
+          if (Object.prototype.hasOwnProperty.call(prev, 'wave_start_sha')) {
+            preserved.wave_start_sha = prev.wave_start_sha;
+          }
         }
       } catch { /* absent / unparseable → no preservation (reset) */ }
     }
@@ -675,7 +712,15 @@ async function main() {
   // must never break the hook, which is informational-only.
   const input = await stdinPromise;
   const { sessionId, semanticSessionId, mode } = await resolveSessionId(input, projectRoot);
-  const platform = process.env.SO_PLATFORM ?? SO_PLATFORM;
+  // getPlatform() ALREADY implements the SO_PLATFORM override as step 1 of its
+  // precedence — and, unlike a bare `??`, it validates the value against the
+  // four-platform allowlist and trims it. The former `process.env.SO_PLATFORM ??
+  // getPlatform()` therefore added nothing except the empty-string trap
+  // (`.claude/rules/development.md` § Env-var fallback whitespace trap): a key
+  // exported as `SO_PLATFORM=` is not nullish, so `??` short-circuited and this
+  // hook stamped `platform: ''` on the session event and handed '' down to the
+  // update probe. Measured 2026-09-06 by the codex test below.
+  const platform = getPlatform();
 
   // Epic #583 P3 — mechanical session.lock writer (closes D1+D2+D4 gaps).
   // Bootstrap the session-lock so discoverActiveSessions() picks us up even
@@ -738,6 +783,11 @@ async function main() {
   } catch { /* hook must remain non-blocking */ }
 
   let peers = [];
+  // GH#67 consumer half — how many mechanically-detected peers were registry-
+  // sourced entries that a LIVE lock at this root supersedes. Counted for the
+  // session.started payload below; NEVER subtracted from any peer count
+  // (HR-106: the banner reports the number the verdict judged).
+  let mechanicalPeersSuperseded = 0;
   try {
     await sweepZombies().catch(() => ({ removed: [], logged: 0 }));
     try {
@@ -839,6 +889,7 @@ async function main() {
       const { discoverActiveSessions } = await import('../scripts/lib/session-discovery.mjs');
       const allActive = await discoverActiveSessions(projectRoot);
       const mechanicalPeers = allActive.filter((s) => s.sessionId !== sessionId);
+      mechanicalPeersSuperseded = mechanicalPeers.filter((p) => p.lockSuperseded === true).length;
       if (mechanicalPeers.length > 0) {
         // #1137 part 1 — say WHERE, not just how many. discoverActiveSessions()
         // walks EVERY path `git worktree list` reports, which includes worktrees
@@ -862,11 +913,14 @@ async function main() {
             // a lock written without the field yields undefined here, while
             // sessionFromRegistryEntry() always defaults it to 'session'.
             const mode = typeof p.mode === 'string' && p.mode.length > 0 ? `:${p.mode}` : '';
-            return `${where}:${shortSessionId(p.sessionId)}${mode}`;
+            return `${where}:${shortSessionId(p.sessionId)}${mode}${supersessionMarker(p)}`;
           })
           .join(', ');
         const overflow = mechanicalPeers.length > 3 ? ` +${mechanicalPeers.length - 3} more` : '';
         pushBanner(`🔍 Mechanical peer-detection: ${mechanicalPeers.length} active in this repo's worktree set (${summary}${overflow})`);
+        if (mechanicalPeersSuperseded > 0) {
+          pushBanner(`   ${mechanicalPeersSuperseded} of them registry-only and superseded by this root's live lock — likely a finished task without SessionEnd (GH#67). Still counted above: the session lock is advisory.`);
+        }
       }
     } catch { /* best effort — banner is informational, never blocks */ }
   }
@@ -908,13 +962,79 @@ async function main() {
     } catch { /* hook must remain non-blocking */ }
   }
 
+  // Plugin-update probe (#nnn, d7 R2) — "is the plugin that is RUNNING behind
+  // the plugin that is PUBLISHED?".
+  //
+  // MEASURED 2026-09-06: this host ran the marketplace-cache copy at 3.19.0
+  // (installed 2026-08-09) while repo and npm stood at the 3.24 line — five minors,
+  // four weeks, zero warnings, because NO code anywhere compared installed
+  // against available (`grep -rln "registry.npmjs.org\|dist-tags" scripts/
+  // hooks/ skills/` → only scripts/release.mjs, the publisher).
+  //
+  // Placement mirrors the probe block above: BEFORE the payload (the event
+  // carries both versions) and BEFORE flushBanner(), so the line rides the ONE
+  // systemMessage envelope. A second stdout object would be silently discarded
+  // (HR-106) — the failure mode the bannerLines docstring describes.
+  //
+  // Same measurement/display split as the probes: the request and the event
+  // fields happen regardless, `pushBanner` is gated on `bannerData`. Network,
+  // cache and kill-switch behaviour live in the module.
+  let pluginUpdate = null;
+  try {
+    const { checkPluginUpdate } = await import('../scripts/lib/plugin-update-banner.mjs');
+    pluginUpdate = await checkPluginUpdate({
+      cacheDir: path.join(projectRoot, '.orchestrator', 'runtime'),
+      // The probe's own fallback is env-only (SO_PLATFORM, then each harness's
+      // compat var) and cannot run detectPlatform()'s third step, the marker-
+      // directory walk from cwd. This hook already resolved the platform at the
+      // top of run() through exactly that full precedence, so handing it over
+      // makes the remedy instruction MEASURED rather than guessed — a Codex or
+      // Cursor consumer with no compat var set would otherwise be told to run
+      // `/plugin update`, a command its harness does not have.
+      platform,
+    });
+    if (pluginUpdate && bannerData) pushBanner(pluginUpdate.message);
+  } catch { /* hook must remain non-blocking */ }
+
   const payload = {
     platform,
     project: projectName,
     branch,
     session_id: sessionId,
     peer_count: peers.length,
+    // GH#67 — additive: how many mechanically-detected peers a live lock at
+    // this root supersedes. `peer_count` is deliberately unchanged; this field
+    // makes the supersession rate measurable instead of inferred (HR-105).
+    peers_superseded: mechanicalPeersSuperseded,
   };
+
+  // #nnn — installed/latest plugin version on the session record.
+  //
+  // HR-105: a verdict nothing records is unfalsifiable. `installed` is stamped
+  // on EVERY start (it is a local file read that cannot fail for network
+  // reasons), and `latest` whenever it is known — including the runs where
+  // checkPluginUpdate() stayed silent because the versions matched. Those runs
+  // are the DENOMINATOR of the probe's firing rate; without them the fleet can
+  // only ever see how often it warned, never how often it could have.
+  //
+  // Both keys are OMITTED rather than nulled when unknown (docs/events-schema.md
+  // optional-field convention: absent ≠ zero) — a kill-switched or offline
+  // session must not read as "latest is 0/unknown-but-measured".
+  try {
+    const { readInstalledPluginVersion, readCachedLatest, isUpdateCheckDisabled } =
+      await import('../scripts/lib/plugin-update-banner.mjs');
+    const installedVersion = readInstalledPluginVersion();
+    if (installedVersion) payload.plugin_version_installed = installedVersion;
+    // `latest` is gated on the kill switch, `installed` is not: reading this
+    // repo's own package.json is not the thing an operator switched off.
+    if (!isUpdateCheckDisabled()) {
+      const latestVersion =
+        pluginUpdate?.latest
+        ?? readCachedLatest({ cacheDir: path.join(projectRoot, '.orchestrator', 'runtime') })?.version
+        ?? null;
+      if (latestVersion) payload.plugin_version_latest = latestVersion;
+    }
+  } catch { /* telemetry never blocks the hook */ }
   if (bannerData) {
     payload.host_class = bannerData.host.host_class;
     payload.ram_free_gb = bannerData.resources.ram_free_gb;
@@ -935,7 +1055,12 @@ async function main() {
     payload.memory_pressure_pct_free = bannerData.resources.memory_pressure_pct_free ?? null;
     payload.peer_sessions_count = bannerData.resources.peer_sessions_count ?? null;
   }
-  await emitEvent('orchestrator.session.started', payload);
+  // #1183 — a malformed record throws EventValidationError BEFORE any side
+  // effect (scripts/lib/events.mjs); this hook must never abort on that, so
+  // the emit is wrapped rather than left to propagate.
+  try {
+    await emitEvent('orchestrator.session.started', payload);
+  } catch { /* telemetry never blocks the hook (#1183) */ }
 
   // #1138 — one-time telemetry-consent nudge. Queued (never written) here so it
   // rides the single stdout envelope below.
@@ -945,6 +1070,30 @@ async function main() {
   // only stdout write in the hook.
   flushBanner();
 
+  // #1229 — refresh the session-lock heartbeat at the END of this hook's run.
+  //
+  // MEASURED (STATE.md deviation 2026-09-05T06:08:46Z): session-20's lock was
+  // reaped as stale at 06:06Z by an UNRELATED session's SessionEnd, its
+  // heartbeat 11.3 h old against a 4 h TTL. The session was not idle — it was
+  // still inside session-start / session-plan, where no heartbeat writer
+  // existed: `updateHeartbeat()` was called only from the wave loop, from
+  // on-stop and from session-end. A session that never reached /go therefore
+  // aged out of its own lock while working.
+  //
+  // bootstrapLock() above stamps `last_heartbeat = started_at` at LOCK GENESIS,
+  // i.e. before the peer scan, the backfill and the Phase-4 probes have run.
+  // Stamping again here moves the clock to the end of the hook and — more
+  // importantly — makes session-start a heartbeat CALL SITE at all, so the
+  // cadence no longer begins only when the first wave starts.
+  //
+  // `updateHeartbeat()` already carries the same-session guard this needs (it
+  // returns false without writing when the lock belongs to another session),
+  // so no `touchIfOwn()` wrapper is warranted — see scripts/lib/session-lock.mjs.
+  try {
+    const { updateHeartbeat } = await import('../scripts/lib/session-lock.mjs');
+    updateHeartbeat({ repoRoot: projectRoot, sessionId });
+  } catch { /* hook must remain non-blocking */ }
+
   // 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.