@rigkit/engine 0.2.2 → 0.2.4

package/src/engine.ts

@@ -3,16 +3,20 @@ import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { isRigkitConfig, isProviderDefinition, isWorkflowNode } from "./authoring.ts";
 import { loadDotEnv } from "./env-file.ts";
-import { hash, stableJson } from "./hash.ts";
+import { hash } from "./hash.ts";
+import {
+  createFileProviderHostStorage,
+  defaultProviderHostStorageDir,
+  type ProviderHostStorageFactory,
+} from "./host-storage.ts";
+import { RESERVED_WORKFLOW_OPERATION_IDS, STEP_INVALIDATION_KIND } from "./types.ts";
 import type {
   BaseProviderPlugin,
   InteractionPresenter,
   InteractionPresentationRequest,
   ProviderFactory,
   ProviderRuntimeContext,
-  SshConnection,
   WorkflowProviderController,
-  WorkflowWorkspaceProvider,
 } from "./provider/types.ts";
 import {
   createStateStore,
@@ -30,20 +34,21 @@ import type {
   LocalWorkspaceRuntime,
   OutputSchema,
   ProviderRuntimeMap,
-  ProviderWorkspaceContext,
   WorkflowInputFieldDefinition,
   WorkflowDefinition,
   WorkflowEvent,
+  WorkflowLogStream,
   WorkflowNodeDefinition,
   WorkflowOperationDefinition,
-  WorkflowHostCapabilityRequirement,
-  WorkflowHostMethodRequirement,
   WorkflowPlan,
   WorkflowPlanNode,
   WorkflowProviderMap,
+  WorkflowStepInvalidation,
+  WorkflowTaskCacheTTL,
   WorkflowTaskNode,
   WorkspaceRecord,
   WorkspaceRuntimeRecord,
+  WorkflowWorkspaceOperationDefinition,
 } from "./types.ts";
 
 export type CreateDevMachineEngineOptions = {
@@ -54,6 +59,8 @@ export type CreateDevMachineEngineOptions = {
   providers?: BaseProviderPlugin[];
   providerFactory?: ProviderFactory;
   stateFactory?: StateServiceFactory;
+  hostStorageDir?: string;
+  hostStorageFactory?: ProviderHostStorageFactory;
   interaction?: {
     present?: InteractionPresenter;
   };
@@ -119,8 +126,6 @@ export type EngineOperationSummary = {
   title?: string;
   description?: string;
   createsWorkspace?: boolean;
-  requiredHostMethods?: readonly WorkflowHostMethodRequirement[];
-  requiredHostCapabilities?: readonly WorkflowHostCapabilityRequirement[];
   inputFields: readonly WorkflowInputFieldDefinition[];
   cli?: EngineOperationCli;
 };
@@ -152,10 +157,16 @@ type EvaluationMode = "plan" | "apply";
 type EvaluationState = {
   context: Record<string, JsonValue>;
   upstreamRunIds: string[];
+  previousTasks: EvaluationPreviousTask[];
   known: boolean;
   blockedReason?: string;
 };
 
+type EvaluationPreviousTask = {
+  name: string;
+  path: string;
+};
+
 type EvaluationResult = EvaluationState & {
   planNodes: WorkflowPlanNode[];
 };
@@ -179,6 +190,35 @@ type RuntimeOperationEntry = {
   readonly run: (input: { workflow?: string; input?: unknown }) => Promise<unknown>;
 };
 
+type RuntimeWorkspaceOperationEntry = {
+  readonly summary: EngineOperationSummary;
+  readonly run: (input: { workspace: string; workflow?: string; input?: unknown }) => Promise<unknown>;
+};
+
+class StepInvalidationRestart extends Error {
+  readonly workflow: string;
+  readonly target: string;
+  readonly targetNodePath: string;
+  readonly currentNodePath: string;
+  readonly invalidatedRunIds: string[];
+
+  constructor(input: {
+    workflow: string;
+    target: string;
+    targetNodePath: string;
+    currentNodePath: string;
+    invalidatedRunIds: string[];
+  }) {
+    super(`Task ${input.currentNodePath} invalidated ${input.targetNodePath}`);
+    this.name = "StepInvalidationRestart";
+    this.workflow = input.workflow;
+    this.target = input.target;
+    this.targetNodePath = input.targetNodePath;
+    this.currentNodePath = input.currentNodePath;
+    this.invalidatedRunIds = input.invalidatedRunIds;
+  }
+}
+
 let configImportCounter = 0;
 
 export class DevMachineEngine {
@@ -189,6 +229,9 @@ export class DevMachineEngine {
   private providers: BaseProviderPlugin[];
   private readonly providerFactory: ProviderFactory;
   private readonly stateFactory: StateServiceFactory;
+  private readonly hostStorageDir: string;
+  private readonly hostStorageFactory: ProviderHostStorageFactory;
+  private readonly providerHostStorage = new Map<string, ReturnType<ProviderHostStorageFactory>>();
   private readonly interactionPresenter: InteractionPresenter;
   private readonly local: LocalWorkspaceRuntime;
   private readonly handlers = new Set<EventHandler>();
@@ -204,6 +247,8 @@ export class DevMachineEngine {
     this.providers = options.providers ?? [];
     this.providerFactory = options.providerFactory ?? ((input) => this.createProviderFromPlugin(input));
     this.stateFactory = options.stateFactory ?? createStateStore;
+    this.hostStorageDir = options.hostStorageDir ? resolve(options.hostStorageDir) : defaultProviderHostStorageDir();
+    this.hostStorageFactory = options.hostStorageFactory ?? createFileProviderHostStorage;
     this.interactionPresenter = options.interaction?.present ?? defaultInteractionPresenter;
     this.local = {
       open: options.local?.open ?? openLocalTarget,
@@ -306,6 +351,10 @@ export class DevMachineEngine {
     return this.listRuntimeOperationEntries().map((entry) => entry.summary);
   }
 
+  listRuntimeWorkspaceOperations(): EngineOperationSummary[] {
+    return this.listRuntimeWorkspaceOperationEntries().map((entry) => entry.summary);
+  }
+
   private listRuntimeOperationEntries(): RuntimeOperationEntry[] {
     const configOperations = this.listConfigOperationEntries();
     const configOperationIds = new Set(configOperations.map((entry) => entry.summary.id));
@@ -319,6 +368,16 @@ export class DevMachineEngine {
     ];
   }
 
+  private listRuntimeWorkspaceOperationEntries(): RuntimeWorkspaceOperationEntry[] {
+    const configOperations = this.listConfigWorkspaceOperationEntries();
+    const configOperationIds = new Set(configOperations.map((entry) => entry.summary.id));
+    const coreOperations = this.listCoreWorkspaceOperationEntries();
+    return [
+      ...coreOperations.filter((entry) => !configOperationIds.has(entry.summary.id)),
+      ...configOperations,
+    ];
+  }
+
   private listConfigOperationEntries(): RuntimeOperationEntry[] {
     return this.listConfigOperationSummaries().map((summary) => ({
       summary,
@@ -341,18 +400,65 @@ export class DevMachineEngine {
           source: "config" as const,
           title: operation.title,
           description: operation.description,
-          createsWorkspace: operation.createsWorkspace,
-          requiredHostMethods: operation.requiredHostMethods,
-          requiredHostCapabilities: operation.requiredHostCapabilities,
           inputFields: operation.input?.fields ?? [],
         };
       }),
     );
   }
 
+  private listConfigWorkspaceOperationEntries(): RuntimeWorkspaceOperationEntry[] {
+    return this.listWorkflows().flatMap((workflow) =>
+      workflow.workspaceOperations.map((operation) => ({
+        summary: this.workspaceOperationSummary(workflow, operation),
+        run: async (input) => {
+          const workspace = this.getStateService().getWorkspace(input.workspace);
+          if (!workspace) throw new Error(`Unknown workspace ${input.workspace}`);
+          if (workspace.workflow !== workflow.name) {
+            throw new EngineOperationValidationError({
+              operation: operation.id,
+              message: `Workspace ${workspace.name} belongs to workflow ${workspace.workflow}, not ${workflow.name}`,
+            });
+          }
+          const providers = await this.createProviders(workflow);
+          return await this.runConfigWorkspaceOperation({
+            workflow,
+            providers,
+            workspace,
+            operation,
+            rawInput: input.input,
+          });
+        },
+      }))
+    );
+  }
+
+  private listConfigWorkspaceOperationSummaries(): EngineOperationSummary[] {
+    return this.listWorkflows().flatMap((workflow) =>
+      workflow.workspaceOperations.map((operation) => {
+        assertAllowedConfigOperationId(operation.id);
+        return this.workspaceOperationSummary(workflow, operation);
+      }),
+    );
+  }
+
+  private workspaceOperationSummary(
+    workflow: LoadedWorkflow,
+    operation: WorkflowWorkspaceOperationDefinition<any, any, any, any>,
+  ): EngineOperationSummary {
+    return {
+      workflow: workflow.name,
+      id: operation.id,
+      source: "config" as const,
+      kind: "workspace-action" as const,
+      title: operation.title,
+      description: operation.description,
+      inputFields: operation.input?.fields ?? [],
+    };
+  }
+
   private listCoreOperationEntries(): RuntimeOperationEntry[] {
     const workflows = this.listWorkflows();
-    const hasWorkspaceCreator = workflows.some((workflow) => workflow.create || workflow.workspace);
+    const hasWorkspaceCreator = workflows.some((workflow) => workflow.workspace);
     const workflowField = stringField({
       name: "workflow",
       required: false,
@@ -421,7 +527,7 @@ export class DevMachineEngine {
               source: "core",
               kind: "command",
               title: "Create",
-              description: "Create a workspace from the resolved workflow artifact",
+              description: "Create a workspace",
               createsWorkspace: true,
               inputFields: [
                 workflowField,
@@ -436,7 +542,7 @@ export class DevMachineEngine {
             },
             async (input) => {
               const parsed = parseCoreOperationInput("create", input.input);
-              return await this.fork({
+              return await this.createWorkspace({
                 workflow: optionalStringInput("create", parsed, "workflow"),
                 name: requiredStringInput("create", parsed, "name"),
               });
@@ -444,117 +550,40 @@ export class DevMachineEngine {
           ),
         ]
         : []),
+    ];
+  }
+
+  private listCoreWorkspaceOperationEntries(): RuntimeWorkspaceOperationEntry[] {
+    const workflows = this.listWorkflows().filter((workflow) => workflow.workspace);
+    if (workflows.length === 0) return [];
+    const coreOperation = (
+      summary: EngineOperationSummary,
+      run: RuntimeWorkspaceOperationEntry["run"],
+    ): RuntimeWorkspaceOperationEntry => ({ summary, run });
+
+    return workflows.map((workflow) =>
       coreOperation(
         {
-          workflow: "",
-          id: "ssh",
-          source: "core",
-          kind: "command",
-          title: "SSH",
-          description: "Get an SSH command for a workspace or VM",
-          requiredHostMethods: [{ id: "host.command.run", modes: ["interactive"] }],
-          inputFields: [
-            workflowField,
-            stringField({ name: "workspaceOrVmId", position: 0, required: true }),
-            stringField({ name: "user", required: false }),
-            booleanField({ name: "print", required: false, defaultValue: false }),
-          ],
-          cli: {
-            positionals: [
-              { name: "workspaceOrVmId", index: 0 },
-            ],
-            options: [
-              { name: "workflow", flag: "--workflow" },
-              { name: "user", flag: "--user" },
-              { name: "print", flag: "--print", type: "boolean" },
-            ],
-          },
-        },
-        async (input) => {
-          const parsed = parseCoreOperationInput("ssh", input.input);
-          const workspaceOrVmId = requiredStringInput("ssh", parsed, "workspaceOrVmId");
-          const terminal = await this.attachTerminal({
-            workflow: optionalStringInput("ssh", parsed, "workflow"),
-            workspaceOrVmId,
-            printOnly: true,
-            user: optionalStringInput("ssh", parsed, "user"),
-          });
-          if (optionalBooleanInput("ssh", parsed, "print", false)) return terminal;
-          const commandResult = await (this.local.command ?? runLocalCommand)({
-            argv: ["sh", "-lc", terminal.command],
-            cwd: this.projectDir,
-            mode: "interactive",
-            reason: `Open an SSH session to ${workspaceOrVmId}`,
-            presentation: {
-              visible: true,
-              label: "SSH into workspace",
-            },
-          });
-          return { ...terminal, commandResult };
-        },
-      ),
-      coreOperation(
-        {
-          workflow: "",
-          id: "snapshot",
-          source: "core",
-          kind: "command",
-          title: "Snapshot",
-          description: "Capture a snapshot from a workspace VM",
-          inputFields: [
-            workflowField,
-            stringField({ name: "workspace", position: 0, required: true }),
-            stringField({ name: "label", required: false }),
-          ],
-          cli: {
-            positionals: [
-              { name: "workspace", index: 0 },
-            ],
-            options: [
-              { name: "workflow", flag: "--workflow" },
-              { name: "label", flag: "--label" },
-            ],
-          },
-        },
-        async (input) => {
-          const parsed = parseCoreOperationInput("snapshot", input.input);
-          return await this.snapshotWorkspace({
-            workflow: optionalStringInput("snapshot", parsed, "workflow"),
-            workspace: requiredStringInput("snapshot", parsed, "workspace"),
-            label: optionalStringInput("snapshot", parsed, "label"),
-          });
-        },
-      ),
-      coreOperation(
-        {
-          workflow: "",
-          id: "delete",
-          aliases: ["rm"],
+          workflow: workflow.name,
+          id: "remove",
           source: "core",
-          kind: "command",
-          title: "Delete",
-          description: "Delete a workspace VM and remove it from state",
-          inputFields: [
-            workflowField,
-            stringField({ name: "workspace", position: 0, required: true }),
-          ],
+          kind: "workspace-action",
+          title: "Remove",
+          description: "Remove a workspace",
+          inputFields: [],
           cli: {
-            positionals: [{ name: "workspace", index: 0 }],
             options: [
-              { name: "workflow", flag: "--workflow" },
-              { name: "yes", flag: "--yes", aliases: ["-y"], required: true, type: "boolean", runtime: false },
+              { name: "yes", flag: "--yes", aliases: ["-y"], type: "boolean", runtime: false },
             ],
           },
         },
-        async (input) => {
-          const parsed = parseCoreOperationInput("delete", input.input);
-          return await this.deleteWorkspace({
-            workflow: optionalStringInput("delete", parsed, "workflow"),
-            workspace: requiredStringInput("delete", parsed, "workspace"),
-          });
-        },
-      ),
-    ];
+        async (input) =>
+          await this.removeWorkspace({
+            workflow: input.workflow,
+            workspace: input.workspace,
+          }),
+      )
+    );
   }
 
   listNodeRuns(): WorkflowNodeRunRecord[] {
@@ -566,6 +595,15 @@ export class DevMachineEngine {
   }
 
   async runRuntimeOperation(input: { operation: string; workflow?: string; input?: unknown }): Promise<unknown> {
+    const workspaceTarget = parseWorkspaceOperationId(input.operation);
+    if (workspaceTarget) {
+      return await this.runWorkspaceOperation({
+        workspace: workspaceTarget.workspace,
+        operation: workspaceTarget.operation,
+        workflow: input.workflow,
+        input: input.input,
+      });
+    }
     const operation = this.findRuntimeOperationEntry(input.operation);
     if (!operation) throw new EngineOperationNotFoundError(input.operation);
     return await operation.run({ workflow: input.workflow, input: input.input });
@@ -588,12 +626,47 @@ export class DevMachineEngine {
       providers: runtime,
       local: this.local,
       workflow: workflow.name,
+      step: this.createStepRuntime(workflow.name, `operation.${operation.id}`, metadata),
     });
     if (result !== undefined) assertJsonValue(result, `Operation ${operation.id} result`);
-    if (operation.createsWorkspace) return this.saveOperationWorkspace(workflow, operation, input.input, result);
     return result ?? null;
   }
 
+  async runWorkspaceOperation(input: {
+    workspace: string;
+    operation: string;
+    workflow?: string;
+    input?: unknown;
+  }): Promise<unknown> {
+    const workspace = this.getStateService().getWorkspace(input.workspace);
+    if (!workspace) throw new Error(`Unknown workspace ${input.workspace}`);
+    const workflow = this.getWorkflow(input.workflow ?? workspace.workflow);
+    if (workspace.workflow !== workflow.name) {
+      throw new EngineOperationValidationError({
+        operation: input.operation,
+        message: `Workspace ${workspace.name} belongs to workflow ${workspace.workflow}, not ${workflow.name}`,
+      });
+    }
+
+    const core = this.listCoreWorkspaceOperationEntries().find((entry) =>
+      entry.summary.workflow === workflow.name && entry.summary.id === input.operation
+    );
+    if (core) {
+      return await core.run({ workspace: workspace.name, workflow: workflow.name, input: input.input });
+    }
+
+    const operation = workflow.workspaceOperations.find((item) => item.id === input.operation);
+    if (!operation) throw new EngineOperationNotFoundError(`${workspace.name}/${input.operation}`);
+    const providers = await this.createProviders(workflow);
+    return await this.runConfigWorkspaceOperation({
+      workflow,
+      providers,
+      workspace,
+      operation,
+      rawInput: input.input,
+    });
+  }
+
   async plan(input: { workflow?: string; machine?: string } = {}): Promise<WorkflowPlan> {
     const workflow = this.getWorkflow(input.workflow ?? input.machine);
     const providers = await this.createProviders(workflow);
@@ -621,163 +694,128 @@ export class DevMachineEngine {
   }> {
     const workflow = this.getWorkflow(input.workflow ?? input.machine);
     const providers = await this.createProviders(workflow);
-    const result = await this.evaluate({
-      workflow,
-      providers,
-      mode: "apply",
-    });
-    const workspaceSource = this.resolveWorkspaceSource(workflow, result.context, providers, { required: false });
+    let result: { context: Record<string, JsonValue>; plan: WorkflowPlan } | undefined;
+    const maxRestarts = 8;
+    for (let attempt = 0; attempt <= maxRestarts; attempt++) {
+      try {
+        result = await this.evaluate({
+          workflow,
+          providers,
+          mode: "apply",
+        });
+        break;
+      } catch (error) {
+        if (!(error instanceof StepInvalidationRestart)) throw error;
+        if (attempt === maxRestarts) {
+          throw new Error(
+            `Task ${error.currentNodePath} repeatedly invalidated ${error.targetNodePath}; stopping after ${maxRestarts + 1} attempts`,
+            { cause: error },
+          );
+        }
+      }
+    }
+    if (!result) throw new Error(`Workflow ${workflow.name} did not produce an apply result`);
 
     return {
       context: result.context,
-      snapshotId: snapshotIdOf(workspaceSource),
-      workspaceSource,
       plan: result.plan,
     };
   }
 
   async fork(input: { workflow?: string; machine?: string; name: string }): Promise<WorkspaceRecord> {
-    if (!input.name) throw new Error(`fork requires a workspace name`);
+    return await this.createWorkspace(input);
+  }
+
+  async createWorkspace(input: { workflow?: string; machine?: string; name: string }): Promise<WorkspaceRecord> {
+    if (!input.name) throw new Error(`create requires a workspace name`);
+    if (this.getStateService().getWorkspace(input.name)) {
+      throw new Error(`Workspace ${input.name} already exists`);
+    }
 
     const applied = await this.apply({ workflow: input.workflow ?? input.machine });
     const workflow = this.getWorkflow(input.workflow ?? input.machine);
     const providers = await this.createProviders(workflow);
-    if (workflow.create) {
-      return await this.createWorkspaceFromCallback({
-        workflow,
-        providers,
-        context: applied.context,
-        name: input.name,
-      });
+    if (!workflow.workspace) {
+      throw new Error(`Workflow ${workflow.name} does not define a workspace`);
     }
 
-    const sourceRef = this.resolveWorkspaceSource(workflow, applied.context, providers, { required: true })!;
-    const workspaceProvider = this.findWorkspaceProvider(providers, sourceRef);
-    const created = await workspaceProvider.createWorkspace(sourceRef, { name: input.name });
-    const providerId = created.providerId ?? providerIdOf(sourceRef) ?? this.providerIdForWorkspaceProvider(providers, workspaceProvider);
     const now = new Date().toISOString();
-
     const workspace: WorkspaceRecord = {
       id: crypto.randomUUID(),
       name: input.name,
-      providerId,
       workflow: workflow.name,
-      resourceId: created.resourceId,
-      snapshotId: created.snapshotId,
-      sourceRef: created.sourceRef ?? sourceRef,
-      context: { ...applied.context },
+      workflowCtx: { ...applied.context },
+      ctx: {},
       createdAt: now,
       updatedAt: now,
-      metadata: created.metadata ?? {},
     };
 
     this.getStateService().saveWorkspace(workspace);
-    await this.runWorkspaceCreatedHook({
-      workflow,
-      providers,
-      workspaceProvider,
-      workspace,
-      context: applied.context,
-    });
-
-    this.emit({
-      type: "workspace.ready",
-      workspaceId: input.name,
-      providerId: workspace.providerId,
-      resourceId: workspace.resourceId,
-      snapshotId: workspace.snapshotId,
-    });
-
-    return workspace;
-  }
-
-  async attachTerminal(input: {
-    workspaceOrVmId: string;
-    workflow?: string;
-    machine?: string;
-    printOnly?: boolean;
-    user?: string;
-  }): Promise<{ command: string }> {
-    const workspace = this.getStateService().findWorkspace(input.workspaceOrVmId);
-    const workflow = this.getWorkflow(input.workflow ?? input.machine ?? workspace?.workflow);
-    const providers = await this.createProviders(workflow);
-    const workspaceProvider = workspace
-      ? this.workspaceProviderById(providers, workspace.providerId)
-      : this.singleWorkspaceProvider(providers);
-    if (workspace) {
-      await this.runWorkspaceOpenHook({
+    try {
+      await this.runWorkspaceCreate({
         workflow,
         providers,
-        workspaceProvider,
         workspace,
-        context: workspace.context,
+        context: applied.context,
+        name: input.name,
       });
+    } catch (error) {
+      this.getStateService().deleteWorkspace(workspace.name);
+      throw error;
     }
-    const terminal = await workspaceProvider.ssh(workspace?.resourceId ?? input.workspaceOrVmId, { user: input.user });
+    const ready = this.getStateService().getWorkspace(input.name) ?? workspace;
 
-    if (!input.printOnly) {
-      const proc = Bun.spawn(["sh", "-lc", terminal.command], {
-        stdin: "inherit",
-        stdout: "inherit",
-        stderr: "inherit",
-      });
-      await proc.exited;
-    }
+    this.emit({
+      type: "workspace.ready",
+      workspaceId: ready.name,
+    });
 
-    return { command: terminal.command };
+    return ready;
   }
 
   async deleteWorkspace(input: { workspace: string; workflow?: string; machine?: string }): Promise<WorkspaceRecord> {
-    const workspace = this.getStateService().getWorkspace(input.workspace);
-    if (!workspace) throw new Error(`Unknown workspace ${input.workspace}`);
-
-    const workflow = this.getWorkflow(input.workflow ?? input.machine ?? workspace.workflow);
-    const providers = await this.createProviders(workflow);
-    const workspaceProvider = this.workspaceProviderById(providers, workspace.providerId);
-    await workspaceProvider.deleteWorkspace(workspace);
-
-    this.getStateService().deleteWorkspace(input.workspace);
-
-    return workspace;
+    return await this.removeWorkspace(input);
   }
 
-  async snapshotWorkspace(input: { workspace: string; label?: string; workflow?: string; machine?: string }): Promise<WorkflowNodeRunRecord> {
+  async removeWorkspace(input: { workspace: string; workflow?: string; machine?: string }): Promise<WorkspaceRecord> {
     const workspace = this.getStateService().getWorkspace(input.workspace);
     if (!workspace) throw new Error(`Unknown workspace ${input.workspace}`);
 
     const workflow = this.getWorkflow(input.workflow ?? input.machine ?? workspace.workflow);
+    if (workspace.workflow !== workflow.name) {
+      throw new EngineOperationValidationError({
+        operation: "remove",
+        message: `Workspace ${workspace.name} belongs to workflow ${workspace.workflow}, not ${workflow.name}`,
+      });
+    }
+    if (!workflow.workspace) {
+      throw new Error(`Workflow ${workflow.name} does not define a workspace`);
+    }
     const providers = await this.createProviders(workflow);
-    const workspaceProvider = this.workspaceProviderById(providers, workspace.providerId);
-    const snapshot = await workspaceProvider.snapshotWorkspace(workspace);
-    const sourceRef = snapshot.sourceRef ?? workspace.sourceRef;
-    const providerFingerprint = providerFingerprintFor(workflow);
-    const now = new Date().toISOString();
-    const record: WorkflowNodeRunRecord = {
-      id: crypto.randomUUID(),
-      workflow: workflow.name,
-      nodePath: `workspace.${workspace.name}`,
-      nodeName: input.label ?? `workspace:${workspace.name}`,
-      nodeKind: "workspace-snapshot",
-      nodeKey: hash({
-        kind: "workspace-snapshot",
-        workspace: workspace.name,
-        label: input.label ?? null,
-      }),
-      providerFingerprint,
-      upstreamRunIds: [],
-      output: { sourceRef },
-      artifacts: collectArtifacts(sourceRef),
-      invalidated: false,
-      createdAt: now,
-      metadata: {
-        workspace: workspace.name,
-        label: input.label ?? null,
-        snapshotId: snapshot.snapshotId ?? null,
+    const metadata: JsonObject = {};
+    const runtime = await this.createTaskRuntime({
+      workflow,
+      providers,
+      nodePath: `workspace.${workspace.name}.remove`,
+      metadata,
+    });
+    const draft = cloneWorkspace(workspace);
+    const workspaceRuntime = this.createWorkspaceRuntime(draft);
+
+    await workflow.workspace.remove({
+      ...runtime,
+      workflow: {
+        name: workflow.name,
+        ctx: Object.freeze({ ...workspace.workflowCtx }),
       },
-    };
+      workspace: workspaceRuntime,
+      providers: runtime,
+      local: this.local,
+      step: this.createStepRuntime(workflow.name, `workspace.${workspace.name}.remove`, metadata),
+    });
 
-    this.getStateService().saveNodeRun(record);
-    return record;
+    this.getStateService().deleteWorkspace(input.workspace);
+    return workspace;
   }
 
   private async evaluate(input: {
@@ -796,6 +834,7 @@ export class DevMachineEngine {
       state: {
         context: {},
         upstreamRunIds: [],
+        previousTasks: [],
         known: true,
       },
       prefix: [],
@@ -844,6 +883,7 @@ export class DevMachineEngine {
       state = {
         context: result.context,
         upstreamRunIds: result.upstreamRunIds,
+        previousTasks: result.previousTasks,
         known: result.known,
         blockedReason: result.blockedReason,
       };
@@ -856,6 +896,7 @@ export class DevMachineEngine {
     const branches = parallelBranches(input.node);
     const branchOutputs: Record<string, JsonValue> = {};
     const joinedRunIds: string[] = [];
+    let joinedPreviousTasks = [...input.state.previousTasks];
     let known = input.state.known;
     let blockedReason = input.state.blockedReason;
 
@@ -870,6 +911,7 @@ export class DevMachineEngine {
         state: {
           context: { ...input.state.context },
           upstreamRunIds: [...input.state.upstreamRunIds],
+          previousTasks: [...input.state.previousTasks],
           known: input.state.known,
           blockedReason: input.state.blockedReason,
         },
@@ -881,6 +923,7 @@ export class DevMachineEngine {
       if (branchState.known) {
         branchOutputs[branchName] = branchState.context;
         joinedRunIds.push(...branchState.upstreamRunIds);
+        joinedPreviousTasks = mergePreviousTasks(joinedPreviousTasks, branchState.previousTasks);
       } else {
         known = false;
         blockedReason ??= branchState.blockedReason ?? `depends on ${branchName}`;
@@ -890,6 +933,7 @@ export class DevMachineEngine {
     return {
       context: known ? { ...input.state.context, ...branchOutputs } : { ...input.state.context },
       upstreamRunIds: known ? joinedRunIds.sort() : [],
+      previousTasks: known ? joinedPreviousTasks : input.state.previousTasks,
       known,
       blockedReason,
       planNodes: input.planNodes,
@@ -900,7 +944,7 @@ export class DevMachineEngine {
     const nodePath = [...input.prefix, input.node.name].join(".");
     const upstreamRunIds = [...input.state.upstreamRunIds];
     const nodeKey = hash({
-      cache: "task-v2",
+      cache: "task-v3",
       kind: "task",
       path: nodePath,
       name: input.node.name,
@@ -922,6 +966,7 @@ export class DevMachineEngine {
       return {
         context: input.state.context,
         upstreamRunIds: [],
+        previousTasks: input.state.previousTasks,
         known: false,
         blockedReason: input.state.blockedReason ?? `depends on ${nodePath}`,
         planNodes: input.planNodes,
@@ -936,9 +981,14 @@ export class DevMachineEngine {
       upstreamRunIds,
       providers: input.providers,
       outputSchema: input.node.options?.output,
+      cacheTTL: input.node.options?.cacheTTL,
     });
 
     if (cached) {
+      const previousTasks = appendPreviousTask(input.state.previousTasks, {
+        name: input.node.name,
+        path: nodePath,
+      });
       this.emit({ type: "node.cached", nodePath, runId: cached.id });
       input.planNodes.push({
         index: planIndex,
@@ -949,8 +999,9 @@ export class DevMachineEngine {
         upstreamRunIds,
       });
       return {
-        context: { ...input.state.context, ...cached.output },
+        context: cached.output,
         upstreamRunIds: [cached.id],
+        previousTasks,
         known: true,
         planNodes: input.planNodes,
       };
@@ -969,6 +1020,7 @@ export class DevMachineEngine {
       return {
         context: input.state.context,
         upstreamRunIds: [],
+        previousTasks: input.state.previousTasks,
         known: false,
         blockedReason: `depends on ${nodePath}`,
         planNodes: input.planNodes,
@@ -983,28 +1035,38 @@ export class DevMachineEngine {
       nodePath,
       metadata,
     });
+    const step = this.createStepRuntime(
+      input.workflow.name,
+      nodePath,
+      metadata,
+      input.state.context,
+      input.state.previousTasks,
+    );
     const result = await input.node.handler({
       ...runtime,
       providers: runtime,
-      ctx: Object.freeze({ ...input.state.context }),
-      runtime: {
-        workflow: input.workflow.name,
-        nodePath,
-        metadata: (value) => {
-          Object.assign(metadata, value);
-        },
-        log: (data, options = {}) => {
-          this.emit({
-            type: "log.output",
-            nodePath,
-            stream: options.stream ?? "info",
-            label: options.label,
-            data,
-          });
-        },
-      },
+      step,
     });
-    const output = normalizeTaskOutput(nodePath, result, input.node.options?.output, "fresh");
+    if (isStepInvalidation(result)) {
+      const invalidatedRunIds = this.getStateService().invalidateNodeRuns({
+        workflow: input.workflow.name,
+        nodePaths: [result.targetNodePath, nodePath],
+      });
+      throw new StepInvalidationRestart({
+        workflow: input.workflow.name,
+        target: result.target,
+        targetNodePath: result.targetNodePath,
+        currentNodePath: nodePath,
+        invalidatedRunIds,
+      });
+    }
+    const output = normalizeTaskOutput(
+      nodePath,
+      result,
+      input.node.options?.output,
+      "fresh",
+      input.state.context,
+    );
     if (!output) {
       throw new Error(`Task ${nodePath} output failed schema validation`);
     }
@@ -1038,9 +1100,15 @@ export class DevMachineEngine {
     }
     this.emit({ type: "node.completed", nodePath, runId: record.id });
 
+    const previousTasks = appendPreviousTask(input.state.previousTasks, {
+      name: input.node.name,
+      path: nodePath,
+    });
+
     return {
-      context: { ...input.state.context, ...output },
+      context: output,
       upstreamRunIds: [record.id],
+      previousTasks,
       known: true,
       planNodes: input.planNodes,
     };
@@ -1054,9 +1122,11 @@ export class DevMachineEngine {
     upstreamRunIds: readonly string[];
     providers: ProviderControllers;
     outputSchema?: OutputSchema;
+    cacheTTL?: WorkflowTaskCacheTTL;
   }): Promise<WorkflowNodeRunRecord | undefined> {
     const cached = this.getStateService().findReusableNodeRun(input);
     if (!cached) return undefined;
+    if (!isCacheFresh(cached.createdAt, input.cacheTTL)) return undefined;
 
     const parsed = normalizeTaskOutput(input.nodePath, cached.output, input.outputSchema, "cached");
     if (!parsed) return undefined;
@@ -1134,65 +1204,133 @@ export class DevMachineEngine {
     return Object.fromEntries(entries) as ProviderRuntimeMap<WorkflowProviderMap>;
   }
 
-  private async runWorkspaceCreatedHook(input: {
+  private async runWorkspaceCreate(input: {
     workflow: LoadedWorkflow;
     providers: ProviderControllers;
-    workspaceProvider: WorkflowWorkspaceProvider;
     workspace: WorkspaceRecord;
     context: Record<string, JsonValue>;
+    name: string;
   }): Promise<void> {
-    await this.runWorkspaceHook("created", input.workflow.workspace?.onCreated, input);
+    if (!input.workflow.workspace) {
+      throw new Error(`Workflow ${input.workflow.name} does not define a workspace`);
+    }
+    const draft = cloneWorkspace(input.workspace);
+    const metadata: JsonObject = {};
+    const providers = await this.createTaskRuntime({
+      workflow: input.workflow,
+      providers: input.providers,
+      nodePath: `workspace.${input.name}.create`,
+      metadata,
+    });
+
+    try {
+      const data = await input.workflow.workspace.create({
+        ...providers,
+        workflow: {
+          name: input.workflow.name,
+          ctx: Object.freeze({ ...input.context }),
+        },
+        workspace: {
+          name: input.name,
+        },
+        providers,
+        local: this.local,
+        step: this.createStepRuntime(input.workflow.name, `workspace.${input.name}.create`, metadata),
+      });
+      assertJsonValue(data, `Workflow ${input.workflow.name} workspace create result`);
+      if (!isPlainObject(data)) {
+        throw new Error(`Workflow ${input.workflow.name} workspace create result must be an object`);
+      }
+      draft.ctx = { ...data };
+    } finally {
+      draft.updatedAt = new Date().toISOString();
+      this.getStateService().saveWorkspace(draft);
+    }
   }
 
-  private async runWorkspaceOpenHook(input: {
+  private async runConfigWorkspaceOperation(input: {
     workflow: LoadedWorkflow;
     providers: ProviderControllers;
-    workspaceProvider: WorkflowWorkspaceProvider;
     workspace: WorkspaceRecord;
-    context: Record<string, JsonValue>;
-  }): Promise<void> {
-    await this.runWorkspaceHook("open", input.workflow.workspace?.onOpen, input);
-  }
-
-  private async runWorkspaceHook(
-    lifecycle: "created" | "open",
-    hook: ((context: {
-      workspace: WorkspaceRuntimeRecord;
-      ctx: Readonly<Record<string, JsonValue>>;
-      providers: ProviderRuntimeMap<WorkflowProviderMap>;
-      providerContext: ProviderWorkspaceContext;
-      local: LocalWorkspaceRuntime;
-    }) => Promise<void> | void) | undefined,
-    input: {
-      workflow: LoadedWorkflow;
-      providers: ProviderControllers;
-      workspaceProvider: WorkflowWorkspaceProvider;
-      workspace: WorkspaceRecord;
-      context: Record<string, JsonValue>;
-    },
-  ): Promise<void> {
-    if (!hook) return;
-
-    const providerContext = await input.workspaceProvider.workspaceContext?.(input.workspace) ?? {};
-    const workspace: WorkspaceRuntimeRecord = {
-      ...input.workspace,
-      cwd: resolveWorkspaceCwd(input.workflow, input.context),
-    };
+    operation: WorkflowWorkspaceOperationDefinition<any, any, any, any>;
+    rawInput: unknown;
+  }): Promise<unknown> {
     const metadata: JsonObject = {};
     const providers = await this.createTaskRuntime({
       workflow: input.workflow,
       providers: input.providers,
-      nodePath: `workspace.${input.workspace.name}.${lifecycle}`,
+      nodePath: `workspace.${input.workspace.name}.${input.operation.id}`,
       metadata,
     });
-
-    await hook({
+    const draft = cloneWorkspace(input.workspace);
+    const workspace = this.createWorkspaceRuntime(draft);
+    const operationInput = this.resolveOperationInput(input.workflow, input.operation, input.rawInput ?? {});
+
+    const result = await input.operation.run({
+      ...providers,
+      workflow: {
+        name: input.workflow.name,
+        ctx: Object.freeze({ ...input.workspace.workflowCtx }),
+      },
+      input: Object.freeze(operationInput),
       workspace,
-      ctx: Object.freeze({ ...input.context }),
       providers,
-      providerContext: normalizeProviderWorkspaceContext(providerContext),
       local: this.local,
+      step: this.createStepRuntime(
+        input.workflow.name,
+        `workspace.${input.workspace.name}.${input.operation.id}`,
+        metadata,
+      ),
     });
+    if (result !== undefined) assertJsonValue(result, `Workspace operation ${input.operation.id} result`);
+    return result ?? null;
+  }
+
+  private createWorkspaceRuntime<Data extends object>(draft: WorkspaceRecord): WorkspaceRuntimeRecord<Data> {
+    return Object.freeze({
+      name: draft.name,
+      ctx: Object.freeze({ ...draft.ctx }) as Data,
+    }) as WorkspaceRuntimeRecord<Data>;
+  }
+
+  private createStepRuntime<Context extends JsonObject = JsonObject>(
+    workflow: string,
+    nodePath: string,
+    metadata: JsonObject,
+    context: Context = {} as Context,
+    previousTasks: readonly EvaluationPreviousTask[] = [],
+  ) {
+    return {
+      workflow,
+      nodePath,
+      ctx: Object.freeze({ ...context }) as Readonly<Context>,
+      metadata: (value: JsonObject) => {
+        Object.assign(metadata, value);
+      },
+      log: (data: string, options: { stream?: WorkflowLogStream; label?: string } = {}) => {
+        this.emit({
+          type: "log.output",
+          nodePath,
+          stream: options.stream ?? "info",
+          label: options.label,
+          data,
+        });
+      },
+      invalidate: <Target extends string>(target: Target) => {
+        const matches = previousTasks.filter((task) => task.name === target || task.path === target);
+        if (matches.length === 0) {
+          throw new Error(`Task ${nodePath} cannot invalidate ${target} because it has not run earlier in this workflow`);
+        }
+        if (matches.length > 1) {
+          throw new Error(`Task ${nodePath} cannot invalidate ${target} because it matches multiple earlier tasks`);
+        }
+        return {
+          kind: STEP_INVALIDATION_KIND,
+          target,
+          targetNodePath: matches[0]!.path,
+        };
+      },
+    };
   }
 
   private getWorkflow(name: string | undefined): LoadedWorkflow {
@@ -1234,7 +1372,7 @@ export class DevMachineEngine {
 
   private resolveOperationInput(
     workflow: LoadedWorkflow,
-    operation: WorkflowOperationDefinition<any, any>,
+    operation: { id: string; input?: { fields: readonly WorkflowInputFieldDefinition[] } },
     value: unknown,
   ): Record<string, unknown> {
     const raw = isPlainObject(value) ? value : {};
@@ -1274,11 +1412,7 @@ export class DevMachineEngine {
             message: `Workspace ${workspace.name} belongs to workflow ${workspace.workflow}, not ${workflow.name}`,
           });
         }
-        resolved[field.name] = {
-          ...workspace,
-          cwd: resolveWorkspaceCwd(workflow, workspace.context),
-          data: workspace.metadata,
-        };
+        resolved[field.name] = this.createWorkspaceRuntime(cloneWorkspace(workspace));
         continue;
       }
 
@@ -1318,115 +1452,6 @@ export class DevMachineEngine {
     return resolved;
   }
 
-  private saveOperationWorkspace(
-    workflow: LoadedWorkflow,
-    operation: WorkflowOperationDefinition<any, any>,
-    rawInput: unknown,
-    result: unknown,
-  ): WorkspaceRecord {
-    if (!isPlainObject(result)) {
-      throw new Error(`Operation ${operation.id} must return an object when createsWorkspace is true`);
-    }
-    const data = result as Record<string, JsonValue>;
-    const raw = isPlainObject(rawInput) ? rawInput : {};
-    const name = typeof data.name === "string"
-      ? data.name
-      : typeof raw.name === "string"
-        ? raw.name
-        : undefined;
-    if (!name) throw new Error(`Operation ${operation.id} must return or receive a workspace name`);
-    const resourceId = typeof data.resourceId === "string"
-      ? data.resourceId
-      : typeof data.vmId === "string"
-        ? data.vmId
-        : name;
-    const now = new Date().toISOString();
-    const workspace: WorkspaceRecord = {
-      id: crypto.randomUUID(),
-      name,
-      providerId: typeof data.providerId === "string" ? data.providerId : "config",
-      workflow: workflow.name,
-      resourceId,
-      snapshotId: typeof data.snapshotId === "string" ? data.snapshotId : undefined,
-      sourceRef: isJsonValue(data.sourceRef) ? data.sourceRef : data,
-      context: {},
-      createdAt: now,
-      updatedAt: now,
-      metadata: data,
-    };
-    this.getStateService().saveWorkspace(workspace);
-    this.emit({
-      type: "workspace.ready",
-      workspaceId: workspace.name,
-      providerId: workspace.providerId,
-      resourceId: workspace.resourceId,
-      snapshotId: workspace.snapshotId,
-    });
-    return workspace;
-  }
-
-  private async createWorkspaceFromCallback(input: {
-    workflow: LoadedWorkflow;
-    providers: ProviderControllers;
-    context: Record<string, JsonValue>;
-    name: string;
-  }): Promise<WorkspaceRecord> {
-    if (!input.workflow.create) {
-      throw new Error(`Workflow ${input.workflow.name} does not define a create callback`);
-    }
-    const metadata: JsonObject = {};
-    const runtime = await this.createTaskRuntime({
-      workflow: input.workflow,
-      providers: input.providers,
-      nodePath: `create.${input.name}`,
-      metadata,
-    });
-    const result = await input.workflow.create.handler({
-      ...runtime,
-      ctx: Object.freeze({ ...input.context }),
-      name: input.name,
-      providers: runtime,
-      local: this.local,
-      workflow: input.workflow.name,
-    });
-    assertJsonValue(result, `Workflow ${input.workflow.name} create result`);
-    if (!isPlainObject(result)) {
-      throw new Error(`Workflow ${input.workflow.name} create result must be an object`);
-    }
-
-    const data = result as Record<string, JsonValue>;
-    const name = typeof data.name === "string" ? data.name : input.name;
-    const resourceId = typeof data.resourceId === "string"
-      ? data.resourceId
-      : typeof data.vmId === "string"
-        ? data.vmId
-        : name;
-    const now = new Date().toISOString();
-    const workspace: WorkspaceRecord = {
-      id: crypto.randomUUID(),
-      name,
-      providerId: typeof data.providerId === "string" ? data.providerId : "config",
-      workflow: input.workflow.name,
-      resourceId,
-      snapshotId: typeof data.snapshotId === "string" ? data.snapshotId : undefined,
-      sourceRef: isJsonValue(data.sourceRef) ? data.sourceRef : data,
-      context: { ...input.context },
-      createdAt: now,
-      updatedAt: now,
-      metadata: data,
-    };
-
-    this.getStateService().saveWorkspace(workspace);
-    this.emit({
-      type: "workspace.ready",
-      workspaceId: workspace.name,
-      providerId: workspace.providerId,
-      resourceId: workspace.resourceId,
-      snapshotId: workspace.snapshotId,
-    });
-    return workspace;
-  }
-
   private getStateService(): StateService {
     if (!this.state) {
       throw new Error(`No state database loaded. Call engine.load() first.`);
@@ -1440,6 +1465,8 @@ export class DevMachineEngine {
         const controller = await this.providerFactory({
           provider,
           storage: this.getStateService().providerStorage(provider.providerId),
+          hostStorage: this.getProviderHostStorage(provider.providerId),
+          local: this.local,
         });
         return [name, controller] as const;
       }),
@@ -1458,6 +1485,18 @@ export class DevMachineEngine {
     return await plugin.createProvider(input);
   }
 
+  private getProviderHostStorage(providerId: string): ReturnType<ProviderHostStorageFactory> {
+    let storage = this.providerHostStorage.get(providerId);
+    if (!storage) {
+      storage = this.hostStorageFactory({
+        providerId,
+        rootDir: this.hostStorageDir,
+      });
+      this.providerHostStorage.set(providerId, storage);
+    }
+    return storage;
+  }
+
   private async resolveWorkflow(root: WorkflowNodeDefinition<any, any, any>): Promise<LoadedWorkflow> {
     const providers: Record<string, LoadedProviderDefinition> = {};
     for (const [name, definition] of Object.entries(root.workflow.providers)) {
@@ -1472,75 +1511,11 @@ export class DevMachineEngine {
       providers,
       root,
       workspace: root.workspaceDefinition,
-      create: root.createDefinition,
       operations: root.operations ?? [],
+      workspaceOperations: root.workspaceOperations ?? [],
     };
   }
 
-  private resolveWorkspaceSource(
-    workflow: LoadedWorkflow,
-    context: Record<string, JsonValue>,
-    providers: ProviderControllers,
-    options: { required: boolean },
-  ): JsonValue | undefined {
-    const source = workflow.workspace?.source?.(context);
-    if (source !== undefined) {
-      assertJsonValue(source, `Workflow ${workflow.name} workspace source`);
-      return source;
-    }
-
-    const candidates = collectArtifacts(context).filter((artifact) =>
-      Object.values(providers).some((provider) => provider.workspace?.canUse(artifact)),
-    );
-
-    if (candidates.length === 1) return candidates[0];
-    if (!options.required && candidates.length === 0) return undefined;
-    if (candidates.length === 0) {
-      throw new Error(`Workflow ${workflow.name} did not produce a provider artifact that can be forked`);
-    }
-    throw new Error(`Workflow ${workflow.name} produced multiple forkable artifacts; configure workspace.source`);
-  }
-
-  private findWorkspaceProvider(
-    providers: ProviderControllers,
-    sourceRef: JsonValue,
-  ): WorkflowWorkspaceProvider {
-    const provider = Object.values(providers).find((controller) => controller.workspace?.canUse(sourceRef));
-    if (!provider?.workspace) {
-      throw new Error(`No workflow provider can create a workspace from ${stableJson(sourceRef)}`);
-    }
-    return provider.workspace;
-  }
-
-  private workspaceProviderById(
-    providers: ProviderControllers,
-    providerId: string,
-  ): WorkflowWorkspaceProvider {
-    const provider = Object.values(providers).find((controller) => controller.providerId === providerId);
-    if (!provider?.workspace) {
-      throw new Error(`Provider ${providerId} does not support workspaces`);
-    }
-    return provider.workspace;
-  }
-
-  private singleWorkspaceProvider(providers: ProviderControllers): WorkflowWorkspaceProvider {
-    const workspaceProviders = Object.values(providers).filter((provider) => provider.workspace);
-    if (workspaceProviders.length !== 1 || !workspaceProviders[0]?.workspace) {
-      throw new Error(`Expected exactly one workspace-capable provider`);
-    }
-    return workspaceProviders[0].workspace;
-  }
-
-  private providerIdForWorkspaceProvider(
-    providers: ProviderControllers,
-    workspaceProvider: WorkflowWorkspaceProvider,
-  ): string {
-    for (const provider of Object.values(providers)) {
-      if (provider.workspace === workspaceProvider) return provider.providerId;
-    }
-    return "unknown";
-  }
-
   private emit(event: WorkflowEvent): void {
     for (const handler of this.handlers) handler(event);
   }
@@ -1552,6 +1527,23 @@ export async function createDevMachineEngine(
   return new DevMachineEngine(options);
 }
 
+function cloneWorkspace(workspace: WorkspaceRecord): WorkspaceRecord {
+  return {
+    ...workspace,
+    workflowCtx: { ...workspace.workflowCtx },
+    ctx: { ...workspace.ctx },
+  };
+}
+
+function parseWorkspaceOperationId(value: string): { workspace: string; operation: string } | undefined {
+  const slash = value.indexOf("/");
+  if (slash <= 0 || slash === value.length - 1) return undefined;
+  return {
+    workspace: value.slice(0, slash),
+    operation: value.slice(slash + 1),
+  };
+}
+
 async function resolveProviderDefinition(
   definition: WorkflowDefinition<any, any>["providers"][string],
 ): Promise<LoadedProviderDefinition> {
@@ -1650,7 +1642,7 @@ function summarizeWorkflow(workflow: LoadedWorkflow): WorkflowSummary {
     providers: Object.entries(workflow.providers).map(([name, provider]) => `${name}:${provider.providerId}`),
     nodes: collectNodePaths(workflow.root),
     operations: workflow.operations.map((operation) => operation.id),
-    createsWorkspace: Boolean(workflow.create || workflow.workspace),
+    createsWorkspace: Boolean(workflow.workspace),
     workspace: workflow.workspace,
   };
 }
@@ -1716,26 +1708,123 @@ function parallelBranches(node: WorkflowNodeDefinition<any, any, any>): Record<s
   return (node as { branches?: Record<string, WorkflowNodeDefinition<any, any, any>> }).branches ?? {};
 }
 
+function appendPreviousTask(
+  tasks: readonly EvaluationPreviousTask[],
+  task: EvaluationPreviousTask,
+): EvaluationPreviousTask[] {
+  return mergePreviousTasks([...tasks], [task]);
+}
+
+function mergePreviousTasks(
+  left: readonly EvaluationPreviousTask[],
+  right: readonly EvaluationPreviousTask[],
+): EvaluationPreviousTask[] {
+  const seen = new Set<string>();
+  const result: EvaluationPreviousTask[] = [];
+  for (const task of [...left, ...right]) {
+    if (seen.has(task.path)) continue;
+    seen.add(task.path);
+    result.push(task);
+  }
+  return result;
+}
+
 function normalizeTaskOutput(
   nodePath: string,
   result: unknown,
   schema: OutputSchema | undefined,
   source: "fresh" | "cached",
+  currentContext: Record<string, JsonValue> = {},
 ): Record<string, JsonValue> | undefined {
+  if (source === "fresh") {
+    if (result === undefined) return { ...currentContext };
+    if (!isPlainObject(result) || !("ctx" in result)) {
+      throw new Error(`Task ${nodePath} must return { ctx: { ... } } or step.invalidate(...)`);
+    }
+    const ctx = result.ctx;
+    const value = schema ? parseWithSchema(schema, ctx, source) : ctx;
+    if (!isPlainObject(value)) {
+      throw new Error(`Task ${nodePath} ctx must be a JSON-serializable object`);
+    }
+
+    for (const [key, item] of Object.entries(value)) {
+      assertJsonValue(item, `Task ${nodePath} ctx value ${key}`);
+    }
+
+    return value as Record<string, JsonValue>;
+  }
+
   const value = schema ? parseWithSchema(schema, result, source) : result;
-  if (value === undefined) return source === "cached" && schema ? undefined : {};
+  if (value === undefined) return schema ? undefined : {};
   if (!isPlainObject(value)) {
     if (source === "cached") return undefined;
-    throw new Error(`Task ${nodePath} must return an object with JSON-serializable context values`);
+    throw new Error(`Task ${nodePath} cached ctx must be a JSON-serializable object`);
   }
 
   for (const [key, item] of Object.entries(value)) {
-    assertJsonValue(item, `Task ${nodePath} return value ${key}`);
+    assertJsonValue(item, `Task ${nodePath} ctx value ${key}`);
   }
 
   return value as Record<string, JsonValue>;
 }
 
+function isCacheFresh(createdAt: string, ttl: WorkflowTaskCacheTTL | undefined): boolean {
+  const ttlMs = parseCacheTTL(ttl);
+  if (ttlMs === undefined) return true;
+  if (ttlMs <= 0) return false;
+  const createdTime = Date.parse(createdAt);
+  if (Number.isNaN(createdTime)) return false;
+  return Date.now() - createdTime <= ttlMs;
+}
+
+function parseCacheTTL(ttl: WorkflowTaskCacheTTL | undefined): number | undefined {
+  if (ttl === undefined) return undefined;
+  if (typeof ttl === "number") {
+    assertFiniteTTL(ttl, "cacheTTL");
+    return ttl;
+  }
+  if (typeof ttl === "string") return parseCacheTTLString(ttl);
+
+  const total =
+    (ttl.seconds ?? 0) * 1000 +
+    (ttl.minutes ?? 0) * 60 * 1000 +
+    (ttl.hours ?? 0) * 60 * 60 * 1000 +
+    (ttl.days ?? 0) * 24 * 60 * 60 * 1000;
+  assertFiniteTTL(total, "cacheTTL");
+  return total;
+}
+
+function parseCacheTTLString(value: string): number {
+  const input = value.trim();
+  const match = input.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/i);
+  if (!match) {
+    throw new Error(`cacheTTL must be a number, an object, or a string like "30m", "6h", or "1d"`);
+  }
+  const amount = Number(match[1]);
+  assertFiniteTTL(amount, "cacheTTL");
+  const unit = match[2].toLowerCase();
+  const multiplier =
+    unit === "ms" ? 1
+      : unit === "s" ? 1000
+      : unit === "m" ? 60 * 1000
+      : unit === "h" ? 60 * 60 * 1000
+      : 24 * 60 * 60 * 1000;
+  return amount * multiplier;
+}
+
+function assertFiniteTTL(value: number, label: string): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${label} must be a finite non-negative duration`);
+  }
+}
+
+function isStepInvalidation(value: unknown): value is WorkflowStepInvalidation<string> {
+  return isPlainObject(value) &&
+    value.kind === STEP_INVALIDATION_KIND &&
+    typeof value.target === "string" &&
+    typeof value.targetNodePath === "string";
+}
+
 function parseWithSchema(
   schema: OutputSchema,
   value: unknown,
@@ -1786,23 +1875,6 @@ function kindOf(value: unknown): string | undefined {
   return isPlainObject(value) && typeof value.kind === "string" ? value.kind : undefined;
 }
 
-function snapshotIdOf(value: unknown): string | undefined {
-  return isPlainObject(value) && typeof value.snapshotId === "string" ? value.snapshotId : undefined;
-}
-
-function resolveWorkspaceCwd(workflow: LoadedWorkflow, context: Record<string, JsonValue>): string | undefined {
-  const cwd = workflow.workspace?.cwd;
-  return typeof cwd === "function" ? cwd(context) : cwd;
-}
-
-function normalizeProviderWorkspaceContext(value: unknown): ProviderWorkspaceContext {
-  if (value === undefined) return {};
-  if (!isPlainObject(value)) {
-    throw new Error(`Provider workspace context must be an object`);
-  }
-  return value as ProviderWorkspaceContext;
-}
-
 function assertJsonValue(value: unknown, label: string): asserts value is JsonValue {
   if (
     value === null ||
@@ -1837,15 +1909,7 @@ function isJsonValue(value: unknown): value is JsonValue {
   }
 }
 
-const RESERVED_HOST_OPERATION_IDS = new Set([
-  "completion",
-  "doctor",
-  "help",
-  "init",
-  "projects",
-  "run",
-  "version",
-]);
+const RESERVED_HOST_OPERATION_IDS = new Set<string>(RESERVED_WORKFLOW_OPERATION_IDS);
 
 const CORE_OPERATION_INPUT_FIELDS: Record<string, readonly string[]> = {
   plan: ["workflow"],
@@ -1853,7 +1917,6 @@ const CORE_OPERATION_INPUT_FIELDS: Record<string, readonly string[]> = {
   create: ["workflow", "name"],
   ssh: ["workflow", "workspaceOrVmId", "user", "print"],
   snapshot: ["workflow", "workspace", "label"],
-  delete: ["workflow", "workspace"],
 };
 
 function assertAllowedConfigOperationId(operationId: string): void {