@tagma/sdk 0.6.11 → 0.7.0

package/src/core/log-prune.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pruneLogDirs } from './log-prune';
+
+function fixture(): string {
+  return mkdtempSync(join(tmpdir(), 'tagma-prune-'));
+}
+
+describe('pruneLogDirs', () => {
+  test('returns silently when logsDir does not exist', async () => {
+    const root = fixture();
+    try {
+      await expect(
+        pruneLogDirs(join(root, 'nope'), 5, 'run_live'),
+      ).resolves.toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('keeps the live run plus (keep-1) most recent historical runs', async () => {
+    const root = fixture();
+    try {
+      for (const id of ['run_001', 'run_002', 'run_003', 'run_004', 'run_005']) {
+        mkdirSync(join(root, id));
+      }
+      await pruneLogDirs(root, 3, 'run_005'); // keep=3 → 1 live + 2 historical
+      expect(readdirSync(root).sort()).toEqual(['run_003', 'run_004', 'run_005']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('never deletes the excluded live runId even if it would be pruned', async () => {
+    const root = fixture();
+    try {
+      for (const id of ['run_001', 'run_002', 'run_003']) mkdirSync(join(root, id));
+      await pruneLogDirs(root, 1, 'run_001');
+      expect(readdirSync(root).sort()).toEqual(['run_001']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('ignores entries that do not look like run dirs', async () => {
+    const root = fixture();
+    try {
+      mkdirSync(join(root, 'run_001'));
+      mkdirSync(join(root, 'not_a_run'));
+      await pruneLogDirs(root, 1, 'run_001');
+      expect(readdirSync(root).sort()).toEqual(['not_a_run', 'run_001']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/core/log-prune.ts

@@ -0,0 +1,43 @@
+import { readdir, rm } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+/**
+ * Delete the oldest subdirectories under `logsDir`, keeping only the
+ * most recent `keep` total runs (including the currently-live run
+ * identified by `excludeRunId`). 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.
+ *
+ * The live run occupies one slot out of `keep`, so the maximum number
+ * of *historical* dirs to retain is `keep - 1`.
+ */
+export async function pruneLogDirs(
+  logsDir: string,
+  keep: number,
+  excludeRunId: string,
+): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await readdir(logsDir);
+  } catch {
+    return; // logsDir doesn't exist yet
+  }
+
+  const runDirs = entries
+    .filter((e) => e.startsWith('run_') && e !== excludeRunId)
+    .sort();
+  const historyKeep = Math.max(0, keep - 1);
+  const toDelete = runDirs.slice(0, Math.max(0, runDirs.length - historyKeep));
+
+  await Promise.all(
+    toDelete.map((dir) =>
+      rm(resolve(logsDir, dir), { recursive: true, force: true }).catch(() => {
+        // Ignore deletion errors — stale dirs are better than a crash
+      }),
+    ),
+  );
+}

package/src/core/preflight.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from 'bun:test';
+import { preflight } from './preflight';
+import { buildDag } from '../dag';
+import { PluginRegistry } from '../registry';
+import { bootstrapBuiltins } from '../bootstrap';
+import type { PipelineConfig } from '../types';
+
+function emptyConfig(overrides: Partial<PipelineConfig> = {}): PipelineConfig {
+  return {
+    name: 'p',
+    tracks: [{ id: 't', name: 'T', tasks: [] }],
+    ...overrides,
+  };
+}
+
+describe('preflight', () => {
+  test('throws when a referenced driver is not registered', () => {
+    const reg = new PluginRegistry();
+    const cfg = emptyConfig({
+      tracks: [
+        { id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', prompt: 'hi' }] },
+      ],
+    });
+    expect(() => preflight(cfg, buildDag(cfg), reg)).toThrow(
+      /driver "opencode" not registered/,
+    );
+  });
+
+  test('passes when all referenced plugins are registered', () => {
+    const reg = new PluginRegistry();
+    bootstrapBuiltins(reg);
+    const cfg = emptyConfig({
+      tracks: [
+        { id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', prompt: 'hi' }] },
+      ],
+    });
+    expect(() => preflight(cfg, buildDag(cfg), reg)).not.toThrow();
+  });
+
+  test('skips driver check for command-only tasks', () => {
+    const reg = new PluginRegistry(); // no drivers registered
+    const cfg = emptyConfig({
+      tracks: [
+        { id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', command: 'echo hi' }] },
+      ],
+    });
+    expect(() => preflight(cfg, buildDag(cfg), reg)).not.toThrow();
+  });
+});

package/src/core/preflight.ts

@@ -0,0 +1,89 @@
+import type { PipelineConfig, TaskConfig, DriverPlugin } from '../types';
+import type { Dag } from '../dag';
+import type { PluginRegistry } from '../registry';
+
+function isCommandOnly(
+  task: TaskConfig,
+): task is TaskConfig & { readonly command: string; readonly prompt?: undefined } {
+  return task.command !== undefined && task.prompt === undefined;
+}
+
+/**
+ * Validate that every plugin referenced by the pipeline (drivers,
+ * triggers, completions, middlewares) is registered, and that
+ * `continue_from` is only used between drivers that can hand off via
+ * sessionResume or text-injection. Throws with all errors aggregated
+ * into one message so the caller sees every misconfiguration in a
+ * single pass.
+ */
+export function preflight(
+  config: PipelineConfig,
+  dag: Dag,
+  registry: PluginRegistry,
+): void {
+  const errors: string[] = [];
+
+  for (const [, node] of dag.nodes) {
+    const task = node.task;
+    const track = node.track;
+    const driverName = task.driver ?? track.driver ?? config.driver ?? 'opencode';
+
+    const isCommand = isCommandOnly(task);
+
+    if (!isCommand && !registry.hasHandler('drivers', driverName)) {
+      errors.push(`Task "${node.taskId}": driver "${driverName}" not registered`);
+    }
+
+    if (task.trigger && !registry.hasHandler('triggers', task.trigger.type)) {
+      errors.push(
+        `Task "${node.taskId}": trigger type "${task.trigger.type}" not registered`,
+      );
+    }
+
+    if (task.completion && !registry.hasHandler('completions', task.completion.type)) {
+      errors.push(
+        `Task "${node.taskId}": completion type "${task.completion.type}" not registered`,
+      );
+    }
+
+    const mws = task.middlewares ?? track.middlewares ?? [];
+    for (const mw of mws) {
+      if (!registry.hasHandler('middlewares', mw.type)) {
+        errors.push(
+          `Task "${node.taskId}": middleware type "${mw.type}" not registered`,
+        );
+      }
+    }
+
+    if (task.continue_from && registry.hasHandler('drivers', driverName)) {
+      const driver = registry.getHandler<DriverPlugin>('drivers', driverName);
+      if (!driver.capabilities.sessionResume) {
+        const upstreamId = node.resolvedContinueFrom;
+        if (upstreamId) {
+          const upstream = dag.nodes.get(upstreamId);
+          if (upstream) {
+            const upstreamDriverName =
+              upstream.task.driver ?? upstream.track.driver ?? config.driver ?? 'opencode';
+            const upstreamDriver = registry.hasHandler('drivers', upstreamDriverName)
+              ? registry.getHandler<DriverPlugin>('drivers', upstreamDriverName)
+              : null;
+            const canNormalize = typeof upstreamDriver?.parseResult === 'function';
+
+            if (!canNormalize) {
+              errors.push(
+                `Task "${node.taskId}" uses continue_from: "${task.continue_from}", ` +
+                  `but upstream task "${upstreamId}" its driver ` +
+                  `does not implement parseResult for text-injection handoff. ` +
+                  `Use a driver with parseResult, or remove continue_from.`,
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Preflight validation failed:\n  - ${errors.join('\n  - ')}`);
+  }
+}

package/src/core/run-context.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, test } from 'bun:test';
+import { RunContext } from './run-context';
+import { buildDag } from '../dag';
+import type { PipelineConfig, RunEventPayload } from '../types';
+import type { PipelineInfo } from '../hooks';
+
+function makeContext(overrides: Partial<{
+  config: PipelineConfig;
+  onEvent: (e: RunEventPayload) => void;
+}> = {}): { ctx: RunContext; events: RunEventPayload[] } {
+  const config: PipelineConfig = overrides.config ?? {
+    name: 'p',
+    tracks: [
+      {
+        id: 't',
+        name: 'T',
+        tasks: [
+          { id: 'a', name: 'A', command: 'echo a' },
+          { id: 'b', name: 'B', command: 'echo b', depends_on: ['a'] },
+        ],
+      },
+    ],
+  };
+  const events: RunEventPayload[] = [];
+  const onEvent = overrides.onEvent ?? ((e: RunEventPayload) => { events.push(e); });
+  const ctx = new RunContext({
+    runId: 'run_test',
+    dag: buildDag(config),
+    config,
+    workDir: '/tmp/wd',
+    pipelineInfo: { name: config.name, run_id: 'run_test', started_at: '2026-04-26T00:00:00Z' } as PipelineInfo,
+    onEvent,
+  });
+  return { ctx, events };
+}
+
+describe('RunContext constructor', () => {
+  test('initializes one idle state per dag node', () => {
+    const { ctx } = makeContext();
+    expect(ctx.states.size).toBe(2);
+    expect(ctx.states.get('t.a')!.status).toBe('idle');
+    expect(ctx.states.get('t.b')!.status).toBe('idle');
+  });
+
+  test('initializes all state maps as empty', () => {
+    const { ctx } = makeContext();
+    expect(ctx.sessionMap.size).toBe(0);
+    expect(ctx.normalizedMap.size).toBe(0);
+    expect(ctx.outputValuesMap.size).toBe(0);
+    expect(ctx.bindingDataMap.size).toBe(0);
+    expect(ctx.resolvedInputsMap.size).toBe(0);
+  });
+
+  test('computes directDownstreams reverse adjacency from dag', () => {
+    const { ctx } = makeContext();
+    expect([...ctx.directDownstreams.get('t.a')!]).toEqual(['t.b']);
+    expect([...ctx.directDownstreams.get('t.b')!]).toEqual([]);
+  });
+
+  test('starts with abortReason null and a fresh AbortController', () => {
+    const { ctx } = makeContext();
+    expect(ctx.abortReason).toBeNull();
+    expect(ctx.abortController.signal.aborted).toBe(false);
+  });
+});
+
+describe('RunContext.emit', () => {
+  test('forwards events to onEvent', () => {
+    const { ctx, events } = makeContext();
+    ctx.emit({ type: 'run_end', runId: 'run_test', success: true, abortReason: null });
+    expect(events).toHaveLength(1);
+    expect(events[0]).toEqual({ type: 'run_end', runId: 'run_test', success: true, abortReason: null });
+  });
+
+  test('is a no-op when onEvent is undefined', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [{ id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', command: 'echo a' }] }],
+    };
+    const ctx = new RunContext({
+      runId: 'run_test',
+      dag: buildDag(config),
+      config,
+      workDir: '/tmp/wd',
+      pipelineInfo: { name: 'p', run_id: 'run_test', started_at: 'now' } as PipelineInfo,
+    });
+    expect(() => ctx.emit({ type: 'run_end', runId: 'run_test', success: true, abortReason: null })).not.toThrow();
+  });
+});
+
+describe('RunContext.setTaskStatus', () => {
+  test('transitions a non-terminal task and emits task_update', () => {
+    const { ctx, events } = makeContext();
+    ctx.setTaskStatus('t.a', 'waiting');
+    expect(ctx.states.get('t.a')!.status).toBe('waiting');
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe('task_update');
+    if (events[0].type === 'task_update') {
+      expect(events[0].taskId).toBe('t.a');
+      expect(events[0].status).toBe('waiting');
+    }
+  });
+
+  test('refuses to re-transition a terminal task (terminal lock)', () => {
+    const { ctx, events } = makeContext();
+    ctx.setTaskStatus('t.a', 'success');
+    events.length = 0;
+    ctx.setTaskStatus('t.a', 'failed');
+    expect(ctx.states.get('t.a')!.status).toBe('success');
+    expect(events).toHaveLength(0);
+  });
+
+  test('echoes resolvedInputs and outputs from the maps in the emitted event', () => {
+    const { ctx, events } = makeContext();
+    ctx.resolvedInputsMap.set('t.a', { x: 1 });
+    ctx.outputValuesMap.set('t.a', { y: 2 });
+    ctx.setTaskStatus('t.a', 'running');
+    if (events[0].type === 'task_update') {
+      expect(events[0].inputs).toEqual({ x: 1 });
+      expect(events[0].outputs).toEqual({ y: 2 });
+    } else {
+      throw new Error('expected task_update');
+    }
+  });
+});
+
+describe('RunContext.getOnFailure', () => {
+  test('returns the track-level on_failure setting', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          on_failure: 'stop_all',
+          tasks: [{ id: 'a', name: 'A', command: 'echo a' }],
+        },
+      ],
+    };
+    const { ctx } = makeContext({ config });
+    expect(ctx.getOnFailure('t.a')).toBe('stop_all');
+  });
+
+  test('defaults to skip_downstream when track does not specify', () => {
+    const { ctx } = makeContext();
+    expect(ctx.getOnFailure('t.a')).toBe('skip_downstream');
+  });
+});
+
+describe('RunContext.isDependencySatisfied', () => {
+  test('returns satisfied for success', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'success';
+    expect(ctx.isDependencySatisfied('t.a')).toBe('satisfied');
+  });
+
+  test('returns skip for skipped', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'skipped';
+    expect(ctx.isDependencySatisfied('t.a')).toBe('skip');
+  });
+
+  test('returns skip for failed under default policy, satisfied under ignore', () => {
+    const cfgSkip: PipelineConfig = {
+      name: 'p',
+      tracks: [{ id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', command: 'echo a' }] }],
+    };
+    const cfgIgnore: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          on_failure: 'ignore',
+          tasks: [{ id: 'a', name: 'A', command: 'echo a' }],
+        },
+      ],
+    };
+    const a = makeContext({ config: cfgSkip }).ctx;
+    a.states.get('t.a')!.status = 'failed';
+    expect(a.isDependencySatisfied('t.a')).toBe('skip');
+
+    const b = makeContext({ config: cfgIgnore }).ctx;
+    b.states.get('t.a')!.status = 'failed';
+    expect(b.isDependencySatisfied('t.a')).toBe('satisfied');
+  });
+
+  test('returns unsatisfied for non-terminal statuses', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'running';
+    expect(ctx.isDependencySatisfied('t.a')).toBe('unsatisfied');
+  });
+});
+
+describe('RunContext.applyStopAll', () => {
+  test('aborts the controller, sets abortReason, marks waiting tasks as skipped', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'waiting';
+    ctx.states.get('t.b')!.status = 'waiting';
+    ctx.applyStopAll();
+    expect(ctx.abortReason).toBe('stop_all');
+    expect(ctx.abortController.signal.aborted).toBe(true);
+    expect(ctx.states.get('t.a')!.status).toBe('skipped');
+    expect(ctx.states.get('t.b')!.status).toBe('skipped');
+  });
+
+  test('does not overwrite an existing abortReason', () => {
+    const { ctx } = makeContext();
+    ctx.abortReason = 'timeout';
+    ctx.applyStopAll();
+    expect(ctx.abortReason).toBe('timeout');
+    expect(ctx.abortController.signal.aborted).toBe(true);
+  });
+
+  test('leaves running and terminal tasks alone', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'running';
+    ctx.states.get('t.b')!.status = 'success';
+    ctx.applyStopAll();
+    expect(ctx.states.get('t.a')!.status).toBe('running');
+    expect(ctx.states.get('t.b')!.status).toBe('success');
+  });
+});
+
+describe('RunContext.buildTaskInfoObj / trackInfoOf', () => {
+  test('buildTaskInfoObj reports type=command for command tasks', () => {
+    const { ctx } = makeContext();
+    expect(ctx.buildTaskInfoObj('t.a').type).toBe('command');
+  });
+
+  test('buildTaskInfoObj reports type=ai for prompt tasks', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [{ id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', prompt: 'hi' }] }],
+    };
+    const { ctx } = makeContext({ config });
+    expect(ctx.buildTaskInfoObj('t.a').type).toBe('ai');
+  });
+
+  test('trackInfoOf returns the track id and name', () => {
+    const { ctx } = makeContext();
+    expect(ctx.trackInfoOf('t.a')).toEqual({ id: 't', name: 'T' });
+  });
+});

package/src/core/run-context.ts

@@ -0,0 +1,207 @@
+import type {
+  AbortReason,
+  OnFailure,
+  Permissions,
+  PipelineConfig,
+  RunEventPayload,
+  TaskConfig,
+  TaskState,
+  TaskStatus,
+} from '../types';
+import type { Dag } from '../dag';
+import type { UpstreamBindingData } from '../ports';
+import {
+  executeHook,
+  buildTaskContext,
+  type PipelineInfo,
+  type TaskInfo,
+  type TrackInfo,
+} from '../hooks';
+import { isTerminal } from './run-state';
+import { nowISO } from '../utils';
+
+function isPromptTaskConfig(
+  task: TaskConfig,
+): task is TaskConfig & { readonly prompt: string; readonly command?: undefined } {
+  return task.prompt !== undefined && task.command === undefined;
+}
+
+export interface RunContextOptions {
+  readonly runId: string;
+  readonly dag: Dag;
+  readonly config: PipelineConfig;
+  readonly workDir: string;
+  readonly pipelineInfo: PipelineInfo;
+  readonly onEvent?: (event: RunEventPayload) => void;
+}
+
+/**
+ * Per-run state container. Owns the maps and abort tracking that
+ * `runPipeline` previously held as closure locals, plus the small
+ * methods that read/write that state. Scheduler, dataflow, and
+ * task-executor extractions in later phases pass `ctx` instead of
+ * relying on closure capture.
+ */
+export class RunContext {
+  readonly runId: string;
+  readonly dag: Dag;
+  readonly config: PipelineConfig;
+  readonly workDir: string;
+  readonly pipelineInfo: PipelineInfo;
+  readonly onEvent?: (event: RunEventPayload) => void;
+
+  readonly states = new Map<string, TaskState>();
+  readonly sessionMap = new Map<string, string>();
+  readonly normalizedMap = new Map<string, string>();
+  readonly outputValuesMap = new Map<string, Readonly<Record<string, unknown>>>();
+  readonly bindingDataMap = new Map<string, UpstreamBindingData>();
+  readonly resolvedInputsMap = new Map<string, Readonly<Record<string, unknown>>>();
+  readonly directDownstreams: Map<string, string[]>;
+  readonly abortController = new AbortController();
+  abortReason: AbortReason | null = null;
+
+  constructor(options: RunContextOptions) {
+    this.runId = options.runId;
+    this.dag = options.dag;
+    this.config = options.config;
+    this.workDir = options.workDir;
+    this.pipelineInfo = options.pipelineInfo;
+    this.onEvent = options.onEvent;
+
+    for (const [id, node] of this.dag.nodes) {
+      this.states.set(id, {
+        config: node.task,
+        trackConfig: node.track,
+        status: 'idle',
+        result: null,
+        startedAt: null,
+        finishedAt: null,
+      });
+    }
+
+    this.directDownstreams = new Map<string, string[]>();
+    for (const [id] of this.dag.nodes) this.directDownstreams.set(id, []);
+    for (const [id, node] of this.dag.nodes) {
+      for (const upstream of node.dependsOn) {
+        const list = this.directDownstreams.get(upstream);
+        if (list) list.push(id);
+      }
+    }
+  }
+
+  emit(event: RunEventPayload): void {
+    this.onEvent?.(event);
+  }
+
+  setTaskStatus(taskId: string, newStatus: TaskStatus): void {
+    const state = this.states.get(taskId)!;
+    // Terminal lock: once a task reaches a terminal state it must not be
+    // re-transitioned. This prevents stop_all from marking running tasks as
+    // skipped and then having their in-flight processTask promise overwrite
+    // that with success/failed, producing an invalid double transition.
+    if (isTerminal(state.status)) return;
+    state.status = newStatus;
+    const result = state.result;
+    const cfg = state.config;
+    this.emit({
+      type: 'task_update',
+      runId: this.runId,
+      taskId,
+      status: newStatus,
+      startedAt: state.startedAt ?? undefined,
+      finishedAt: state.finishedAt ?? undefined,
+      durationMs: result?.durationMs,
+      exitCode: result?.exitCode,
+      stdout: result?.stdout,
+      stderr: result?.stderr,
+      stdoutPath: result?.stdoutPath ?? null,
+      stderrPath: result?.stderrPath ?? null,
+      stdoutBytes: result?.stdoutBytes ?? null,
+      stderrBytes: result?.stderrBytes ?? null,
+      sessionId: result?.sessionId ?? null,
+      normalizedOutput: result?.normalizedOutput ?? null,
+      inputs: this.resolvedInputsMap.get(taskId) ?? null,
+      outputs: this.outputValuesMap.get(taskId) ?? null,
+      resolvedDriver: cfg.driver ?? null,
+      resolvedModel: cfg.model ?? null,
+      resolvedPermissions: (cfg.permissions as Permissions | undefined) ?? null,
+    });
+  }
+
+  getOnFailure(taskId: string): OnFailure {
+    return this.dag.nodes.get(taskId)?.track.on_failure ?? 'skip_downstream';
+  }
+
+  isDependencySatisfied(depId: string): 'satisfied' | 'unsatisfied' | 'skip' {
+    const depState = this.states.get(depId);
+    if (!depState) return 'skip';
+    switch (depState.status) {
+      case 'success':
+        return 'satisfied';
+      case 'skipped':
+        return 'skip';
+      case 'failed':
+      case 'timeout':
+      case 'blocked':
+        return this.getOnFailure(depId) === 'ignore' ? 'satisfied' : 'skip';
+      default:
+        return 'unsatisfied';
+    }
+  }
+
+  /**
+   * H3: stop_all marks every still-waiting task across every track as
+   * skipped and aborts in-flight tasks via the shared signal. The
+   * terminal lock in setTaskStatus prevents any later re-transition
+   * should a completed running task try to overwrite the skipped state.
+   */
+  applyStopAll(): void {
+    if (this.abortReason === null) this.abortReason = 'stop_all';
+    this.abortController.abort();
+    for (const [id, state] of this.states) {
+      if (state.status === 'waiting') {
+        state.finishedAt = nowISO();
+        this.setTaskStatus(id, 'skipped');
+      }
+    }
+  }
+
+  buildTaskInfoObj(taskId: string): TaskInfo {
+    const state = this.states.get(taskId)!;
+    return {
+      id: taskId,
+      name: state.config.name,
+      type: isPromptTaskConfig(state.config) ? 'ai' : 'command',
+      status: state.status,
+      exit_code: state.result?.exitCode ?? null,
+      duration_ms: state.result?.durationMs ?? null,
+      stderr_path: state.result?.stderrPath ?? null,
+      session_id: state.result?.sessionId ?? null,
+      started_at: state.startedAt,
+      finished_at: state.finishedAt,
+    };
+  }
+
+  trackInfoOf(taskId: string): TrackInfo {
+    const node = this.dag.nodes.get(taskId)!;
+    return { id: node.track.id, name: node.track.name };
+  }
+
+  async fireHook(
+    taskId: string,
+    event: 'task_success' | 'task_failure',
+  ): Promise<void> {
+    await executeHook(
+      this.config.hooks,
+      event,
+      buildTaskContext(
+        event,
+        this.pipelineInfo,
+        this.trackInfoOf(taskId),
+        this.buildTaskInfoObj(taskId),
+      ),
+      this.workDir,
+      this.abortController.signal,
+    );
+  }
+}