@lchase/yak 0.1.0

package/dist/index.js

@@ -0,0 +1,2771 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/cli/commands/artifacts.ts
+import path16 from "path";
+
+// src/engine/artifacts.ts
+import { randomUUID } from "crypto";
+import { mkdir, readdir, readFile, rename, writeFile } from "fs/promises";
+import path from "path";
+import { z } from "zod";
+
+// src/util/hash.ts
+import { createHash } from "crypto";
+function sha256(input) {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+// src/engine/artifacts.ts
+async function writeFileAtomic(finalPath, content) {
+  const tmpPath = path.join(path.dirname(finalPath), `.${path.basename(finalPath)}.${randomUUID()}.tmp`);
+  await writeFile(tmpPath, content, "utf8");
+  await rename(tmpPath, finalPath);
+}
+function artifactPath(runDir, name, iteration) {
+  const fileName = iteration === void 0 ? `${name}.json` : `${name}.${iteration}.json`;
+  return path.join(runDir, "artifacts", fileName);
+}
+async function writeArtifact(runDir, name, value, schema, iteration) {
+  const parsed = schema.parse(value);
+  const json = JSON.stringify(parsed, null, 2);
+  await mkdir(path.join(runDir, "artifacts"), { recursive: true });
+  const filePath = artifactPath(runDir, name, iteration);
+  await writeFileAtomic(filePath, json);
+  return { name, hash: sha256(json), bytes: Buffer.byteLength(json), path: filePath };
+}
+async function readArtifact(runDir, name, schema, iteration) {
+  const json = await readFile(artifactPath(runDir, name, iteration), "utf8");
+  return schema.parse(JSON.parse(json));
+}
+async function readArtifactRaw(runDir, name, iteration) {
+  return readArtifact(runDir, name, z.unknown(), iteration);
+}
+async function readArtifactRawOrUndefined(runDir, name) {
+  try {
+    return await readArtifactRaw(runDir, name);
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+}
+async function listMapItemArtifacts(runDir, produces) {
+  const dir = path.join(runDir, "artifacts");
+  const entries = await readdir(dir).catch(() => []);
+  const escaped = produces.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^${escaped}\\.(\\d+)\\.json$`);
+  return entries.map((name) => re.exec(name)).filter((m) => m !== null).map((m) => Number(m[1])).sort((a, b) => a - b);
+}
+async function writeRejectedOutput(runDir, stepId, attempt, content) {
+  const dir = path.join(runDir, "artifacts", ".rejected");
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, `${stepId}.${attempt}.txt`);
+  await writeFileAtomic(filePath, content);
+  return filePath;
+}
+
+// src/engine/run.ts
+import { randomBytes as randomBytes2 } from "crypto";
+import { mkdir as mkdir6, readdir as readdir2, readFile as readFile9, writeFile as writeFile4 } from "fs/promises";
+import path15 from "path";
+
+// src/ir/graph.ts
+function buildProducerMap(steps) {
+  const producerOf = /* @__PURE__ */ new Map();
+  for (const step of steps) {
+    if (step.produces) producerOf.set(step.produces, step.id);
+  }
+  return producerOf;
+}
+function agentInputNames(step) {
+  const names = new Set(step.needs ?? []);
+  if (typeof step.context === "object" && "inherit" in step.context) {
+    for (const name of step.context.inherit) names.add(name);
+  }
+  return [...names];
+}
+function mapInputNames(step) {
+  const names = new Set(step.needs ?? []);
+  names.add(step.over);
+  return [...names];
+}
+function inputNamesOf(step) {
+  if (step.kind === "agent") return agentInputNames(step);
+  if (step.kind === "map") return mapInputNames(step);
+  return step.needs ?? [];
+}
+function dependenciesOf(step, producerOf) {
+  return inputNamesOf(step).map((need) => producerOf.get(need)).filter((id) => id !== void 0);
+}
+function flattenSteps(steps) {
+  const result = [];
+  for (const step of steps) {
+    result.push(step);
+    if (step.kind === "loop") result.push(...flattenSteps(step.body));
+    if (step.kind === "map") result.push(...flattenSteps([step.step]));
+  }
+  return result;
+}
+function renderMermaid(workflow) {
+  const producerOf = buildProducerMap(flattenSteps(workflow.steps));
+  const lines = ["flowchart TD"];
+  renderStepList(workflow.steps, producerOf, lines);
+  return lines.join("\n");
+}
+function renderStepList(steps, producerOf, lines) {
+  for (const step of steps) {
+    const nested = step.kind === "loop" ? step.body : step.kind === "map" ? [step.step] : void 0;
+    if (nested) {
+      lines.push(`  subgraph ${step.id}`);
+      renderStepList(nested, producerOf, lines);
+      lines.push("  end");
+    } else {
+      lines.push(`  ${step.id}[${step.id}]`);
+    }
+    for (const name of inputNamesOf(step)) {
+      const producer = producerOf.get(name);
+      if (producer) lines.push(`  ${producer} -->|${name}| ${step.id}`);
+    }
+  }
+}
+
+// src/ir/load.ts
+import { readFile as readFile2 } from "fs/promises";
+import { parse } from "yaml";
+async function loadWorkflowYaml(filePath) {
+  const contents = await readFile2(filePath, "utf8");
+  return parse(contents);
+}
+
+// src/ir/normalize.ts
+import { z as z2 } from "zod";
+var rawCommandSchema = z2.object({
+  run: z2.string(),
+  cwd: z2.string().optional(),
+  failOn: z2.enum(["exitCode", "never"]).optional(),
+  capture: z2.array(z2.enum(["stdout", "stderr", "exitCode"])).optional()
+});
+var rawTransformSchema = z2.object({
+  fn: z2.string()
+});
+var rawAgentContextSchema = z2.union([
+  z2.literal("fresh"),
+  z2.object({ inherit: z2.array(z2.string()) }),
+  z2.object({ session: z2.string() })
+]);
+var rawSchemaSpecSchema = z2.union([z2.string(), z2.object({ inline: z2.record(z2.unknown()) })]);
+var rawAgentSchema = z2.object({
+  prompt: z2.union([z2.object({ file: z2.string() }), z2.object({ inline: z2.string() })]),
+  schema: rawSchemaSpecSchema.optional(),
+  context: rawAgentContextSchema.optional(),
+  tools: z2.array(z2.string()).optional(),
+  model: z2.string().optional(),
+  repairAttempts: z2.number().optional()
+});
+var rawExprSchema = z2.union([z2.string(), z2.object({ fn: z2.string() })]);
+var rawGateSchema = z2.object({
+  schema: rawSchemaSpecSchema,
+  render: z2.union([z2.object({ file: z2.string() }), z2.object({ inline: z2.string() })])
+});
+var rawBudgetSchema = z2.object({
+  maxIterations: z2.number(),
+  maxTokens: z2.number().optional(),
+  maxUsd: z2.number().optional(),
+  noProgress: z2.object({ signal: rawExprSchema, rounds: z2.number() }).optional()
+});
+var rawStepSchema = z2.lazy(
+  () => z2.object({
+    id: z2.string(),
+    needs: z2.array(z2.string()).optional(),
+    produces: z2.string().optional(),
+    cache: z2.enum(["strict", "loose"]).optional(),
+    skipIf: rawExprSchema.optional(),
+    finally: z2.boolean().optional(),
+    command: rawCommandSchema.optional(),
+    transform: rawTransformSchema.optional(),
+    agent: rawAgentSchema.optional(),
+    gate: rawGateSchema.optional(),
+    loop: z2.object({
+      until: rawExprSchema,
+      budget: rawBudgetSchema,
+      onExhausted: z2.enum(["suspend", "fail", "continue"]).optional(),
+      freshContext: z2.boolean().optional(),
+      body: z2.array(rawStepSchema)
+    }).optional(),
+    map: z2.object({
+      over: z2.string(),
+      step: rawStepSchema,
+      concurrency: z2.number().optional(),
+      isolation: z2.enum(["worktree", "none"]).optional(),
+      onItemFailure: z2.enum(["skip", "fail", "retry"]).optional()
+    }).optional()
+  })
+);
+var rawWorkflowSchema = z2.object({
+  name: z2.string(),
+  version: z2.string(),
+  inputSchema: z2.string().optional(),
+  steps: z2.array(rawStepSchema)
+});
+function normalizeStep(raw) {
+  if (raw.command) {
+    const step = {
+      id: raw.id,
+      needs: raw.needs ?? [],
+      cache: raw.cache ?? "strict",
+      kind: "command",
+      run: raw.command.run,
+      failOn: raw.command.failOn ?? "exitCode",
+      capture: raw.command.capture ?? ["stdout", "stderr", "exitCode"],
+      ...raw.produces !== void 0 ? { produces: raw.produces } : {},
+      ...raw.command.cwd !== void 0 ? { cwd: raw.command.cwd } : {},
+      ...raw.skipIf !== void 0 ? { skipIf: raw.skipIf } : {},
+      ...raw.finally !== void 0 ? { finally: raw.finally } : {}
+    };
+    return step;
+  }
+  if (raw.transform) {
+    const step = {
+      id: raw.id,
+      needs: raw.needs ?? [],
+      cache: raw.cache ?? "strict",
+      kind: "transform",
+      fn: raw.transform.fn,
+      ...raw.produces !== void 0 ? { produces: raw.produces } : {},
+      ...raw.skipIf !== void 0 ? { skipIf: raw.skipIf } : {},
+      ...raw.finally !== void 0 ? { finally: raw.finally } : {}
+    };
+    return step;
+  }
+  if (raw.agent) {
+    const step = {
+      id: raw.id,
+      needs: raw.needs ?? [],
+      cache: raw.cache ?? "strict",
+      kind: "agent",
+      prompt: raw.agent.prompt,
+      ...raw.agent.schema !== void 0 ? { schema: raw.agent.schema } : {},
+      ...raw.agent.context !== void 0 ? { context: raw.agent.context } : {},
+      ...raw.agent.tools !== void 0 ? { tools: raw.agent.tools } : {},
+      ...raw.agent.model !== void 0 ? { model: raw.agent.model } : {},
+      ...raw.agent.repairAttempts !== void 0 ? { repairAttempts: raw.agent.repairAttempts } : {},
+      ...raw.produces !== void 0 ? { produces: raw.produces } : {},
+      ...raw.skipIf !== void 0 ? { skipIf: raw.skipIf } : {},
+      ...raw.finally !== void 0 ? { finally: raw.finally } : {}
+    };
+    return step;
+  }
+  if (raw.gate) {
+    const step = {
+      id: raw.id,
+      needs: raw.needs ?? [],
+      cache: raw.cache ?? "strict",
+      kind: "gate",
+      schema: raw.gate.schema,
+      render: raw.gate.render,
+      ...raw.skipIf !== void 0 ? { skipIf: raw.skipIf } : {},
+      ...raw.finally !== void 0 ? { finally: raw.finally } : {},
+      ...raw.produces !== void 0 ? { produces: raw.produces } : {}
+    };
+    return step;
+  }
+  if (raw.loop) {
+    const step = {
+      id: raw.id,
+      needs: raw.needs ?? [],
+      cache: raw.cache ?? "strict",
+      kind: "loop",
+      body: raw.loop.body.map(normalizeStep),
+      until: raw.loop.until,
+      budget: raw.loop.budget,
+      onExhausted: raw.loop.onExhausted ?? "suspend",
+      freshContext: raw.loop.freshContext ?? true,
+      ...raw.produces !== void 0 ? { produces: raw.produces } : {}
+    };
+    return step;
+  }
+  if (raw.map) {
+    const step = {
+      id: raw.id,
+      needs: raw.needs ?? [],
+      cache: raw.cache ?? "strict",
+      kind: "map",
+      over: raw.map.over,
+      step: normalizeStep(raw.map.step),
+      concurrency: raw.map.concurrency ?? 4,
+      // Ticket 07: the M3 loader default is 'none', not 'worktree' — real
+      // worktree isolation is M5's job, and requesting it explicitly is a
+      // load-time error (checked in ir/validate.ts), never a silent no-op.
+      isolation: raw.map.isolation ?? "none",
+      onItemFailure: raw.map.onItemFailure ?? "skip",
+      ...raw.produces !== void 0 ? { produces: raw.produces } : {}
+    };
+    return step;
+  }
+  throw new Error(
+    `step "${raw.id}": only "command", "transform", "agent", "gate", "loop", and "map" steps are supported`
+  );
+}
+function normalizeWorkflow(raw) {
+  const parsed = rawWorkflowSchema.parse(raw);
+  return {
+    name: parsed.name,
+    version: parsed.version,
+    ...parsed.inputSchema !== void 0 ? { inputSchema: parsed.inputSchema } : {},
+    steps: parsed.steps.map(normalizeStep)
+  };
+}
+
+// src/ir/validate.ts
+import { execFile } from "child_process";
+import { readFile as readFile3 } from "fs/promises";
+import path3 from "path";
+import { promisify } from "util";
+
+// src/expr/template.ts
+import jexl from "jexl";
+var PLACEHOLDER_RE = /\{\{\s*([^}]+?)\s*\}\}/g;
+function extractTemplateRoots(template) {
+  const roots = /* @__PURE__ */ new Set();
+  for (const match of template.matchAll(PLACEHOLDER_RE)) {
+    const expr = match[1].trim();
+    const root = expr.split(/[.[]/, 1)[0];
+    if (root) roots.add(root);
+  }
+  return [...roots];
+}
+async function renderTemplate(template, inputs) {
+  let result = "";
+  let lastIndex = 0;
+  for (const match of template.matchAll(PLACEHOLDER_RE)) {
+    const [full, exprRaw] = match;
+    const expr = exprRaw.trim();
+    const start = match.index;
+    const value = await jexl.eval(expr, inputs);
+    if (value === void 0) {
+      throw new Error(`prompt template placeholder "{{${expr}}}" resolved to undefined`);
+    }
+    result += template.slice(lastIndex, start);
+    result += typeof value === "string" ? value : JSON.stringify(value);
+    lastIndex = start + full.length;
+  }
+  result += template.slice(lastIndex);
+  return result;
+}
+
+// src/ir/schema-resolve.ts
+import path2 from "path";
+import { pathToFileURL } from "url";
+import { Ajv } from "ajv";
+import { ZodBoolean, ZodDefault, ZodEnum, ZodNumber, ZodObject, ZodOptional, ZodString, ZodType } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+async function resolveZodSchema(name, cwd) {
+  const modulePath = path2.resolve(cwd, ".yak/schemas.ts");
+  const mod = await import(pathToFileURL(modulePath).href);
+  const schema = mod[name];
+  if (!(schema instanceof ZodType)) {
+    throw new Error(`schema "${name}" not found in .yak/schemas.ts`);
+  }
+  return schema;
+}
+function formatZodError(error) {
+  return error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("\n");
+}
+var ZodResolvedSchema = class {
+  constructor(schema) {
+    this.schema = schema;
+  }
+  schema;
+  toJsonSchema(name) {
+    return name === void 0 ? zodToJsonSchema(this.schema) : zodToJsonSchema(this.schema, name);
+  }
+  safeParse(value) {
+    const parsed = this.schema.safeParse(value);
+    if (parsed.success) return { success: true, data: parsed.data };
+    return { success: false, errorSummary: formatZodError(parsed.error) };
+  }
+  parseDefaults() {
+    return this.safeParse({});
+  }
+  isFlatAnswerObject() {
+    if (!(this.schema instanceof ZodObject)) {
+      return { ok: false, reason: "must be a top-level object" };
+    }
+    for (const [field, fieldSchemaRaw] of Object.entries(this.schema.shape)) {
+      let fieldSchema = fieldSchemaRaw;
+      while (fieldSchema instanceof ZodOptional || fieldSchema instanceof ZodDefault) {
+        fieldSchema = fieldSchema instanceof ZodOptional ? fieldSchema.unwrap() : fieldSchema._def.innerType;
+      }
+      const isScalar = fieldSchema instanceof ZodString || fieldSchema instanceof ZodNumber || fieldSchema instanceof ZodBoolean;
+      if (!isScalar && !(fieldSchema instanceof ZodEnum)) {
+        return { ok: false, reason: `field "${field}" is not a flat scalar/enum type` };
+      }
+    }
+    return { ok: true };
+  }
+};
+var ajv = new Ajv({ useDefaults: true, allErrors: true, strict: false });
+function formatAjvErrors(errors) {
+  return errors.map((err) => `${err.instancePath.replace(/^\//, "").replace(/\//g, ".")}: ${err.message}`).join("\n");
+}
+var JsonResolvedSchema = class {
+  constructor(schema) {
+    this.schema = schema;
+    this.validateFn = ajv.compile(schema);
+  }
+  schema;
+  validateFn;
+  toJsonSchema() {
+    return this.schema;
+  }
+  safeParse(value) {
+    const data = value !== null && typeof value === "object" ? structuredClone(value) : value;
+    const valid = this.validateFn(data);
+    if (valid) return { success: true, data };
+    return { success: false, errorSummary: formatAjvErrors(this.validateFn.errors ?? []) };
+  }
+  parseDefaults() {
+    return this.safeParse({});
+  }
+  isFlatAnswerObject() {
+    const schema = this.schema;
+    if (schema.type !== "object" || typeof schema.properties !== "object" || schema.properties === null) {
+      return { ok: false, reason: "must be a top-level object" };
+    }
+    for (const [field, fieldSchemaRaw] of Object.entries(schema.properties)) {
+      const type = fieldSchemaRaw.type;
+      const isScalar = type === "string" || type === "number" || type === "integer" || type === "boolean";
+      const isEnum = Array.isArray(fieldSchemaRaw.enum);
+      if (!isScalar && !isEnum) {
+        return { ok: false, reason: `field "${field}" is not a flat scalar/enum type` };
+      }
+    }
+    return { ok: true };
+  }
+};
+function wrapZodSchema(schema) {
+  return new ZodResolvedSchema(schema);
+}
+async function resolveSchemaSpec(spec, cwd) {
+  if (typeof spec === "string") {
+    return new ZodResolvedSchema(await resolveZodSchema(spec, cwd));
+  }
+  return new JsonResolvedSchema(spec.inline);
+}
+function describeSchemaSpec(spec) {
+  return typeof spec === "string" ? `"${spec}"` : "inline schema";
+}
+
+// src/ir/validate.ts
+var WorkflowValidationError = class extends Error {
+};
+var KNOWN_KINDS = /* @__PURE__ */ new Set(["agent", "command", "transform", "gate", "map", "loop"]);
+var KNOWN_AGENT_TOOLS = /* @__PURE__ */ new Set([
+  "Read",
+  "Edit",
+  "Write",
+  "Bash",
+  "Grep",
+  "Glob",
+  "WebFetch",
+  "WebSearch",
+  "NotebookEdit",
+  "TodoWrite",
+  "Task",
+  "Skill"
+]);
+async function validateWorkflow(workflow, cwd = process.cwd(), runIsolation = "none") {
+  const flatSteps = flattenSteps(workflow.steps);
+  checkKnownKinds(flatSteps);
+  checkDuplicateIds(flatSteps);
+  const producerOf = buildProducerMap(workflow.steps);
+  checkNeedsSatisfied(workflow.steps, producerOf);
+  checkNoCycles(workflow.steps, producerOf);
+  checkExitCodeReads(workflow.steps, producerOf);
+  checkAgentToolNames(flatSteps);
+  await checkAgentSchemaKeys(flatSteps, cwd);
+  await checkAgentPromptPlaceholders(flatSteps, cwd);
+  checkSessionChainDepth(flatSteps);
+  checkMapIsolation(workflow.steps, runIsolation);
+  await checkGateSchemaKeys(flatSteps, cwd);
+  await checkGateRenderPlaceholders(flatSteps, cwd);
+  checkSandboxImage(flatSteps);
+  await checkDockerAvailable(flatSteps);
+}
+function checkSandboxImage(steps) {
+  for (const step of steps) {
+    if (step.kind !== "command" || step.sandbox !== "docker") continue;
+    if (!step.image) {
+      throw new WorkflowValidationError(
+        `step "${step.id}": sandbox: 'docker' requires an "image" field \u2014 yak has no default image`
+      );
+    }
+  }
+}
+var execFileAsync = promisify(execFile);
+async function checkDockerAvailable(steps) {
+  const needsDocker = (step) => (step.kind === "command" || step.kind === "agent") && step.sandbox === "docker";
+  if (!steps.some(needsDocker)) return;
+  try {
+    await execFileAsync("docker", ["--version"]);
+  } catch {
+    throw new WorkflowValidationError(
+      `workflow uses sandbox: 'docker' on at least one step, but the "docker" binary was not found on PATH`
+    );
+  }
+}
+var WRITE_CAPABLE_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "Bash"]);
+function checkMapIsolation(steps, runIsolation) {
+  for (const step of steps) {
+    if (step.kind === "loop") checkMapIsolation(step.body, runIsolation);
+    if (step.kind !== "map") continue;
+    if (step.isolation === "worktree") {
+      if (runIsolation !== "worktree") {
+        throw new WorkflowValidationError(
+          `step "${step.id}": isolation: 'worktree' requires the run itself to use --isolation worktree (there's no run branch to fork an item worktree from otherwise) \u2014 use isolation: 'none' or omit isolation, or run with --isolation worktree`
+        );
+      }
+    } else {
+      const concurrency = step.concurrency ?? 4;
+      if (concurrency > 1 && step.step.kind === "agent") {
+        const writeTool = (step.step.tools ?? []).find((tool) => WRITE_CAPABLE_TOOLS.has(tool));
+        if (writeTool) {
+          throw new WorkflowValidationError(
+            `step "${step.id}": isolation: 'none' with concurrency ${concurrency} and item step "${step.step.id}" declaring write-capable tool "${writeTool}" \u2014 concurrent items would share one cwd and race; use concurrency: 1 or drop the write-capable tool`
+          );
+        }
+      }
+    }
+    checkMapIsolation([step.step], runIsolation);
+  }
+}
+function checkAgentToolNames(steps) {
+  for (const step of steps) {
+    if (step.kind !== "agent") continue;
+    for (const tool of step.tools ?? []) {
+      if (!KNOWN_AGENT_TOOLS.has(tool)) {
+        throw new WorkflowValidationError(
+          `step "${step.id}": unknown or unsupported tool "${tool}" \u2014 must be one of ${[...KNOWN_AGENT_TOOLS].join(", ")}`
+        );
+      }
+    }
+  }
+}
+function checkKnownKinds(steps) {
+  for (const step of steps) {
+    if (!KNOWN_KINDS.has(step.kind)) {
+      throw new WorkflowValidationError(`step "${step.id}": unknown step kind "${step.kind}"`);
+    }
+  }
+}
+function checkDuplicateIds(steps) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const step of steps) {
+    if (seen.has(step.id)) {
+      throw new WorkflowValidationError(`duplicate step id "${step.id}"`);
+    }
+    seen.add(step.id);
+  }
+}
+function checkNeedsSatisfied(steps, producerOf) {
+  for (const step of steps) {
+    for (const need of step.needs ?? []) {
+      if (!producerOf.has(need)) {
+        throw new WorkflowValidationError(
+          `step "${step.id}": needs artifact "${need}" but no step produces it`
+        );
+      }
+    }
+    if (step.kind === "loop") {
+      const localProducerOf = new Map([...producerOf, ...buildProducerMap(step.body)]);
+      checkNeedsSatisfied(step.body, localProducerOf);
+    }
+    if (step.kind === "map") {
+      checkNeedsSatisfied([step.step], producerOf);
+    }
+  }
+}
+function checkNoCycles(steps, producerOf) {
+  const stepsById = new Map(steps.map((s) => [s.id, s]));
+  const state = /* @__PURE__ */ new Map();
+  function visit(step, path21) {
+    const mark = state.get(step.id);
+    if (mark === "done") return;
+    if (mark === "visiting") {
+      const cycle = [...path21, step.id].join(" -> ");
+      throw new WorkflowValidationError(`cycle detected: ${cycle}`);
+    }
+    state.set(step.id, "visiting");
+    for (const depId of dependenciesOf(step, producerOf)) {
+      const dep = stepsById.get(depId);
+      if (dep) visit(dep, [...path21, step.id]);
+    }
+    state.set(step.id, "done");
+  }
+  for (const step of steps) visit(step, []);
+}
+function checkExitCodeReads(steps, producerOf) {
+  const stepsById = new Map(steps.map((s) => [s.id, s]));
+  for (const step of steps) {
+    for (const expr of exprsIn(step)) {
+      for (const artifactName of exitCodeReferences(expr)) {
+        const producerId = producerOf.get(artifactName);
+        if (!producerId) continue;
+        const producer = stepsById.get(producerId);
+        if (producer?.kind === "command" && (producer.failOn ?? "exitCode") === "exitCode") {
+          throw new WorkflowValidationError(
+            `step "${step.id}" reads "${artifactName}.exitCode", but step "${producer.id}" has failOn: 'exitCode' \u2014 that step can never produce a non-zero exitCode`
+          );
+        }
+      }
+    }
+  }
+}
+function exprsIn(step) {
+  const exprs = [];
+  if (step.skipIf) exprs.push(step.skipIf);
+  if (step.kind === "loop") {
+    exprs.push(step.until);
+    if (step.budget.noProgress) exprs.push(step.budget.noProgress.signal);
+    for (const inner of step.body) exprs.push(...exprsIn(inner));
+  }
+  if (step.kind === "map") exprs.push(...exprsIn(step.step));
+  return exprs;
+}
+function exitCodeReferences(expr) {
+  if (typeof expr !== "string") return [];
+  const matches = [...expr.matchAll(/([A-Za-z_][A-Za-z0-9_-]*)\.exitCode\b/g)];
+  return matches.map((m) => m[1]);
+}
+async function checkAgentSchemaKeys(steps, cwd) {
+  for (const step of steps) {
+    if (step.kind !== "agent" || !step.schema) continue;
+    await checkSchemaSpecResolves(step.id, step.schema, cwd);
+  }
+}
+async function checkSchemaSpecResolves(stepId, spec, cwd) {
+  try {
+    await resolveSchemaSpec(spec, cwd);
+  } catch (err) {
+    throw new WorkflowValidationError(
+      `step "${stepId}": could not resolve schema ${describeSchemaSpec(spec)}: ${err.message}`
+    );
+  }
+}
+async function checkGateSchemaKeys(steps, cwd) {
+  for (const step of steps) {
+    if (step.kind !== "gate") continue;
+    await checkSchemaSpecResolves(step.id, step.schema, cwd);
+    const schema = await resolveSchemaSpec(step.schema, cwd);
+    if (step.skipIf !== void 0) {
+      const defaulted = schema.parseDefaults();
+      if (!defaulted.success) {
+        throw new WorkflowValidationError(
+          `step "${step.id}": has skipIf but schema ${describeSchemaSpec(step.schema)} doesn't default every field (parsing {} failed: ${defaulted.errorSummary}) \u2014 every field needs a default so a skip can synthesize the answer artifact`
+        );
+      }
+    }
+    checkFlatAnswerSchema(step, schema);
+  }
+}
+function checkFlatAnswerSchema(step, schema) {
+  const check = schema.isFlatAnswerObject();
+  if (!check.ok) {
+    throw new WorkflowValidationError(
+      `step "${step.id}": schema ${describeSchemaSpec(step.schema)} ${check.reason} \u2014 --interactive can only render string/number/boolean/enum properties`
+    );
+  }
+}
+async function checkGateRenderPlaceholders(steps, cwd) {
+  for (const step of steps) {
+    if (step.kind !== "gate") continue;
+    const text = "file" in step.render ? await readFile3(path3.resolve(cwd, step.render.file), "utf8") : step.render.inline;
+    const allowed = new Set(step.needs ?? []);
+    for (const root of extractTemplateRoots(text)) {
+      if (!allowed.has(root)) {
+        throw new WorkflowValidationError(
+          `step "${step.id}": render references "{{${root}}}" but "${root}" is not in needs`
+        );
+      }
+    }
+  }
+}
+async function checkAgentPromptPlaceholders(steps, cwd) {
+  for (const step of steps) {
+    if (step.kind !== "agent") continue;
+    const text = "file" in step.prompt ? await readFile3(path3.resolve(cwd, step.prompt.file), "utf8") : step.prompt.inline;
+    const allowed = new Set(agentInputNames(step));
+    for (const root of extractTemplateRoots(text)) {
+      if (!allowed.has(root)) {
+        throw new WorkflowValidationError(
+          `step "${step.id}": prompt references "{{${root}}}" but "${root}" is not in needs or context.inherit`
+        );
+      }
+    }
+  }
+}
+function checkSessionChainDepth(steps) {
+  const stepsById = new Map(steps.map((s) => [s.id, s]));
+  function sessionParentOf(step) {
+    if (step.kind !== "agent") return void 0;
+    if (typeof step.context !== "object" || !("session" in step.context)) return void 0;
+    return step.context.session;
+  }
+  for (const step of steps) {
+    if (step.kind !== "agent") continue;
+    let depth = 0;
+    let current = sessionParentOf(step);
+    const seen = /* @__PURE__ */ new Set([step.id]);
+    while (current !== void 0 && !seen.has(current)) {
+      seen.add(current);
+      depth += 1;
+      const parentStep = stepsById.get(current);
+      current = parentStep ? sessionParentOf(parentStep) : void 0;
+    }
+    if (depth > 3) {
+      console.warn(
+        `step "${step.id}": context.session chain exceeds depth 3 (depth ${depth}) \u2014 spec \xA73.4 discourages long resume chains`
+      );
+    }
+  }
+}
+
+// src/steps/gate.ts
+import { readFile as readFile6 } from "fs/promises";
+import path7 from "path";
+import { z as z4 } from "zod";
+
+// src/engine/journal.ts
+import { appendFile, mkdir as mkdir2, readFile as readFile4 } from "fs/promises";
+import path4 from "path";
+function journalPath(runDir) {
+  return path4.join(runDir, "journal.jsonl");
+}
+async function appendJournalEvent(runDir, runId, event) {
+  const envelope = { ...event, at: (/* @__PURE__ */ new Date()).toISOString(), runId };
+  await mkdir2(runDir, { recursive: true });
+  await appendFile(journalPath(runDir), `${JSON.stringify(envelope)}
+`, "utf8");
+}
+async function readJournal(runDir) {
+  const contents = await readFile4(journalPath(runDir), "utf8").catch(() => "");
+  return contents.split("\n").filter((line) => line.trim().length > 0).map((line) => JSON.parse(line));
+}
+function completedStepsFromJournal(events) {
+  const started = /* @__PURE__ */ new Map();
+  const completed = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    if (event.t === "step.started") {
+      started.set(event.stepId, { semanticKey: event.semanticKey, definitionKey: event.definitionKey });
+      completed.delete(event.stepId);
+    } else if (event.t === "step.completed") {
+      const info = started.get(event.stepId);
+      if (info) {
+        completed.set(event.stepId, {
+          stepId: event.stepId,
+          semanticKey: info.semanticKey,
+          definitionKey: info.definitionKey,
+          ...event.artifact !== void 0 ? { artifact: event.artifact } : {},
+          ...event.artifactHash !== void 0 ? { artifactHash: event.artifactHash } : {}
+        });
+      }
+    } else if (event.t === "step.failed") {
+      completed.delete(event.stepId);
+    }
+  }
+  return completed;
+}
+
+// src/engine/suspend.ts
+import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
+import path5 from "path";
+import { z as z3 } from "zod";
+var LoopExhaustionAnswerSchema = z3.object({
+  action: z3.enum(["continue", "abort"]),
+  addIterations: z3.number().optional()
+});
+function requestPath(runDir, stepId) {
+  return path5.join(runDir, "pending", `${stepId}.request.json`);
+}
+function answerPath(runDir, stepId) {
+  return path5.join(runDir, "pending", `${stepId}.answer.json`);
+}
+async function writeRequest(runDir, runId, request) {
+  await mkdir3(path5.join(runDir, "pending"), { recursive: true });
+  await writeFile2(requestPath(runDir, request.stepId), JSON.stringify(request, null, 2), "utf8");
+  await appendJournalEvent(runDir, runId, {
+    t: "gate.opened",
+    stepId: request.stepId,
+    requestPath: requestPath(runDir, request.stepId)
+  });
+}
+async function writeGateRequest(runDir, runId, step, rendered, answerSchema) {
+  await writeRequest(runDir, runId, {
+    kind: "gate",
+    stepId: step.id,
+    runId,
+    rendered,
+    answerSchema,
+    context: { artifacts: step.needs ?? [] },
+    openedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+async function writeLoopExhaustedRequest(runDir, runId, stepId, iteration, tripped) {
+  await writeRequest(runDir, runId, {
+    kind: "loop-exhausted",
+    stepId,
+    runId,
+    tripped,
+    iteration,
+    answerSchema: loopExhaustionJsonSchema(),
+    openedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+function loopExhaustionJsonSchema() {
+  return {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["continue", "abort"] },
+      addIterations: { type: "number" }
+    },
+    required: ["action"]
+  };
+}
+async function readPendingRequest(runDir, stepId) {
+  const raw = await readFile5(requestPath(runDir, stepId), "utf8").catch(() => void 0);
+  return raw === void 0 ? void 0 : JSON.parse(raw);
+}
+async function readAnswerRaw(runDir, stepId) {
+  const raw = await readFile5(answerPath(runDir, stepId), "utf8").catch(() => void 0);
+  return raw === void 0 ? void 0 : JSON.parse(raw);
+}
+async function writeAnswer(runDir, stepId, answer) {
+  await mkdir3(path5.join(runDir, "pending"), { recursive: true });
+  await writeFile2(answerPath(runDir, stepId), JSON.stringify(answer, null, 2), "utf8");
+}
+function openRequestStepIds(events) {
+  const open = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    if (event.t === "gate.opened") open.set(event.stepId, true);
+    else if (event.t === "gate.answered") open.set(event.stepId, false);
+  }
+  return [...open.entries()].filter(([, isOpen]) => isOpen).map(([stepId]) => stepId);
+}
+async function resolveAnswer(runDir, stepId, gateAnswerSchema) {
+  const request = await readPendingRequest(runDir, stepId);
+  if (!request) throw new Error(`no pending request found for step "${stepId}"`);
+  const answerRaw = await readAnswerRaw(runDir, stepId);
+  if (answerRaw === void 0) return { status: "missing", stepId };
+  const schema = request.kind === "loop-exhausted" ? wrapZodSchema(LoopExhaustionAnswerSchema) : await gateAnswerSchema(request);
+  const parsed = schema.safeParse(answerRaw);
+  if (!parsed.success) return { status: "invalid", stepId, errors: parsed.errorSummary ?? "" };
+  return { status: "ok", stepId, request, answer: parsed.data };
+}
+
+// src/expr/eval.ts
+import path6 from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
+import jexl2 from "jexl";
+async function evalExpr(expr, context, cwd) {
+  if (typeof expr === "string") {
+    return jexl2.eval(expr, context);
+  }
+  const modulePath = path6.resolve(cwd, ".yak/predicates.ts");
+  const mod = await import(pathToFileURL2(modulePath).href);
+  const impl = mod[expr.fn];
+  if (typeof impl !== "function") {
+    throw new Error(`predicate "${expr.fn}" not found in .yak/predicates.ts`);
+  }
+  return impl(context);
+}
+
+// src/steps/gate.ts
+async function renderGate(step, inputs, cwd) {
+  const text = "file" in step.render ? await readFile6(path7.resolve(cwd, step.render.file), "utf8") : step.render.inline;
+  return renderTemplate(text, inputs);
+}
+async function completeGate(step, ctx, answer, opts) {
+  let artifactName;
+  let artifactHash;
+  if (step.produces) {
+    const schema = await resolveSchemaSpec(step.schema, ctx.cwd);
+    const parsed = schema.safeParse(answer);
+    if (!parsed.success) {
+      throw new Error(`gate step "${step.id}": answer failed schema validation: ${parsed.errorSummary}`);
+    }
+    const written = await writeArtifact(ctx.runDir, step.produces, parsed.data, z4.unknown());
+    artifactName = written.name;
+    artifactHash = written.hash;
+    await appendJournalEvent(ctx.runDir, ctx.runId, {
+      t: "artifact.written",
+      name: written.name,
+      hash: written.hash,
+      bytes: written.bytes
+    });
+  }
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.completed",
+    stepId: step.id,
+    ...artifactName ? { artifact: artifactName, artifactHash } : {},
+    cached: false
+  });
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "gate.answered",
+    stepId: step.id,
+    ...opts.skipped ? { skipped: true } : {}
+  });
+}
+async function runGateStep(step, inputs, ctx) {
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.started",
+    stepId: step.id,
+    semanticKey: "",
+    definitionKey: ""
+  });
+  const schema = await resolveSchemaSpec(step.schema, ctx.cwd);
+  const skip = step.skipIf ? Boolean(await evalExpr(step.skipIf, inputs, ctx.cwd)) : false;
+  if (skip) {
+    await appendJournalEvent(ctx.runDir, ctx.runId, { t: "gate.opened", stepId: step.id, requestPath: "" });
+    const defaulted = schema.parseDefaults();
+    if (!defaulted.success) {
+      throw new Error(
+        `gate step "${step.id}": skipIf true but schema doesn't default every field: ${defaulted.errorSummary}`
+      );
+    }
+    await completeGate(step, ctx, defaulted.data, { skipped: true });
+    return "ok";
+  }
+  const rendered = await renderGate(step, inputs, ctx.cwd);
+  const answerSchema = schema.toJsonSchema();
+  await writeGateRequest(ctx.runDir, ctx.runId, step, rendered, answerSchema);
+  return "suspended";
+}
+
+// src/util/git.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
+var WorktreeCreationError = class extends Error {
+};
+var ENGINE_AUTHOR = ["-c", "user.name=yak", "-c", "user.email=engine@yak.local"];
+async function commitAllIfDirty(repoRoot, message) {
+  const { stdout } = await execFileAsync2("git", ["status", "--porcelain"], { cwd: repoRoot });
+  if (stdout.trim() === "") return;
+  await execFileAsync2("git", ["add", "-A"], { cwd: repoRoot });
+  await execFileAsync2("git", [...ENGINE_AUTHOR, "commit", "-m", message], { cwd: repoRoot });
+}
+var WORKTREE_ADD_RETRIES = 5;
+var WORKTREE_ADD_RETRY_DELAY_MS = 50;
+function isLockContention(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return message.includes("index.lock") || message.includes(".git/worktrees") && message.includes("lock");
+}
+async function createWorktree(repoRoot, branchName, baseRef, worktreePath) {
+  for (let attempt = 1; attempt <= WORKTREE_ADD_RETRIES; attempt++) {
+    try {
+      await execFileAsync2("git", ["worktree", "add", "-b", branchName, worktreePath, baseRef], { cwd: repoRoot });
+      return;
+    } catch (err) {
+      if (attempt < WORKTREE_ADD_RETRIES && isLockContention(err)) {
+        await new Promise((resolve) => setTimeout(resolve, WORKTREE_ADD_RETRY_DELAY_MS));
+        continue;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      throw new WorktreeCreationError(
+        `failed to create worktree at "${worktreePath}" on branch "${branchName}" from "${baseRef}": ${message}`
+      );
+    }
+  }
+}
+
+// src/engine/scheduler.ts
+import path14 from "path";
+import pLimit2 from "p-limit";
+import { z as z8 } from "zod";
+
+// src/adapters/claude-code.ts
+import { spawn } from "child_process";
+import { mkdir as mkdir4, appendFile as appendFile2 } from "fs/promises";
+import path9 from "path";
+import {
+  query
+} from "@anthropic-ai/claude-agent-sdk";
+
+// src/steps/agent.ts
+import { readFile as readFile7 } from "fs/promises";
+import path8 from "path";
+async function buildPrompt(step, inputs, cwd) {
+  const text = "file" in step.prompt ? await readFile7(path8.resolve(cwd, step.prompt.file), "utf8") : step.prompt.inline;
+  return renderTemplate(text, inputs);
+}
+async function callAgentOnce(step, inputs, ctx, promptSuffix) {
+  const prompt = await buildPrompt(step, inputs, ctx.cwd) + (promptSuffix ?? "");
+  const schema = step.schema ? await resolveSchemaSpec(step.schema, ctx.cwd) : void 0;
+  const jsonSchema = schema ? schema.toJsonSchema() : void 0;
+  const response = await ctx.adapter.run({
+    prompt,
+    tools: step.tools ?? [],
+    cwd: ctx.cwd,
+    model: step.model,
+    schema: jsonSchema,
+    sessionId: ctx.sessionId,
+    signal: new AbortController().signal
+  });
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "budget.consumed",
+    stepId: step.id,
+    tokens: response.tokens.input + response.tokens.output
+  });
+  return { output: response.output, sessionId: response.sessionId };
+}
+var AgentStepFailedError = class extends Error {
+  failure;
+  constructor(failure) {
+    super(failure.detail);
+    this.failure = failure;
+  }
+};
+function repairSuffix(jsonSchema, errorSummary) {
+  return `
+
+---
+Your previous output did not match the required schema.
+Schema:
+${JSON.stringify(jsonSchema)}
+
+Validation errors:
+${errorSummary}
+
+Return output that satisfies the schema.`;
+}
+async function runAgentStep(step, inputs, ctx, onSessionId) {
+  const schema = step.schema ? await resolveSchemaSpec(step.schema, ctx.cwd) : void 0;
+  const maxAttempts = (step.repairAttempts ?? 2) + 1;
+  let sessionId = ctx.sessionId;
+  let suffix;
+  let lastOutput;
+  let lastErrorSummary = "";
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const call = await callAgentOnce(step, inputs, { ...ctx, sessionId }, suffix);
+    sessionId = call.sessionId;
+    onSessionId?.(sessionId);
+    lastOutput = call.output;
+    if (!schema) return call.output;
+    const parsed = schema.safeParse(call.output);
+    if (parsed.success) return parsed.data;
+    lastErrorSummary = parsed.errorSummary ?? "";
+    suffix = repairSuffix(schema.toJsonSchema(), lastErrorSummary);
+  }
+  await writeRejectedOutput(ctx.runDir, step.id, maxAttempts, JSON.stringify(lastOutput, null, 2));
+  throw new AgentStepFailedError({
+    reason: "schema-invalid",
+    detail: lastErrorSummary,
+    recoverable: false
+  });
+}
+
+// src/adapters/sandbox-network.ts
+import { randomBytes } from "crypto";
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify3 } from "util";
+var execFileAsync3 = promisify3(execFile3);
+var DEFAULT_ALLOWED_DOMAINS = ["api.anthropic.com"];
+var PROXY_IMAGE = "yak-agent-sandbox-proxy:latest";
+var PROXY_PORT = 3128;
+function randomSuffix() {
+  return randomBytes(4).toString("hex");
+}
+function sandboxNetworkName(stepId) {
+  return `yak-agent-${stepId.replace(/[^a-zA-Z0-9_.-]/g, "-")}-${randomSuffix()}`;
+}
+function proxyContainerName(networkName) {
+  return `${networkName}-proxy`;
+}
+function createNetworkArgs(networkName) {
+  return ["network", "create", "--internal", networkName];
+}
+function removeNetworkArgs(networkName) {
+  return ["network", "rm", networkName];
+}
+function startProxyArgs(networkName, containerName, allowedDomains) {
+  return [
+    "run",
+    "-d",
+    "--rm",
+    "--name",
+    containerName,
+    "--network",
+    networkName,
+    "-e",
+    `ALLOWED_DOMAINS=${allowedDomains.join(",")}`,
+    PROXY_IMAGE
+  ];
+}
+function connectProxyToBridgeArgs(containerName) {
+  return ["network", "connect", "bridge", containerName];
+}
+function removeProxyArgs(containerName) {
+  return ["rm", "-f", containerName];
+}
+async function docker(args) {
+  await execFileAsync3("docker", args);
+}
+async function createAgentSandboxNetwork(stepId, allowedDomains = DEFAULT_ALLOWED_DOMAINS) {
+  const networkName = sandboxNetworkName(stepId);
+  const containerName = proxyContainerName(networkName);
+  await docker(createNetworkArgs(networkName));
+  try {
+    await docker(startProxyArgs(networkName, containerName, allowedDomains));
+    await docker(connectProxyToBridgeArgs(containerName));
+  } catch (err) {
+    await docker(removeNetworkArgs(networkName)).catch(() => {
+    });
+    throw err;
+  }
+  return {
+    networkName,
+    proxyUrl: `http://${containerName}:${PROXY_PORT}`,
+    async teardown() {
+      await docker(removeProxyArgs(containerName)).catch(() => {
+      });
+      await docker(removeNetworkArgs(networkName)).catch(() => {
+      });
+    }
+  };
+}
+
+// src/adapters/claude-code.ts
+var AGENT_SANDBOX_IMAGE_DEFAULT = "yak-agent-sandbox:latest";
+var CONTAINER_CLI_PATH = "/app/claude-cli";
+var CONTAINER_WORKDIR = "/workspace";
+function dockerAgentRunArgs(image, cwd, networkName, proxyUrl, args, hostEnv = process.env) {
+  const credentialEnv = ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"].filter((key) => hostEnv[key] !== void 0).flatMap((key) => ["-e", `${key}=${hostEnv[key]}`]);
+  return [
+    "run",
+    "--rm",
+    "-i",
+    "--network",
+    networkName,
+    "-v",
+    `${cwd}:${CONTAINER_WORKDIR}`,
+    "-w",
+    CONTAINER_WORKDIR,
+    "-e",
+    `HTTPS_PROXY=${proxyUrl}`,
+    "-e",
+    `HTTP_PROXY=${proxyUrl}`,
+    ...credentialEnv,
+    image ?? AGENT_SANDBOX_IMAGE_DEFAULT,
+    CONTAINER_CLI_PATH,
+    ...args
+  ];
+}
+var FIXED_OPTIONS = {
+  permissionMode: "bypassPermissions",
+  allowDangerouslySkipPermissions: true
+};
+var FILE_MUTATING_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "NotebookEdit"]);
+function collectFilesChanged(message, into) {
+  if (message.type !== "assistant") return;
+  for (const block of message.message.content) {
+    if (block.type !== "tool_use") continue;
+    if (!FILE_MUTATING_TOOLS.has(block.name)) continue;
+    const input = block.input;
+    if (input && typeof input === "object" && "file_path" in input) {
+      const filePath = input.file_path;
+      if (typeof filePath === "string") into.add(filePath);
+    }
+  }
+}
+function mapResultError(result) {
+  const detail = result.errors.length > 0 ? result.errors.join("; ") : `${result.subtype} (no detail)`;
+  switch (result.subtype) {
+    case "error_max_budget_usd":
+      return { reason: "budget-exhausted", detail, recoverable: false };
+    case "error_max_turns":
+      return { reason: "adapter-error", detail, recoverable: false };
+    case "error_max_structured_output_retries":
+      return { reason: "adapter-error", detail, recoverable: false };
+    case "error_during_execution":
+    default:
+      return { reason: "adapter-error", detail, recoverable: true };
+  }
+}
+var ClaudeCodeAdapter = class {
+  constructor(runDir, stepId, sandbox) {
+    this.runDir = runDir;
+    this.stepId = stepId;
+    this.sandbox = sandbox;
+  }
+  runDir;
+  stepId;
+  sandbox;
+  id = "claude-code";
+  async run(req) {
+    const abortController = new AbortController();
+    if (req.signal.aborted) abortController.abort(req.signal.reason);
+    else req.signal.addEventListener("abort", () => abortController.abort(req.signal.reason));
+    let network;
+    if (this.sandbox) {
+      network = await createAgentSandboxNetwork(this.stepId);
+    }
+    const options = {
+      ...FIXED_OPTIONS,
+      abortController,
+      cwd: req.cwd,
+      tools: req.tools,
+      ...req.model !== void 0 ? { model: req.model } : {},
+      ...req.systemPrompt !== void 0 ? { systemPrompt: req.systemPrompt } : {},
+      // §3.4 `context: { session }` resume vs `'fresh'` (ticket 06): a
+      // prior sessionId genuinely replays that session's transcript via
+      // `resume`; omitting it is `'fresh'` — no explicit teardown needed,
+      // and this Options object is always freshly built per call, never
+      // reused/mutated across steps.
+      ...req.sessionId !== void 0 ? { resume: req.sessionId } : {},
+      ...req.schema !== void 0 ? { outputFormat: { type: "json_schema", schema: req.schema } } : {},
+      // Ticket 07/08: substitutes a `docker run` wrapping the CLI child
+      // process for the SDK's default local spawn. `spawnOptions.command`
+      // (a host path) is deliberately dropped — see dockerAgentRunArgs's
+      // doc comment — only `.args` (portable CLI flags) crosses over.
+      ...network ? {
+        spawnClaudeCodeProcess: (spawnOptions) => spawn(
+          "docker",
+          dockerAgentRunArgs(
+            this.sandbox.image,
+            req.cwd,
+            network.networkName,
+            network.proxyUrl,
+            spawnOptions.args
+          ),
+          { signal: spawnOptions.signal }
+        )
+      } : {}
+    };
+    try {
+      const sessionLogPath = path9.join(this.runDir, "sessions", `${this.stepId}.jsonl`);
+      await mkdir4(path9.dirname(sessionLogPath), { recursive: true });
+      const filesChanged = /* @__PURE__ */ new Set();
+      let result;
+      for await (const message of query({ prompt: req.prompt, options })) {
+        await appendFile2(sessionLogPath, `${JSON.stringify(message)}
+`, "utf8");
+        collectFilesChanged(message, filesChanged);
+        if (message.type === "result") result = message;
+      }
+      if (!result) {
+        throw new AgentStepFailedError({
+          reason: "adapter-error",
+          detail: `claude-code adapter for step "${this.stepId}": query() stream ended without a result message`,
+          recoverable: true
+        });
+      }
+      if (result.permission_denials.length > 0) {
+        throw new AgentStepFailedError({
+          reason: "tool-denied",
+          detail: `tool call(s) denied: ${result.permission_denials.map((d) => d.tool_name).join(", ")}`,
+          recoverable: false
+        });
+      }
+      if (result.subtype !== "success") {
+        throw new AgentStepFailedError(mapResultError(result));
+      }
+      return {
+        output: result.structured_output ?? result.result,
+        sessionId: result.session_id,
+        tokens: { input: result.usage.input_tokens, output: result.usage.output_tokens },
+        filesChanged: [...filesChanged].sort(),
+        stopReason: "complete"
+      };
+    } finally {
+      await network?.teardown();
+    }
+  }
+};
+
+// src/adapters/mock.ts
+import { readFileSync } from "fs";
+import path10 from "path";
+var MockAdapter = class {
+  /** Ticket 08: `iteration` (1-based) picks the starting fixture entry for a
+   * step inside a loop body — e.g. iteration 3's `run()` starts at
+   * `responses[2]`, so a fixture can script "iteration 1 fails, iteration 3
+   * passes." Schema-repair retries within that same call still advance the
+   * index normally from there. Omitted for non-loop steps, unchanged from
+   * always starting at 0. */
+  constructor(fixturesDir, workflowName, stepId, iteration) {
+    this.stepId = stepId;
+    const fixturePath = path10.join(fixturesDir, workflowName, `${stepId}.json`);
+    const raw = readFileSync(fixturePath, "utf8");
+    this.responses = JSON.parse(raw);
+    this.callIndex = iteration !== void 0 ? iteration - 1 : 0;
+  }
+  stepId;
+  id = "mock";
+  callIndex = 0;
+  responses;
+  async run(_req) {
+    const lastIndex = this.responses.length - 1;
+    const entry = this.responses[Math.min(this.callIndex, lastIndex)];
+    if (!entry) {
+      throw new Error(`mock fixture for step "${this.stepId}" has no response entries`);
+    }
+    const callIndex = this.callIndex;
+    this.callIndex += 1;
+    return {
+      output: entry.output,
+      sessionId: `mock:${this.stepId}:${callIndex}`,
+      tokens: entry.tokens ?? { input: 0, output: 0 },
+      filesChanged: entry.filesChanged ?? [],
+      stopReason: entry.stopReason ?? "complete"
+    };
+  }
+};
+
+// src/steps/command.ts
+import { spawn as spawn2 } from "child_process";
+import { z as z5 } from "zod";
+var CommandResultSchema = z5.object({
+  stdout: z5.string().optional(),
+  stderr: z5.string().optional(),
+  exitCode: z5.number().optional()
+});
+var CommandStepFailedError = class extends Error {
+  failure;
+  constructor(failure) {
+    super(failure.detail);
+    this.failure = failure;
+  }
+};
+var KILL_GRACE_MS = 5e3;
+var DOCKER_CLI_ERROR_EXIT_CODE = 125;
+function dockerRunArgs(step, cwd) {
+  const workdir = step.cwd ? `/workspace/${step.cwd}` : "/workspace";
+  return [
+    "run",
+    "--rm",
+    "--network",
+    "none",
+    "-v",
+    `${cwd}:/workspace`,
+    "-w",
+    workdir,
+    step.image,
+    "sh",
+    "-c",
+    step.run
+  ];
+}
+function feedLines(carry, chunk, onLine) {
+  const combined = carry + chunk;
+  const lines = combined.split("\n");
+  const remainder = lines.pop() ?? "";
+  for (const _line of lines) onLine();
+  return remainder;
+}
+function runCommandStep(step, cwd, extraEnv) {
+  const capture = step.capture ?? ["stdout", "stderr", "exitCode"];
+  const failOn = step.failOn ?? "exitCode";
+  return new Promise((resolve, reject) => {
+    const child = step.sandbox === "docker" ? spawn2("docker", dockerRunArgs(step, cwd), {
+      ...extraEnv ? { env: { ...process.env, ...extraEnv } } : {}
+    }) : spawn2(step.run, {
+      cwd: step.cwd ?? cwd,
+      shell: true,
+      ...extraEnv ? { env: { ...process.env, ...extraEnv } } : {}
+    });
+    let stdout = "";
+    let stderr = "";
+    let stdoutCarry = "";
+    let stderrCarry = "";
+    let settled = false;
+    let timedOut = false;
+    let idleTimer;
+    let killTimer;
+    const clearTimers = () => {
+      if (idleTimer) clearTimeout(idleTimer);
+      if (killTimer) clearTimeout(killTimer);
+    };
+    const onLine = () => {
+      if (step.idleTimeoutMs === void 0) return;
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = setTimeout(onIdleTimeout, step.idleTimeoutMs);
+    };
+    function onIdleTimeout() {
+      timedOut = true;
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
+    }
+    if (step.idleTimeoutMs !== void 0) idleTimer = setTimeout(onIdleTimeout, step.idleTimeoutMs);
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+      stdoutCarry = feedLines(stdoutCarry, chunk, onLine);
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+      stderrCarry = feedLines(stderrCarry, chunk, onLine);
+    });
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      reject(
+        step.sandbox === "docker" ? new CommandStepFailedError({
+          reason: "sandbox-error",
+          detail: `docker failed to start for command "${step.run}": ${err.message}`,
+          recoverable: false
+        }) : new CommandStepFailedError({
+          reason: "command-failed",
+          detail: `command "${step.run}" failed to start: ${err.message}`,
+          recoverable: false
+        })
+      );
+    });
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      if (timedOut) {
+        reject(
+          new CommandStepFailedError({
+            reason: "timeout",
+            detail: `command "${step.run}" idle for longer than ${step.idleTimeoutMs}ms, killed`,
+            recoverable: false
+          })
+        );
+        return;
+      }
+      const exitCode = code ?? (signal ? 1 : 0);
+      const result = {};
+      if (capture.includes("stdout")) result.stdout = stdout;
+      if (capture.includes("stderr")) result.stderr = stderr;
+      if (capture.includes("exitCode")) result.exitCode = exitCode;
+      if (step.sandbox === "docker" && exitCode === DOCKER_CLI_ERROR_EXIT_CODE) {
+        reject(
+          new CommandStepFailedError({
+            reason: "sandbox-error",
+            detail: `docker run exited ${DOCKER_CLI_ERROR_EXIT_CODE} for command "${step.run}" (image "${step.image}") \u2014 the container never started (bad image, daemon unreachable, invalid docker invocation), not the command inside it failing`,
+            recoverable: false
+          })
+        );
+        return;
+      }
+      if (failOn === "exitCode" && exitCode !== 0) {
+        reject(
+          new CommandStepFailedError({
+            reason: "command-failed",
+            detail: `command "${step.run}" exited with code ${exitCode}`,
+            recoverable: false
+          })
+        );
+        return;
+      }
+      resolve(result);
+    });
+  });
+}
+
+// src/steps/loop.ts
+import { z as z6 } from "zod";
+
+// src/engine/cache.ts
+import { mkdir as mkdir5, readFile as readFile8, rename as rename2, writeFile as writeFile3 } from "fs/promises";
+import { randomUUID as randomUUID2 } from "crypto";
+import path11 from "path";
+var ENGINE_VERSION = "0.0.1";
+function definitionPayload(step) {
+  switch (step.kind) {
+    case "command":
+      return {
+        run: step.run,
+        cwd: step.cwd,
+        failOn: step.failOn,
+        capture: step.capture,
+        skipIf: step.skipIf,
+        finally: step.finally
+      };
+    case "transform":
+      return { fn: step.fn, skipIf: step.skipIf, finally: step.finally };
+    case "agent":
+      return {
+        prompt: step.prompt,
+        tools: step.tools,
+        schema: step.schema,
+        model: step.model,
+        repairAttempts: step.repairAttempts,
+        skipIf: step.skipIf,
+        finally: step.finally
+      };
+    case "gate":
+      return { schema: step.schema, render: step.render, skipIf: step.skipIf, finally: step.finally };
+    case "map":
+      return {
+        over: step.over,
+        concurrency: step.concurrency,
+        isolation: step.isolation,
+        onItemFailure: step.onItemFailure,
+        step: step.step
+      };
+    case "loop":
+      return {
+        until: step.until,
+        budget: step.budget,
+        onExhausted: step.onExhausted,
+        freshContext: step.freshContext,
+        body: step.body
+      };
+  }
+}
+function computeDefinitionKey(step) {
+  return sha256(JSON.stringify({ def: definitionPayload(step), engineVersion: ENGINE_VERSION }));
+}
+function computeSemanticKey(step, inputArtifactHashes, iteration = 0) {
+  const inputs = Object.keys(inputArtifactHashes).sort().map((name) => `${name}=${inputArtifactHashes[name]}`).join(",");
+  const adapterId = step.kind === "agent" ? "default" : "";
+  const modelId = step.kind === "agent" ? step.model ?? "" : "";
+  return sha256(`${step.id}|${inputs}|${adapterId}|${modelId}|${iteration}`);
+}
+function decideCache(cacheMode, definitionKey, entry) {
+  if (!entry) return { kind: "miss" };
+  if (entry.definitionKey === definitionKey) return { kind: "hit", entry, stale: false };
+  if (cacheMode === "loose") return { kind: "hit", entry, stale: true };
+  return { kind: "miss" };
+}
+function entryPath(cacheDir, semanticKey) {
+  return path11.join(cacheDir, `${semanticKey}.json`);
+}
+async function readCacheEntry(cacheDir, semanticKey) {
+  const raw = await readFile8(entryPath(cacheDir, semanticKey), "utf8").catch(() => void 0);
+  return raw === void 0 ? void 0 : JSON.parse(raw);
+}
+async function writeCacheEntry(cacheDir, entry) {
+  await mkdir5(cacheDir, { recursive: true });
+  const finalPath = entryPath(cacheDir, entry.semanticKey);
+  const tmpPath = path11.join(cacheDir, `.${entry.semanticKey}.${randomUUID2()}.tmp`);
+  await writeFile3(tmpPath, JSON.stringify(entry, null, 2), "utf8");
+  await rename2(tmpPath, finalPath);
+}
+
+// src/steps/transform.ts
+import path12 from "path";
+import { pathToFileURL as pathToFileURL3 } from "url";
+async function resolveTransformFn(fn, cwd) {
+  const modulePath = path12.resolve(cwd, ".yak/transforms.ts");
+  const mod = await import(pathToFileURL3(modulePath).href);
+  const impl = mod[fn];
+  if (typeof impl !== "function") {
+    throw new Error(`transform "${fn}" not found in .yak/transforms.ts`);
+  }
+  return impl;
+}
+async function runTransformStep(step, inputs, cwd) {
+  const impl = await resolveTransformFn(step.fn, cwd);
+  return impl(inputs);
+}
+
+// src/steps/loop.ts
+async function runLoopStep(step, ctx) {
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.started",
+    stepId: step.id,
+    semanticKey: ctx.semanticKey,
+    definitionKey: ctx.definitionKey
+  });
+  if (ctx.loopContinuation?.action === "abort") {
+    await appendJournalEvent(ctx.runDir, ctx.runId, {
+      t: "step.failed",
+      stepId: step.id,
+      failure: {
+        reason: "budget-exhausted",
+        detail: `loop "${step.id}" aborted by human after budget exhaustion`,
+        recoverable: false
+      }
+    });
+    return "failed";
+  }
+  const resumeFrom = ctx.loopContinuation?.action === "continue" ? await buildResumeFrom(step, ctx) : void 0;
+  const status = await runLoopBody(step, ctx, resumeFrom);
+  if (status === "ok") {
+    await appendJournalEvent(ctx.runDir, ctx.runId, { t: "step.completed", stepId: step.id, cached: false });
+  }
+  return status;
+}
+async function buildResumeFrom(step, ctx) {
+  const events = await readJournal(ctx.runDir);
+  const bodyStepIds = new Set(step.body.map((s) => s.id));
+  const trippedIteration = [...events].reverse().find((e) => e.t === "loop.iteration" && e.stepId === step.id);
+  const iteration = trippedIteration && trippedIteration.t === "loop.iteration" ? trippedIteration.n : 0;
+  const priorValues = /* @__PURE__ */ new Map();
+  const priorHashes = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    if (event.t !== "step.completed" || event.iteration !== iteration) continue;
+    if (!bodyStepIds.has(event.stepId) || !event.artifact) continue;
+    priorValues.set(event.artifact, await readArtifactRaw(ctx.runDir, event.artifact, iteration));
+    if (event.artifactHash) priorHashes.set(event.artifact, event.artifactHash);
+  }
+  const addIterations = ctx.loopContinuation?.addIterations ?? 0;
+  return {
+    startIteration: iteration + 1,
+    priorValues,
+    priorHashes,
+    maxIterations: step.budget.maxIterations + addIterations
+  };
+}
+async function runLoopBody(step, ctx, resumeFrom) {
+  const localProducerOf = buildProducerMap(step.body);
+  const bodyOrderIndex = new Map(step.body.map((s, i) => [s.id, i]));
+  const bodyStepIds = new Set(step.body.map((s) => s.id));
+  const effectiveMaxIterations = resumeFrom?.maxIterations ?? step.budget.maxIterations;
+  let priorValues = resumeFrom?.priorValues ?? /* @__PURE__ */ new Map();
+  let priorHashes = resumeFrom?.priorHashes ?? /* @__PURE__ */ new Map();
+  let lastSignal;
+  const bodySessionIds = /* @__PURE__ */ new Map();
+  for (let iteration = resumeFrom?.startIteration ?? 1; ; iteration++) {
+    const thisValues = /* @__PURE__ */ new Map();
+    const thisHashes = /* @__PURE__ */ new Map();
+    try {
+      for (const [posIndex, bodyStep] of step.body.entries()) {
+        await runOneBodyStep({
+          bodyStep,
+          posIndex,
+          iteration,
+          ctx,
+          localProducerOf,
+          bodyOrderIndex,
+          priorValues,
+          priorHashes,
+          thisValues,
+          thisHashes,
+          freshContext: step.freshContext ?? true,
+          bodySessionIds
+        });
+      }
+    } catch (err) {
+      if (err instanceof CommandStepFailedError || err instanceof AgentStepFailedError) {
+        await appendJournalEvent(ctx.runDir, ctx.runId, {
+          t: "step.failed",
+          stepId: step.id,
+          failure: {
+            reason: err.failure.reason,
+            detail: `loop "${step.id}" body step failed: ${err.failure.detail}`,
+            recoverable: false
+          }
+        });
+        return "failed";
+      }
+      throw err;
+    }
+    const untilContext = Object.fromEntries(thisValues);
+    if (await evalExpr(step.until, untilContext, ctx.cwd)) return "ok";
+    let tripped;
+    if (step.budget.noProgress) {
+      lastSignal = await evalExpr(step.budget.noProgress.signal, untilContext, ctx.cwd);
+    }
+    await appendJournalEvent(ctx.runDir, ctx.runId, {
+      t: "loop.iteration",
+      stepId: step.id,
+      n: iteration,
+      ...lastSignal !== void 0 ? { signal: lastSignal } : {}
+    });
+    if (step.budget.noProgress) {
+      tripped = await noProgressTripped(step, ctx, iteration) ? "noProgress" : tripped;
+    }
+    if (!tripped && iteration >= effectiveMaxIterations) tripped = "maxIterations";
+    if (!tripped && step.budget.maxTokens !== void 0) {
+      const tokensTotal = await sumBodyTokens(ctx.runDir, bodyStepIds);
+      if (tokensTotal >= step.budget.maxTokens) tripped = "maxTokens";
+    }
+    if (tripped) return await handleExhausted(step, ctx, iteration, tripped);
+    priorValues = thisValues;
+    priorHashes = thisHashes;
+  }
+}
+async function noProgressTripped(step, ctx, iteration) {
+  const rounds = step.budget.noProgress.rounds;
+  const events = await readJournal(ctx.runDir);
+  const signals = events.filter((e) => e.t === "loop.iteration" && e.stepId === step.id && e.n <= iteration).map((e) => e.signal).filter((s) => typeof s === "number");
+  if (signals.length < rounds) return false;
+  const recent = signals.slice(-rounds);
+  for (let i = 1; i < recent.length; i++) {
+    if (recent[i] < recent[i - 1]) return false;
+  }
+  return true;
+}
+async function sumBodyTokens(runDir, bodyStepIds) {
+  const events = await readJournal(runDir);
+  return events.filter((e) => e.t === "budget.consumed" && bodyStepIds.has(e.stepId)).reduce((sum, e) => sum + e.tokens, 0);
+}
+async function handleExhausted(step, ctx, iteration, tripped) {
+  const onExhausted = step.onExhausted ?? "suspend";
+  if (onExhausted === "continue") return "ok";
+  if (onExhausted === "fail") {
+    await appendJournalEvent(ctx.runDir, ctx.runId, {
+      t: "step.failed",
+      stepId: step.id,
+      failure: {
+        reason: "budget-exhausted",
+        detail: `loop "${step.id}" exhausted (${tripped}) after ${iteration} iterations`,
+        recoverable: false
+      }
+    });
+    return "failed";
+  }
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "run.suspended",
+    reason: "exhausted",
+    loopStepId: step.id,
+    iteration,
+    tripped
+  });
+  await writeLoopExhaustedRequest(ctx.runDir, ctx.runId, step.id, iteration, tripped);
+  return "suspended";
+}
+async function runOneBodyStep(args) {
+  const {
+    bodyStep,
+    posIndex,
+    iteration,
+    ctx,
+    localProducerOf,
+    bodyOrderIndex,
+    priorValues,
+    priorHashes,
+    thisValues,
+    thisHashes,
+    freshContext,
+    bodySessionIds
+  } = args;
+  const inputs = {};
+  const inputHashesForKey = {};
+  for (const name of inputNamesOf(bodyStep)) {
+    const producerId = localProducerOf.get(name);
+    if (producerId !== void 0) {
+      const producerPos = bodyOrderIndex.get(producerId);
+      const fromThisRound = producerPos < posIndex;
+      inputs[name] = fromThisRound ? thisValues.get(name) : priorValues.get(name);
+      const hash = fromThisRound ? thisHashes.get(name) : priorHashes.get(name);
+      if (hash) inputHashesForKey[name] = hash;
+    } else {
+      inputs[name] = await readArtifactRaw(ctx.runDir, name);
+      const hash = ctx.outerArtifactHashes.get(name);
+      if (hash) inputHashesForKey[name] = hash;
+    }
+  }
+  const semanticKey = computeSemanticKey(bodyStep, inputHashesForKey, iteration);
+  const definitionKey = computeDefinitionKey(bodyStep);
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.started",
+    stepId: bodyStep.id,
+    iteration,
+    semanticKey,
+    definitionKey
+  });
+  const cacheMode = bodyStep.cache ?? "strict";
+  const existingEntry = await readCacheEntry(ctx.cacheDir, semanticKey);
+  const decision = decideCache(cacheMode, definitionKey, existingEntry);
+  let result;
+  let cached = false;
+  let stale = false;
+  if (decision.kind === "hit") {
+    result = decision.entry.artifact;
+    cached = true;
+    stale = decision.stale;
+  } else {
+    result = await runBodyStepKind(bodyStep, inputs, ctx, iteration, freshContext, bodySessionIds);
+  }
+  let artifactHash;
+  if (bodyStep.produces) {
+    const schema = bodyStep.kind === "command" ? CommandResultSchema : z6.unknown();
+    const written = await writeArtifact(ctx.runDir, bodyStep.produces, result, schema, iteration);
+    artifactHash = written.hash;
+    thisValues.set(bodyStep.produces, result);
+    thisHashes.set(bodyStep.produces, artifactHash);
+    if (!cached) {
+      await appendJournalEvent(ctx.runDir, ctx.runId, {
+        t: "artifact.written",
+        name: bodyStep.produces,
+        hash: artifactHash,
+        bytes: written.bytes
+      });
+    }
+  }
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.completed",
+    stepId: bodyStep.id,
+    iteration,
+    ...bodyStep.produces ? { artifact: bodyStep.produces, artifactHash } : {},
+    cached,
+    ...stale ? { stale: true } : {}
+  });
+  if (!cached) {
+    await writeCacheEntry(ctx.cacheDir, {
+      semanticKey,
+      definitionKey,
+      ...bodyStep.produces ? { artifactName: bodyStep.produces, artifactHash, artifact: result } : {}
+    });
+  }
+}
+async function runBodyStepKind(bodyStep, inputs, ctx, iteration, freshContext, bodySessionIds) {
+  try {
+    if (bodyStep.kind === "command") return await runCommandStep(bodyStep, ctx.cwd);
+    if (bodyStep.kind === "transform") return await runTransformStep(bodyStep, inputs, ctx.cwd);
+    if (bodyStep.kind === "agent") {
+      const adapter = ctx.buildAdapter(bodyStep, iteration);
+      const sessionId = freshContext ? void 0 : bodySessionIds.get(bodyStep.id);
+      return await runAgentStep(
+        bodyStep,
+        inputs,
+        { runId: ctx.runId, runDir: ctx.runDir, cwd: ctx.cwd, adapter, sessionId },
+        freshContext ? void 0 : (nextSessionId) => bodySessionIds.set(bodyStep.id, nextSessionId)
+      );
+    }
+  } catch (err) {
+    if (err instanceof CommandStepFailedError || err instanceof AgentStepFailedError) {
+      await appendJournalEvent(ctx.runDir, ctx.runId, {
+        t: "step.failed",
+        stepId: bodyStep.id,
+        iteration,
+        failure: err.failure
+      });
+    }
+    throw err;
+  }
+  throw new Error(`step "${bodyStep.id}": kind "${bodyStep.kind}" not supported inside a loop body in M3`);
+}
+
+// src/steps/map.ts
+import path13 from "path";
+import pLimit from "p-limit";
+import { z as z7 } from "zod";
+var RETRY_ATTEMPTS = 2;
+async function runMapStep(step, ctx) {
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.started",
+    stepId: step.id,
+    semanticKey: ctx.semanticKey,
+    definitionKey: ctx.definitionKey
+  });
+  if (step.isolation === "worktree") {
+    await commitAllIfDirty(ctx.cwd, `yak: checkpoint before map ${step.id}`);
+  }
+  const items = await readArtifactRaw(ctx.runDir, step.over);
+  const limit = pLimit(Math.min(step.concurrency ?? 4, ctx.globalConcurrency));
+  const results = new Array(items.length);
+  let anyFailed = false;
+  await Promise.all(
+    items.map(
+      (item, index) => limit(async () => {
+        const outcome = await runMapItem(step, item, index, ctx);
+        results[index] = outcome.result;
+        if (outcome.failed) anyFailed = true;
+      })
+    )
+  );
+  if (anyFailed && (step.onItemFailure ?? "skip") === "fail") {
+    await appendJournalEvent(ctx.runDir, ctx.runId, {
+      t: "step.failed",
+      stepId: step.id,
+      failure: {
+        reason: "command-failed",
+        detail: `map "${step.id}": at least one item failed under onItemFailure: 'fail'`,
+        recoverable: false
+      }
+    });
+    return "failed";
+  }
+  if (step.produces) {
+    const written = await writeArtifact(ctx.runDir, step.produces, results, z7.array(z7.unknown()));
+    await appendJournalEvent(ctx.runDir, ctx.runId, {
+      t: "artifact.written",
+      name: step.produces,
+      hash: written.hash,
+      bytes: written.bytes
+    });
+  }
+  await appendJournalEvent(ctx.runDir, ctx.runId, { t: "step.completed", stepId: step.id, cached: false });
+  return "ok";
+}
+function itemWorktreePath(runDir, runId, mapStepId, index) {
+  const runsDir = path13.dirname(runDir);
+  const yakRoot = path13.dirname(runsDir);
+  return path13.join(yakRoot, ".yak", "worktrees", runId, mapStepId, String(index));
+}
+async function ensureItemWorktree(step, index, ctx) {
+  const worktreePath = itemWorktreePath(ctx.runDir, ctx.runId, step.id, index);
+  await createWorktree(ctx.cwd, `yak-item/${ctx.runId}/${step.id}/${index}`, "HEAD", worktreePath);
+  return worktreePath;
+}
+async function runMapItem(step, item, index, ctx) {
+  const onItemFailure = step.onItemFailure ?? "skip";
+  const maxAttempts = onItemFailure === "retry" ? RETRY_ATTEMPTS + 1 : 1;
+  let itemCwd;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      if (step.isolation === "worktree" && itemCwd === void 0) {
+        itemCwd = await ensureItemWorktree(step, index, ctx);
+      }
+      const result = await runOneItemAttempt(step, item, index, ctx, itemCwd ?? ctx.cwd);
+      return { result, failed: false };
+    } catch (rawErr) {
+      const err = rawErr instanceof WorktreeCreationError ? new CommandStepFailedError({ reason: "command-failed", detail: rawErr.message, recoverable: false }) : rawErr;
+      if (!(err instanceof CommandStepFailedError || err instanceof AgentStepFailedError)) throw err;
+      if (attempt < maxAttempts) {
+        await appendJournalEvent(ctx.runDir, ctx.runId, {
+          t: "map.item.retried",
+          mapStepId: step.id,
+          itemIndex: index,
+          attempt,
+          error: err.failure.detail
+        });
+      }
+    }
+  }
+  if (onItemFailure === "fail") return { result: null, failed: true };
+  return { result: null, failed: false };
+}
+async function runOneItemAttempt(step, item, index, ctx, itemCwd) {
+  const itemStep = step.step;
+  const syntheticId = `${step.id}[${index}]`;
+  const inputs = { [step.over]: item };
+  const inputHashesForKey = {};
+  for (const name of inputNamesOf(itemStep)) {
+    if (name === step.over) continue;
+    inputs[name] = await readArtifactRaw(ctx.runDir, name);
+    const hash = ctx.outerArtifactHashes.get(name);
+    if (hash) inputHashesForKey[name] = hash;
+  }
+  const semanticKey = computeSemanticKey(itemStep, inputHashesForKey, index);
+  const definitionKey = computeDefinitionKey(itemStep);
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.started",
+    stepId: syntheticId,
+    iteration: index,
+    semanticKey,
+    definitionKey
+  });
+  const cacheMode = itemStep.cache ?? "strict";
+  const existingEntry = await readCacheEntry(ctx.cacheDir, semanticKey);
+  const decision = decideCache(cacheMode, definitionKey, existingEntry);
+  let result;
+  let cached = false;
+  let stale = false;
+  if (decision.kind === "hit") {
+    result = decision.entry.artifact;
+    cached = true;
+    stale = decision.stale;
+  } else {
+    try {
+      if (itemStep.kind === "command") {
+        result = await runCommandStep(itemStep, itemCwd, {
+          MAP_ITEM_INDEX: String(index),
+          MAP_ITEM: JSON.stringify(item)
+        });
+      } else if (itemStep.kind === "transform") {
+        result = await runTransformStep(itemStep, inputs, itemCwd);
+      } else if (itemStep.kind === "agent") {
+        const adapter = ctx.buildAdapter(itemStep, index);
+        result = await runAgentStep(itemStep, inputs, { runId: ctx.runId, runDir: ctx.runDir, cwd: itemCwd, adapter });
+      } else {
+        throw new Error(`step "${itemStep.id}": kind "${itemStep.kind}" not supported as a map item step in M3`);
+      }
+    } catch (err) {
+      if (err instanceof CommandStepFailedError || err instanceof AgentStepFailedError) {
+        await appendJournalEvent(ctx.runDir, ctx.runId, {
+          t: "step.failed",
+          stepId: syntheticId,
+          iteration: index,
+          failure: err.failure
+        });
+      }
+      throw err;
+    }
+  }
+  let artifactHash;
+  if (step.produces) {
+    const schema = itemStep.kind === "command" ? CommandResultSchema : z7.unknown();
+    const written = await writeArtifact(ctx.runDir, step.produces, result, schema, index);
+    artifactHash = written.hash;
+    if (!cached) {
+      await appendJournalEvent(ctx.runDir, ctx.runId, {
+        t: "artifact.written",
+        name: step.produces,
+        hash: artifactHash,
+        bytes: written.bytes
+      });
+    }
+  }
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.completed",
+    stepId: syntheticId,
+    iteration: index,
+    ...step.produces ? { artifact: step.produces, artifactHash } : {},
+    cached,
+    ...stale ? { stale: true } : {}
+  });
+  if (!cached) {
+    await writeCacheEntry(ctx.cacheDir, {
+      semanticKey,
+      definitionKey,
+      ...step.produces ? { artifactName: step.produces, artifactHash, artifact: result } : {}
+    });
+  }
+  return result;
+}
+
+// src/engine/scheduler.ts
+var DEFAULT_CONCURRENCY = 4;
+function buildAdapter(adapterId, ctx, workflowName, step, iteration) {
+  if (adapterId === "mock") {
+    const fixturesDir = path14.join(ctx.cwd, "test", "fixtures");
+    return new MockAdapter(fixturesDir, workflowName, step.id, iteration);
+  }
+  return new ClaudeCodeAdapter(
+    ctx.runDir,
+    step.id,
+    step.sandbox === "docker" ? { image: step.image } : void 0
+  );
+}
+function collectInputHashes(step, artifactHashes) {
+  const inputArtifactHashes = {};
+  for (const need of inputNamesOf(step)) {
+    const hash = artifactHashes.get(need);
+    if (hash) inputArtifactHashes[need] = hash;
+  }
+  return inputArtifactHashes;
+}
+function trustResumedSteps(remaining, producerOf, resumeState, completed, artifactHashes) {
+  let progressed = true;
+  while (progressed) {
+    progressed = false;
+    for (const step of remaining.values()) {
+      const info = resumeState.get(step.id);
+      if (!info) continue;
+      if (!dependenciesOf(step, producerOf).every((dep) => completed.has(dep))) continue;
+      if (step.kind !== "gate") {
+        const semanticKey = computeSemanticKey(step, collectInputHashes(step, artifactHashes));
+        const definitionKey = computeDefinitionKey(step);
+        if (semanticKey !== info.semanticKey || definitionKey !== info.definitionKey) continue;
+      }
+      completed.add(step.id);
+      remaining.delete(step.id);
+      if (info.artifact && info.artifactHash) artifactHashes.set(info.artifact, info.artifactHash);
+      progressed = true;
+    }
+  }
+}
+async function runEligibleSteps(workflow, ctx, resumeState) {
+  const limit = pLimit2(ctx.concurrency ?? DEFAULT_CONCURRENCY);
+  const producerOf = buildProducerMap(workflow.steps);
+  const remaining = new Map(workflow.steps.map((s) => [s.id, s]));
+  const completed = /* @__PURE__ */ new Set();
+  const failedSteps = /* @__PURE__ */ new Set();
+  const inFlight = /* @__PURE__ */ new Map();
+  const artifactHashes = /* @__PURE__ */ new Map();
+  let failed = false;
+  let suspended = false;
+  if (resumeState) trustResumedSteps(remaining, producerOf, resumeState, completed, artifactHashes);
+  const agentSessionIds = /* @__PURE__ */ new Map();
+  function launchEligible() {
+    if (suspended) return;
+    for (const step of remaining.values()) {
+      if (inFlight.has(step.id)) continue;
+      const deps = dependenciesOf(step, producerOf);
+      if (step.finally) {
+        if (deps.every((dep) => completed.has(dep) || failedSteps.has(dep))) {
+          inFlight.set(
+            step.id,
+            limit(() => runStep(step, ctx, artifactHashes, workflow.name, agentSessionIds))
+          );
+        }
+        continue;
+      }
+      if (failed) continue;
+      if (deps.every((dep) => completed.has(dep))) {
+        inFlight.set(
+          step.id,
+          limit(() => runStep(step, ctx, artifactHashes, workflow.name, agentSessionIds))
+        );
+      }
+    }
+  }
+  launchEligible();
+  while (inFlight.size > 0) {
+    const [doneId, status] = await Promise.race(
+      [...inFlight.entries()].map(async ([id, p]) => [id, await p])
+    );
+    inFlight.delete(doneId);
+    remaining.delete(doneId);
+    if (status === "failed") {
+      failed = true;
+      failedSteps.add(doneId);
+    } else if (status === "suspended") suspended = true;
+    else completed.add(doneId);
+    launchEligible();
+  }
+  if (!failed && !suspended && remaining.size > 0) {
+    const stuck = [...remaining.keys()].join(", ");
+    throw new Error(`workflow stalled: step(s) [${stuck}] never became eligible`);
+  }
+  return failed ? "failed" : suspended ? "suspended" : "ok";
+}
+async function runStep(step, ctx, artifactHashes, workflowName, agentSessionIds) {
+  if (step.kind === "loop") {
+    const semanticKey2 = computeSemanticKey(step, collectInputHashes(step, artifactHashes));
+    const definitionKey2 = computeDefinitionKey(step);
+    return runLoopStep(step, {
+      runId: ctx.runId,
+      runDir: ctx.runDir,
+      cwd: ctx.cwd,
+      cacheDir: ctx.cacheDir,
+      semanticKey: semanticKey2,
+      definitionKey: definitionKey2,
+      outerArtifactHashes: artifactHashes,
+      buildAdapter: (step2, iteration) => buildAdapter(ctx.adapter, ctx, workflowName, step2, iteration),
+      loopContinuation: ctx.loopContinuations?.get(step.id)
+    });
+  }
+  if (step.kind === "gate") {
+    const inputs = {};
+    for (const need of step.needs ?? []) {
+      inputs[need] = step.finally ? await readArtifactRawOrUndefined(ctx.runDir, need) : await readArtifactRaw(ctx.runDir, need);
+    }
+    return runGateStep(step, inputs, { runId: ctx.runId, runDir: ctx.runDir, cwd: ctx.cwd });
+  }
+  if (step.kind === "map") {
+    const semanticKey2 = computeSemanticKey(step, collectInputHashes(step, artifactHashes));
+    const definitionKey2 = computeDefinitionKey(step);
+    return runMapStep(step, {
+      runId: ctx.runId,
+      runDir: ctx.runDir,
+      cwd: ctx.cwd,
+      cacheDir: ctx.cacheDir,
+      semanticKey: semanticKey2,
+      definitionKey: definitionKey2,
+      globalConcurrency: ctx.concurrency ?? DEFAULT_CONCURRENCY,
+      outerArtifactHashes: artifactHashes,
+      buildAdapter: (step2, itemIndex) => buildAdapter(ctx.adapter, ctx, workflowName, step2, itemIndex)
+    });
+  }
+  const semanticKey = computeSemanticKey(step, collectInputHashes(step, artifactHashes));
+  const definitionKey = computeDefinitionKey(step);
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.started",
+    stepId: step.id,
+    semanticKey,
+    definitionKey
+  });
+  if (step.skipIf) {
+    const skipInputs = {};
+    for (const name of inputNamesOf(step)) {
+      skipInputs[name] = step.finally ? await readArtifactRawOrUndefined(ctx.runDir, name) : await readArtifactRaw(ctx.runDir, name);
+    }
+    const skip = Boolean(await evalExpr(step.skipIf, skipInputs, ctx.cwd));
+    if (skip) {
+      await appendJournalEvent(ctx.runDir, ctx.runId, {
+        t: "step.completed",
+        stepId: step.id,
+        cached: false,
+        skipped: true
+      });
+      return "ok";
+    }
+  }
+  const cacheMode = step.cache ?? "strict";
+  const existingEntry = await readCacheEntry(ctx.cacheDir, semanticKey);
+  const decision = decideCache(cacheMode, definitionKey, existingEntry);
+  if (decision.kind === "hit") {
+    const { entry } = decision;
+    let artifactHash2;
+    if (entry.artifactName) {
+      const artifactSchema = step.kind === "command" ? CommandResultSchema : z8.unknown();
+      const written = await writeArtifact(ctx.runDir, entry.artifactName, entry.artifact, artifactSchema);
+      artifactHash2 = written.hash;
+      artifactHashes.set(entry.artifactName, artifactHash2);
+    }
+    await appendJournalEvent(ctx.runDir, ctx.runId, {
+      t: "step.completed",
+      stepId: step.id,
+      ...entry.artifactName ? { artifact: entry.artifactName, artifactHash: artifactHash2 } : {},
+      cached: true,
+      ...decision.stale ? { stale: true } : {}
+    });
+    return "ok";
+  }
+  let result;
+  try {
+    if (step.kind === "command") {
+      result = await runCommandStep(step, ctx.cwd);
+    } else if (step.kind === "transform") {
+      const inputs = {};
+      for (const need of step.needs ?? []) {
+        inputs[need] = step.finally ? await readArtifactRawOrUndefined(ctx.runDir, need) : await readArtifactRaw(ctx.runDir, need);
+      }
+      result = await runTransformStep(step, inputs, ctx.cwd);
+    } else {
+      const inputs = {};
+      for (const name of agentInputNames(step)) {
+        inputs[name] = step.finally ? await readArtifactRawOrUndefined(ctx.runDir, name) : await readArtifactRaw(ctx.runDir, name);
+      }
+      const sessionId = typeof step.context === "object" && "session" in step.context ? agentSessionIds.get(step.context.session) : void 0;
+      const adapter = buildAdapter(ctx.adapter, ctx, workflowName, step);
+      result = await runAgentStep(
+        step,
+        inputs,
+        { runId: ctx.runId, runDir: ctx.runDir, cwd: ctx.cwd, adapter, sessionId },
+        (nextSessionId) => agentSessionIds.set(step.id, nextSessionId)
+      );
+    }
+  } catch (err) {
+    if (err instanceof CommandStepFailedError || err instanceof AgentStepFailedError) {
+      await appendJournalEvent(ctx.runDir, ctx.runId, {
+        t: "step.failed",
+        stepId: step.id,
+        failure: err.failure
+      });
+      return "failed";
+    }
+    throw err;
+  }
+  let artifactName;
+  let artifactHash;
+  if (step.produces) {
+    const artifact = step.kind === "command" ? await writeArtifact(ctx.runDir, step.produces, result, CommandResultSchema) : await writeArtifact(ctx.runDir, step.produces, result, z8.unknown());
+    artifactName = artifact.name;
+    artifactHash = artifact.hash;
+    artifactHashes.set(artifact.name, artifact.hash);
+    await appendJournalEvent(ctx.runDir, ctx.runId, {
+      t: "artifact.written",
+      name: artifact.name,
+      hash: artifact.hash,
+      bytes: artifact.bytes
+    });
+  }
+  await appendJournalEvent(ctx.runDir, ctx.runId, {
+    t: "step.completed",
+    stepId: step.id,
+    ...artifactName ? { artifact: artifactName, artifactHash } : {},
+    cached: false
+  });
+  await writeCacheEntry(ctx.cacheDir, {
+    semanticKey,
+    definitionKey,
+    ...artifactName ? { artifactName, artifactHash, artifact: result } : {}
+  });
+  return "ok";
+}
+
+// src/engine/run.ts
+var DEFAULT_ADAPTER = "claude-code";
+function defaultRunsDir() {
+  return path15.join(process.cwd(), ".runs");
+}
+function resolveDirs(runsDir, cwd, cacheDir) {
+  const resolvedRunsDir = runsDir ?? defaultRunsDir();
+  return {
+    runsDir: resolvedRunsDir,
+    cwd: cwd ?? process.cwd(),
+    cacheDir: cacheDir ?? path15.join(path15.dirname(resolvedRunsDir), ".yak", "cache")
+  };
+}
+function worktreePathFor(runsDir, runId) {
+  return path15.join(path15.dirname(runsDir), ".yak", "worktrees", runId);
+}
+function generateRunId() {
+  const iso = (/* @__PURE__ */ new Date()).toISOString();
+  const [datePart, timePart] = iso.split("T");
+  const time = (timePart ?? "").replace(/\.\d+Z$/, "").replace(/:/g, "-");
+  const suffix = randomBytes2(2).toString("hex");
+  return `${datePart}T${time}Z-${suffix}`;
+}
+async function executeWorkflowFile(workflowPath, opts = {}) {
+  const { runsDir, cwd, cacheDir } = resolveDirs(opts.runsDir, opts.cwd, opts.cacheDir);
+  const adapter = opts.adapter ?? DEFAULT_ADAPTER;
+  const isolation = opts.isolation ?? "none";
+  const raw = await loadWorkflowYaml(workflowPath);
+  const workflow = normalizeWorkflow(raw);
+  await validateWorkflow(workflow, cwd, isolation);
+  const runId = generateRunId();
+  const runDir = path15.join(runsDir, runId);
+  await mkdir6(runDir, { recursive: true });
+  await writeFile4(path15.join(runDir, "workflow.json"), JSON.stringify(workflow, null, 2), "utf8");
+  await appendJournalEvent(runDir, runId, {
+    t: "run.started",
+    runId,
+    workflow: workflow.name,
+    inputHash: sha256(JSON.stringify(workflow)),
+    adapter,
+    isolation
+  });
+  let stepCwd = cwd;
+  if (isolation === "worktree") {
+    const worktreePath = worktreePathFor(runsDir, runId);
+    try {
+      await createWorktree(cwd, `yak/${runId}`, "HEAD", worktreePath);
+    } catch {
+      await appendJournalEvent(runDir, runId, { t: "run.finished", status: "failed" });
+      return { runId, runDir, status: "failed" };
+    }
+    stepCwd = worktreePath;
+  }
+  const status = await runEligibleSteps(workflow, { runId, runDir, cwd: stepCwd, cacheDir, adapter });
+  await appendJournalEvent(runDir, runId, { t: "run.finished", status });
+  return { runId, runDir, status };
+}
+async function findLatestRunId(runsDir) {
+  const entries = await readdir2(runsDir).catch(() => []);
+  return entries.sort().at(-1);
+}
+async function readRunWorkflow(runDir) {
+  return JSON.parse(await readFile9(path15.join(runDir, "workflow.json"), "utf8"));
+}
+async function resolveOpenRequests(runId, runDir, workflow, cwd, events) {
+  const loopContinuations = /* @__PURE__ */ new Map();
+  const openIds = openRequestStepIds(events);
+  if (openIds.length === 0) return loopContinuations;
+  const flatSteps = flattenSteps(workflow.steps);
+  const gateAnswerSchema = async (request) => {
+    const step = flatSteps.find((s) => s.id === request.stepId);
+    if (!step || step.kind !== "gate") {
+      throw new Error(`pending request for step "${request.stepId}" but no gate step with that id exists`);
+    }
+    return resolveSchemaSpec(step.schema, cwd);
+  };
+  const resolutions = await Promise.all(openIds.map((stepId) => resolveAnswer(runDir, stepId, gateAnswerSchema)));
+  const missing = resolutions.filter((r) => r.status === "missing");
+  const invalid = resolutions.filter((r) => r.status === "invalid");
+  if (missing.length > 0 || invalid.length > 0) {
+    const lines = [
+      ...missing.map((r) => `  ${r.stepId}: no answer file written yet`),
+      ...invalid.map((r) => `  ${r.stepId}: invalid answer
+${r.errors.replace(/^/gm, "    ")}`)
+    ];
+    throw new Error(`run ${runId} still has unresolved pending requests:
+${lines.join("\n")}`);
+  }
+  for (const resolution of resolutions) {
+    if (resolution.status !== "ok") continue;
+    const { request, answer } = resolution;
+    if (request.kind === "loop-exhausted") {
+      loopContinuations.set(request.stepId, answer);
+      await appendJournalEvent(runDir, runId, { t: "gate.answered", stepId: request.stepId });
+      continue;
+    }
+    const step = flatSteps.find((s) => s.id === request.stepId);
+    if (!step || step.kind !== "gate") {
+      throw new Error(`pending request for step "${request.stepId}" but no gate step with that id exists`);
+    }
+    await completeGate(step, { runId, runDir, cwd }, answer, { skipped: false });
+  }
+  return loopContinuations;
+}
+async function resumeRun(runId, opts = {}) {
+  const { runsDir, cwd, cacheDir } = resolveDirs(opts.runsDir, opts.cwd, opts.cacheDir);
+  const runDir = path15.join(runsDir, runId);
+  const workflow = await readRunWorkflow(runDir);
+  let events = await readJournal(runDir);
+  const loopContinuations = await resolveOpenRequests(runId, runDir, workflow, cwd, events);
+  events = await readJournal(runDir);
+  const resumeState = completedStepsFromJournal(events);
+  const startedEvent = events.find((e) => e.t === "run.started");
+  const persistedAdapter = startedEvent?.adapter ?? DEFAULT_ADAPTER;
+  if (opts.adapter !== void 0 && opts.adapter !== persistedAdapter) {
+    throw new Error(
+      `run ${runId} started with adapter "${persistedAdapter}" \u2014 cannot resume with adapter "${opts.adapter}"`
+    );
+  }
+  const persistedIsolation = startedEvent?.isolation ?? "none";
+  if (opts.isolation !== void 0 && opts.isolation !== persistedIsolation) {
+    throw new Error(
+      `run ${runId} started with isolation "${persistedIsolation}" \u2014 cannot resume with isolation "${opts.isolation}"`
+    );
+  }
+  const stepCwd = persistedIsolation === "worktree" ? worktreePathFor(runsDir, runId) : cwd;
+  const status = await runEligibleSteps(
+    workflow,
+    { runId, runDir, cwd: stepCwd, cacheDir, adapter: persistedAdapter, loopContinuations },
+    resumeState
+  );
+  await appendJournalEvent(runDir, runId, { t: "run.finished", status });
+  return { runId, runDir, status };
+}
+
+// src/cli/commands/artifacts.ts
+async function artifactsCommand(runId, opts = {}) {
+  const runsDir = opts.runsDir ?? defaultRunsDir();
+  const resolvedRunId = runId ?? await findLatestRunId(runsDir);
+  if (!resolvedRunId) {
+    console.error("no runs found");
+    return 1;
+  }
+  const runDir = path16.join(runsDir, resolvedRunId);
+  const workflow = await readRunWorkflow(runDir).catch(() => void 0);
+  if (!workflow) {
+    console.error(`run ${resolvedRunId} not found`);
+    return 1;
+  }
+  console.log(`run ${resolvedRunId}:`);
+  const mapSteps = workflow.steps.filter((s) => s.kind === "map" && s.produces);
+  if (mapSteps.length === 0) {
+    console.log("  (no map steps with a produced artifact)");
+    return 0;
+  }
+  for (const step of mapSteps) {
+    const indices = await listMapItemArtifacts(runDir, step.produces);
+    console.log(`  ${step.id} (${step.produces}): items [${indices.join(", ")}]`);
+  }
+  return 0;
+}
+
+// src/cli/commands/graph.ts
+async function graphCommand(workflowPath) {
+  const raw = await loadWorkflowYaml(workflowPath);
+  const workflow = normalizeWorkflow(raw);
+  console.log(renderMermaid(workflow));
+  return 0;
+}
+
+// src/cli/commands/pending.ts
+import { readdir as readdir3 } from "fs/promises";
+import path17 from "path";
+async function pendingCommand(opts = {}) {
+  const runsDir = opts.runsDir ?? defaultRunsDir();
+  const runIds = (await readdir3(runsDir).catch(() => [])).sort();
+  let anyPending = false;
+  for (const runId of runIds) {
+    const runDir = path17.join(runsDir, runId);
+    const events = await readJournal(runDir);
+    const last = events.at(-1);
+    if (!last || last.t !== "run.finished" || last.status !== "suspended") continue;
+    anyPending = true;
+    console.log(`run ${runId} suspended:`);
+    const openIds = openRequestStepIds(events);
+    if (openIds.length === 0) {
+      console.log("  (no open request found \u2014 loop budget suspend from before M4, unresumable)");
+      continue;
+    }
+    for (const stepId of openIds) {
+      const request = await readPendingRequest(runDir, stepId);
+      if (!request) {
+        console.log(`  ${stepId}: (request file missing)`);
+        continue;
+      }
+      if (request.kind === "gate") {
+        console.log(`  ${stepId} (gate): ${request.rendered.split("\n")[0]}`);
+      } else {
+        console.log(`  ${stepId} (loop exhausted): tripped ${request.tripped} at iteration ${request.iteration}`);
+      }
+    }
+  }
+  if (!anyPending) console.log("nothing pending");
+  return 0;
+}
+
+// src/cli/commands/resume.ts
+async function resumeCommand(runId, adapter) {
+  let result;
+  try {
+    result = await resumeRun(runId, { adapter });
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+  if (result.status === "ok") {
+    console.log(`run ${result.runId} finished: ok`);
+    return 0;
+  }
+  console.error(`run ${result.runId} finished: ${result.status}`);
+  return 1;
+}
+
+// src/cli/commands/run.ts
+import path18 from "path";
+
+// src/cli/interactive.ts
+import { createInterface } from "readline";
+function terminalAsk(input, output) {
+  const rl = createInterface({ input, output });
+  const queued = [];
+  const waiters = [];
+  rl.on("line", (line) => {
+    const waiter = waiters.shift();
+    if (waiter) waiter(line);
+    else queued.push(line);
+  });
+  return (question) => {
+    output.write(question);
+    const queuedLine = queued.shift();
+    if (queuedLine !== void 0) return Promise.resolve(queuedLine);
+    return new Promise((resolve) => waiters.push(resolve));
+  };
+}
+async function promptForAnswer(request, ask, announce = () => {
+}) {
+  if (request.kind === "gate") {
+    announce(`
+${request.rendered}
+`);
+  } else {
+    announce(`
+loop "${request.stepId}" exhausted (${request.tripped}) at iteration ${request.iteration}
+`);
+  }
+  const schema = request.answerSchema;
+  const required = new Set(schema.required ?? []);
+  const answer = {};
+  for (const [name, prop] of Object.entries(schema.properties ?? {})) {
+    const value = await promptField(ask, name, prop, required.has(name));
+    if (value !== void 0) answer[name] = value;
+  }
+  return answer;
+}
+async function promptField(ask, name, prop, required) {
+  const label = required ? name : `${name} (optional, blank to skip)`;
+  for (; ; ) {
+    const raw = (await ask(prop.enum ? `${label} [${prop.enum.join("/")}]: ` : `${label}: `)).trim();
+    if (!raw) {
+      if (!required) return void 0;
+      continue;
+    }
+    if (prop.enum && !prop.enum.includes(raw)) continue;
+    if (prop.type === "number") {
+      const n = Number(raw);
+      if (Number.isNaN(n)) continue;
+      return n;
+    }
+    if (prop.type === "boolean") return /^y(es)?$/i.test(raw);
+    return raw;
+  }
+}
+
+// src/cli/commands/run.ts
+var EX_SUSPEND = 78;
+async function answerOpenRequestsInteractively(runId, runDir) {
+  const events = await readJournal(runDir);
+  const openIds = new Set(openRequestStepIds(events));
+  if (openIds.size === 0) return;
+  const workflow = await readRunWorkflow(runDir);
+  const orderedIds = workflow.steps.map((s) => s.id).filter((id) => openIds.has(id));
+  const ask = terminalAsk(process.stdin, process.stdout);
+  for (const stepId of orderedIds) {
+    const request = await readPendingRequest(runDir, stepId);
+    if (!request) continue;
+    const answer = await promptForAnswer(request, ask, (text) => console.log(text));
+    await writeAnswer(runDir, stepId, answer);
+  }
+}
+async function runCommand(workflowPath, opts = {}) {
+  let result = await executeWorkflowFile(path18.resolve(workflowPath), {
+    adapter: opts.adapter,
+    isolation: opts.isolation
+  });
+  while (opts.interactive && result.status === "suspended") {
+    await answerOpenRequestsInteractively(result.runId, result.runDir);
+    result = await resumeRun(result.runId, { adapter: opts.adapter });
+  }
+  if (result.status === "ok") {
+    console.log(`run ${result.runId} finished: ok`);
+    return 0;
+  }
+  if (result.status === "suspended") {
+    console.log(`run ${result.runId} suspended \u2014 resume with:
+  yak resume ${result.runId}`);
+    return EX_SUSPEND;
+  }
+  console.error(`run ${result.runId} finished: failed`);
+  return 1;
+}
+
+// src/cli/commands/status.ts
+import path19 from "path";
+
+// src/engine/status.ts
+function stepStatusesFromJournal(steps, events) {
+  const stateByStep = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    if (event.t === "step.started") {
+      stateByStep.set(event.stepId, "pending");
+    } else if (event.t === "step.completed") {
+      stateByStep.set(event.stepId, event.stale ? "stale" : event.cached ? "cached" : "completed");
+    } else if (event.t === "step.failed") {
+      stateByStep.set(event.stepId, "failed");
+    }
+  }
+  return steps.map((step) => ({ stepId: step.id, status: stateByStep.get(step.id) ?? "pending" }));
+}
+function loopStatusFromJournal(step, events) {
+  const bodyStepIds = new Set(step.body.map((s) => s.id));
+  let state = "pending";
+  for (const event of events) {
+    if (event.t === "step.started" && event.stepId === step.id) state = "running";
+    else if (event.t === "step.completed" && event.stepId === step.id) state = "completed";
+    else if (event.t === "step.failed" && event.stepId === step.id) state = "failed";
+    else if (event.t === "run.suspended" && event.loopStepId === step.id) state = "suspended";
+  }
+  const iteration = events.filter((e) => e.t === "step.started" && bodyStepIds.has(e.stepId)).reduce((max, e) => Math.max(max, e.iteration ?? 0), 0);
+  const consumedTokens = events.filter((e) => e.t === "budget.consumed" && bodyStepIds.has(e.stepId)).reduce((sum, e) => sum + e.tokens, 0);
+  const lastIterationEvent = [...events].reverse().find((e) => e.t === "loop.iteration" && e.stepId === step.id);
+  const noProgressSignal = lastIterationEvent?.t === "loop.iteration" ? lastIterationEvent.signal : void 0;
+  return {
+    stepId: step.id,
+    state,
+    iteration,
+    maxIterations: step.budget.maxIterations,
+    consumedTokens,
+    ...step.budget.maxTokens !== void 0 ? { maxTokens: step.budget.maxTokens } : {},
+    ...noProgressSignal !== void 0 ? { noProgressSignal } : {}
+  };
+}
+function formatLoopBudget(detail) {
+  return detail.maxTokens !== void 0 ? `iteration ${detail.iteration}/${detail.maxIterations}, tokens ${detail.consumedTokens}/${detail.maxTokens}` : `iteration ${detail.iteration}/${detail.maxIterations}, tokens ${detail.consumedTokens}`;
+}
+
+// src/cli/commands/status.ts
+async function statusCommand(runId, opts = {}) {
+  const runsDir = opts.runsDir ?? defaultRunsDir();
+  const resolvedRunId = runId ?? await findLatestRunId(runsDir);
+  if (!resolvedRunId) {
+    console.error("no runs found");
+    return 1;
+  }
+  const runDir = path19.join(runsDir, resolvedRunId);
+  const workflow = await readRunWorkflow(runDir).catch(() => void 0);
+  if (!workflow) {
+    console.error(`run ${resolvedRunId} not found`);
+    return 1;
+  }
+  const events = await readJournal(runDir);
+  const statuses = stepStatusesFromJournal(workflow.steps, events);
+  console.log(`run ${resolvedRunId}:`);
+  for (const { stepId, status } of statuses) {
+    console.log(`  ${stepId}: ${status}`);
+    const step = workflow.steps.find((s) => s.id === stepId);
+    if (step?.kind === "loop") {
+      const detail = loopStatusFromJournal(step, events);
+      const signal = detail.noProgressSignal !== void 0 ? `, noProgress signal ${detail.noProgressSignal}` : "";
+      console.log(`    ${formatLoopBudget(detail)}${signal}`);
+    }
+  }
+  return 0;
+}
+
+// src/cli/commands/watch.ts
+import path20 from "path";
+import { render } from "ink";
+import React2 from "react";
+
+// src/engine/watch.ts
+function isLoopStep(step) {
+  return step.kind === "loop";
+}
+function snapshotFromJournal(workflow, events) {
+  const stepStatuses = stepStatusesFromJournal(workflow.steps, events);
+  const loopStatuses = flattenSteps(workflow.steps).filter(isLoopStep).map((step) => loopStatusFromJournal(step, events));
+  const openGateIds = openRequestStepIds(events);
+  const finishedEvent = [...events].reverse().find((e) => e.t === "run.finished");
+  const runStatus = finishedEvent?.t === "run.finished" ? finishedEvent.status : void 0;
+  return { stepStatuses, loopStatuses, openGateIds, ...runStatus !== void 0 ? { runStatus } : {} };
+}
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function watchRun(runDir, workflow, onSnapshot, intervalMs = 300, deps = { readJournal, sleep: defaultSleep }) {
+  let lastSerialized;
+  for (; ; ) {
+    const events = await deps.readJournal(runDir);
+    const snapshot = snapshotFromJournal(workflow, events);
+    const serialized = JSON.stringify(snapshot);
+    if (serialized !== lastSerialized) {
+      onSnapshot(snapshot);
+      lastSerialized = serialized;
+    }
+    if (snapshot.runStatus !== void 0) return snapshot;
+    await deps.sleep(intervalMs);
+  }
+}
+
+// src/cli/watch-ui.ts
+import { Box, Text } from "ink";
+import React from "react";
+var h = React.createElement;
+function WatchApp({ snapshot }) {
+  const openGates = new Set(snapshot.openGateIds);
+  const stepRows = snapshot.stepStatuses.map(
+    (s) => h(
+      Text,
+      { key: s.stepId, color: openGates.has(s.stepId) ? "yellow" : void 0 },
+      `${s.stepId}: ${s.status}${openGates.has(s.stepId) ? " \u2014 awaiting yak resume" : ""}`
+    )
+  );
+  const loopRows = snapshot.loopStatuses.map(
+    (l) => h(Text, { key: `loop-${l.stepId}`, dimColor: true }, `  ${l.stepId}: ${formatLoopBudget(l)}`)
+  );
+  const footer = snapshot.runStatus !== void 0 ? [h(Text, { key: "footer", bold: true }, `run ${snapshot.runStatus}`)] : [];
+  return h(Box, { flexDirection: "column" }, ...stepRows, ...loopRows, ...footer);
+}
+
+// src/cli/commands/watch.ts
+async function watchCommand(runId, opts = {}) {
+  const runsDir = opts.runsDir ?? defaultRunsDir();
+  const resolvedRunId = runId ?? await findLatestRunId(runsDir);
+  if (!resolvedRunId) {
+    console.error("no runs found");
+    return 1;
+  }
+  const runDir = path20.join(runsDir, resolvedRunId);
+  const workflow = await readRunWorkflow(runDir).catch(() => void 0);
+  if (!workflow) {
+    console.error(`run ${resolvedRunId} not found`);
+    return 1;
+  }
+  const initialEvents = await readJournal(runDir);
+  const instance = render(React2.createElement(WatchApp, { snapshot: snapshotFromJournal(workflow, initialEvents) }));
+  await watchRun(runDir, workflow, (snapshot) => {
+    instance.rerender(React2.createElement(WatchApp, { snapshot }));
+  });
+  instance.unmount();
+  await instance.waitUntilExit();
+  return 0;
+}
+
+// src/cli/index.ts
+function requireAdapterId(value) {
+  if (value !== "mock" && value !== "claude-code") {
+    throw new Error(`--adapter must be "mock" or "claude-code", got "${value}"`);
+  }
+  return value;
+}
+function requireIsolation(value) {
+  if (value !== "worktree" && value !== "none") {
+    throw new Error(`--isolation must be "worktree" or "none", got "${value}"`);
+  }
+  return value;
+}
+var program = new Command();
+program.name("yak").description("An agentic workflow engine").version("0.0.1");
+program.command("run").description("Run a workflow YAML file").argument("<workflow>", "path to the workflow YAML file").option("--adapter <adapter>", "agent adapter to use", "claude-code").option("--interactive", "prompt inline for gate answers instead of exiting to resume later", false).option("--isolation <mode>", 'run inside a fresh git worktree ("worktree") or the plain cwd ("none")', "none").action(async (workflow, options) => {
+  process.exitCode = await runCommand(workflow, {
+    adapter: requireAdapterId(options.adapter),
+    interactive: options.interactive,
+    isolation: requireIsolation(options.isolation)
+  });
+});
+program.command("resume").description("Resume an interrupted run").argument("<run-id>", "id of the run to resume").option("--adapter <adapter>", "must match the adapter the run started with, if given").action(async (runId, options) => {
+  process.exitCode = await resumeCommand(runId, options.adapter ? requireAdapterId(options.adapter) : void 0);
+});
+program.command("status").description("Report a run's per-step status").argument("[run-id]", "id of the run to report on (default: most recent)").action(async (runId) => {
+  process.exitCode = await statusCommand(runId);
+});
+program.command("pending").description("List every run across the repo awaiting a human answer").action(async () => {
+  process.exitCode = await pendingCommand();
+});
+program.command("graph").description("Emit a workflow's DAG as Mermaid to stdout").argument("<workflow>", "path to the workflow YAML file").action(async (workflow) => {
+  process.exitCode = await graphCommand(workflow);
+});
+program.command("watch").description("Live-tail a run's step statuses in a terminal UI").argument("[run-id]", "id of the run to watch (default: most recent)").action(async (runId) => {
+  process.exitCode = await watchCommand(runId);
+});
+program.command("artifacts").description("List a map step's per-item artifact files for a run").argument("[run-id]", "id of the run to report on (default: most recent)").action(async (runId) => {
+  process.exitCode = await artifactsCommand(runId);
+});
+program.parse();