@tagma/sdk 0.2.6 → 0.2.8

package/README.md

@@ -296,6 +296,7 @@ Options:
   - `task_status_change` — a task changed status; includes `state: TaskState` (complete snapshot at the time of change: `startedAt` is populated before the `running` event; `result` and `finishedAt` are populated before any terminal-status event)
   - `task_log` — a structured log line was written to `pipeline.log`. Mirrors every `Logger` call (info/warn/error/debug/section/quiet) and carries `{ taskId: string | null, level, timestamp, text }`. `taskId` is non-null for lines tagged with a `[task:<id>]` prefix (or passed explicitly to `section`/`quiet`) and `null` for pipeline-wide messages such as the configuration dump and DAG topology. Use this to stream the full run process into UIs without tailing the log file.
   - `pipeline_end` — pipeline finished; includes `success: boolean`
+- `runId` -- caller-supplied run ID. When provided the engine uses this instead of generating its own, keeping the caller and the SDK log directories aligned on the same ID
 - `maxLogRuns` -- number of per-run log directories to keep under `<workDir>/.tagma/logs/` (default: 20)
 
 ### `PipelineRunner`
@@ -435,7 +436,7 @@ const yaml = serializePipeline(config);
 | `upsertTask(config, trackId, task)` | Insert or replace a task |
 | `removeTask(config, trackId, taskId, cleanRefs?)` | Remove a task; pass `cleanRefs: true` to also strip dangling `depends_on` / `continue_from` references. Only refs that resolve to the deleted task are removed — same-named tasks in other tracks are unaffected |
 | `moveTask(config, trackId, taskId, toIndex)` | Reorder a task within its track |
-| `transferTask(config, fromTrackId, taskId, toTrackId)` | Move a task across tracks |
+| `transferTask(config, fromTrackId, taskId, toTrackId, qualifyRefs?)` | Move a task across tracks. When `qualifyRefs` is `true` (default), bare `depends_on` / `continue_from` references to the moved task are converted to fully-qualified form (`toTrackId.taskId`) so same-track resolution stays correct |
 
 ### `parseYaml(content: string): RawPipelineConfig`
 
@@ -469,7 +470,7 @@ Use `validateRaw` for editing raw configs in a UI; use `validateConfig` after `r
 
 Validates a raw pipeline config without resolving inheritance or executing anything. Returns a flat list of `{ path, message }` objects — empty array means valid.
 
-Checks: required fields, `prompt`/`command` exclusivity, `depends_on`/`continue_from` reference integrity (including ambiguous bare refs that exist in multiple tracks — use `trackId.taskId` to disambiguate), circular dependency detection.
+Checks: required fields, `prompt`/`command` exclusivity, duplicate task IDs within a track, `depends_on`/`continue_from` reference integrity (including ambiguous bare refs that exist in multiple tracks — use `trackId.taskId` to disambiguate), circular dependency detection.
 
 Does **not** check plugin registration (plugins may not be loaded at edit time).
 
@@ -508,6 +509,7 @@ logger.section('Title');             // file only — visual separator
 logger.quiet(bulkText);              // file only — bulk payload
 logger.path;                         // log file path
 logger.dir;                          // run artifact directory
+logger.close();                      // close the persistent file handle (called automatically by runPipeline at run completion)
 ```
 
 Pass an optional third argument to stream every appended line out as a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/completions/output-check.ts

@@ -34,6 +34,17 @@ export const OutputCheckCompletion: CompletionPlugin = {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
 
+    // Wire pipeline abort signal into the check process so external abort
+    // terminates the child instead of leaving it running undetected.
+    const onAbort = () => controller.abort();
+    if (ctx.signal) {
+      if (ctx.signal.aborted) {
+        controller.abort();
+      } else {
+        ctx.signal.addEventListener('abort', onAbort, { once: true });
+      }
+    }
+
     const proc = Bun.spawn(shellArgs(checkCmd) as string[], {
       cwd: ctx.workDir,
       stdin: 'pipe',
@@ -69,6 +80,7 @@ export const OutputCheckCompletion: CompletionPlugin = {
       return exitCode === 0;
     } finally {
       clearTimeout(timer);
+      if (ctx.signal) ctx.signal.removeEventListener('abort', onAbort);
     }
   },
 };

package/src/config-ops.ts

@@ -226,13 +226,21 @@ export function moveTask(
 /**
  * Move a task from one track to another (appends to the target track).
  * No-op if either trackId or taskId is not found.
+ *
+ * When `qualifyRefs` is true (the default), bare references (`depends_on`,
+ * `continue_from`) pointing to the moved task are converted to fully-qualified
+ * refs (`toTrackId.taskId`) so that same-track resolution doesn't silently
+ * break after the task changes tracks.
  */
 export function transferTask(
   config: RawPipelineConfig,
   fromTrackId: string,
   taskId: string,
   toTrackId: string,
+  qualifyRefs = true,
 ): RawPipelineConfig {
+  if (fromTrackId === toTrackId) return config;
+
   let task: RawTaskConfig | undefined;
   const afterRemove = {
     ...config,
@@ -245,5 +253,70 @@ export function transferTask(
     }),
   };
   if (!task) return config;
-  return upsertTask(afterRemove, toTrackId, task);
+  const afterInsert = upsertTask(afterRemove, toTrackId, task);
+
+  if (!qualifyRefs) return afterInsert;
+
+  // Qualify bare references to the moved task. After the move, bare ref
+  // "taskId" from the old track no longer resolves via same-track priority.
+  // Convert it to the qualified form "toTrackId.taskId" so the dependency
+  // graph stays correct.
+  const qualId = `${toTrackId}.${taskId}`;
+  const oldQualId = `${fromTrackId}.${taskId}`;
+
+  // Does any track (other than the destination) still have a task with this bare id?
+  const bareIdSurvivesElsewhere = afterInsert.tracks.some(t =>
+    t.id !== toTrackId && t.tasks.some(tk => tk.id === taskId),
+  );
+
+  return {
+    ...afterInsert,
+    tracks: afterInsert.tracks.map(t => {
+      const localHasId = t.tasks.some(tk => tk.id === taskId);
+
+      const qualifyRef = (ref: string): string => {
+        // Already-qualified ref to old location → rewrite to new location
+        if (ref === oldQualId) return qualId;
+        // Bare ref: only needs qualifying if it would have resolved to the
+        // moved task before the transfer
+        if (ref === taskId) {
+          if (t.id === fromTrackId) {
+            // Was same-track in the old track — now the task is gone.
+            // If no other local task shadows it, qualify to new location.
+            if (!localHasId) return qualId;
+          }
+          // From a different track: bare ref resolved globally before.
+          // If the bare id is now ambiguous or gone from this track's
+          // perspective, qualify it.
+          if (!localHasId && !bareIdSurvivesElsewhere) return qualId;
+        }
+        return ref;
+      };
+
+      return {
+        ...t,
+        tasks: t.tasks.map(tk => qualifyTaskRefs(tk, qualifyRef)),
+      };
+    }),
+  };
+}
+
+/** Rewrite `depends_on` and `continue_from` refs using a mapping function. */
+function qualifyTaskRefs(
+  task: RawTaskConfig,
+  rewrite: (ref: string) => string,
+): RawTaskConfig {
+  const newDeps = task.depends_on?.map(rewrite);
+  const newContinue = task.continue_from !== undefined ? rewrite(task.continue_from) : undefined;
+
+  const depsChanged = newDeps !== undefined && newDeps.some((d, i) => d !== task.depends_on![i]);
+  const continueChanged = newContinue !== undefined && newContinue !== task.continue_from;
+
+  if (!depsChanged && !continueChanged) return task;
+
+  return {
+    ...task,
+    ...(newDeps !== undefined ? { depends_on: newDeps } : {}),
+    ...(newContinue !== undefined ? { continue_from: newContinue } : {}),
+  };
 }

package/src/dag.ts

@@ -118,8 +118,10 @@ export function buildDag(config: PipelineConfig): Dag {
   }
 
   const sorted: string[] = [];
-  while (queue.length > 0) {
-    const current = queue.shift()!;
+  // Use an index pointer instead of shift() to avoid O(n) per dequeue.
+  let qi = 0;
+  while (qi < queue.length) {
+    const current = queue[qi++]!;
     sorted.push(current);
     for (const child of adjacency.get(current)!) {
       const newDegree = inDegree.get(child)! - 1;
@@ -129,8 +131,13 @@ export function buildDag(config: PipelineConfig): Dag {
   }
 
   if (sorted.length !== nodes.size) {
-    const remaining = [...nodes.keys()].filter(id => !sorted.includes(id));
-    throw new Error(`Circular dependency detected involving tasks: ${remaining.join(', ')}`);
+    // Only report nodes that are actually part of cycles (in-degree > 0
+    // after Kahn's algorithm), not their downstream dependents.
+    const sortedSet = new Set(sorted);
+    const cycleMembers = [...nodes.keys()].filter(id =>
+      !sortedSet.has(id) && (inDegree.get(id) ?? 0) > 0
+    );
+    throw new Error(`Circular dependency detected involving tasks: ${cycleMembers.join(', ')}`);
   }
 
   return { nodes, sorted };

package/src/engine.ts

@@ -88,13 +88,23 @@ function preflight(config: PipelineConfig, dag: Dag): void {
 }
 
 function resolveRefInDag(dag: Dag, ref: string, fromTrackId: string): string | null {
+  // Already fully qualified
   if (dag.nodes.has(ref)) return ref;
+  // Same-track match (preferred)
   const sameTrack = `${fromTrackId}.${ref}`;
   if (dag.nodes.has(sameTrack)) return sameTrack;
+  // Cross-track bare name lookup — must be unambiguous (aligned with buildDag's resolveRef)
+  let match: string | null = null;
   for (const [id] of dag.nodes) {
-    if (id.endsWith(`.${ref}`)) return id;
+    if (id.endsWith(`.${ref}`)) {
+      if (match !== null) {
+        // Ambiguous: multiple tasks share the bare name across tracks
+        return null;
+      }
+      match = id;
+    }
   }
-  return null;
+  return match;
 }
 
 // ═══ Engine ═══
@@ -132,6 +142,12 @@ export interface RunPipelineOptions {
    * Oldest directories are deleted after each run. Defaults to 20. Set to 0 to disable cleanup.
    */
   readonly maxLogRuns?: number;
+  /**
+   * Caller-supplied run ID. When provided the engine uses this instead of
+   * generating its own via `generateRunId()`, keeping the editor and SDK
+   * log directories aligned on the same ID.
+   */
+  readonly runId?: string;
   /**
    * External AbortSignal — aborting it cancels the pipeline immediately.
    * Equivalent to the pipeline timeout firing, but caller-controlled.
@@ -163,7 +179,7 @@ export async function runPipeline(
   }
 
   const dag = buildDag(config);
-  const runId = generateRunId();
+  const runId = options.runId ?? generateRunId();
   preflight(config, dag);
 
   const startedAt = nowISO();
@@ -181,6 +197,9 @@ export async function runPipeline(
       text: record.text,
     });
   });
+
+  try {
+
   log.info('[pipeline]', `start "${config.name}" run_id=${runId}`);
 
   // File-only: dump the resolved pipeline shape + DAG topology for post-mortem.
@@ -214,8 +233,6 @@ export async function runPipeline(
     });
   }
 
-  try {
-
   // Pipeline start hook (gate)
   const startHook = await executeHook(
     config.hooks, 'pipeline_start', buildPipelineStartContext(pipelineInfo), workDir,
@@ -268,15 +285,15 @@ export async function runPipeline(
   });
 
   // Wire external cancel signal into the internal abort controller.
+  const externalAbortHandler = () => {
+    pipelineAborted = true;
+    abortController.abort();
+  };
   if (options.signal) {
     if (options.signal.aborted) {
-      pipelineAborted = true;
-      abortController.abort();
+      externalAbortHandler();
     } else {
-      options.signal.addEventListener('abort', () => {
-        pipelineAborted = true;
-        abortController.abort();
-      }, { once: true });
+      options.signal.addEventListener('abort', externalAbortHandler, { once: true });
     }
   }
 
@@ -361,7 +378,7 @@ export async function runPipeline(
 
   async function fireHook(taskId: string, event: 'task_success' | 'task_failure'): Promise<void> {
     await executeHook(config.hooks, event,
-      buildTaskContext(event, pipelineInfo, trackInfoOf(taskId), buildTaskInfoObj(taskId)), workDir);
+      buildTaskContext(event, pipelineInfo, trackInfoOf(taskId), buildTaskInfoObj(taskId)), workDir, abortController.signal);
   }
 
   // ── Process a single task ──
@@ -423,7 +440,7 @@ export async function runPipeline(
 
     // 3. task_start hook (gate)
     const hookResult = await executeHook(config.hooks, 'task_start',
-      buildTaskContext('task_start', pipelineInfo, trackInfoOf(taskId), buildTaskInfoObj(taskId)), workDir);
+      buildTaskContext('task_start', pipelineInfo, trackInfoOf(taskId), buildTaskInfoObj(taskId)), workDir, abortController.signal);
     if (hookResult.exitCode !== 0 || config.hooks?.task_start) {
       log.debug(`[task:${taskId}]`,
         `task_start hook exit=${hookResult.exitCode} allowed=${hookResult.allowed}`);
@@ -515,7 +532,7 @@ export async function runPipeline(
         terminalStatus = 'failed';
       } else if (task.completion) {
         const plugin = getHandler<CompletionPlugin>('completions', task.completion.type);
-        const completionCtx = { workDir: task.cwd ?? workDir };
+        const completionCtx = { workDir: task.cwd ?? workDir, signal: abortController.signal };
         const passed = await plugin.check(task.completion as Record<string, unknown>, result, completionCtx);
         terminalStatus = passed ? 'success' : 'failed';
       } else {
@@ -664,6 +681,11 @@ export async function runPipeline(
     }
   } finally {
     if (pipelineTimer) clearTimeout(pipelineTimer);
+    // Clean up the external abort signal listener to prevent dead references
+    // accumulating on long-lived shared AbortControllers.
+    if (options.signal) {
+      options.signal.removeEventListener('abort', externalAbortHandler);
+    }
     // Safety net: drain any approvals still pending at shutdown (e.g. crash path).
     if (approvalGateway.pending().length > 0) {
       approvalGateway.abortAll('pipeline finished');
@@ -714,15 +736,17 @@ export async function runPipeline(
     log.quiet(`  ${state.status.padEnd(8)} ${id}  (exit=${exit}, ${dur})`);
   }
 
-  console.log(`\n[Pipeline "${config.name}"] completed`);
-  console.log(`  Total: ${summary.total} | Success: ${summary.success} | Failed: ${summary.failed} | Skipped: ${summary.skipped} | Timeout: ${summary.timeout} | Blocked: ${summary.blocked}`);
-  console.log(`  Duration: ${(durationMs / 1000).toFixed(1)}s`);
-  console.log(`  Log: ${log.path}`);
+  log.info('[pipeline]', `completed "${config.name}"`);
+  log.info('[pipeline]', `Total: ${summary.total} | Success: ${summary.success} | Failed: ${summary.failed} | Skipped: ${summary.skipped} | Timeout: ${summary.timeout} | Blocked: ${summary.blocked}`);
+  log.info('[pipeline]', `Duration: ${(durationMs / 1000).toFixed(1)}s`);
+  log.info('[pipeline]', `Log: ${log.path}`);
 
   emit({ type: 'pipeline_end', runId, success: allSuccess });
   return { success: allSuccess, runId, logPath: log.path, summary, states: freezeStates(states) };
 
   } finally {
+    // Close the persistent log file handle before pruning.
+    log.close();
     // Prune old per-run log directories on every exit path (normal, blocked, or thrown).
     // Exclude the current runId so a concurrent run cannot delete its own live directory.
     if (maxLogRuns > 0) {

package/src/hooks.ts

@@ -18,42 +18,71 @@ function normalizeCommands(cmd: HookCommand | undefined): readonly string[] {
   return cmd;
 }
 
-async function runSingleHook(command: string, context: unknown, cwd?: string): Promise<number> {
+const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
+
+async function runSingleHook(
+  command: string,
+  context: unknown,
+  cwd?: string,
+  signal?: AbortSignal,
+  timeoutMs: number = DEFAULT_HOOK_TIMEOUT_MS,
+): Promise<number> {
   const jsonInput = JSON.stringify(context, null, 2);
 
-  const proc = Bun.spawn(shellArgs(command) as string[], {
-    stdin: 'pipe',
-    stdout: 'pipe',
-    stderr: 'pipe',
-    ...(cwd ? { cwd } : {}),
-  });
-
-  if (proc.stdin) {
-    try {
-      proc.stdin.write(jsonInput);
-      proc.stdin.end();
-    } catch {
-      // Process may exit before reading stdin (e.g. `exit 1`), ignore EPIPE
+  const controller = new AbortController();
+  const timer = timeoutMs > 0
+    ? setTimeout(() => controller.abort(), timeoutMs)
+    : null;
+
+  // Wire pipeline abort signal into hook process
+  const onAbort = () => controller.abort();
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort();
+    } else {
+      signal.addEventListener('abort', onAbort, { once: true });
     }
   }
 
-  // Consume stdout and stderr concurrently with waiting for exit.
-  // Sequential reads after proc.exited risk a pipe-buffer deadlock when
-  // hook output exceeds the ~64 KB kernel buffer.
-  const [exitCode, stdout, stderr] = await Promise.all([
-    proc.exited,
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-
-  if (stdout.trim()) {
-    console.log(`[hook: ${command}] stdout: ${stdout.trim()}`);
-  }
-  if (stderr.trim()) {
-    console.error(`[hook: ${command}] stderr: ${stderr.trim()}`);
-  }
+  try {
+    const proc = Bun.spawn(shellArgs(command) as string[], {
+      stdin: 'pipe',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      signal: controller.signal,
+      ...(cwd ? { cwd } : {}),
+    });
+
+    if (proc.stdin) {
+      try {
+        proc.stdin.write(jsonInput);
+        proc.stdin.end();
+      } catch {
+        // Process may exit before reading stdin (e.g. `exit 1`), ignore EPIPE
+      }
+    }
 
-  return exitCode;
+    // Consume stdout and stderr concurrently with waiting for exit.
+    // Sequential reads after proc.exited risk a pipe-buffer deadlock when
+    // hook output exceeds the ~64 KB kernel buffer.
+    const [exitCode, stdout, stderr] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+
+    if (stdout.trim()) {
+      console.log(`[hook: ${command}] stdout: ${stdout.trim()}`);
+    }
+    if (stderr.trim()) {
+      console.error(`[hook: ${command}] stderr: ${stderr.trim()}`);
+    }
+
+    return exitCode;
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (signal) signal.removeEventListener('abort', onAbort);
+  }
 }
 
 export async function executeHook(
@@ -61,6 +90,7 @@ export async function executeHook(
   event: HookEvent,
   context: unknown,
   workDir?: string,
+  signal?: AbortSignal,
 ): Promise<HookResult> {
   if (!hooks) return { allowed: true, exitCode: 0 };
 
@@ -70,7 +100,7 @@ export async function executeHook(
   const isGate = GATE_HOOKS.has(event);
 
   for (const cmd of commands) {
-    const exitCode = await runSingleHook(cmd, context, workDir);
+    const exitCode = await runSingleHook(cmd, context, workDir, signal);
 
     if (isGate && exitCode === 1) {
       // Only exit code 1 has gate semantics (block execution)

package/src/logger.ts

@@ -1,5 +1,5 @@
 import { resolve, dirname } from 'node:path';
-import { mkdirSync, appendFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, openSync, writeSync, closeSync } from 'node:fs';
 
 /**
  * Structured record emitted for every log line. Consumers (e.g. the editor
@@ -43,18 +43,21 @@ export class Logger {
   private readonly filePath: string;
   private readonly runDir: string;
   private readonly onLine: LogListener | null;
+  /** Persistent file descriptor for append writes (avoids open/close per line). */
+  private fd: number | null;
 
   constructor(workDir: string, runId: string, onLine?: LogListener) {
     this.runDir = resolve(workDir, '.tagma', 'logs', runId);
     this.filePath = resolve(this.runDir, 'pipeline.log');
     this.onLine = onLine ?? null;
     mkdirSync(dirname(this.filePath), { recursive: true });
-    writeFileSync(
-      this.filePath,
+    const header =
       `# Pipeline run ${runId} @ ${new Date().toISOString()}\n` +
       `# Host: ${process.platform} ${process.arch}  Bun: ${process.versions.bun ?? 'n/a'}\n` +
-      `# Work dir: ${workDir}\n\n`,
-    );
+      `# Work dir: ${workDir}\n\n`;
+    writeFileSync(this.filePath, header);
+    // Open once for all subsequent appends (O_APPEND is implied by 'a' flag)
+    this.fd = openSync(this.filePath, 'a');
   }
 
   info(prefix: string, message: string): void {
@@ -105,13 +108,23 @@ export class Logger {
   }
 
   private append(line: string): void {
+    if (this.fd === null) return;
     try {
-      appendFileSync(this.filePath, line.endsWith('\n') ? line : line + '\n');
+      const data = line.endsWith('\n') ? line : line + '\n';
+      writeSync(this.fd, data);
     } catch {
       // Swallow log write failures; engine correctness shouldn't depend on logging.
     }
   }
 
+  /** Close the persistent file handle. Called by the engine at run completion. */
+  close(): void {
+    if (this.fd !== null) {
+      try { closeSync(this.fd); } catch { /* already closed */ }
+      this.fd = null;
+    }
+  }
+
   private emit(level: LogLevel, ts: string, text: string, taskId: string | null): void {
     if (!this.onLine) return;
     try {

package/src/pipeline-runner.ts

@@ -61,6 +61,15 @@ export class PipelineRunner {
   start(): Promise<EngineResult> {
     if (this._result) return this._result;
 
+    // Guard: if abort() was called before start(), the signal is already
+    // aborted. Create a fresh controller so the pipeline doesn't terminate
+    // immediately. If users truly want pre-abort semantics, they call
+    // abort() after start().
+    if (this._abortController.signal.aborted) {
+      this._abortController = new AbortController();
+      this._status = 'idle';
+    }
+
     this._status = 'running';
     this._result = runPipeline(this.config, this.workDir, {
       ...this.opts,

package/src/registry.ts

@@ -37,8 +37,20 @@ export function hasHandler(category: PluginCategory, type: string): boolean {
   return registries[category].has(type);
 }
 
+// Plugin name must be a scoped npm package or a tagma-prefixed package.
+// Reject absolute/relative paths and suspicious patterns to prevent
+// arbitrary code execution via crafted YAML configs.
+const PLUGIN_NAME_RE = /^(@[a-z0-9-]+\/[a-z0-9._-]+|tagma-plugin-[a-z0-9._-]+)$/;
+
 export async function loadPlugins(pluginNames: readonly string[]): Promise<void> {
   for (const name of pluginNames) {
+    if (!PLUGIN_NAME_RE.test(name)) {
+      throw new Error(
+        `Plugin "${name}" rejected: plugin names must be scoped npm packages ` +
+        `(e.g. @tagma/trigger-xyz) or tagma-plugin-* packages. ` +
+        `Relative/absolute paths are not allowed.`
+      );
+    }
     const mod = await import(name);
     if (!mod.pluginCategory || !mod.pluginType || !mod.default) {
       throw new Error(

package/src/runner.ts

@@ -15,10 +15,17 @@ const SIGKILL_DELAY_MS = 3_000;
 function killProcessTree(pid: number): void {
   if (process.platform !== 'win32') return;
   try {
-    Bun.spawnSync(['taskkill', '/F', '/T', '/PID', String(pid)], {
-      stdout: 'ignore',
-      stderr: 'ignore',
+    const result = Bun.spawnSync(['taskkill', '/F', '/T', '/PID', String(pid)], {
+      stdout: 'pipe',
+      stderr: 'pipe',
     });
+    if (result.exitCode !== 0) {
+      const stderr = new TextDecoder().decode(result.stderr);
+      // Exit code 128 = process not found (already exited) — not worth warning about
+      if (result.exitCode !== 128) {
+        console.error(`[killProcessTree] taskkill exited ${result.exitCode} for PID ${pid}: ${stderr.trim()}`);
+      }
+    }
   } catch {
     /* best-effort — process may have already exited */
   }
@@ -42,8 +49,18 @@ export interface RunOptions {
  * Returns the original name if resolution fails; Bun will raise the same
  * ENOENT it would have otherwise.
  */
+const RESOLVED_EXE_CACHE_MAX = 128;
 const resolvedExeCache = new Map<string, string | null>();
 
+/** Evict the oldest entry when the cache is at capacity. */
+function evictIfFull(): void {
+  if (resolvedExeCache.size >= RESOLVED_EXE_CACHE_MAX) {
+    // Map iteration order is insertion order — delete the first (oldest) key.
+    const oldest = resolvedExeCache.keys().next().value;
+    if (oldest !== undefined) resolvedExeCache.delete(oldest);
+  }
+}
+
 function resolveWindowsExe(
   args: readonly string[],
   envPath: string,
@@ -73,11 +90,13 @@ function resolveWindowsExe(
     for (const ext of exts) {
       const candidate = join(dir, cmd + ext);
       if (existsSync(candidate)) {
+        evictIfFull();
         resolvedExeCache.set(cacheKey, candidate);
         return [candidate, ...args.slice(1)];
       }
     }
   }
+  evictIfFull();
   resolvedExeCache.set(cacheKey, null);
   return args;
 }
@@ -140,6 +159,7 @@ export async function runSpawn(
 
   // ── 3. Timeout & abort handling ────────────────────────────────────────
   let killedByUs = false;
+  let timedOut = false;
   let timer: ReturnType<typeof setTimeout> | null = null;
   let forceTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -165,7 +185,10 @@ export async function runSpawn(
   };
 
   if (timeoutMs && timeoutMs > 0) {
-    timer = setTimeout(killGracefully, timeoutMs);
+    timer = setTimeout(() => {
+      timedOut = true;
+      killGracefully();
+    }, timeoutMs);
   }
 
   const onAbort = () => killGracefully();
@@ -197,8 +220,10 @@ export async function runSpawn(
   // We initiated the kill (timeout or abort) — always treat as non-success
   // regardless of exit code. A process that catches SIGTERM and exits 0 still
   // hit the timeout; letting it pass as success would unblock downstream tasks
-  // incorrectly.
-  if (killedByUs) {
+  // incorrectly. The `timedOut` flag guards against the narrow race where the
+  // process exits naturally at the exact moment the timeout fires — even if
+  // killedByUs wasn't set in time, the timeout intention still applies.
+  if (killedByUs || timedOut) {
     return {
       exitCode: -1,
       stdout,

package/src/schema.ts

@@ -101,7 +101,9 @@ async function loadTemplate(ref: string): Promise<TemplateConfig> {
     // Expect the module to export a template.yaml content or parsed object
     if (mod.template) return mod.template as TemplateConfig;
 
-    // Try loading template.yaml from the package
+    // Try loading template.yaml from the package.
+    // NOTE: require.resolve is a CommonJS API. Bun supports it natively, but
+    // this would need import.meta.resolve() for pure ESM runtimes (e.g. Deno).
     const pkgPath = require.resolve(`${moduleName}/template.yaml`);
     const content = await Bun.file(pkgPath).text();
     const doc = yaml.load(content) as { template: TemplateConfig };
@@ -196,10 +198,15 @@ function expandTemplateTask(
       newTask.continue_from = `${instanceId}.${task.continue_from}`;
     }
 
-    // Rewrite output path to instance namespace
+    // Rewrite output path to instance namespace so parallel template
+    // instances don't collide on the same file. Handles any relative path
+    // (e.g. ./tmp/foo, ./output/bar, ./build/result.json) by injecting
+    // the instanceId as the first directory component after `./`.
     if (task.output) {
       const original = interpolate(task.output);
-      newTask.output = original.replace('./tmp/', `./tmp/${instanceId}/`);
+      newTask.output = original.startsWith('./')
+        ? `./${instanceId}/${original.slice(2)}`
+        : `${instanceId}/${original}`;
     }
 
     return newTask as unknown as RawTaskConfig;

package/src/triggers/file.ts

@@ -1,5 +1,6 @@
 import { watch } from 'chokidar';
 import { resolve, dirname } from 'path';
+import { mkdir } from 'fs/promises';
 import type { TriggerPlugin, TriggerContext } from '../types';
 import { parseDuration, validatePath } from '../utils';
 
@@ -35,7 +36,7 @@ export const FileTrigger: TriggerPlugin = {
     const safePath = validatePath(filePath, ctx.workDir);
     const timeoutMs = config.timeout != null ? parseDuration(String(config.timeout)) : 0;
 
-    return new Promise((resolve_p, reject) => {
+    return new Promise(async (resolve_p, reject) => {
       if (ctx.signal.aborted) {
         reject(new Error('Pipeline aborted'));
         return;
@@ -44,7 +45,13 @@ export const FileTrigger: TriggerPlugin = {
       let settled = false;
       let timer: ReturnType<typeof setTimeout> | null = null;
 
+      // Ensure the parent directory exists so the watcher doesn't fail
+      // with ENOENT for nested paths like `build/output/result.json`.
       const dir = dirname(safePath);
+      try {
+        await mkdir(dir, { recursive: true });
+      } catch { /* best effort — dir may already exist */ }
+
       const watcher = watch(dir, {
         ignoreInitial: true,
         depth: 0,

package/src/triggers/manual.ts

@@ -41,19 +41,26 @@ export const ManualTrigger: TriggerPlugin = {
     // so instead we race against an abort promise and let engine status logic
     // fall back to pipelineAborted → skipped. abortAll() on gateway still runs
     // from engine shutdown path to clean up any truly-pending entries.
+    const onAbort = () => {};
     const abortPromise = new Promise<never>((_, reject) => {
       if (ctx.signal.aborted) {
         reject(new Error('Pipeline aborted'));
         return;
       }
-      ctx.signal.addEventListener(
-        'abort',
-        () => reject(new Error('Pipeline aborted')),
-        { once: true },
-      );
+      const handler = () => reject(new Error('Pipeline aborted'));
+      // Store reference so we can remove it after the race settles.
+      (onAbort as { handler?: () => void }).handler = handler;
+      ctx.signal.addEventListener('abort', handler, { once: true });
     });
 
-    const decision = await Promise.race([decisionPromise, abortPromise]);
+    let decision: Awaited<typeof decisionPromise>;
+    try {
+      decision = await Promise.race([decisionPromise, abortPromise]);
+    } finally {
+      // Clean up the abort listener to prevent leaking on normal completion.
+      const handler = (onAbort as { handler?: () => void }).handler;
+      if (handler) ctx.signal.removeEventListener('abort', handler);
+    }
 
     switch (decision.outcome) {
       case 'approved':

package/src/utils.ts

@@ -1,12 +1,12 @@
 import { resolve, relative } from 'path';
 import { randomBytes } from 'crypto';
 
-const DURATION_RE = /^(\d+(?:\.\d+)?)\s*(s|m|h)$/;
+const DURATION_RE = /^(\d*\.?\d+)\s*(s|m|h|d)$/;
 
 export function parseDuration(input: string): number {
   const match = DURATION_RE.exec(input.trim());
   if (!match) {
-    throw new Error(`Invalid duration format: "${input}". Expected format: <number>(s|m|h)`);
+    throw new Error(`Invalid duration format: "${input}". Expected format: <number>(s|m|h|d)`);
   }
   const value = parseFloat(match[1]);
   const unit = match[2];
@@ -14,6 +14,7 @@ export function parseDuration(input: string): number {
     case 's': return value * 1000;
     case 'm': return value * 60_000;
     case 'h': return value * 3_600_000;
+    case 'd': return value * 86_400_000;
     default:  throw new Error(`Unknown duration unit: "${unit}"`);
   }
 }
@@ -136,8 +137,13 @@ export function shellArgs(command: string): readonly string[] {
 /** Quote a single argument for inclusion in a shell command string. */
 function quoteArg(arg: string): string {
   if (!/[\s"'\\<>|&;`$!^%]/.test(arg)) return arg;
-  // Double-quote and escape embedded double quotes + backslashes
-  return '"' + arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+  if (IS_WINDOWS) {
+    // On Windows (cmd.exe), double-quote and escape embedded quotes + backslashes
+    return '"' + arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+  }
+  // On Unix, use single quotes to prevent $variable expansion.
+  // Escape embedded single quotes via the '\'' idiom.
+  return "'" + arg.replace(/'/g, "'\\''") + "'";
 }
 
 /**

package/src/validate-raw.ts

@@ -74,6 +74,7 @@ export function validateRaw(config: RawPipelineConfig): ValidationError[] {
     }
 
     // ── Per-task validation ──
+    const seenTaskIds = new Set<string>();
     for (let ki = 0; ki < track.tasks.length; ki++) {
       const task = track.tasks[ki];
       const taskPath = `${trackPath}.tasks[${ki}]`;
@@ -83,6 +84,11 @@ export function validateRaw(config: RawPipelineConfig): ValidationError[] {
         continue; // Can't check further without an id
       }
 
+      if (seenTaskIds.has(task.id)) {
+        errors.push({ path: taskPath, message: `Duplicate task id "${task.id}" in track "${track.id}"` });
+      }
+      seenTaskIds.add(task.id);
+
       // Template-based tasks: skip prompt/command checks (params validated at runtime)
       if (task.use) continue;
 
@@ -195,10 +201,13 @@ function detectCycles(
   // Canonical key = sorted node list joined — order-independent fingerprint.
   const seenCycles = new Set<string>();
 
-  function dfs(id: string, path: string[]): void {
+  // Use a mutable path array instead of copying at each level (O(n) vs O(n^2)).
+  const pathStack: string[] = [];
+
+  function dfs(id: string): void {
     if (inStack.has(id)) {
-      const cycleStart = path.indexOf(id);
-      const cycleNodes = [...path.slice(cycleStart), id];
+      const cycleStart = pathStack.indexOf(id);
+      const cycleNodes = [...pathStack.slice(cycleStart), id];
       const key = [...cycleNodes].sort().join(',');
       if (!seenCycles.has(key)) {
         seenCycles.add(key);
@@ -209,14 +218,16 @@ function detectCycles(
     if (visited.has(id)) return;
     visited.add(id);
     inStack.add(id);
+    pathStack.push(id);
     for (const dep of adj.get(id) ?? []) {
-      dfs(dep, [...path, id]);
+      dfs(dep);
     }
+    pathStack.pop();
     inStack.delete(id);
   }
 
   for (const id of adj.keys()) {
-    if (!visited.has(id)) dfs(id, []);
+    if (!visited.has(id)) dfs(id);
   }
 
   return errors;