@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/agents/agents.js

@@ -24,8 +24,10 @@ 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.
+/** @type {((name: string) => string | null) | null} */
 let _commandPathProbe = null;
 
+/** @type {{[key: string]: Function}} */
 const LAUNCHERS = {
   codex: startCodexDraftAgent,
   claude: startClaudeAgent,
@@ -33,6 +35,7 @@ const LAUNCHERS = {
   custom: startOpencodeAgent
 };
 
+/** @type {{[key: string]: () => string}} */
 const RESOLVERS = {
   codex: resolveCodexCommand,
   claude: resolveClaudeCommand,
@@ -40,6 +43,7 @@ const RESOLVERS = {
   custom: resolveOpencodeCommand
 };
 
+/** @type {{[key: string]: string[]}} */
 const HEALTH_PROBE_ARGS = Object.freeze({
   codex: ['--help'],
   claude: ['--help'],
@@ -58,6 +62,7 @@ const KNOWN_AGENT_NAMES = Object.freeze([
   'human'
 ]);
 
+/** @param {string} agent */
 function workflowLauncherStatus(agent) {
   const resolver = RESOLVERS[agent];
   if (!resolver) {
@@ -77,8 +82,10 @@ function workflowLauncherStatus(agent) {
   });
 
   if (probe.error || probe.status !== 0) {
+    /** @type {Error & {code?: string}} */
+    const pErr = probe.error || new Error('');
     const reason = probe.error
-      ? probe.error.code || probe.error.message
+      ? (pErr.code || pErr.message)
       : `exit ${probe.status}`;
     return {
       agent,
@@ -92,6 +99,7 @@ function workflowLauncherStatus(agent) {
   return { agent, supported: true, detail: `${command} ${probeArgs.join(' ')}`.trim(), health: 'ok' };
 }
 
+/** @param {string} name */
 function commandInPath(name) {
   if (_commandPathProbe) {
     return _commandPathProbe(name) || false;
@@ -103,9 +111,11 @@ function commandInPath(name) {
   return result.status === 0 && result.stdout.trim().length > 0;
 }
 
+/** @param {string} configPath @param {string} scope @param {{message?: string} | null} originalError */
 function buildInvalidAgentConfigError(configPath, scope, originalError) {
   const location = path.resolve(configPath);
   const detail = originalError && originalError.message ? originalError.message : 'invalid JSON';
+  /** @type {any} */
   const error = 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.'
@@ -116,6 +126,7 @@ function buildInvalidAgentConfigError(configPath, scope, originalError) {
   return error;
 }
 
+/** @param {{code?: string}} error */
 function isInvalidAgentConfigError(error) {
   return Boolean(error && error.code === 'WORKFLOW_AGENT_CONFIG_INVALID');
 }
@@ -123,30 +134,33 @@ function isInvalidAgentConfigError(error) {
 function readAgentConfigOrExit(configPath = CONFIG_PATH, options = {}) {
   try {
     return readAgentConfig(configPath, options);
-  } catch (error) {
-    if (isInvalidAgentConfigError(error)) {
-      fmt.log.fail(error.message);
+  } catch (/** @type {unknown} */ error) {
+    if (isInvalidAgentConfigError(/** @type {any} */ (error))) {
+      fmt.log.fail(/** @type {any} */ (error).message);
       process.exit(1);
     }
     throw error;
   }
 }
 
+/** @param {string} configPath @param {string} scope */
 function parseAgentConfigFile(configPath, scope) {
   try {
     return JSON.parse(fs.readFileSync(configPath, 'utf8'));
-  } catch (err) {
-    throw buildInvalidAgentConfigError(configPath, scope, err);
+  } catch (/** @type {unknown} */ err) {
+    throw buildInvalidAgentConfigError(configPath, scope, /** @type {{message?: string}} */ (err));
   }
 }
 
+/** @param {{mergeLocal?: boolean, mainWorktreePath?: string | null, warn?: Function, targetPath?: string}} options */
 function readAgentConfig(configPath = CONFIG_PATH, options = {}) {
   const {
     mergeLocal = path.resolve(configPath) === path.resolve(CONFIG_PATH),
     mainWorktreePath,
     warn = fmt.log.warn
   } = options;
-  let config = null;
+  /** @type {{blocklist?: {[key: string]: any}, steps?: {[key: string]: any}}} */
+  let config = {};
   if (fs.existsSync(configPath)) {
     config = parseAgentConfigFile(configPath, 'workflow');
   }
@@ -157,12 +171,12 @@ function readAgentConfig(configPath = CONFIG_PATH, options = {}) {
     const mainWorktree = mainWorktreePath !== undefined
       ? mainWorktreePath
       : getMainWorktreePath({ cwd: projectRoot, warn });
-    const legacyPaths = [
+    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') : null
-    ].filter(Boolean);
-    const targetPath = options.targetPath || storage.resolveAgentsLocalPath({ ensureDir: true });
+      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({
@@ -170,14 +184,14 @@ function readAgentConfig(configPath = CONFIG_PATH, options = {}) {
           destinationPath: targetPath,
           warn
         });
-      } catch (error) {
-        throw buildInvalidAgentConfigError(targetPath, 'local', error);
+      } catch (/** @type {unknown} */ error) {
+        throw buildInvalidAgentConfigError(targetPath, 'local', /** @type {any} */ (error));
       }
     }
     if (fs.existsSync(targetPath)) {
       const localConfig = parseAgentConfigFile(targetPath, 'local');
       if (localConfig && localConfig.blocklist) {
-        config.blocklist = Object.assign(config.blocklist || {}, localConfig.blocklist);
+        /** @type {{blocklist?: {[key: string]: any}}} */ (config).blocklist = Object.assign(/** @type {{blocklist?: {[key: string]: any}}} */ (config).blocklist || {}, localConfig.blocklist);
       }
     }
   }
@@ -185,6 +199,7 @@ function readAgentConfig(configPath = CONFIG_PATH, options = {}) {
   return config;
 }
 
+/** @param {{cwd?: string, warn?: Function}} options */
 function getMainWorktreePath(options = {}) {
   const { cwd = process.cwd(), warn = fmt.log.warn } = options;
   try {
@@ -209,7 +224,7 @@ function getMainWorktreePath(options = {}) {
     const lines = result.stdout.split('\n');
     const mainWorktreePath = detectMainWorktreePath(lines, cwd, commonDir);
     if (mainWorktreePath) {
-      if (commonDir) MainWorktreeDetector.byCommonDir.set(commonDir, mainWorktreePath);
+      if (commonDir) {MainWorktreeDetector.byCommonDir.set(commonDir, mainWorktreePath);}
       return mainWorktreePath;
     }
 
@@ -220,7 +235,7 @@ function getMainWorktreePath(options = {}) {
         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);
+          if (commonDir) {MainWorktreeDetector.byCommonDir.set(commonDir, wt);}
           return wt;
         }
       }
@@ -232,13 +247,15 @@ function getMainWorktreePath(options = {}) {
       if (lines[i].startsWith('worktree ')) {
         const wt = lines[i].slice('worktree '.length).trim();
         if (wt !== cwd) {
-          if (commonDir) MainWorktreeDetector.byCommonDir.set(commonDir, wt);
+          if (commonDir) {MainWorktreeDetector.byCommonDir.set(commonDir, wt);}
           return wt;
         }
       }
     }
-  } catch (err) {
-    const detail = err && (err.code || err.message) ? (err.code || err.message) : 'unknown error';
+  } catch (/** @type {unknown} */ err) {
+    /** @type {Error & {code?: string}} */
+    const e = /** @type {any} */ (err);
+    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}).`
@@ -261,6 +278,7 @@ const MainWorktreeDetector = {
   byCommonDir: new Map()
 };
 
+/** @param {string} cwd @param {string[]} args */
 function getGitPath(cwd, args) {
   const result = spawnSync('git', ['-C', cwd, ...args], {
     encoding: 'utf8',
@@ -273,13 +291,15 @@ function getGitPath(cwd, args) {
   return result.stdout.trim() || null;
 }
 
+/** @param {string[]} lines */
 function parseWorktreePaths(lines) {
   return lines
-    .filter(line => line.startsWith('worktree '))
-    .map(line => line.slice('worktree '.length).trim())
+    .filter(/** @param {string} line */ (line) => line.startsWith('worktree '))
+    .map(/** @param {string} line */ (line) => line.slice('worktree '.length).trim())
     .filter(Boolean);
 }
 
+/** @param {string[]} lines @param {string} cwd @param {string | null} commonDir */
 function detectMainWorktreePath(lines, cwd, commonDir) {
   const worktrees = parseWorktreePaths(lines);
   if (worktrees.length === 0) {
@@ -307,6 +327,7 @@ function detectMainWorktreePath(lines, cwd, commonDir) {
   return null;
 }
 
+/** @param {string | number} value */
 function parseBlockUntil(value) {
   if (typeof value !== 'string') {
     return NaN;
@@ -336,16 +357,20 @@ function parseBlockUntil(value) {
   return parsed.getTime();
 }
 
+/**
+ * @param {string} agent
+ * @param {{blocklist?: {[key: string]: any}, steps?: {[key: string]: any}} | null} config
+ */
 function isAgentBlocked(agent, config) {
   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 === 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.blocked === true) {return true;}
+    if (entry.blocked === false) {return false;}
     if (entry.until) {
       const until = parseBlockUntil(entry.until);
       if (!isNaN(until) && until > Date.now()) {
@@ -356,29 +381,38 @@ function isAgentBlocked(agent, config) {
   return false;
 }
 
+/**
+ * @param {string} step
+ * @param {{config?: {blocklist?: {[key: string]: any}, steps?: {[key: string]: any}}, configPath?: string}} options
+ */
 function eligibleAgentsForStep(step, options = {}) {
-  const config = options.config !== undefined
+  const /** @type {{blocklist?: {[key: string]: any}, steps?: {[key: string]: any}} | null} */ config = options.config !== undefined
     ? options.config
-    : readAgentConfig(options.configPath || CONFIG_PATH, options);
+    : readAgentConfig(options.configPath || CONFIG_PATH, /** @type {{mergeLocal?: boolean, mainWorktreePath?: string | null, warn?: Function, targetPath?: string}} */ (options));
   let eligible;
   if (!config || !config.steps || !config.steps[step]) {
     eligible = Object.keys(LAUNCHERS);
   } else {
     eligible = config.steps[step].eligible || Object.keys(LAUNCHERS);
   }
-  return eligible.filter(agent => !isAgentBlocked(agent, config));
+  return eligible.filter(/** @param {string} agent */ (agent) => !isAgentBlocked(agent, config));
 }
 
+/** @param {string[]} agents @param {{[key: string]: number}} weights */
 function weightedRandom(agents, weights) {
-  const total = agents.reduce((sum, a) => sum + (weights[a] || 1), 0);
+  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;
+    if (r <= 0) {return agent;}
   }
   return agents[agents.length - 1];
 }
 
+/**
+ * @param {string} step
+ * @param {{exclude?: Set<string>, config?: {blocklist?: {[key: string]: any}, steps?: {[key: string]: any}}, configPath?: string}} options
+ */
 function selectAgent(step, options = {}) {
   const envOverride = process.env.WORKFLOW_AGENT;
   const excluded = options.exclude instanceof Set ? options.exclude : new Set();
@@ -393,7 +427,7 @@ function selectAgent(step, options = {}) {
     return envOverride;
   }
 
-  const pool = eligible.filter(agent => !excluded.has(agent));
+  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}`);
   }
@@ -407,15 +441,15 @@ function selectAgent(step, options = {}) {
   // Filter to agents that are both eligible (per config) and supported (launcher present).
   const statuses = new Map(
     pool
-      .filter(agent => LAUNCHERS[agent])
-      .map(agent => [agent, workflowLauncherStatus(agent)])
+      .filter(/** @param {string} agent */ (agent) => LAUNCHERS[agent])
+      .map(/** @param {string} agent */ (agent) => [agent, workflowLauncherStatus(agent)])
   );
-  const available = pool.filter(agent => {
+  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(agent => {
+    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})`;
@@ -427,9 +461,9 @@ function selectAgent(step, options = {}) {
     );
   }
 
-  const config = options.config !== undefined
+  const /** @type {{blocklist?: {[key: string]: any}, steps?: {[key: string]: any}} | null} */ config = options.config !== undefined
     ? options.config
-    : readAgentConfig(options.configPath || CONFIG_PATH, options);
+    : readAgentConfig(options.configPath || CONFIG_PATH, /** @type {{mergeLocal?: boolean, mainWorktreePath?: string | null, warn?: Function, targetPath?: string}} */ (options));
   const stepConfig = config && config.steps && config.steps[step] ? config.steps[step] : {};
   const selection = stepConfig.selection || 'random';
 
@@ -445,8 +479,10 @@ function selectAgent(step, options = {}) {
   return available[0];
 }
 
+/** @param {string} agent */
 function assertAgentSupported(agent) {
   if (!LAUNCHERS[agent]) {
+    /** @type {any} */
     const error = new Error(
       `Unknown agent: "${fmt.agent(agent)}". Supported agents: ${Object.keys(LAUNCHERS).join(', ')}.`
     );
@@ -458,6 +494,7 @@ function assertAgentSupported(agent) {
   if (!status.supported) {
     const health = status.health ? ` (${status.health})` : '';
     const reason = status.reason ? `; reason: ${status.reason}` : '';
+    /** @type {any} */
     const error = new Error(
       `Agent "${fmt.agent(agent)}" launcher is not available on this workstation${health}. ` +
       `Looked for: ${fmt.path(status.detail)}${reason}. ` +
@@ -468,11 +505,13 @@ function assertAgentSupported(agent) {
   }
 }
 
+/** @param {{targetPath?: string}} options */
 function resolveBlocklistTargetPath(options = {}) {
-  if (options.targetPath) return options.targetPath;
+  if (options.targetPath) {return options.targetPath;}
   return storage.resolveAgentsLocalPath({ ensureDir: true });
 }
 
+/** @param {string} agent @param {string} until @param {{targetPath?: string}} options */
 function updateAgentBlock(agent, until, options = {}) {
   if (!agent || typeof agent !== 'string') {
     throw new Error('updateAgentBlock requires an agent name');
@@ -483,6 +522,7 @@ function updateAgentBlock(agent, until, options = {}) {
 
   const targetPath = resolveBlocklistTargetPath(options);
 
+  /** @type {{blocklist?: {[key: string]: any}}} */
   let payload = {};
   if (fs.existsSync(targetPath)) {
     // Match the read-path contract (parseAgentConfigFile): malformed local agent
@@ -490,8 +530,8 @@ function updateAgentBlock(agent, until, options = {}) {
     // 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);
+    } catch (/** @type {unknown} */ err) {
+      throw buildInvalidAgentConfigError(targetPath, 'local', /** @type {{message?: string}} */ (err));
     }
     if (typeof payload !== 'object' || Array.isArray(payload)) {
       throw buildInvalidAgentConfigError(
@@ -510,11 +550,12 @@ function updateAgentBlock(agent, until, options = {}) {
   return { path: targetPath, blocklist: payload.blocklist };
 }
 
+/** @param {string} agent */
 function defaultIsAgentBlockedNow(agent) {
   try {
     const config = readAgentConfig(CONFIG_PATH, {});
     return isAgentBlocked(agent, config);
-  } catch (err) {
+  } catch (/** @type {unknown} */ 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.
@@ -522,18 +563,20 @@ function defaultIsAgentBlockedNow(agent) {
   }
 }
 
+/** @param {string} name */
 function readPositiveMsEnv(name) {
   const raw = process.env[name];
-  if (raw === undefined || raw === '') return null;
+  if (raw === undefined || raw === '') {return null;}
   const value = Number(raw);
   return Number.isFinite(value) && value >= 0 ? value : null;
 }
 
-function resolveNoOutputWatchdogConfig(config = {}, step = null) {
+/** @param {{initialDelayMs?: number, intervalMs?: number}|boolean} config @param {string | null} step */
+function resolveNoOutputWatchdogConfig(config, step = null) {
   if (config === false || process.env.WORKFLOW_AGENT_NO_OUTPUT_WATCHDOG === '0') {
     return null;
   }
-  const explicit = config && typeof config === 'object' ? config : {};
+  const /** @type {{initialDelayMs?: number, intervalMs?: number}} */ explicit = 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.
@@ -557,15 +600,20 @@ function resolveNoOutputWatchdogConfig(config = {}, step = null) {
   return { initialDelayMs, intervalMs };
 }
 
+/** @param {number} elapsedMs */
 function formatElapsed(elapsedMs) {
   const seconds = Math.max(0, Math.round(elapsedMs / 1000));
-  if (seconds < 60) return `${seconds}s`;
+  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, opts = {}) {
+/**
+ * @param {string} step
+ * @param {{prompt: string | Function, worktree?: string, agent?: string, env?: {[key: string]: string}, exclude?: (string|null|Set<string>)[], onLimitHit?: Function, onLaunch?: Function, slug?: string | null, role?: string | null, detectLimitHitFn?: Function, updateAgentBlockFn?: Function, selectAgentFn?: Function, resolveAgentModelFn?: Function, isAgentBlockedFn?: Function, sessionsModule?: object, log?: Function, noOutputWatchdog?: {initialDelayMs?: number, intervalMs?: number}}} opts
+ */
+async function startAgent(step, opts = { prompt: '' }) {
   const {
     prompt,
     worktree,
@@ -602,17 +650,16 @@ async function startAgent(step, opts = {}) {
     if (!chosen) {
       try {
         chosen = selectAgentFn(step, { exclude: tried });
-      } catch (err) {
+      } catch (/** @type {unknown} */ 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.message || !(
-          err.message.includes('exhausted') ||
-          err.message.includes('No agents available')
-        )) {
+        if (!(/** @type {any} */ (err).message || '').includes('exhausted') &&
+          !(/** @type {any} */ (err).message || '').includes('No agents available')
+        ) {
           throw err;
         }
         // Pool exhausted; build clear exhaustion diagnostics with per-agent errors (SC 3)
@@ -639,33 +686,35 @@ async function startAgent(step, opts = {}) {
       // 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 = null;
+      chosen = undefined;
       continue;
     }
 
     try {
-      assertAgentSupported(chosen);
-    } catch (err) {
-      if (err.code !== 'LAUNCHER_UNAVAILABLE') {
+      assertAgentSupported(chosen || '');
+    } catch (/** @type {unknown} */ err) {
+      /** @type {Error & {code?: string}} */
+      const e = /** @type {any} */ (err);
+      if (e.code !== 'LAUNCHER_UNAVAILABLE') {
         throw err;
       }
-      log(fmt.status('WARN', err.message));
+      log(fmt.status('WARN', /** @type {any} */ (err).message));
       // Only reroute for launcher-availability failures (missing or probe-failed).
-      tried.add(chosen);
+      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 = null;
+        chosen = undefined;
         continue;
       }
-      chosen = null;
+      chosen = undefined;
       continue;
     }
-    tried.add(chosen);
-    launched.add(chosen);
+    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})` : ''}`));
+    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;
@@ -678,15 +727,15 @@ async function startAgent(step, opts = {}) {
     // invalidates the prior session).
     const resume = Boolean(
       worktree && slug && role &&
-      RESUME_CAPABLE.has(chosen) &&
-      sessionsModule.shouldResume(worktree, slug, role, chosen)
+      RESUME_CAPABLE.has(chosen || '') &&
+      (/** @type {any} */ (sessionsModule)).shouldResume(worktree, slug, role, chosen || '')
     );
-    const sessionId = sessionsModule.getSessionId(worktree, slug, role);
+    const sessionId = (/** @type {any} */ (sessionsModule)).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.`));
+        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.`));
       }
     }
 
@@ -699,9 +748,9 @@ async function startAgent(step, opts = {}) {
     // 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());
+    const model = resolveAgentModelFn(chosen || '', worktree || process.cwd());
     if (model) {
-      log(fmt.status('INFO', `Using configured model for ${fmt.agent(chosen)}: ${model}`));
+      log(fmt.status('INFO', `Using configured model for ${fmt.agent(chosen || '')}: ${model}`));
     }
 
     const watchdogConfig = resolveNoOutputWatchdogConfig(noOutputWatchdog, step);
@@ -717,14 +766,14 @@ async function startAgent(step, opts = {}) {
       teeOptions: watchdogConfig ? {
         noOutputWatchdog: {
           ...watchdogConfig,
-          onNoOutput: ({ pid, elapsedMs }) => {
-            const stage = elapsedMs < (step === 'draft' ? DRAFT_NO_OUTPUT_INITIAL_DELAY_MS : DEFAULT_NO_OUTPUT_INITIAL_DELAY_MS)
+          onNoOutput: (/** @type {{pid: number, elapsedMs: number}} */ evt) => {
+            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(elapsedMs)} ` +
-              `(pid ${pid || 'unknown'}, agent ${stage}). ` +
+              `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.`
             ));
           }
@@ -760,12 +809,12 @@ async function startAgent(step, opts = {}) {
     });
 
     if (limitHit) {
-      log(fmt.status('WARN', `Limit hit detected for ${fmt.agent(chosen)}; reset estimate "${limitHit.until}" (${limitHit.source}). Blocking and retrying.`));
+      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.message}`));
+        const blockResult = updateAgentBlockFn(chosen || '', limitHit.until);
+        log(fmt.status('INFO', `Wrote blocklist entry for ${fmt.agent(chosen || '')} -> ${fmt.path(blockResult.path)}`));
+      } catch (/** @type {unknown} */ err) {
+        log(fmt.status('WARN', `Could not persist blocklist entry for ${fmt.agent(chosen || '')}: ${/** @type {any} */ (err).message}`));
       }
       if (typeof onLimitHit === 'function') {
         onLimitHit({ agent: chosen, until: limitHit.until, source: limitHit.source });
@@ -774,22 +823,22 @@ async function startAgent(step, opts = {}) {
       // 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 = null;
+        chosen = undefined;
         continue;
       }
-      chosen = null;
+      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);
+      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 = null;
+        chosen = undefined;
         continue;
       }
-      chosen = null;
+      chosen = undefined;
       continue;
     }
 
@@ -814,29 +863,29 @@ async function startAgent(step, opts = {}) {
       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, {
+      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);
+      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.message}`));
+          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 (/** @type {unknown} */ err) {
+          log(fmt.status('WARN', `Could not persist blocklist entry for ${fmt.agent(chosen || '')}: ${/** @type {any} */ (err).message}`));
         }
       }
-      chosen = null;
+      chosen = undefined;
       continue;
     }
     // Record the marker so a subsequent same-(slug, role) launch knows which
@@ -846,9 +895,9 @@ async function startAgent(step, opts = {}) {
     if (worktree && slug && role && result && result.status === 0 && !result.error) {
       try {
         const sessionId = result && result.sessionId ? result.sessionId : null;
-        sessionsModule.writeSession(worktree, slug, role, { agent: chosen, sessionId });
-      } catch (err) {
-        log(fmt.status('WARN', `Could not persist session marker for ${fmt.slug(slug)} (${role}): ${err.message}`));
+        (/** @type {any} */ (sessionsModule)).writeSession(worktree, slug, role, { agent: chosen || '', sessionId });
+      } catch (/** @type {unknown} */ err) {
+        log(fmt.status('WARN', `Could not persist session marker for ${fmt.slug(slug)} (${role}): ${/** @type {any} */ (err).message}`));
       }
     }
 
@@ -858,7 +907,7 @@ async function startAgent(step, opts = {}) {
 
 // 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 = {}) {
+async function startDraftAgent(opts = { prompt: '' }) {
   return startAgent('draft', opts);
 }
 
@@ -873,7 +922,7 @@ module.exports = {
   readAgentConfigOrExit,
   assertAgentSupported,
   workflowLauncherStatus,
-  setCommandPathProbe: (fn) => { _commandPathProbe = fn; },
+  setCommandPathProbe: (/** @type {(name: string) => string | null} */ fn) => { _commandPathProbe = fn; },
   isAgentBlocked,
   parseBlockUntil,
   isInvalidAgentConfigError,