@devosurf/tesser 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@devosurf/tesser",
+  "version": "0.1.0-alpha.0",
+  "description": "Tesser CLI — the machine-first interface for agents and humans.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "tesser": "./bin/tesser.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "esbuild": "^0.28.1",
+    "@devosurf/tesser-sdk": "0.1.0-alpha.0",
+    "@devosurf/tesser-testing": "0.1.0-alpha.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,63 @@
+// Thin control-plane client. Every command is a shell over this (ADR-0007).
+
+import { EXIT } from "./exit-codes.js";
+import { CliError } from "./output.js";
+
+export class ApiClient {
+  constructor(
+    readonly baseUrl: string,
+    readonly token: string | undefined,
+  ) {}
+
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    if (!this.token) {
+      throw new CliError(
+        EXIT.AUTH,
+        "no API token — run `tesser login --url <instance> --token <tsk_…>` or set TESSER_TOKEN",
+      );
+    }
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}/api${path}`, {
+        method,
+        headers: {
+          authorization: `Bearer ${this.token}`,
+          ...(body !== undefined ? { "content-type": "application/json" } : {}),
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      });
+    } catch (cause) {
+      throw new CliError(EXIT.AUTH, `cannot reach instance at ${this.baseUrl} (${String(cause)})`);
+    }
+    const text = await res.text();
+    let parsed: unknown;
+    try {
+      parsed = text.length > 0 ? JSON.parse(text) : null;
+    } catch {
+      parsed = { raw: text };
+    }
+    if (!res.ok) {
+      const errBody = parsed as { error?: { code?: string; message?: string } };
+      const message = errBody?.error?.message ?? `instance responded ${res.status}`;
+      if (res.status === 401) throw new CliError(EXIT.AUTH, message);
+      if (res.status === 404) throw new CliError(EXIT.NOT_FOUND, message);
+      if (res.status === 400) throw new CliError(EXIT.USAGE, message);
+      if (res.status === 409) throw new CliError(EXIT.CONFLICT, message);
+      throw new CliError(EXIT.ERROR, message);
+    }
+    return parsed as T;
+  }
+
+  get<T>(path: string): Promise<T> {
+    return this.request("GET", path);
+  }
+  post<T>(path: string, body?: unknown): Promise<T> {
+    return this.request("POST", path, body);
+  }
+  put<T>(path: string, body?: unknown): Promise<T> {
+    return this.request("PUT", path, body);
+  }
+  delete<T>(path: string): Promise<T> {
+    return this.request("DELETE", path);
+  }
+}

package/src/commands/auth.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "vitest";
+import { _test } from "./auth.js";
+
+describe("Harness auth helper internals", () => {
+  test("extracts Claude setup-token output without exposing it", () => {
+    const raw = "Open browser...\nCLAUDE_CODE_OAUTH_TOKEN=oauth_token_abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJ\n";
+    expect(_test.extractClaudeToken(raw)).toBe("oauth_token_abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJ");
+    expect(_test.sanitizeSetupOutput(raw)).not.toContain("abcdefghijklmnopqrstuvwxyz0123456789");
+  });
+
+  test("builds connect form endpoint from URL or token", () => {
+    expect(_test.connectPostUrl("https://inst.example", "https://inst.example/connect/cl_abc123")).toBe(
+      "https://inst.example/connect/cl_abc123/connection",
+    );
+    expect(_test.connectPostUrl("https://inst.example/", "cl_deadbeef")).toBe(
+      "https://inst.example/connect/cl_deadbeef/connection",
+    );
+  });
+});

package/src/commands/auth.ts

@@ -0,0 +1,154 @@
+import { spawn } from "node:child_process";
+import { EXIT } from "../exit-codes.js";
+import { CliError, type Output } from "../output.js";
+
+export interface HarnessAuthOpts {
+  connect: string;
+  mode?: string;
+  scope?: string;
+  endUserId?: string;
+  tokenStdin?: boolean;
+  fromEnv?: string;
+  bin?: string;
+}
+
+export async function authClaudeCode(out: Output, instanceUrl: string, opts: HarnessAuthOpts): Promise<void> {
+  const mode = opts.mode ?? "subscription";
+  if (mode !== "subscription" && mode !== "apiKey") {
+    throw new CliError(EXIT.USAGE, "claude-code auth mode must be subscription or apiKey");
+  }
+  const token =
+    opts.tokenStdin === true || opts.fromEnv !== undefined
+      ? await tokenFromPipeOrEnv(opts)
+      : mode === "subscription"
+        ? await runClaudeSetupToken(out, opts.bin ?? "claude")
+        : await tokenFromPipeOrEnv({ ...opts, tokenStdin: true });
+  await postConnection({
+    instanceUrl,
+    connect: opts.connect,
+    connector: "claude-code",
+    mode,
+    scope: opts.scope ?? "workspace",
+    ...(opts.endUserId !== undefined ? { endUserId: opts.endUserId } : {}),
+    fields: mode === "subscription" ? { oauth_token: token } : { api_key: token },
+  });
+  out.data({ connector: "claude-code", mode, connected: true }, () => `claude-code ${mode} connected ✓`);
+}
+
+export async function authPi(out: Output, instanceUrl: string, opts: HarnessAuthOpts): Promise<void> {
+  const mode = opts.mode ?? "anthropicOAuth";
+  if (mode !== "anthropicOAuth" && mode !== "anthropicApiKey") {
+    throw new CliError(EXIT.USAGE, "pi auth mode must be anthropicOAuth or anthropicApiKey");
+  }
+  const token = await tokenFromPipeOrEnv(opts);
+  await postConnection({
+    instanceUrl,
+    connect: opts.connect,
+    connector: "pi",
+    mode,
+    scope: opts.scope ?? "workspace",
+    ...(opts.endUserId !== undefined ? { endUserId: opts.endUserId } : {}),
+    fields: mode === "anthropicOAuth" ? { oauth_token: token } : { api_key: token },
+  });
+  out.data({ connector: "pi", mode, connected: true }, () => `pi ${mode} connected ✓`);
+}
+
+async function tokenFromPipeOrEnv(opts: HarnessAuthOpts): Promise<string> {
+  if (opts.fromEnv !== undefined) {
+    const value = process.env[opts.fromEnv];
+    if (!value) throw new CliError(EXIT.USAGE, `env ${opts.fromEnv} is empty or missing`);
+    return value;
+  }
+  if (opts.tokenStdin !== true) {
+    throw new CliError(EXIT.USAGE, "pass --token-stdin or --from-env <NAME> so the token never appears in argv");
+  }
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  const value = Buffer.concat(chunks).toString("utf8").trim();
+  if (value.length === 0) throw new CliError(EXIT.USAGE, "empty token on stdin");
+  return value;
+}
+
+async function runClaudeSetupToken(out: Output, bin: string): Promise<string> {
+  out.log("starting `claude setup-token`; complete the browser login if prompted...");
+  const raw = await runInteractiveCapture(bin, ["setup-token"]);
+  const token = extractClaudeToken(raw);
+  if (!token) {
+    throw new CliError(
+      EXIT.ERROR,
+      "could not find a Claude Code OAuth token in `claude setup-token` output; rerun with `claude setup-token | tesser auth claude-code --connect <url> --token-stdin`",
+    );
+  }
+  return token;
+}
+
+function runInteractiveCapture(command: string, args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ["inherit", "pipe", "pipe"] });
+    let raw = "";
+    const onData = (buf: Buffer) => {
+      const text = buf.toString("utf8");
+      raw += text;
+      process.stderr.write(sanitizeSetupOutput(text));
+    };
+    child.stdout.on("data", onData);
+    child.stderr.on("data", onData);
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve(raw);
+      else reject(new CliError(EXIT.ERROR, `${command} ${args.join(" ")} exited ${code ?? 1}`));
+    });
+  });
+}
+
+function extractClaudeToken(raw: string): string | null {
+  const envMatch = raw.match(/CLAUDE_CODE_OAUTH_TOKEN\s*=\s*([^\s]+)/);
+  if (envMatch?.[1]) return envMatch[1].trim().replace(/^['"]|['"]$/g, "");
+  const candidates = raw
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => /^[A-Za-z0-9._-]{40,}$/.test(l) && !/^https?:/i.test(l));
+  return candidates.at(-1) ?? null;
+}
+
+function sanitizeSetupOutput(text: string): string {
+  return text.replace(/(CLAUDE_CODE_OAUTH_TOKEN\s*=\s*)[^\s]+/g, "$1[redacted]").replace(/\b[A-Za-z0-9._-]{64,}\b/g, "[redacted-token]");
+}
+
+async function postConnection(opts: {
+  instanceUrl: string;
+  connect: string;
+  connector: string;
+  mode: string;
+  scope: string;
+  endUserId?: string;
+  fields: Record<string, string>;
+}): Promise<void> {
+  const url = connectPostUrl(opts.instanceUrl, opts.connect);
+  const body = new URLSearchParams({ connector: opts.connector, mode: opts.mode, scope: opts.scope });
+  if (opts.endUserId !== undefined) body.set("end_user_id", opts.endUserId);
+  for (const [key, value] of Object.entries(opts.fields)) body.set(`field_${key}`, value);
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+    redirect: "manual",
+  });
+  if (res.status >= 300 && res.status < 400) return;
+  const text = await res.text().catch(() => "");
+  throw new CliError(EXIT.ERROR, `connect page rejected ${opts.connector} ${opts.mode}: ${res.status}${text ? ` ${text}` : ""}`);
+}
+
+function connectPostUrl(instanceUrl: string, connect: string): string {
+  if (/^https?:\/\//i.test(connect)) {
+    const u = new URL(connect);
+    const match = u.pathname.match(/\/connect\/([^/]+)/);
+    if (!match?.[1]) throw new CliError(EXIT.USAGE, "--connect must be a Tesser /connect/<token> URL or token");
+    return `${u.origin}/connect/${match[1]}/connection`;
+  }
+  const token = connect.replace(/^\/?connect\//, "");
+  if (!/^cl_[a-f0-9]+$/i.test(token)) throw new CliError(EXIT.USAGE, "--connect must be a Tesser /connect/<token> URL or token");
+  return `${instanceUrl.replace(/\/$/, "")}/connect/${token}/connection`;
+}
+
+export const _test = { extractClaudeToken, sanitizeSetupOutput, connectPostUrl };

package/src/commands/deploy.ts

@@ -0,0 +1,80 @@
+// `tesser deploy`: trigger a sync (git ref, or --local working tree), poll to a settled
+// state, surface the connect link on halt (exit 4), failures on red (exit 8).
+
+import type { ApiClient } from "../client.js";
+import { EXIT } from "../exit-codes.js";
+import { CliError, Output } from "../output.js";
+
+interface DeployState {
+  repo?: { status: string; report?: DeployReport | null; error?: string | null } | null;
+  live?: unknown[];
+}
+interface DeployReport {
+  sha?: string;
+  env?: string;
+  built?: string[];
+  unchanged?: string[];
+  failed?: Array<{ automation: string; stage: string; reason: string }>;
+  removed?: string[];
+  connectUrl?: string;
+  manual?: unknown[];
+}
+
+export async function deploy(
+  out: Output,
+  api: ApiClient,
+  project: string,
+  opts: { ref?: string | undefined; local?: string | undefined; timeoutMs?: number; wait?: boolean },
+): Promise<never> {
+  await api.post(`/projects/${project}/sync`, {
+    ...(opts.ref !== undefined ? { ref: opts.ref } : {}),
+    ...(opts.local !== undefined ? { localPath: opts.local } : {}),
+  });
+  out.log(`sync queued for ${project}${opts.local ? " (local tree)" : opts.ref ? ` @ ${opts.ref}` : ""}`);
+
+  if (opts.wait === false) {
+    out.data({ queued: true });
+    process.exit(EXIT.OK);
+  }
+
+  const deadline = Date.now() + (opts.timeoutMs ?? 10 * 60_000);
+  let last: DeployState = {};
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 750));
+    last = await api.get<DeployState>(`/projects/${project}/deploys/latest`);
+    const status = last.repo?.status;
+    if (status === "syncing" || status === "idle" || status === undefined) continue;
+
+    const report = (last.repo?.report ?? {}) as DeployReport;
+    if (status === "halted-credentials") {
+      out.data(
+        { status, connectUrl: report.connectUrl, report },
+        () =>
+          `deploy HALTED — credentials needed.\nOpen this link in a browser to connect:\n  ${report.connectUrl}\nThen rerun: tesser deploy${opts.local ? " --local" : ""}`,
+      );
+      process.exit(EXIT.HALTED_CREDENTIALS);
+    }
+    if (status === "failed") {
+      out.data({ status, report, error: last.repo?.error }, () =>
+        [
+          "deploy FAILED:",
+          ...(report.failed ?? []).map((f) => `  ${f.automation} [${f.stage}]: ${f.reason.split("\n")[0]}`),
+          ...(last.repo?.error ? [`  ${last.repo.error}`] : []),
+        ].join("\n"),
+      );
+      process.exit(EXIT.DEPLOY_FAILED);
+    }
+    if (status === "synced") {
+      out.data({ status, report, live: last.live }, () =>
+        [
+          `deploy OK @ ${report.sha?.slice(0, 8) ?? "?"} → ${report.env}`,
+          `  built:     ${report.built?.join(", ") || "(none)"}`,
+          `  unchanged: ${report.unchanged?.join(", ") || "(none)"}`,
+          ...(report.removed?.length ? [`  removed:   ${report.removed.join(", ")}`] : []),
+        ].join("\n"),
+      );
+      process.exit(EXIT.OK);
+    }
+  }
+  throw new CliError(EXIT.ERROR, "timed out waiting for the deploy to settle", { last: last as never });
+}

package/src/commands/dev.ts

@@ -0,0 +1,119 @@
+// `tesser dev`: a real local instance with zero setup — spawns the tesser-server BINARY
+// (process boundary; the Apache CLI never links AGPL code) on embedded PGlite, deploys
+// the local working tree through the REAL reconciler, and redeploys on change.
+
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { existsSync, watch } from "node:fs";
+import { join, dirname } from "node:path";
+import { ApiClient } from "../client.js";
+import { EXIT } from "../exit-codes.js";
+import { CliError, Output } from "../output.js";
+
+/** Returns [command, ...args]. Prefers the package's real .mjs entry (run with node);
+ *  falls back to the .bin shim executed directly (it is a shell script, not JS). */
+function findServerBin(start: string): string[] | null {
+  const envBin = process.env["TESSER_SERVER_BIN"];
+  if (envBin && existsSync(envBin)) {
+    return envBin.endsWith(".mjs") || envBin.endsWith(".js") ? [process.execPath, envBin] : [envBin];
+  }
+  let dir = start;
+  for (;;) {
+    const entry = join(dir, "node_modules", "@devosurf", "tesser-server", "bin", "tesser-server.mjs");
+    if (existsSync(entry)) return [process.execPath, entry];
+    const shim = join(dir, "node_modules", ".bin", "tesser-server");
+    if (existsSync(shim)) return [shim];
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export async function dev(
+  out: Output,
+  projectRoot: string,
+  project: string,
+  opts: { port?: number; watch?: boolean },
+): Promise<void> {
+  const bin = findServerBin(projectRoot);
+  if (!bin) {
+    throw new CliError(
+      EXIT.USAGE,
+      "tesser-server binary not found — install @devosurf/tesser-server (pnpm add -D @devosurf/tesser-server) or set TESSER_SERVER_BIN",
+    );
+  }
+  const port = opts.port ?? 8377;
+  const token = `tsk_${randomBytes(24).toString("hex")}`;
+  const url = `http://localhost:${port}`;
+
+  out.log(`starting local instance on ${url} (embedded postgres at .tesser/pglite)`);
+  const child = spawn(bin[0]!, bin.slice(1), {
+    env: {
+      ...process.env,
+      PORT: String(port),
+      TESSER_DATA_DIR: join(projectRoot, ".tesser"),
+      TESSER_BOOTSTRAP_TOKEN: token,
+      TESSER_BASE_URL: url,
+      DATABASE_URL: "",
+    },
+    stdio: ["ignore", "inherit", "inherit"],
+  });
+  const stop = () => {
+    child.kill("SIGTERM");
+  };
+  process.on("SIGINT", () => {
+    stop();
+    process.exit(0);
+  });
+  process.on("SIGTERM", stop);
+
+  const api = new ApiClient(url, token);
+  const deadline = Date.now() + 30_000;
+  for (;;) {
+    try {
+      await api.get("/health");
+      break;
+    } catch {
+      if (Date.now() > deadline) throw new CliError(EXIT.ERROR, "local instance did not come up");
+      await new Promise((r) => setTimeout(r, 300));
+    }
+  }
+  await api.post("/projects", { name: project });
+
+  const syncOnce = async () => {
+    await api.post(`/projects/${project}/sync`, { localPath: projectRoot });
+    // poll to settled, print, but DON'T exit (deploy() exits — inline a light loop)
+    for (let i = 0; i < 600; i++) {
+      await new Promise((r) => setTimeout(r, 500));
+      const state = await api.get<{ repo?: { status: string; report?: { connectUrl?: string; failed?: unknown[] } } }>(
+        `/projects/${project}/deploys/latest`,
+      );
+      const status = state.repo?.status;
+      if (status === "syncing") continue;
+      if (status === "halted-credentials") {
+        out.log(`HALTED — connect credentials in your browser:\n  ${state.repo?.report?.connectUrl}`);
+      } else if (status === "failed") {
+        out.log(`deploy failed: ${JSON.stringify(state.repo?.report?.failed ?? [])}`);
+      } else if (status === "synced") {
+        out.log(`deployed ✓ — webhooks at ${url}/hooks/${project}/<automation>`);
+      }
+      return;
+    }
+  };
+  await syncOnce();
+
+  if (opts.watch !== false) {
+    let timer: NodeJS.Timeout | null = null;
+    watch(join(projectRoot, "automations"), { recursive: true }, () => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        out.log("change detected — redeploying…");
+        void syncOnce();
+      }, 400);
+    });
+    out.log("watching automations/ for changes (ctrl-c to stop)");
+    await new Promise(() => {}); // run until interrupted
+  } else {
+    stop();
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,101 @@
+// `tesser init <name>`: scaffold a Project — the linked repo unit (ADR-0006). One
+// automation per directory; colocated tests; git is the source of truth.
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { EXIT } from "../exit-codes.js";
+import { CliError, Output } from "../output.js";
+
+const EXAMPLE_AUTOMATION = `import { defineAutomation, onWebhook } from "@devosurf/tesser-sdk";
+import { z } from "zod";
+
+export default defineAutomation({
+  id: "hello",
+  trigger: onWebhook({ input: z.object({ name: z.string().default("world") }) }),
+  output: z.object({ greeting: z.string() }),
+
+  run: async (input, ctx) => {
+    // Plain TypeScript. Durability ONLY from ctx.step() (every side effect goes inside one).
+    const greeting = await ctx.step("compose", async () => \`hello, \${input.name}!\`);
+    return { greeting };
+  },
+});
+`;
+
+const EXAMPLE_TEST = `import { createTest } from "@devosurf/tesser-testing";
+import automation from "./index";
+
+test("greets by name", async () => {
+  const t = createTest({ automation });
+  const { result } = await t.run({ input: { name: "tesser" } });
+  expect(result).toEqual({ greeting: "hello, tesser!" });
+});
+`;
+
+export function init(out: Output, name: string, opts: { dir?: string | undefined; instance?: string | undefined }): void {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) {
+    throw new CliError(EXIT.USAGE, "project name must be kebab-case");
+  }
+  const root = join(opts.dir ?? process.cwd(), name);
+  if (existsSync(join(root, "tesser.json"))) {
+    throw new CliError(EXIT.CONFLICT, `${root} is already a Tesser project`);
+  }
+  mkdirSync(join(root, "automations", "hello"), { recursive: true });
+
+  writeFileSync(
+    join(root, "tesser.json"),
+    JSON.stringify({ project: name, ...(opts.instance !== undefined ? { instance: opts.instance } : {}) }, null, 2) + "\n",
+  );
+  writeFileSync(
+    join(root, "package.json"),
+    JSON.stringify(
+      {
+        name,
+        private: true,
+        type: "module",
+        packageManager: "pnpm@9.12.0",
+        scripts: { test: "tesser test", deploy: "tesser deploy", dev: "tesser dev" },
+        dependencies: { "@devosurf/tesser-sdk": "latest", "@devosurf/tesser-connectors": "latest", zod: "^4" },
+        devDependencies: {
+          "@devosurf/tesser": "latest",
+          "@devosurf/tesser-server": "latest",
+          "@devosurf/tesser-testing": "latest",
+          vitest: "^4",
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+  writeFileSync(
+    join(root, "tsconfig.json"),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2022",
+          module: "ESNext",
+          moduleResolution: "Bundler",
+          strict: true,
+          skipLibCheck: true,
+          types: ["vitest/globals"],
+        },
+        include: ["automations"],
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+  writeFileSync(
+    join(root, "vitest.config.ts"),
+    `import { defineConfig } from "vitest/config";\nexport default defineConfig({ test: { globals: true, include: ["automations/**/*.test.ts"] } });\n`,
+  );
+  writeFileSync(join(root, ".gitignore"), "node_modules/\n.tesser/\n.env\n");
+  writeFileSync(join(root, "automations", "hello", "index.ts"), EXAMPLE_AUTOMATION);
+  writeFileSync(join(root, "automations", "hello", "index.test.ts"), EXAMPLE_TEST);
+
+  out.data(
+    { created: root, next: ["cd " + name, "git init && git add -A && git commit -m init", "npm install (or pnpm)", "tesser link", "tesser test"] },
+    () =>
+      `created ${root}\nnext:\n  cd ${name}\n  git init && git add -A && git commit -m init\n  pnpm install\n  tesser link    # register on your instance\n  tesser test    # green in milliseconds`,
+  );
+}

package/src/commands/replay.ts

@@ -0,0 +1,81 @@
+// `tesser replay <runId>` (ADR-0008): pull a real run's trigger + journal, freeze it as a
+// committed fixture, and write a regression test that re-feeds the exact input with
+// journal-derived mocks. The suite grows from real edge cases.
+
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ApiClient } from "../client.js";
+import { EXIT } from "../exit-codes.js";
+import { CliError, Output } from "../output.js";
+
+interface ReplayBundle {
+  replay: {
+    id: string;
+    automation_id: string;
+    status: string;
+    trigger: Record<string, unknown>;
+    input: unknown;
+    output: unknown;
+    error: unknown;
+    journal: Array<{ name: string; occurrence: number; status: string; result: unknown; error: unknown }>;
+  };
+}
+
+export async function replay(out: Output, api: ApiClient, projectRoot: string, runId: string): Promise<void> {
+  const { replay: run } = await api.get<ReplayBundle>(`/runs/${runId}/replay`);
+  const dir = join(projectRoot, "automations", run.automation_id);
+  if (!existsSync(dir)) {
+    throw new CliError(EXIT.NOT_FOUND, `automation directory not found locally: automations/${run.automation_id}`);
+  }
+  const shortId = run.id.slice(0, 8);
+  const fixtureDir = join(dir, "__replays__");
+  mkdirSync(fixtureDir, { recursive: true });
+  const fixturePath = join(fixtureDir, `${shortId}.replay.json`);
+  writeFileSync(
+    fixturePath,
+    JSON.stringify(
+      {
+        runId: run.id,
+        automation: run.automation_id,
+        recordedStatus: run.status,
+        trigger: run.trigger,
+        input: run.input,
+        output: run.output,
+        error: run.error,
+        steps: run.journal.filter((s) => !s.name.startsWith("$")),
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  const testPath = join(dir, `replay-${shortId}.test.ts`);
+  writeFileSync(
+    testPath,
+    `// Regression frozen from run ${run.id} (recorded status: ${run.status}).
+// Generated by \`tesser replay\` — adjust the final assertion once the bug is fixed.
+import { createTest } from "@devosurf/tesser-testing";
+import automation from "./index";
+import replay from "./__replays__/${shortId}.replay.json";
+
+test("replays run ${shortId} exactly", async () => {
+  const t = createTest({ automation });
+  // Recorded step results replay through the journal — completed steps return their
+  // captured values without executing, exactly like durable recovery (ADR-0002).
+  const journal = replay.steps
+    .filter((s) => s.status === "completed")
+    .map((s) => ({ name: s.name, occurrence: s.occurrence, result: s.result }));
+  const result = await t.run({ input: replay.input ?? undefined, journal });
+
+  // Recorded behaviour at capture time — keep as the regression contract:
+  expect(result.status).toBe(${JSON.stringify(run.status === "completed" ? "completed" : "failed")});
+${run.status === "completed" ? `  expect(result.result).toEqual(replay.output);` : `  // This run FAILED in production. After fixing, flip the expectation to "completed".`}
+});
+`,
+  );
+
+  out.data(
+    { fixture: fixturePath, test: testPath, recordedStatus: run.status },
+    () => `frozen run ${shortId} → ${testPath}\nfixture: ${fixturePath}\nrun \`tesser test\` to execute it`,
+  );
+}