session-orchestrator 3.16.0

package/hooks/on-stop.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * on-stop.mjs — consolidated Stop + SubagentStop hook.
+ *
+ * Replaces hooks/on-stop.sh and hooks/on-subagent-stop.sh. Handles both Claude Code
+ * hook events in a single file, discriminating by the `hook_event_name` field first,
+ * then falling back to presence of `agent_type` (SubagentStop) vs absence (Stop).
+ *
+ * Part of v3.0.0 Windows-native migration. Issue #141.
+ *
+ * Exit codes: 0 always (informational hooks must never block).
+ *
+ * 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>}
+ *   SubagentStop: {"timestamp":<ISO>,"event":"orchestrator.agent.stopped","agent":"<name>"}
+ */
+
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { $ } from 'zx';
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
+// #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
+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 { updateHeartbeat } from '../scripts/lib/session-lock.mjs';
+
+// ---------------------------------------------------------------------------
+// stdin reading (inline — no io.mjs because Stop hooks exit 0 always, never deny)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read stdin to EOF and parse as JSON. Returns null on empty or parse failure.
+ * @returns {Promise<object|null>}
+ */
+async function readStdinJson() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    const timer = setTimeout(() => {
+      process.stdin.destroy();
+      resolve(null);
+    }, 8000); // generous guard; contract says 5s (Stop) / 3s (SubagentStop)
+
+    if (process.stdin.readableEnded) {
+      clearTimeout(timer);
+      resolve(null);
+      return;
+    }
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      const raw = chunks.join('').trim();
+      if (!raw) { resolve(null); return; }
+      try { resolve(JSON.parse(raw)); } catch { resolve(null); }
+    });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(null); });
+    process.stdin.resume();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// discriminate hook event type
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine whether the parsed stdin represents a Stop or SubagentStop event.
+ * Precedence: hook_event_name field → presence of agent_type field → default Stop.
+ * @param {object|null} input
+ * @returns {"stop"|"subagent_stop"}
+ */
+function discriminate(input) {
+  if (!input) return 'stop';
+  const name = input.hook_event_name;
+  if (typeof name === 'string') {
+    if (name === 'SubagentStop') return 'subagent_stop';
+    return 'stop';
+  }
+  // Fallback: SubagentStop always provides agent_type; Stop does not.
+  if (typeof input.agent_type === 'string') return 'subagent_stop';
+  return 'stop';
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+ * @param {string} projectRoot — working directory for git commands
+ * @returns {Promise<{commit:string|null, branch:string|null}>}
+ */
+async function gitInfo(projectRoot) {
+  $.verbose = false;
+  $.quiet = true;
+  const opts = projectRoot ? { cwd: projectRoot } : {};
+  try {
+    const commitResult = await $({ ...opts })`git rev-parse HEAD`;
+    const branchResult = await $({ ...opts })`git rev-parse --abbrev-ref HEAD`;
+    return {
+      commit: commitResult.stdout.trim() || null,
+      branch: branchResult.stdout.trim() || null,
+    };
+  } catch {
+    return { commit: null, branch: null };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// wave-scope.json helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to read the wave number from .claude/wave-scope.json (or .codex / .cursor / .pi).
+ * Returns 0 if no scope file is found or the file cannot be parsed.
+ * @param {string} projectRoot
+ * @returns {Promise<number>}
+ */
+async function readWaveNumber(projectRoot) {
+  const dirs = ['.pi', '.claude', '.codex', '.cursor'];
+  for (const dir of dirs) {
+    const scopePath = path.join(projectRoot, dir, 'wave-scope.json');
+    try {
+      const raw = await fs.readFile(scopePath, 'utf8');
+      const obj = JSON.parse(raw);
+      const wave = typeof obj.wave === 'number' ? obj.wave : 0;
+      return wave;
+    } catch {
+      // file missing or unparseable — try next
+    }
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// event handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ *
+ * @param {object|null} input
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>}
+ */
+async function resolveSessionId(input, projectRoot) {
+  const fromStdin = input?.session_id ?? input?.sessionId ?? null;
+  if (typeof fromStdin === 'string' && fromStdin.length > 0) return fromStdin;
+  try {
+    const raw = await fs.readFile(
+      path.join(projectRoot, '.orchestrator', 'current-session.json'),
+      'utf8',
+    );
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.session_id === 'string' && parsed.session_id.length > 0) {
+      return parsed.session_id;
+    }
+  } catch { /* missing or unparseable is fine */ }
+  return null;
+}
+
+/**
+ * Handle a Stop event. Reads wave from scope file + git info, appends JSONL.
+ * @param {object|null} input
+ */
+async function handleStop(input) {
+  const projectRoot = SO_PROJECT_DIR;
+
+  const wave = await readWaveNumber(projectRoot);
+  const { commit, branch } = await gitInfo(projectRoot);
+
+  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).
+  if (sessionId) {
+    try {
+      await deregisterSelf(sessionId);
+    } 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) });
+    }
+
+    // Epic #583 W5-F1c — refresh session.lock heartbeat on every turn-end.
+    // Augments PostToolBatch's heartbeat (closes W4-Q3 H2 cadence finding:
+    // a session with no PostToolBatch activity would otherwise go heartbeat-stale).
+    // Best-effort: never throws, never blocks the Stop hook.
+    try {
+      updateHeartbeat({ sessionId, repoRoot: projectRoot });
+    } catch { /* best-effort */ }
+  }
+
+  // duration_ms: if input provides a start time we compute from it, else 0
+  const durationMs =
+    typeof input?.start_ms === 'number' ? Date.now() - input.start_ms : 0;
+
+  // 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.
+  await emitEvent('orchestrator.session.stopped', {
+    ...(sessionId !== null ? { session_id: sessionId } : {}),
+    wave,
+    ...(branch !== null ? { branch } : {}),
+    ...(commit !== null ? { commit } : {}),
+    duration_ms: durationMs,
+  });
+}
+
+/**
+ * Handle a SubagentStop event. Extracts agent name, emits orchestrator.agent.stopped.
+ * Returns an optional additionalContext string (v2.1.163+) to feed back to the
+ * coordinator turn. Currently always returns null (no inline warning from this
+ * handler) — the slot is reserved for future SubagentStop feedback.
+ * @param {object|null} input
+ * @returns {Promise<string|null>} additionalContext or null
+ */
+async function handleSubagentStop(input) {
+  const agent = input?.agent_type ?? 'unknown';
+  await emitEvent('orchestrator.agent.stopped', { agent });
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const input = await readStdinJson();
+  const eventType = discriminate(input);
+
+  if (eventType === 'subagent_stop') {
+    const additionalContext = await handleSubagentStop(input);
+    // v2.1.163+: emit hookSpecificOutput for SubagentStop path.
+    // If handleSubagentStop returns a non-empty context string, feed it back
+    // to the coordinator turn. Currently returns null (no inline warning from
+    // this handler), but the slot is live for future SubagentStop feedback.
+    // terminalSequence is a Stop-only field — not emitted for SubagentStop.
+    if (typeof additionalContext === 'string' && additionalContext.length > 0) {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'SubagentStop',
+          additionalContext,
+        },
+      }));
+    }
+  } else {
+    // terminalSequence must be emitted even when handleStop() throws (e.g.
+    // emitEvent's fs.appendFile fails on a full / read-only disk). Wrap the
+    // Stop branch in try/finally so the desktop notification is always sent.
+    // SubagentStop is intentionally outside this block — it must never emit
+    // terminalSequence.
+    try {
+      await handleStop(input);
+    } finally {
+      // terminalSequence is only meaningful for Stop (session-level) events.
+      process.stdout.write(buildTerminalSequenceJson());
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// terminal notification
+// ---------------------------------------------------------------------------
+
+/**
+ * Emit a cross-platform desktop notification via the CC 2.1.141+ terminalSequence
+ * output field. Supports OSC 9 (iTerm2, Windows Terminal, WezTerm, ConEmu) and
+ * OSC 777 (Ghostty, urxvt, Warp). Both sequences are emitted together; unsupported
+ * terminals silently ignore. Returns the JSON string to write to stdout.
+ * @returns {string}
+ */
+function buildTerminalSequenceJson() {
+  const title = 'Claude Code';
+  const body  = 'Session stopped — your turn';
+  const osc9   = `\x1b]9;${title}: ${body}\x07`;
+  const osc777 = `\x1b]777;notify;${title};${body}\x07`;
+  return JSON.stringify({ terminalSequence: osc9 + osc777 });
+}
+
+// Exit 0 always — informational hook must never block Claude.
+main()
+  .catch(() => {})
+  .finally(() => process.exit(0));

package/hooks/operator-steer.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * operator-steer.mjs — PostToolBatch hook for operator in-band steering.
+ *
+ * Hook event: PostToolBatch (issue #409).
+ * Fires after a batch of tool invocations completes within a single wave turn.
+ * Reads `.orchestrator/STEER.md` and, if non-empty, emits its contents as a
+ * `systemMessage` payload to stdout so Claude Code injects the guidance into
+ * the active session context. The file is then truncated (set to empty) so the
+ * message fires exactly once per write — a one-shot handshake.
+ *
+ * Operator workflow:
+ *   echo "Focus on error handling in wave 3" > .orchestrator/STEER.md
+ *   # Claude picks it up at the next PostToolBatch boundary, clears the file.
+ *
+ * Decision flow:
+ *   1. shouldRunHook gate — exit 0 immediately when the hook is disabled.
+ *   2. Resolve steerPath: $SO_PROJECT_DIR/.orchestrator/STEER.md
+ *   3. If the file is absent or whitespace-only → exit 0 silently.
+ *   4. If non-empty: emit { systemMessage: <contents> } to stdout, then
+ *      truncate the file to '' so it fires only once.
+ *
+ * Output contract (PostToolBatch):
+ *   stdout: JSON — { systemMessage: string }
+ *   stderr: nothing (diagnostic errors swallowed)
+ *   exit code: 0 always (informational — must never block Claude)
+ *
+ * TODO(#409): Cursor support — hooks-cursor.json uses a different event model
+ *   (no PostToolBatch equivalent) and is not wired here. Register this hook
+ *   in hooks-cursor.json when Cursor gains a suitable between-batch event.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
+// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+if (!shouldRunHook('operator-steer')) process.exit(0);
+
+import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const steerPath = path.join(SO_PROJECT_DIR, '.orchestrator', 'STEER.md');
+
+  // File absent — nothing to do.
+  if (!existsSync(steerPath)) return;
+
+  // Read contents and check for meaningful (non-whitespace) content.
+  const contents = readFileSync(steerPath, 'utf8');
+  if (!contents.trim()) return;
+
+  // Emit the systemMessage payload so Claude Code injects it into the session.
+  console.log(JSON.stringify({ systemMessage: contents }));
+
+  // Truncate the file — one-shot handshake, fires exactly once per write.
+  writeFileSync(steerPath, '', 'utf8');
+}
+
+// Exit 0 always — informational hook must never block Claude.
+main().catch(() => {}).finally(() => process.exit(0));

package/hooks/post-edit-validate.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * post-edit-validate.mjs — PostToolUse hook for incremental validation after Edit/Write/MultiEdit.
+ *
+ * Node.js port of hooks/post-edit-validate.sh. Part of v3.0.0 Windows-native migration.
+ * Issue: github.com/Kanevry/session-orchestrator/issues/139
+ *
+ * Runs incremental typecheck on the file that was just edited.
+ * This is informational only — it NEVER blocks (always exits 0).
+ *
+ * Decision flow:
+ *   G1  stdin null → silent exit 0
+ *   G2  tool_name filter — only Edit/Write/MultiEdit trigger typecheck
+ *   G3  file_path present
+ *   G4  file extension filter — only .ts|.tsx|.js|.jsx|.mjs|.cjs
+ *   G5  gate check — wave-scope.json.gates['post-edit-validate'] === false → exit 0
+ *   G6  resolve typecheck command: Session Config → tsgo → tsc → npx tsc → skip
+ *   G7  run typecheck with 2s AbortController timeout
+ *   G8  emit JSONL result to stderr
+ *
+ * Output (stderr): {"check":"typecheck","status":"pass|fail|skip","file":"<rel>","duration_ms":<int>}
+ * Exit codes: 0 — always (PostToolUse hooks are informational)
+ *
+ * SECURITY notes:
+ *   REQ-01  top-level try/catch → silent exit 0 on unexpected error (never blocks)
+ *   REQ-02  typecheck process uses AbortController (not shell `timeout` — cross-platform)
+ *   REQ-03  relative path computed via path.relative(projectRoot, absFilePath)
+ */
+
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { performance } from 'node:perf_hooks';
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
+// #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
+if (!shouldRunHook('post-edit-validate')) process.exit(0);
+
+import { readStdin } from '../scripts/lib/io.mjs';
+import { resolveProjectDir } from '../scripts/lib/platform.mjs';
+import { findScopeFile, gateEnabled } from '../scripts/lib/hardening.mjs';
+import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** File extensions that trigger typecheck. */
+const TS_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+
+/**
+ * Emit the JSONL result line to stderr.
+ * @param {string} file            - relative file path
+ * @param {'pass'|'fail'|'skip'} status
+ * @param {number} [duration_ms]   - omit for skip
+ * @param {string} [reason]        - human-readable reason for skip or fail
+ * @param {string} [remediation]   - actionable fix hint for fail status only
+ */
+function emitResult(file, status, duration_ms, reason, remediation) {
+  const obj = { check: 'typecheck', status, file };
+  if (typeof duration_ms === 'number') obj.duration_ms = duration_ms;
+  if (reason !== undefined) obj.reason = reason;
+  if (remediation !== undefined) obj.remediation = remediation;
+  process.stderr.write(JSON.stringify(obj) + '\n');
+}
+
+/**
+ * Try to resolve the typecheck command.
+ * Order: Session Config typecheck-command → tsgo → tsc → npx tsc → null
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<{cmd: string, args: string[]}|null>}
+ */
+async function resolveTypecheckCommand(projectRoot) {
+  // 1. Session Config typecheck-command
+  try {
+    const md = await readConfigFile(projectRoot);
+    const config = parseSessionConfig(md);
+    const cmd = config['typecheck-command'];
+    if (cmd && typeof cmd === 'string') {
+      const parts = cmd.trim().split(/\s+/);
+      return { cmd: parts[0], args: parts.slice(1) };
+    }
+  } catch {
+    // config unavailable — fall through
+  }
+
+  // 2. tsgo
+  const tsgoParts = _tryWhich('tsgo');
+  if (tsgoParts) return { cmd: tsgoParts, args: ['--noEmit'] };
+
+  // 3. tsc
+  const tscParts = _tryWhich('tsc');
+  if (tscParts) return { cmd: tscParts, args: ['--noEmit'] };
+
+  // 4. npx tsc
+  const npxParts = _tryWhich('npx');
+  if (npxParts) return { cmd: npxParts, args: ['tsc', '--noEmit'] };
+
+  return null;
+}
+
+/**
+ * Check whether an executable exists on PATH using `which` / `where` (sync).
+ * Returns the executable name if found, null otherwise. Never throws.
+ *
+ * @param {string} name
+ * @returns {string|null}
+ */
+function _tryWhich(name) {
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const result = spawnSync(whichCmd, [name], { encoding: 'utf8', timeout: 2000 });
+    if (result.status === 0 && result.stdout.trim()) return name;
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Run the typecheck command with a 2s AbortController timeout.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {{status: 'pass'|'fail', duration_ms: number, reason?: string}}
+ */
+function runTypecheck(cmd, args) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 2000);
+
+  const start = performance.now();
+  let spawnResult;
+  try {
+    spawnResult = spawnSync(cmd, args, {
+      signal: controller.signal,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 2000,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const duration_ms = Math.max(0, Math.round(performance.now() - start));
+
+  // AbortError or SIGTERM from timeout
+  if (spawnResult.error?.name === 'AbortError' || spawnResult.signal === 'SIGTERM') {
+    return { status: 'fail', duration_ms, reason: 'typecheck timed out after 2s' };
+  }
+
+  if (spawnResult.status !== 0) {
+    // Capture the first non-empty line of stderr/stdout as a compact reason.
+    const combined = ((spawnResult.stderr ?? '') + (spawnResult.stdout ?? '')).trim();
+    const firstLine = combined.split('\n').find((l) => l.trim()) ?? 'typecheck exited non-zero';
+    return { status: 'fail', duration_ms, reason: firstLine.slice(0, 256) };
+  }
+
+  return { status: 'pass', duration_ms };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  // G1: null stdin → silent exit 0
+  let input;
+  try {
+    input = await readStdin();
+  } catch {
+    process.exit(0);
+  }
+  if (!input) process.exit(0);
+
+  const toolName = input.tool_name;
+  const filePath = input?.tool_input?.file_path;
+
+  // G2: only Edit, Write, and MultiEdit trigger typecheck
+  if (toolName !== 'Edit' && toolName !== 'Write' && toolName !== 'MultiEdit') process.exit(0);
+
+  // G3: file_path must be present
+  if (!filePath || typeof filePath !== 'string') process.exit(0);
+
+  // G4: extension filter — only TS/JS variants
+  const ext = path.extname(filePath).toLowerCase();
+  if (!TS_EXTS.has(ext)) process.exit(0);
+
+  const projectRoot = resolveProjectDir();
+
+  // Compute relative path (REQ-03)
+  const absFilePath = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(projectRoot, filePath);
+  const relPath = path.relative(projectRoot, absFilePath);
+
+  // G5: per-gate toggle — skip if post-edit-validate gate is disabled
+  const scopeFile = findScopeFile(projectRoot);
+  if (scopeFile && !gateEnabled(scopeFile, 'post-edit-validate')) {
+    process.exit(0);
+  }
+
+  // G6: resolve typecheck command
+  const tc = await resolveTypecheckCommand(projectRoot);
+  if (!tc) {
+    emitResult(relPath, 'skip', undefined, 'no typecheck command found');
+    process.exit(0);
+  }
+
+  // G7: run typecheck with 2s timeout (REQ-02)
+  const { status, duration_ms, reason } = runTypecheck(tc.cmd, tc.args);
+
+  // G8: emit JSONL result to stderr
+  const remediation =
+    status === 'fail'
+      ? 'Run `npm run typecheck` to see full error context, then fix the type at the cited location.'
+      : undefined;
+  emitResult(relPath, status, duration_ms, reason, remediation);
+
+  process.exit(0);
+}
+
+// REQ-01: top-level catch — PostToolUse must never block; always exit 0
+main().catch(() => {
+  process.exit(0);
+});