@tagma/sdk 0.6.7 → 0.6.8

package/src/engine.ts

@@ -30,7 +30,13 @@ import {
   renderInputsBlock,
   renderOutputSchemaBlock,
 } from './prompt-doc';
-import { extractTaskOutputs, resolveTaskInputs, substituteInputs } from './ports';
+import {
+  extractTaskOutputs,
+  inferPromptPorts,
+  resolveTaskInputs,
+  substituteInputs,
+} from './ports';
+import type { TaskPorts } from './types';
 import {
   executeHook,
   buildPipelineStartContext,
@@ -393,6 +399,20 @@ export async function runPipeline(
     // just before a task runs, so every subsequent task_update event can
     // echo them to the UI without re-resolving.
     const resolvedInputsMap = new Map<string, Readonly<Record<string, unknown>>>();
+    // Reverse adjacency: for each task, list the direct-downstream task ids
+    // (tasks whose `depends_on` includes this one after DAG qualification).
+    // Computed once up front so Prompt-task port inference — which needs
+    // "what Commands directly consume me?" — is O(1) instead of O(tasks)
+    // per Prompt start. `dag.nodes` only exposes forward edges via
+    // `dependsOn`, so we build this locally.
+    const directDownstreams = new Map<string, string[]>();
+    for (const [id] of dag.nodes) directDownstreams.set(id, []);
+    for (const [id, node] of dag.nodes) {
+      for (const upstream of node.dependsOn) {
+        const list = directDownstreams.get(upstream);
+        if (list) list.push(id);
+      }
+    }
 
     // Pipeline timeout + abort reason tracking.
     //
@@ -753,7 +773,83 @@ export async function runPipeline(
       // Resolution runs even for tasks that declare no ports — the call
       // is cheap and returns `{kind: 'ready', inputs: {}}` in that case,
       // which downstream code handles uniformly.
-      const inputResolution = resolveTaskInputs(task, outputValuesMap, node.dependsOn);
+      //
+      // Prompt Tasks have no declared ports — their I/O contract is
+      // inferred from direct-neighbor Command Tasks (see ports.ts:
+      // `inferPromptPorts`). We synthesize a `TaskPorts` object and
+      // feed it into the same resolve/substitute/render/extract
+      // pipeline the Command path uses. Collisions that a Prompt can't
+      // disambiguate (same input name on two upstreams, incompatible
+      // downstream output types) block the task with a clear message.
+      const isPromptTask = task.prompt !== undefined && task.command === undefined;
+      let effectivePorts: TaskPorts | undefined = task.ports;
+      let promptInferenceBlockReason: string | null = null;
+
+      if (isPromptTask) {
+        const inference = inferPromptPorts({
+          upstreams: node.dependsOn.map((upstreamId) => {
+            const upstream = dag.nodes.get(upstreamId);
+            const isUpstreamCommand = !!upstream?.task.command;
+            return {
+              taskId: upstreamId,
+              outputs: isUpstreamCommand ? upstream?.task.ports?.outputs : undefined,
+            };
+          }),
+          downstreams: (directDownstreams.get(taskId) ?? []).map((downstreamId) => {
+            const downstream = dag.nodes.get(downstreamId);
+            const isDownstreamCommand = !!downstream?.task.command;
+            return {
+              taskId: downstreamId,
+              inputs: isDownstreamCommand ? downstream?.task.ports?.inputs : undefined,
+            };
+          }),
+        });
+        effectivePorts = inference.ports;
+        if (inference.inputConflicts.length > 0 || inference.outputConflicts.length > 0) {
+          const lines: string[] = [];
+          for (const c of inference.inputConflicts) lines.push(c.reason);
+          for (const c of inference.outputConflicts) lines.push(c.reason);
+          promptInferenceBlockReason = lines.join('\n');
+        }
+      }
+
+      if (promptInferenceBlockReason !== null) {
+        log.error(
+          `[task:${taskId}]`,
+          `blocked — prompt port inference failed:\n${promptInferenceBlockReason}`,
+        );
+        state.result = {
+          exitCode: -1,
+          stdout: '',
+          stderr: `[engine] prompt port inference failed:\n${promptInferenceBlockReason}`,
+          stdoutPath: null,
+          stderrPath: null,
+          durationMs: 0,
+          sessionId: null,
+          normalizedOutput: null,
+          failureKind: 'spawn_error',
+          outputs: null,
+        };
+        state.finishedAt = nowISO();
+        setTaskStatus(taskId, 'blocked');
+        try {
+          await fireHook(taskId, 'task_failure');
+        } catch (hookErr) {
+          log.error(
+            `[task:${taskId}]`,
+            `hook execution failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`,
+          );
+        }
+        if (getOnFailure(taskId) === 'stop_all') applyStopAll(node.track.id);
+        return;
+      }
+
+      // Feed effective ports into `resolveTaskInputs` by shallow-cloning
+      // the task. Prompt tasks get the inferred ports; Command tasks are
+      // unchanged (effectivePorts === task.ports).
+      const taskForResolve: TaskConfig =
+        effectivePorts === task.ports ? task : { ...task, ports: effectivePorts };
+      const inputResolution = resolveTaskInputs(taskForResolve, outputValuesMap, node.dependsOn);
       if (inputResolution.kind === 'blocked') {
         log.error(
           `[task:${taskId}]`,
@@ -792,10 +888,11 @@ export async function runPipeline(
           `optional inputs unresolved (empty in placeholders): ${inputResolution.missingOptional.join(', ')}`,
         );
       }
-      if (task.ports?.inputs && task.ports.inputs.length > 0) {
+      if (effectivePorts?.inputs && effectivePorts.inputs.length > 0) {
         log.debug(
           `[task:${taskId}]`,
-          `resolved inputs: ${JSON.stringify(resolvedInputs)}`,
+          `resolved inputs: ${JSON.stringify(resolvedInputs)}` +
+            (isPromptTask ? ' (inferred from upstream Commands)' : ''),
         );
       }
 
@@ -888,11 +985,11 @@ export async function runPipeline(
           // matters: [Output Format] first (sets the deliverable), then
           // [Inputs] (the concrete data to operate on). Empty blocks are
           // filtered out — tasks without ports get no extra blocks at all.
-          const outputFormatBlock = renderOutputSchemaBlock(task.ports?.outputs);
+          const outputFormatBlock = renderOutputSchemaBlock(effectivePorts?.outputs);
           if (outputFormatBlock) {
             doc = prependContext(doc, outputFormatBlock);
           }
-          const inputsBlock = renderInputsBlock(task.ports?.inputs, resolvedInputs);
+          const inputsBlock = renderInputsBlock(effectivePorts?.inputs, resolvedInputs);
           if (inputsBlock) {
             doc = prependContext(doc, inputsBlock);
           }
@@ -996,6 +1093,13 @@ export async function runPipeline(
             ...task,
             prompt,
             continue_from: node.resolvedContinueFrom,
+            // Hand the driver the EFFECTIVE port schema rather than the
+            // raw task.ports. For Prompt tasks this is the one inferred
+            // from neighbor Commands; Command tasks are unchanged.
+            // Drivers that introspect ports (e.g. to annotate a system
+            // prompt with the I/O contract) otherwise saw `undefined`
+            // for every prompt and had no way to know the contract.
+            ports: effectivePorts,
           };
           const driverCtx: DriverContext = {
             sessionMap,
@@ -1074,17 +1178,22 @@ export async function runPipeline(
         // through driver-specific logs.
         let extractedOutputs: Readonly<Record<string, unknown>> | null = null;
         if (terminalStatus === 'success') {
+          // Prompt tasks use inferred ports (from direct-downstream Command
+          // inputs); Command tasks use their declared ports. Either way,
+          // `extractTaskOutputs` is a no-op when there are no declared
+          // outputs to pull, so pre-ports tasks pay nothing for this call.
           const extraction = extractTaskOutputs(
-            task.ports,
+            effectivePorts,
             result.stdout,
             result.normalizedOutput,
           );
-          if (task.ports?.outputs && task.ports.outputs.length > 0) {
+          if (effectivePorts?.outputs && effectivePorts.outputs.length > 0) {
             extractedOutputs = extraction.outputs;
             outputValuesMap.set(taskId, extraction.outputs);
             log.debug(
               `[task:${taskId}]`,
-              `extracted outputs: ${JSON.stringify(extraction.outputs)}`,
+              `extracted outputs: ${JSON.stringify(extraction.outputs)}` +
+                (isPromptTask ? ' (inferred from downstream Commands)' : ''),
             );
             if (extraction.diagnostic) {
               log.error(`[task:${taskId}]`, extraction.diagnostic);

package/src/ports.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import {
   extractInputReferences,
   extractTaskOutputs,
+  inferPromptPorts,
   resolveTaskInputs,
   substituteInputs,
 } from './ports';
@@ -299,3 +300,172 @@ describe('extractTaskOutputs', () => {
     expect(r.diagnostic).toContain('could not find a final-line JSON object');
   });
 });
+
+// ─── inferPromptPorts ───────────────────────────────────────────────
+
+describe('inferPromptPorts', () => {
+  test('inputs are taken from direct-upstream Command outputs', () => {
+    const r = inferPromptPorts({
+      upstreams: [
+        {
+          taskId: 't.up',
+          outputs: [
+            { name: 'city', type: 'string' },
+            { name: 'id', type: 'number' },
+          ],
+        },
+      ],
+      downstreams: [],
+    });
+    expect(r.inputConflicts).toEqual([]);
+    expect(r.outputConflicts).toEqual([]);
+    expect(r.ports.inputs).toHaveLength(2);
+    expect(r.ports.inputs?.map((p) => p.name).sort()).toEqual(['city', 'id']);
+    // Inferred inputs default to required: the LLM wouldn't see a real
+    // value if the upstream failed to produce one.
+    expect(r.ports.inputs?.every((p) => p.required === true)).toBe(true);
+    expect(r.ports.outputs).toBeUndefined();
+  });
+
+  test('outputs are taken from direct-downstream Command inputs', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        {
+          taskId: 't.down',
+          inputs: [
+            { name: 'greeting', type: 'string', required: true },
+            { name: 'target', type: 'string', default: 'world' },
+          ],
+        },
+      ],
+    });
+    expect(r.outputConflicts).toEqual([]);
+    expect(r.ports.outputs?.map((p) => p.name).sort()).toEqual(['greeting', 'target']);
+    // Outputs drop input-only fields (required, default, from).
+    for (const p of r.ports.outputs ?? []) {
+      expect(p).not.toHaveProperty('required');
+      expect(p).not.toHaveProperty('default');
+      expect(p).not.toHaveProperty('from');
+    }
+    expect(r.ports.inputs).toBeUndefined();
+  });
+
+  test('Prompt neighbors (outputs undefined) contribute nothing', () => {
+    const r = inferPromptPorts({
+      upstreams: [
+        { taskId: 't.up', outputs: undefined }, // Prompt upstream
+      ],
+      downstreams: [
+        { taskId: 't.down', inputs: undefined }, // Prompt downstream
+      ],
+    });
+    expect(r.ports).toEqual({});
+    expect(r.inputConflicts).toEqual([]);
+    expect(r.outputConflicts).toEqual([]);
+  });
+
+  test('two upstreams with the same output name produce an input conflict', () => {
+    const r = inferPromptPorts({
+      upstreams: [
+        { taskId: 't.a', outputs: [{ name: 'city', type: 'string' }] },
+        { taskId: 't.b', outputs: [{ name: 'city', type: 'string' }] },
+      ],
+      downstreams: [],
+    });
+    expect(r.inputConflicts).toHaveLength(1);
+    expect(r.inputConflicts[0]!.portName).toBe('city');
+    expect(r.inputConflicts[0]!.producers.map((p) => p.taskId).sort()).toEqual(['t.a', 't.b']);
+    expect(r.inputConflicts[0]!.reason).toMatch(/cannot disambiguate/);
+  });
+
+  test('two downstreams with compatible input types merge silently', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        {
+          taskId: 't.d1',
+          inputs: [{ name: 'date', type: 'string', required: true }],
+        },
+        {
+          taskId: 't.d2',
+          inputs: [{ name: 'date', type: 'string', required: false }],
+        },
+      ],
+    });
+    expect(r.outputConflicts).toEqual([]);
+    expect(r.ports.outputs).toHaveLength(1);
+    expect(r.ports.outputs![0]!.name).toBe('date');
+    expect(r.ports.outputs![0]!.type).toBe('string');
+  });
+
+  test('two downstreams with incompatible input types produce an output conflict', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        { taskId: 't.d1', inputs: [{ name: 'date', type: 'string' }] },
+        { taskId: 't.d2', inputs: [{ name: 'date', type: 'number' }] },
+      ],
+    });
+    expect(r.outputConflicts).toHaveLength(1);
+    expect(r.outputConflicts[0]!.portName).toBe('date');
+    expect(r.outputConflicts[0]!.reason).toMatch(/conflicting type requirements/);
+  });
+
+  test('enum ports with differing value sets are incompatible', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        {
+          taskId: 't.d1',
+          inputs: [{ name: 'bucket', type: 'enum', enum: ['a', 'b'] }],
+        },
+        {
+          taskId: 't.d2',
+          inputs: [{ name: 'bucket', type: 'enum', enum: ['a', 'c'] }],
+        },
+      ],
+    });
+    expect(r.outputConflicts).toHaveLength(1);
+  });
+
+  test('enum ports with identical value sets merge', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        {
+          taskId: 't.d1',
+          inputs: [{ name: 'bucket', type: 'enum', enum: ['a', 'b'] }],
+        },
+        {
+          taskId: 't.d2',
+          inputs: [{ name: 'bucket', type: 'enum', enum: ['b', 'a'] }], // different order, same set
+        },
+      ],
+    });
+    expect(r.outputConflicts).toEqual([]);
+    expect(r.ports.outputs).toHaveLength(1);
+  });
+
+  test('description and enum propagate from the first occurrence', () => {
+    const r = inferPromptPorts({
+      upstreams: [
+        {
+          taskId: 't.up',
+          outputs: [
+            {
+              name: 'kind',
+              type: 'enum',
+              enum: ['hot', 'cold'],
+              description: 'Weather kind',
+            },
+          ],
+        },
+      ],
+      downstreams: [],
+    });
+    const port = r.ports.inputs![0]!;
+    expect(port.description).toBe('Weather kind');
+    expect(port.enum).toEqual(['hot', 'cold']);
+  });
+});

package/src/ports.ts

@@ -1,6 +1,6 @@
-// ═══ Task ports: substitute / resolve / extract ═══
+// ═══ Task ports: substitute / resolve / extract / infer ═══
 //
-// One module, three concerns, all keyed on `task.ports`:
+// One module, four concerns, all keyed on `task.ports`:
 //
 //   1. `substituteInputs(text, inputs)` — expand `{{inputs.<name>}}` in
 //      user-authored strings (command lines, prompts). Strict syntax, no
@@ -22,10 +22,19 @@
 //      it. Prefer `normalizedOutput` for AI tasks, fall back to raw
 //      stdout — command tasks only ever have stdout.
 //
+//   4. `inferPromptPorts({upstreams, downstreams})` — Prompt Tasks do NOT
+//      declare ports; their I/O contract is inferred from direct-neighbor
+//      Command Tasks. This helper synthesizes a `TaskPorts` object the
+//      engine can feed into the three concerns above, and surfaces any
+//      collisions that block the task (same port name on two upstreams,
+//      incompatible types across downstreams, …). Prompt neighbors
+//      contribute zero structured I/O — they pass free text via
+//      `continue_from` / normalizedOutput instead.
+//
 // Everything here is pure / deterministic so it can be reused by the CLI,
 // the editor (for preview/simulation), and the engine without side effects.
 
-import type { PortDef, TaskConfig, TaskPorts } from './types';
+import type { PortDef, PortType, TaskConfig, TaskPorts } from './types';
 
 // ─── Template substitution ────────────────────────────────────────────
 
@@ -440,3 +449,221 @@ function safeParseJson(candidate: string): Record<string, unknown> | null {
   }
   return null;
 }
+
+// ─── Prompt-task port inference ───────────────────────────────────────
+//
+// Prompt Tasks have no declared ports. The engine calls `inferPromptPorts`
+// to synthesize one from the Task's direct DAG neighbors:
+//
+//   - **inputs** are taken from the declared `outputs` of every direct
+//     upstream Command Task. The union of names becomes the Prompt's
+//     inferred inputs. Upstream Prompt neighbors contribute nothing —
+//     information flows between Prompts as free text through
+//     `continue_from` / normalizedOutput, not through port values.
+//
+//   - **outputs** are taken from the declared `inputs` of every direct
+//     downstream Command Task. The union of names becomes the Prompt's
+//     inferred outputs, which drives the `[Output Format]` block that
+//     tells the LLM what JSON to emit. Downstream Prompt neighbors
+//     contribute nothing (they just consume free text).
+//
+// Collisions:
+//
+//   - **Input collision**: two upstream Commands both export an output
+//     named `city`. Command→Command would let a downstream add
+//     `from: taskId.city` to pick one; Prompt Tasks have no port
+//     declarations and therefore no escape hatch. The only fix is to
+//     rename on the Command side. We surface this as an `inputConflicts`
+//     entry; the engine blocks the task with that reason.
+//
+//   - **Output collision with compatible types** (e.g. both downstreams
+//     ask for `date: string` with the same description) → merged into a
+//     single inferred output. The Prompt produces one `date`; both
+//     downstreams consume it.
+//
+//   - **Output collision with incompatible types** (e.g. one downstream
+//     wants `date: string`, another `date: number`) → no single LLM
+//     emission can satisfy both. Surfaced as `outputConflicts`; engine
+//     blocks the task. User must rename on one side.
+
+export interface PromptUpstreamNeighbor {
+  readonly taskId: string;
+  /**
+   * Declared outputs of the upstream task. `undefined` signals that the
+   * neighbor is a Prompt Task (no structured contribution) or otherwise
+   * has no outputs to offer. The inference logic treats `undefined` and
+   * an empty array the same way — neither contributes ports.
+   */
+  readonly outputs: readonly PortDef[] | undefined;
+}
+
+export interface PromptDownstreamNeighbor {
+  readonly taskId: string;
+  /**
+   * Declared inputs of the downstream task. `undefined` signals a
+   * Prompt-Task neighbor or a Command Task without declared inputs.
+   * Either way it contributes no ports to the inferred output contract.
+   */
+  readonly inputs: readonly PortDef[] | undefined;
+}
+
+export interface PromptPortConflict {
+  readonly portName: string;
+  readonly producers: readonly { readonly taskId: string; readonly type: PortType }[];
+  /** Pre-formatted human-readable reason for logs / stderr. */
+  readonly reason: string;
+}
+
+export interface PromptPortInference {
+  /**
+   * Synthetic `TaskPorts` the engine feeds into the resolve / substitute /
+   * render / extract helpers, exactly as if the Prompt had declared these
+   * ports itself. Empty arrays are preserved as absent so downstream code
+   * paths treat "no ports" uniformly (see engine.ts's existing
+   * `task.ports?.outputs && task.ports.outputs.length > 0` guard).
+   */
+  readonly ports: TaskPorts;
+  readonly inputConflicts: readonly PromptPortConflict[];
+  readonly outputConflicts: readonly PromptPortConflict[];
+}
+
+/**
+ * Derive the effective `TaskPorts` for a Prompt Task from its direct
+ * neighbors. See the module-level "Prompt-task port inference" comment
+ * for the full contract.
+ *
+ * Pure function — no side effects, safe to call from the CLI, editor
+ * preview, and engine hot path alike.
+ */
+export function inferPromptPorts(input: {
+  readonly upstreams: readonly PromptUpstreamNeighbor[];
+  readonly downstreams: readonly PromptDownstreamNeighbor[];
+}): PromptPortInference {
+  const { upstreams, downstreams } = input;
+
+  // ─── Inputs: union of upstream-Command outputs ─────────────────────
+  //
+  // Walk every upstream in DAG order. First occurrence of a name wins
+  // (for the synthesized port shape used to resolve values). Subsequent
+  // occurrences under the same name become an `inputConflicts` entry —
+  // the engine blocks the task because a Prompt can't disambiguate.
+  const inputsByName = new Map<string, { port: PortDef; firstProducer: string }>();
+  const inputCollisionSources = new Map<string, { taskId: string; type: PortType }[]>();
+
+  for (const upstream of upstreams) {
+    if (!upstream.outputs || upstream.outputs.length === 0) continue;
+    for (const out of upstream.outputs) {
+      const prior = inputsByName.get(out.name);
+      if (!prior) {
+        // Copy the shape verbatim but drop output-only fields and force
+        // `required: true`. Prompt-task inferred inputs are required by
+        // default: the LLM wouldn't be getting a real-world value
+        // otherwise, and substituting an empty string silently is the
+        // same kind of bug we already reject elsewhere.
+        inputsByName.set(out.name, {
+          port: {
+            name: out.name,
+            type: out.type,
+            ...(out.description ? { description: out.description } : {}),
+            ...(out.enum ? { enum: [...out.enum] } : {}),
+            required: true,
+          },
+          firstProducer: upstream.taskId,
+        });
+        continue;
+      }
+      // Collision — seed the source list with the first producer too so
+      // the emitted conflict lists *all* contributing producers.
+      const list = inputCollisionSources.get(out.name) ?? [
+        { taskId: prior.firstProducer, type: prior.port.type },
+      ];
+      list.push({ taskId: upstream.taskId, type: out.type });
+      inputCollisionSources.set(out.name, list);
+    }
+  }
+
+  const inputConflicts: PromptPortConflict[] = [];
+  for (const [portName, producers] of inputCollisionSources) {
+    const producerList = producers.map((p) => p.taskId).join(', ');
+    inputConflicts.push({
+      portName,
+      producers,
+      reason:
+        `input "${portName}" is produced by multiple upstream Commands (${producerList}) — ` +
+        `Prompt tasks cannot disambiguate (no explicit "from:" binding). ` +
+        `Rename the output on one of the upstream Commands.`,
+    });
+  }
+
+  // ─── Outputs: union of downstream-Command inputs ───────────────────
+  //
+  // Compatible repeats merge (preserve first-encountered shape; prefer
+  // required when any downstream requires it). Incompatible repeats
+  // (different type, different enum set) go to `outputConflicts`.
+  const outputsByName = new Map<string, { port: PortDef; firstConsumer: string }>();
+  const outputCollisionSources = new Map<string, { taskId: string; type: PortType }[]>();
+
+  for (const downstream of downstreams) {
+    if (!downstream.inputs || downstream.inputs.length === 0) continue;
+    for (const inp of downstream.inputs) {
+      const prior = outputsByName.get(inp.name);
+      if (!prior) {
+        // Outputs drop input-only fields (required, default, from).
+        outputsByName.set(inp.name, {
+          port: {
+            name: inp.name,
+            type: inp.type,
+            ...(inp.description ? { description: inp.description } : {}),
+            ...(inp.enum ? { enum: [...inp.enum] } : {}),
+          },
+          firstConsumer: downstream.taskId,
+        });
+        continue;
+      }
+      if (portsAreCompatible(prior.port, inp)) continue; // merge silently
+      const list = outputCollisionSources.get(inp.name) ?? [
+        { taskId: prior.firstConsumer, type: prior.port.type },
+      ];
+      list.push({ taskId: downstream.taskId, type: inp.type });
+      outputCollisionSources.set(inp.name, list);
+    }
+  }
+
+  const outputConflicts: PromptPortConflict[] = [];
+  for (const [portName, producers] of outputCollisionSources) {
+    const consumerList = producers.map((p) => `${p.taskId} (${p.type})`).join(', ');
+    outputConflicts.push({
+      portName,
+      producers,
+      reason:
+        `output "${portName}" has conflicting type requirements across downstream Commands ` +
+        `(${consumerList}) — a single LLM emission cannot satisfy both. ` +
+        `Rename the input on one of the downstream Commands.`,
+    });
+  }
+
+  const inferredInputs = [...inputsByName.values()].map((e) => e.port);
+  const inferredOutputs = [...outputsByName.values()].map((e) => e.port);
+
+  const ports: TaskPorts = {
+    ...(inferredInputs.length > 0 ? { inputs: inferredInputs } : {}),
+    ...(inferredOutputs.length > 0 ? { outputs: inferredOutputs } : {}),
+  };
+  return { ports, inputConflicts, outputConflicts };
+}
+
+/**
+ * Two ports with the same name are compatible if they agree on `type`
+ * and, for enum ports, on the enum value set. Descriptions and
+ * required/default flags are deliberately ignored — they don't affect
+ * whether a single value can satisfy both consumers.
+ */
+function portsAreCompatible(a: PortDef, b: PortDef): boolean {
+  if (a.type !== b.type) return false;
+  if (a.type === 'enum') {
+    const aEnum = [...(a.enum ?? [])].sort().join('');
+    const bEnum = [...(b.enum ?? [])].sort().join('');
+    if (aEnum !== bEnum) return false;
+  }
+  return true;
+}

package/src/runner.test.ts

@@ -55,10 +55,10 @@ test('runSpawn: oversized output — bounded tail in memory, full bytes on disk'
     expect(result.exitCode).toBe(0);
     // Total bytes reported match reality
     expect(result.stdoutBytes).toBe(totalBytes);
-    // In-memory tail bounded (tail + truncation marker header is a couple
-    // hundred bytes at most; give it slack)
+    // In-memory tail bounded above (tail + truncation marker header is a
+    // couple hundred bytes at most; give it slack). No lower bound — chunk
+    // boundaries are platform-dependent so the exact retained size varies.
     expect(result.stdout.length).toBeLessThan(cap + 1024);
-    expect(result.stdout.length).toBeGreaterThan(cap - 1024);
     // Truncation breadcrumb present and points at the full output
     expect(result.stdout).toContain('truncated from head');
     expect(result.stdout).toContain(stdoutPath);

package/src/runner.ts

@@ -114,12 +114,20 @@ async function collectStream(
   const chunks: Uint8Array[] = [];
   let tailBytes = 0;
   let totalBytes = 0;
-  const reader = stream.getReader();
+  let streamError: Error | null = null;
 
   try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
+    // Use for await...of to avoid Bun bug where getReader() returns an
+    // incomplete reader missing releaseLock() under concurrent spawn.
+    // https://github.com/oven-sh/bun/issues/28952
+    //
+    // Bun 1.3.x also has sporadic failures iterating a spawned process's
+    // stream under concurrent Bun.spawn — the iterator throws mid-drain even
+    // when the child exited 0. We record the error as a breadcrumb instead
+    // of propagating, so the caller still sees the real exitCode from
+    // proc.exited and a task that the OS considered successful doesn't get
+    // marked failed over a runtime stream glitch.
+    for await (const value of stream as AsyncIterable<Uint8Array>) {
       totalBytes += value.length;
 
       // Disk: persist every byte. Failure here degrades to tail-only mode
@@ -157,8 +165,12 @@ async function collectStream(
         tailBytes = chunks[0]!.length;
       }
     }
+  } catch (err) {
+    streamError = err instanceof Error ? err : new Error(String(err));
+    console.error(
+      `[runner] stream read failed: ${streamError.message} — returning partial output`,
+    );
   } finally {
-    reader.releaseLock();
     if (fh) {
       try {
         await fh.close();
@@ -187,6 +199,10 @@ async function collectStream(
     text = `[…${dropped} bytes truncated from head — full output at: ${pathHint}]\n${text}`;
   }
 
+  if (streamError) {
+    text = text + `\n[runner] stream read aborted: ${streamError.message}`;
+  }
+
   return {
     text,
     totalBytes,