opencode-ultracode 0.1.0

package/src/runtime/schema.ts

@@ -0,0 +1,92 @@
+// Minimal JSON-Schema validator for agent structured output.
+// Supports the subset workflow scripts use: type (object/array/string/number/boolean),
+// properties, required, items, enum, additionalProperties.
+
+export class SchemaError extends Error {}
+
+export function validateSchema(value: unknown, schema: unknown, path = "$"): void {
+  if (!schema || typeof schema !== "object") return
+  const s = schema as any
+  if (s.type) {
+    const types = Array.isArray(s.type) ? s.type : [s.type]
+    if (!types.some((t: string) => matchesType(value, t)))
+      throw new SchemaError(`${path}: expected type ${types.join("|")}, got ${typeName(value)}`)
+  }
+  if (s.enum && !s.enum.includes(value))
+    throw new SchemaError(`${path}: value not in enum [${s.enum.join(", ")}]`)
+  if (s.type === "object" || (typeof value === "object" && value !== null && !Array.isArray(value) && s.properties)) {
+    const obj = value as Record<string, unknown>
+    for (const req of s.required ?? []) {
+      if (!(req in obj)) throw new SchemaError(`${path}: missing required property "${req}"`)
+    }
+    for (const [key, sub] of Object.entries<any>(s.properties ?? {})) {
+      if (key in obj) validateSchema(obj[key], sub, `${path}.${key}`)
+    }
+    if (s.additionalProperties === false && s.required) {
+      const allowed = new Set(s.required)
+      for (const k of Object.keys(obj)) if (!allowed.has(k)) {
+        // only reject when properties are also defined, to stay permissive
+        if (s.properties) throw new SchemaError(`${path}.${k}: additional property not allowed`)
+      }
+    }
+  }
+  if (s.type === "array" || Array.isArray(value)) {
+    if (Array.isArray(value) && s.items) {
+      value.forEach((v, i) => validateSchema(v, s.items, `${path}[${i}]`))
+    }
+  }
+}
+
+function matchesType(value: unknown, type: string): boolean {
+  switch (type) {
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value)
+    case "array":
+      return Array.isArray(value)
+    case "string":
+      return typeof value === "string"
+    case "number":
+      return typeof value === "number"
+    case "integer":
+      return Number.isInteger(value)
+    case "boolean":
+      return typeof value === "boolean"
+    case "null":
+      return value === null
+    default:
+      return true
+  }
+}
+function typeName(v: unknown): string {
+  if (v === null) return "null"
+  if (Array.isArray(v)) return "array"
+  return typeof v
+}
+
+/** Extract the JSON value from a model's text response: last code block or last object/array literal. */
+export function extractJson(text: string): { ok: true; value: unknown } | { ok: false; error: string } {
+  const t = text.trim()
+  try {
+    return { ok: true, value: JSON.parse(t) }
+  } catch {}
+  // fenced block
+  const fences = [...t.matchAll(/```(?:json)?\s*([\s\S]*?)```/g)]
+  for (let i = fences.length - 1; i >= 0; i--) {
+    const inner = fences[i][1].trim()
+    try {
+      return { ok: true, value: JSON.parse(inner) }
+    } catch {}
+  }
+  // last balanced object
+  for (const open of ["{", "["]) {
+    const close = open === "{" ? "}" : "]"
+    const start = t.lastIndexOf(open)
+    const end = t.lastIndexOf(close)
+    if (start !== -1 && end > start) {
+      try {
+        return { ok: true, value: JSON.parse(t.slice(start, end + 1)) }
+      } catch {}
+    }
+  }
+  return { ok: false, error: "no JSON object found in response" }
+}

package/src/runtime/script.ts

@@ -0,0 +1,220 @@
+// Workflow script parsing and sandboxed execution context.
+//
+// Scripts are plain JavaScript (NOT TypeScript) that must begin with a pure
+// literal `export const meta = {...}`. The body runs in an async sandbox with
+// the orchestration primitives as parameters. Deterministic-safety:
+// Date.now()/Math.random()/argless new Date() throw, and dangerous globals
+// (process, require, fetch, Bun, ...) are shadowed so they resolve to throwers.
+// This is a determinism sandbox for resume, NOT a security boundary.
+
+import type { PhaseDef } from "../shared/state.ts"
+
+export interface WorkflowMeta {
+  name: string
+  description: string
+  whenToUse?: string
+  phases?: PhaseDef[]
+}
+
+export interface ParsedScript {
+  meta: WorkflowMeta
+  body: string
+}
+
+const META_RE = /export\s+const\s+meta\s*=\s*/
+
+export function parseScript(script: string): ParsedScript {
+  const m = script.match(META_RE)
+  if (!m || m.index === undefined) throw new Error("Workflow script must start with `export const meta = { ... }`")
+  const start = script.indexOf("{", m.index + m[0].length)
+  if (start === -1) throw new Error("Could not find meta object literal")
+  const end = findBalanced(script, start)
+  const literal = script.slice(start, end + 1)
+  // meta must be a pure literal; evaluating an object literal with new Function
+  // is safe as long as it contains no expressions — we lint that first.
+  if (/[;,\n]\s*function\b|\bnew\s+|\bif\s*\(|\bwhile\s*\(|=>/.test(literal))
+    throw new Error("meta must be a pure object literal (no functions, calls, or arrow functions)")
+  let meta: WorkflowMeta
+  try {
+    meta = new Function(`"use strict"; return (${literal})`)() as WorkflowMeta
+  } catch (e: any) {
+    throw new Error(`Invalid meta literal: ${e?.message ?? e}`)
+  }
+  if (!meta || typeof meta !== "object") throw new Error("meta must be an object")
+  if (!meta.name || typeof meta.name !== "string") throw new Error("meta.name is required")
+  if (!meta.description || typeof meta.description !== "string")
+    throw new Error("meta.description is required (one line, shown in the approval dialog)")
+  for (const p of meta.phases ?? []) {
+    if (!p.title) throw new Error("each meta.phases entry needs a title")
+  }
+  const body = (script.slice(0, start) + " ".repeat(end - start + 1) + script.slice(end + 1)).replace(META_RE, "")
+  return { meta, body }
+}
+
+function findBalanced(s: string, openIdx: number): number {
+  let depth = 0
+  let inStr: string | null = null
+  for (let i = openIdx; i < s.length; i++) {
+    const c = s[i]
+    if (inStr) {
+      if (c === "\\") i++
+      else if (c === inStr) inStr = null
+      continue
+    }
+    if (c === '"' || c === "'" || c === "`") inStr = c
+    else if (c === "{" || c === "[" || c === "(") depth++
+    else if (c === "}" || c === "]" || c === ")") {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  throw new Error("Unbalanced meta literal")
+}
+
+// --- sandbox ----------------------------------------------------------------
+
+export interface Primitives {
+  agent: (prompt: string, opts?: AgentOpts) => Promise<any>
+  parallel: (thunks: Array<() => Promise<any>>) => Promise<any[]>
+  pipeline: <T, R>(items: T[], ...stages: Array<(prev: any, item: T, index: number) => Promise<R> | R>) => Promise<any[]>
+  phase: (title: string) => void
+  log: (message: string) => void
+  args: any
+  budget: Budget
+}
+
+export interface AgentOpts {
+  label?: string
+  phase?: string
+  schema?: object
+  model?: string
+  effort?: string
+  isolation?: string
+  agentType?: string
+}
+
+export interface Budget {
+  total: number | null
+  spent(): number
+  remaining(): number
+}
+
+function throwing(name: string): any {
+  const f: any = () => {
+    throw new Error(`Access to global "${name}" is not available in workflow scripts; use log() for output`)
+  }
+  return new Proxy(f, {
+    get(_t, prop) {
+      if (prop === Symbol.toPrimitive || prop === "then") return undefined
+      throw new Error(`Access to "${name}.${String(prop)}" is not available in workflow scripts`)
+    },
+    apply: () => {
+      throw new Error(`Access to global "${name}" is not available in workflow scripts`)
+    },
+  })
+}
+
+/** Deterministic Date: no-arg new Date() and Date.now() throw. */
+function makeSafeDate(): any {
+  class SafeDate {
+    getTime = () => 0
+    valueOf = () => 0
+    toString = () => ""
+    toISOString = () => ""
+    constructor(...args: any[]) {
+      if (args.length === 0)
+        throw new Error("new Date() without arguments is not available in workflow scripts (breaks resume); pass a timestamp via args")
+      // delegate to the real Date via a hidden reference
+      const D = makeSafeDate as any;
+      const real = new D.__impl(...args)
+      for (const k of Object.keys(real)) (this as any)[k] = (real as any)[k]
+      this.getTime = real.getTime.bind(real)
+      this.valueOf = real.valueOf.bind(real)
+      this.toString = real.toString.bind(real)
+      this.toISOString = real.toISOString.bind(real)
+    }
+    static now() {
+      throw new Error("Date.now() is not available in workflow scripts (breaks resume); pass a timestamp via args")
+    }
+    static parse(...a: any[]) {
+      const D = makeSafeDate as any
+      return D.__impl.parse(...a)
+    }
+    static UTC(...a: any[]) {
+      const D = makeSafeDate as any
+      return D.__impl.UTC(...a)
+    }
+  }
+  ;(makeSafeDate as any).__impl = Date
+  return SafeDate
+}
+
+/** Math minus random. */
+function makeSafeMath(): any {
+  const real = Object.create(Math)
+  return new Proxy(real, {
+    get(t, prop) {
+      if (prop === "random")
+        return () => {
+          throw new Error("Math.random() is not available in workflow scripts (breaks resume); vary prompts/labels by index")
+        }
+      const v = (t as any)[prop]
+      return typeof v === "function" ? v.bind(t) : v
+    },
+  })
+}
+
+const SHADOWED = [
+  "require",
+  "process",
+  "Bun",
+  "fetch",
+  "WebSocket",
+  "EventSource",
+  "crypto",
+  "globalThis",
+  "self",
+  "window",
+  "global",
+  "Buffer",
+  "child_process",
+  "fs",
+  "os",
+  "module",
+  "exports",
+  "__dirname",
+  "__filename",
+] as const
+
+/**
+ * Build the sandboxed script function. The body runs in an async IIFE with the
+ * primitives in scope; dangerous globals are shadowed by the proxy throwers.
+ */
+export function buildScriptFunction(prims: Primitives, body: string): () => Promise<any> {
+  const safeDate = makeSafeDate()
+  const safeMath = makeSafeMath()
+  const shadows = SHADOWED.map((n) => throwing(n))
+  const fn = new Function(
+    "agent",
+    "parallel",
+    "pipeline",
+    "phase",
+    "log",
+    "args",
+    "budget",
+    "Date",
+    "Math",
+    "console",
+    ...SHADOWED,
+    `"use strict"; return (async () => {\n${body}\n})()`,
+  )
+  const consoleShadow = new Proxy({} as Record<string | symbol, any>, {
+    get() {
+      return (..._a: any[]) => {
+        throw new Error("console is not available in workflow scripts; use log()")
+      }
+    },
+  })
+  return () =>
+    fn(prims.agent, prims.parallel, prims.pipeline, prims.phase, prims.log, prims.args, prims.budget, safeDate, safeMath, consoleShadow, ...shadows)
+}

package/src/runtime/selftest.ts

@@ -0,0 +1,321 @@
+// Standalone engine test: runs workflow scripts against a mocked opencode client.
+// Usage: node src/runtime/selftest.ts
+
+import { mkdtempSync, readFileSync, existsSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import assert from "node:assert"
+import { generateRunId, loadPriorRun, RunEngine } from "./engine.ts"
+import { parseScript } from "./script.ts"
+
+const tmp = mkdtempSync(join(tmpdir(), "wf-selftest-"))
+const opencodeDir = join(tmp, ".opencode")
+const runsRoot = join(tmp, "runs")
+
+let sessionSeq = 0
+let promptCount = 0
+const seenSessions: string[] = []
+
+const fakeClient = {
+  session: {
+    async create(args: any) {
+      const id = `ses_fake_${++sessionSeq}`
+      seenSessions.push(id)
+      console.log(`  [mock] session.create  title=${args.body?.title} -> ${id}`)
+      return { id, parentID: args.body?.parentID }
+    },
+    async prompt(args: any) {
+      promptCount++
+      const id = args.path.id
+      const text = String(args.body?.parts?.[0]?.text ?? "")
+      console.log(`  [mock] session.prompt  ${id} model=${args.body?.model ? JSON.stringify(args.body.model) : "(inherit)"} chars=${text.length}`)
+      // emulate the model: if the task asks for JSON tips, return JSON; synthesis returns JSON report
+      if (/\bJSON\b/i.test(text)) {
+        if (/synthes/i.test(text)) {
+          const extracted = text.match(/\[.*\]/s)?.[0]
+          let parsed: any[] = []
+          try {
+            parsed = JSON.parse(extracted ?? "[]")
+          } catch {}
+          const best = parsed.slice(0, 3).map((p: any) => p?.tip ?? "")
+          return {
+            info: assistantMsg(id),
+            parts: [{ type: "text", id: "p1", sessionID: id, messageID: "m1", text: JSON.stringify({ report: { count: best.length, best }, }) }],
+          }
+        }
+        const angleMatch = text.match(/about (\w+) multi-agent workflows/i)
+        const angle = angleMatch?.[1] ?? "general"
+        return {
+          info: assistantMsg(id),
+          parts: [{ type: "text", id: "p1", sessionID: id, messageID: "m1", text: JSON.stringify({ angle: `${angle} multi-agent workflows: mock tip`, tip: `A mock tip about ${angle}.` }) }],
+        }
+      }
+      return {
+        info: assistantMsg(id),
+        parts: [{ type: "text", id: "p1", sessionID: id, messageID: "m1", text: "plain text answer" }],
+      }
+    },
+    async abort(args: any) {
+      console.log(`  [mock] session.abort ${args.path.id}`)
+      return true
+    },
+  },
+}
+
+function assistantMsg(sessionID = "x") {
+  return {
+    id: `msg_${Math.random().toString(36).slice(2)}`,
+    sessionID,
+    role: "assistant",
+    time: { created: Date.now(), completed: Date.now() },
+    parentID: "p",
+    modelID: "mock-model",
+    providerID: "mock",
+    mode: "workflow",
+    path: { cwd: "/", root: "/" },
+    cost: 0.001,
+    tokens: { input: 10_000, output: 3_600, reasoning: 0, cache: { read: 20_000, write: 500 } },
+  }
+}
+
+const DEMO = `
+export const meta = {
+  name: "demo-fanout",
+  description: "Demo: 3 agents write tips on multi-agent workflows, 1 agent synthesizes",
+  phases: [
+    { title: "Generate", detail: "3 agents, one tip each" },
+    { title: "Synthesize", detail: "merge the tips into the final set" },
+  ],
+}
+
+const ANGLES = ["design", "execution", "debugging"]
+
+phase("Generate")
+const results = await parallel(ANGLES.map((a) => () =>
+  agent(
+    \`Write one concise tip (2-3 sentences) about \${a.toUpperCase()} multi-agent workflows: concurrency limits, token budget, and isolation. Respond with JSON.\`,
+    {
+      label: \`tip:\${a}\`,
+      schema: { type: "object", properties: { angle: { type: "string" }, tip: { type: "string" } }, required: ["angle", "tip"] },
+    },
+  ),
+))
+const tips = results.filter(Boolean)
+log(\`\${tips.length}/\${ANGLES.length} tips generated\`)
+
+phase("Synthesize")
+const final = await agent(
+  \`Synthesize these tips into the single best set (pick up to 3). Respond with JSON. Tips: \${JSON.stringify(tips, null, 2)}\`,
+  {
+    label: "tip:synthesis",
+    schema: { type: "object", properties: { report: { type: "object" } }, required: ["report"] },
+  },
+)
+return { tips, final }
+`
+
+async function main() {
+  // ---- test 1: meta parsing ------------------------------------------------
+  console.log("test 1: parseScript meta + body")
+  const parsed = parseScript(DEMO)
+  assert.equal(parsed.meta.name, "demo-fanout")
+  assert.equal(parsed.meta.phases?.length, 2)
+  assert.ok(!/^export\s+const\s+meta/m.test(parsed.body.trimStart()), "body should not retain meta")
+  assert.ok(parsed.body.includes("parallel("))
+  console.log("  ok: meta parsed, body clean")
+
+  const bad = () => parseScript("const meta = { name: 'x' };\nagent('hi')")
+  assert.throws(bad, /must start with/)
+  const impure = `export const meta = { name: "x", description: f() };\nphase("a")`
+  // f() is a call — our lint only bans functions/new/if/while/arrow; a plain call() would pass lint
+  // and blow up at eval time: still an error either way
+  assert.throws(() => parseScript(impure), /meta|moust|literal|name|description/i)
+  console.log("  ok: invalid scripts rejected")
+
+  // ---- test 2: full demo run ----------------------------------------------
+  console.log("test 2: full demo-fanout run (4 agents)")
+  const runId = generateRunId()
+  const engine = new RunEngine(
+    { client: fakeClient as any, opencodeDir, runsRoot, mainSessionID: "ses_main", defaultModel: "mock/sonnet", availableModels: new Set(["mock/sonnet", "mock/haiku"]), runArgs: { extra: 1 } },
+    runId,
+  )
+  const t0 = Date.now()
+  const res = await engine.run({ script: DEMO })
+  const dt = Date.now() - t0
+  console.log(`  result: status=${res.status} in ${dt}ms`)
+  assert.equal(res.status, "completed", `expected completed, error=${res.error}`)
+  assert.ok(res.result, "expected a result payload")
+  const result = JSON.parse(res.result!)
+  assert.ok(Array.isArray(result.tips) && result.tips.length === 3, "expected 3 tips")
+  assert.ok(result.final?.report?.best?.length <= 3, "expected synthesized report")
+
+  // state file
+  const state = JSON.parse(readFileSync(join(runsRoot, runId, "state.json"), "utf8"))
+  assert.equal(state.status, "completed")
+  assert.equal(state.agentCount, 4)
+  assert.equal(state.agentDone, 4)
+  assert.equal(state.phases.length, 2)
+  assert.equal(state.phases[0].title, "Generate")
+  assert.equal(state.phases[0].agentIds.length, 3)
+  assert.equal(state.phases[1].agentIds.length, 1)
+  const labels = state.agentOrder.map((id: string) => state.agents[id].label)
+  assert.deepEqual(labels, ["tip:design", "tip:execution", "tip:debugging", "tip:synthesis"])
+  const synth = state.agents[state.agentOrder[3]]
+  assert.equal(synth.model, "mock/sonnet", "agent should inherit session model")
+  assert.ok(synth.tokens > 0, "tokens tracked")
+  // mock message: input 10k + cache read 20k + cache write 500 = 30.5k context per call
+  assert.equal(synth.contextTokens, 30_500, "context = prompt size of the latest call")
+  assert.ok(synth.tokens >= synth.contextTokens + 3_600, "billed includes output on top of context")
+  assert.ok(synth.outcome, "outcome stored")
+  assert.ok(state.totalTokens > 0)
+  assert.equal(
+    state.totalContextTokens,
+    state.agentOrder.reduce((n: number, id: string) => n + state.agents[id].contextTokens, 0),
+    "run context = sum of agent contexts",
+  )
+  console.log(`  ok: state.json (4 agents, 2 phases, billed=${state.totalTokens}, context=${state.totalContextTokens})`)
+
+  // journal
+  const journal = readFileSync(join(runsRoot, runId, "journal.jsonl"), "utf8").trim().split("\n")
+  assert.ok(journal.length >= 9, `journal lines = ${journal.length}`)
+  const kinds = journal.map((l) => JSON.parse(l).type)
+  assert.ok(kinds.includes("run-start") && kinds.includes("run-end"))
+  assert.equal(kinds.filter((k: string) => k === "agent-start").length, 4)
+  assert.equal(kinds.filter((k: string) => k === "agent-done").length, 4)
+  console.log("  ok: journal (run-start, 4x agent-start/done, run-end)")
+
+  // script.js persisted
+  assert.ok(existsSync(join(runsRoot, runId, "script.js")), "script.js persisted")
+  console.log("  ok: script.js persisted")
+
+  // ---- test 3: deterministic sandbox ---------------------------------------
+  console.log("test 3: sandbox blocks Date.now / Math.random / fetch / process")
+  const S1 = `
+export const meta = { name: "t3", description: "sandbox", phases: [{ title: "A" }] }
+phase("A")
+try { Date.now() } catch (e) { log("date-now-blocked:" + (String(e.message).includes("not available"))) }
+try { Math.random() } catch (e) { log("math-random-blocked:" + (String(e.message).includes("not available"))) }
+try { fetch("http://x") } catch (e) { log("fetch-blocked:" + (String(e.message).includes("not available"))) }
+try { process.exit } catch (e) { log("process-blocked:" + true) }
+await agent("say hi", { label: "t3a" })
+return "done"
+`
+  const rid3 = generateRunId()
+  const e3 = new RunEngine({ client: fakeClient as any, opencodeDir, runsRoot, mainSessionID: "ses_main", availableModels: new Set() }, rid3)
+  const r3 = await e3.run({ script: S1 })
+  assert.equal(r3.status, "completed")
+  const s3 = JSON.parse(readFileSync(join(runsRoot, rid3, "state.json"), "utf8"))
+  const logs = s3.logs.map((l: any) => l.message).join(" | ")
+  console.log(`  logs: ${logs}`)
+  assert.ok(logs.includes("date-now-blocked:true"))
+  assert.ok(logs.includes("math-random-blocked:true"))
+  assert.ok(logs.includes("fetch-blocked:true"))
+  assert.ok(logs.includes("process-blocked:true"))
+  console.log("  ok: sandbox blocks verified")
+
+  // Date with args still works
+  const S2 = `
+export const meta = { name: "t3b", description: "date-with-args", phases: [{ title: "A" }] }
+phase("A")
+log("date-ok:" + (new Date(1700000000000).getTime() === 1700000000000))
+return 42
+`
+  const rid3b = generateRunId()
+  const e3b = new RunEngine({ client: fakeClient as any, opencodeDir, runsRoot, mainSessionID: "ses_main", availableModels: new Set() }, rid3b)
+  const r3b = await e3b.run({ script: S2 })
+  assert.equal(r3b.status, "completed")
+  const s3b = JSON.parse(readFileSync(join(runsRoot, rid3b, "state.json"), "utf8"))
+  assert.ok(s3b.logs.some((l: any) => l.message === "date-ok:true"))
+  assert.equal(r3b.result, "42")
+  console.log("  ok: new Date(ts) + return values work")
+
+  // ---- test 4: pipeline stages (no barrier) + error -> null -----------------
+  console.log("test 4: pipeline + error handling")
+  const S4 = `
+export const meta = { name: "t4", description: "pipeline", phases: [{ title: "P" }] }
+phase("P")
+const items = ["a", "b", "c"]
+const out = await pipeline(items,
+  (prev, item) => agent("work on " + item, { label: "work:" + item }),
+  (prev, item, i) => { if (item === "b") throw new Error("boom"); return prev + "/" + i },
+)
+const bad = await parallel([() => agent("fine"), () => Promise.reject(new Error("nope"))])
+log("pipeline:" + out.map(x => x ?? "null").join(","))
+log("parallel-nulls:" + bad.filter(Boolean).length + "/" + bad.length)
+return out
+`
+  const rid4 = generateRunId()
+  const e4 = new RunEngine({ client: fakeClient as any, opencodeDir, runsRoot, mainSessionID: "ses_main", availableModels: new Set() }, rid4)
+  const r4 = await e4.run({ script: S4 })
+  assert.equal(r4.status, "completed")
+  const s4 = JSON.parse(readFileSync(join(runsRoot, rid4, "state.json"), "utf8"))
+  const l4 = s4.logs.map((l: any) => l.message).join(" | ")
+  console.log(`  logs: ${l4}`)
+  const pm = l4.match(/pipeline:(.*) \| parallel-nulls/)
+  assert.ok(pm, `no pipeline line: ${l4}`)
+  const line = pm[1] // "<item0>,<item1>,<item2>" where item1 is null
+  const mid = line.indexOf(",null,")
+  assert.ok(mid > 0, `expected a null middle item: ${line}`)
+  assert.ok(line.slice(0, mid).endsWith("/0"), `item0 should end with /0: ${line.slice(0, mid)}`)
+  assert.ok(line.endsWith("/2"), `item2 should end with /2: ${line}`)
+  assert.ok(line.slice(mid + 6).startsWith("{"), `item2 should be a result object: ${line}`)
+  assert.ok(l4.includes("parallel-nulls:1/2"))
+  const failed = s4.agentOrder.map((id: string) => s4.agents[id]).filter((a: any) => a.status === "failed")
+  assert.equal(failed.length, 0, "pipeline stage throw should drop item, not fail agent (agent itself succeeded)")
+  console.log("  ok: pipeline stages, item drop on stage error, parallel null on reject")
+
+    // ---- test 5: resume after the engine died ----------------------------------
+  console.log("test 5: resume a stopped run (completed agents replay from the journal)")
+  {
+    const rid = generateRunId()
+    const deps = { client: fakeClient as any, opencodeDir, runsRoot, mainSessionID: "ses_main", defaultModel: "mock/sonnet", availableModels: new Set(["mock/sonnet"]) }
+    const e1 = new RunEngine(deps, rid)
+    // make the synthesis agent die mid-run: stop the run once the Generate phase is done
+    const origPrompt = fakeClient.session.prompt
+    let calls = 0
+    fakeClient.session.prompt = async (args: any) => {
+      calls++
+      if (calls === 4) {
+        e1.shutdown("opencode exited while the workflow was running")
+        throw new Error("connection closed")
+      }
+      return origPrompt(args)
+    }
+    const r1 = await e1.run({ script: DEMO, args: { extra: 7 } })
+    fakeClient.session.prompt = origPrompt
+    assert.equal(r1.status, "stopped", `expected stopped, got ${r1.status} (${r1.error})`)
+    const s1: any = JSON.parse(readFileSync(join(runsRoot, rid, "state.json"), "utf8"))
+    assert.equal(s1.mainSessionID, "ses_main")
+    assert.deepEqual(s1.args, { extra: 7 })
+    const done1 = Object.values(s1.agents).filter((a: any) => a.status === "completed").length
+    assert.equal(done1, 3, `3 tip agents should have completed before the stop (got ${done1})`)
+
+    const prior = loadPriorRun(runsRoot, rid)
+    assert.ok(prior, "prior run loads")
+    assert.equal(prior!.replayable, 3)
+    const before = promptCount
+    const e2 = new RunEngine(deps, rid)
+    const r2 = await e2.run({ resume: prior! })
+    assert.equal(r2.status, "completed", `resumed run should complete, error=${r2.error}`)
+    assert.equal(promptCount - before, 1, "only the synthesis agent should call the model again")
+    const s2: any = JSON.parse(readFileSync(join(runsRoot, rid, "state.json"), "utf8"))
+    const replayed = Object.values(s2.agents).filter((a: any) => a.replayed).length
+    assert.equal(replayed, 3, "3 agents replayed")
+    assert.equal(s2.agentCount, 4)
+    assert.equal(s2.resumeCount, 1)
+    assert.equal(s2.startedAt, s1.startedAt, "original start time kept")
+    assert.ok(s2.logs.some((l: any) => /paused|stopped|exited/.test(l.message)), "prior logs carried over")
+    assert.ok(s2.logs.some((l: any) => /^resumed \(3 completed agents replay/.test(l.message)), "resume log line")
+    const final = JSON.parse(r2.result!)
+    assert.equal(final.tips.length, 3, "replayed results feed the rest of the script")
+    assert.ok(!s2.error, "error cleared on successful resume")
+    console.log(`  ok: resume replayed ${replayed} agents, re-ran 1, completed`)
+  }
+
+console.log(`\nALL TESTS PASSED (${Date.now() - t0}ms total, tmp=${tmp})`)
+}
+
+main().catch((e) => {
+  console.error("\nSELFTEST FAILED:", e)
+  process.exit(1)
+})