session-orchestrator 3.16.0

package/scripts/lib/wave-context.mjs

@@ -0,0 +1,29 @@
+/**
+ * Wave-context helpers — single source of truth for the
+ * agent-context env-var contract documented in
+ * CLAUDE.md (or AGENTS.md on Codex CLI) "Critical Gotchas"
+ * + .claude/rules/parallel-sessions.md.
+ *
+ * The `SO_WAVE_AGENT` env-var is set to '1' by the wave-executor
+ * harness when dispatching subagents. Agents check this guard before
+ * calling memory.propose() — coordinator-thread invocations must NOT
+ * succeed (use /evolve instead). See #548 A4.
+ *
+ * Strict equality semantics (=== '1') are intentional: leading
+ * whitespace, trailing newline, '01', 'true', '0', undefined, and
+ * empty string all return false. This matches the documented contract
+ * in scripts/memory-propose.mjs Step 2b and the regression tests in
+ * tests/scripts/memory-propose.test.mjs Section E.
+ */
+
+export const WAVE_AGENT_ENV_VAR = 'SO_WAVE_AGENT';
+export const WAVE_AGENT_ENV_VALUE = '1';
+
+/**
+ * @returns {boolean} true iff this process is running as a dispatched
+ *   wave-agent (i.e., SO_WAVE_AGENT === '1', strict equality — leading
+ *   whitespace, trailing newline, '01', etc. all return false).
+ */
+export function isWaveAgentContext() {
+  return process.env[WAVE_AGENT_ENV_VAR] === WAVE_AGENT_ENV_VALUE;
+}

package/scripts/lib/wave-executor/pool.mjs

@@ -0,0 +1,248 @@
+/**
+ * pool.mjs — Bounded-concurrency worker-pool cursor for wave-executor dispatch.
+ *
+ * Provides a true cursor-based pull loop for agent dispatch, replacing the
+ * existing Promise.all() fan-out model when `worker-pool.enabled: true` in
+ * Session Config. Agents pull tasks from a shared cursor so at most
+ * `maxParallel` workers are active at any moment — forward-compatible with
+ * resource-gate decisions (#193).
+ *
+ * Issue: #415
+ *
+ * Exports:
+ *   runWavePool(opts) → Promise<{results: Array, errors: Array}>
+ *
+ * AbortSignal behaviour:
+ *   When the caller's abortSignal fires, each in-flight worker is sent a
+ *   per-worker AbortController.abort(). No new tasks are pulled. The function
+ *   drains for up to `drainTimeoutMs` before returning partial results.
+ *
+ * Error semantics:
+ *   A single failing task never cascades — remaining workers continue pulling
+ *   until the cursor is exhausted. Failed tasks accumulate in `errors`.
+ */
+
+// ---------------------------------------------------------------------------
+// Types (JSDoc only — no TypeScript at runtime)
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ taskId: string, dispatch: () => Promise<*> }} PoolTask
+ *
+ * @typedef {{
+ *   tasks: PoolTask[],
+ *   maxParallel: number,
+ *   abortSignal?: AbortSignal,
+ *   drainTimeoutMs?: number,
+ *   onTaskStart?: (taskId: string) => void,
+ *   onTaskComplete?: (taskId: string, result: *, error: Error|null) => void,
+ * }} PoolOptions
+ *
+ * @typedef {{
+ *   results: Array<{ taskId: string, result: * }>,
+ *   errors: Array<{ taskId: string, error: Error }>,
+ * }} PoolResult
+ */
+
+/** Default drain timeout (ms) when an abort signal fires mid-run. */
+export const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
+
+// ---------------------------------------------------------------------------
+// runWavePool
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute `tasks` with at most `maxParallel` concurrent workers.
+ *
+ * Workers pull tasks from a shared cursor — this is a genuine cursor model,
+ * not Promise.all(tasks.map(...)).  Each worker loop:
+ *   1. Picks up the next unstarted task (atomic cursor advance).
+ *   2. Awaits task.dispatch().
+ *   3. Records result/error.
+ *   4. Repeats until cursor is exhausted.
+ *
+ * When `abortSignal.aborted` is true (or fires during execution), the pool
+ * stops pulling new tasks and each in-flight worker receives its own
+ * AbortController abort.  The pool then waits up to `drainTimeoutMs` for
+ * workers to settle before returning partial results.
+ *
+ * @param {PoolOptions} opts
+ * @returns {Promise<PoolResult>}
+ */
+export async function runWavePool({
+  tasks,
+  maxParallel,
+  abortSignal,
+  drainTimeoutMs = DEFAULT_DRAIN_TIMEOUT_MS,
+  onTaskStart,
+  onTaskComplete,
+}) {
+  // ── Input validation ──────────────────────────────────────────────────────
+
+  if (!Array.isArray(tasks)) {
+    throw new TypeError('runWavePool: tasks must be an array');
+  }
+  if (typeof maxParallel !== 'number' || !Number.isInteger(maxParallel) || maxParallel < 1) {
+    throw new TypeError('runWavePool: maxParallel must be a positive integer');
+  }
+  if (typeof drainTimeoutMs !== 'number' || drainTimeoutMs < 0) {
+    throw new TypeError('runWavePool: drainTimeoutMs must be a non-negative number');
+  }
+
+  // ── Duplicate taskId guard ─────────────────────────────────────────────────
+  // Two tasks with the same taskId would produce duplicate records in `results`,
+  // silently dropping one when a caller builds a Map<taskId, result>.
+  const seenIds = new Set();
+  for (const t of tasks) {
+    if (!t || typeof t.taskId !== 'string') continue; // caught by runtime dispatch
+    if (seenIds.has(t.taskId)) {
+      throw new TypeError(`runWavePool: duplicate taskId "${t.taskId}"`);
+    }
+    seenIds.add(t.taskId);
+  }
+
+  // ── Fast path: empty tasks ─────────────────────────────────────────────────
+
+  if (tasks.length === 0) {
+    return { results: [], errors: [] };
+  }
+
+  // ── Shared state (cursor + result accumulators) ───────────────────────────
+
+  let nextIndex = 0;
+  /** @type {Map<number, AbortController>} taskIndex → per-worker AbortController */
+  const inFlight = new Map();
+  /** @type {Array<{ taskId: string, result: * }>} */
+  const results = [];
+  /** @type {Array<{ taskId: string, error: Error }>} */
+  const errors = [];
+
+  // Cap effective concurrency at tasks.length to avoid over-spawn.
+  const effective = Math.min(maxParallel, tasks.length);
+
+  // ── Abort handling ─────────────────────────────────────────────────────────
+
+  /**
+   * Returns true when the pool should stop pulling new tasks.
+   * Checks the caller-supplied AbortSignal (if any).
+   */
+  function isAborted() {
+    return abortSignal !== null && abortSignal !== undefined && abortSignal.aborted;
+  }
+
+  /**
+   * Abort all currently in-flight workers by forwarding to their per-worker
+   * AbortControllers.  Called when the caller's abortSignal fires.
+   *
+   * Only workers that are already executing `task.dispatch()` at the moment
+   * this function is called will receive the abort signal.  Tasks that are
+   * still queued (not yet pulled by any worker) are simply never started —
+   * the `isAborted()` guard in the worker loop stops the cursor on the next
+   * pull attempt.
+   */
+  function abortInFlight() {
+    for (const controller of inFlight.values()) {
+      controller.abort();
+    }
+  }
+
+  // Register a one-shot listener on the caller's AbortSignal so we react
+  // immediately if it fires while workers are running.
+  let abortListener = null;
+  if (abortSignal !== null && abortSignal !== undefined) {
+    abortListener = () => abortInFlight();
+    abortSignal.addEventListener('abort', abortListener, { once: true });
+  }
+
+  // ── Worker function ───────────────────────────────────────────────────────
+
+  /**
+   * A single worker loop.  Pulls tasks from the shared cursor until the
+   * cursor is exhausted or the pool is aborted.
+   */
+  async function worker() {
+    while (true) {
+      // Stop pulling when aborted.
+      if (isAborted()) break;
+
+      // Atomically claim the next task index.
+      const taskIndex = nextIndex;
+      if (taskIndex >= tasks.length) break; // cursor exhausted
+      nextIndex += 1;
+
+      const task = tasks[taskIndex];
+      const workerController = new AbortController();
+      inFlight.set(taskIndex, workerController);
+
+      // Notify caller that this task is starting.
+      if (typeof onTaskStart === 'function') {
+        onTaskStart(task.taskId);
+      }
+
+      try {
+        // Pass the worker's AbortSignal to the dispatch function so callers
+        // can propagate cancellation into their child processes.
+        const result = await task.dispatch(workerController.signal);
+        results.push({ taskId: task.taskId, result });
+        if (typeof onTaskComplete === 'function') {
+          onTaskComplete(task.taskId, result, null);
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        errors.push({ taskId: task.taskId, error });
+        if (typeof onTaskComplete === 'function') {
+          onTaskComplete(task.taskId, null, error);
+        }
+        // Single failure: continue the cursor, do NOT cascade abort.
+      } finally {
+        inFlight.delete(taskIndex);
+      }
+    }
+  }
+
+  // ── Spawn workers ──────────────────────────────────────────────────────────
+
+  // Pre-abort: if the signal already fired before workers started, abort now.
+  if (isAborted()) {
+    abortInFlight();
+  }
+
+  // Worker errors are individual task failures already captured above; we
+  // use allSettled so the pool itself never rejects.
+  const workerSettle = Promise.allSettled(
+    Array.from({ length: effective }, () => worker()),
+  );
+
+  // ── Drain with abort-timeout ───────────────────────────────────────────────
+
+  // Normal path: await all workers.
+  // Abort path: the abortListener forwards abort to each worker's controller,
+  // then we race settle vs. drainTimeoutMs.  Workers that honour their signal
+  // exit quickly; those that ignore it are abandoned after the timeout (the
+  // Promise is still in-flight but we return whatever results we have).
+
+  let drainTimeoutHandle;
+  const drainTimeoutPromise = new Promise((resolve) => {
+    drainTimeoutHandle = setTimeout(resolve, drainTimeoutMs);
+  });
+
+  if (abortSignal !== null && abortSignal !== undefined) {
+    // Race: workers settle OR drain timeout fires after abort.
+    // The abortListener (registered earlier) already handles aborting workers
+    // when the signal fires.  We just need to bound the wait.
+    await Promise.race([workerSettle, drainTimeoutPromise]);
+  } else {
+    // No abort signal — just wait for all workers to finish.
+    await workerSettle;
+  }
+
+  clearTimeout(drainTimeoutHandle);
+
+  // ── Cleanup ───────────────────────────────────────────────────────────────
+
+  if (abortListener !== null && abortSignal !== null && abortSignal !== undefined) {
+    abortSignal.removeEventListener('abort', abortListener);
+  }
+
+  return { results, errors };
+}

package/scripts/lib/wave-resource-gate.mjs

@@ -0,0 +1,204 @@
+/**
+ * wave-resource-gate.mjs — Pre-dispatch resource gate for parallel agent waves.
+ *
+ * Evaluates RAM / CPU / concurrent-session pressure before dispatching agents
+ * and returns a decision: "proceed", "reduce", or "coordinator-direct".
+ *
+ * Part of v3.1.0 Epic #157, Sub-Epic resource-gate. Issue #193.
+ */
+
+import { probe } from './resource-probe.mjs';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract resource measurements either from a test override or by calling
+ * the live resource probe. Returns either a measurements object or a sentinel
+ * `{ probeFailed: true }` indicating the caller should short-circuit with a
+ * "proceed" decision.
+ *
+ * @param {object} opts - Same opts shape as evaluateWaveResourceGate
+ * @returns {Promise<{ramFreeGb: number, ramAvailableGb: number|null, cpuLoadPct: number, concurrentSessions: number} | {probeFailed: true}>}
+ */
+async function extractMeasurements(opts) {
+  const { probeOverride } = opts;
+
+  if (probeOverride !== undefined && probeOverride !== null) {
+    return {
+      ramFreeGb: probeOverride.ramFreeGb,
+      // Tests may supply ramAvailableGb to exercise the macOS path; absent → null.
+      ramAvailableGb: probeOverride.ramAvailableGb ?? null,
+      cpuLoadPct: probeOverride.cpuLoadPct,
+      concurrentSessions: probeOverride.concurrentSessions,
+    };
+  }
+
+  let snapshot;
+  try {
+    snapshot = await probe({ skipProcessCounts: false });
+  } catch {
+    return { probeFailed: true };
+  }
+  return {
+    ramFreeGb: snapshot.ram_free_gb,
+    // macOS: free + reclaimable (vm_stat). null on Linux/Windows where
+    // os.freemem() is already accurate. (#667)
+    ramAvailableGb: snapshot.ram_available_gb ?? null,
+    cpuLoadPct: snapshot.cpu_load_pct,
+    // concurrent sessions: number of claude processes found by the probe.
+    concurrentSessions: snapshot.claude_processes_count ?? 0,
+  };
+}
+
+/**
+ * Apply the gate decision rule sequence (rules 3-8) given measurements and
+ * config. Returns the full gate result.
+ *
+ * @param {{ramFreeGb: number, cpuLoadPct: number, concurrentSessions: number}} measurements
+ * @param {object} opts - Same opts shape as evaluateWaveResourceGate
+ * @returns {{decision: string, agents: number, reasons: string[], measurements: object}}
+ */
+function applyDecisionRules(measurements, opts) {
+  const { config, plannedAgents } = opts;
+  const { ramFreeGb, ramAvailableGb, cpuLoadPct, concurrentSessions } = measurements;
+  const T = config['resource-thresholds'];
+
+  // macOS fix (#667): os.freemem() reports only `Pages free`, which reads
+  // sub-1 GB even on a 128 GB host with 80+ GB reclaimable cache — a false
+  // RAM-critical that forced spurious coordinator-direct fallbacks. When the
+  // probe supplied a numeric `ramAvailableGb` (free + reclaimable, via vm_stat),
+  // judge RAM thresholds on AVAILABLE; otherwise fall back to FREE (Linux/Win,
+  // where os.freemem() is already accurate).
+  const hasAvailable = ramAvailableGb !== null && ramAvailableGb !== undefined;
+  const effectiveRamGb = hasAvailable ? ramAvailableGb : ramFreeGb;
+  const ramLabel = hasAvailable ? 'RAM available' : 'RAM free';
+
+  // Rule 3: resource-thresholds missing → degrade to proceed (defensive).
+  // Handles legacy pre-#166 configs and test fixtures that omit the key.
+  // The gate is considered "ran" — caller receives measurements but no enforcement.
+  if (!T || typeof T !== 'object') {
+    return {
+      decision: 'proceed',
+      agents: plannedAgents,
+      reasons: ['resource-thresholds missing from config — gate skipped'],
+      measurements,
+    };
+  }
+
+  // Rule 4: RAM below critical → coordinator-direct.
+  if (effectiveRamGb < T['ram-free-critical-gb']) {
+    return {
+      decision: 'coordinator-direct',
+      agents: 0,
+      reasons: [
+        `${ramLabel} ${effectiveRamGb}GB < critical ${T['ram-free-critical-gb']}GB — escalating to coordinator-direct`,
+      ],
+      measurements,
+    };
+  }
+
+  // Rule 5: RAM below min (but above critical) → reduce.
+  if (effectiveRamGb < T['ram-free-min-gb']) {
+    return {
+      decision: 'reduce',
+      agents: Math.max(1, Math.floor(plannedAgents / 2)),
+      reasons: [
+        `${ramLabel} ${effectiveRamGb}GB < min ${T['ram-free-min-gb']}GB — reducing agent count`,
+      ],
+      measurements,
+    };
+  }
+
+  // Rule 6: CPU overloaded → reduce.
+  if (cpuLoadPct > T['cpu-load-max-pct']) {
+    return {
+      decision: 'reduce',
+      agents: Math.max(1, Math.floor(plannedAgents / 2)),
+      reasons: [
+        `CPU load ${cpuLoadPct}% > max ${T['cpu-load-max-pct']}% — reducing agent count`,
+      ],
+      measurements,
+    };
+  }
+
+  // Rule 7: concurrent sessions above warn → proceed with warning.
+  if (concurrentSessions > T['concurrent-sessions-warn']) {
+    return {
+      decision: 'proceed',
+      agents: plannedAgents,
+      reasons: [`warn: ${concurrentSessions} concurrent sessions`],
+      measurements,
+    };
+  }
+
+  // Rule 8: all within bounds.
+  return {
+    decision: 'proceed',
+    agents: plannedAgents,
+    reasons: ['all thresholds within bounds'],
+    measurements,
+  };
+}
+
+/**
+ * Evaluate whether the wave can be dispatched at the planned agent count.
+ * @param {object} opts
+ * @param {object} opts.config - Parsed Session Config (from parse-config.sh output)
+ * @param {number} opts.plannedAgents - Number of agents the session-plan wants to dispatch
+ * @param {string} opts.waveRole - e.g. "Impl-Core", "Quality"
+ * @param {object} [opts.probeOverride] - {ramFreeGb, cpuLoadPct, concurrentSessions} for
+ *   testing; when omitted, calls resource-probe
+ * @returns {Promise<{decision: "proceed"|"reduce"|"coordinator-direct", agents: number, reasons: string[], measurements: object}>}
+ */
+export async function evaluateWaveResourceGate(opts) {
+  const { config, plannedAgents } = opts;
+
+  // Rule 1: resource-awareness disabled — skip all probing.
+  if (config['resource-awareness'] === false) {
+    return {
+      decision: 'proceed',
+      agents: plannedAgents,
+      reasons: ['resource-awareness disabled in Session Config'],
+      measurements: {},
+    };
+  }
+
+  // Rule 2: probe the system (or use override for tests).
+  const measured = await extractMeasurements(opts);
+  if ('probeFailed' in measured) {
+    return {
+      decision: 'proceed',
+      agents: plannedAgents,
+      reasons: ['probe failed (ignored)'],
+      measurements: {},
+    };
+  }
+
+  // Rules 3-8: apply decision rule sequence.
+  return applyDecisionRules(measured, opts);
+}
+
+/**
+ * Format a gate result into a short multi-line coordinator progress string.
+ * @param {{decision: string, agents: number, reasons: string[], measurements: object}} result
+ * @returns {string}
+ */
+export function formatGateReport(result) {
+  const { decision, agents, reasons, measurements } = result;
+  const lines = reasons.map((r) => `  - ${r}`);
+  const m = measurements;
+  // Prefer the macOS available-RAM figure in the banner when present (#667):
+  // "RAM free" alone is misleading on Darwin (Pages-free underreports).
+  const hasAvailable = m.ramAvailableGb !== null && m.ramAvailableGb !== undefined;
+  const ramStr = hasAvailable
+    ? `RAM ${m.ramAvailableGb}GB avail`
+    : `RAM ${m.ramFreeGb ?? '?'}GB free`;
+  const measStr =
+    Object.keys(m).length > 0
+      ? ` (${ramStr}, CPU ${m.cpuLoadPct ?? '?'}%, sessions ${m.concurrentSessions ?? '?'})`
+      : '';
+  lines.push(`Decision: ${decision} — agents: ${agents}${measStr}`);
+  return lines.join('\n');
+}

package/scripts/lib/wave-sizing.mjs

@@ -0,0 +1,75 @@
+/**
+ * wave-sizing.mjs — graduated isolation defaults (issue #194).
+ * Learning: coordinator-over-worktree-on-shared-files caused back-to-back regressions.
+ */
+
+const VALID_SESSION_TYPES = ['housekeeping', 'feature', 'deep'];
+const VALID_COLLISION_RISKS = ['low', 'medium', 'high'];
+const VALID_CONFIG_ISOLATIONS = ['auto', 'worktree', 'none'];
+const VALID_ENFORCEMENTS = ['strict', 'warn', 'off'];
+const VALID_ISOLATIONS = ['worktree', 'none'];
+
+/**
+ * Resolve isolation mode for an agent wave dispatch.
+ *
+ * @param {Object} opts
+ * @param {number} opts.agentCount          positive integer
+ * @param {string} opts.sessionType         'housekeeping' | 'feature' | 'deep'
+ * @param {string} [opts.collisionRisk]     'low' | 'medium' | 'high' — default 'low'
+ * @param {string} [opts.configIsolation]   'auto' | 'worktree' | 'none' — default 'auto'
+ * @returns {'worktree'|'none'}
+ */
+export function resolveIsolation({ agentCount, sessionType, collisionRisk = 'low', configIsolation = 'auto' } = {}) {
+  if (!Number.isInteger(agentCount) || agentCount < 1) {
+    throw new TypeError(`resolveIsolation: agentCount must be a positive integer, got ${agentCount}`);
+  }
+  if (!VALID_SESSION_TYPES.includes(sessionType)) {
+    throw new TypeError(`resolveIsolation: sessionType must be housekeeping|feature|deep, got '${sessionType}'`);
+  }
+  if (!VALID_COLLISION_RISKS.includes(collisionRisk)) {
+    throw new TypeError(`resolveIsolation: collisionRisk must be low|medium|high, got '${collisionRisk}'`);
+  }
+  if (!VALID_CONFIG_ISOLATIONS.includes(configIsolation)) {
+    throw new TypeError(`resolveIsolation: configIsolation must be auto|worktree|none, got '${configIsolation}'`);
+  }
+
+  // Hard user overrides — first-match wins
+  if (configIsolation === 'worktree') return 'worktree';
+  if (configIsolation === 'none') return 'none';
+
+  // Plan-level collision declaration forces isolation even at ≤2 agents
+  if (collisionRisk === 'high') return 'worktree';
+
+  // Decision table
+  if (agentCount <= 2) return 'none';
+  if (agentCount >= 5) return 'worktree';
+  // agentCount is 3 or 4
+  if (sessionType === 'housekeeping') return 'none';
+  return 'worktree'; // feature | deep
+}
+
+/**
+ * Resolve enforcement mode given isolation.
+ *
+ * When isolation is 'none', the scope-enforcement hook is the only barrier —
+ * auto-promote 'warn' to 'strict'. Explicit 'off' is respected as user opt-out.
+ *
+ * @param {Object} opts
+ * @param {string} opts.isolation          'worktree' | 'none'
+ * @param {string} [opts.configEnforcement] 'strict' | 'warn' | 'off' — default 'warn'
+ * @returns {'strict'|'warn'|'off'}
+ */
+export function resolveEnforcement({ isolation, configEnforcement = 'warn' } = {}) {
+  if (!VALID_ISOLATIONS.includes(isolation)) {
+    throw new TypeError(`resolveEnforcement: isolation must be worktree|none, got '${isolation}'`);
+  }
+  if (!VALID_ENFORCEMENTS.includes(configEnforcement)) {
+    throw new TypeError(`resolveEnforcement: configEnforcement must be strict|warn|off, got '${configEnforcement}'`);
+  }
+
+  if (isolation === 'worktree') return configEnforcement;
+
+  // isolation === 'none': auto-promote warn → strict; respect strict and off as-is
+  if (configEnforcement === 'warn') return 'strict';
+  return configEnforcement;
+}

package/scripts/lib/webhook-url.mjs

@@ -0,0 +1,105 @@
+/**
+ * webhook-url.mjs — Centralized webhook URL resolution for session-orchestrator.
+ *
+ * Replaces ad-hoc hardcoded personal-domain URL fallbacks with a single
+ * resolution function that reads from environment variables and Session Config.
+ * No personal-domain default exists — callers that need a URL must supply one
+ * explicitly via env or config.
+ *
+ * Resolution order (env wins over config):
+ *   1. Environment variable:  SO_WEBHOOK_<KIND>_URL   (e.g. SO_WEBHOOK_SLACK_URL)
+ *   2. Session Config field:  webhooks.<kind>.url
+ *   3. Error: WebhookConfigError is thrown — no silent fallback to a personal domain.
+ *
+ * Supported kinds: 'slack' | 'discord' | 'generic' | 'gitlab-pipeline-status'
+ *
+ * Issue #228 — centralize webhook URL resolution + drop personal-domain default.
+ */
+
+// ---------------------------------------------------------------------------
+// Named error
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by `resolveWebhookUrl` when no URL source (env or config) provides a
+ * webhook URL for the requested kind. Callers should catch this and surface an
+ * actionable message to the user.
+ */
+export class WebhookConfigError extends Error {
+  /**
+   * @param {string} kind  - The webhook kind that was requested.
+   * @param {string} [message] - Optional override; defaults to a descriptive message.
+   */
+  constructor(kind, message) {
+    super(
+      message ??
+        `No webhook URL configured for kind "${kind}". ` +
+          `Set SO_WEBHOOK_${kind.toUpperCase().replace(/-/g, '_')}_URL ` +
+          `or add webhooks.${kind}.url to Session Config.`,
+    );
+    this.name = 'WebhookConfigError';
+    this.kind = kind;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Supported kinds
+// ---------------------------------------------------------------------------
+
+/** @type {ReadonlySet<string>} */
+const SUPPORTED_KINDS = new Set([
+  'slack',
+  'discord',
+  'generic',
+  'gitlab-pipeline-status',
+]);
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a webhook URL for the given kind.
+ *
+ * Resolution order:
+ *   1. `SO_WEBHOOK_<KIND>_URL` environment variable (e.g. `SO_WEBHOOK_SLACK_URL`)
+ *      — kind is upper-cased and hyphens become underscores.
+ *   2. `config.webhooks.<kind>.url` — when a Session Config object is provided.
+ *   3. Throws {@link WebhookConfigError} — no silent personal-domain fallback.
+ *
+ * @param {{ kind: string, config?: object }} options
+ *   - `kind`   — One of the supported webhook kinds (see SUPPORTED_KINDS).
+ *   - `config` — Parsed Session Config object (optional). Must have a `webhooks`
+ *                sub-object if a config-based URL is desired.
+ * @returns {string}  The resolved webhook URL (guaranteed non-empty string).
+ * @throws {WebhookConfigError}  When kind is unsupported or no URL is found.
+ * @throws {TypeError}  When `kind` is not a string.
+ */
+export function resolveWebhookUrl({ kind, config } = {}) {
+  if (typeof kind !== 'string' || kind.length === 0) {
+    throw new TypeError('resolveWebhookUrl: "kind" must be a non-empty string');
+  }
+
+  if (!SUPPORTED_KINDS.has(kind)) {
+    throw new WebhookConfigError(
+      kind,
+      `Unsupported webhook kind "${kind}". Supported kinds: ${[...SUPPORTED_KINDS].join(', ')}.`,
+    );
+  }
+
+  // 1. Environment variable: SO_WEBHOOK_<KIND>_URL
+  const envKey = `SO_WEBHOOK_${kind.toUpperCase().replace(/-/g, '_')}_URL`;
+  const envUrl = process.env[envKey];
+  if (typeof envUrl === 'string' && envUrl.length > 0) {
+    return envUrl;
+  }
+
+  // 2. Session Config: webhooks.<kind>.url
+  const configUrl = config?.webhooks?.[kind]?.url;
+  if (typeof configUrl === 'string' && configUrl.length > 0) {
+    return configUrl;
+  }
+
+  // 3. No source provided a URL — throw rather than fall back to a personal domain.
+  throw new WebhookConfigError(kind);
+}