@tagma/sdk 0.2.6 → 0.2.7

package/README.md

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

package/package.json

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

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

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

package/src/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/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;