session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/config.mjs

@@ -14,6 +14,10 @@
  *   events-rotation.mjs   — _parseEventsRotation
  *   vault-integration.mjs — _parseVaultIntegration + _parseResourceThresholds
  *
+ * One parser lives OUTSIDE that directory: `_parseExpressPath` in
+ * scripts/lib/express-path.mjs, alongside the express-path decision it configures.
+ * See that module's header for the reason and the revisit trigger.
+ *
  * Originally ported from parse-config.sh (v2) plus its helper libs
  * config-yaml-parser.sh and config-json-coercion.sh. Windows + CRLF safe.
  *
@@ -57,6 +61,7 @@ import { _parseAutoDream } from './config/auto-dream.mjs';
 import { _parseStateMdLock } from './config/state-md-lock.mjs';
 import { _parseHandoverGate } from './config/handover-gate.mjs';
 import { _parseIssueBudget } from './config/issue-budget.mjs';
+import { _parseHealthEndpoints, _parseEcosystemHealthBlockEnabled } from './config/health-endpoints.mjs';
 import { _parseBrokenWindow } from './config/broken-window.mjs';
 import { _parseSlopcheck } from './config/slopcheck.mjs';
 import { _parseDiscoveryValidator } from './config/discovery-validator.mjs';
@@ -67,11 +72,17 @@ import { _parseEval } from './config/eval.mjs';
 import { _parseMemory } from './config/memory.mjs';
 import { _parseReconcile } from './config/reconcile.mjs';
 import { _parseCustomPhases } from './config/custom-phases.mjs';
+import { _parseRemoteHosts } from './config/remote-hosts.mjs';
 import { _parseEvolve, _parseEvolveDecay } from './config/evolve.mjs';
 import { _parseSkillEvolution } from './config/skill-evolution.mjs';
 import { _parseDispatcherAutonomy, resolveDispatcherAutonomy } from './config/dispatcher-autonomy.mjs';
 import { loadHostPaths, resolveHostPath } from './config/host-paths.mjs';
 import { resolveNamedBaseline } from './named-baseline-resolver.mjs';
+// express-path lives one level UP from config/ (see its module header for why):
+// the parser is a sibling of config/state-md-lock.mjs in every respect except
+// its directory. Only the pure parser is imported here — `evaluateExpressPath`
+// and its telemetry stay out of this module's import graph by construction.
+import { _parseExpressPath } from './express-path.mjs';
 
 // Re-export the two functions that external callers import directly from this module.
 export { _coerceEnum, _coerceCollisionRisk } from './config/coercers.mjs';
@@ -189,7 +200,14 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
 
   // Boolean fields
   const persistence = _coerceBoolean(kv, 'persistence', true);
-  const ecosystemHealth = _coerceBoolean(kv, 'ecosystem-health', false);
+  // ecosystem-health has TWO spellings and only the scalar one reaches `kv`:
+  // the wizard writes a valueless `ecosystem-health:` header opening a block,
+  // which carries no `key: value` pair and is therefore invisible to the KV
+  // map (#1174). Scalar wins when present; otherwise the block form decides.
+  const ecosystemHealth =
+    _getVal(kv, 'ecosystem-health', undefined) !== undefined
+      ? _coerceBoolean(kv, 'ecosystem-health', false)
+      : (_parseEcosystemHealthBlockEnabled(mdContent) ?? false);
   const discoveryOnClose = _coerceBoolean(kv, 'discovery-on-close', false);
   const reasoningOutput = _coerceBoolean(kv, 'reasoning-output', false);
   const groundingCheck = _coerceBoolean(kv, 'grounding-check', true);
@@ -205,7 +223,6 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   const ssotFiles = _coerceList(kv, 'ssot-files', undefined);
   const discoveryProbes = _coerceList(kv, 'discovery-probes', '[all]');
   const discoveryExcludePaths = _coerceList(kv, 'discovery-exclude-paths', '[]');
-  const healthEndpoints = _coerceList(kv, 'health-endpoints', undefined);
   const worktreeExclude = _coerceList(
     kv,
     'worktree-exclude',
@@ -221,29 +238,77 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // follow-up (see docs/session-config-reference.md). This wires the parser + value only.
   const worktreeCleanup = _coerceEnum(kv, 'worktree-cleanup', 'default', ['default', 'aggressive']);
 
+  // remote-hosts: opt-in ssh-reachable hosts heavy roles may be offloaded to (#1160).
+  // Parsed HERE, before agent-mapping, because the `ssh:<alias>` channel below
+  // validates its target against the declared aliases. Defaults to [].
+  const remoteHosts = _parseRemoteHosts(mdContent);
+
   // Object fields
   const agentMapping = _coerceObject(kv, 'agent-mapping');
   if (agentMapping !== null) {
     // Validate role keys against canonical list from skills/_shared/config-reading.md
     const ALLOWED_ROLES = ['impl', 'test', 'db', 'ui', 'security', 'compliance', 'docs', 'perf'];
+    // Dispatch channels a mapping value may name via a `<channel>:<target>`
+    // prefix (#1150). Without a colon the value is a plain agent name and is
+    // dispatched natively, exactly as before.
+    //   impl: code-implementer      → native Agent dispatch (unchanged)
+    //   impl: cursor:composer-2.5   → foreign model over the Cursor channel
+    //   test: ssh:m5                → same Claude, another host (#1160)
+    // An unknown prefix is a typo or a channel this build cannot route, and
+    // must fail loudly: silently accepting it would dispatch to an agent that
+    // does not exist, which surfaces only as an empty wave much later.
+    const KNOWN_CHANNELS = ['cursor', 'session-orchestrator', 'ssh'];
+    // Accumulate every defect, then report once. A config with two bad entries
+    // must name BOTH — throwing on the first one makes the operator re-run the
+    // parse per defect, and each re-run hides the ones behind it.
     const invalidKeys = [];
+    const valueProblems = [];
     for (const [k, v] of Object.entries(agentMapping)) {
       if (!ALLOWED_ROLES.includes(k)) {
         invalidKeys.push(k);
         continue;
       }
       if (typeof v !== 'string' || v === '') {
-        throw new Error(
-          `config.mjs: agent-mapping role '${k}' has invalid value '${v}' (expected non-empty string)`
-        );
+        valueProblems.push(`role '${k}' has invalid value '${v}' (expected non-empty string)`);
+        continue;
+      }
+      const colonIdx = v.indexOf(':');
+      if (colonIdx !== -1) {
+        const channel = v.slice(0, colonIdx).trim();
+        const target = v.slice(colonIdx + 1).trim();
+        if (!KNOWN_CHANNELS.includes(channel)) {
+          valueProblems.push(
+            `role '${k}' names unknown channel '${channel}' in value '${v}' ` +
+              `(known channels: ${KNOWN_CHANNELS.join(', ')}; a value without ':' is a plain agent name)`
+          );
+        } else if (target === '') {
+          valueProblems.push(
+            `role '${k}' has channel '${channel}' but no target in value '${v}' ` +
+              `(expected '${channel}:<model-or-agent>')`
+          );
+        } else if (channel === 'ssh' && !remoteHosts.some((h) => h.alias === target)) {
+          // An ssh target is a host ALIAS, and the only place aliases are declared
+          // is the remote-hosts: block. An undeclared alias would reach argv as
+          // `-H <target>` and fail at connect time, one wave too late.
+          const declared = remoteHosts.map((h) => h.alias).join(', ') || 'none';
+          valueProblems.push(
+            `role '${k}' names ssh host '${target}' which is not declared in remote-hosts: ` +
+              `(declared: ${declared})`
+          );
+        }
       }
     }
+    const problems = [];
     if (invalidKeys.length > 0) {
-      throw new Error(
-        `config.mjs: agent-mapping contains invalid role key(s): ${invalidKeys.join(', ')} ` +
-          `(allowed: ${ALLOWED_ROLES.join(', ')})`
+      problems.push(
+        `invalid role key(s): ${invalidKeys.join(', ')} (allowed: ${ALLOWED_ROLES.join(', ')})`
       );
     }
+    problems.push(...valueProblems);
+    if (problems.length > 0) {
+      // Still fail loud — only the reporting shape changed, never the verdict.
+      throw new Error(`config.mjs: agent-mapping ${problems.join('; ')}`);
+    }
   }
   const enforcementGates = _coerceBoolObject(kv, 'enforcement-gates');
 
@@ -286,6 +351,14 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // events-rotation: parsed from full content (standalone top-level block)
   const eventsRotation = _parseEventsRotation(mdContent);
 
+  // express-path: parsed from full content (standalone top-level block, #214/#1119).
+  // Documented in docs/session-config-template.md:585 and
+  // docs/session-config-reference.md:1519 since #214, but never in the key schema —
+  // measured 2026-08-23, a probe carrying `express-path:\n  enabled: false` produced
+  // 88 keys and none of them was `express-path`. The key was dropped even when it
+  // stood in the file, so the documented default was prose rather than a value.
+  const expressPath = _parseExpressPath(mdContent);
+
   // vault-mirror.quality: parsed from full content (PRD F1.2 / issue #504)
   const vaultMirror = _parseVaultMirrorQuality(mdContent);
 
@@ -392,6 +465,10 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   const evolveDecay = _parseEvolveDecay(mdContent);
 
   // persona-gate-wave: opt-in mid-wave persona-panel hook (#458). Returns null when absent.
+  // health-endpoints: content-scoped (NOT _coerceList, which bails to null on
+  // any '{' and cannot see the wizard's nested block form at all) — #1174.
+  const healthEndpoints = _parseHealthEndpoints(mdContent);
+
   const personaGateWave = _parsePersonaGateWave(mdContent);
   if (personaGateWave !== null && personaGateWave.enabled === true && personaGateWave.mode === 'off') {
     process.stderr.write(
@@ -482,11 +559,13 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'context-coverage': contextCoverage,
     'worktree-orphans': worktreeOrphans,
     'events-rotation': eventsRotation,
+    'express-path': expressPath,
     'test': testConfig,
     'gitlab-portfolio': gitlabPortfolio,
     'wave-reviewers': waveReviewers,
     'persona-gate-wave': personaGateWave,
     'custom-phases': customPhases,
+    'remote-hosts': remoteHosts,
     'evolve.extra-sources': evolveExtraSources,
     'evolve.decay': evolveDecay,
   };

package/scripts/lib/convergence-monitor.mjs

@@ -312,12 +312,23 @@ function evaluateSignals(state, alreadyEmitted, latestWave) {
 }
 
 /**
+ * Poll delay.
+ *
+ * The timer is deliberately NOT `unref()`d: it is the only handle this process
+ * holds, so an unref'd timer drains the event loop and node exits 0 the instant
+ * the first tick is scheduled — a monitor that supervises nothing while looking
+ * like a clean shutdown (it has already emitted `tail.started` and writes
+ * nothing to stderr). Measured 2026-08-25 on the unref'd variant:
+ * `node scripts/lib/convergence-monitor.mjs --tail --interval=1` returned
+ * exit 0 after 47 ms instead of running until SIGTERM. This is the mechanism
+ * behind #980 (convergence-monitor never fires) — the same defect A1 measured
+ * in `scripts/lib/wave-transcript-tail.mjs`, which this sleep() was copied to.
+ *
  * @param {number} ms
  */
 function sleep(ms) {
   return new Promise((resolve) => {
-    const t = setTimeout(resolve, ms);
-    t.unref?.();
+    setTimeout(resolve, ms);
   });
 }
 

package/scripts/lib/cursor-hook-bridge.mjs

@@ -0,0 +1,443 @@
+/**
+ * cursor-hook-bridge.mjs — map Cursor IDE hook events onto existing handlers.
+ *
+ * Cursor emits native events (`beforeShellExecution`, `preToolUse`, …) with its
+ * own stdin JSON and reads `{ permission, user_message, agent_message }` back.
+ * Existing Session Orchestrator hooks speak the Claude/Codex contract:
+ * `{ hook_event_name, tool_name, tool_input, ... }` plus an exit-0
+ * `hookSpecificOutput.permissionDecision` envelope (#906).
+ *
+ * This bridge is the Cursor counterpart of `pi-hook-bridge.mjs`. It closes the
+ * #919 silent-no-op: without it, `enforce-commands.mjs` sees no `tool_name ===
+ * "Bash"` on a Cursor payload and writes 0 bytes / exit 0, so the command runs.
+ *
+ * Usage (`.cursor/hooks.json`):
+ *   sh hooks/run-node.sh scripts/lib/cursor-hook-bridge.mjs --event beforeShellExecution
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { matcherMatches, readHookDecision } from './pi-hook-bridge.mjs';
+import { resolvePluginRoot } from './plugin-root.mjs';
+
+export const CURSOR_TO_CANONICAL_EVENT = Object.freeze({
+  sessionStart: 'SessionStart',
+  sessionEnd: 'SessionEnd',
+  beforeShellExecution: 'PreToolUse',
+  afterShellExecution: 'PostToolUse',
+  preToolUse: 'PreToolUse',
+  postToolUse: 'PostToolUse',
+  afterFileEdit: 'PostToolUse',
+  postToolUseFailure: 'PostToolUseFailure',
+  stop: 'Stop',
+  subagentStart: 'SubagentStart',
+  subagentStop: 'SubagentStop',
+});
+
+export const CURSOR_BLOCKING_EVENTS = Object.freeze([
+  'beforeShellExecution',
+  'preToolUse',
+  'beforeMCPExecution',
+  'subagentStart',
+]);
+
+const TOOL_NAME_MAP = Object.freeze({
+  shell: 'Bash',
+  bash: 'Bash',
+  write: 'Write',
+  tabwrite: 'Write',
+  strreplace: 'Edit',
+  edit: 'Edit',
+  multiedit: 'MultiEdit',
+  read: 'Read',
+  tabread: 'Read',
+  delete: 'Write',
+  task: 'Agent',
+});
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+function objectOrEmpty(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+/**
+ * @param {string|undefined} toolName
+ * @returns {string|undefined}
+ */
+export function mapCursorToolName(toolName) {
+  if (typeof toolName !== 'string' || toolName.length === 0) return undefined;
+  const key = toolName.toLowerCase();
+  return TOOL_NAME_MAP[key] ?? toolName;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string|undefined}
+ */
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/**
+ * @param {string} cursorEventName
+ * @param {Record<string, unknown>} event
+ * @returns {string|undefined}
+ */
+function inferCursorToolName(cursorEventName, event) {
+  if (cursorEventName === 'beforeShellExecution' || cursorEventName === 'afterShellExecution') {
+    return 'Bash';
+  }
+  if (cursorEventName === 'afterFileEdit') {
+    return mapCursorToolName(typeof event.tool_type === 'string' ? event.tool_type : 'Write');
+  }
+  const raw = firstString(
+    typeof event.tool_name === 'string' ? event.tool_name : undefined,
+    typeof event.toolName === 'string' ? event.toolName : undefined,
+    typeof event.tool_type === 'string' ? event.tool_type : undefined,
+    typeof event.toolType === 'string' ? event.toolType : undefined,
+  );
+  return mapCursorToolName(raw);
+}
+
+/**
+ * @param {Record<string, unknown>} event
+ * @returns {Record<string, unknown>}
+ */
+function collectToolInput(event) {
+  const nested = objectOrEmpty(event.tool_input ?? event.arguments ?? event.args ?? event.input);
+  const next = { ...nested };
+  const command = firstString(
+    typeof event.command === 'string' ? event.command : undefined,
+    typeof next.command === 'string' ? next.command : undefined,
+  );
+  if (command) next.command = command;
+
+  const filePath = firstString(
+    typeof next.file_path === 'string' ? next.file_path : undefined,
+    typeof event.file_path === 'string' ? event.file_path : undefined,
+    typeof event.filePath === 'string' ? event.filePath : undefined,
+    typeof event.path === 'string' ? event.path : undefined,
+    typeof next.path === 'string' ? next.path : undefined,
+  );
+  if (filePath) {
+    next.file_path = filePath;
+    if (typeof next.path !== 'string') next.path = filePath;
+  }
+
+  if (typeof next.old_string !== 'string' && typeof next.oldText === 'string') {
+    next.old_string = next.oldText;
+  }
+  if (typeof next.new_string !== 'string' && typeof next.newText === 'string') {
+    next.new_string = next.newText;
+  }
+
+  return next;
+}
+
+/**
+ * Build the hook stdin payload expected by existing session-orchestrator hooks.
+ *
+ * @param {string} cursorEventName
+ * @param {Record<string, unknown>} [event]
+ * @param {Record<string, unknown>} [ctx]
+ * @returns {Record<string, unknown>}
+ */
+export function normalizeCursorHookPayload(cursorEventName, event = {}, ctx = {}) {
+  const eventObject = objectOrEmpty(event);
+  const ctxObject = objectOrEmpty(ctx);
+  const toolName = inferCursorToolName(cursorEventName, eventObject);
+  const toolInput = collectToolInput(eventObject);
+  const cwd = firstString(
+    typeof ctxObject.cwd === 'string' ? ctxObject.cwd : undefined,
+    typeof eventObject.cwd === 'string' ? eventObject.cwd : undefined,
+    process.cwd(),
+  );
+
+  return {
+    hook_event_name: CURSOR_TO_CANONICAL_EVENT[cursorEventName] ?? cursorEventName,
+    cursor_event_name: cursorEventName,
+    session_id: eventObject.session_id ?? eventObject.sessionId ?? ctxObject.sessionId,
+    cwd,
+    reason: eventObject.reason,
+    tool_name: toolName,
+    tool_input: toolInput,
+    tool_call_id: eventObject.tool_call_id ?? eventObject.toolCallId,
+    tool_response: eventObject.tool_response ?? eventObject.result ?? eventObject.output,
+    is_error: eventObject.is_error ?? eventObject.isError,
+    timestamp: eventObject.timestamp ?? new Date().toISOString(),
+  };
+}
+
+/**
+ * @param {string} pluginRoot
+ * @returns {Record<string, unknown>}
+ */
+export function loadCursorHookManifest(pluginRoot = resolvePluginRoot()) {
+  const manifestPath = path.join(pluginRoot, 'hooks', 'hooks-cursor.json');
+  if (!existsSync(manifestPath)) {
+    throw new Error(`Cursor hook manifest not found at ${manifestPath}`);
+  }
+  return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+
+/**
+ * @param {string} cursorEventName
+ * @param {Record<string, unknown>} event
+ * @param {string|undefined} canonicalToolName
+ * @returns {string[]}
+ */
+function matcherTargets(cursorEventName, event, canonicalToolName) {
+  const rawToolName = firstString(
+    typeof event.tool_name === 'string' ? event.tool_name : undefined,
+    typeof event.toolName === 'string' ? event.toolName : undefined,
+    typeof event.tool_type === 'string' ? event.tool_type : undefined,
+  );
+  return [
+    cursorEventName,
+    typeof event.reason === 'string' ? event.reason : '',
+    rawToolName ?? '',
+    canonicalToolName ?? '',
+    cursorEventName === 'beforeShellExecution' || cursorEventName === 'afterShellExecution' ? 'bash' : '',
+    cursorEventName === 'beforeShellExecution' || cursorEventName === 'afterShellExecution' ? 'shell' : '',
+  ].map((v) => v.toLowerCase());
+}
+
+/**
+ * @param {Record<string, unknown>} manifest
+ * @param {string} cursorEventName
+ * @param {Record<string, unknown>} [event]
+ * @returns {Array<Record<string, unknown>>}
+ */
+export function selectCursorHooks(manifest, cursorEventName, event = {}) {
+  const hooksByEvent = objectOrEmpty(manifest.hooks);
+  const entry = hooksByEvent[cursorEventName];
+  const eventObject = objectOrEmpty(event);
+  const canonicalToolName = inferCursorToolName(cursorEventName, eventObject);
+  const targets = matcherTargets(cursorEventName, eventObject, canonicalToolName);
+  const selected = [];
+
+  if (entry && !Array.isArray(entry) && typeof objectOrEmpty(entry).script === 'string') {
+    const script = objectOrEmpty(entry).script;
+    selected.push({
+      type: 'command',
+      command: `sh "$CURSOR_PLUGIN_ROOT/hooks/run-node.sh" "$CURSOR_PLUGIN_ROOT/${script}"`,
+    });
+    return selected;
+  }
+
+  const matchers = Array.isArray(entry) ? entry : [];
+  for (const matcherConfig of matchers) {
+    const config = objectOrEmpty(matcherConfig);
+    const matcher = typeof config.matcher === 'string' ? config.matcher : '';
+    if (!matcherMatches(matcher, targets)) continue;
+    const hooks = Array.isArray(config.hooks) ? config.hooks : [];
+    for (const hook of hooks) {
+      selected.push(objectOrEmpty(hook));
+    }
+  }
+
+  return selected;
+}
+
+/**
+ * @param {Record<string, unknown>} hook
+ * @param {Record<string, unknown>} payload
+ * @param {{ pluginRoot: string, cwd?: string, env?: NodeJS.ProcessEnv }} options
+ * @returns {{ command: string, status: number|null, stdout: string, stderr: string, blocked: boolean, reason: string|null }}
+ */
+export function runCursorHookCommand(hook, payload, options) {
+  const command = typeof hook.command === 'string' ? hook.command : '';
+  if (!command) {
+    return { command, status: 0, stdout: '', stderr: '', blocked: false, reason: null };
+  }
+
+  const timeoutSeconds = Number.isFinite(hook.timeout) ? Number(hook.timeout) : 5;
+  const cwd = options.cwd || (typeof payload.cwd === 'string' ? payload.cwd : process.cwd());
+  const env = {
+    ...process.env,
+    ...options.env,
+  };
+  delete env.CLAUDE_PLUGIN_ROOT;
+  delete env.CODEX_PLUGIN_ROOT;
+  delete env.PI_PLUGIN_ROOT;
+  delete env.CLAUDE_PROJECT_DIR;
+  delete env.CODEX_PROJECT_DIR;
+  delete env.PI_PROJECT_DIR;
+  env.CURSOR_PLUGIN_ROOT = options.pluginRoot;
+  env.CURSOR_RULES_DIR = options.pluginRoot;
+  env.PLUGIN_ROOT = options.pluginRoot;
+  env.SO_PLATFORM = 'cursor';
+  if (typeof payload.cwd === 'string') env.CURSOR_PROJECT_DIR = payload.cwd;
+
+  // `hook.command` is a shell line from the repo-committed hooks.json, so a
+  // shell is the intended interpreter — the same commit-gated trust class as
+  // the `*-command` keys run by scripts/lib/quality-gate.mjs (see
+  // .claude/rules/security.md § Session Config Command Trust). Nothing here
+  // interpolates user or payload input into the command string; the payload
+  // travels on stdin.
+  // nosemgrep: unsafe-shell-spawn
+  const result = spawnSync(command, {
+    shell: true,
+    cwd,
+    env,
+    input: JSON.stringify(payload) + '\n',
+    encoding: 'utf8',
+    timeout: timeoutSeconds * 1000,
+  });
+
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+  const decision = readHookDecision(stdout);
+  const isPreToolUse = payload.hook_event_name === 'PreToolUse';
+  const infraFailure = Boolean(result.error) ||
+    result.status === null ||
+    (result.status !== 0 && result.status !== 2) ||
+    decision.malformed;
+  const blocked = result.status === 2 ||
+    decision.deny ||
+    (isPreToolUse && infraFailure);
+
+  let reason = decision.reason;
+  if (reason === null && blocked) {
+    reason = result.error?.message
+      || (decision.malformed
+        ? `Hook stdout is not a parseable decision envelope (possible truncated output) — failing closed: ${command}`
+        : '')
+      || stdout.trim()
+      || stderr.trim()
+      || `Hook command blocked: ${command}`;
+  }
+
+  return {
+    command,
+    status: result.status,
+    stdout,
+    stderr,
+    blocked,
+    reason,
+  };
+}
+
+/**
+ * @param {string} cursorEventName
+ * @param {Record<string, unknown>} [event]
+ * @param {Record<string, unknown>} [ctx]
+ * @param {{ pluginRoot?: string, manifest?: Record<string, unknown>, env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Promise<{ block: boolean, reason: string|null, payload: Record<string, unknown>, results: Array<object> }>}
+ */
+export async function runCursorHookEvent(cursorEventName, event = {}, ctx = {}, options = {}) {
+  const pluginRoot = options.pluginRoot ?? resolvePluginRoot();
+  const manifest = options.manifest ?? loadCursorHookManifest(pluginRoot);
+  const payload = normalizeCursorHookPayload(cursorEventName, event, ctx);
+  const hooks = selectCursorHooks(manifest, cursorEventName, event);
+  const results = [];
+
+  for (const hook of hooks) {
+    const result = runCursorHookCommand(hook, payload, {
+      pluginRoot,
+      cwd: typeof payload.cwd === 'string' ? payload.cwd : process.cwd(),
+      env: options.env,
+    });
+    results.push(result);
+    if (result.blocked) {
+      return {
+        block: true,
+        reason: result.reason,
+        payload,
+        results,
+      };
+    }
+  }
+
+  return {
+    block: false,
+    reason: null,
+    payload,
+    results,
+  };
+}
+
+/**
+ * Map a bridge result onto Cursor's hook stdout contract.
+ *
+ * @param {string} cursorEventName
+ * @param {{ block: boolean, reason: string|null }} result
+ * @returns {Record<string, unknown>}
+ */
+export function toCursorHookOutput(cursorEventName, result) {
+  const blocking = CURSOR_BLOCKING_EVENTS.includes(cursorEventName);
+  if (result.block && blocking) {
+    const reason = result.reason || 'Blocked by Session Orchestrator';
+    return {
+      permission: 'deny',
+      user_message: reason,
+      agent_message: reason,
+    };
+  }
+  if (result.block && (cursorEventName === 'afterFileEdit' || cursorEventName === 'postToolUse')) {
+    return {
+      additional_context: result.reason || 'Session Orchestrator post-hoc warning',
+    };
+  }
+  if (blocking) {
+    return { permission: 'allow' };
+  }
+  return {};
+}
+
+function readStdinSync() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+async function main() {
+  const eventIdx = process.argv.indexOf('--event');
+  const eventName = eventIdx >= 0 ? process.argv[eventIdx + 1] : '';
+  if (!eventName || typeof CURSOR_TO_CANONICAL_EVENT[eventName] !== 'string') {
+    process.stderr.write(`cursor-hook-bridge: missing or unknown --event ${eventName || '(none)'}\n`);
+    process.stdout.write(`${JSON.stringify({ permission: 'allow' })}\n`);
+    return;
+  }
+
+  const raw = readStdinSync();
+  let event;
+  try {
+    event = raw.trim() ? JSON.parse(raw) : {};
+  } catch (err) {
+    const blocking = CURSOR_BLOCKING_EVENTS.includes(eventName);
+    if (blocking) {
+      const reason = `Cursor hook payload is not valid JSON: ${err instanceof Error ? err.message : err}`;
+      process.stdout.write(`${JSON.stringify({
+        permission: 'deny',
+        user_message: reason,
+        agent_message: reason,
+      })}\n`);
+      return;
+    }
+    process.stdout.write('{}\n');
+    return;
+  }
+
+  const result = await runCursorHookEvent(eventName, objectOrEmpty(event), { cwd: process.cwd() });
+  process.stdout.write(`${JSON.stringify(toCursorHookOutput(eventName, result))}\n`);
+}
+
+const isMain = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  main().catch((err) => {
+    process.stderr.write(`cursor-hook-bridge: ${err instanceof Error ? err.message : err}\n`);
+    process.stdout.write(`${JSON.stringify({ permission: 'allow' })}\n`);
+  });
+}

package/scripts/lib/dispatcher/cli.mjs

@@ -99,8 +99,8 @@ export async function runDispatch({ startDir, now, deps } = {}) {
  * session-lock.mjs — returns its result VERBATIM so callers (the skill prose,
  * Wave-4 tests) can branch on the exact `{ ok, reason, ... }` contract.
  *
- * On `ok:false` (race lost / busy — reasons: active, stale-pid-alive,
- * stale-pid-dead, fs-error, ...) the dispatcher must exclude that repo and
+ * On `ok:false` (race lost / busy — reasons: active, stale-heartbeat,
+ * fs-error, ...) the dispatcher must exclude that repo and
  * re-rank the remaining free candidates. On `ok:true` the claim is held and the
  * coordinator may launch the chosen entry command.
  *