@rigkit/engine 0.0.0-canary-20260518T014918-c5bc0c2

package/src/engine.test.ts

@@ -0,0 +1,1244 @@
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createDevMachineEngine, type InteractionPresentationRequest } from "./engine.ts";
+import { RIGKIT_STATE_SCHEMA_VERSION } from "./db/index.ts";
+import { createStateStore } from "./state.ts";
+import type {
+  BaseProviderPlugin,
+  ProviderRuntimeContext,
+  WorkflowProviderController,
+} from "./provider/types.ts";
+import type { DevMachineEvent, ExecResult, JsonValue } from "./types.ts";
+
+describe("DevMachineEngine workflow runtime", () => {
+  test("plans, applies graph nodes, reuses graph cache, and forks workspaces", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("test", {
+          providers: {
+            test: defineProvider("test", { token: "test-key" }),
+          },
+        });
+
+        const base = app.sequence("base").task("first", async ({ step, test }) => {
+          console.log("preparing base");
+          const vm = await test.createVm();
+          await vm.exec("touch /tmp/first", { name: "touch first" });
+          if (!(await vm.exists("/tmp/first"))) throw new Error("first was not created");
+          return { ctx: { first: true, vm: await vm.snapshotRef() } };
+        });
+
+        const left = app.sequence("left").task("second", async ({ step, test }) => {
+          if (!step.ctx.first) throw new Error("missing first context");
+          const vm = await test.fromSnapshot(step.ctx.vm);
+          await vm.exec("touch /tmp/second", { name: "touch second" });
+          return { ctx: { second: true, vm: await vm.snapshotRef() } };
+        });
+
+        const right = app.sequence("right").task("data", async ({ step }) => {
+          if (!step.ctx.first) throw new Error("missing first context");
+          return { ctx: { data: "right-ready" } };
+        });
+
+        export default app
+          .sequence("root")
+          .add(base)
+          .parallel({ left, right })
+          .task("join", async ({ step }) => {
+            if (!step.ctx.left.second) throw new Error("missing left context");
+            if (step.ctx.right.data !== "right-ready") throw new Error("missing right context");
+            return { ctx: { vm: step.ctx.left.vm, summary: step.ctx.right.data } };
+          })
+          .workspace({
+            create: async ({ providers, workflow, workspace, local }) => {
+              if (workflow.ctx.summary !== "right-ready") throw new Error("missing final context");
+              const vm = await providers.test.fromSnapshot(workflow.ctx.vm);
+              await vm.exec("touch /tmp/workspace-" + workspace.name, { name: "mark workspace" });
+              await local.open("created://" + workspace.name);
+              return {
+                summary: workflow.ctx.summary,
+                repoPath: "/workspace/repo",
+                vmId: vm.vmId,
+              };
+            },
+            remove: async ({ providers, workspace, workflow }) => {
+              if (workflow.ctx.summary !== "right-ready") throw new Error("missing final context on remove");
+              const vm = providers.test.fromId(workspace.ctx.vmId);
+              await vm.exec("touch /tmp/remove-" + workspace.name, { name: "mark workspace remove" });
+            },
+          })
+          .workspaceOperation("open", {
+            run: async ({ providers, workspace, workflow, local }) => {
+              if (workflow.ctx.summary !== "right-ready") throw new Error("missing final context on open");
+              if (workspace.ctx.summary !== "right-ready") throw new Error("missing workspace context");
+              const vm = providers.test.fromId(workspace.ctx.vmId);
+              await vm.exec("touch /tmp/open-" + workspace.name, { name: "mark workspace open" });
+              await local.open("open://" + workspace.name);
+            },
+          })
+          .operation("mark", {
+            input: (workflow) =>
+              workflow
+                .workspaceInput({ name: "workspace", position: 0 })
+                .extend({
+                  label: workflow.string({ defaultValue: "marked" }),
+            }),
+            run: async ({ input, providers, local }) => {
+              const vm = providers.test.fromId(input.workspace.ctx.vmId);
+              await vm.exec("touch /tmp/mark-" + input.workspace.name, { name: "mark via operation" });
+              await local.open("mark://" + input.workspace.name);
+              return {
+                workspace: input.workspace.name,
+                label: input.label,
+                repoPath: input.workspace.ctx.repoPath,
+                summary: input.workspace.ctx.summary,
+              };
+            },
+          });
+      `,
+    );
+
+    const opened: string[] = [];
+    const events: DevMachineEvent[] = [];
+    const provider = new FakeWorkflowProvider();
+    const engine = await createDevMachineEngine({
+      projectDir,
+      providerFactory: async () => provider,
+      local: {
+        open: async (target) => {
+          opened.push(target);
+        },
+      },
+    });
+    engine.onEvent((event) => events.push(event));
+
+    await engine.load();
+
+    const initial = await engine.plan();
+    expect(initial.workflow).toBe("test");
+    expect(initial.cachedNodeCount).toBe(0);
+    expect(initial.nodeCount).toBe(4);
+    expect(initial.nodes.map((node) => node.path)).toEqual([
+      "base.first",
+      "left.second",
+      "right.data",
+      "join",
+    ]);
+
+    const applied = await engine.apply();
+    expect(applied.context.vm).toEqual({ provider: "test", kind: "vmSnapshot", snapshotId: "snap-2" });
+    expect(events).toContainEqual({
+      type: "log.output",
+      nodePath: "base.first",
+      stream: "info",
+      data: "preparing base",
+    });
+    expect(provider.snapshots).toHaveLength(2);
+    expect(engine.listNodeRuns()).toHaveLength(4);
+
+    const cached = await engine.plan();
+    expect(cached.cachedNodeCount).toBe(4);
+    expect(cached.finalContext?.summary).toBe("right-ready");
+
+    const workspace = await engine.fork({ name: "work" });
+    expect(workspace.name).toBe("work");
+    expect(workspace.ctx).toMatchObject({
+      summary: "right-ready",
+      repoPath: "/workspace/repo",
+      vmId: "vm-3",
+    });
+    expect(engine.listWorkspaces()).toHaveLength(1);
+    expect(opened).toEqual(["created://work"]);
+    expect(provider.hasFile("vm-3", "/tmp/workspace-work")).toBe(true);
+
+    const openOperation = engine.listRuntimeWorkspaceOperations().find((operation) => operation.id === "open");
+    expect(openOperation?.id).toBe("open");
+    const marked = await engine.runOperation({ operation: "mark", input: { workspace: "work" } });
+    expect(marked).toEqual({ workspace: "work", label: "marked", repoPath: "/workspace/repo", summary: "right-ready" });
+    expect(opened).toEqual(["created://work", "mark://work"]);
+    expect(provider.hasFile("vm-3", "/tmp/mark-work")).toBe(true);
+
+    await engine.runRuntimeOperation({ operation: "work/open" });
+    expect(opened).toEqual(["created://work", "mark://work", "open://work"]);
+    expect(provider.hasFile("vm-3", "/tmp/open-work")).toBe(true);
+
+    await engine.runRuntimeOperation({ operation: "work/remove" });
+    expect(engine.listWorkspaces()).toHaveLength(0);
+    expect(provider.hasFile("vm-3", "/tmp/remove-work")).toBe(true);
+  });
+
+  test("creates workspaces from workspace definitions and exposes persisted workspace context", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineConfig, defineProvider, sequence } from "${import.meta.dir}/index.ts";
+
+        const test = defineProvider("test", { token: "test-key" });
+
+        const root = sequence("create-test")
+          .step("prepare", async ({ providers }) => {
+            const vm = await providers.test.createVm();
+            await vm.exec("touch /tmp/template", { name: "prepare template" });
+            return {
+              ctx: {
+                vm: await vm.snapshotRef(),
+                repoPath: "/workspace/repo",
+              },
+            };
+          })
+          .workspace({
+            create: async ({ workflow, workspace, providers }) => {
+              const vm = await providers.test.fromSnapshot(workflow.ctx.vm);
+              await vm.exec("touch /tmp/create-" + workspace.name, { name: "create workspace" });
+              return {
+                name: workspace.name,
+                vmId: vm.vmId,
+                sourceSnapshot: workflow.ctx.vm,
+                repoPath: workflow.ctx.repoPath,
+                ready: true,
+              };
+            },
+            remove: async () => {},
+          })
+          .operation("inspect", {
+            input: (workflow) => workflow.workspaceInput({ name: "workspace", position: 0 }),
+            run: async ({ input, local }) => {
+              await local.open("created://" + input.workspace.name);
+              return {
+                vmId: input.workspace.ctx.vmId,
+                repoPath: input.workspace.ctx.repoPath,
+                ready: input.workspace.ctx.ready,
+              };
+            },
+          })
+          .workspaceOperation("status", {
+            run: async ({ workspace }) => ({
+              workspace: workspace.name,
+              vmId: workspace.ctx.vmId,
+            }),
+          });
+
+        export default defineConfig({
+          providers: { test },
+          workflows: { root },
+        });
+      `,
+    );
+
+    const opened: string[] = [];
+    const provider = new FakeWorkflowProvider();
+    const engine = await createDevMachineEngine({
+      projectDir,
+      providerFactory: () => provider,
+      local: {
+        open: async (target) => {
+          opened.push(target);
+        },
+      },
+    });
+
+    await engine.load();
+    const projectInfo = engine.getProjectInfo();
+    expect(projectInfo.workflow?.createsWorkspace).toBe(true);
+    expect(projectInfo.workflows.map((workflow) => workflow.name)).toEqual(["create-test"]);
+    expect(engine.listOperations().map((operation) => operation.id)).toEqual(["inspect"]);
+
+    const workspace = await engine.fork({ name: "created" });
+    expect(workspace.name).toBe("created");
+    expect(workspace.ctx).toMatchObject({
+      name: "created",
+      vmId: "vm-2",
+      repoPath: "/workspace/repo",
+      ready: true,
+    });
+    expect(provider.hasFile("vm-2", "/tmp/create-created")).toBe(true);
+
+    const inspected = await engine.runOperation({ operation: "inspect", input: { workspace: "created" } });
+    expect(inspected).toEqual({
+      vmId: "vm-2",
+      repoPath: "/workspace/repo",
+      ready: true,
+    });
+    expect(opened).toEqual(["created://created"]);
+
+    const status = await engine.runRuntimeOperation({ operation: "created/status" });
+    expect(status).toEqual({ workspace: "created", vmId: "vm-2" });
+  });
+
+  test("rejects workspace names that are not shell-safe", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineConfig, sequence } from "${import.meta.dir}/index.ts";
+
+        const root = sequence("workspace-names")
+          .step("ready", async () => ({ ctx: { ready: true } }))
+          .workspace({
+            create: async ({ workspace }) => ({ name: workspace.name }),
+            remove: async () => {},
+          });
+
+        export default defineConfig({
+          providers: {},
+          workflows: { root },
+        });
+      `,
+    );
+
+    const engine = await createDevMachineEngine({ projectDir });
+    await engine.load();
+
+    await expect(engine.fork({ name: "" })).rejects.toThrow("create requires a workspace name");
+    for (const name of ["some workspace", "some/workspace", "-workspace"]) {
+      await expect(engine.fork({ name })).rejects.toThrow("Workspace name");
+    }
+    expect(engine.listWorkspaces()).toEqual([]);
+  });
+
+  test("loads multiple workflows from defineConfig", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineConfig, sequence } from "${import.meta.dir}/index.ts";
+
+        const api = sequence("api").step("ready", async () => ({ ctx: { api: true } }));
+        const web = sequence("web").step("ready", async () => ({ ctx: { web: true } }));
+
+        export default defineConfig({
+          providers: {},
+          workflows: { api, web },
+        });
+      `,
+    );
+
+    const engine = await createDevMachineEngine({
+      projectDir,
+      providerFactory: () => new FakeWorkflowProvider(),
+    });
+
+    await engine.load();
+
+    expect(engine.listWorkflowSummaries().map((workflow) => workflow.name)).toEqual(["api", "web"]);
+    expect(engine.getProjectInfo().workflow).toBeUndefined();
+    await expect(engine.plan()).rejects.toThrow("Multiple workflows are defined");
+    expect((await engine.plan({ workflow: "api" })).workflow).toBe("api");
+  });
+
+  test("creates state through an injectable state service factory", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    const statePath = join(projectDir, "custom-state.sqlite");
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineConfig, sequence } from "${import.meta.dir}/index.ts";
+
+        const root = sequence("factory-test").step("ready", async () => ({ ctx: { ready: true } }));
+
+        export default defineConfig({
+          providers: {},
+          workflows: { root },
+        });
+      `,
+    );
+
+    const configPath = join(projectDir, "rig.config.ts");
+    const calls: Array<{ projectDir: string; configPath?: string; statePath?: string }> = [];
+    const engine = await createDevMachineEngine({
+      projectDir,
+      statePath,
+      providerFactory: () => new FakeWorkflowProvider(),
+      stateFactory: (options) => {
+        calls.push({
+          projectDir: options.projectDir,
+          configPath: options.configPath,
+          statePath: options.statePath,
+        });
+        return createStateStore(options);
+      },
+    });
+
+    await engine.load();
+
+    expect(calls).toEqual([{ projectDir, configPath, statePath }]);
+    expect(engine.getProjectInfo().statePath).toBe(statePath);
+
+    const state = createStateStore({ projectDir, statePath: join(projectDir, "provided-state.sqlite") });
+    const engineWithState = await createDevMachineEngine({
+      projectDir,
+      providerFactory: () => new FakeWorkflowProvider(),
+      state,
+      stateFactory: () => {
+        throw new Error("stateFactory should not be called when state is provided");
+      },
+    });
+
+    await engineWithState.load();
+    expect(engineWithState.getProjectInfo().statePath).toBe(state.path);
+  });
+
+  test("resets stale state before applying the Drizzle push schema", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    const statePath = join(projectDir, ".rigkit", "state.sqlite");
+    mkdirSync(join(projectDir, ".rigkit"));
+    const legacy = new Database(statePath, { create: true });
+    legacy.run(`
+      CREATE TABLE workspaces (
+        id TEXT PRIMARY KEY NOT NULL,
+        name TEXT NOT NULL,
+        provider_id TEXT NOT NULL,
+        vm_id TEXT NOT NULL,
+        machine TEXT NOT NULL,
+        snapshot_id TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        metadata_json TEXT NOT NULL
+      )
+    `);
+    legacy
+      .query(`
+        INSERT INTO workspaces (
+          id, name, provider_id, vm_id, machine, snapshot_id, created_at, updated_at, metadata_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+      .run(
+        "workspace-1",
+        "demo",
+        "freestyle",
+        "vm-1",
+        "smoke",
+        "snap-1",
+        "2026-05-10T00:00:00.000Z",
+        "2026-05-10T00:00:00.000Z",
+        JSON.stringify({ ready: true }),
+      );
+    legacy.close();
+
+    const state = createStateStore({ projectDir, statePath });
+    const result = await state.syncSchema();
+    const workspaces = state.listWorkspaces();
+
+    expect(result.applied).toEqual([RIGKIT_STATE_SCHEMA_VERSION]);
+    expect(result.hasDataLoss).toBe(true);
+    expect(result.warnings.some((warning) => warning.startsWith("Reset Rigkit state database after Drizzle push failed"))).toBe(
+      true,
+    );
+    expect(workspaces).toEqual([]);
+
+    const now = new Date().toISOString();
+    state.saveWorkspace({
+      id: "workspace-2",
+      name: "demo",
+      workflow: "smoke",
+      workflowCtx: { ready: true },
+      createdAt: now,
+      updatedAt: now,
+      ctx: { ready: true },
+    });
+    expect(state.getWorkspace("demo")).toMatchObject({
+      name: "demo",
+      workflow: "smoke",
+      ctx: { ready: true },
+    });
+  });
+
+  test("invalidates task cache when handler source changes", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-handler-cache-"));
+    const statePath = join(projectDir, ".rigkit", "state.sqlite");
+    mkdirSync(join(projectDir, ".rigkit"));
+    const writeConfig = (configPath: string, value: string) =>
+      writeFileSync(
+        configPath,
+        `
+          import { workflow } from "${import.meta.dir}/index.ts";
+
+          const app = workflow("handler-cache", { providers: {} });
+
+          export default app.sequence("root").task("value", async () => {
+            return { ctx: { value: "${value}" } };
+          });
+        `,
+      );
+
+    const firstConfigPath = join(projectDir, "rig.one.config.ts");
+    const secondConfigPath = join(projectDir, "rig.two.config.ts");
+    writeConfig(firstConfigPath, "one");
+    writeConfig(secondConfigPath, "two");
+
+    const first = await createDevMachineEngine({
+      projectDir,
+      configPath: firstConfigPath,
+      statePath,
+    });
+    await first.load();
+    const applied = await first.apply();
+    expect(applied.context.value).toBe("one");
+
+    const cached = await first.plan();
+    expect(cached.cachedNodeCount).toBe(1);
+
+    const second = await createDevMachineEngine({
+      projectDir,
+      configPath: secondConfigPath,
+      statePath,
+    });
+    await second.load();
+    const changed = await second.plan();
+    expect(changed.cachedNodeCount).toBe(0);
+    expect(changed.nodes[0]?.status).toBe("pending");
+
+    const reapplied = await second.apply();
+    expect(reapplied.context.value).toBe("two");
+    expect(second.listNodeRuns()).toHaveLength(2);
+  });
+
+  test("stores globally scoped sequence runs in fragment state and busts downstream local cache", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-global-fragment-"));
+    const statePath = join(projectDir, ".rigkit", "state.sqlite");
+    const fragmentRoot = join(projectDir, "fragments");
+    mkdirSync(join(projectDir, ".rigkit"));
+
+    const writeConfig = (configPath: string, value: string) =>
+      writeFileSync(
+        configPath,
+        `
+          import { sequence } from "${import.meta.dir}/index.ts";
+
+          const deps = sequence("deps")
+            .configure({ value: "${value}" })
+            .task("prepare", async ({ config }) => ({ ctx: { value: String(config.value) } }))
+            .global();
+
+          export default sequence("site")
+            .add(deps)
+            .task("install", async ({ step }) => ({ ctx: { installed: step.ctx.value } }));
+        `,
+      );
+
+    const firstConfigPath = join(projectDir, "rig.one.config.ts");
+    const secondConfigPath = join(projectDir, "rig.two.config.ts");
+    writeConfig(firstConfigPath, "one");
+    writeConfig(secondConfigPath, "two");
+
+    const engineOptions = {
+      projectDir,
+      statePath,
+      globalFragmentStateLocator: (fragment: { hash: string }) => ({
+        statePath: join(fragmentRoot, fragment.hash, "state.sqlite"),
+      }),
+    };
+
+    const first = await createDevMachineEngine({ ...engineOptions, configPath: firstConfigPath });
+    await first.load();
+    await first.apply();
+    expect((await first.plan()).cachedNodeCount).toBe(2);
+    expect(first.listNodeRuns().map((run) => run.nodePath)).toEqual(["install"]);
+
+    const fragmentHashes = readdirSync(fragmentRoot);
+    expect(fragmentHashes).toHaveLength(1);
+    const fragmentDb = new Database(join(fragmentRoot, fragmentHashes[0]!, "state.sqlite"));
+    const fragmentRuns = fragmentDb
+      .query<{ node_path: string }, []>("select node_path from workflow_node_runs order by node_path")
+      .all();
+    fragmentDb.close();
+    expect(fragmentRuns.map((run) => run.node_path)).toEqual(["deps.prepare"]);
+
+    const cache = await first.listCache();
+    expect(cache.entries.map((entry) => entry.scope).sort()).toEqual(["global", "local"]);
+
+    const second = await createDevMachineEngine({ ...engineOptions, configPath: secondConfigPath });
+    await second.load();
+    const changed = await second.plan();
+    expect(changed.cachedNodeCount).toBe(0);
+
+    const reapplied = await second.apply();
+    expect(reapplied.context.installed).toBe("two");
+    expect(readdirSync(fragmentRoot)).toHaveLength(2);
+  });
+
+  test("allows a later local task to invalidate an earlier global fragment task", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-global-invalidates-"));
+    const statePath = join(projectDir, ".rigkit", "state.sqlite");
+    const fragmentRoot = join(projectDir, "fragments");
+    mkdirSync(join(projectDir, ".rigkit"));
+
+    const previous = {
+      installCount: process.env.RIGKIT_GLOBAL_INSTALL_COUNT,
+      authCount: process.env.RIGKIT_GLOBAL_AUTH_COUNT,
+      repoCount: process.env.RIGKIT_LOCAL_REPO_COUNT,
+      checkCount: process.env.RIGKIT_LOCAL_CHECK_COUNT,
+      forceReauth: process.env.RIGKIT_FORCE_GLOBAL_REAUTH,
+    };
+    process.env.RIGKIT_GLOBAL_INSTALL_COUNT = "0";
+    process.env.RIGKIT_GLOBAL_AUTH_COUNT = "0";
+    process.env.RIGKIT_LOCAL_REPO_COUNT = "0";
+    process.env.RIGKIT_LOCAL_CHECK_COUNT = "0";
+    process.env.RIGKIT_FORCE_GLOBAL_REAUTH = "0";
+
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { sequence } from "${import.meta.dir}/index.ts";
+
+        const base = sequence("base")
+          .task("install", async () => {
+            const count = Number(process.env.RIGKIT_GLOBAL_INSTALL_COUNT ?? "0") + 1;
+            process.env.RIGKIT_GLOBAL_INSTALL_COUNT = String(count);
+            return { ctx: { installed: "install-" + count } };
+          })
+          .task("auth", async ({ step }) => {
+            const count = Number(process.env.RIGKIT_GLOBAL_AUTH_COUNT ?? "0") + 1;
+            process.env.RIGKIT_GLOBAL_AUTH_COUNT = String(count);
+            return { ctx: { ...step.ctx, token: "token-" + count } };
+          })
+          .global();
+
+        const repo = sequence("repo")
+          .task("clone", async ({ step }) => {
+            const count = Number(process.env.RIGKIT_LOCAL_REPO_COUNT ?? "0") + 1;
+            process.env.RIGKIT_LOCAL_REPO_COUNT = String(count);
+            return { ctx: { ...step.ctx, repoToken: step.ctx.token, repoCount: count } };
+          });
+
+        export default sequence("root")
+          .add(base)
+          .add(repo)
+          .task("check-auth", { cacheTTL: 0 }, async ({ step }) => {
+            const count = Number(process.env.RIGKIT_LOCAL_CHECK_COUNT ?? "0") + 1;
+            process.env.RIGKIT_LOCAL_CHECK_COUNT = String(count);
+            if (process.env.RIGKIT_FORCE_GLOBAL_REAUTH === "1") {
+              process.env.RIGKIT_FORCE_GLOBAL_REAUTH = "0";
+              return step.invalidate("auth");
+            }
+            return { ctx: step.ctx };
+          });
+      `,
+    );
+
+    try {
+      const engine = await createDevMachineEngine({
+        projectDir,
+        statePath,
+        globalFragmentStateLocator: (fragment: { hash: string }) => ({
+          statePath: join(fragmentRoot, fragment.hash, "state.sqlite"),
+        }),
+      });
+      await engine.load();
+
+      const first = await engine.apply();
+      expect(first.context.token).toBe("token-1");
+      expect(first.context.repoToken).toBe("token-1");
+      expect(process.env.RIGKIT_GLOBAL_INSTALL_COUNT).toBe("1");
+      expect(process.env.RIGKIT_GLOBAL_AUTH_COUNT).toBe("1");
+      expect(process.env.RIGKIT_LOCAL_REPO_COUNT).toBe("1");
+      expect(process.env.RIGKIT_LOCAL_CHECK_COUNT).toBe("1");
+
+      process.env.RIGKIT_FORCE_GLOBAL_REAUTH = "1";
+      const second = await engine.apply();
+      expect(second.context.token).toBe("token-2");
+      expect(second.context.repoToken).toBe("token-2");
+      expect(process.env.RIGKIT_GLOBAL_INSTALL_COUNT).toBe("1");
+      expect(process.env.RIGKIT_GLOBAL_AUTH_COUNT).toBe("2");
+      expect(process.env.RIGKIT_LOCAL_REPO_COUNT).toBe("2");
+      expect(process.env.RIGKIT_LOCAL_CHECK_COUNT).toBe("3");
+      expect(readdirSync(fragmentRoot)).toHaveLength(1);
+    } finally {
+      restoreEnv("RIGKIT_GLOBAL_INSTALL_COUNT", previous.installCount);
+      restoreEnv("RIGKIT_GLOBAL_AUTH_COUNT", previous.authCount);
+      restoreEnv("RIGKIT_LOCAL_REPO_COUNT", previous.repoCount);
+      restoreEnv("RIGKIT_LOCAL_CHECK_COUNT", previous.checkCount);
+      restoreEnv("RIGKIT_FORCE_GLOBAL_REAUTH", previous.forceReauth);
+    }
+  });
+
+  test("stores provider JSON state in Rigkit-owned provider storage", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    const plugin: BaseProviderPlugin = {
+      providerId: "test",
+      createProvider({ storage }) {
+        storage.set("ready", { value: "provider" });
+        return new FakeWorkflowProvider();
+      },
+    };
+
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("provider-storage", {
+          providers: {
+            test: defineProvider("test", {}),
+          },
+        });
+
+        export default app.sequence("root").task("ready", async () => ({ ctx: { ready: true } }));
+      `,
+    );
+
+    const engine = await createDevMachineEngine({
+      projectDir,
+      providers: [plugin],
+    });
+
+    await engine.load();
+    await engine.plan();
+
+    const statePath = engine.getProjectInfo().statePath;
+    const main = new Database(statePath);
+    const mainTables = main
+      .query<{ name: string }, []>("select name from sqlite_master where type = 'table' order by name")
+      .all()
+      .map((row) => row.name);
+
+    expect(mainTables).toContain("workspaces");
+    expect(mainTables).toContain("provider_state");
+    expect(mainTables).toContain("runtime_metadata");
+    expect(mainTables).not.toContain("provider_local_state");
+
+    const row = main
+      .query<{ value_json: string }, []>(
+        "select value_json from provider_state where provider_id = 'test' and key = 'ready'",
+      )
+      .get();
+    const metadataRows = main
+      .query<{ key: string; value_json: string }, []>(
+        "select key, value_json from runtime_metadata order by key",
+      )
+      .all();
+    main.close();
+
+    expect(row ? JSON.parse(row.value_json).value : undefined).toBe("provider");
+    const metadata = Object.fromEntries(metadataRows.map((item) => [item.key, JSON.parse(item.value_json)]));
+    expect(metadata["state.schemaVersion"]).toBe(RIGKIT_STATE_SCHEMA_VERSION);
+    expect(metadata["project.dir"]).toBe(projectDir);
+    expect(metadata["config.path"]).toBe(join(projectDir, "rig.config.ts"));
+  });
+
+  test("stores provider host JSON state outside project state", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    const hostStorageDir = join(projectDir, ".host-storage");
+    const opened: string[] = [];
+    const plugin: BaseProviderPlugin = {
+      providerId: "test",
+      async createProvider({ storage, hostStorage, local }) {
+        storage.set("project", { value: "state" });
+        hostStorage.set("token", { value: "secret" });
+        await local.open("rigkit://provider-auth");
+        return new FakeWorkflowProvider();
+      },
+    };
+
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("provider-host-storage", {
+          providers: {
+            test: defineProvider("test", {}),
+          },
+        });
+
+        export default app.sequence("root").task("ready", async () => ({ ctx: { ready: true } }));
+      `,
+    );
+
+    const engine = await createDevMachineEngine({
+      projectDir,
+      hostStorageDir,
+      providers: [plugin],
+      local: {
+        open: async (target) => {
+          opened.push(target);
+        },
+      },
+    });
+
+    await engine.load();
+    await engine.plan();
+
+    expect(opened).toEqual(["rigkit://provider-auth"]);
+
+    const files = readdirSync(hostStorageDir);
+    expect(files).toHaveLength(1);
+    const hostState = JSON.parse(readFileSync(join(hostStorageDir, files[0]!), "utf8"));
+    expect(hostState.records.token.value.value).toBe("secret");
+
+    const main = new Database(engine.getProjectInfo().statePath);
+    const projectRow = main
+      .query<{ value_json: string }, []>(
+        "select value_json from provider_state where provider_id = 'test' and key = 'project'",
+      )
+      .get();
+    const leakedHostRow = main
+      .query<{ value_json: string }, []>(
+        "select value_json from provider_state where provider_id = 'test' and key = 'token'",
+      )
+      .get();
+    main.close();
+
+    expect(projectRow ? JSON.parse(projectRow.value_json).value : undefined).toBe("state");
+    expect(leakedHostRow).toBeNull();
+  });
+
+  test("rejects task outputs that are not JSON serializable", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("test", {
+          providers: {
+            test: defineProvider("test", { token: "test-key" }),
+          },
+        });
+
+        export default app.sequence("bad").task("returns-function", async () => {
+          return { ctx: { fn: () => "nope" } };
+        });
+      `,
+    );
+
+    const engine = await createDevMachineEngine({
+      projectDir,
+      providerFactory: () => new FakeWorkflowProvider(),
+    });
+
+    await engine.load();
+    await expect(engine.apply()).rejects.toThrow("must be JSON-serializable");
+  });
+
+  test("routes terminal interactions through provider runtimes", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("test", {
+          providers: {
+            test: defineProvider("test", { token: "test-key" }),
+          },
+        });
+
+        export default app.sequence("auth").task("login", async ({ test }) => {
+          const result = await test.openTerminal("GitHub auth", "gh auth login");
+          return { ctx: { finished: result.finished } };
+        });
+      `,
+    );
+
+    const interactions: InteractionPresentationRequest[] = [];
+    const engine = await createDevMachineEngine({
+      projectDir,
+      providerFactory: () => new FakeWorkflowProvider(),
+      interaction: {
+        present: async (request) => {
+          interactions.push(request);
+        },
+      },
+    });
+
+    await engine.load();
+    const applied = await engine.apply();
+
+    expect(interactions).toEqual([
+      {
+        nodePath: "login",
+        id: "fake-terminal",
+        title: "GitHub auth",
+        url: "http://127.0.0.1/fake-terminal",
+        instructions: undefined,
+      },
+    ]);
+    expect(applied.context.finished).toBe(true);
+  });
+
+  test("waits for provider-owned interaction completion before resuming tasks", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("test", {
+          providers: {
+            test: defineProvider("test", { token: "test-key" }),
+          },
+        });
+
+        export default app.sequence("auth").task("login", async ({ test }) => {
+          const result = await test.openTerminal("GitHub auth", "gh auth login");
+          return { ctx: { finished: result.finished } };
+        });
+      `,
+    );
+
+    let complete!: (result: { finished: true }) => void;
+    const completed = new Promise<{ finished: true }>((resolve) => {
+      complete = resolve;
+    });
+    const provider = new FakeWorkflowProvider({
+      terminalCompleted: completed,
+    });
+    const engine = await createDevMachineEngine({
+      projectDir,
+      providerFactory: () => provider,
+      interaction: {
+        present: async () => {},
+      },
+    });
+
+    await engine.load();
+    let applied: Awaited<ReturnType<typeof engine.apply>> | undefined;
+    const applying = engine.apply().then((result) => {
+      applied = result;
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    expect(applied).toBeUndefined();
+    expect(provider.terminalStopped).toBe(0);
+
+    complete({ finished: true });
+    await applying;
+
+    expect(applied?.context.finished).toBe(true);
+    expect(provider.terminalStopped).toBe(1);
+  });
+
+  test("provider config contributes to the workflow cache fingerprint", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    const previousToken = process.env.RIGKIT_TEST_PROVIDER_TOKEN;
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("test", {
+          providers: {
+            test: defineProvider("test", { token: () => process.env.RIGKIT_TEST_PROVIDER_TOKEN }),
+          },
+        });
+
+        export default app.sequence("setup").task("touch", async ({ test }) => {
+          const vm = await test.createVm();
+          await vm.exec("touch /tmp/setup", { name: "touch setup" });
+          return { ctx: { vm: await vm.snapshotRef() } };
+        });
+      `,
+    );
+
+    try {
+      const provider = new FakeWorkflowProvider();
+      process.env.RIGKIT_TEST_PROVIDER_TOKEN = "one";
+      const first = await createDevMachineEngine({
+        projectDir,
+        providerFactory: () => provider,
+      });
+      await first.load();
+      await first.apply();
+      expect((await first.plan()).cachedNodeCount).toBe(1);
+
+      process.env.RIGKIT_TEST_PROVIDER_TOKEN = "two";
+      const second = await createDevMachineEngine({
+        projectDir,
+        providerFactory: () => provider,
+      });
+      await second.load();
+      expect((await second.plan()).cachedNodeCount).toBe(0);
+    } finally {
+      if (previousToken === undefined) {
+        delete process.env.RIGKIT_TEST_PROVIDER_TOKEN;
+      } else {
+        process.env.RIGKIT_TEST_PROVIDER_TOKEN = previousToken;
+      }
+    }
+  });
+
+  test("treats cached output schema failures as cache misses", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-"));
+    const previousMode = process.env.RIGKIT_SCHEMA_MODE;
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { defineProvider, workflow } from "${import.meta.dir}/index.ts";
+
+        const app = workflow("test", {
+          providers: {
+            test: defineProvider("test", { token: "test-key" }),
+          },
+        });
+
+        const schema = {
+          parse(value) {
+            if (!value || typeof value !== "object") throw new Error("not an object");
+            if (process.env.RIGKIT_SCHEMA_MODE === "next" && value.next !== true) {
+              throw new Error("missing next");
+            }
+            return value;
+          },
+        };
+
+        export default app.sequence("schema").task("value", { output: schema }, async () => {
+          return process.env.RIGKIT_SCHEMA_MODE === "next"
+            ? { ctx: { value: "ok", next: true } }
+            : { ctx: { value: "ok" } };
+        });
+      `,
+    );
+
+    try {
+      process.env.RIGKIT_SCHEMA_MODE = "old";
+      const first = await createDevMachineEngine({
+        projectDir,
+        providerFactory: () => new FakeWorkflowProvider(),
+      });
+      await first.load();
+      await first.apply();
+      expect((await first.plan()).cachedNodeCount).toBe(1);
+
+      process.env.RIGKIT_SCHEMA_MODE = "next";
+      const second = await createDevMachineEngine({
+        projectDir,
+        providerFactory: () => new FakeWorkflowProvider(),
+      });
+      await second.load();
+      const plan = await second.plan();
+      expect(plan.cachedNodeCount).toBe(0);
+      expect(plan.nodes[0]?.status).toBe("pending");
+    } finally {
+      if (previousMode === undefined) {
+        delete process.env.RIGKIT_SCHEMA_MODE;
+      } else {
+        process.env.RIGKIT_SCHEMA_MODE = previousMode;
+      }
+    }
+  });
+
+  test("expires task cache when cacheTTL has elapsed", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-cache-ttl-"));
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { sequence } from "${import.meta.dir}/index.ts";
+
+        export default sequence("ttl").task("daily-check", { cacheTTL: "1d" }, async () => {
+          return { ctx: { checked: true } };
+        });
+      `,
+    );
+
+    const engine = await createDevMachineEngine({ projectDir });
+    await engine.load();
+    await engine.apply();
+    expect((await engine.plan()).cachedNodeCount).toBe(1);
+
+    const db = new Database(engine.getProjectInfo().statePath);
+    db.run("update workflow_node_runs set created_at = ?", [
+      new Date(Date.now() - 2 * 24 * 60 * 60 * 1000).toISOString(),
+    ]);
+    db.close();
+
+    const expired = await engine.plan();
+    expect(expired.cachedNodeCount).toBe(0);
+    expect(expired.nodes[0]?.status).toBe("pending");
+  });
+
+  test("step.invalidate invalidates a previous task and replays from that point", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-invalidate-"));
+    const previous = {
+      authCount: process.env.RIGKIT_AUTH_COUNT,
+      checkCount: process.env.RIGKIT_CHECK_COUNT,
+      forceReauth: process.env.RIGKIT_FORCE_REAUTH,
+    };
+    process.env.RIGKIT_AUTH_COUNT = "0";
+    process.env.RIGKIT_CHECK_COUNT = "0";
+    process.env.RIGKIT_FORCE_REAUTH = "0";
+
+    writeFileSync(
+      join(projectDir, "rig.config.ts"),
+      `
+        import { sequence } from "${import.meta.dir}/index.ts";
+
+        export default sequence("reauth")
+          .task("prepare", async () => ({ ctx: { prepared: true } }))
+          .task("github-auth", async () => {
+            const count = Number(process.env.RIGKIT_AUTH_COUNT ?? "0") + 1;
+            process.env.RIGKIT_AUTH_COUNT = String(count);
+            return { ctx: { token: "token-" + count } };
+          })
+          .task("check-auth", { cacheTTL: 0 }, async ({ step }) => {
+            const count = Number(process.env.RIGKIT_CHECK_COUNT ?? "0") + 1;
+            process.env.RIGKIT_CHECK_COUNT = String(count);
+            if (process.env.RIGKIT_FORCE_REAUTH === "1") {
+              process.env.RIGKIT_FORCE_REAUTH = "0";
+              return step.invalidate("github-auth");
+            }
+            return { ctx: step.ctx };
+          });
+      `,
+    );
+
+    try {
+      const engine = await createDevMachineEngine({ projectDir });
+      await engine.load();
+
+      const first = await engine.apply();
+      expect(first.context.token).toBe("token-1");
+      expect(process.env.RIGKIT_AUTH_COUNT).toBe("1");
+      expect(process.env.RIGKIT_CHECK_COUNT).toBe("1");
+
+      process.env.RIGKIT_FORCE_REAUTH = "1";
+      const second = await engine.apply();
+      expect(second.context.token).toBe("token-2");
+      expect(process.env.RIGKIT_AUTH_COUNT).toBe("2");
+      expect(process.env.RIGKIT_CHECK_COUNT).toBe("3");
+
+      const validRuns = engine.listNodeRuns().filter((run) => !run.invalidated);
+      expect(validRuns.map((run) => run.nodePath).sort()).toEqual(["check-auth", "github-auth", "prepare"]);
+    } finally {
+      restoreEnv("RIGKIT_AUTH_COUNT", previous.authCount);
+      restoreEnv("RIGKIT_CHECK_COUNT", previous.checkCount);
+      restoreEnv("RIGKIT_FORCE_REAUTH", previous.forceReauth);
+    }
+  });
+});
+
+type FakeSnapshotRef = {
+  provider: "test";
+  kind: "vmSnapshot";
+  snapshotId: string;
+};
+
+type FakeVm = {
+  vmId: string;
+  exec(command: string, options?: { name?: string }): Promise<ExecResult>;
+  probe(command: string, options?: { name?: string }): Promise<ExecResult>;
+  exists(path: string): Promise<boolean>;
+  snapshotRef(): Promise<FakeSnapshotRef>;
+};
+
+type FakeRuntime = {
+  createVm(): Promise<FakeVm>;
+  fromSnapshot(ref: FakeSnapshotRef): Promise<FakeVm>;
+  fromId(vmId: string): FakeVm;
+  openTerminal(label: string, command: string): Promise<{ finished: true }>;
+};
+
+class FakeWorkflowProvider implements WorkflowProviderController<FakeRuntime> {
+  readonly providerId = "test";
+  snapshots: FakeSnapshotRef[] = [];
+  private nextVm = 1;
+  private files = new Map<string, Set<string>>();
+  terminalStopped = 0;
+
+  constructor(
+    private readonly options: {
+      terminalCompleted?: Promise<{ finished: true }>;
+    } = {},
+  ) {}
+
+  runtime(context: ProviderRuntimeContext): FakeRuntime {
+    return {
+      createVm: async () => this.createVm(context),
+      fromSnapshot: async () => this.createVm(context),
+      fromId: (vmId) => this.vmRuntime({ vmId }, context),
+      openTerminal: async (label, command) => {
+        const completed = this.options.terminalCompleted ?? Promise.resolve({ finished: true as const });
+        return await context.interaction.present({
+          id: "fake-terminal",
+          title: label,
+          url: "http://127.0.0.1/fake-terminal",
+          completed,
+          stop: () => {
+            this.terminalStopped += 1;
+          },
+        });
+      },
+    };
+  }
+
+  validateArtifact(ref: JsonValue): boolean {
+    return isFakeSnapshotRef(ref);
+  }
+
+  hasFile(vmId: string, path: string): boolean {
+    return this.files.get(vmId)?.has(path) ?? false;
+  }
+
+  private async createVm(context: ProviderRuntimeContext): Promise<FakeVm> {
+    const vm = { vmId: `vm-${this.nextVm++}` };
+    this.files.set(vm.vmId, new Set());
+    context.emit({ type: "vm.created", providerId: "test", vmId: vm.vmId });
+    return this.vmRuntime(vm, context);
+  }
+
+  private vmRuntime(vm: { vmId: string }, _context: ProviderRuntimeContext): FakeVm {
+    return {
+      vmId: vm.vmId,
+      exec: async (command) => this.exec(vm.vmId, command, true),
+      probe: async (command) => this.exec(vm.vmId, command, false),
+      exists: async (path) => this.hasFile(vm.vmId, path),
+      snapshotRef: async () => this.createSnapshot(vm),
+    };
+  }
+
+  private exec(vmId: string, command: string, throwOnFailure: boolean): ExecResult {
+    const files = this.files.get(vmId)!;
+    const touch = /^touch (.+)$/.exec(command);
+    if (touch) files.add(touch[1]!);
+
+    const exists = /^test -e (.+)$/.exec(command);
+    if (exists) {
+      const path = exists[1]!.replace(/^'|'$/g, "");
+      return result(files.has(path));
+    }
+
+    const output = result(true);
+    if (throwOnFailure && !output.ok) throw new Error("command failed");
+    return output;
+  }
+
+  private createSnapshot(vm: { vmId: string }): FakeSnapshotRef {
+    const snapshot = {
+      provider: "test" as const,
+      kind: "vmSnapshot" as const,
+      snapshotId: `snap-${this.snapshots.length + 1}`,
+    };
+    this.snapshots.push(snapshot);
+    return snapshot;
+  }
+}
+
+function result(ok: boolean): ExecResult {
+  return { stdout: "", stderr: "", exitCode: ok ? 0 : 1, ok };
+}
+
+function restoreEnv(name: string, value: string | undefined): void {
+  if (value === undefined) {
+    delete process.env[name];
+  } else {
+    process.env[name] = value;
+  }
+}
+
+function isFakeSnapshotRef(value: unknown): value is FakeSnapshotRef {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      (value as FakeSnapshotRef).provider === "test" &&
+      (value as FakeSnapshotRef).kind === "vmSnapshot" &&
+      typeof (value as FakeSnapshotRef).snapshotId === "string",
+  );
+}