@netnodeag/kraftwerk 0.2.0

package/dist/harnesses/pi.js

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+/**
+ * pi harness (badlogic/pi-mono): a thin coding agent over raw vendor APIs —
+ * Anthropic (also via the Claude subscription OAuth), OpenAI, DeepSeek,
+ * Groq, OpenRouter, and many more. This is the "direct API call" runtime:
+ * same file tools and sessions as claude -p, any provider behind it.
+ *
+ * Model ids use pi's `provider/id` form, e.g. "anthropic/claude-haiku-4-5"
+ * or "deepseek/deepseek-chat" (vendor API key in env for non-OAuth
+ * providers; check with `pi auth check --provider <name>`).
+ *
+ * Session handling: `--session-id` is create-or-continue, so the adapter
+ * generates the id on the first call and simply reuses it to resume —
+ * nothing to parse back. `--no-context-files` keeps the run hermetic
+ * (no AGENTS.md/CLAUDE.md discovery). The effort scale maps 1:1 onto
+ * `--thinking` (low..max).
+ *
+ * JSONL events (verified against pi 0.84.1):
+ *   session              {id, cwd}
+ *   tool_execution_start {toolName, args: {path|command|...}}
+ *   message_end          {message: {role, content[{type,text}],
+ *                          usage: {input, output, cacheRead, cacheWrite,
+ *                                  cost: {total}}}}
+ *   agent_end / agent_settled
+ */
+/** Framework tool names → pi built-in tool names. Unmapped tools (e.g. WebFetch) are dropped. */
+const TOOL_MAP = {
+    Read: "read",
+    Write: "write",
+    Edit: "edit",
+    Bash: "bash",
+    Grep: "grep",
+    Glob: "find",
+    LS: "ls",
+};
+const clip = (raw) => {
+    const oneLine = raw.replace(/\s+/g, " ").trim();
+    return oneLine.length > 160 ? `${oneLine.slice(0, 160)}…` : oneLine;
+};
+function invokePi(inv) {
+    if (Object.keys(inv.mcpServers ?? {}).length > 0) {
+        throw new Error("pi harness has no MCP support (pi uses its own extension system) — run this agent on claude or codex");
+    }
+    const sessionId = inv.resume ?? randomUUID();
+    const tools = inv.tools.map((t) => TOOL_MAP[t]).filter(Boolean);
+    // pi has no per-command allowlist: a CLI grant enables the plain bash
+    // tool; the scoping lives only in the persona hints.
+    if ((inv.clis?.length ?? 0) > 0 && !tools.includes("bash"))
+        tools.push("bash");
+    const args = [
+        "-p",
+        "--mode", "json",
+        "--model", inv.model,
+        "--system-prompt", inv.systemPrompt,
+        "--tools", tools.join(","),
+        "--no-context-files",
+        "--session-id", sessionId,
+    ];
+    if (inv.effort)
+        args.push("--thinking", inv.effort);
+    const started = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = spawn("pi", args, {
+            cwd: inv.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        child.stdin.write(inv.prompt);
+        child.stdin.end();
+        const usage = {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+        };
+        let costUsd = 0;
+        let sawAssistant = false;
+        const texts = [];
+        let failure;
+        let stderr = "";
+        let buffer = "";
+        const handleLine = (line) => {
+            if (!line.trim())
+                return;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                return; // non-JSON noise on stdout
+            }
+            if (event.type === "tool_execution_start" && event.toolName) {
+                const a = event.args ?? {};
+                const raw = a.path ?? a.file_path ?? a.command ?? a.pattern ?? "";
+                inv.onToolUse?.(event.toolName, clip(String(raw)));
+            }
+            if (event.type === "message_end" && event.message?.role === "assistant") {
+                sawAssistant = true;
+                for (const block of event.message.content ?? []) {
+                    if (block?.type === "text" && block.text?.trim()) {
+                        texts.push(block.text.trim());
+                        inv.onText?.(block.text.trim());
+                    }
+                }
+                const u = event.message.usage;
+                if (u) {
+                    usage.inputTokens += u.input ?? 0;
+                    usage.outputTokens += u.output ?? 0;
+                    usage.cacheReadTokens += u.cacheRead ?? 0;
+                    usage.cacheCreationTokens += u.cacheWrite ?? 0;
+                    costUsd += u.cost?.total ?? 0;
+                }
+            }
+            if (event.type === "error") {
+                failure = typeof event.error === "string" ? event.error : line;
+            }
+        };
+        child.stdout.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            lines.forEach(handleLine);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (err) => reject(new Error(`could not spawn pi: ${err.message}`)));
+        child.on("close", (code) => {
+            handleLine(buffer);
+            if (failure || code !== 0 || !sawAssistant) {
+                reject(new Error(`pi failed (exit ${code})` +
+                    (failure ? `: ${failure}` : "") +
+                    (stderr.trim() ? `\nstderr: ${stderr.trim().slice(-2000)}` : "")));
+                return;
+            }
+            resolve({
+                sessionId,
+                // The envelope sits in the last message; parseEnvelope takes the
+                // last fenced block, so joining all messages is safe.
+                text: texts.join("\n\n"),
+                durationMs: Date.now() - started,
+                costUsd,
+                usage,
+            });
+        });
+    });
+}
+export const piHarness = {
+    id: "pi",
+    invoke: invokePi,
+};

package/dist/harnesses/registry.d.ts

@@ -0,0 +1,2 @@
+import type { Harness, HarnessId } from "../harness.js";
+export declare function harnessFor(id?: HarnessId): Harness;

package/dist/harnesses/registry.js

@@ -0,0 +1,19 @@
+import { claudeHarness } from "./claude.js";
+import { codexHarness } from "./codex.js";
+import { piHarness } from "./pi.js";
+/**
+ * Maps an agent's `harness` field to the adapter that runs it.
+ * Default is claude — an agent without a harness runs on `claude -p`.
+ */
+const HARNESSES = {
+    claude: claudeHarness,
+    codex: codexHarness,
+    pi: piHarness,
+};
+export function harnessFor(id = "claude") {
+    const harness = HARNESSES[id];
+    if (!harness) {
+        throw new Error(`harness "${id}" is not registered (available: ${Object.keys(HARNESSES).join(", ")})`);
+    }
+    return harness;
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * kraftwerk — deterministic workflow-as-code over headless agent
+ * harnesses. "Agent proposes, code disposes."
+ *
+ * An agent is persona + model/effort + tools + harness (defineAgent); the
+ * Run executes it inside bounded phases (agentPhase/codePhase), judges the
+ * result (envelope + gates), corrects in the same session, and accounts for
+ * time/tokens/cost. Harnesses: claude -p (default), codex exec, pi.
+ */
+export { defineAgent, type AgentDefinition, type EffortLevel } from "./agent.js";
+export { type AgentInvocation, type AgentResult, type Harness, type HarnessId, type McpServerConfig, type TokenUsage, } from "./harness.js";
+export { harnessFor } from "./harnesses/registry.js";
+export { Run, type RunOptions } from "./run.js";
+export { correctionPrompt, envelopeContract, parseEnvelope, type Envelope, } from "./envelope.js";
+export { containsText, fileNonEmpty, slotsFilled, type Gate } from "./gates.js";
+export { fmtDuration, fmtTokens, phaseStatsLine, summaryTable, totalIn, type PhaseStats, type RunTotals, } from "./stats.js";
+export { runStamp, type RunResult, type WorkflowDefinition, type WorkflowRunOptions, } from "./workflow.js";
+export { runCli } from "./cli.js";
+export { loadWorkflow, loadWorkflowYaml, missingEnv, type LoadedWorkflow } from "./yaml.js";
+export { discoverWorkflows, findWorkflowsRoot, type DiscoveredWorkflow } from "./discover.js";
+export { validateWorkflows } from "./validate.js";
+export { resolveProject, SCHEMA_URL, type Project, type ProjectConfig } from "./config.js";
+export { isRemoteSpec, resolveRemote, type RemoteSource } from "./remote.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * kraftwerk — deterministic workflow-as-code over headless agent
+ * harnesses. "Agent proposes, code disposes."
+ *
+ * An agent is persona + model/effort + tools + harness (defineAgent); the
+ * Run executes it inside bounded phases (agentPhase/codePhase), judges the
+ * result (envelope + gates), corrects in the same session, and accounts for
+ * time/tokens/cost. Harnesses: claude -p (default), codex exec, pi.
+ */
+export { defineAgent } from "./agent.js";
+export { harnessFor } from "./harnesses/registry.js";
+export { Run } from "./run.js";
+export { correctionPrompt, envelopeContract, parseEnvelope, } from "./envelope.js";
+export { containsText, fileNonEmpty, slotsFilled } from "./gates.js";
+export { fmtDuration, fmtTokens, phaseStatsLine, summaryTable, totalIn, } from "./stats.js";
+export { runStamp, } from "./workflow.js";
+export { runCli } from "./cli.js";
+export { loadWorkflow, loadWorkflowYaml, missingEnv } from "./yaml.js";
+export { discoverWorkflows, findWorkflowsRoot } from "./discover.js";
+export { validateWorkflows } from "./validate.js";
+export { resolveProject, SCHEMA_URL } from "./config.js";
+export { isRemoteSpec, resolveRemote } from "./remote.js";

package/dist/remote.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Remote workflow sources: run workflows straight from a git repository
+ * without vendoring them ("kraftwerk run --from github:org/repo tagline ...").
+ *
+ * Spec forms:
+ *   github:org/repo          shorthand for https://github.com/org/repo.git
+ *   github:org/repo@ref      branch, tag, or commit
+ *   https://.../repo.git     any https git remote (also with @ref)
+ *   git@host:org/repo.git    any ssh git remote (also with @ref)
+ *
+ * Clones land shallow in ~/.cache/kraftwerk/remotes/<slug>; an existing
+ * clone is refreshed with fetch + reset. Offline with an existing clone
+ * degrades to a warning and uses the cached state.
+ */
+export interface RemoteSource {
+    /** Absolute directory of the (refreshed) clone — the project root to discover in. */
+    dir: string;
+    url: string;
+    ref?: string;
+}
+export declare function isRemoteSpec(spec: string): boolean;
+/** Clone or refresh the spec's repository; returns the local project dir. */
+export declare function resolveRemote(spec: string): Promise<RemoteSource>;

package/dist/remote.js

@@ -0,0 +1,57 @@
+import { spawnSync } from "node:child_process";
+import { mkdir, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export function isRemoteSpec(spec) {
+    return /^github:|^https:\/\/|^git@/.test(spec);
+}
+function parseSpec(spec) {
+    // @ref suffix: split on the last @ that isn't part of git@host.
+    let rest = spec;
+    let ref;
+    const at = rest.lastIndexOf("@");
+    if (at > rest.indexOf(":") && at > 0) {
+        ref = rest.slice(at + 1);
+        rest = rest.slice(0, at);
+    }
+    if (rest.startsWith("github:")) {
+        const orgRepo = rest.slice("github:".length).replace(/\/+$/, "");
+        if (!/^[\w.-]+\/[\w.-]+$/.test(orgRepo)) {
+            throw new Error(`Invalid github: source "${spec}" — expected github:org/repo[@ref]`);
+        }
+        return { url: `https://github.com/${orgRepo}.git`, ref };
+    }
+    return { url: rest, ref };
+}
+const slugify = (s) => s.replace(/^https:\/\/|^git@|\.git$/g, "").replace(/[^A-Za-z0-9._-]+/g, "-");
+function git(args, cwd) {
+    const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+    return { ok: r.status === 0, out: (r.stderr || r.stdout || "").trim() };
+}
+/** Clone or refresh the spec's repository; returns the local project dir. */
+export async function resolveRemote(spec) {
+    const { url, ref } = parseSpec(spec);
+    const cacheRoot = path.join(os.homedir(), ".cache", "kraftwerk", "remotes");
+    const dir = path.join(cacheRoot, slugify(url) + (ref ? `-${slugify(ref)}` : ""));
+    await mkdir(cacheRoot, { recursive: true });
+    const cloned = (await stat(path.join(dir, ".git")).catch(() => null)) !== null;
+    if (!cloned) {
+        const args = ["clone", "--depth", "1", ...(ref ? ["--branch", ref] : []), url, dir];
+        const r = git(args);
+        if (!r.ok)
+            throw new Error(`git clone ${url} failed:\n${r.out}`);
+    }
+    else {
+        const fetched = git(["fetch", "--depth", "1", "origin", ...(ref ? [ref] : [])], dir);
+        if (fetched.ok) {
+            const target = ref ? "FETCH_HEAD" : "origin/HEAD";
+            const reset = git(["reset", "--hard", target], dir);
+            if (!reset.ok)
+                git(["reset", "--hard", "FETCH_HEAD"], dir);
+        }
+        else {
+            console.error(`Warning: ${url} not reachable — using the cached state.`);
+        }
+    }
+    return { dir, url, ref };
+}

package/dist/run.d.ts

@@ -0,0 +1,66 @@
+import type { AgentDefinition } from "./agent.js";
+import { type Envelope } from "./envelope.js";
+import type { Gate } from "./gates.js";
+import { type PhaseStats } from "./stats.js";
+/**
+ * The phase runner: agent proposes, code disposes. An agent phase spawns one
+ * headless `claude -p` process, then the ORCHESTRATOR judges the result
+ * (envelope parse + gates). Failures produce a correction prompt into the
+ * same session, bounded by maxGateRetries. Agents never control retries
+ * or phase transitions.
+ *
+ * The runner is workflow-agnostic: agents, prompts, and gates are injected
+ * per phase by the concrete workflow. Per phase, the agent's persona is
+ * composed with the run's workspace context into the system prompt; one
+ * session PER HARNESS is shared across phases via resume, so a phase sees
+ * the prior conversation on its harness but always speaks with its own
+ * agent's voice. Across harnesses, context travels through the run files.
+ *
+ * Every event is appended to <runDir>/trace.jsonl for observability.
+ */
+export interface RunOptions {
+    runDir: string;
+    /**
+     * Workflow-level context appended to every agent's persona: the run
+     * directory, the file layout, how the orchestrator works.
+     */
+    workspaceContext: string;
+    verbose?: boolean;
+    /** Corrections in the same session before the run aborts. Default 2. */
+    maxGateRetries?: number;
+}
+export declare class Run {
+    private readonly sessions;
+    /** Per-phase stats in execution order; repeated phases appear once per execution. */
+    readonly stats: PhaseStats[];
+    readonly runDir: string;
+    private readonly workspaceContext;
+    private readonly verbose;
+    private readonly maxGateRetries;
+    constructor(options: RunOptions);
+    trace(event: string, data?: Record<string, unknown>): Promise<void>;
+    agentPhase(params: {
+        name: string;
+        agent: AgentDefinition;
+        prompt: string;
+        gates: Gate[];
+    }): Promise<Envelope>;
+    /**
+     * Deterministic script phase: run a bash script in the run directory —
+     * no agent, no LLM. The script sees REQUEST, RUN_DIR, PHASE, and (in
+     * folder mode) WORKFLOW_DIR as env vars. It hands over the same envelope as an agent phase: either it
+     * prints the fenced ```json envelope itself (last block on stdout wins),
+     * or the runner synthesizes one from the exit code (status ok, summary =
+     * last stdout line). Gates run afterwards, but there is no correction
+     * loop — a script is deterministic, so a failing gate fails the run.
+     */
+    scriptPhase(params: {
+        name: string;
+        script: string;
+        gates: Gate[];
+        env?: Record<string, string>;
+    }): Promise<Envelope>;
+    codePhase<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /** Per-phase table (time, tokens, cost) plus totals; also traced as run_summary. */
+    printSummary(): Promise<void>;
+}

package/dist/run.js

@@ -0,0 +1,278 @@
+import { spawn } from "node:child_process";
+import { appendFile } from "node:fs/promises";
+import path from "node:path";
+import { harnessFor } from "./harnesses/registry.js";
+import { correctionPrompt, parseEnvelope } from "./envelope.js";
+import { fmtDuration, phaseStatsLine, summaryTable } from "./stats.js";
+export class Run {
+    sessions = new Map();
+    /** Per-phase stats in execution order; repeated phases appear once per execution. */
+    stats = [];
+    runDir;
+    workspaceContext;
+    verbose;
+    maxGateRetries;
+    constructor(options) {
+        this.runDir = options.runDir;
+        this.workspaceContext = options.workspaceContext;
+        this.verbose = options.verbose ?? false;
+        this.maxGateRetries = options.maxGateRetries ?? 2;
+    }
+    async trace(event, data = {}) {
+        await appendFile(path.join(this.runDir, "trace.jsonl"), JSON.stringify({ ts: new Date().toISOString(), event, ...data }) + "\n");
+    }
+    async agentPhase(params) {
+        const { agent } = params;
+        const harness = harnessFor(agent.harness);
+        const modelName = harness.id === "claude" ? agent.model : `${harness.id}:${agent.model}`;
+        const modelLabel = agent.effort ? `${modelName}, effort ${agent.effort}` : modelName;
+        console.log(`\n▸ Phase "${params.name}" — ${agent.name} [${agent.id}] (${modelLabel})`);
+        await this.trace("phase_start", {
+            phase: params.name,
+            kind: "agent",
+            agent: agent.id,
+            harness: harness.id,
+            model: agent.model,
+            effort: agent.effort ?? null,
+            clis: agent.clis ? Object.keys(agent.clis) : [],
+            mcp: agent.mcp ? Object.keys(agent.mcp) : [],
+            resume: this.sessions.get(harness.id) ?? null,
+        });
+        const phaseStats = {
+            phase: params.name,
+            kind: "agent",
+            agent: agent.id,
+            harness: harness.id,
+            model: agent.model,
+            effort: agent.effort,
+            attempts: 0,
+            durationMs: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+            costUsd: 0,
+        };
+        const started = Date.now();
+        // CLI grants are persona-level knowledge: inject the usage hints once
+        // here instead of repeating them in every step prompt.
+        const cliEntries = Object.entries(agent.clis ?? {});
+        const cliBlock = cliEntries.length
+            ? "\n\nThese CLIs are available to you via Bash (pre-approved, usable without asking):\n" +
+                cliEntries
+                    .map(([name, hint]) => `- ${name}${hint.trim() ? ` — ${hint.trim()}` : ""}`)
+                    .join("\n")
+            : "";
+        let prompt = params.prompt;
+        for (let attempt = 0; attempt <= this.maxGateRetries; attempt++) {
+            const result = await harness.invoke({
+                prompt,
+                systemPrompt: `${agent.persona.trim()}${cliBlock}\n\n${this.workspaceContext.trim()}`,
+                cwd: this.runDir,
+                model: agent.model,
+                effort: agent.effort,
+                tools: agent.tools,
+                clis: cliEntries.map(([name]) => name),
+                mcpServers: agent.mcp,
+                resume: this.sessions.get(harness.id),
+                onToolUse: (tool, target) => {
+                    console.log(`  ⚙ ${tool} ${target}`.trimEnd());
+                    void this.trace("tool_use", { phase: params.name, attempt, tool, target });
+                },
+                onText: this.verbose ? (text) => console.log(`  💬 ${text}`) : undefined,
+            });
+            if (result.sessionId)
+                this.sessions.set(harness.id, result.sessionId);
+            phaseStats.attempts = attempt + 1;
+            phaseStats.durationMs = Date.now() - started;
+            phaseStats.costUsd += result.costUsd ?? 0;
+            if (result.usage) {
+                phaseStats.inputTokens += result.usage.inputTokens;
+                phaseStats.outputTokens += result.usage.outputTokens;
+                phaseStats.cacheReadTokens += result.usage.cacheReadTokens;
+                phaseStats.cacheCreationTokens += result.usage.cacheCreationTokens;
+            }
+            await this.trace("agent_result", {
+                phase: params.name,
+                attempt,
+                harness: harness.id,
+                sessionId: result.sessionId,
+                numTurns: result.numTurns,
+                durationMs: result.durationMs,
+                costUsd: result.costUsd,
+                usage: result.usage,
+            });
+            const failures = [];
+            let envelope;
+            try {
+                envelope = parseEnvelope(result.text, params.name);
+                await this.trace("envelope", { phase: params.name, attempt, envelope });
+            }
+            catch (err) {
+                failures.push(err.message);
+            }
+            if (envelope?.status === "blocked") {
+                await this.trace("phase_end", { phase: params.name, status: "blocked" });
+                throw new Error(`Phase "${params.name}" blocked by agent: ${envelope.reason ?? "no reason given"}`);
+            }
+            for (const gate of params.gates) {
+                const failure = await gate.check(this.runDir);
+                await this.trace("gate_result", {
+                    phase: params.name,
+                    attempt,
+                    gate: gate.name,
+                    passed: failure === null,
+                    failure,
+                });
+                if (failure)
+                    failures.push(`${gate.name}: ${failure}`);
+            }
+            if (failures.length === 0) {
+                this.stats.push(phaseStats);
+                console.log(`  ✔ envelope + ${params.gates.length} gates passed (${phaseStatsLine(phaseStats, result.numTurns)})`);
+                await this.trace("phase_end", { phase: params.name, status: "ok", stats: phaseStats });
+                return envelope;
+            }
+            const retrying = attempt < this.maxGateRetries;
+            console.log(`  ✖ ${failures.length} check(s) failed${retrying ? ", correcting in the same session" : ""}`);
+            for (const failure of failures)
+                console.log(`    - ${failure}`);
+            prompt = correctionPrompt(params.name, failures);
+        }
+        this.stats.push(phaseStats);
+        await this.trace("phase_end", { phase: params.name, status: "failed", stats: phaseStats });
+        throw new Error(`Phase "${params.name}" failed after ${this.maxGateRetries + 1} attempts`);
+    }
+    /**
+     * Deterministic script phase: run a bash script in the run directory —
+     * no agent, no LLM. The script sees REQUEST, RUN_DIR, PHASE, and (in
+     * folder mode) WORKFLOW_DIR as env vars. It hands over the same envelope as an agent phase: either it
+     * prints the fenced ```json envelope itself (last block on stdout wins),
+     * or the runner synthesizes one from the exit code (status ok, summary =
+     * last stdout line). Gates run afterwards, but there is no correction
+     * loop — a script is deterministic, so a failing gate fails the run.
+     */
+    async scriptPhase(params) {
+        console.log(`\n▸ Phase "${params.name}" — script (bash)`);
+        await this.trace("phase_start", { phase: params.name, kind: "script" });
+        const started = Date.now();
+        const result = await new Promise((resolve, reject) => {
+            const child = spawn("bash", ["-c", params.script], {
+                cwd: this.runDir,
+                env: { ...process.env, RUN_DIR: this.runDir, PHASE: params.name, ...params.env },
+            });
+            let stdout = "";
+            let stderr = "";
+            child.stdout.on("data", (chunk) => {
+                const text = String(chunk);
+                stdout += text;
+                if (this.verbose) {
+                    for (const line of text.split("\n")) {
+                        if (line.trim())
+                            console.log(`  💬 ${line}`);
+                    }
+                }
+            });
+            child.stderr.on("data", (chunk) => (stderr += String(chunk)));
+            child.on("error", reject);
+            child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+        });
+        const phaseStats = {
+            phase: params.name,
+            kind: "script",
+            attempts: 1,
+            durationMs: Date.now() - started,
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+            costUsd: 0,
+        };
+        await this.trace("script_result", {
+            phase: params.name,
+            exitCode: result.code,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        });
+        const fail = async (message) => {
+            this.stats.push(phaseStats);
+            await this.trace("phase_end", { phase: params.name, status: "failed", stats: phaseStats });
+            throw new Error(`Phase "${params.name}" (script) failed: ${message}`);
+        };
+        if (result.code !== 0) {
+            const tail = result.stderr.trim().split("\n").slice(-5).join("\n");
+            return await fail(`exit code ${result.code}${tail ? `\n${tail}` : ""}`);
+        }
+        let envelope;
+        if (result.stdout.includes("```json")) {
+            try {
+                envelope = parseEnvelope(result.stdout, params.name);
+            }
+            catch (err) {
+                return await fail(err.message);
+            }
+        }
+        else {
+            const lines = result.stdout.trim().split("\n").filter((l) => l.trim());
+            envelope = {
+                phase: params.name,
+                status: "ok",
+                artifacts: [],
+                summary: lines.at(-1),
+            };
+        }
+        await this.trace("envelope", { phase: params.name, envelope });
+        if (envelope.status === "blocked") {
+            return await fail(`blocked: ${envelope.reason ?? "no reason given"}`);
+        }
+        const failures = [];
+        for (const gate of params.gates) {
+            const failure = await gate.check(this.runDir);
+            await this.trace("gate_result", {
+                phase: params.name,
+                gate: gate.name,
+                passed: failure === null,
+                failure,
+            });
+            if (failure)
+                failures.push(`${gate.name}: ${failure}`);
+        }
+        if (failures.length > 0) {
+            for (const failure of failures)
+                console.log(`    - ${failure}`);
+            return await fail(`${failures.length} gate(s) failed — script steps are deterministic, no correction loop`);
+        }
+        this.stats.push(phaseStats);
+        console.log(`  ✔ envelope + ${params.gates.length} gates passed (exit 0 | ${fmtDuration(phaseStats.durationMs)})`);
+        await this.trace("phase_end", { phase: params.name, status: "ok", stats: phaseStats });
+        return envelope;
+    }
+    async codePhase(name, fn) {
+        console.log(`\n▸ Phase "${name}" — code`);
+        await this.trace("phase_start", { phase: name, kind: "code" });
+        const started = Date.now();
+        const value = await fn();
+        const phaseStats = {
+            phase: name,
+            kind: "code",
+            attempts: 1,
+            durationMs: Date.now() - started,
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+            costUsd: 0,
+        };
+        this.stats.push(phaseStats);
+        await this.trace("phase_end", { phase: name, status: "ok", stats: phaseStats });
+        return value;
+    }
+    /** Per-phase table (time, tokens, cost) plus totals; also traced as run_summary. */
+    async printSummary() {
+        const { lines, total } = summaryTable(this.stats);
+        console.log(`\n▸ Run summary`);
+        for (const line of lines)
+            console.log(line);
+        await this.trace("run_summary", { phases: this.stats, total });
+    }
+}