@tagma/sdk 0.1.4 → 0.1.6

package/README.md

@@ -108,10 +108,39 @@ Parses YAML, resolves inheritance, expands templates, and validates the configur
 
 ### `runPipeline(config, workDir, options?): Promise<EngineResult>`
 
-Executes the pipeline. Returns `{ success, summary, states }`.
+Executes the pipeline. Returns `{ success, runId, logPath, summary, states }`.
 
 Options:
 - `approvalGateway` -- custom `ApprovalGateway` instance (defaults to `InMemoryApprovalGateway`)
+- `signal` -- `AbortSignal` to cancel the run externally
+- `onEvent` -- callback for real-time `PipelineEvent` updates (task status changes, pipeline start/end)
+- `maxLogRuns` -- number of per-run log directories to keep under `<workDir>/logs/` (default: 20)
+
+### `PipelineRunner`
+
+Higher-level wrapper for managing multiple concurrent pipeline runs — designed for sidecar / Tauri IPC scenarios where the frontend controls pipeline lifecycle by ID.
+
+```ts
+const runner = new PipelineRunner(config, workDir);
+
+// Subscribe before start — handler is called for every PipelineEvent
+const unsubscribe = runner.subscribe(event => {
+  tauriEmit('pipeline_event', { id: runner.instanceId, event });
+});
+
+runner.start(); // returns Promise<EngineResult>, idempotent
+
+// Cancel from IPC
+runner.abort();
+
+// After completion
+const states = runner.getStates(); // ReadonlyMap<taskId, TaskState>
+```
+
+Properties:
+- `instanceId` — stable ID assigned at construction, safe to use as a Map key before `start()`
+- `runId` — engine-assigned run ID, available after the first `pipeline_start` event (`null` until then)
+- `status` — `'idle' | 'running' | 'done' | 'aborted'`
 
 ### `loadPlugins(names: string[]): Promise<void>`
 
@@ -125,6 +154,83 @@ Attaches an interactive stdin-based approval handler.
 
 Starts a WebSocket server for remote approval decisions.
 
+### Config CRUD (`config-ops`)
+
+Pure, immutable helper functions for building and editing `RawPipelineConfig` in a visual editor. No runtime dependencies — safe to use in renderer processes.
+
+```ts
+import {
+  createEmptyPipeline, setPipelineField,
+  upsertTrack, removeTrack, moveTrack, updateTrack,
+  upsertTask, removeTask, moveTask, transferTask,
+  serializePipeline,
+} from '@tagma/sdk';
+
+// Build a config programmatically
+let config = createEmptyPipeline('my-pipeline');
+config = upsertTrack(config, { id: 'backend', name: 'Backend', tasks: [] });
+config = upsertTask(config, 'backend', { id: 'implement', prompt: 'Add /health endpoint' });
+
+// Sync back to YAML
+const yaml = serializePipeline(config);
+```
+
+| Function | Description |
+|---|---|
+| `createEmptyPipeline(name)` | Create a minimal pipeline config |
+| `setPipelineField(config, fields)` | Update top-level pipeline fields |
+| `upsertTrack(config, track)` | Insert or replace a track by id |
+| `removeTrack(config, trackId)` | Remove a track |
+| `moveTrack(config, trackId, toIndex)` | Reorder a track |
+| `updateTrack(config, trackId, fields)` | Patch track fields (not tasks) |
+| `upsertTask(config, trackId, task)` | Insert or replace a task |
+| `removeTask(config, trackId, taskId)` | Remove a task |
+| `moveTask(config, trackId, taskId, toIndex)` | Reorder a task within its track |
+| `transferTask(config, fromTrackId, taskId, toTrackId)` | Move a task across tracks |
+
+### `parseYaml(content: string): RawPipelineConfig`
+
+Parses a YAML string and returns the raw (unresolved) pipeline config. Use this when you need to edit and re-save YAML without losing relative paths or user-authored formatting — pass the result to `serializePipeline()` rather than going through `loadPipeline()`.
+
+### `deresolvePipeline(config: PipelineConfig, workDir: string): RawPipelineConfig`
+
+Converts a resolved `PipelineConfig` back to a `RawPipelineConfig` suitable for serialization. Strips injected defaults and converts absolute `cwd` paths back to relative so the output YAML is portable across machines.
+
+Use this when you have a programmatically modified resolved config and need to save it back to YAML:
+
+```ts
+// Correct: load → modify resolved config → deresolve → save
+const config = await loadPipeline(yaml, workDir);
+const modified = { ...config, name: 'renamed' };
+const savedYaml = serializePipeline(deresolvePipeline(modified, workDir));
+
+// Also correct: work entirely in raw space (preferred for visual editors)
+const raw = parseYaml(yaml);
+const updatedRaw = setPipelineField(raw, { name: 'renamed' });
+const savedYaml = serializePipeline(updatedRaw);
+```
+
+### `validateConfig(config: PipelineConfig): string[]`
+
+Validates a resolved pipeline config without executing it. Checks DAG structure (cycles, missing dependencies). Returns an array of error message strings — empty means valid.
+
+Use `validateRaw` for editing raw configs in a UI; use `validateConfig` after `resolveConfig` for a final pre-run check.
+
+### `validateRaw(config: RawPipelineConfig): ValidationError[]`
+
+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, circular dependency detection.
+
+Does **not** check plugin registration (plugins may not be loaded at edit time).
+
+```ts
+const errors = validateRaw(draftConfig);
+if (errors.length > 0) {
+  errors.forEach(e => highlightNode(e.path, e.message));
+}
+```
+
 ## Related Packages
 
 | Package | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "workspaces": [
     "plugins/*"
@@ -20,13 +20,13 @@
   "dependencies": {
     "js-yaml": "^4.1.0",
     "chokidar": "^4.0.0",
-    "@tagma/types": "workspace:*"
+    "@tagma/types": "0.1.3"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "bun-types": "latest",
     "typescript": "^6.0.2",
-    "@tagma/driver-codex": "workspace:*",
-    "@tagma/driver-opencode": "workspace:*"
+    "@tagma/driver-codex": "0.1.3",
+    "@tagma/driver-opencode": "0.1.3"
   }
 }

package/src/config-ops.ts

@@ -0,0 +1,183 @@
+// ═══ RawPipelineConfig CRUD Operations ═══
+//
+// Pure, immutable helper functions for building and editing pipeline configs
+// in a visual editor. None of these functions have runtime dependencies —
+// safe to import in any context (sidecar, renderer, tests).
+//
+// All operations return a new config object; inputs are never mutated.
+
+import type { RawPipelineConfig, RawTrackConfig, RawTaskConfig } from './types';
+
+// ── Pipeline ──
+
+/**
+ * Create a minimal empty pipeline config.
+ */
+export function createEmptyPipeline(name: string): RawPipelineConfig {
+  return { name, tracks: [] };
+}
+
+/**
+ * Update a top-level pipeline field (name, driver, timeout, etc.).
+ */
+export function setPipelineField(
+  config: RawPipelineConfig,
+  fields: Partial<Omit<RawPipelineConfig, 'tracks'>>,
+): RawPipelineConfig {
+  return { ...config, ...fields };
+}
+
+// ── Tracks ──
+
+/**
+ * Insert or replace a track by id. Appends if the id is new.
+ */
+export function upsertTrack(
+  config: RawPipelineConfig,
+  track: RawTrackConfig,
+): RawPipelineConfig {
+  const exists = config.tracks.some(t => t.id === track.id);
+  return {
+    ...config,
+    tracks: exists
+      ? config.tracks.map(t => (t.id === track.id ? track : t))
+      : [...config.tracks, track],
+  };
+}
+
+/**
+ * Remove a track by id. No-op if the id is not found.
+ */
+export function removeTrack(
+  config: RawPipelineConfig,
+  trackId: string,
+): RawPipelineConfig {
+  return { ...config, tracks: config.tracks.filter(t => t.id !== trackId) };
+}
+
+/**
+ * Move a track to a new index position (0-based).
+ * Clamps toIndex to valid bounds.
+ */
+export function moveTrack(
+  config: RawPipelineConfig,
+  trackId: string,
+  toIndex: number,
+): RawPipelineConfig {
+  const idx = config.tracks.findIndex(t => t.id === trackId);
+  if (idx === -1) return config;
+  const tracks = [...config.tracks];
+  const [track] = tracks.splice(idx, 1);
+  const clamped = Math.max(0, Math.min(toIndex, tracks.length));
+  tracks.splice(clamped, 0, track);
+  return { ...config, tracks };
+}
+
+/**
+ * Update fields on a single track (excluding tasks list, use upsertTask / removeTask for that).
+ */
+export function updateTrack(
+  config: RawPipelineConfig,
+  trackId: string,
+  fields: Partial<Omit<RawTrackConfig, 'id' | 'tasks'>>,
+): RawPipelineConfig {
+  return {
+    ...config,
+    tracks: config.tracks.map(t =>
+      t.id === trackId ? { ...t, ...fields } : t,
+    ),
+  };
+}
+
+// ── Tasks ──
+
+/**
+ * Insert or replace a task within a track, matched by task.id. Appends if new.
+ * No-op if the trackId is not found.
+ */
+export function upsertTask(
+  config: RawPipelineConfig,
+  trackId: string,
+  task: RawTaskConfig,
+): RawPipelineConfig {
+  return {
+    ...config,
+    tracks: config.tracks.map(t => {
+      if (t.id !== trackId) return t;
+      const exists = t.tasks.some(tk => tk.id === task.id);
+      return {
+        ...t,
+        tasks: exists
+          ? t.tasks.map(tk => (tk.id === task.id ? task : tk))
+          : [...t.tasks, task],
+      };
+    }),
+  };
+}
+
+/**
+ * Remove a task from a track. No-op if either id is not found.
+ */
+export function removeTask(
+  config: RawPipelineConfig,
+  trackId: string,
+  taskId: string,
+): RawPipelineConfig {
+  return {
+    ...config,
+    tracks: config.tracks.map(t => {
+      if (t.id !== trackId) return t;
+      return { ...t, tasks: t.tasks.filter(tk => tk.id !== taskId) };
+    }),
+  };
+}
+
+/**
+ * Reorder a task within its track.
+ * Clamps toIndex to valid bounds.
+ */
+export function moveTask(
+  config: RawPipelineConfig,
+  trackId: string,
+  taskId: string,
+  toIndex: number,
+): RawPipelineConfig {
+  return {
+    ...config,
+    tracks: config.tracks.map(t => {
+      if (t.id !== trackId) return t;
+      const idx = t.tasks.findIndex(tk => tk.id === taskId);
+      if (idx === -1) return t;
+      const tasks = [...t.tasks];
+      const [task] = tasks.splice(idx, 1);
+      const clamped = Math.max(0, Math.min(toIndex, tasks.length));
+      tasks.splice(clamped, 0, task);
+      return { ...t, tasks };
+    }),
+  };
+}
+
+/**
+ * Move a task from one track to another (appends to the target track).
+ * No-op if either trackId or taskId is not found.
+ */
+export function transferTask(
+  config: RawPipelineConfig,
+  fromTrackId: string,
+  taskId: string,
+  toTrackId: string,
+): RawPipelineConfig {
+  let task: RawTaskConfig | undefined;
+  const afterRemove = {
+    ...config,
+    tracks: config.tracks.map(t => {
+      if (t.id !== fromTrackId) return t;
+      const found = t.tasks.find(tk => tk.id === taskId);
+      if (!found) return t;
+      task = found;
+      return { ...t, tasks: t.tasks.filter(tk => tk.id !== taskId) };
+    }),
+  };
+  if (!task) return config;
+  return upsertTask(afterRemove, toTrackId, task);
+}

package/src/engine.ts

@@ -7,7 +7,7 @@ import type {
   OnFailure,
 } from './types';
 import { buildDag, type Dag, type DagNode } from './dag';
-import { getHandler, hasHandler } from './registry';
+import { getHandler, hasHandler, loadPlugins } from './registry';
 import { runSpawn, runCommand } from './runner';
 import { parseDuration, nowISO, generateRunId } from './utils';
 import {
@@ -94,6 +94,13 @@ export interface EngineResult {
   readonly states: ReadonlyMap<string, TaskState>;
 }
 
+// ═══ Pipeline Events ═══
+
+export type PipelineEvent =
+  | { readonly type: 'task_status_change'; readonly taskId: string; readonly status: TaskStatus; readonly prevStatus: TaskStatus; readonly runId: string }
+  | { readonly type: 'pipeline_start'; readonly runId: string }
+  | { readonly type: 'pipeline_end'; readonly runId: string; readonly success: boolean };
+
 export interface RunPipelineOptions {
   readonly approvalGateway?: ApprovalGateway;
   /**
@@ -101,6 +108,16 @@ export interface RunPipelineOptions {
    * Oldest directories are deleted after each run. Defaults to 20. Set to 0 to disable cleanup.
    */
   readonly maxLogRuns?: number;
+  /**
+   * External AbortSignal — aborting it cancels the pipeline immediately.
+   * Equivalent to the pipeline timeout firing, but caller-controlled.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Called on every pipeline/task status transition.
+   * Use for real-time UI updates (e.g. updating a visual workflow graph).
+   */
+  readonly onEvent?: (event: PipelineEvent) => void;
 }
 
 export async function runPipeline(
@@ -110,10 +127,17 @@ export async function runPipeline(
 ): Promise<EngineResult> {
   const approvalGateway = options.approvalGateway ?? new InMemoryApprovalGateway();
   const maxLogRuns = options.maxLogRuns ?? 20;
+
+  // Load any plugins declared in the pipeline config before preflight so that
+  // drivers, completions, and middlewares referenced in YAML are registered.
+  if (config.plugins?.length) {
+    await loadPlugins(config.plugins);
+  }
+
   const dag = buildDag(config);
+  const runId = generateRunId();
   preflight(config, dag);
 
-  const runId = generateRunId();
   const startedAt = nowISO();
   const pipelineInfo: PipelineInfo = { name: config.name, run_id: runId, started_at: startedAt };
   const log = new Logger(workDir, runId);
@@ -150,6 +174,8 @@ export async function runPipeline(
     });
   }
 
+  try {
+
   // Pipeline start hook (gate)
   const startHook = await executeHook(
     config.hooks, 'pipeline_start', buildPipelineStartContext(pipelineInfo), workDir,
@@ -172,6 +198,7 @@ export async function runPipeline(
   for (const [, state] of states) {
     state.status = 'waiting';
   }
+  options.onEvent?.({ type: 'pipeline_start', runId });
 
   const sessionMap = new Map<string, string>();
   const outputMap = new Map<string, string>();
@@ -196,8 +223,32 @@ export async function runPipeline(
     approvalGateway.abortAll('pipeline aborted');
   });
 
+  // Wire external cancel signal into the internal abort controller.
+  if (options.signal) {
+    if (options.signal.aborted) {
+      pipelineAborted = true;
+      abortController.abort();
+    } else {
+      options.signal.addEventListener('abort', () => {
+        pipelineAborted = true;
+        abortController.abort();
+      }, { once: true });
+    }
+  }
+
   // ── Helpers ──
 
+  function emit(event: PipelineEvent): void {
+    options.onEvent?.(event);
+  }
+
+  function setTaskStatus(taskId: string, newStatus: TaskStatus): void {
+    const state = states.get(taskId)!;
+    const prevStatus = state.status;
+    state.status = newStatus;
+    emit({ type: 'task_status_change', taskId, status: newStatus, prevStatus, runId });
+  }
+
   function getOnFailure(taskId: string): OnFailure {
     return dag.nodes.get(taskId)?.track.on_failure ?? 'skip_downstream';
   }
@@ -215,10 +266,9 @@ export async function runPipeline(
   }
 
   function applyStopAll(trackId: string): void {
-    for (const [, state] of states) {
-      const node = dag.nodes.get(state.config.id);
+    for (const [id, state] of states) {
       if (state.trackConfig.id === trackId && !isTerminal(state.status)) {
-        state.status = 'skipped';
+        setTaskStatus(id, 'skipped');
         state.finishedAt = nowISO();
       }
     }
@@ -269,7 +319,7 @@ export async function runPipeline(
       if (result === 'skip') {
         const depStatus = states.get(depId)?.status ?? 'unknown';
         log.debug(`[task:${taskId}]`, `skipped (upstream "${depId}" status=${depStatus})`);
-        state.status = 'skipped';
+        setTaskStatus(taskId, 'skipped');
         state.finishedAt = nowISO();
         return;
       }
@@ -294,13 +344,13 @@ export async function runPipeline(
         // If pipeline was aborted while we were still waiting for the trigger,
         // this task never entered running state → skipped, not timeout.
         if (pipelineAborted) {
-          state.status = 'skipped';
+          setTaskStatus(taskId, 'skipped');
         } else if (msg.includes('rejected') || msg.includes('denied')) {
-          state.status = 'blocked';       // user/policy rejection
+          setTaskStatus(taskId, 'blocked');       // user/policy rejection
         } else if (msg.includes('timeout')) {
-          state.status = 'timeout';       // genuine trigger wait timeout
+          setTaskStatus(taskId, 'timeout');       // genuine trigger wait timeout
         } else {
-          state.status = 'failed';        // plugin error, watcher crash, etc.
+          setTaskStatus(taskId, 'failed');        // plugin error, watcher crash, etc.
         }
         state.finishedAt = nowISO();
         await fireHook(taskId, 'task_failure');
@@ -316,14 +366,14 @@ export async function runPipeline(
         `task_start hook exit=${hookResult.exitCode} allowed=${hookResult.allowed}`);
     }
     if (!hookResult.allowed) {
-      state.status = 'blocked';
+      setTaskStatus(taskId, 'blocked');
       state.finishedAt = nowISO();
       await fireHook(taskId, 'task_failure');
       return;
     }
 
     // 4. Mark running
-    state.status = 'running';
+    setTaskStatus(taskId, 'running');
     state.startedAt = nowISO();
     log.info(`[task:${taskId}]`, task.command ? `running: ${task.command}` : `running (driver task)`);
 
@@ -395,16 +445,16 @@ export async function runPipeline(
 
       // 5. Determine status
       if (result.exitCode === -1) {
-        state.status = 'timeout';
+        setTaskStatus(taskId, 'timeout');
       } else if (result.exitCode !== 0) {
-        state.status = 'failed';
+        setTaskStatus(taskId, 'failed');
       } else if (task.completion) {
         const plugin = getHandler<CompletionPlugin>('completions', task.completion.type);
         const completionCtx = { workDir: task.cwd ?? workDir };
         const passed = await plugin.check(task.completion as Record<string, unknown>, result, completionCtx);
-        state.status = passed ? 'success' : 'failed';
+        setTaskStatus(taskId, passed ? 'success' : 'failed');
       } else {
-        state.status = 'success';
+        setTaskStatus(taskId, 'success');
       }
 
       // 6. Write output file with RAW stdout (preserves driver output format).
@@ -478,7 +528,7 @@ export async function runPipeline(
       }
 
     } catch (err: unknown) {
-      state.status = 'failed';
+      setTaskStatus(taskId, 'failed');
       state.finishedAt = nowISO();
       const errMsg = err instanceof Error ? (err.stack ?? err.message) : String(err);
       log.error(`[task:${taskId}]`, `failed before execution: ${errMsg}`);
@@ -502,40 +552,44 @@ export async function runPipeline(
   }
 
   // ── Event loop ──
-  try {
-    let progress = true;
-    while (progress && !pipelineAborted) {
-      progress = false;
+  // Each task is launched as soon as ALL its deps reach a terminal state.
+  // We track in-flight tasks in `running` so a task completing mid-batch
+  // immediately unblocks its dependents without waiting for sibling tasks.
+  const running = new Map<string, Promise<void>>();
 
-      // Collect tasks whose deps are all terminal and that are still waiting
-      const launchable: string[] = [];
+  try {
+    while (!pipelineAborted) {
+      // Launch every task whose deps are all terminal and that isn't already in-flight
       for (const [id, state] of states) {
-        if (state.status !== 'waiting') continue;
+        if (state.status !== 'waiting' || running.has(id)) continue;
         const node = dag.nodes.get(id)!;
         const allDepsTerminal = node.dependsOn.length === 0 ||
           node.dependsOn.every(d => isTerminal(states.get(d)!.status));
-        if (allDepsTerminal) launchable.push(id);
+        if (!allDepsTerminal) continue;
+        const p = processTask(id).finally(() => running.delete(id));
+        running.set(id, p);
       }
 
-      if (launchable.length === 0) {
-        // Check if anything is still running (trigger waits etc.)
-        const anyNonTerminal = [...states.values()].some(s => !isTerminal(s.status));
-        if (!anyNonTerminal) break;
+      // All tasks terminal — done
+      if ([...states.values()].every(s => isTerminal(s.status))) break;
+
+      if (running.size === 0) {
+        // Nothing in-flight but non-terminal tasks exist (e.g. trigger-wait states
+        // that processTask hasn't been called for yet). Poll briefly.
         await new Promise(r => setTimeout(r, 50));
-        progress = true;
-        continue;
+      } else {
+        // Wait for any one task to finish, then re-scan for new launchables.
+        await Promise.race(running.values());
       }
-
-      // Launch all launchable tasks concurrently
-      await Promise.all(launchable.map(id => processTask(id)));
-      progress = true;
     }
 
     if (pipelineAborted) {
-      for (const [, state] of states) {
+      // Wait for in-flight tasks to honour the abort signal before marking states.
+      if (running.size > 0) await Promise.allSettled(running.values());
+      for (const [id, state] of states) {
         if (!isTerminal(state.status)) {
           // Running tasks get timeout (they were killed); waiting tasks get skipped
-          state.status = state.status === 'running' ? 'timeout' : 'skipped';
+          setTaskStatus(id, state.status === 'running' ? 'timeout' : 'skipped');
           state.finishedAt = nowISO();
         }
       }
@@ -597,20 +651,27 @@ export async function runPipeline(
   console.log(`  Duration: ${(durationMs / 1000).toFixed(1)}s`);
   console.log(`  Log: ${log.path}`);
 
-  // Prune old per-run log directories, keeping only the most recent maxLogRuns.
-  if (maxLogRuns > 0) {
-    await pruneLogDirs(resolve(workDir, 'logs'), maxLogRuns);
-  }
-
+  emit({ type: 'pipeline_end', runId, success: allSuccess });
   return { success: allSuccess, runId, logPath: log.path, summary, states };
+
+  } finally {
+    // 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) {
+      await pruneLogDirs(resolve(workDir, 'logs'), maxLogRuns, runId);
+    }
+  }
 }
 
 /**
  * Delete the oldest subdirectories under `logsDir`, keeping only the most recent `keep`.
  * Directories are sorted lexicographically; because runIds are prefixed with a base-36
  * timestamp, lexicographic order equals chronological order.
+ *
+ * `excludeRunId` is always skipped from deletion even if it would otherwise be pruned —
+ * this prevents a concurrent run from removing a live log directory that is still in use.
  */
-async function pruneLogDirs(logsDir: string, keep: number): Promise<void> {
+async function pruneLogDirs(logsDir: string, keep: number, excludeRunId: string): Promise<void> {
   let entries: string[];
   try {
     entries = await readdir(logsDir);
@@ -618,8 +679,8 @@ async function pruneLogDirs(logsDir: string, keep: number): Promise<void> {
     return; // logsDir doesn't exist yet — nothing to prune
   }
 
-  // Only consider directories that look like run IDs (run_<...>)
-  const runDirs = entries.filter(e => e.startsWith('run_')).sort();
+  // Only consider directories that look like run IDs (run_<...>), excluding the live run.
+  const runDirs = entries.filter(e => e.startsWith('run_') && e !== excludeRunId).sort();
   const toDelete = runDirs.slice(0, Math.max(0, runDirs.length - keep));
 
   await Promise.all(

package/src/pipeline-runner.ts

@@ -0,0 +1,113 @@
+// ═══ PipelineRunner ═══
+//
+// Wraps runPipeline in a lifecycle object suited for multi-pipeline management
+// in sidecar / Tauri IPC scenarios. Each instance controls one pipeline run.
+//
+// Typical sidecar usage:
+//
+//   const runners = new Map<string, PipelineRunner>();
+//
+//   const runner = new PipelineRunner(config, workDir);
+//   runner.subscribe(event => ipcEmit('pipeline_event', event));
+//   runner.start();
+//   runners.set(runner.instanceId, runner);
+//
+//   // Later, from IPC:
+//   runners.get(id)?.abort();
+
+import { runPipeline } from './engine';
+import type { EngineResult, PipelineEvent, RunPipelineOptions } from './engine';
+import type { PipelineConfig, TaskState } from './types';
+import { generateRunId } from './utils';
+
+export type { PipelineEvent, EngineResult };
+
+export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
+
+export class PipelineRunner {
+  /**
+   * Stable ID assigned before start() — safe to use as a Map key in the sidecar
+   * before the engine-assigned runId becomes available.
+   */
+  readonly instanceId: string;
+
+  /**
+   * The runId generated by the engine. Available after the first 'pipeline_start'
+   * event fires (i.e. effectively immediately after start() is called).
+   * null until then.
+   */
+  private _runId: string | null = null;
+  private _status: PipelineRunnerStatus = 'idle';
+  private _result: Promise<EngineResult> | null = null;
+  private _abortController = new AbortController();
+  private _handlers = new Set<(event: PipelineEvent) => void>();
+  private _states: ReadonlyMap<string, TaskState> | null = null;
+
+  constructor(
+    private readonly config: PipelineConfig,
+    private readonly workDir: string,
+    private readonly opts: Omit<RunPipelineOptions, 'signal' | 'onEvent'> = {},
+  ) {
+    this.instanceId = generateRunId();
+  }
+
+  get runId(): string | null { return this._runId; }
+  get status(): PipelineRunnerStatus { return this._status; }
+
+  /**
+   * Start the pipeline. Calling start() more than once returns the same Promise.
+   */
+  start(): Promise<EngineResult> {
+    if (this._result) return this._result;
+
+    this._status = 'running';
+    this._result = runPipeline(this.config, this.workDir, {
+      ...this.opts,
+      signal: this._abortController.signal,
+      onEvent: (event) => {
+        if (event.type === 'pipeline_start') {
+          this._runId = event.runId;
+        }
+        if (event.type === 'pipeline_end') {
+          this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
+        }
+        for (const h of this._handlers) h(event);
+      },
+    }).then(result => {
+      this._states = result.states;
+      if (this._status === 'running') this._status = 'done';
+      return result;
+    }).catch(err => {
+      this._status = 'aborted';
+      throw err;
+    });
+
+    return this._result;
+  }
+
+  /**
+   * Cancel the running pipeline. Safe to call multiple times or before start().
+   */
+  abort(reason?: string): void {
+    this._status = 'aborted';
+    this._abortController.abort(reason);
+  }
+
+  /**
+   * Snapshot of task states. Populated after the run completes.
+   * During a run, listen to subscribe() events for incremental updates.
+   */
+  getStates(): ReadonlyMap<string, TaskState> | null {
+    return this._states;
+  }
+
+  /**
+   * Subscribe to pipeline/task events. Returns an unsubscribe function.
+   * Events are emitted synchronously in the engine's event loop, so keep
+   * handlers non-blocking (e.g. queue to IPC, do not await inside).
+   */
+  subscribe(handler: (event: PipelineEvent) => void): () => void {
+    this._handlers.add(handler);
+    return () => this._handlers.delete(handler);
+  }
+}

package/src/registry.ts

@@ -16,9 +16,7 @@ export function registerPlugin<T extends PluginType>(
   category: PluginCategory, type: string, handler: T,
 ): void {
   const registry = registries[category] as Map<string, T>;
-  if (registry.has(type)) {
-    throw new Error(`${category} type "${type}" is already registered`);
-  }
+  if (registry.has(type)) return; // idempotent — skip duplicate registration
   registry.set(type, handler);
 }
 

package/src/runner.ts

@@ -151,9 +151,11 @@ export async function runSpawn(
 
   const durationMs = elapsed();
 
-  // If we killed the process but it had already exited with a real code
-  // before our signal landed, don't treat it as a timeout.
-  if (killedByUs && exitCode !== 0) {
+  // 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) {
     return {
       exitCode: -1,
       stdout,

package/src/schema.ts

@@ -1,5 +1,5 @@
 import yaml from 'js-yaml';
-import { resolve } from 'path';
+import { resolve, relative } from 'path';
 import type {
   PipelineConfig, RawPipelineConfig, RawTrackConfig, RawTaskConfig,
   TrackConfig, TaskConfig, Permissions, MiddlewareConfig,
@@ -7,6 +7,7 @@ import type {
 } from './types';
 import { truncateForName, validatePathParam } from './utils';
 import { DEFAULT_PERMISSIONS } from './types';
+import { buildDag } from './dag';
 
 // ═══ YAML Parsing ═══
 
@@ -243,6 +244,103 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
   };
 }
 
+// ═══ YAML Serialization ═══
+
+/**
+ * Serialize a pipeline config back to YAML string.
+ * Wraps the config under the top-level `pipeline` key as expected by parseYaml.
+ */
+export function serializePipeline(config: PipelineConfig | RawPipelineConfig): string {
+  return yaml.dump({ pipeline: config }, { lineWidth: 120, indent: 2 });
+}
+
+/**
+ * Convert a resolved PipelineConfig back to a RawPipelineConfig for serialization.
+ * Strips injected defaults and converts absolute cwd paths back to relative so the
+ * resulting YAML is portable across machines.
+ *
+ * Use this when you need to save a config that was previously loaded via
+ * loadPipeline(). For a pure load→edit→save cycle on raw YAML, prefer
+ * parseYaml() → edit RawPipelineConfig → serializePipeline().
+ */
+export function deresolvePipeline(config: PipelineConfig, workDir: string): RawPipelineConfig {
+  const tracks: RawTrackConfig[] = config.tracks.map(track => {
+    const trackCwdRel = track.cwd && track.cwd !== workDir
+      ? relative(workDir, track.cwd)
+      : undefined;
+    const effectiveTrackDriver = track.driver ?? config.driver ?? 'claude-code';
+
+    const tasks: RawTaskConfig[] = track.tasks.map(task => {
+      const taskCwdRel = task.cwd && task.cwd !== track.cwd
+        ? relative(workDir, task.cwd)
+        : undefined;
+
+      return {
+        id: task.id,
+        ...(task.name ? { name: task.name } : {}),
+        ...(task.prompt !== undefined ? { prompt: task.prompt } : {}),
+        ...(task.command !== undefined ? { command: task.command } : {}),
+        ...(task.depends_on?.length ? { depends_on: task.depends_on } : {}),
+        ...(task.trigger ? { trigger: task.trigger } : {}),
+        ...(task.continue_from ? { continue_from: task.continue_from } : {}),
+        ...(task.output ? { output: task.output } : {}),
+        ...(taskCwdRel ? { cwd: taskCwdRel } : {}),
+        ...(task.model_tier && task.model_tier !== 'medium' ? { model_tier: task.model_tier } : {}),
+        ...(task.driver && task.driver !== effectiveTrackDriver ? { driver: task.driver } : {}),
+        ...(task.timeout ? { timeout: task.timeout } : {}),
+        ...(task.middlewares !== undefined ? { middlewares: task.middlewares } : {}),
+        ...(task.completion ? { completion: task.completion } : {}),
+        ...(task.agent_profile ? { agent_profile: task.agent_profile } : {}),
+        ...(task.permissions && JSON.stringify(task.permissions) !== JSON.stringify(DEFAULT_PERMISSIONS)
+          ? { permissions: task.permissions }
+          : {}),
+      };
+    });
+
+    return {
+      id: track.id,
+      name: track.name,
+      ...(track.color ? { color: track.color } : {}),
+      ...(track.agent_profile ? { agent_profile: track.agent_profile } : {}),
+      ...(track.model_tier && track.model_tier !== 'medium' ? { model_tier: track.model_tier } : {}),
+      ...(track.driver && track.driver !== (config.driver ?? 'claude-code') ? { driver: track.driver } : {}),
+      ...(trackCwdRel ? { cwd: trackCwdRel } : {}),
+      ...(track.middlewares?.length ? { middlewares: track.middlewares } : {}),
+      ...(track.on_failure && track.on_failure !== 'skip_downstream' ? { on_failure: track.on_failure } : {}),
+      ...(track.permissions && JSON.stringify(track.permissions) !== JSON.stringify(DEFAULT_PERMISSIONS)
+        ? { permissions: track.permissions }
+        : {}),
+      tasks,
+    };
+  });
+
+  return {
+    name: config.name,
+    ...(config.driver ? { driver: config.driver } : {}),
+    ...(config.timeout ? { timeout: config.timeout } : {}),
+    ...(config.plugins?.length ? { plugins: config.plugins } : {}),
+    ...(config.hooks ? { hooks: config.hooks } : {}),
+    tracks,
+  };
+}
+
+// ═══ Offline Validation ═══
+
+/**
+ * Validate a pipeline config without executing it.
+ * Only checks structural/DAG correctness — does not check plugin registration.
+ * Returns an array of error messages (empty = valid).
+ */
+export function validateConfig(config: PipelineConfig): string[] {
+  const errors: string[] = [];
+  try {
+    buildDag(config);
+  } catch (err) {
+    errors.push(err instanceof Error ? err.message : String(err));
+  }
+  return errors;
+}
+
 // ═══ Full Parse Pipeline ═══
 
 export async function loadPipeline(yamlContent: string, workDir: string): Promise<PipelineConfig> {

package/src/sdk.ts

@@ -5,10 +5,32 @@
 
 // ── Core engine ──
 export { runPipeline } from './engine';
-export type { EngineResult, RunPipelineOptions } from './engine';
+export type { EngineResult, RunPipelineOptions, PipelineEvent } from './engine';
 
-// ── Schema: parse / resolve / load ──
-export { parseYaml, resolveConfig, expandTemplates, loadPipeline } from './schema';
+// ── Pipeline runner (multi-pipeline lifecycle management) ──
+export { PipelineRunner } from './pipeline-runner';
+export type { PipelineRunnerStatus } from './pipeline-runner';
+
+// ── Raw config CRUD (visual editor / YAML sync) ──
+export {
+  createEmptyPipeline,
+  setPipelineField,
+  upsertTrack,
+  removeTrack,
+  moveTrack,
+  updateTrack,
+  upsertTask,
+  removeTask,
+  moveTask,
+  transferTask,
+} from './config-ops';
+
+// ── Raw config validation (real-time feedback) ──
+export { validateRaw } from './validate-raw';
+export type { ValidationError } from './validate-raw';
+
+// ── Schema: parse / resolve / load / serialize / validate ──
+export { parseYaml, resolveConfig, expandTemplates, loadPipeline, serializePipeline, deresolvePipeline, validateConfig } from './schema';
 
 // ── DAG ──
 export { buildDag } from './dag';

package/src/validate-raw.ts

@@ -0,0 +1,199 @@
+// ═══ Raw Pipeline Config Validation ═══
+//
+// Validates a RawPipelineConfig without resolving inheritance or executing
+// anything — intended for real-time feedback in a visual editor (e.g. drag
+// to add a task, live error highlighting).
+//
+// Returns a flat list of ValidationError objects. An empty array means valid.
+
+import type { RawPipelineConfig } from './types';
+
+export interface ValidationError {
+  /** JSONPath-style location, e.g. "tracks[0].tasks[1].prompt" */
+  path: string;
+  message: string;
+}
+
+/**
+ * Validate a raw pipeline config.
+ * Checks structure, required fields, prompt/command exclusivity,
+ * depends_on reference integrity, and circular dependencies.
+ *
+ * Does NOT check plugin registration — plugins may not be loaded yet
+ * when the frontend is editing a config offline.
+ */
+export function validateRaw(config: RawPipelineConfig): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // ── Top level ──
+  if (!config.name?.trim()) {
+    errors.push({ path: 'name', message: 'Pipeline name is required' });
+  }
+
+  if (!config.tracks || config.tracks.length === 0) {
+    errors.push({ path: 'tracks', message: 'At least one track is required' });
+    return errors; // No point going further without tracks
+  }
+
+  // ── Build qualified ID sets for cross-reference checks ──
+  // Qualified ID format: "trackId.taskId" (mirrors the engine's convention)
+  const allQualified = new Set<string>();
+  // For bare depends_on references: bare taskId → first qualified ID found
+  const bareToQualified = new Map<string, string>();
+
+  for (const track of config.tracks) {
+    if (!track.id) continue;
+    for (const task of track.tasks ?? []) {
+      if (!task.id) continue;
+      const qid = `${track.id}.${task.id}`;
+      allQualified.add(qid);
+      if (!bareToQualified.has(task.id)) {
+        bareToQualified.set(task.id, qid);
+      }
+    }
+  }
+
+  // ── Per-track validation ──
+  for (let ti = 0; ti < config.tracks.length; ti++) {
+    const track = config.tracks[ti];
+    const trackPath = `tracks[${ti}]`;
+
+    if (!track.id?.trim()) {
+      errors.push({ path: `${trackPath}.id`, message: 'Track id is required' });
+    }
+    if (!track.name?.trim()) {
+      errors.push({ path: `${trackPath}.name`, message: 'Track name is required' });
+    }
+
+    if (!track.tasks || track.tasks.length === 0) {
+      errors.push({ path: `${trackPath}.tasks`, message: `Track "${track.id || ti}": must have at least one task` });
+      continue;
+    }
+
+    // ── Per-task validation ──
+    for (let ki = 0; ki < track.tasks.length; ki++) {
+      const task = track.tasks[ki];
+      const taskPath = `${trackPath}.tasks[${ki}]`;
+
+      if (!task.id?.trim()) {
+        errors.push({ path: `${taskPath}.id`, message: 'Task id is required' });
+        continue; // Can't check further without an id
+      }
+
+      // Template-based tasks: skip prompt/command checks (params validated at runtime)
+      if (task.use) continue;
+
+      const hasPrompt = typeof task.prompt === 'string' && task.prompt.trim().length > 0;
+      const hasCommand = typeof task.command === 'string' && task.command.trim().length > 0;
+
+      if (!hasPrompt && !hasCommand) {
+        errors.push({
+          path: taskPath,
+          message: `Task "${task.id}": must have "prompt" or "command"`,
+        });
+      }
+      if (hasPrompt && hasCommand) {
+        errors.push({
+          path: taskPath,
+          message: `Task "${task.id}": cannot have both "prompt" and "command"`,
+        });
+      }
+
+      // ── depends_on reference checks ──
+      if (task.depends_on && task.depends_on.length > 0) {
+        for (const dep of task.depends_on) {
+          const resolved = resolveDepRef(dep, track.id, allQualified, bareToQualified);
+          if (!resolved) {
+            errors.push({
+              path: `${taskPath}.depends_on`,
+              message: `Task "${task.id}": depends_on "${dep}" — no such task found`,
+            });
+          }
+        }
+      }
+
+      // ── continue_from reference check ──
+      if (task.continue_from) {
+        const resolved = resolveDepRef(task.continue_from, track.id, allQualified, bareToQualified);
+        if (!resolved) {
+          errors.push({
+            path: `${taskPath}.continue_from`,
+            message: `Task "${task.id}": continue_from "${task.continue_from}" — no such task found`,
+          });
+        }
+      }
+    }
+  }
+
+  // ── Cycle detection ──
+  errors.push(...detectCycles(config, allQualified, bareToQualified));
+
+  return errors;
+}
+
+// ── Helpers ──
+
+function resolveDepRef(
+  ref: string,
+  fromTrackId: string,
+  allQualified: Set<string>,
+  bareToQualified: Map<string, string>,
+): string | null {
+  // Fully qualified reference (trackId.taskId)
+  if (allQualified.has(ref)) return ref;
+  // Same-track shorthand (just taskId)
+  const sameTrack = `${fromTrackId}.${ref}`;
+  if (allQualified.has(sameTrack)) return sameTrack;
+  // Global bare lookup (first match across all tracks)
+  return bareToQualified.get(ref) ?? null;
+}
+
+function detectCycles(
+  config: RawPipelineConfig,
+  allQualified: Set<string>,
+  bareToQualified: Map<string, string>,
+): ValidationError[] {
+  // Build adjacency: qualifiedId → [resolved dep qualifiedIds]
+  const adj = new Map<string, string[]>();
+
+  for (const track of config.tracks) {
+    if (!track.id) continue;
+    for (const task of track.tasks ?? []) {
+      if (!task.id || task.use) continue;
+      const qid = `${track.id}.${task.id}`;
+      const deps: string[] = [];
+      for (const dep of task.depends_on ?? []) {
+        const resolved = resolveDepRef(dep, track.id, allQualified, bareToQualified);
+        if (resolved) deps.push(resolved);
+      }
+      adj.set(qid, deps);
+    }
+  }
+
+  const errors: ValidationError[] = [];
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+
+  function dfs(id: string, path: string[]): void {
+    if (inStack.has(id)) {
+      // Trim path to just the cycle portion
+      const cycleStart = path.indexOf(id);
+      const cycle = [...path.slice(cycleStart), id].join(' → ');
+      errors.push({ path: 'tracks', message: `Circular dependency detected: ${cycle}` });
+      return;
+    }
+    if (visited.has(id)) return;
+    visited.add(id);
+    inStack.add(id);
+    for (const dep of adj.get(id) ?? []) {
+      dfs(dep, [...path, id]);
+    }
+    inStack.delete(id);
+  }
+
+  for (const id of adj.keys()) {
+    if (!visited.has(id)) dfs(id, []);
+  }
+
+  return errors;
+}