kanbango 3.5.0 → 3.8.0

package/workflow.js

@@ -0,0 +1,806 @@
+const fs = require('fs').promises;
+const path = require('path');
+const { spawn } = require('child_process');
+const kanban = require('./kanban.js');
+
+const BACKLOG = path.join(process.cwd(), 'backlog');
+const CONFIG_PATH = path.join(BACKLOG, 'kanbango.json');
+const JOBS_DIR = path.join(BACKLOG, '.workflow');
+
+const GATE_COLUMNS = ['testing', 'review'];
+const DEFAULT_LABELS = {
+  icebox: 'Icebox',
+  planned: 'Planned',
+  active: 'NOW',
+  testing: 'Testing',
+  review: 'Review',
+  done: 'Done'
+};
+
+/** PIDs spawned by this process — only these may be SIGTERM'd on timeout. */
+const ownedPids = new Set();
+/** In-flight run_ids to prevent double-spawn within this process. */
+const runningLocal = new Set();
+
+let cachedConfig = null;
+let cacheCwd = null;
+let ensureTail = Promise.resolve();
+
+function workflowError(code, message, hint, details = {}) {
+  return kanban.createKanbanError(code, message, hint, details, false, 400);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function parseAgentField(value, fieldName, defaultName) {
+  if (value === undefined) {
+    return { enabled: true, name: defaultName };
+  }
+  if (typeof value === 'string') {
+    if (!isNonEmptyString(value)) {
+      throw workflowError(
+        'CONFIG_INVALID',
+        `workflow.${fieldName} must be a non-empty string when set`,
+        `Fix workflow.${fieldName} in backlog/kanbango.json`,
+        { field: `workflow.${fieldName}` }
+      );
+    }
+    return { enabled: true, name: value.trim() };
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `workflow.${fieldName} must be a string or { enabled, name }`,
+      `Use a name string or object with optional enabled/name`,
+      { field: `workflow.${fieldName}` }
+    );
+  }
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `workflow.${fieldName}.enabled must be a boolean`,
+      'Use true or false',
+      { field: `workflow.${fieldName}.enabled` }
+    );
+  }
+  if (value.name !== undefined && !isNonEmptyString(value.name)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `workflow.${fieldName}.name must be a non-empty string when set`,
+      `Fix workflow.${fieldName}.name in backlog/kanbango.json`,
+      { field: `workflow.${fieldName}.name` }
+    );
+  }
+  return {
+    enabled: value.enabled === undefined ? true : value.enabled,
+    name: isNonEmptyString(value.name) ? value.name.trim() : defaultName
+  };
+}
+
+function parseGateColumn(value, columnId) {
+  if (value === undefined) {
+    return { enabled: true, label: DEFAULT_LABELS[columnId] };
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `columns.${columnId} must be an object`,
+      `Use { "enabled": true, "label": "${DEFAULT_LABELS[columnId]}" }`,
+      { field: `columns.${columnId}` }
+    );
+  }
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `columns.${columnId}.enabled must be a boolean`,
+      'Use true or false',
+      { field: `columns.${columnId}.enabled` }
+    );
+  }
+  if (value.label !== undefined && !isNonEmptyString(value.label)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `columns.${columnId}.label must be a non-empty string when set`,
+      `Fix columns.${columnId}.label in backlog/kanbango.json`,
+      { field: `columns.${columnId}.label` }
+    );
+  }
+  return {
+    enabled: value.enabled === undefined ? true : value.enabled,
+    label: isNonEmptyString(value.label) ? value.label.trim() : DEFAULT_LABELS[columnId]
+  };
+}
+
+function assertWorkflowShape(workflow) {
+  if (!workflow || typeof workflow !== 'object' || Array.isArray(workflow)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'workflow config must be an object',
+      'Set backlog/kanbango.json with a workflow object',
+      { field: 'workflow' }
+    );
+  }
+  if (typeof workflow.enabled !== 'boolean') {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'workflow.enabled must be a boolean',
+      'Use "enabled": true or false',
+      { field: 'workflow.enabled' }
+    );
+  }
+  if (workflow.command !== undefined && !isNonEmptyString(workflow.command)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'workflow.command must be a non-empty string when set',
+      'Fix workflow.command in backlog/kanbango.json',
+      { field: 'workflow.command' }
+    );
+  }
+  if (workflow.e2e_agent !== undefined && !isNonEmptyString(workflow.e2e_agent)
+    && !(workflow.e2e_agent && typeof workflow.e2e_agent === 'object')) {
+    // Keep legacy string validation; object form not used for spawn yet.
+    if (typeof workflow.e2e_agent === 'string' && !isNonEmptyString(workflow.e2e_agent)) {
+      throw workflowError(
+        'CONFIG_INVALID',
+        'workflow.e2e_agent must be a non-empty string when set',
+        'Fix workflow.e2e_agent in backlog/kanbango.json',
+        { field: 'workflow.e2e_agent' }
+      );
+    }
+  }
+  if (workflow.timeout_ms !== undefined) {
+    if (!Number.isInteger(workflow.timeout_ms) || workflow.timeout_ms <= 0) {
+      throw workflowError(
+        'CONFIG_INVALID',
+        'workflow.timeout_ms must be a positive integer',
+        'Use milliseconds, e.g. 600000',
+        { field: 'workflow.timeout_ms' }
+      );
+    }
+  }
+  // Validate agent fields early (parseAgentField throws CONFIG_INVALID).
+  parseAgentField(workflow.testing_agent, 'testing_agent', 'qa-tester');
+  parseAgentField(workflow.review_agent, 'review_agent', 'temida');
+  if (workflow.e2e_agent !== undefined && typeof workflow.e2e_agent === 'string') {
+    parseAgentField(workflow.e2e_agent, 'e2e_agent', 'qa-e2e-tester');
+  }
+}
+
+function assertColumnsShape(columns) {
+  if (columns === undefined) return;
+  if (!columns || typeof columns !== 'object' || Array.isArray(columns)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'columns config must be an object',
+      'Use { "testing": { "enabled": true, "label": "Testing" }, "review": { ... } }',
+      { field: 'columns' }
+    );
+  }
+  for (const key of Object.keys(columns)) {
+    if (!GATE_COLUMNS.includes(key)) {
+      throw workflowError(
+        'CONFIG_INVALID',
+        `columns.${key} is not configurable`,
+        'Only testing and review may be set under columns',
+        { field: `columns.${key}`, allowed: GATE_COLUMNS }
+      );
+    }
+  }
+  parseGateColumn(columns.testing, 'testing');
+  parseGateColumn(columns.review, 'review');
+}
+
+function buildTransitions(testingOn, reviewOn) {
+  const afterActive = testingOn ? 'testing' : (reviewOn ? 'review' : 'done');
+  const afterTesting = reviewOn ? 'review' : 'done';
+
+  const transitions = {
+    icebox: ['planned'],
+    planned: ['active', 'icebox', afterActive],
+    active: ['planned', afterActive, 'icebox'],
+    done: ['active']
+  };
+
+  // Dedupe while preserving order
+  for (const key of Object.keys(transitions)) {
+    transitions[key] = [...new Set(transitions[key])];
+  }
+
+  if (testingOn) {
+    transitions.testing = ['active', afterTesting];
+  }
+  if (reviewOn) {
+    transitions.review = ['active', 'done'];
+  }
+
+  return transitions;
+}
+
+function buildActiveCols(testingOn, reviewOn) {
+  const cols = ['active', 'planned', 'icebox'];
+  if (testingOn) cols.push('testing');
+  if (reviewOn) cols.push('review');
+  cols.push('done');
+  return cols;
+}
+
+function planDoneTarget(testingOn, reviewOn) {
+  if (testingOn) return 'testing';
+  if (reviewOn) return 'review';
+  return 'done';
+}
+
+function defaultConfig() {
+  const testingOn = true;
+  const reviewOn = true;
+  return {
+    missing: true,
+    enabled: false,
+    command: 'opencode',
+    testing_agent: { enabled: true, name: 'qa-tester' },
+    e2e_agent: { enabled: true, name: 'qa-e2e-tester' },
+    review_agent: { enabled: true, name: 'temida' },
+    timeout_ms: 600000,
+    columns: {
+      icebox: { enabled: true, label: DEFAULT_LABELS.icebox },
+      planned: { enabled: true, label: DEFAULT_LABELS.planned },
+      active: { enabled: true, label: DEFAULT_LABELS.active },
+      testing: { enabled: true, label: DEFAULT_LABELS.testing },
+      review: { enabled: true, label: DEFAULT_LABELS.review },
+      done: { enabled: true, label: DEFAULT_LABELS.done }
+    },
+    active_cols: buildActiveCols(testingOn, reviewOn),
+    workflow_stages: GATE_COLUMNS.slice(),
+    transitions: buildTransitions(testingOn, reviewOn),
+    plan_done_column: planDoneTarget(testingOn, reviewOn),
+    move_order: ['icebox', 'planned', 'active', 'testing', 'review', 'done'],
+    board_columns: [
+      { id: 'icebox', label: DEFAULT_LABELS.icebox },
+      { id: 'planned', label: DEFAULT_LABELS.planned },
+      { id: 'testing', label: DEFAULT_LABELS.testing },
+      { id: 'review', label: DEFAULT_LABELS.review },
+      { id: 'done', label: DEFAULT_LABELS.done }
+    ]
+  };
+}
+
+function shapePublicConfig(config) {
+  return {
+    columns: config.columns,
+    active_cols: config.active_cols.slice(),
+    workflow_stages: config.workflow_stages.slice(),
+    transitions: Object.fromEntries(
+      Object.entries(config.transitions).map(([k, v]) => [k, v.slice()])
+    ),
+    plan_done_column: config.plan_done_column,
+    move_order: config.move_order.slice(),
+    board_columns: config.board_columns.map((c) => ({ id: c.id, label: c.label })),
+    workflow: {
+      enabled: config.enabled,
+      command: config.command,
+      testing_agent: { ...config.testing_agent },
+      e2e_agent: { ...config.e2e_agent },
+      review_agent: { ...config.review_agent },
+      timeout_ms: config.timeout_ms
+    }
+  };
+}
+
+async function loadConfig() {
+  let raw;
+  try {
+    raw = await fs.readFile(CONFIG_PATH, 'utf-8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return defaultConfig();
+    }
+    throw error;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'backlog/kanbango.json is not valid JSON',
+      'Fix JSON syntax or remove the file to disable workflow',
+      { reason: error.message }
+    );
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'kanbango.json root must be an object',
+      'Use { "workflow": { ... }, "columns": { ... } }',
+      { field: 'root' }
+    );
+  }
+
+  assertColumnsShape(parsed.columns);
+
+  // workflow optional when only columns are configured
+  let w = parsed.workflow;
+  if (w === undefined) {
+    w = { enabled: false };
+  }
+  assertWorkflowShape(w);
+
+  const testingCol = parseGateColumn(parsed.columns && parsed.columns.testing, 'testing');
+  const reviewCol = parseGateColumn(parsed.columns && parsed.columns.review, 'review');
+  const testingOn = testingCol.enabled;
+  const reviewOn = reviewCol.enabled;
+
+  const testingAgent = parseAgentField(w.testing_agent, 'testing_agent', 'qa-tester');
+  const reviewAgent = parseAgentField(w.review_agent, 'review_agent', 'temida');
+  let e2eAgent = { enabled: true, name: 'qa-e2e-tester' };
+  if (w.e2e_agent !== undefined) {
+    if (typeof w.e2e_agent === 'string') {
+      e2eAgent = parseAgentField(w.e2e_agent, 'e2e_agent', 'qa-e2e-tester');
+    } else {
+      e2eAgent = parseAgentField(w.e2e_agent, 'e2e_agent', 'qa-e2e-tester');
+    }
+  }
+
+  const envRunner = String(process.env.KANBANGO_WORKFLOW_RUNNER || '').trim();
+  const activeCols = buildActiveCols(testingOn, reviewOn);
+  const workflowStages = GATE_COLUMNS.filter((col) => (col === 'testing' ? testingOn : reviewOn));
+  const moveOrder = ['icebox', 'planned', 'active']
+    .concat(testingOn ? ['testing'] : [])
+    .concat(reviewOn ? ['review'] : [])
+    .concat(['done']);
+
+  const boardColumns = [
+    { id: 'icebox', label: DEFAULT_LABELS.icebox },
+    { id: 'planned', label: DEFAULT_LABELS.planned }
+  ];
+  if (testingOn) boardColumns.push({ id: 'testing', label: testingCol.label });
+  if (reviewOn) boardColumns.push({ id: 'review', label: reviewCol.label });
+  boardColumns.push({ id: 'done', label: DEFAULT_LABELS.done });
+
+  return {
+    missing: false,
+    enabled: w.enabled,
+    command: envRunner || (isNonEmptyString(w.command) ? w.command.trim() : 'opencode'),
+    testing_agent: testingAgent,
+    e2e_agent: e2eAgent,
+    review_agent: reviewAgent,
+    timeout_ms: Number.isInteger(w.timeout_ms) && w.timeout_ms > 0 ? w.timeout_ms : 600000,
+    columns: {
+      icebox: { enabled: true, label: DEFAULT_LABELS.icebox },
+      planned: { enabled: true, label: DEFAULT_LABELS.planned },
+      active: { enabled: true, label: DEFAULT_LABELS.active },
+      testing: testingCol,
+      review: reviewCol,
+      done: { enabled: true, label: DEFAULT_LABELS.done }
+    },
+    active_cols: activeCols,
+    workflow_stages: workflowStages,
+    transitions: buildTransitions(testingOn, reviewOn),
+    plan_done_column: planDoneTarget(testingOn, reviewOn),
+    move_order: moveOrder,
+    board_columns: boardColumns
+  };
+}
+
+async function migrateDisabledGateCards(config) {
+  const migrated = [];
+  for (const col of GATE_COLUMNS) {
+    if (config.columns[col].enabled) continue;
+    const tasks = await kanban.listTasksInKnownColumn(col);
+    for (const task of tasks) {
+      await kanban.relocateTask(task.id, 'planned');
+      migrated.push({ id: task.id, from: col, to: 'planned' });
+    }
+  }
+  return migrated;
+}
+
+/**
+ * Load board config, apply layout to kanban, migrate cards out of disabled gates.
+ * Always re-reads backlog/kanbango.json (file is small) so enable/disable changes apply.
+ * Migration is idempotent: second call finds no cards in disabled columns.
+ */
+async function ensureBoardConfig({ force = false } = {}) {
+  const run = ensureTail.then(async () => {
+    const cwd = process.cwd();
+    // force kept for API/tests; always reload from disk so config edits are live.
+    void force;
+    const config = await loadConfig();
+    kanban.applyBoardLayout({
+      cols: config.active_cols,
+      transitions: config.transitions,
+      workflowStages: config.workflow_stages
+    });
+    await migrateDisabledGateCards(config);
+
+    cachedConfig = config;
+    cacheCwd = cwd;
+    return config;
+  });
+  ensureTail = run.then(() => undefined, () => undefined);
+  return run;
+}
+
+function clearConfigCache() {
+  cachedConfig = null;
+  cacheCwd = null;
+}
+
+function newRunId() {
+  return `run-${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
+}
+
+function agentForStage(config, stage) {
+  if (stage === 'review') return config.review_agent;
+  return config.testing_agent;
+}
+
+function buildPrompt(taskId, stage, agent) {
+  const lines = [
+    `Kanbango workflow stage=${stage} agent=${agent} task_id=${taskId}.`,
+    `Read the kanbango task ${taskId} (kanban_read show view=execution).`,
+    'Perform your agent role.'
+  ];
+  if (stage === 'testing') {
+    lines.push('Write/run tests only. End with a clear verdict line: PASS or FAIL or BLOCKED.');
+  }
+  if (stage === 'review') {
+    lines.push('After your verdict, the LAST line of the response MUST be exactly GATE: PASS or GATE: FAIL.');
+  }
+  return lines.join(' ');
+}
+
+function truncate(text, max = 2000) {
+  const s = String(text || '');
+  if (s.length <= max) return s;
+  return s.slice(s.length - max);
+}
+
+function parseTestingVerdict(stdout, stderr, exitCode) {
+  const text = `${stdout}\n${stderr}`;
+  if (/\bBLOCKED\b/i.test(text)) return 'blocked';
+  if (/\bPASS\b/i.test(text) && !/\bFAIL\b/i.test(text)) return 'pass';
+  if (/\bFAIL\b/i.test(text)) return 'fail';
+  if (exitCode !== 0) return 'fail';
+  return 'fail';
+}
+
+function parseReviewGate(stdout, stderr) {
+  const lines = `${stdout}\n${stderr}`
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const last = lines[lines.length - 1] || '';
+  if (last === 'GATE: PASS') return 'pass';
+  if (last === 'GATE: FAIL') return 'fail';
+  return null;
+}
+
+async function writeJob(job) {
+  await fs.mkdir(JOBS_DIR, { recursive: true });
+  const filePath = path.join(JOBS_DIR, `${job.run_id}.json`);
+  await fs.writeFile(filePath, JSON.stringify(job, null, 2) + '\n', 'utf-8');
+  return filePath;
+}
+
+async function updateJob(runId, patch) {
+  const filePath = path.join(JOBS_DIR, `${runId}.json`);
+  let job = {};
+  try {
+    job = JSON.parse(await fs.readFile(filePath, 'utf-8'));
+  } catch {
+    job = { run_id: runId };
+  }
+  const next = { ...job, ...patch };
+  await fs.writeFile(filePath, JSON.stringify(next, null, 2) + '\n', 'utf-8');
+  return next;
+}
+
+function spawnRunner(config, prompt, agent) {
+  return new Promise((resolve) => {
+    const args = ['run', prompt, '--agent', agent, '--format', 'json', '--dir', process.cwd()];
+    let child;
+    try {
+      child = spawn(config.command, args, {
+        cwd: process.cwd(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        env: process.env
+      });
+    } catch (error) {
+      resolve({
+        stdout: '',
+        stderr: error.message || String(error),
+        exitCode: 1,
+        timedOut: false,
+        pid: null,
+        argv: [config.command, ...args]
+      });
+      return;
+    }
+
+    const pid = child.pid;
+    if (pid) ownedPids.add(pid);
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      if (pid && ownedPids.has(pid)) {
+        try {
+          child.kill('SIGTERM');
+        } catch (killErr) {
+          // process may have already exited
+          if (killErr && killErr.code !== 'ESRCH') {
+            stderr += `\nkill failed: ${killErr.message || killErr}`;
+          }
+        }
+      }
+    }, config.timeout_ms);
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    const finish = (exitCode) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (pid) ownedPids.delete(pid);
+      resolve({
+        stdout,
+        stderr,
+        exitCode: exitCode == null ? 1 : exitCode,
+        timedOut,
+        pid,
+        argv: [config.command, ...args]
+      });
+    };
+
+    child.on('error', (error) => {
+      stderr += error.message || String(error);
+      finish(1);
+    });
+    child.on('close', (code) => finish(code));
+  });
+}
+
+function outcomeForResult(stage, result) {
+  if (result.timedOut) {
+    return {
+      verdict: 'blocked',
+      nextColumn: null,
+      workflowStatus: 'blocked',
+      summary: `timeout after runner; card stays in ${stage}`
+    };
+  }
+
+  if (stage === 'testing') {
+    const verdict = parseTestingVerdict(result.stdout, result.stderr, result.exitCode);
+    if (verdict === 'pass') {
+      const config = cachedConfig || defaultConfig();
+      const nextColumn = config.columns.review.enabled ? 'review' : 'done';
+      return {
+        verdict: 'pass',
+        nextColumn,
+        workflowStatus: 'pass',
+        summary: truncate(result.stdout || 'PASS', 500)
+      };
+    }
+    if (verdict === 'blocked') {
+      return {
+        verdict: 'blocked',
+        nextColumn: 'active',
+        workflowStatus: 'blocked',
+        summary: truncate(result.stdout || result.stderr || 'BLOCKED', 500)
+      };
+    }
+    return {
+      verdict: 'fail',
+      nextColumn: 'active',
+      workflowStatus: 'fail',
+      summary: truncate(result.stdout || result.stderr || 'FAIL', 500)
+    };
+  }
+
+  // review
+  const gate = parseReviewGate(result.stdout, result.stderr);
+  if (gate === 'pass') {
+    return {
+      verdict: 'pass',
+      nextColumn: 'done',
+      workflowStatus: 'pass',
+      summary: 'GATE: PASS'
+    };
+  }
+  if (gate === 'fail') {
+    return {
+      verdict: 'fail',
+      nextColumn: 'active',
+      workflowStatus: 'fail',
+      summary: 'GATE: FAIL'
+    };
+  }
+  return {
+    verdict: 'blocked',
+    nextColumn: null,
+    workflowStatus: 'blocked',
+    summary: truncate(result.stdout || result.stderr || 'missing GATE marker', 500)
+  };
+}
+
+async function finishRun(taskId, stage, agent, runId, result) {
+  const outcome = outcomeForResult(stage, result);
+  const finishedAt = new Date().toISOString();
+  const evidence = {
+    diff: '',
+    test_command: (result.argv || []).join(' '),
+    stdout: truncate(result.stdout),
+    stderr: truncate(result.stderr),
+    exit_code: result.exitCode,
+    created: finishedAt,
+    stage,
+    agent,
+    verdict: outcome.verdict,
+    summary: outcome.summary
+  };
+
+  const patch = {
+    appendEvidence: evidence,
+    workflow: {
+      stage,
+      status: outcome.workflowStatus,
+      agent,
+      run_id: runId,
+      finished_at: finishedAt
+    }
+  };
+  if (outcome.nextColumn) {
+    patch.column = outcome.nextColumn;
+  }
+
+  await kanban.updateTask(taskId, patch);
+  await updateJob(runId, {
+    status: outcome.workflowStatus,
+    finished_at: finishedAt,
+    verdict: outcome.verdict,
+    exit_code: result.exitCode,
+    timed_out: Boolean(result.timedOut)
+  });
+  runningLocal.delete(runId);
+}
+
+async function startRun(task, stage, config) {
+  const agentField = agentForStage(config, stage);
+  const agent = agentField.name;
+  const runId = newRunId();
+  const startedAt = new Date().toISOString();
+
+  runningLocal.add(runId);
+
+  await kanban.updateTask(task.id, {
+    workflow: {
+      stage,
+      status: 'running',
+      agent,
+      run_id: runId,
+      started_at: startedAt
+    }
+  });
+
+  await writeJob({
+    run_id: runId,
+    task_id: task.id,
+    stage,
+    agent,
+    started_at: startedAt,
+    status: 'running'
+  });
+
+  // Spawn outside any board lock (caller already released lock).
+  setImmediate(async () => {
+    const prompt = buildPrompt(task.id, stage, agent);
+    const result = await spawnRunner(config, prompt, agent);
+    if (result.pid) {
+      await updateJob(runId, { pid: result.pid });
+    }
+    try {
+      await finishRun(task.id, stage, agent, runId, result);
+    } catch (error) {
+      console.error('workflow finish failed:', error && error.message ? error.message : error);
+      runningLocal.delete(runId);
+    }
+  });
+
+  return { run_id: runId, agent, stage, status: 'running' };
+}
+
+/**
+ * Called after a successful column change into testing|review.
+ * Must not run inside withBoardLock.
+ */
+async function maybeEnqueueOnColumnEnter(task, previousColumn) {
+  if (!task || !kanban.WORKFLOW_STAGES.includes(task.column)) {
+    return { enqueued: false, reason: 'not_gate_column' };
+  }
+  if (previousColumn === task.column) {
+    return { enqueued: false, reason: 'same_column' };
+  }
+
+  const config = await ensureBoardConfig();
+  if (config.missing || !config.enabled) {
+    return { enqueued: false, reason: config.missing ? 'no_config' : 'disabled' };
+  }
+
+  if (!config.columns[task.column] || !config.columns[task.column].enabled) {
+    return { enqueued: false, reason: 'column_disabled' };
+  }
+
+  const agentField = agentForStage(config, task.column);
+  if (!agentField.enabled) {
+    return { enqueued: false, reason: 'agent_disabled' };
+  }
+
+  // Dedup: already running this stage
+  const wf = task.workflow;
+  if (wf && wf.status === 'running' && wf.stage === task.column) {
+    return { enqueued: false, reason: 'already_running' };
+  }
+  if (wf && wf.run_id && runningLocal.has(wf.run_id) && wf.stage === task.column) {
+    return { enqueued: false, reason: 'already_running_local' };
+  }
+
+  const fresh = await kanban.getTask(task.id);
+  if (fresh.workflow && fresh.workflow.status === 'running' && fresh.workflow.stage === task.column) {
+    return { enqueued: false, reason: 'already_running' };
+  }
+
+  const started = await startRun(fresh, task.column, config);
+  return { enqueued: true, ...started };
+}
+
+/** Test helper: wait until a run reaches a terminal workflow status. */
+async function waitForIdle(taskId, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  let sawRunning = false;
+  while (Date.now() < deadline) {
+    const task = await kanban.getTask(taskId);
+    const status = task.workflow && task.workflow.status;
+    if (status === 'running') sawRunning = true;
+    if (status === 'pass' || status === 'fail' || status === 'blocked') return task;
+    if (sawRunning && status !== 'running') return task;
+    await new Promise((r) => setTimeout(r, 40));
+  }
+  throw new Error(`waitForIdle timeout for task ${taskId}`);
+}
+
+async function planDoneColumn() {
+  const config = await ensureBoardConfig();
+  return config.plan_done_column;
+}
+
+module.exports = {
+  loadConfig,
+  ensureBoardConfig,
+  clearConfigCache,
+  shapePublicConfig,
+  maybeEnqueueOnColumnEnter,
+  parseTestingVerdict,
+  parseReviewGate,
+  waitForIdle,
+  planDoneColumn,
+  buildTransitions,
+  DEFAULT_LABELS,
+  JOBS_DIR,
+  CONFIG_PATH
+};