@tagma/sdk 0.2.5 → 0.2.7

package/README.md

@@ -118,7 +118,6 @@ pipeline:
           trigger:
             type: manual
             message: "Approve before running"
-            options: [approve, reject]
             timeout: 5m
           completion:
             type: exit_code
@@ -224,7 +223,6 @@ Track-level `middlewares` apply to all tasks in the track. Setting task-level `m
 |---|---|---|---|---|
 | `type` | `"manual"` | Yes | — | Trigger type |
 | `message` | `string` | No | `"Manual confirmation required for task \"{taskId}\""` | Message shown to the approver |
-| `options` | `string[]` | No | — | Choice options (e.g. `[approve, reject]`) |
 | `timeout` | `string` | No | — | How long to wait for a decision before timing out |
 | `metadata` | `object` | No | — | Arbitrary metadata passed to the approval gateway |
 
@@ -296,7 +294,9 @@ Options:
 - `onEvent` -- callback for real-time `PipelineEvent` updates:
   - `pipeline_start` — pipeline began; includes `states: ReadonlyMap<taskId, TaskState>` (initial snapshot of all tasks at `waiting`)
   - `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`
@@ -436,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`
 
@@ -470,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).
 
@@ -506,9 +506,32 @@ logger.warn('[track]', 'message');   // console + file
 logger.error('[track]', 'message');  // console + file
 logger.debug('[track]', 'message');  // file only
 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.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
+structured `LogRecord` — `runPipeline` uses this to emit `task_log` events:
+
+```ts
+import { Logger, type LogRecord } from '@tagma/sdk';
+
+const logger = new Logger(workDir, runId, (record: LogRecord) => {
+  // record = { level, taskId, timestamp, text }
+  // level  = 'info' | 'warn' | 'error' | 'debug' | 'section' | 'quiet'
+  // taskId is extracted from a '[task:<id>]' prefix, or null for untagged lines
+  forwardToUI(record);
+});
+```
+
+`section` and `quiet` carry no prefix, so pass an explicit `taskId` when the
+line logically belongs to a task — the extractor cannot infer one otherwise:
+
+```ts
+logger.section(`Task ${taskId}`, taskId);
+logger.quiet(`--- stdout (${taskId}) ---\n${body}\n--- end stdout ---`, taskId);
 ```
 
 ### `tailLines(text: string, n: number): string`

package/package.json

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

package/src/adapters/stdin-approval.ts

@@ -43,34 +43,23 @@ export function attachStdinApprovalAdapter(gateway: ApprovalGateway): StdinAppro
         // If the request was already resolved by another path while queued, skip it.
         if (!gateway.pending().some((p) => p.id === req.id)) continue;
 
-        const optionsStr = req.options.join(' / ');
         process.stdout.write(
           `\n[APPROVAL REQUIRED] ${req.message}\n` +
             `  id:      ${req.id}\n` +
             `  task:    ${req.taskId}${req.trackId ? ` (track: ${req.trackId})` : ''}\n` +
-            `  options: ${optionsStr}\n` +
-            `  > `,
+            `  approve / reject > `,
         );
 
         const input = (await readOneLine()).trim().toLowerCase();
 
         const approveAliases = new Set(['approve', 'yes', 'y', 'ok', 'true', '1']);
         const rejectAliases = new Set(['reject', 'no', 'n', 'deny', 'false', '0']);
-        const matchedOption = req.options.find((o) => o.toLowerCase() === input);
 
-        if (matchedOption) {
-          const isReject = rejectAliases.has(matchedOption.toLowerCase());
-          gateway.resolve(req.id, {
-            outcome: isReject ? 'rejected' : 'approved',
-            choice: matchedOption,
-            actor: 'cli',
-          });
-        } else if (approveAliases.has(input)) {
-          gateway.resolve(req.id, { outcome: 'approved', choice: input, actor: 'cli' });
+        if (approveAliases.has(input)) {
+          gateway.resolve(req.id, { outcome: 'approved', actor: 'cli' });
         } else if (rejectAliases.has(input)) {
           gateway.resolve(req.id, {
             outcome: 'rejected',
-            choice: input,
             actor: 'cli',
             reason: 'user rejected via CLI',
           });

package/src/adapters/websocket-approval.ts

@@ -16,7 +16,7 @@ import type { ApprovalGateway, ApprovalEvent } from '../approval';
 //
 // Protocol — client → server:
 //   { type: 'resolve', approvalId: string, outcome: 'approved'|'rejected',
-//     choice?: string, actor?: string, reason?: string }
+//     actor?: string, reason?: string }
 
 export interface WebSocketApprovalAdapterOptions {
   port?: number;      // default: 3000
@@ -123,7 +123,6 @@ export function attachWebSocketApprovalAdapter(
 
         const ok = gateway.resolve(msg.approvalId, {
           outcome: msg.outcome,
-          choice: msg.choice,
           actor: msg.actor ?? 'websocket',
           reason: msg.reason,
         });
@@ -159,7 +158,6 @@ interface ResolveMessage {
   type: 'resolve';
   approvalId: string;
   outcome: 'approved' | 'rejected';
-  choice?: string;
   actor?: string;
   reason?: string;
 }

package/src/approval.ts

@@ -16,9 +16,6 @@ export type {
   ApprovalListener, ApprovalGateway,
 } from '@tagma/types';
 
-// Default options presented to the approver when the caller does not specify any.
-const DEFAULT_APPROVAL_OPTIONS = ['approve', 'reject'] as const;
-
 // ═══ Default In-Memory Implementation ═══
 
 interface PendingEntry {
@@ -32,7 +29,7 @@ export class InMemoryApprovalGateway implements ApprovalGateway {
   private readonly listeners = new Set<ApprovalListener>();
 
   request(
-    req: Omit<ApprovalRequest, 'id' | 'createdAt' | 'options'> & { options?: readonly string[] },
+    req: Omit<ApprovalRequest, 'id' | 'createdAt'>,
   ): Promise<ApprovalDecision> {
     const full: ApprovalRequest = {
       id: randomUUID(),
@@ -40,7 +37,6 @@ export class InMemoryApprovalGateway implements ApprovalGateway {
       taskId: req.taskId,
       trackId: req.trackId,
       message: req.message,
-      options: req.options && req.options.length > 0 ? req.options : DEFAULT_APPROVAL_OPTIONS,
       timeoutMs: req.timeoutMs,
       metadata: req.metadata,
     };
@@ -80,7 +76,6 @@ export class InMemoryApprovalGateway implements ApprovalGateway {
     const full: ApprovalDecision = {
       approvalId,
       outcome: decision.outcome,
-      choice: decision.choice,
       actor: decision.actor,
       reason: decision.reason,
       decidedAt: nowISO(),

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/engine.ts

@@ -16,7 +16,7 @@ import {
   buildPipelineCompleteContext, buildPipelineErrorContext,
   type PipelineInfo, type TrackInfo, type TaskInfo,
 } from './hooks';
-import { Logger, tailLines, clip } from './logger';
+import { Logger, tailLines, clip, type LogLevel } from './logger';
 import { InMemoryApprovalGateway, type ApprovalGateway } from './approval';
 
 // ═══ Preflight Validation ═══
@@ -115,7 +115,15 @@ export interface EngineResult {
 export type PipelineEvent =
   | { readonly type: 'task_status_change'; readonly taskId: string; readonly status: TaskStatus; readonly prevStatus: TaskStatus; readonly runId: string; readonly state: TaskState }
   | { readonly type: 'pipeline_start'; readonly runId: string; readonly states: ReadonlyMap<string, TaskState> }
-  | { readonly type: 'pipeline_end'; readonly runId: string; readonly success: boolean };
+  | { readonly type: 'pipeline_end'; readonly runId: string; readonly success: boolean }
+  /**
+   * Fine-grained log line emitted alongside every write to pipeline.log.
+   * Consumers use this to stream the full run process into UIs without
+   * tailing the log file. `taskId` is non-null for task-scoped lines and
+   * null for pipeline-wide messages (e.g. configuration dumps, DAG
+   * topology, pipeline start/end).
+   */
+  | { readonly type: 'task_log'; readonly runId: string; readonly taskId: string | null; readonly level: LogLevel; readonly timestamp: string; readonly text: string };
 
 export interface RunPipelineOptions {
   readonly approvalGateway?: ApprovalGateway;
@@ -124,6 +132,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.
@@ -155,12 +169,24 @@ export async function runPipeline(
   }
 
   const dag = buildDag(config);
-  const runId = generateRunId();
+  const runId = options.runId ?? generateRunId();
   preflight(config, dag);
 
   const startedAt = nowISO();
   const pipelineInfo: PipelineInfo = { name: config.name, run_id: runId, started_at: startedAt };
-  const log = new Logger(workDir, runId);
+  // Forward every structured log line to subscribers as task_log events.
+  // Reading options.onEvent inside the callback (vs. capturing it once) keeps
+  // the SDK behavior correct if callers pass a fresh onEvent on each run.
+  const log = new Logger(workDir, runId, (record) => {
+    options.onEvent?.({
+      type: 'task_log',
+      runId,
+      taskId: record.taskId,
+      level: record.level,
+      timestamp: record.timestamp,
+      text: record.text,
+    });
+  });
   log.info('[pipeline]', `start "${config.name}" run_id=${runId}`);
 
   // File-only: dump the resolved pipeline shape + DAG topology for post-mortem.
@@ -352,7 +378,7 @@ export async function runPipeline(
     const task = node.task;
     const track = node.track;
 
-    log.section(`Task ${taskId}`);
+    log.section(`Task ${taskId}`, taskId);
     log.debug(`[task:${taskId}]`,
       `type=${task.prompt ? 'ai' : 'cmd'} track=${track.id} deps=[${node.dependsOn.join(', ') || '(root)'}]`);
 
@@ -469,7 +495,7 @@ export async function runPipeline(
         }
         log.debug(`[task:${taskId}]`,
           `prompt: ${originalLen} chars (final: ${prompt.length} chars)`);
-        log.quiet(`--- prompt (final) ---\n${clip(prompt)}\n--- end prompt ---`);
+        log.quiet(`--- prompt (final) ---\n${clip(prompt)}\n--- end prompt ---`, taskId);
 
         const enrichedTask: TaskConfig = { ...task, prompt };
         const driverCtx: DriverContext = {
@@ -565,10 +591,10 @@ export async function runPipeline(
         log.debug(`[task:${taskId}]`, `wrote stderr: ${result.stderrPath}`);
       }
       if (result.stdout) {
-        log.quiet(`--- stdout (${taskId}) ---\n${clip(result.stdout)}\n--- end stdout ---`);
+        log.quiet(`--- stdout (${taskId}) ---\n${clip(result.stdout)}\n--- end stdout ---`, taskId);
       }
       if (result.stderr) {
-        log.quiet(`--- stderr (${taskId}) ---\n${clip(result.stderr)}\n--- end stderr ---`);
+        log.quiet(`--- stderr (${taskId}) ---\n${clip(result.stderr)}\n--- end stderr ---`, taskId);
       }
       if (task.completion) {
         log.debug(`[task:${taskId}]`,
@@ -703,6 +729,8 @@ export async function runPipeline(
   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/logger.ts

@@ -1,112 +1,177 @@
-import { resolve, dirname } from 'node:path';
-import { mkdirSync, appendFileSync, writeFileSync } from 'node:fs';
-
-/**
- * Dual-channel logger.
- *
- *   - `info/warn/error` → console AND file (brief, user-visible events)
- *   - `debug`           → file ONLY (verbose diagnostics)
- *   - `section`         → file ONLY (visual separators)
- *   - `quiet`           → file ONLY (bulk payload like full stdout dumps)
- *
- * Log file path: <workDir>/.tagma/logs/<runId>/pipeline.log (one file per pipeline run,
- * truncated on construction).
- */
-export class Logger {
-  private readonly filePath: string;
-  private readonly runDir: string;
-
-  constructor(workDir: string, runId: string) {
-    this.runDir = resolve(workDir, '.tagma', 'logs', runId);
-    this.filePath = resolve(this.runDir, 'pipeline.log');
-    mkdirSync(dirname(this.filePath), { recursive: true });
-    writeFileSync(
-      this.filePath,
-      `# Pipeline run ${runId} @ ${new Date().toISOString()}\n` +
-      `# Host: ${process.platform} ${process.arch}  Bun: ${process.versions.bun ?? 'n/a'}\n` +
-      `# Work dir: ${workDir}\n\n`,
-    );
-  }
-
-  info(prefix: string, message: string): void {
-    const line = `${timestamp()} ${prefix} ${message}`;
-    console.log(line);
-    this.append(line);
-  }
-
-  warn(prefix: string, message: string): void {
-    const line = `${timestamp()} ${prefix} WARN: ${message}`;
-    console.warn(line);
-    this.append(line);
-  }
-
-  error(prefix: string, message: string): void {
-    const line = `${timestamp()} ${prefix} ERROR: ${message}`;
-    console.error(line);
-    this.append(line);
-  }
-
-  /** File-only diagnostic log line. */
-  debug(prefix: string, message: string): void {
-    this.append(`${timestamp()} ${prefix} DEBUG: ${message}`);
-  }
-
-  /** File-only visual separator with title. */
-  section(title: string): void {
-    this.append(`\n━━━ ${title} ━━━`);
-  }
-
-  /** File-only bulk payload (e.g. full stdout / stderr dumps). */
-  quiet(message: string): void {
-    this.append(message);
-  }
-
-  private append(line: string): void {
-    try {
-      appendFileSync(this.filePath, line.endsWith('\n') ? line : line + '\n');
-    } catch {
-      // Swallow log write failures; engine correctness shouldn't depend on logging.
-    }
-  }
-
-  get path(): string {
-    return this.filePath;
-  }
-
-  /** Directory that holds all artifacts for this run (pipeline.log, *.stderr, etc.). */
-  get dir(): string {
-    return this.runDir;
-  }
-}
-
-function timestamp(): string {
-  const d = new Date();
-  const hh = String(d.getHours()).padStart(2, '0');
-  const mm = String(d.getMinutes()).padStart(2, '0');
-  const ss = String(d.getSeconds()).padStart(2, '0');
-  const ms = String(d.getMilliseconds()).padStart(3, '0');
-  return `${hh}:${mm}:${ss}.${ms}`;
-}
-
-/** Return the last `n` non-empty lines of `text`, joined with newlines. */
-export function tailLines(text: string, n: number): string {
-  if (!text) return '';
-  const lines = text.split(/\r?\n/).filter(l => l.length > 0);
-  return lines.slice(-n).join('\n');
-}
-
-/**
- * Truncate a blob to at most `maxBytes` UTF-8 bytes for log embedding,
- * appending a marker when truncation occurred.
- * Uses TextEncoder so CJK and emoji (multi-byte) characters are counted correctly.
- */
-export function clip(text: string, maxBytes = 16 * 1024): string {
-  if (!text) return '';
-  const encoder = new TextEncoder();
-  const bytes = encoder.encode(text);
-  if (bytes.length <= maxBytes) return text;
-  const omittedBytes = bytes.length - maxBytes;
-  // TextDecoder handles partial code-point boundaries safely (replacement char insertion)
-  const truncated = new TextDecoder().decode(bytes.slice(0, maxBytes));
-  return truncated + `\n…[truncated ${omittedBytes} bytes]`;
-}
+import { resolve, dirname } from 'node:path';
+import { mkdirSync, writeFileSync, openSync, writeSync, closeSync } from 'node:fs';
+
+/**
+ * Structured record emitted for every log line. Consumers (e.g. the editor
+ * server) use this to stream process-level detail into UIs alongside the
+ * on-disk pipeline.log. `taskId` is extracted from a `[task:<id>]` prefix
+ * when the call site passes one, or overridden explicitly via the optional
+ * `taskId` argument on `section`/`quiet` (which carry no prefix).
+ */
+export type LogLevel = 'info' | 'warn' | 'error' | 'debug' | 'section' | 'quiet';
+
+export interface LogRecord {
+  readonly level: LogLevel;
+  readonly taskId: string | null;
+  readonly timestamp: string;
+  readonly text: string;
+}
+
+export type LogListener = (record: LogRecord) => void;
+
+const TASK_PREFIX_RE = /\[task:([^\]]+)\]/;
+
+function taskIdFromPrefix(prefix: string): string | null {
+  const m = TASK_PREFIX_RE.exec(prefix);
+  return m ? m[1] : null;
+}
+
+/**
+ * Dual-channel logger.
+ *
+ *   - `info/warn/error` → console AND file (brief, user-visible events)
+ *   - `debug`           → file ONLY (verbose diagnostics)
+ *   - `section`         → file ONLY (visual separators)
+ *   - `quiet`           → file ONLY (bulk payload like full stdout dumps)
+ *
+ * Log file path: <workDir>/.tagma/logs/<runId>/pipeline.log (one file per pipeline run,
+ * truncated on construction). Every line is also forwarded to the optional
+ * `onLine` callback as a structured `LogRecord`, so callers that want to
+ * stream the run process over IPC/SSE don't need to tail the file.
+ */
+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 });
+    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`;
+    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 {
+    const ts = timestamp();
+    const line = `${ts} ${prefix} ${message}`;
+    console.log(line);
+    this.emit('info', ts, line, taskIdFromPrefix(prefix));
+    this.append(line);
+  }
+
+  warn(prefix: string, message: string): void {
+    const ts = timestamp();
+    const line = `${ts} ${prefix} WARN: ${message}`;
+    console.warn(line);
+    this.emit('warn', ts, line, taskIdFromPrefix(prefix));
+    this.append(line);
+  }
+
+  error(prefix: string, message: string): void {
+    const ts = timestamp();
+    const line = `${ts} ${prefix} ERROR: ${message}`;
+    console.error(line);
+    this.emit('error', ts, line, taskIdFromPrefix(prefix));
+    this.append(line);
+  }
+
+  /** File-only diagnostic log line. */
+  debug(prefix: string, message: string): void {
+    const ts = timestamp();
+    const line = `${ts} ${prefix} DEBUG: ${message}`;
+    this.emit('debug', ts, line, taskIdFromPrefix(prefix));
+    this.append(line);
+  }
+
+  /** File-only visual separator with title. */
+  section(title: string, taskId?: string | null): void {
+    const ts = timestamp();
+    const text = `\n━━━ ${title} ━━━`;
+    this.emit('section', ts, text, taskId ?? null);
+    this.append(text);
+  }
+
+  /** File-only bulk payload (e.g. full stdout / stderr dumps). */
+  quiet(message: string, taskId?: string | null): void {
+    const ts = timestamp();
+    this.emit('quiet', ts, message, taskId ?? null);
+    this.append(message);
+  }
+
+  private append(line: string): void {
+    if (this.fd === null) return;
+    try {
+      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 {
+      this.onLine({ level, taskId, timestamp: ts, text });
+    } catch {
+      // Never let a listener error derail the pipeline.
+    }
+  }
+
+  get path(): string {
+    return this.filePath;
+  }
+
+  /** Directory that holds all artifacts for this run (pipeline.log, *.stderr, etc.). */
+  get dir(): string {
+    return this.runDir;
+  }
+}
+
+function timestamp(): string {
+  const d = new Date();
+  const hh = String(d.getHours()).padStart(2, '0');
+  const mm = String(d.getMinutes()).padStart(2, '0');
+  const ss = String(d.getSeconds()).padStart(2, '0');
+  const ms = String(d.getMilliseconds()).padStart(3, '0');
+  return `${hh}:${mm}:${ss}.${ms}`;
+}
+
+/** Return the last `n` non-empty lines of `text`, joined with newlines. */
+export function tailLines(text: string, n: number): string {
+  if (!text) return '';
+  const lines = text.split(/\r?\n/).filter(l => l.length > 0);
+  return lines.slice(-n).join('\n');
+}
+
+/**
+ * Truncate a blob to at most `maxBytes` UTF-8 bytes for log embedding,
+ * appending a marker when truncation occurred.
+ * Uses TextEncoder so CJK and emoji (multi-byte) characters are counted correctly.
+ */
+export function clip(text: string, maxBytes = 16 * 1024): string {
+  if (!text) return '';
+  const encoder = new TextEncoder();
+  const bytes = encoder.encode(text);
+  if (bytes.length <= maxBytes) return text;
+  const omittedBytes = bytes.length - maxBytes;
+  // TextDecoder handles partial code-point boundaries safely (replacement char insertion)
+  const truncated = new TextDecoder().decode(bytes.slice(0, maxBytes));
+  return truncated + `\n…[truncated ${omittedBytes} bytes]`;
+}

package/src/middlewares/static-context.ts

@@ -1,45 +1,45 @@
-import { basename } from 'path';
-import type { MiddlewarePlugin, MiddlewareContext } from '../types';
-import { validatePath } from '../utils';
-
-export const StaticContextMiddleware: MiddlewarePlugin = {
-  name: 'static_context',
-  schema: {
-    description: 'Prepend a reference file to the prompt as static context.',
-    fields: {
-      file: {
-        type: 'path',
-        required: true,
-        description: 'Path to the reference file (relative to workDir or absolute).',
-        placeholder: 'docs/spec.md',
-      },
-      label: {
-        type: 'string',
-        description: 'Header shown before the content. Defaults to "Reference: <basename>".',
-        placeholder: 'Reference: spec.md',
-      },
-    },
-  },
-
-  async enhance(
-    prompt: string,
-    config: Record<string, unknown>,
-    ctx: MiddlewareContext,
-  ): Promise<string> {
-    const filePath = config.file as string;
-    if (!filePath) throw new Error('static_context middleware: "file" is required');
-
-    const safePath = validatePath(filePath, ctx.workDir);
-    const file = Bun.file(safePath);
-
-    if (!(await file.exists())) {
-      console.warn(`static_context: file ${filePath} not found, skipping`);
-      return prompt;
-    }
-
-    const content = await file.text();
-    const label = (config.label as string) ?? `Reference: ${basename(filePath)}`;
-
-    return `[${label}]\n${content}\n\n[Task]\n${prompt}`;
-  },
-};
+import { basename } from 'path';
+import type { MiddlewarePlugin, MiddlewareContext } from '../types';
+import { validatePath } from '../utils';
+
+export const StaticContextMiddleware: MiddlewarePlugin = {
+  name: 'static_context',
+  schema: {
+    description: 'Prepend a reference file to the prompt as static context.',
+    fields: {
+      file: {
+        type: 'path',
+        required: true,
+        description: 'Path to the reference file (relative to workDir or absolute).',
+        placeholder: 'docs/spec.md',
+      },
+      label: {
+        type: 'string',
+        description: 'Header shown before the content. Defaults to "Reference: <basename>".',
+        placeholder: 'Reference: spec.md',
+      },
+    },
+  },
+
+  async enhance(
+    prompt: string,
+    config: Record<string, unknown>,
+    ctx: MiddlewareContext,
+  ): Promise<string> {
+    const filePath = config.file as string;
+    if (!filePath) throw new Error('static_context middleware: "file" is required');
+
+    const safePath = validatePath(filePath, ctx.workDir);
+    const file = Bun.file(safePath);
+
+    if (!(await file.exists())) {
+      console.warn(`static_context: file ${filePath} not found, skipping`);
+      return prompt;
+    }
+
+    const content = await file.text();
+    const label = (config.label as string) ?? `Reference: ${basename(filePath)}`;
+
+    return `[${label}]\n${content}\n\n[Task]\n${prompt}`;
+  },
+};

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 */
   }
@@ -140,6 +147,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 +173,10 @@ export async function runSpawn(
   };
 
   if (timeoutMs && timeoutMs > 0) {
-    timer = setTimeout(killGracefully, timeoutMs);
+    timer = setTimeout(() => {
+      timedOut = true;
+      killGracefully();
+    }, timeoutMs);
   }
 
   const onAbort = () => killGracefully();
@@ -197,8 +208,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 };

package/src/sdk.ts

@@ -63,6 +63,7 @@ export type { WebSocketApprovalAdapter, WebSocketApprovalAdapterOptions } from '
 
 // ── Logger ──
 export { Logger, tailLines, clip } from './logger';
+export type { LogRecord, LogLevel, LogListener } from './logger';
 
 // ── Hook context types (useful for frontend display) ──
 export type { HookResult, PipelineInfo, TrackInfo, TaskInfo } from './hooks';

package/src/triggers/manual.ts

@@ -16,11 +16,6 @@ export const ManualTrigger: TriggerPlugin = {
         description: 'Maximum wait time (e.g. 10m). Omit or 0 to wait indefinitely.',
         placeholder: '10m',
       },
-      options: {
-        type: 'string',
-        description: 'Comma-separated list of choices offered to the approver (e.g. "yes,no,defer").',
-        placeholder: 'yes,no',
-      },
     },
   },
 
@@ -28,9 +23,6 @@ export const ManualTrigger: TriggerPlugin = {
     const message =
       (config.message as string | undefined) ?? `Manual confirmation required for task "${ctx.taskId}"`;
     const timeoutMs = config.timeout ? parseDuration(config.timeout as string) : 0;
-    const options = Array.isArray(config.options)
-      ? (config.options as unknown[]).map(String)
-      : undefined;
     const metadata =
       config.metadata && typeof config.metadata === 'object'
         ? (config.metadata as Record<string, unknown>)
@@ -40,7 +32,6 @@ export const ManualTrigger: TriggerPlugin = {
       taskId: ctx.taskId,
       trackId: ctx.trackId,
       message,
-      options,
       timeoutMs,
       metadata,
     });
@@ -66,7 +57,7 @@ export const ManualTrigger: TriggerPlugin = {
 
     switch (decision.outcome) {
       case 'approved':
-        return { confirmed: true, approvalId: decision.approvalId, choice: decision.choice, actor: decision.actor };
+        return { confirmed: true, approvalId: decision.approvalId, actor: decision.actor };
       case 'rejected':
         throw new Error(
           `Manual trigger rejected by ${decision.actor ?? 'user'}` +

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;