session-orchestrator 3.22.0 → 3.24.0

package/hooks/on-session-start.mjs

@@ -52,6 +52,8 @@ import {
 } from '../scripts/lib/session-registry.mjs';
 import { detectColdStart, consumeMarker } from '../scripts/lib/cold-start-detector.mjs';
 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';
 
 const execFileAsync = promisify(execFile);
 
@@ -79,6 +81,19 @@ const execFileAsync = promisify(execFile);
 // re-introduce the bug.
 const bannerLines = [];
 
+/**
+ * Coordinator-directed context for the single end-of-hook flush (#1138).
+ *
+ * The banner above is for the OPERATOR (`systemMessage`); this is for the
+ * MODEL (`hookSpecificOutput.additionalContext`). Both leave in the SAME JSON
+ * object for the same reason the banner was consolidated: Claude Code surfaces
+ * only the FIRST JSON object a SessionStart hook writes to stdout, so a second
+ * `writeSync` would be silently discarded.
+ *
+ * @type {string|null}
+ */
+let pendingAdditionalContext = null;
+
 /**
  * Queue one or more banner lines for the single end-of-hook flush.
  * @param {string|null|undefined} line — multi-line strings are pushed verbatim
@@ -89,7 +104,70 @@ function pushBanner(line) {
 }
 
 /**
- * Emit every queued banner line as ONE systemMessage envelope.
+ * Render a session id compactly for a banner line.
+ *
+ * Semantic ids (`main-2026-08-23-deep-1`) are already short and are printed
+ * verbatim — they carry the branch and the mode, which is exactly what an
+ * operator needs to recognise a peer. A UUID (Claude Code's `session_id` on
+ * hosts where no semantic id was resolved) is truncated to its first 8 chars:
+ * long enough to disambiguate the handful of peers a repo can have, short
+ * enough that three of them fit on one banner line.
+ *
+ * Ceiling: 8 chars is ~4 billion values against at most a few dozen live
+ * sessions per host — revisit only if two peers ever collide in a banner.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+function shortSessionId(id) {
+  if (typeof id !== 'string' || id.length === 0) return '?';
+  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
+ * character here costs context on every session start.
+ * @param {string|null|undefined} text
+ */
+function setAdditionalContext(text) {
+  if (typeof text !== 'string' || text.length === 0) return;
+  pendingAdditionalContext = text;
+}
+
+/**
+ * Emit the queued banner lines AND any queued additionalContext as ONE JSON
+ * envelope.
+ *
+ * Both keys are valid siblings of one hook-output object: the shipped Claude
+ * Code binary (v2.1.241) documents `systemMessage` ("Display a message to the
+ * user (all hooks)") and `hookSpecificOutput.additionalContext` ("Text injected
+ * into model context") as fields of the same "Hook JSON Output" object, and its
+ * output validator recognises both keys on that one object.
  *
  * Uses `fs.writeSync(1, …)` rather than `console.log`: the top-level guard
  * calls `process.exit(0)`, which discards anything still sitting in libuv's
@@ -101,11 +179,22 @@ function pushBanner(line) {
  * Idempotent: a second call after a flush is a no-op.
  */
 function flushBanner() {
-  if (bannerLines.length === 0) return;
-  const payload = JSON.stringify({ systemMessage: bannerLines.join('\n') });
+  const hasBanner = bannerLines.length > 0;
+  const hasContext = typeof pendingAdditionalContext === 'string' && pendingAdditionalContext.length > 0;
+  if (!hasBanner && !hasContext) return;
+
+  const envelope = {};
+  if (hasBanner) envelope.systemMessage = bannerLines.join('\n');
+  if (hasContext) {
+    envelope.hookSpecificOutput = {
+      hookEventName: 'SessionStart',
+      additionalContext: pendingAdditionalContext,
+    };
+  }
   bannerLines.length = 0;
+  pendingAdditionalContext = null;
   try {
-    writeSync(1, `${payload}\n`);
+    writeSync(1, `${JSON.stringify(envelope)}\n`);
   } catch { /* stdout closed — the hook is informational and never blocks */ }
 }
 
@@ -315,6 +404,12 @@ 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;
+          }
         }
       } catch { /* absent / unparseable → no preservation (reset) */ }
     }
@@ -349,6 +444,10 @@ async function resolveSessionId(input, projectRoot) {
  *
  * Returns the candidate string on success, null on any failure. Never throws.
  *
+ * Contract (#1066, "Minimal"): the semantic id is a best-effort, host-wide
+ * monotonic LABEL, never an ownership key — ownership stays `(raw session_id,
+ * owner proof)`, and the two identity forms are never interchangeable.
+ *
  * Used by both branches of resolveSessionId() so the semantic_session_id
  * field on the session.lock is consistently populated regardless of whether
  * the SessionStart stdin payload provided a UUID (Claude Code) or nothing
@@ -359,7 +458,7 @@ async function resolveSessionId(input, projectRoot) {
  */
 async function deriveSemanticCandidate({ projectRoot, mode }) {
   try {
-    const { resolveSemanticSessionId } = await import('../scripts/lib/session-id.mjs');
+    const { resolveSemanticSessionId, parseSessionId } = await import('../scripts/lib/session-id.mjs');
     const { discoverActiveSessions } = await import('../scripts/lib/session-discovery.mjs');
     const { execSync } = await import('node:child_process');
 
@@ -387,10 +486,28 @@ async function deriveSemanticCandidate({ projectRoot, mode }) {
       discoverActiveSessions(projectRoot).catch(() => []),
       readRegistry().catch(() => []),
     ]);
-    const registrySessions = registryEntries.map((r) => ({
-      sessionId: r.session_id,
-      mode: r.mode ?? 'session',
-    }));
+
+    // Registry census (#1066 AC1): the registry keeps the two identity forms in
+    // SEPARATE fields — `session_id` is the RAW id (a UUID on Claude Code) and
+    // `semantic_session_id` is the label. resolveSemanticSessionId counts only
+    // semantic candidates, so projecting `session_id` alone made the host-wide
+    // registry contribute NOTHING to the n-increment, and two sessions on one
+    // host could mint the same label. Preference order per entry:
+    //   1. `semantic_session_id`, when it parses as semantic;
+    //   2. `session_id`, ONLY when it itself parses as semantic (Codex/Cursor
+    //      may write a semantic raw id).
+    // A legacy v1 entry (no `semantic_session_id`, UUID `session_id`) matches
+    // neither and is dropped — a UUID is never reintroduced as a candidate.
+    const semanticLabelOf = (entry) => {
+      for (const candidate of [entry?.semantic_session_id, entry?.session_id]) {
+        if (parseSessionId(candidate)?.format === 'semantic') return candidate;
+      }
+      return null;
+    };
+    const registrySessions = registryEntries.flatMap((r) => {
+      const label = semanticLabelOf(r);
+      return label === null ? [] : [{ sessionId: label, mode: r.mode ?? 'session' }];
+    });
     const activeSessions = [...localSessions, ...registrySessions];
 
     return await resolveSemanticSessionId({
@@ -467,6 +584,60 @@ async function emitHostBanner(projectRoot) {
   }
 }
 
+/**
+ * The one-time telemetry-consent instruction handed to the coordinator (#1138).
+ *
+ * Deliberately terse: it is injected into the model context on EVERY session
+ * start until the operator decides, so every character is a recurring cost.
+ * It names the phase rather than restating it, so the AUQ wording stays
+ * single-sourced in `skills/session-start/SKILL.md` § Phase 6.8.
+ */
+const CONSENT_NUDGE =
+  'Telemetrie-Consent ist auf diesem Host unentschieden. Stelle JETZT, vor jeder anderen Arbeit, '
+  + 'genau einmal die consent-neutrale AskUserQuestion aus skills/session-start/SKILL.md § Phase 6.8 '
+  + '(zwei Optionen, keine "(Recommended)"-Markierung; Codex/Cursor: nummerierte Liste) und rufe danach '
+  + 'grantConsent() bzw. denyConsent() aus scripts/lib/telemetry/consent.mjs. Danach nie wieder fragen.';
+
+/**
+ * #1138 — queue the consent nudge when, and only when, this host has no
+ * telemetry decision on record.
+ *
+ * WHY A HOOK AT ALL. Phase 6.8 was prose only: it fired when the coordinator
+ * happened to reach line ~1060 of a 1230-line skill, after 24 other phases.
+ * Measured 2026-08-23: 0 records from any host other than the author's.
+ *
+ * WHY `isCiEnv` AND NOT `isHeadless`. `isHeadless()` answers "can THIS process
+ * prompt on a TTY?" — and this process is a hook whose stdout is a pipe, so it
+ * would answer `true` unconditionally and the nudge could never fire. Measured
+ * in a plain non-TTY subprocess on this host, 2026-08-23:
+ *   `isHeadless()=true isCiEnv()=false stdout.isTTY=undefined`
+ * The question that actually matters here is a different one: "is there an
+ * operator who can answer an AskUserQuestion?" The prompting happens in the
+ * live session, not in this process, so TTY-ness of the hook is irrelevant and
+ * `isCiEnv()` — the fail-closed "this is unattended automation" probe — is the
+ * correct gate. (The same trap sits in the Phase 6.8 prose, which passes
+ * `interactive: !isHeadless()` from a `node -e` subprocess whose stdout is also
+ * a pipe: it would have resolved `prompt:false` every time even if executed.)
+ *
+ * `resolveConsent` remains the single decision point: `prompt` is true only for
+ * a host with no stored decision, no env override, and no fleet flag.
+ *
+ * Never throws — a failure here must not affect session start.
+ */
+function maybeQueueConsentNudge() {
+  try {
+    if (isCiEnv(process.env)) return;
+    const consent = resolveConsent({
+      env: process.env,
+      ownerConfig: loadOwnerConfig().config,
+      state: readTelemetryState().record,
+      interactive: true,
+    });
+    if (consent.prompt !== true) return;
+    setAdditionalContext(CONSENT_NUDGE);
+  } catch { /* best effort — the nudge is informational, never blocks */ }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -597,6 +768,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 {
@@ -698,23 +874,89 @@ 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
+        // another coordinator parked outside this working copy (e.g. under
+        // /private/tmp/…). Measured 2026-08-23: all 4 reported "peers" were the
+        // 4 registered worktrees, none of them in this checkout — and the old
+        // wording ("active in same repo") read as 4 sessions competing for THIS
+        // directory. The surface is deliberately unchanged (a foreign-worktree
+        // session IS a peer of this repo); only the label and the per-peer
+        // detail are, so the operator can tell the two apart at a glance.
         const summary = mechanicalPeers
           .slice(0, 3)
-          .map((p) => `${p.sessionId}:${p.mode ?? 'session'}`)
+          .map((p) => {
+            const where = p.worktreePath ? path.basename(p.worktreePath) : '?';
+            // #1151 — carry the peer's MODE when the source recorded one.
+            // `worktree:id` says where a peer sits but not what it is doing,
+            // and the operator's next decision (wait / promote / proceed)
+            // turns on exactly that: a `deep` peer holding this worktree set
+            // is a different situation from a `discovery` one. Guarded rather
+            // than assumed — sessionFromLock() passes `lock.mode` verbatim, so
+            // 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}${supersessionMarker(p)}`;
+          })
           .join(', ');
         const overflow = mechanicalPeers.length > 3 ? ` +${mechanicalPeers.length - 3} more` : '';
-        pushBanner(`🔍 Mechanical peer-detection: ${mechanicalPeers.length} active in same repo (${summary}${overflow})`);
+        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 */ }
   }
 
+  // Phase 4 measurement probes — the mechanical caller (#1128).
+  //
+  // `skills/session-start/SKILL.md` § Phase 4 names 18 probes with module paths
+  // and entry functions. Measured 2026-08-23 at `4f6404e`, not one of them had
+  // a caller anywhere in hooks/, npm scripts, .gitlab-ci.yml or .husky/ — the
+  // only caller was the prose itself, and across 336 recorded session starts
+  // there was no event proving any of them had ever run. Built, documented,
+  // never wired.
+  //
+  // Placement is deliberate: AFTER the backfill (so `sessions-staleness` and
+  // `sessions-integrity` measure the reconstructed ledger, not the stale one)
+  // and BEFORE flushBanner() (so probe findings ride the single systemMessage
+  // envelope instead of adding a second stdout object Claude Code would
+  // discard — see the bannerLines docstring and HR-106).
+  //
+  // Best-effort exactly like `backfillOnSessionStart` above: the runner has no
+  // rejecting path of its own, and this try/catch is defence-in-depth so a
+  // future regression inside it still cannot block a session start.
+  // Escape hatch: SO_DISABLE_STARTUP_PROBES=1.
+  //
+  // `enable-host-banner: false` silences the DISPLAY, never the MEASUREMENT.
+  // The documented opt-out ("a user who silenced session-start banners has
+  // opted out of ALL session-start banners") governs `pushBanner` and nothing
+  // else: the probes still run and `orchestrator.probes.completed` is still
+  // written, because the defect this wiring repairs is precisely that nobody
+  // could tell whether the probes had ever run (HR-105). Gating the run on a
+  // display preference would rebuild that blind spot behind a config key.
+  if (process.env.SO_DISABLE_STARTUP_PROBES !== '1') {
+    try {
+      const { runSessionStartProbes } = await import('../scripts/lib/session-start-probes.mjs');
+      const probeRun = await runSessionStartProbes({ repoRoot: projectRoot });
+      if (bannerData) {
+        for (const line of probeRun.bannerLines) pushBanner(line);
+      }
+    } 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,
   };
   if (bannerData) {
     payload.host_class = bannerData.host.host_class;
@@ -736,7 +978,16 @@ 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.
+  maybeQueueConsentNudge();
 
   // Single flush — see the bannerLines docstring for why this must stay the
   // only stdout write in the hook.