@mndrk/agx 1.4.30 → 1.4.33

package/lib/commands/daemonBoard.js

@@ -1,5 +1,5 @@
 const fs = require('fs');
-const { spawn } = require('child_process');
+const execa = require('execa');
 
 function getBoardUrl({ getBoardPort }) {
   const apiUrl = process.env.AGX_CLOUD_URL || process.env.AGX_BOARD_URL || 'http://localhost:41741';
@@ -23,17 +23,17 @@ function openInBrowser(url) {
   try {
     if (!url) return false;
     if (process.platform === 'darwin') {
-      const p = spawn('open', [url], { stdio: 'ignore', detached: true });
-      p.unref();
+      const p = execa('open', [url], { stdio: 'ignore', detached: true, reject: false });
+      p.unref?.();
       return true;
     }
     if (process.platform === 'win32') {
-      const p = spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true });
-      p.unref();
+      const p = execa('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true, reject: false });
+      p.unref?.();
       return true;
     }
-    const p = spawn('xdg-open', [url], { stdio: 'ignore', detached: true });
-    p.unref();
+    const p = execa('xdg-open', [url], { stdio: 'ignore', detached: true, reject: false });
+    p.unref?.();
     return true;
   } catch {
     return false;
@@ -158,7 +158,7 @@ async function maybeHandleDaemonBoardCommand({ cmd, args, ctx }) {
         process.exit(0);
       }
       console.log(`${c.dim}Tailing ${DAEMON_LOG_FILE}... (Ctrl+C to stop)${c.reset}\n`);
-      const tail = spawn('tail', ['-f', DAEMON_LOG_FILE], { stdio: 'inherit' });
+      const tail = execa('tail', ['-f', DAEMON_LOG_FILE], { stdio: 'inherit', reject: false });
       tail.on('close', () => process.exit(0));
       return true;
     } else {
@@ -259,7 +259,7 @@ async function maybeHandleDaemonBoardCommand({ cmd, args, ctx }) {
         process.exit(0);
       }
       console.log(`${c.dim}Tailing ${BOARD_LOG_FILE}... (Ctrl+C to stop)${c.reset}\n`);
-      const tail = spawn('tail', ['-f', BOARD_LOG_FILE], { stdio: 'inherit' });
+      const tail = execa('tail', ['-f', BOARD_LOG_FILE], { stdio: 'inherit', reject: false });
       tail.on('close', () => process.exit(0));
       return true;
     } else {

package/lib/executor.js

@@ -5,10 +5,11 @@
  * The executor spawns the appropriate CLI and captures output.
  */
 
-const { spawn, spawnSync } = require('child_process');
+const execa = require('execa');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { commandExists } = require('./proc/commandExists');
 
 const DEFAULT_STAGE_PROMPT = 'Execute this stage using the latest stage prompt from the cloud task context.';
 
@@ -45,15 +46,6 @@ const ENGINES = {
   },
 };
 
-function commandExists(cmd) {
-  try {
-    spawnSync('which', [cmd], { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function findStagePromptRecord(stagePrompts, stage) {
   if (!stagePrompts) return null;
   if (!stage) return null;
@@ -156,10 +148,11 @@ async function executeTask(options) {
       args.push(prompt);
     }
 
-    const proc = spawn(engineConfig.cmd, args, {
+    const proc = execa(engineConfig.cmd, args, {
       cwd: workDir,
       stdio: ['pipe', 'pipe', 'pipe'],
       env: { ...process.env, ...engineConfig.env, TERM: 'dumb' },
+      reject: false,
     });
 
     let output = '';

package/lib/orchestrator/httpClient.js

@@ -92,8 +92,12 @@ function createHttpClient(config) {
 
     async queryTask(taskId, query = 'getStatus', args = null) {
       const normalizedTaskId = normalizeTaskId(taskId);
-      // Note: new API uses /status instead of /query, supports both GET and POST
-      return apiRequest(config, 'POST', `${orchestratorBase}/tasks/${encodeURIComponent(normalizedTaskId)}/status`, {
+      const endpoint = `${orchestratorBase}/tasks/${encodeURIComponent(normalizedTaskId)}/status`;
+      // New API expects GET /status for simple status reads; keep POST for advanced queries.
+      if (query === 'getStatus' && !args) {
+        return apiRequest(config, 'GET', endpoint);
+      }
+      return apiRequest(config, 'POST', endpoint, {
         query,
         ...(args ? { args } : {})
       });

package/lib/proc/ProcessManager.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getDescendants } = require('./killProcessTree');
+
+const CONFIG_DIR = path.join(require('os').homedir(), '.agx');
+const HEARTBEAT_DIR = path.join(CONFIG_DIR, 'heartbeat');
+
+class ProcessManager {
+  /** @type {Map<number, {proc: import('child_process').ChildProcess, label: string, spawnedAt: number, timeout: number|null, timeoutTimer: NodeJS.Timeout|null, lastActivity: number}>} */
+  #processes = new Map();
+  #heartbeatInterval = null;
+  #cleanupInstalled = false;
+
+  constructor() {
+    this.#ensureHeartbeatDir();
+    this.#installCleanupHooks();
+    this.#startHeartbeatMonitor();
+  }
+
+  #ensureHeartbeatDir() {
+    try {
+      if (!fs.existsSync(HEARTBEAT_DIR)) {
+        fs.mkdirSync(HEARTBEAT_DIR, { recursive: true });
+      }
+    } catch { }
+  }
+
+  /**
+   * Register a spawned child process for tracking.
+   * @param {import('child_process').ChildProcess} proc
+   * @param {object} opts
+   * @param {string} [opts.label]
+   * @param {number} [opts.timeoutMs] - Hard timeout; kills process after this many ms.
+   * @param {boolean} [opts.heartbeat=true] - Enable activity-based heartbeat monitoring.
+   * @returns {import('child_process').ChildProcess}
+   */
+  register(proc, opts = {}) {
+    const pid = proc.pid;
+    if (!pid) return proc;
+
+    const timeoutMs = opts.timeoutMs ?? (process.env.AGX_TASK_TIMEOUT_MS ? Number(process.env.AGX_TASK_TIMEOUT_MS) : null);
+    const now = Date.now();
+
+    const entry = {
+      proc,
+      label: opts.label || `pid-${pid}`,
+      spawnedAt: now,
+      lastActivity: now,
+      timeout: timeoutMs,
+      timeoutTimer: null,
+      heartbeat: opts.heartbeat !== false,
+    };
+
+    // Hard timeout
+    if (timeoutMs && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      entry.timeoutTimer = setTimeout(() => {
+        if (this.#processes.has(pid)) {
+          this.kill(pid);
+        }
+      }, timeoutMs);
+      entry.timeoutTimer.unref();
+    }
+
+    this.#processes.set(pid, entry);
+
+    // Auto-remove on exit
+    proc.on('exit', () => {
+      this.#cleanup(pid);
+    });
+    proc.on('error', () => {
+      this.#cleanup(pid);
+    });
+
+    return proc;
+  }
+
+  /**
+   * Record activity for a tracked process (extends heartbeat).
+   */
+  recordActivity(pid) {
+    const entry = this.#processes.get(pid);
+    if (entry) {
+      entry.lastActivity = Date.now();
+    }
+  }
+
+  /**
+   * Kill a tracked process and its entire tree.
+   */
+  kill(pid, { signal = 'SIGTERM', graceMs = 2000 } = {}) {
+    const descendants = getDescendants(pid);
+    // Kill bottom-up (leaves first)
+    for (let i = descendants.length - 1; i >= 0; i--) {
+      try { process.kill(descendants[i], signal); } catch { }
+    }
+    try { process.kill(pid, signal); } catch { }
+
+    // Schedule SIGKILL escalation
+    if (signal !== 'SIGKILL') {
+      const timer = setTimeout(() => {
+        for (let i = descendants.length - 1; i >= 0; i--) {
+          try { process.kill(descendants[i], 'SIGKILL'); } catch { }
+        }
+        try { process.kill(pid, 'SIGKILL'); } catch { }
+      }, graceMs);
+      timer.unref();
+    }
+
+    this.#cleanup(pid);
+  }
+
+  /**
+   * Kill all tracked processes.
+   */
+  killAll() {
+    for (const pid of [...this.#processes.keys()]) {
+      this.kill(pid);
+    }
+  }
+
+  #cleanup(pid) {
+    const entry = this.#processes.get(pid);
+    if (!entry) return;
+    if (entry.timeoutTimer) clearTimeout(entry.timeoutTimer);
+    this.#processes.delete(pid);
+    // Clean heartbeat file
+    try { fs.unlinkSync(path.join(HEARTBEAT_DIR, String(pid))); } catch { }
+  }
+
+  #startHeartbeatMonitor() {
+    const STALE_THRESHOLD_MS = 120_000; // 2 minutes
+    const CHECK_INTERVAL_MS = 60_000;   // 1 minute
+
+    this.#heartbeatInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [pid, entry] of this.#processes) {
+        if (!entry.heartbeat) continue;
+        if (now - entry.lastActivity > STALE_THRESHOLD_MS) {
+          console.error(`[ProcessManager] Process ${pid} (${entry.label}) stale for >${Math.round((now - entry.lastActivity) / 1000)}s — killing`);
+          this.kill(pid);
+        }
+      }
+    }, CHECK_INTERVAL_MS);
+    this.#heartbeatInterval.unref();
+  }
+
+  #installCleanupHooks() {
+    if (this.#cleanupInstalled) return;
+    this.#cleanupInstalled = true;
+
+    const cleanup = () => {
+      if (this.#heartbeatInterval) {
+        clearInterval(this.#heartbeatInterval);
+        this.#heartbeatInterval = null;
+      }
+      this.killAll();
+    };
+
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => { cleanup(); process.exit(130); });
+    process.on('SIGTERM', () => { cleanup(); process.exit(143); });
+  }
+
+  /**
+   * Sweep orphaned heartbeat files whose PIDs no longer exist.
+   */
+  sweepOrphanedHeartbeats() {
+    try {
+      const files = fs.readdirSync(HEARTBEAT_DIR);
+      for (const file of files) {
+        const pid = parseInt(file, 10);
+        if (!Number.isFinite(pid)) continue;
+        try {
+          process.kill(pid, 0);
+        } catch {
+          // Process doesn't exist, clean up
+          try { fs.unlinkSync(path.join(HEARTBEAT_DIR, file)); } catch { }
+        }
+      }
+    } catch { }
+  }
+
+  get tracked() {
+    return this.#processes.size;
+  }
+}
+
+// Singleton
+let _instance;
+function getProcessManager() {
+  if (!_instance) _instance = new ProcessManager();
+  return _instance;
+}
+
+module.exports = { ProcessManager, getProcessManager };

package/lib/proc/commandExists.js

@@ -1,14 +1,14 @@
-const { execSync } = require('child_process');
+const execa = require('execa');
 
 // Check if a command exists on PATH
 function commandExists(cmd) {
   try {
-    execSync(`which ${cmd}`, { stdio: 'ignore' });
-    return true;
+    const tool = process.platform === 'win32' ? 'where' : 'which';
+    const res = execa.sync(tool, [cmd], { stdio: 'ignore', reject: false });
+    return res.exitCode === 0;
   } catch {
     return false;
   }
 }
 
 module.exports = { commandExists };
-

package/lib/proc/killProcessTree.js

@@ -0,0 +1,157 @@
+'use strict';
+
+const execa = require('execa');
+
+function isPidAlive(pid) {
+  if (!pid || typeof pid !== 'number' || !Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get all descendant PIDs of a process using `ps -o pid=,ppid= -ax`.
+ * Returns descendants in bottom-up order (leaves first).
+ */
+function getDescendants(rootPid) {
+  if (process.platform === 'win32') return [];
+  try {
+    const output = execa.sync('ps', ['-o', 'pid=,ppid=', '-ax'], {
+      encoding: 'utf8',
+      timeout: 3000,
+      reject: false,
+    }).stdout || '';
+    const children = new Map();
+    for (const line of output.trim().split('\n')) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length < 2) continue;
+      const pid = parseInt(parts[0], 10);
+      const ppid = parseInt(parts[1], 10);
+      if (!Number.isFinite(pid) || !Number.isFinite(ppid)) continue;
+      if (!children.has(ppid)) children.set(ppid, []);
+      children.get(ppid).push(pid);
+    }
+
+    // BFS to collect all descendants, then reverse for bottom-up order
+    const result = [];
+    const queue = [rootPid];
+    while (queue.length) {
+      const parent = queue.shift();
+      const kids = children.get(parent);
+      if (!kids) continue;
+      for (const kid of kids) {
+        if (kid !== rootPid) {
+          result.push(kid);
+          queue.push(kid);
+        }
+      }
+    }
+    return result.reverse(); // leaves first
+  } catch {
+    return [];
+  }
+}
+
+function tryKillPid(pid, signal) {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'ESRCH') return false;
+    return false;
+  }
+}
+
+function tryKillUnixProcessGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'ESRCH') return false;
+    return false;
+  }
+}
+
+function tryTaskkillWindows(pid, force) {
+  try {
+    const args = ['/pid', String(pid), '/T'];
+    if (force) args.push('/F');
+    const res = execa.sync('taskkill', args, { stdio: 'ignore', timeout: 3000, reject: false });
+    return res.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Kill the entire process tree rooted at `pid`.
+ * Uses ps-based descendant enumeration for reliable tree killing,
+ * with process group kill as fallback.
+ */
+function tryKillTree(pid, signal) {
+  if (!pid) return false;
+
+  if (process.platform === 'win32') {
+    return tryTaskkillWindows(pid, signal === 'SIGKILL' || signal === 'SIGTERM');
+  }
+
+  // Enumerate descendants and kill bottom-up (leaves first)
+  const descendants = getDescendants(pid);
+  let killed = false;
+
+  for (const desc of descendants) {
+    if (tryKillPid(desc, signal)) killed = true;
+  }
+
+  // Kill root — try group first, then individual
+  if (tryKillUnixProcessGroup(pid, signal)) {
+    killed = true;
+  } else if (tryKillPid(pid, signal)) {
+    killed = true;
+  }
+
+  return killed;
+}
+
+function scheduleTermination(pid, { graceMs = 800, forceMs = 2500 } = {}) {
+  if (!pid) return { cancel: () => { } };
+
+  if (isPidAlive(pid)) {
+    tryKillTree(pid, 'SIGTERM');
+  }
+
+  let killTimer = null;
+  let forceTimer = null;
+
+  killTimer = setTimeout(() => {
+    if (!isPidAlive(pid)) return;
+    tryKillTree(pid, 'SIGKILL');
+  }, Math.max(0, graceMs));
+
+  forceTimer = setTimeout(() => {
+    if (!isPidAlive(pid)) return;
+    tryKillTree(pid, 'SIGKILL');
+  }, Math.max(0, forceMs));
+
+  try { killTimer.unref(); } catch { }
+  try { forceTimer.unref(); } catch { }
+
+  return {
+    cancel: () => {
+      if (killTimer) clearTimeout(killTimer);
+      if (forceTimer) clearTimeout(forceTimer);
+      killTimer = null;
+      forceTimer = null;
+    }
+  };
+}
+
+module.exports = {
+  isPidAlive,
+  tryKillTree,
+  scheduleTermination,
+  getDescendants,
+};

package/lib/proc/spawnCloudTaskProcess.js

@@ -1,17 +1,44 @@
-const { spawn } = require('child_process');
+const execa = require('execa');
 const { commandExists } = require('./commandExists');
+const { getProcessManager } = require('./ProcessManager');
 
 function spawnCloudTaskProcess(childArgs, options = {}) {
-  const useScriptTty = commandExists('script');
+  // A PTY wrapper (`script`) tends to inject control characters and can explode log churn
+  // when stdout is streamed back into cloud task content. Only enable when explicitly requested.
+  const useScriptTty = options.tty === true && commandExists('script');
   const spawnCmd = useScriptTty ? 'script' : process.execPath;
   const spawnArgs = useScriptTty
     ? ['-q', '/dev/null', process.execPath, ...childArgs]
     : childArgs;
-  return spawn(spawnCmd, spawnArgs, {
+
+  // Put spawned tasks in their own process group so we can reliably terminate the whole tree
+  // (handles grandchild processes started by providers).
+  const detachedDefault = process.platform !== 'win32';
+  const env = {
+    ...process.env,
+    ...(options.env || {}),
+    // Child can self-terminate if the parent crashes, preventing orphaned processes.
+    AGX_PARENT_PID: String(process.pid),
+  };
+
+  const { timeoutMs, heartbeat, label, ...spawnOpts } = options;
+
+  const child = execa(spawnCmd, spawnArgs, {
     stdio: ['ignore', 'pipe', 'pipe'],
-    ...options
+    detached: spawnOpts.detached ?? detachedDefault,
+    env,
+    reject: false,
+    ...spawnOpts,
   });
+
+  // Register with ProcessManager for tracking, heartbeat, and cleanup
+  getProcessManager().register(child, {
+    label: label || childArgs.join(' ').slice(0, 80),
+    timeoutMs,
+    heartbeat: heartbeat !== false,
+  });
+
+  return child;
 }
 
 module.exports = { spawnCloudTaskProcess };
-

package/lib/prompts/cloudTask.js

@@ -1,3 +1,47 @@
+function stripMarkdownSection(markdown, heading) {
+  if (!markdown) return '';
+  const h = String(heading || '').trim();
+  if (!h) return String(markdown || '');
+
+  // Remove "## Heading ... until next ##" blocks to prevent prompt self-reinforcement
+  // when agent output is persisted into the task content.
+  const sectionRegex = new RegExp(
+    `^##\\s+${h.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\s*$[\\s\\S]*?(?=^##\\s+|\\Z)`,
+    'gim'
+  );
+  return String(markdown || '').replace(sectionRegex, '').trim();
+}
+
+function collapseBlankLines(text) {
+  return String(text || '').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+function sanitizeTaskContentForPrompt(content) {
+  // Critical: don't inline the continuously-updated sections (Output/Error) into the prompt.
+  // Otherwise every iteration includes prior agent output, which tends to explode the context.
+  let out = String(content || '').replace(/\r/g, '');
+
+  // First, drop known noisy sections if present.
+  out = stripMarkdownSection(out, 'Output');
+  out = stripMarkdownSection(out, 'Error');
+  out = stripMarkdownSection(out, 'Cloud Task Context');
+  out = stripMarkdownSection(out, 'Extracted State');
+  out = stripMarkdownSection(out, 'Instructions');
+
+  // Then, keep only the preamble (everything before the first "##" heading).
+  // Task bodies are expected to keep the user-facing request up top, with
+  // derived/agent/system sections below.
+  const firstSubheading = out.search(/^##\s+/m);
+  if (firstSubheading !== -1) {
+    out = out.slice(0, firstSubheading);
+  }
+
+  // Hard cap to avoid accidental large prompts from corrupted content.
+  const MAX_CHARS = 8000;
+  if (out.length > MAX_CHARS) out = out.slice(0, MAX_CHARS);
+  return collapseBlankLines(out);
+}
+
 function buildContinueCloudTaskPrompt({
   task,
   taskComments,
@@ -5,11 +49,15 @@ function buildContinueCloudTaskPrompt({
   stagePrompt,
   stageRequirement,
   extracted,
+  runContext,
 }) {
   const plan = extracted?.plan || '';
   const todo = extracted?.todo || '';
   const checkpoints = extracted?.checkpoints || '';
   const learnings = extracted?.learnings || '';
+  const runRoot = typeof runContext?.run_root === 'string' ? runContext.run_root.trim() : '';
+  const planDir = typeof runContext?.plan_dir === 'string' ? runContext.plan_dir.trim() : '';
+  const artifactsDir = typeof runContext?.artifacts_dir === 'string' ? runContext.artifacts_dir.trim() : '';
 
   let augmentedPrompt = task?.prompt || `## Cloud Task Context
 
@@ -21,14 +69,14 @@ Stage: ${task.stage || 'ideation'}
 Stage Objective: ${stagePrompt}
 Stage Completion Requirement: ${stageRequirement}
 
-User Request: 
-"""
-${task?.title}
-${task?.content}
----
-Task Thread:
-${(taskComments || []).map(c => `${c.author}: ${c.content}`).join('\n')}
-"""
+	User Request: 
+	"""
+	${task?.title}
+	${sanitizeTaskContentForPrompt(task?.content)}
+	---
+	Task Thread:
+	${(taskComments || []).map(c => `${c.author}: ${c.content}`).join('\n')}
+	"""
 
 ## Extracted State
 
@@ -50,6 +98,8 @@ Learnings: ${learnings || '(none)'}
 Continue working on this task. Use the cloud API to sync progress.
 Respect the Stage Completion Requirement before using [complete] or [done].
 
+${(runRoot || planDir || artifactsDir) ? `\nLocal run paths (scratch space):\n- Run root: ${runRoot || '(unset)'}\n- Plan dir: ${planDir || '(unset)'}\n- Artifacts dir: ${artifactsDir || '(unset)'}\n\nPrefer writing scratch planning docs under the run's Plan dir to avoid polluting the repo.\n` : ''}
+
 To update the task:
 - [done] - Mark task complete
 - [complete: message] - Complete current stage
@@ -74,20 +124,20 @@ function buildNewAutonomousCloudTaskPrompt({
 }) {
   return `## Cloud Task Context
 
-Task ID: ${task.id}
-Title: ${task.title || finalPrompt}
-Stage: ${task.stage}
-Stage Objective: ${stagePrompt}
-Stage Completion Requirement: ${stageRequirement}
-
-User Request: 
-"""
-${task?.title}
-${task?.content}
----
-Task Thread:
-${(taskComments || []).map(c => `${c.author}: ${c.content}`).join('\n')}
-"""
+	Task ID: ${task.id}
+	Title: ${task.title || finalPrompt}
+	Stage: ${task.stage}
+	Stage Objective: ${stagePrompt}
+	Stage Completion Requirement: ${stageRequirement}
+
+	User Request: 
+	"""
+	${task?.title}
+	${sanitizeTaskContentForPrompt(task?.content)}
+	---
+	Task Thread:
+	${(taskComments || []).map(c => `${c.author}: ${c.content}`).join('\n')}
+	"""
 
 ---
 
@@ -109,4 +159,3 @@ module.exports = {
   buildContinueCloudTaskPrompt,
   buildNewAutonomousCloudTaskPrompt,
 };
-

package/lib/storage/paths.js

@@ -362,6 +362,8 @@ function runPaths(projectSlug, taskSlug, stage, runId) {
         output: path.join(root, 'output.md'),
         decision: path.join(root, 'decision.json'),
         events: path.join(root, 'events.ndjson'),
+        // Scratch space for agents that want a stable "plan/" folder without polluting the repo.
+        plan: path.join(root, 'plan'),
         artifacts: path.join(root, 'artifacts'),
         logs: path.join(root, 'artifacts', 'logs.txt'),
         diff: path.join(root, 'artifacts', 'diff.patch'),
@@ -383,6 +385,7 @@ function runPathsLegacy(projectSlug, taskSlug, stage, runId) {
         output: path.join(root, 'output.md'),
         decision: path.join(root, 'decision.json'),
         events: path.join(root, 'events.ndjson'),
+        plan: path.join(root, 'plan'),
         artifacts: path.join(root, 'artifacts'),
         logs: path.join(root, 'artifacts', 'logs.txt'),
         diff: path.join(root, 'artifacts', 'diff.patch'),

package/lib/storage/runs.js

@@ -108,6 +108,7 @@ async function createRun({ projectSlug, taskSlug, stage, runId: explicitRunId, e
 
     // Create run directory
     await ensureDir(paths.root);
+    await ensureDir(paths.plan);
     await ensureDir(paths.artifacts);
 
     // If run already exists, return handle to existing run (idempotent)