tulingcode 0.1.0

package/src/workflow/meta.ts

@@ -0,0 +1,335 @@
+// Parses the mandatory `export const meta = { ... }` literal from a workflow
+// script WITHOUT executing the script body — and, critically, WITHOUT executing
+// the literal either. The literal is parsed as DATA by a small recursive-descent
+// reader (objects/arrays/strings/numbers/booleans/null only), so listing/preview
+// is side-effect-free and cannot reach the host realm. Anything that isn't a
+// pure data literal (calls, property access, operators, functions, spreads,
+// templates) fails to parse and is rejected.
+//
+// Why not `new Function`/`eval`: that runs the literal in the HOST realm,
+// outside the QuickJS sandbox — a meta like
+//   { name: (globalThis.process.mainModule.require('child_process').execSync('id'),'x') }
+// would execute arbitrary host code. Why not jsonc-parser: the real meta uses
+// JS object syntax with UNQUOTED keys (`{ name: "x", phases: [{ title: "a" }] }`)
+// and single quotes, which strict/lenient JSONC rejects (verified empirically).
+// A purpose-built data reader handles that syntax while remaining pure data.
+//
+// The meta statement is replaced with an equal-length blank so the body's line
+// numbers are preserved for stack traces.
+
+export type WorkflowMeta = {
+  name: string
+  description: string
+  whenToUse?: string
+  phases?: { title: string; detail?: string }[]
+  model?: string
+}
+
+export type ParseResult =
+  | { ok: true; meta: WorkflowMeta; body: string }
+  | { ok: false; error: string }
+
+const META_START_RE = /export\s+const\s+meta\s*=\s*/
+
+export function parseMeta(script: string): ParseResult {
+  const start = META_START_RE.exec(script)
+  if (!start) {
+    return { ok: false, error: "workflow script must start with `export const meta = { ... }`" }
+  }
+  const open = script.indexOf("{", start.index + start[0].length)
+  if (open === -1) {
+    return { ok: false, error: "workflow script must start with `export const meta = { ... }`" }
+  }
+  const close = findBalancedClose(script, open)
+  if (close === -1) {
+    return { ok: false, error: "could not locate a balanced meta object literal" }
+  }
+  const literal = script.slice(open, close + 1)
+  const parsed = parseDataLiteral(literal)
+  if (!parsed.ok) return { ok: false, error: `meta is not a valid object literal: ${parsed.error}` }
+  const meta = parsed.value
+  if (typeof meta !== "object" || meta === null || Array.isArray(meta)) return { ok: false, error: "meta must be an object" }
+  const m = meta as Record<string, unknown>
+  if (typeof m.name !== "string" || !m.name) return { ok: false, error: "meta.name (non-empty string) is required" }
+  if (typeof m.description !== "string" || !m.description)
+    return { ok: false, error: "meta.description (non-empty string) is required" }
+  const endIndex = close + 1 + (script[close + 1] === ";" ? 1 : 0)
+  const matched = script.slice(start.index, endIndex)
+  const body = script.slice(0, start.index) + matched.replace(/[^\n]/g, " ") + script.slice(endIndex)
+  return { ok: true, meta: m as WorkflowMeta, body }
+}
+
+// Scans from the `{` at `open`, counting brace depth while ignoring braces that
+// appear inside string literals (single/double/backtick, respecting backslash
+// escapes) or comments (`//` line, `/* */` block). Comment handling mirrors
+// `skipTrivia` so a brace inside a meta comment (`{ name: "n" // }` ) is not
+// miscounted. Returns the index of the matching `}` that closes depth to 0, or -1.
+function findBalancedClose(script: string, open: number): number {
+  let depth = 0
+  let quote = ""
+  for (let i = open; i < script.length; i++) {
+    const ch = script[i]
+    if (quote) {
+      if (ch === "\\") {
+        i++
+        continue
+      }
+      if (ch === quote) quote = ""
+      continue
+    }
+    if (ch === "/" && script[i + 1] === "/") {
+      i += 2
+      while (i < script.length && script[i] !== "\n") i++
+      continue
+    }
+    if (ch === "/" && script[i + 1] === "*") {
+      i += 2
+      while (i < script.length && !(script[i] === "*" && script[i + 1] === "/")) i++
+      i++ // land on the `/` of `*/`; loop's i++ steps past it
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch
+      continue
+    }
+    if (ch === "{") depth++
+    else if (ch === "}") {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  return -1
+}
+
+// ---------------------------------------------------------------------------
+// A tiny recursive-descent reader for the JS object-literal DATA subset. It
+// PARSES, never evaluates: there is no `new Function`/`eval`/`vm` and no host
+// code runs. Accepts objects, arrays, double/single-quoted strings (with
+// standard escapes), numbers, `true`/`false`/`null`, identifier or quoted keys,
+// and trailing commas. Anything else (a call `()`, member access `.`/`[]` as an
+// expression, operators, `function`/`=>`, `...`, backtick templates) is a parse
+// error -> rejected. This is strictly a superset-free of code execution.
+// ---------------------------------------------------------------------------
+
+type DataResult = { ok: true; value: unknown } | { ok: false; error: string }
+
+// Real metas are ~2 levels deep (object -> phases[] -> phase object). A cap of
+// 100 is generous for any legitimate meta while preventing pathologically deep
+// input (e.g. `[[[...]]]` 50k deep) from overflowing the native call stack with
+// a `RangeError`. The cap throws `ParseFail`, so `parseDataLiteral`'s catch
+// converts it to `{ ok: false }` — keeping the documented return contract
+// (callers branch on `parsed.ok` and do not try/catch a thrown exception).
+const MAX_DEPTH = 100
+
+function parseDataLiteral(text: string): DataResult {
+  const reader = { text, pos: 0, depth: 0 }
+  // `try` is justified here: the recursive reader signals malformed input by
+  // throwing a tagged error which we convert to a result. (No host execution.)
+  try {
+    skipTrivia(reader)
+    const value = readValue(reader)
+    skipTrivia(reader)
+    if (reader.pos !== reader.text.length) throw new ParseFail(`unexpected token at offset ${reader.pos}`)
+    return { ok: true, value }
+  } catch (e) {
+    if (e instanceof ParseFail) return { ok: false, error: e.message }
+    throw e
+  }
+}
+
+class ParseFail extends Error {}
+
+type Reader = { text: string; pos: number; depth: number }
+
+// Skip whitespace plus `//` line and `/* */` block comments.
+function skipTrivia(r: Reader): void {
+  for (;;) {
+    const ch = r.text[r.pos]
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f" || ch === "\v") {
+      r.pos++
+      continue
+    }
+    if (ch === "/" && r.text[r.pos + 1] === "/") {
+      r.pos += 2
+      while (r.pos < r.text.length && r.text[r.pos] !== "\n") r.pos++
+      continue
+    }
+    if (ch === "/" && r.text[r.pos + 1] === "*") {
+      r.pos += 2
+      while (r.pos < r.text.length && !(r.text[r.pos] === "*" && r.text[r.pos + 1] === "/")) r.pos++
+      if (r.pos >= r.text.length) throw new ParseFail("unterminated comment")
+      r.pos += 2
+      continue
+    }
+    return
+  }
+}
+
+function readValue(r: Reader): unknown {
+  const ch = r.text[r.pos]
+  if (ch === undefined) throw new ParseFail("unexpected end of input")
+  if (ch === "{") return readObject(r)
+  if (ch === "[") return readArray(r)
+  if (ch === '"' || ch === "'") return readString(r)
+  if (ch === "-" || (ch >= "0" && ch <= "9")) return readNumber(r)
+  if (matchKeyword(r, "true")) return true
+  if (matchKeyword(r, "false")) return false
+  if (matchKeyword(r, "null")) return null
+  throw new ParseFail(`unexpected token at offset ${r.pos} (only data literals are allowed)`)
+}
+
+function readObject(r: Reader): Record<string, unknown> {
+  if (++r.depth > MAX_DEPTH) throw new ParseFail("meta nesting too deep")
+  r.pos++ // consume `{`
+  const obj: Record<string, unknown> = {}
+  skipTrivia(r)
+  if (r.text[r.pos] === "}") {
+    r.pos++
+    r.depth--
+    return obj
+  }
+  for (;;) {
+    skipTrivia(r)
+    const key = readKey(r)
+    skipTrivia(r)
+    if (r.text[r.pos] !== ":") throw new ParseFail(`expected ':' after key '${key}' at offset ${r.pos}`)
+    r.pos++ // consume `:`
+    skipTrivia(r)
+    obj[key] = readValue(r)
+    skipTrivia(r)
+    const sep = r.text[r.pos]
+    if (sep === ",") {
+      r.pos++
+      skipTrivia(r)
+      if (r.text[r.pos] === "}") {
+        // trailing comma
+        r.pos++
+        r.depth--
+        return obj
+      }
+      continue
+    }
+    if (sep === "}") {
+      r.pos++
+      r.depth--
+      return obj
+    }
+    throw new ParseFail(`expected ',' or '}' at offset ${r.pos}`)
+  }
+}
+
+function readArray(r: Reader): unknown[] {
+  if (++r.depth > MAX_DEPTH) throw new ParseFail("meta nesting too deep")
+  r.pos++ // consume `[`
+  const arr: unknown[] = []
+  skipTrivia(r)
+  if (r.text[r.pos] === "]") {
+    r.pos++
+    r.depth--
+    return arr
+  }
+  for (;;) {
+    skipTrivia(r)
+    arr.push(readValue(r))
+    skipTrivia(r)
+    const sep = r.text[r.pos]
+    if (sep === ",") {
+      r.pos++
+      skipTrivia(r)
+      if (r.text[r.pos] === "]") {
+        // trailing comma
+        r.pos++
+        r.depth--
+        return arr
+      }
+      continue
+    }
+    if (sep === "]") {
+      r.pos++
+      r.depth--
+      return arr
+    }
+    throw new ParseFail(`expected ',' or ']' at offset ${r.pos}`)
+  }
+}
+
+// Object key: an identifier (`name`, `$a`, `_b`, `a1`) or a quoted string.
+// No computed keys (`[expr]`), no numeric keys — those aren't legitimate meta.
+function readKey(r: Reader): string {
+  const ch = r.text[r.pos]
+  if (ch === '"' || ch === "'") return readString(r)
+  if (ch !== undefined && (/[A-Za-z_$]/.test(ch))) {
+    const startPos = r.pos
+    r.pos++
+    while (r.pos < r.text.length && /[A-Za-z0-9_$]/.test(r.text[r.pos])) r.pos++
+    return r.text.slice(startPos, r.pos)
+  }
+  throw new ParseFail(`expected a property name at offset ${r.pos}`)
+}
+
+function readString(r: Reader): string {
+  const quote = r.text[r.pos]
+  r.pos++ // consume opening quote
+  let out = ""
+  for (;;) {
+    const ch = r.text[r.pos]
+    if (ch === undefined || ch === "\n") throw new ParseFail("unterminated string")
+    if (ch === "\\") {
+      const esc = r.text[r.pos + 1]
+      r.pos += 2
+      if (esc === "n") out += "\n"
+      else if (esc === "t") out += "\t"
+      else if (esc === "r") out += "\r"
+      else if (esc === "b") out += "\b"
+      else if (esc === "f") out += "\f"
+      else if (esc === "v") out += "\v"
+      else if (esc === "0") out += "\0"
+      else if (esc === "u") {
+        const hex = r.text.slice(r.pos, r.pos + 4)
+        if (!/^[0-9a-fA-F]{4}$/.test(hex)) throw new ParseFail("invalid \\u escape")
+        out += String.fromCharCode(parseInt(hex, 16))
+        r.pos += 4
+      } else if (esc === undefined) throw new ParseFail("unterminated string")
+      else out += esc // \\ \" \' \/ and any other escaped char -> literal
+      continue
+    }
+    if (ch === quote) {
+      r.pos++
+      return out
+    }
+    out += ch
+    r.pos++
+  }
+}
+
+function readNumber(r: Reader): number {
+  const startPos = r.pos
+  if (r.text[r.pos] === "-") r.pos++
+  while (r.pos < r.text.length && /[0-9]/.test(r.text[r.pos])) r.pos++
+  if (r.text[r.pos] === ".") {
+    r.pos++
+    while (r.pos < r.text.length && /[0-9]/.test(r.text[r.pos])) r.pos++
+  }
+  if (r.text[r.pos] === "e" || r.text[r.pos] === "E") {
+    r.pos++
+    if (r.text[r.pos] === "+" || r.text[r.pos] === "-") r.pos++
+    while (r.pos < r.text.length && /[0-9]/.test(r.text[r.pos])) r.pos++
+  }
+  const raw = r.text.slice(startPos, r.pos)
+  const n = Number(raw)
+  if (!Number.isFinite(n)) throw new ParseFail(`invalid number '${raw}'`)
+  return n
+}
+
+// Matches a bare keyword only when it is not followed by an identifier char
+// (so `truefoo` is not read as `true`).
+function matchKeyword(r: Reader, word: string): boolean {
+  if (r.text.startsWith(word, r.pos)) {
+    const after = r.text[r.pos + word.length]
+    if (after === undefined || !/[A-Za-z0-9_$]/.test(after)) {
+      r.pos += word.length
+      return true
+    }
+  }
+  return false
+}

package/src/workflow/persistence.ts

@@ -0,0 +1,312 @@
+import { Effect } from "effect"
+import path from "path"
+import { createHash } from "node:crypto"
+import { appendFileSync, mkdirSync } from "node:fs"
+import { Database, eq, desc } from "../storage"
+import { WorkflowRunTable } from "./workflow.sql"
+import { Global } from "../global"
+import type { SessionID } from "../session/schema"
+
+// Recursively sort object keys so JSON.stringify is canonical (key order in the
+// guest's opts object must not change the content key).
+function canonical(value: unknown): unknown {
+  if (value === null || typeof value !== "object") return value
+  if (Array.isArray(value)) return value.map(canonical)
+  return Object.fromEntries(
+    Object.keys(value as Record<string, unknown>)
+      .sort()
+      .map((k) => [k, canonical((value as Record<string, unknown>)[k])]),
+  )
+}
+
+// Content hash for one agent() call: sha256 over the SEMANTIC fields only
+// (prompt + agentType/model/schema/phase). label/tools/isolation are
+// display/dispatch only and are excluded so they never bust the cache.
+export function journalKeyBase(prompt: string, opts: {
+  agentType?: string
+  model?: unknown
+  schema?: unknown
+  phase?: string
+  [k: string]: unknown
+}): string {
+  const material = canonical({
+    prompt,
+    agentType: opts.agentType ?? null,
+    model: opts.model ?? null,
+    schema: opts.schema ?? null,
+    phase: opts.phase ?? null,
+  })
+  return createHash("sha256").update(JSON.stringify(material)).digest("hex")
+}
+
+// Full journal key = content hash + ":" + occurrence index, to disambiguate
+// byte-identical calls (e.g. N identical refuters) into distinct journal slots.
+export function journalKey(
+  prompt: string,
+  opts: { agentType?: string; model?: unknown; schema?: unknown; phase?: string; [k: string]: unknown },
+  occ: number,
+): string {
+  return journalKeyBase(prompt, opts) + ":" + occ
+}
+
+export type JournalEvent =
+  | { t: "agent"; key: string; result: unknown; pass: number }
+  | { t: "log"; msg: string; pass: number }
+  | { t: "phase"; title: string; pass: number }
+
+export type JournalLoad = { results: Map<string, unknown>; pass: number }
+
+export type RunSummary = {
+  runID: string
+  sessionID: SessionID
+  name: string
+  status: "running" | "completed" | "failed" | "cancelled"
+  running: number
+  succeeded: number
+  failed: number
+  currentPhase?: string
+  parentActorID?: string
+  args?: unknown
+  scriptSha?: string
+  /** The per-agent timeout this run was originally launched with (ms). Persisted
+   * so a resume that doesn't supply its own override picks the same value, instead
+   * of silently defaulting to unbounded. Undefined means the launch had no timeout. */
+  agentTimeoutMs?: number
+  error?: string
+  createdAt: number
+  updatedAt: number
+}
+
+const scriptDir = () => path.join(Global.Path.data, "workflow")
+
+// Defense in depth: persistence path functions must not trust their caller. runID
+// is interpolated directly into a filename, so a value containing a path separator
+// or dot-dot (`../../../etc/passwd`, `wf_../x`, an absolute path) would escape
+// scriptDir. The HTTP route already rejects these, but resume()/journal IO are also
+// reachable from the workflow tool and the TUI, so we re-enforce the minted shape
+// here (`wf_` + base62 — a charset with no `.` or `/`). A throw here surfaces as an
+// Effect defect: on the async IO paths (readScript/loadJournal) resume() captures it
+// via Effect.exit and treats it as not-resumable; on the synchronous journal appends
+// it fails as a defect BEFORE any appendFileSync (the caller Effect.ignore's it), so
+// a malformed runID can never touch the filesystem.
+// The `+` form (not the route's fixed `{26}`) is deliberate: this in-depth guard only
+// needs the traversal-proof property (no `.`/`/`), so it stays correct even if the
+// minted ID length changes; the strict length check lives at the route trust boundary.
+const RUN_ID = /^wf_[0-9A-Za-z]+$/
+const safeRunID = (runID: string) => {
+  if (!RUN_ID.test(runID)) throw new Error(`invalid workflow runID: ${JSON.stringify(runID)}`)
+  return runID
+}
+const scriptPath = (runID: string) => path.join(scriptDir(), `${safeRunID(runID)}.js`)
+const journalPath = (runID: string) => path.join(scriptDir(), `${safeRunID(runID)}.jsonl`)
+
+function toSummary(row: typeof WorkflowRunTable.$inferSelect): RunSummary {
+  return {
+    runID: row.id,
+    sessionID: row.session_id,
+    name: row.name,
+    status: row.status,
+    running: row.running,
+    succeeded: row.succeeded,
+    failed: row.failed,
+    ...(row.current_phase ? { currentPhase: row.current_phase } : {}),
+    ...(row.parent_actor_id ? { parentActorID: row.parent_actor_id } : {}),
+    ...(row.args !== null && row.args !== undefined ? { args: row.args } : {}),
+    ...(row.script_sha ? { scriptSha: row.script_sha } : {}),
+    ...(row.agent_timeout_ms !== null && row.agent_timeout_ms !== undefined ? { agentTimeoutMs: row.agent_timeout_ms } : {}),
+    ...(row.error ? { error: row.error } : {}),
+    createdAt: row.time_created,
+    updatedAt: row.time_updated,
+  }
+}
+
+const recordStart = (input: {
+  runID: string
+  sessionID: SessionID
+  name: string
+  parentActorID?: string
+  args?: unknown
+  scriptSha?: string
+  /** The per-agent timeout for this run, persisted so a subsequent resume
+   * (especially via TUI / API where the caller doesn't know the original
+   * launch parameters) can read it back instead of silently defaulting to
+   * unbounded — which would let a wedged mimo TTFT stall the run forever. */
+  agentTimeoutMs?: number
+}) =>
+  Effect.sync(() =>
+    Database.use((db) =>
+      db
+        .insert(WorkflowRunTable)
+        .values({
+          id: input.runID,
+          session_id: input.sessionID,
+          name: input.name,
+          status: "running",
+          running: 0,
+          succeeded: 0,
+          failed: 0,
+          parent_actor_id: input.parentActorID ?? null,
+          args: input.args ?? null,
+          script_sha: input.scriptSha ?? null,
+          agent_timeout_ms: input.agentTimeoutMs ?? null,
+        })
+        // On resume the row already exists. We reset the counters AND re-stamp the
+        // script_sha: launch passes the CURRENT script's sha, so a same-script
+        // resume re-writes the identical sha (no-op) while a changed-script relaunch
+        // (the P1-2 mismatch path) overwrites the stale sha with the new one — so a
+        // SUBSEQUENT resume of the now-current script replays correctly. The sha
+        // COMPARISON happens in resume() against load()'s pre-launch value, before
+        // this overwrite runs, so re-stamping here never hides the mismatch.
+        // agent_timeout_ms is overwritten ONLY when the caller passes one (i.e. an
+        // explicit override on resume); undefined input preserves the persisted
+        // value via the COALESCE-style guard below.
+        .onConflictDoUpdate({
+          target: WorkflowRunTable.id,
+          set: {
+            status: "running",
+            running: 0,
+            succeeded: 0,
+            failed: 0,
+            script_sha: input.scriptSha ?? null,
+            ...(input.agentTimeoutMs !== undefined ? { agent_timeout_ms: input.agentTimeoutMs } : {}),
+          },
+        })
+        .run(),
+    ),
+  )
+
+const recordPhase = (input: { runID: string; phase: string }) =>
+  Effect.sync(() =>
+    Database.use((db) =>
+      db.update(WorkflowRunTable).set({ current_phase: input.phase }).where(eq(WorkflowRunTable.id, input.runID)).run(),
+    ),
+  )
+
+const flushCounters = (input: { runID: string; running: number; succeeded: number; failed: number }) =>
+  Effect.sync(() =>
+    Database.use((db) =>
+      db
+        .update(WorkflowRunTable)
+        .set({ running: input.running, succeeded: input.succeeded, failed: input.failed })
+        .where(eq(WorkflowRunTable.id, input.runID))
+        .run(),
+    ),
+  )
+
+const recordTerminal = (input: { runID: string; status: "completed" | "failed" | "cancelled"; error?: string }) =>
+  Effect.sync(() =>
+    Database.use((db) =>
+      db
+        .update(WorkflowRunTable)
+        .set({ status: input.status, ...(input.error ? { error: input.error } : {}) })
+        .where(eq(WorkflowRunTable.id, input.runID))
+        .run(),
+    ),
+  )
+
+const list = (input?: { sessionID?: SessionID }) =>
+  Effect.sync(() =>
+    Database.use((db) => {
+      const rows = input?.sessionID
+        ? db
+            .select()
+            .from(WorkflowRunTable)
+            .where(eq(WorkflowRunTable.session_id, input.sessionID))
+            .orderBy(desc(WorkflowRunTable.time_created))
+            .all()
+        : db.select().from(WorkflowRunTable).orderBy(desc(WorkflowRunTable.time_created)).all()
+      return rows.map(toSummary)
+    }),
+  )
+
+const load = (runID: string) =>
+  Effect.sync(() =>
+    Database.use((db) => {
+      const row = db.select().from(WorkflowRunTable).where(eq(WorkflowRunTable.id, runID)).get()
+      return row ? toSummary(row) : undefined
+    }),
+  )
+
+const writeScript = (runID: string, body: string) =>
+  Effect.promise(async () => {
+    const fs = await import("fs/promises")
+    await fs.mkdir(scriptDir(), { recursive: true })
+    await Bun.write(scriptPath(runID), body)
+  })
+
+const readScript = (runID: string) => Effect.promise(() => Bun.file(scriptPath(runID)).text())
+
+const appendJournal = (runID: string, event: JournalEvent) =>
+  Effect.promise(async () => {
+    const fs = await import("fs/promises")
+    await fs.mkdir(scriptDir(), { recursive: true })
+    await fs.appendFile(journalPath(runID), JSON.stringify(event) + "\n")
+  })
+
+// Synchronous append (one or a batch of events). Called PER-AGENT from the
+// agent() hook the instant a spawn succeeds, so each result is durable on disk
+// immediately — a mid-run process exit / SIGKILL / deadline leaves a journal
+// containing every completed agent, which is what makes resume replay them
+// (durability does NOT wait for run completion). It is SYNCHRONOUS on purpose:
+// an Effect.promise(async fs) append suspends the calling fiber on a macrotask,
+// which empirically starves the quickjs sandbox pump (the guest's own promise
+// stops being driven); a sync write completes in one scheduler slice and never
+// yields the pump. Empty batch is a no-op (no mkdir/open). Errors propagate as a
+// defect for Effect.ignore.
+const appendJournalSync = (runID: string, events: JournalEvent[]) =>
+  Effect.sync(() => {
+    if (events.length === 0) return
+    mkdirSync(scriptDir(), { recursive: true })
+    appendFileSync(journalPath(runID), events.map((e) => JSON.stringify(e) + "\n").join(""))
+  })
+
+const loadJournal = (runID: string): Effect.Effect<JournalLoad> =>
+  Effect.promise(async () => {
+    const file = Bun.file(journalPath(runID))
+    if (!(await file.exists())) return { results: new Map(), pass: 1 }
+    const text = await file.text()
+    const results = new Map<string, unknown>()
+    let maxPass = 0
+    for (const line of text.split("\n")) {
+      if (!line) continue
+      let ev: JournalEvent
+      try {
+        ev = JSON.parse(line) as JournalEvent
+      } catch {
+        continue // torn/partial line (crash mid-append) — skip
+      }
+      if (typeof ev.pass === "number" && ev.pass > maxPass) maxPass = ev.pass
+      if (ev.t === "agent") results.set(ev.key, ev.result)
+    }
+    return { results, pass: maxPass + 1 }
+  })
+
+// Truncate the journal to empty (MR104 P1-2). Called on the resume sha-mismatch
+// path BEFORE the fresh relaunch appends: replaying the OLD journal onto an EDITED
+// script is silent divergence, so the stale lines must not survive — and a fresh
+// run must not interleave its appends with them (a LATER resume's loadJournal would
+// otherwise read both old + new → wrong replay). We truncate (write "") rather than
+// delete so the file always exists for a concurrent reader; loadJournal treats an
+// empty file as "no results, pass 1" exactly like a missing one. mkdir first so the
+// truncate cannot fail on a never-written run (no journal yet → still ends empty).
+const clearJournal = (runID: string) =>
+  Effect.promise(async () => {
+    const fs = await import("fs/promises")
+    await fs.mkdir(scriptDir(), { recursive: true })
+    await Bun.write(journalPath(runID), "")
+  })
+
+export const WorkflowPersistence = {
+  recordStart,
+  recordPhase,
+  flushCounters,
+  recordTerminal,
+  list,
+  load,
+  writeScript,
+  readScript,
+  appendJournal,
+  appendJournalSync,
+  loadJournal,
+  clearJournal,
+}

package/src/workflow/resolve.ts

@@ -0,0 +1,45 @@
+import path from "path"
+import { Filesystem } from "@/util"
+
+// A first arg to workflow() is an inline script when it contains the mandatory
+// meta export anywhere (real scripts may have a leading comment/whitespace);
+// otherwise it is a bare saved-workflow name to resolve from the workflows dir.
+const META_RE = /export\s+const\s+meta\s*=/
+
+export function isInlineScript(nameOrScript: string): boolean {
+  return META_RE.test(nameOrScript)
+}
+
+// Walk from `start` up to `stop` (the worktree root), checking
+// .tulingcode/workflows/<name>.js then .claude/workflows/<name>.js at each level.
+// First hit wins, nearest-first (project dir overrides a higher-level one) —
+// mirrors how skills/commands resolve named user files. Returns the script body
+// or null if no file matches (the caller turns null into a thrown, fail-loud
+// "unknown workflow"). A bare name is constrained to a single path segment so it
+// can never inject a separator and escape the workflows dir.
+const SAFE_NAME = /^[A-Za-z0-9._-]+$/
+
+export async function resolveWorkflowScript(name: string, start: string, stop: string): Promise<string | null> {
+  if (!SAFE_NAME.test(name)) throw new Error(`invalid workflow name: ${JSON.stringify(name)}`)
+  const subdirs = [".tulingcode/workflows", ".claude/workflows"]
+  for (const found of await collectUp(name, subdirs, start, stop)) {
+    return Filesystem.readText(found)
+  }
+  return null
+}
+
+async function collectUp(name: string, subdirs: string[], start: string, stop: string): Promise<string[]> {
+  const out: string[] = []
+  let current = start
+  for (;;) {
+    for (const sub of subdirs) {
+      const candidate = path.join(current, sub, `${name}.js`)
+      if (await Filesystem.exists(candidate)) out.push(candidate)
+    }
+    if (current === stop) break
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return out
+}