session-orchestrator 3.21.0 → 3.23.0

package/hooks/on-stop.mjs

@@ -16,7 +16,8 @@
  * JSONL format (`.orchestrator/metrics/events.jsonl`) — emitted via the canonical
  * `emitEvent()` so the JSONL record and the optional Clank webhook always carry the
  * SAME dotted event name (was: bare `stop`/`subagent_stop` in JSONL vs dotted in webhook):
- *   Stop:        {"timestamp":<ISO>,"event":"orchestrator.session.stopped","session_id":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>}
+ *   Stop:        {"timestamp":<ISO>,"event":"orchestrator.session.stopped","session_id":"...","semantic_session_id":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>}
+ *                (`session_id` / `semantic_session_id` are omitted when unresolvable — #1068 AC1.)
  *   SubagentStop: {"timestamp":<ISO>,"event":"orchestrator.agent.stopped","agent":"<name>"}
  */
 
@@ -29,6 +30,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 { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { updateHeartbeat } from '../scripts/lib/session-lock.mjs';
 
@@ -216,17 +218,39 @@ async function readWaveNumber(projectRoot) {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve this session's id. Stdin payload wins. If Claude Code did not pass
- * one (Codex / Cursor paths, or older harnesses), fall back to
- * `.orchestrator/current-session.json` which on-session-start.mjs writes.
+ * Resolve this session's id + its attested semantic id. A stdin payload id wins
+ * ONLY when it parses as a UUID. If Claude Code did not pass one (Codex /
+ * Cursor paths, or older harnesses) — or passed something that is not a UUID —
+ * fall back to `.orchestrator/current-session.json` which on-session-start.mjs
+ * writes.
+ *
+ * #1091 / Kanevry#66 — WRITER/READER SYMMETRY, same defect class as
+ * `hooks/on-session-end.mjs`: `on-session-start.mjs` accepts a stdin raw id
+ * only when `parseSessionId(fromStdin)?.format === 'uuid'` and otherwise mints
+ * a `randomUUID()`, so every artifact this hook then addresses by id (the host
+ * registry entry, `session.lock`) is keyed by a UUID. Passing a non-UUID stdin
+ * string through meant `heartbeat()` and `updateHeartbeat()` addressed a key
+ * that was never written: the registry entry silently went un-refreshed (and
+ * aged into the zombie sweep) while the lock heartbeat no-oped on an ownership
+ * mismatch.
+ *
+ * `semanticSessionId` (#1068 AC1) is read from the SAME file and is deliberately
+ * gated on the resolved id BEING the recorded one — `current-session.json` is a
+ * single repo-global file describing whichever session most recently ran
+ * SessionStart, so an unrelated window's turn-end must not inherit a live
+ * peer's semantic identity (the #863 defect (c) contamination shape, mirrored
+ * here from `hooks/on-session-end.mjs`).
  *
  * @param {object|null} input
  * @param {string} projectRoot
- * @returns {Promise<string|null>}
+ * @returns {Promise<{sessionId: string|null, semanticSessionId: string|null}>}
  */
 async function resolveSessionId(input, projectRoot) {
   const fromStdin = input?.session_id ?? input?.sessionId ?? null;
-  if (typeof fromStdin === 'string' && fromStdin.length > 0) return fromStdin;
+  let sessionId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
+
+  let recordedId = null;
+  let semanticSessionId = null;
   try {
     const raw = await fs.readFile(
       path.join(projectRoot, '.orchestrator', 'current-session.json'),
@@ -234,10 +258,20 @@ async function resolveSessionId(input, projectRoot) {
     );
     const parsed = JSON.parse(raw);
     if (typeof parsed.session_id === 'string' && parsed.session_id.length > 0) {
-      return parsed.session_id;
+      recordedId = parsed.session_id;
+    }
+    if (typeof parsed.semantic_session_id === 'string' && parsed.semantic_session_id.length > 0) {
+      semanticSessionId = parsed.semantic_session_id;
     }
   } catch { /* missing or unparseable is fine */ }
-  return null;
+
+  if (sessionId === null) sessionId = recordedId;
+
+  const isRecordedSession = sessionId !== null && sessionId === recordedId;
+  return {
+    sessionId,
+    semanticSessionId: isRecordedSession ? semanticSessionId : null,
+  };
 }
 
 /**
@@ -250,7 +284,7 @@ async function handleStop(input) {
   const wave = await readWaveNumber(projectRoot);
   const { commit, branch } = await gitInfo(projectRoot);
 
-  const sessionId = await resolveSessionId(input, projectRoot);
+  const { sessionId, semanticSessionId } = await resolveSessionId(input, projectRoot);
 
   // v3.1.0 multi-session registry (#169), corrected in #1047 — REFRESH the
   // registry entry here; never remove it.
@@ -323,8 +357,13 @@ async function handleStop(input) {
   // Single emission path: emitEvent writes the canonical {timestamp, event, ...payload}
   // JSONL record AND fires the optional Clank webhook with the SAME event name — no
   // more bare-`stop` (JSONL) vs dotted-`stopped` (webhook) divergence.
+  // #1068 AC1 — carry the attested semantic id alongside the raw UUID so a
+  // turn-end outcome is joinable by identity from events.jsonl alone. Omitted
+  // (never `""`/`null`) when unattested: an unresolved identity stays visibly
+  // unresolved rather than becoming a guessed id.
   await emitEvent('orchestrator.session.stopped', {
     ...(sessionId !== null ? { session_id: sessionId } : {}),
+    ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
     wave,
     ...(branch !== null ? { branch } : {}),
     ...(commit !== null ? { commit } : {}),

package/hooks/post-subagent-discovery-validator.mjs

@@ -30,6 +30,19 @@
  * Why read the transcript: the SubagentStop stdin payload has NO output_text
  * field. The agent's text lives in `input.transcript_path`.
  *
+ * Output channels — THREE writes, TWO different recipients:
+ *   - `discovery_validator_violation` in .orchestrator/metrics/events.jsonl,
+ *     and the stderr WARN → the COORDINATOR's only copy of the finding. PSA-006
+ *     makes REJECTING the unverified claim his duty, so these two are the
+ *     channels that carry the rule's enforcement path.
+ *   - stdout `hookSpecificOutput.additionalContext` → the STOPPING SUBAGENT
+ *     (which continues and may self-correct), NOT the coordinator — a hook is
+ *     structurally unable to address him. See the measured delivery note at the
+ *     hookSpecificOutput write below for the shipped-binary evidence.
+ *   All three are pinned together by the "all three channels fire" test in
+ *   tests/hooks/post-subagent-discovery-validator.test.mjs — do not collapse
+ *   the coordinator-visible pair into additionalContext.
+ *
  * Exit codes: 0 always (informational, never blocking).
  */
 
@@ -594,12 +607,30 @@ async function main() {
   }
 
   if (alreadyWarned) {
-    // Events logged above; suppress additionalContext to prevent coordinator loop.
+    // Events logged above; suppress the repeat additionalContext for this
+    // already-warned real context. (Recipient is the stopping subagent, not the
+    // coordinator — see the delivery note at the hookSpecificOutput write below.)
     return;
   }
 
-  // v2.1.163+ additionalContext: feed the warning back to the coordinator turn
-  // so the finding is visible inline, not just in stderr + events.jsonl.
+  // v2.1.163+ additionalContext: surface the finding inline, not just in
+  // stderr + events.jsonl.
+  //
+  // The recipient is the SUBAGENT that just stopped — NOT the coordinator.
+  // Measured in the shipped binary (Claude Code 2.1.241, 2026-08-23): the
+  // SubagentStop hookSpecificOutput schema reads "additionalContext is
+  // non-error feedback delivered to the subagent; the subagent continues so it
+  // can act on it", and the emitter picks its target with
+  // `i.agentId ? "SubagentStop" : "Stop"`, yielding a `hook_additional_context`
+  // message into that agent's own loop. So this text lands in the transcript of
+  // the agent whose claims it is about, one moment after that agent is done.
+  //
+  // Worth knowing before "fixing" the path: PSA-006 asks the COORDINATOR to
+  // reject unverified distributional claims, and this channel never reaches
+  // him. His copy of the finding is events.jsonl + stderr, not this write.
+  // Whether he SHOULD receive it is a product question (#1116) — changing the
+  // route is not a comment edit.
+  //
   // Non-blocking — exit 0 always. Decision:"block" must never be set here.
   process.stdout.write(JSON.stringify({
     hookSpecificOutput: {

package/hooks/post-tool-batch-wave-signal.mjs

@@ -41,6 +41,7 @@ if (!shouldRunHook('post-tool-batch-wave-signal')) process.exit(0);
 
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
 import { emitEvent } from '../scripts/lib/events.mjs';
+import { findScopeFile } from '../scripts/lib/scope-gate.mjs';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -135,17 +136,25 @@ async function resolveSessionIdForHeartbeat(input, sessionFile) {
 }
 
 /**
- * Resolve the current wave number from .claude/wave-scope.json `.wave`.
+ * Resolve the current wave number from the wave-scope manifest's `.wave`.
  * Returns 0 when the file is absent or unparseable, mirroring the
  * pre-bash-memory-propose-audit.mjs G5 precedent ("wave defaults to 0 when
  * wave-scope.json absent"). The file is deleted mid-session at Quality phase
  * transitions and final cleanup, so absence is an expected, non-error state.
  *
+ * The manifest is located via `findScopeFile()` (#1082), the same precedence
+ * every other consumer uses — `.pi` > `.cursor` > `.codex` > `.claude`. The
+ * previous hard-coded `.claude/` path made this hook's whole wave-lifecycle
+ * fallback structurally dead on Codex CLI, Cursor and pi: the manifest exists,
+ * it just is not under `.claude/`, so every batch read 0 and no
+ * `orchestrator.wave.started`/`completed` event was ever emitted there.
+ *
  * @param {string} projectDir
  * @returns {Promise<number>}
  */
 async function resolveWaveNumber(projectDir) {
-  const waveFile = path.join(projectDir, '.claude', 'wave-scope.json');
+  const waveFile = findScopeFile(projectDir);
+  if (waveFile === null) return 0;
   try {
     const raw = await readFile(waveFile, 'utf8');
     const data = JSON.parse(raw);