@magnusekdahl/parallix 1.2.0 → 1.2.1

package/lib/agents/agents.ts

@@ -0,0 +1,930 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import * as fmt from '../core/fmt.js';
+import { startCodexDraftAgent, resolveCodexCommand } from './codex.js';
+import { startClaudeAgent, resolveClaudeCommand } from './claude.js';
+import { startMistralAgent, resolveMistralCommand } from './mistral.js';
+import { startOpencodeAgent, resolveOpencodeCommand, isSpuriousOpencodeExit } from './opencode.js';
+import { detectLimitHit, formatBlockUntil, DEFAULT_FALLBACK_HOURS } from './limit-hit.js';
+import * as storage from '../core/storage.js';
+import { resolveAgentModel } from '../core/product-config.js';
+import { migrateAgentBlocklists } from '../core/persistent-data-migration.js';
+// tools/sessions is still CJS (not converted in this wave); require keeps it
+// untyped (any) without pulling a non-included .js into the typecheck program.
+const sessions = require('../tools/sessions');
+
+interface LauncherStatus {
+  agent: string;
+  supported: boolean;
+  detail: string;
+  health?: string;
+  reason?: string;
+}
+
+type AgentConfig = { blocklist?: {[key: string]: any}, steps?: {[key: string]: any} };
+
+interface StartAgentOptions {
+  prompt: string | Function;
+  worktree?: string;
+  agent?: string;
+  env?: {[key: string]: string};
+  exclude?: any;
+  onLimitHit?: Function;
+  onLaunch?: Function;
+  slug?: string | null;
+  role?: string | null;
+  detectLimitHitFn?: Function;
+  updateAgentBlockFn?: Function;
+  selectAgentFn?: Function;
+  resolveAgentModelFn?: Function;
+  isAgentBlockedFn?: Function;
+  sessionsModule?: any;
+  log?: Function;
+  noOutputWatchdog?: {initialDelayMs?: number, intervalMs?: number} | boolean;
+}
+
+type ReadAgentConfigOptions = {
+  mergeLocal?: boolean;
+  mainWorktreePath?: string | null;
+  warn?: Function;
+  targetPath?: string;
+  config?: AgentConfig | null;
+  configPath?: string;
+  exclude?: any;
+};
+
+// Launchers whose CLI accepts a per-call resume flag threaded by startAgent.
+// Each launcher outputs a session resume hint at the end of its run (e.g.
+// "codex resume <id>", "opencode -s ses_<id>",
+// "claude --resume <id>"). The resume flag is only used when the caller
+// passes slug+role+worktree and the session marker matches the chosen agent.
+// custom (opencode) always uses --continue; claude uses --continue; codex uses
+// `exec resume --last`.
+const RESUME_CAPABLE = new Set(['claude', 'codex', 'custom']);
+
+const CONFIG_PATH = path.join(__dirname, '..', '..', 'config', 'agents.json');
+
+// Test hook: when set, used instead of spawning `command -v` to check PATH.
+let _commandPathProbe: ((name: string) => string | null) | null = null;
+
+const LAUNCHERS: {[key: string]: Function} = {
+  codex: startCodexDraftAgent,
+  claude: startClaudeAgent,
+  mistral: startMistralAgent,
+  custom: startOpencodeAgent
+};
+
+const RESOLVERS: {[key: string]: () => string} = {
+  codex: resolveCodexCommand,
+  claude: resolveClaudeCommand,
+  mistral: resolveMistralCommand,
+  custom: resolveOpencodeCommand
+};
+
+const HEALTH_PROBE_ARGS: {[key: string]: string[]} = Object.freeze({
+  codex: ['--help'],
+  claude: ['--help'],
+  mistral: ['--help'],
+  custom: ['--help']
+});
+const LAUNCHER_HEALTH_TIMEOUT_MS = 3000;
+const DEFAULT_NO_OUTPUT_INITIAL_DELAY_MS = 60_000;
+const DEFAULT_NO_OUTPUT_INTERVAL_MS = 60_000;
+const DRAFT_NO_OUTPUT_INITIAL_DELAY_MS = 15_000;
+const DRAFT_NO_OUTPUT_INTERVAL_MS = 30_000;
+
+const WORKFLOW_AGENT_NAMES = Object.freeze(Object.keys(LAUNCHERS));
+const KNOWN_AGENT_NAMES = Object.freeze([
+  ...WORKFLOW_AGENT_NAMES,
+  'human'
+]);
+
+function workflowLauncherStatus(agent: string): LauncherStatus {
+  const resolver = RESOLVERS[agent];
+  if (!resolver) {
+    return { agent, supported: false, detail: `unknown agent: ${agent}` };
+  }
+  const command = resolver();
+  const exists = command.includes('/') ? fs.existsSync(command) : commandInPath(command);
+  if (!exists) {
+    return { agent, supported: false, detail: command, health: 'missing' };
+  }
+
+  const probeArgs = HEALTH_PROBE_ARGS[agent] || ['--help'];
+  const probe = spawnSync(command, probeArgs, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: LAUNCHER_HEALTH_TIMEOUT_MS
+  });
+
+  if (probe.error || probe.status !== 0) {
+    const pErr: Error & {code?: string} = probe.error || new Error('');
+    const reason = probe.error
+      ? (pErr.code || pErr.message)
+      : `exit ${probe.status}`;
+    return {
+      agent,
+      supported: false,
+      detail: `${command} ${probeArgs.join(' ')}`.trim(),
+      health: 'probe-failed',
+      reason
+    };
+  }
+
+  return { agent, supported: true, detail: `${command} ${probeArgs.join(' ')}`.trim(), health: 'ok' };
+}
+
+function commandInPath(name: string) {
+  if (_commandPathProbe) {
+    return _commandPathProbe(name) || false;
+  }
+  const result = spawnSync('bash', ['-c', `command -v ${name}`], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore']
+  });
+  return result.status === 0 && result.stdout.trim().length > 0;
+}
+
+function buildInvalidAgentConfigError(configPath: string, scope: string, originalError: {message?: string} | null) {
+  const location = path.resolve(configPath);
+  const detail = originalError && originalError.message ? originalError.message : 'invalid JSON';
+  const error: any = new Error(
+    `Invalid ${scope} agent config at ${location}: ${detail}. ` +
+    'Fix or remove the malformed file before running workflow commands so agent blocking is applied deterministically.'
+  );
+  error.code = 'WORKFLOW_AGENT_CONFIG_INVALID';
+  error.configPath = location;
+  error.configScope = scope;
+  return error;
+}
+
+function isInvalidAgentConfigError(error: {code?: string}) {
+  return Boolean(error && error.code === 'WORKFLOW_AGENT_CONFIG_INVALID');
+}
+
+function readAgentConfigOrExit(configPath: string = CONFIG_PATH, options: ReadAgentConfigOptions = {}) {
+  try {
+    return readAgentConfig(configPath, options);
+  } catch (error) {
+    if (isInvalidAgentConfigError((error as any))) {
+      fmt.log.fail((error as any).message);
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+
+function parseAgentConfigFile(configPath: string, scope: string) {
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    throw buildInvalidAgentConfigError(configPath, scope, (err as {message?: string}));
+  }
+}
+
+function readAgentConfig(configPath: string = CONFIG_PATH, options: ReadAgentConfigOptions = {}) {
+  const {
+    mergeLocal = path.resolve(configPath) === path.resolve(CONFIG_PATH),
+    mainWorktreePath,
+    warn = fmt.log.warn
+  } = options;
+  let config: AgentConfig = {};
+  if (fs.existsSync(configPath)) {
+    config = parseAgentConfigFile(configPath, 'workflow');
+  }
+
+  if (mergeLocal) {
+    config = config || {};
+    const projectRoot = path.resolve(path.dirname(configPath), '..', '..');
+    const mainWorktree = mainWorktreePath !== undefined
+      ? mainWorktreePath
+      : getMainWorktreePath({ cwd: projectRoot, warn });
+    const /** @type {string[]} */ legacyPaths = [
+      path.join(path.dirname(configPath), 'agents.local.json'),
+      path.join(projectRoot, 'agents.local.json'),
+      mainWorktree ? path.join(mainWorktree, 'agents.local.json') : ''
+    ].filter(/** @param {string} p */ (p) => Boolean(p));
+    const /** @type {string} */ targetPath = options.targetPath || storage.resolveAgentsLocalPath({ ensureDir: true });
+    if (!fs.existsSync(targetPath)) {
+      try {
+        migrateAgentBlocklists({
+          sourcePaths: legacyPaths,
+          destinationPath: targetPath,
+          warn: warn as any
+        });
+      } catch (error) {
+        throw buildInvalidAgentConfigError(targetPath, 'local', (error as any));
+      }
+    }
+    if (fs.existsSync(targetPath)) {
+      const localConfig = parseAgentConfigFile(targetPath, 'local');
+      if (localConfig && localConfig.blocklist) {
+        (config as {blocklist?: {[key: string]: any}}).blocklist = Object.assign((config as {blocklist?: {[key: string]: any}}).blocklist || {}, localConfig.blocklist);
+      }
+    }
+  }
+
+  return config;
+}
+
+function getMainWorktreePath(options: {cwd?: string, warn?: Function} = {}) {
+  const { cwd = process.cwd(), warn = fmt.log.warn } = options;
+  try {
+    const commonDir = getGitPath(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    if (commonDir && MainWorktreeDetector.byCommonDir.has(commonDir)) {
+      return MainWorktreeDetector.byCommonDir.get(commonDir);
+    }
+
+    const result = spawnSync('git', ['-C', cwd, 'worktree', 'list', '--porcelain'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1000
+    });
+    if (result.status !== 0) {
+      warn(
+        `Could not inspect git worktrees while looking for main-worktree agents.local.json; ` +
+        `skipping that lookup (git exited with status ${result.status}).`
+      );
+      return null;
+    }
+
+    const lines = result.stdout.split('\n');
+    const mainWorktreePath = detectMainWorktreePath(lines, cwd, commonDir);
+    if (mainWorktreePath) {
+      if (commonDir) {MainWorktreeDetector.byCommonDir.set(commonDir, mainWorktreePath);}
+      return mainWorktreePath;
+    }
+
+    // Fallback: pick the first worktree whose HEAD points to main
+    let i = 0;
+    while (i < lines.length) {
+      if (lines[i].startsWith('worktree ')) {
+        const wt = lines[i].slice('worktree '.length).trim();
+        const branchLineIdx = i + 1;
+        if (branchLineIdx < lines.length && lines[branchLineIdx].startsWith('branch refs/heads/main')) {
+          if (commonDir) {MainWorktreeDetector.byCommonDir.set(commonDir, wt);}
+          return wt;
+        }
+      }
+      i++;
+    }
+
+    // Last resort: the first worktree in the list that isn't the current cwd
+    for (i = 0; i < lines.length; i++) {
+      if (lines[i].startsWith('worktree ')) {
+        const wt = lines[i].slice('worktree '.length).trim();
+        if (wt !== cwd) {
+          if (commonDir) {MainWorktreeDetector.byCommonDir.set(commonDir, wt);}
+          return wt;
+        }
+      }
+    }
+  } catch (err) {
+    const e: Error & {code?: string} = (err as any);
+    const detail = e && (e.code || e.message) ? (e.code || e.message) : 'unknown error';
+    warn(
+      `Could not inspect git worktrees while looking for main-worktree agents.local.json; ` +
+      `skipping that lookup (${detail}).`
+    );
+    return null;
+  }
+
+  warn(
+    'Could not determine the main worktree from `git worktree list --porcelain`; ' +
+    'skipping main-worktree agents.local.json lookup.'
+  );
+  return null;
+}
+
+// Extract the known main worktree path from the repo metadata so worktree
+// iteration doesn't accidentally pick the current (non-main) worktree.
+// Cached per git common directory to avoid repeated subprocess calls without
+// leaking a temp-repo answer into later tests or nested workflow invocations.
+const MainWorktreeDetector = {
+  byCommonDir: new Map<string, string>()
+};
+
+function getGitPath(cwd: string, args: string[]) {
+  const result = spawnSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 1000
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  return result.stdout.trim() || null;
+}
+
+function parseWorktreePaths(lines: string[]) {
+  return lines
+    .filter(/** @param {string} line */ (line) => line.startsWith('worktree '))
+    .map(/** @param {string} line */ (line) => line.slice('worktree '.length).trim())
+    .filter(Boolean);
+}
+
+function detectMainWorktreePath(lines: string[], cwd: string, commonDir: string | null) {
+  const worktrees = parseWorktreePaths(lines);
+  if (worktrees.length === 0) {
+    return null;
+  }
+
+  const resolvedCommonDir = commonDir ? path.resolve(commonDir) : null;
+  for (const wt of worktrees) {
+    const gitDir = getGitPath(wt, ['rev-parse', '--absolute-git-dir']);
+    const wtCommonDir = getGitPath(wt, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    if (
+      gitDir &&
+      wtCommonDir &&
+      path.resolve(gitDir) === path.resolve(wtCommonDir) &&
+      (!resolvedCommonDir || path.resolve(wtCommonDir) === resolvedCommonDir)
+    ) {
+      return wt;
+    }
+  }
+
+  const currentTopLevel = getGitPath(cwd, ['rev-parse', '--show-toplevel']);
+  if (currentTopLevel && worktrees.length === 1 && path.resolve(worktrees[0]) === path.resolve(currentTopLevel)) {
+    return worktrees[0];
+  }
+  return null;
+}
+
+function parseBlockUntil(value: string | number) {
+  if (typeof value !== 'string') {
+    return NaN;
+  }
+
+  const match = value.match(/^(\d{4})-(\d{2})-(\d{2}) (\d{2})$/);
+  if (!match) {
+    return NaN;
+  }
+
+  const [, yearStr, monthStr, dayStr, hourStr] = match;
+  const year = Number(yearStr);
+  const month = Number(monthStr);
+  const day = Number(dayStr);
+  const hour = Number(hourStr);
+  const parsed = new Date(year, month - 1, day, hour, 0, 0, 0);
+
+  if (
+    parsed.getFullYear() !== year ||
+    parsed.getMonth() !== month - 1 ||
+    parsed.getDate() !== day ||
+    parsed.getHours() !== hour
+  ) {
+    return NaN;
+  }
+
+  return parsed.getTime();
+}
+
+function isAgentBlocked(agent: string, config: AgentConfig | null) {
+  if (!config || !config.blocklist || config.blocklist[agent] === undefined) {
+    return false;
+  }
+  const entry = config.blocklist[agent];
+  if (entry === true) {return true;}
+  if (entry === false) {return false;}
+  if (entry && typeof entry === 'object') {
+    if (entry.blocked === true) {return true;}
+    if (entry.blocked === false) {return false;}
+    if (entry.until) {
+      const until = parseBlockUntil(entry.until);
+      if (!isNaN(until) && until > Date.now()) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function eligibleAgentsForStep(step: string, options: ReadAgentConfigOptions = {}) {
+  const /** @type {{blocklist?: {[key: string]: any}, steps?: {[key: string]: any}} | null} */ config = options.config !== undefined
+    ? options.config
+    : readAgentConfig(options.configPath || CONFIG_PATH, (options as {mergeLocal?: boolean, mainWorktreePath?: string | null, warn?: Function, targetPath?: string}));
+  let eligible: string[];
+  if (!config || !config.steps || !config.steps[step]) {
+    eligible = Object.keys(LAUNCHERS);
+  } else {
+    eligible = config.steps[step].eligible || Object.keys(LAUNCHERS);
+  }
+  return eligible.filter(/** @param {string} agent */ (agent) => !isAgentBlocked(agent, config));
+}
+
+function weightedRandom(agents: string[], weights: {[key: string]: number}) {
+  const total = agents.reduce(/** @param {number} sum @param {string} a */ (sum, a) => sum + (weights[a] || 1), 0);
+  let r = Math.random() * total;
+  for (const agent of agents) {
+    r -= weights[agent] || 1;
+    if (r <= 0) {return agent;}
+  }
+  return agents[agents.length - 1];
+}
+
+function selectAgent(step: string, options: ReadAgentConfigOptions = {}) {
+  const envOverride = process.env.WORKFLOW_AGENT;
+  const excluded = options.exclude instanceof Set ? options.exclude : new Set();
+  const eligible = eligibleAgentsForStep(step, options);
+  // Honor the env override only when it is in the current eligible-and-unblocked
+  // pool and not already excluded (a previous limit-hit attempt in the same
+  // startAgent retry loop). A pinned agent that is hard-blocked in
+  // agents.local.json or excluded by step eligibility falls through to normal
+  // selection — matches parallix/docs/agents.md, which documents that
+  // WORKFLOW_AGENT is honored alongside the eligibility config and blocklist.
+  if (envOverride && !excluded.has(envOverride) && eligible.includes(envOverride)) {
+    return envOverride;
+  }
+
+  const pool = eligible.filter(/** @param {string} agent */ (agent) => !excluded.has(agent));
+  if (eligible.length === 0) {
+    throw new Error(`No agents are eligible for workflow step: ${step}`);
+  }
+  if (pool.length === 0) {
+    throw new Error(
+      `All eligible agents for step "${step}" are exhausted (limit-hit or excluded). ` +
+      `Tried: ${[...excluded].join(', ')}.`
+    );
+  }
+
+  // Filter to agents that are both eligible (per config) and supported (launcher present).
+  const statuses = new Map(
+    pool
+      .filter(/** @param {string} agent */ (agent) => LAUNCHERS[agent])
+      .map(/** @param {string} agent */ (agent) => [agent, workflowLauncherStatus(agent)] as [string, LauncherStatus])
+  );
+  const available = pool.filter(/** @param {string} agent */ (agent) => {
+    const status = statuses.get(agent);
+    return Boolean(status && status.supported);
+  });
+  if (available.length === 0) {
+    const blockers = pool.map(/** @param {string} agent */ (agent) => {
+      const status = statuses.get(agent) || { detail: agent, reason: 'unsupported-agent' };
+      const suffix = status.reason ? `; ${status.reason}` : '';
+      return `${agent} (looked for: ${status.detail}${suffix})`;
+    });
+    throw new Error(
+      `No eligible agents have a working launcher for step "${step}". ` +
+      `Eligible but blocked: ${blockers.join(', ')}. ` +
+      `Set WORKFLOW_AGENT=<name> to override or install a supported agent.`
+    );
+  }
+
+  const /** @type {{blocklist?: {[key: string]: any}, steps?: {[key: string]: any}} | null} */ config = options.config !== undefined
+    ? options.config
+    : readAgentConfig(options.configPath || CONFIG_PATH, (options as {mergeLocal?: boolean, mainWorktreePath?: string | null, warn?: Function, targetPath?: string}));
+  const stepConfig = config && config.steps && config.steps[step] ? config.steps[step] : {};
+  const selection = stepConfig.selection || 'random';
+
+  if (selection === 'weighted') {
+    const weights = stepConfig.weights || {};
+    return weightedRandom(available, weights);
+  }
+
+  if (selection === 'random') {
+    return available[Math.floor(Math.random() * available.length)];
+  }
+
+  return available[0];
+}
+
+function assertAgentSupported(agent: string) {
+  if (!LAUNCHERS[agent]) {
+    const error: any = new Error(
+      `Unknown agent: "${fmt.agent(agent)}". Supported agents: ${Object.keys(LAUNCHERS).join(', ')}.`
+    );
+    error.code = 'UNKNOWN_AGENT';
+    throw error;
+  }
+
+  const status = workflowLauncherStatus(agent);
+  if (!status.supported) {
+    const health = status.health ? ` (${status.health})` : '';
+    const reason = status.reason ? `; reason: ${status.reason}` : '';
+    const error: any = new Error(
+      `Agent "${fmt.agent(agent)}" launcher is not available on this workstation${health}. ` +
+      `Looked for: ${fmt.path(status.detail)}${reason}. ` +
+      `Ensure ${fmt.agent(agent)} is on your PATH and retry.`
+    );
+    error.code = 'LAUNCHER_UNAVAILABLE';
+    throw error;
+  }
+}
+
+function resolveBlocklistTargetPath(options: {targetPath?: string} = {}) {
+  if (options.targetPath) {return options.targetPath;}
+  return storage.resolveAgentsLocalPath({ ensureDir: true });
+}
+
+function updateAgentBlock(agent: string, until: string, options: {targetPath?: string} = {}) {
+  if (!agent || typeof agent !== 'string') {
+    throw new Error('updateAgentBlock requires an agent name');
+  }
+  if (!until || typeof until !== 'string' || !/^\d{4}-\d{2}-\d{2} \d{2}$/.test(until)) {
+    throw new Error(`updateAgentBlock requires an "YYYY-MM-DD HH" timestamp; got: ${until}`);
+  }
+
+  const targetPath = resolveBlocklistTargetPath(options);
+
+  let payload: {blocklist?: {[key: string]: any}} = {};
+  if (fs.existsSync(targetPath)) {
+    // Match the read-path contract (parseAgentConfigFile): malformed local agent
+    // JSON is a hard failure, not a silent overwrite. Otherwise a limit hit on a
+    // corrupted agents.local.json would destroy whatever was on disk.
+    try {
+      payload = JSON.parse(fs.readFileSync(targetPath, 'utf8')) || {};
+    } catch (err) {
+      throw buildInvalidAgentConfigError(targetPath, 'local', (err as {message?: string}));
+    }
+    if (typeof payload !== 'object' || Array.isArray(payload)) {
+      throw buildInvalidAgentConfigError(
+        targetPath,
+        'local',
+        new Error('expected a JSON object at the file root')
+      );
+    }
+  }
+  if (!payload.blocklist || typeof payload.blocklist !== 'object' || Array.isArray(payload.blocklist)) {
+    payload.blocklist = {};
+  }
+  payload.blocklist[agent] = { until };
+
+  storage.writeJson(targetPath, payload);
+  return { path: targetPath, blocklist: payload.blocklist };
+}
+
+function defaultIsAgentBlockedNow(agent: string) {
+  try {
+    const config = readAgentConfig(CONFIG_PATH, {});
+    return isAgentBlocked(agent, config);
+  } catch (err) {
+    // If the config is malformed, surface that through the launcher path
+    // (assertAgentSupported / launch) instead of silently rerouting. Treat as
+    // not-blocked here so the existing error path runs.
+    return false;
+  }
+}
+
+function readPositiveMsEnv(name: string) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === '') {return null;}
+  const value = Number(raw);
+  return Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function resolveNoOutputWatchdogConfig(config: {initialDelayMs?: number, intervalMs?: number} | boolean, step: string | null = null) {
+  if (config === false || process.env.WORKFLOW_AGENT_NO_OUTPUT_WATCHDOG === '0') {
+    return null;
+  }
+  const explicit: {initialDelayMs?: number, intervalMs?: number} = config && typeof config === 'object' ? config : {};
+  // Draft gets a shorter default watchdog to surface agent-launch visibility
+  // quickly; the generic default (60s) is too slow for the draft entrypoint
+  // where an operator cannot tell launch from hang.
+  let initialDelayMs;
+  let intervalMs;
+  if (step === 'draft') {
+    initialDelayMs = explicit.initialDelayMs ??
+      readPositiveMsEnv('WORKFLOW_DRAFT_AGENT_NO_OUTPUT_INITIAL_MS') ??
+      DRAFT_NO_OUTPUT_INITIAL_DELAY_MS;
+    intervalMs = explicit.intervalMs ??
+      readPositiveMsEnv('WORKFLOW_DRAFT_AGENT_NO_OUTPUT_INTERVAL_MS') ??
+      DRAFT_NO_OUTPUT_INTERVAL_MS;
+  } else {
+    initialDelayMs = explicit.initialDelayMs ??
+      readPositiveMsEnv('WORKFLOW_AGENT_NO_OUTPUT_INITIAL_MS') ??
+      DEFAULT_NO_OUTPUT_INITIAL_DELAY_MS;
+    intervalMs = explicit.intervalMs ??
+      readPositiveMsEnv('WORKFLOW_AGENT_NO_OUTPUT_INTERVAL_MS') ??
+      DEFAULT_NO_OUTPUT_INTERVAL_MS;
+  }
+  return { initialDelayMs, intervalMs };
+}
+
+function formatElapsed(elapsedMs: number) {
+  const seconds = Math.max(0, Math.round(elapsedMs / 1000));
+  if (seconds < 60) {return `${seconds}s`;}
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return remainder === 0 ? `${minutes}m` : `${minutes}m ${remainder}s`;
+}
+
+async function startAgent(step: string, opts: StartAgentOptions = { prompt: '' }) {
+  const {
+    prompt,
+    worktree,
+    agent: agentOverride,
+    env = {},
+    exclude = [],
+    onLimitHit,
+    onLaunch,
+    slug = null,
+    role = null,
+    detectLimitHitFn = detectLimitHit,
+    updateAgentBlockFn = updateAgentBlock,
+    selectAgentFn = selectAgent,
+    resolveAgentModelFn = resolveAgentModel,
+    isAgentBlockedFn = defaultIsAgentBlockedNow,
+    sessionsModule = sessions,
+    log = fmt.log.plain,
+    noOutputWatchdog = {}
+  } = opts;
+
+  // `exclude` seeds the tried-set so callers can reserve agents (e.g. exclude
+  // the current implementer from reviewer fallback to preserve family separation).
+  const excludeIterable = exclude instanceof Set ? exclude : exclude;
+  const tried = new Set(excludeIterable);
+  // Track per-agent failure details for accurate exhaustion diagnostics (SC 3)
+  const agentErrors = new Map();
+  // Track agents actually launched (not just pre-excluded) for accurate reporting
+  const launched = new Set();
+  let iteration = 0;
+  let chosen = agentOverride;
+
+  while (true) {
+    iteration += 1;
+    if (!chosen) {
+      try {
+        chosen = selectAgentFn(step, { exclude: tried });
+      } catch (err) {
+        // Only catch pool exhaustion errors from selectAgent.
+        // Configuration errors (no eligible agents, no working launcher) must
+        // propagate unchanged to preserve diagnostics (SC 3).
+        // Exhaustion is indicated by:
+        // - "exhausted" from real selectAgent pool exhaustion ("are exhausted")
+        // - "No agents available" from test mocks simulating exhaustion
+        if (!((err as any).message || '').includes('exhausted') &&
+          !((err as any).message || '').includes('No agents available')
+        ) {
+          throw err;
+        }
+        // Pool exhausted; build clear exhaustion diagnostics with per-agent errors (SC 3)
+        const errorDetails = [...agentErrors.entries()].map(([agent, details]) => {
+          const status = details.exitInfo === 'stalled'
+            ? 'stalled (no output)'
+            : (details.status !== undefined && details.status !== null
+              ? `exit ${details.status}`
+              : (details.signal ? `signal ${details.signal}` : 'unknown'));
+          const stderrSnippet = details.stderr ? ` (${details.stderr.trim().split('\n')[0]})` : '';
+          return `${agent}: ${status}${stderrSnippet}`;
+        }).join('; ');
+        const launchedList = [...launched].join(', ');
+        throw new Error(
+          `All eligible agents exhausted for step "${step}". ` +
+          `Tried: ${launchedList}. Errors: ${errorDetails}.`
+        );
+      }
+    } else if (isAgentBlockedFn(chosen)) {
+      // Pre-launch blocklist gate. An explicit `agent:` override (e.g. a pinned
+      // reviewer/implementer carried over from review-state.json) bypasses
+      // selectAgent's blocklist filter. Without this check, a known-blocked
+      // family is relaunched immediately and the harness wastes a retry hitting
+      // the same limit. Reroute through normal selection on the next iteration.
+      log(fmt.status('WARN', `Pinned agent "${fmt.agent(chosen)}" is currently blocked in agents.local.json; rerouting via selectAgent for step "${step}".`));
+      tried.add(chosen);
+      chosen = undefined;
+      continue;
+    }
+
+    try {
+      assertAgentSupported(chosen || '');
+    } catch (err) {
+      /** @type {Error & {code?: string}} */
+      const e = (err as any);
+      if (e.code !== 'LAUNCHER_UNAVAILABLE') {
+        throw err;
+      }
+      log(fmt.status('WARN', (err as any).message));
+      // Only reroute for launcher-availability failures (missing or probe-failed).
+      tried.add(chosen || '');
+      // If the caller pinned a specific agent, allow one retry that ignores
+      // the override and falls back to normal selection (matches limit-hit logic).
+      if (agentOverride && agentOverride === chosen && iteration === 1) {
+        chosen = undefined;
+        continue;
+      }
+      chosen = undefined;
+      continue;
+    }
+    tried.add(chosen || '');
+    launched.add(chosen || '');
+
+    const launcher = LAUNCHERS[chosen || ''];
+    log(fmt.status('INFO', `Selected agent for step "${step}": ${fmt.agent(chosen || '')}${iteration > 1 ? ` (attempt ${iteration})` : ''}`));
+
+    // Enforce the agent family as the Forgejo identity (ADR 0029 / task-095).
+    // FORGEJO_USER is set last so the harness-selected identity always wins;
+    // a caller-supplied env.FORGEJO_USER cannot override it.
+    const agentEnv = { ...env, FORGEJO_USER: chosen };
+
+    // Decide whether to resume the agent's prior session for this (slug, role).
+    // Only honored when the caller passed slug+role+worktree AND the previous
+    // marker matches the chosen agent family (a fallback to a different family
+    // invalidates the prior session).
+    const resume = Boolean(
+      worktree && slug && role &&
+      RESUME_CAPABLE.has(chosen || '') &&
+      ((sessionsModule as any)).shouldResume(worktree, slug, role, chosen || '')
+    );
+    const sessionId = ((sessionsModule as any)).getSessionId(worktree, slug, role);
+    if (slug && role) {
+      if (resume) {
+        log(fmt.status('INFO', `Resuming ${fmt.agent(chosen || '')} session for ${fmt.slug(slug)} (${role}).${sessionId ? ` Session: ${sessionId}` : ''}`));
+      } else if (RESUME_CAPABLE.has(chosen || '')) {
+        log(fmt.status('INFO', `No prior ${fmt.agent(chosen || '')} session for ${fmt.slug(slug)} (${role}); launching fresh.`));
+      }
+    }
+
+    // Resolve the prompt string. If a function was provided, call it with the
+    // currently chosen agent name (TASK-1051). This ensures that if startAgent
+    // falls back to a different family after a limit hit, the fallback agent
+    // receives a prompt tailored to its own identity.
+    const actualPrompt = typeof prompt === 'function' ? prompt(chosen) : prompt;
+
+    // Resolve the per-family model override (adapters.agents.models[chosen]).
+    // null when the family is not configured, in which case the launcher omits
+    // the model flag entirely and the agent uses its own default.
+    const model = resolveAgentModelFn(chosen || '', worktree || process.cwd());
+    if (model) {
+      log(fmt.status('INFO', `Using configured model for ${fmt.agent(chosen || '')}: ${model}`));
+    }
+
+    const watchdogConfig = resolveNoOutputWatchdogConfig(noOutputWatchdog, step);
+    const launchResult = launcher({
+      prompt: actualPrompt,
+      worktree,
+      env: agentEnv,
+      resume,
+      sessionId,
+      model,
+      slug,
+      role,
+      teeOptions: watchdogConfig ? {
+        noOutputWatchdog: {
+          ...watchdogConfig,
+          onNoOutput: (evt: {pid: number, elapsedMs: number}) => {
+            const stage = evt.elapsedMs < (step === 'draft' ? DRAFT_NO_OUTPUT_INITIAL_DELAY_MS : DEFAULT_NO_OUTPUT_INITIAL_DELAY_MS)
+              ? 'starting up'
+              : 'running';
+            log(fmt.status(
+              'INFO',
+              `No output yet from ${fmt.agent(chosen || '')} for step "${step}" after ${formatElapsed(evt.elapsedMs)} ` +
+              `(pid ${evt.pid || 'unknown'}, agent ${stage}). ` +
+              `Launcher is still running; stdout/stderr have not produced visible output.`
+            ));
+          }
+        }
+      } : {}
+    });
+    const { invocation, resultPromise } = launchResult;
+    if (invocation) {
+      log(fmt.status('INFO', `Launching: ${fmt.command(`${invocation.command} ${invocation.args.join(' ')}`)}`));
+      if (invocation.options && invocation.options.cwd) {
+        log(fmt.status('INFO', `Working directory: ${fmt.path(invocation.options.cwd)}`));
+      }
+    }
+
+    if (onLaunch) {
+      await onLaunch({ agent: chosen, invocation });
+    }
+
+    const result = resultPromise ? await resultPromise : launchResult.result;
+
+    // Pass exit metadata so detectLimitHit only treats matching transcript text
+    // as a real limit hit when the launcher actually failed. A successful run
+    // (status === 0) that happens to contain limit-hit phrases — for example,
+    // an agent reviewing code or logs that quote those phrases — must not block
+    // the healthy agent.
+    const limitHit = detectLimitHitFn({
+      agent: chosen,
+      stdout: result && result.stdout,
+      stderr: result && result.stderr,
+      status: result && result.status,
+      signal: result && result.signal,
+      error: result && result.error
+    });
+
+    if (limitHit) {
+      log(fmt.status('WARN', `Limit hit detected for ${fmt.agent(chosen || '')}; reset estimate "${limitHit.until}" (${limitHit.source}). Blocking and retrying.`));
+      try {
+        const blockResult = updateAgentBlockFn(chosen || '', limitHit.until);
+        log(fmt.status('INFO', `Wrote blocklist entry for ${fmt.agent(chosen || '')} -> ${fmt.path(blockResult.path)}`));
+      } catch (err) {
+        log(fmt.status('WARN', `Could not persist blocklist entry for ${fmt.agent(chosen || '')}: ${(err as any).message}`));
+      }
+      if (typeof onLimitHit === 'function') {
+        onLimitHit({ agent: chosen, until: limitHit.until, source: limitHit.source });
+      }
+      // Reset chosen so next iteration reselects, but only when no explicit override.
+      // If the caller pinned a specific agent, fail loudly — there is no fallback.
+      if (agentOverride && agentOverride === chosen && iteration === 1) {
+        // Allow one retry that ignores the override.
+        chosen = undefined;
+        continue;
+      }
+      chosen = undefined;
+      continue;
+    }
+
+    // Reroute if the launcher binary could not be started (ENOENT = not found, EACCES = not executable).
+    if (result && result.error && (result.error.code === 'ENOENT' || result.error.code === 'EACCES')) {
+      log(fmt.status('WARN', `Launcher for "${chosen || ''}" could not be started (${result.error.code}); rerouting.`));
+      tried.add(chosen || '');
+      if (agentOverride && agentOverride === chosen && iteration === 1) {
+        chosen = undefined;
+        continue;
+      }
+      chosen = undefined;
+      continue;
+    }
+
+    // Detect launch failure: agent started but exited with non-zero status and
+    // no limit-hit was detected. This catches errors like "Model not found" in
+    // opencode that cause the launcher to exit immediately with an error code.
+    // Retry with the next eligible agent instead of returning the failure.
+    // Only treat `status !== null && status !== 0` or `signal` (with no spawn
+    // error) as a launch failure; `status: null` without signal is ambiguous
+    // (spawn-tee close event can emit null code) and should not trigger a retry.
+    // Spurious opencode v2.0.0 JSON-mode exits (exit 1 after a valid
+    // "reason":"stop" completion) are excluded — the agent completed, the
+    // non-zero code is a post-run cleanup race.
+    const launchFailed = result &&
+      ((result.status !== null && result.status !== 0) || (result.signal && !result.error)) &&
+      !limitHit &&
+      !isSpuriousOpencodeExit(result);
+    if (launchFailed) {
+      const exitInfo = result.signal
+        ? `signal ${result.signal}`
+        : `exit ${result.status}`;
+      const stderrSnippet = result && result.stderr
+        ? ` (${result.stderr.trim().split('\n')[0]})`
+        : '';
+      log(fmt.status('WARN', `Agent ${fmt.agent(chosen || '')} failed to complete (${exitInfo}${stderrSnippet}); retrying with next eligible agent.`));
+      agentErrors.set(chosen || '', {
+        exitInfo,
+        stderr: result.stderr,
+        stdout: result.stdout,
+        signal: result.signal,
+        status: result.status,
+      });
+      tried.add(chosen || '');
+      launched.add(chosen || '');
+      // Block non-custom agents on non-limit failures so selectAgent excludes them
+      // on the next retry iteration, and the review-loop fallback path can activate.
+      // custom (opencode/local AI) is excluded — exit 1 is a temporary local error.
+      if (chosen !== 'custom') {
+        const blockUntil = formatBlockUntil(new Date(Date.now() + DEFAULT_FALLBACK_HOURS * 60 * 60 * 1000));
+        try {
+          const blockResult = updateAgentBlockFn(chosen || '', blockUntil);
+          log(fmt.status('INFO', `Wrote blocklist entry for ${fmt.agent(chosen || '')} -> ${fmt.path(blockResult.path)} (${DEFAULT_FALLBACK_HOURS}h block)`));
+        } catch (err) {
+          log(fmt.status('WARN', `Could not persist blocklist entry for ${fmt.agent(chosen || '')}: ${(err as any).message}`));
+        }
+      }
+      chosen = undefined;
+      continue;
+    }
+    // Record the marker so a subsequent same-(slug, role) launch knows which
+    // family last ran here. We only persist when the run exited cleanly
+    // (status 0 and no spawn error); a failed launch should not overwrite
+    // the canonical session marker with a stale transcript.
+    if (worktree && slug && role && result && result.status === 0 && !result.error) {
+      try {
+        const sessionId = result && result.sessionId ? result.sessionId : null;
+        ((sessionsModule as any)).writeSession(worktree, slug, role, { agent: chosen || '', sessionId });
+      } catch (err) {
+        log(fmt.status('WARN', `Could not persist session marker for ${fmt.slug(slug)} (${role}): ${(err as any).message}`));
+      }
+    }
+
+    return { agent: chosen, invocation, result };
+  }
+}
+
+// Legacy alias kept for backwards compatibility — draft.js calls this directly.
+// Returns { agent, invocation, result } so callers can log which agent ran.
+async function startDraftAgent(opts: StartAgentOptions = { prompt: '' }) {
+  return startAgent('draft', opts);
+}
+
+const setCommandPathProbe = (fn: (name: string) => string | null) => { _commandPathProbe = fn; };
+
+export {
+  KNOWN_AGENT_NAMES,
+  WORKFLOW_AGENT_NAMES,
+  startAgent,
+  startDraftAgent,
+  selectAgent,
+  eligibleAgentsForStep,
+  readAgentConfig,
+  readAgentConfigOrExit,
+  assertAgentSupported,
+  workflowLauncherStatus,
+  setCommandPathProbe,
+  isAgentBlocked,
+  parseBlockUntil,
+  isInvalidAgentConfigError,
+  updateAgentBlock,
+  resolveBlocklistTargetPath,
+  resolveNoOutputWatchdogConfig
+};