@kb-labs/workflow-engine 2.94.0 → 2.98.0

package/dist/index.js

@@ -1,7 +1,7 @@
-import { readFile, mkdir, writeFile, readdir } from 'fs/promises';
+import { readFile, access, mkdir, writeFile, readdir } from 'fs/promises';
 import { resolve, join, basename } from 'path';
 import { parse, stringify } from 'yaml';
-import { WorkflowSpecSchema } from '@kb-labs/workflow-contracts';
+import { WorkflowSpecSchema, evaluateExpression } from '@kb-labs/workflow-contracts';
 import { randomUUID } from 'crypto';
 import { WORKFLOW_REDIS_CHANNEL, EVENT_NAMES, IDEMPOTENCY_TTL_ENV, CONCURRENCY_TTL_ENV } from '@kb-labs/workflow-constants';
 import { createFileSystemArtifactClient } from '@kb-labs/workflow-artifacts';
@@ -317,7 +317,8 @@ var RunCoordinator = class {
         needs,
         pendingDependencies: [...needs],
         blocked: needs.length > 0,
-        priority
+        priority,
+        if: jobSpec.if
       });
     }
     const workflowRun = {
@@ -857,7 +858,38 @@ var WorkflowEngine = class {
         this.logger.info("Job re-queued for retry", { runId, jobId });
       }, backoffMs);
     } else {
-      await this.moveToDLQ(runId, jobId, error);
+      await this.deadLetterJob(runId, jobId, error);
+      await this.cancelDownstreamJobs(runId, job.jobName, `upstream job "${job.jobName}" failed`);
+      await this.checkRunCompletion(runId);
+    }
+  }
+  /**
+   * Recursively cancel jobs blocked on a failed/cancelled upstream job, so the
+   * DAG does not leave dependents stuck in 'queued'. Cancellation cascades:
+   * a cancelled job also cancels its own dependents.
+   */
+  async cancelDownstreamJobs(runId, failedJobName, reason) {
+    const released = await this.stateStore.releaseBlockedJobs(runId, failedJobName);
+    for (const downstreamJob of released) {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      await this.stateStore.updateJob(runId, downstreamJob.id, (draft) => {
+        draft.status = "cancelled";
+        draft.blocked = false;
+        draft.finishedAt = now;
+        draft.error = { message: reason, timestamp: now };
+      });
+      await this.events.publish({
+        type: EVENT_NAMES.job.cancelled,
+        runId,
+        jobId: downstreamJob.id,
+        payload: { jobName: downstreamJob.jobName, reason }
+      });
+      this.logger.info("Cancelled dependent job after upstream failure", {
+        runId,
+        jobId: downstreamJob.id,
+        unlockedBy: failedJobName
+      });
+      await this.cancelDownstreamJobs(runId, downstreamJob.jobName, reason);
     }
   }
   /**
@@ -879,7 +911,15 @@ var WorkflowEngine = class {
       draft.status = "running";
       draft.startedAt = (/* @__PURE__ */ new Date()).toISOString();
     });
-    this.logger.debug("Job started", { runId, jobId });
+    await this.stateStore.updateRun(runId, (draft) => {
+      if (draft.status === "queued") {
+        draft.status = "running";
+        if (!draft.startedAt) {
+          draft.startedAt = (/* @__PURE__ */ new Date()).toISOString();
+        }
+      }
+    });
+    this.logger.info("Job started", { runId, jobId });
     const run = await this.getRun(runId);
     const job = run?.jobs.find((j) => j.id === jobId);
     this.analytics?.track("workflow.job.started", {
@@ -924,14 +964,65 @@ var WorkflowEngine = class {
       payload: { jobName: job?.jobName, durationMs: duration }
     });
     if (job?.jobName) {
+      const run2 = await this.stateStore.getRun(runId);
+      const exprCtx = this.buildExpressionContext(run2);
       const released = await this.stateStore.releaseBlockedJobs(runId, job.jobName);
       for (const releasedJob of released) {
-        await this.scheduler.enqueueJob(runId, releasedJob, releasedJob.priority ?? "normal");
-        this.logger.info("Unblocked dependent job", { runId, jobId: releasedJob.id, unlockedBy: job.jobName });
+        if (releasedJob.if && !this.evaluateJobIf(releasedJob.if, exprCtx)) {
+          await this.skipJob(runId, releasedJob);
+        } else {
+          await this.scheduler.enqueueJob(runId, releasedJob, releasedJob.priority ?? "normal");
+          this.logger.info("Unblocked dependent job", { runId, jobId: releasedJob.id, unlockedBy: job.jobName });
+        }
       }
     }
     await this.checkRunCompletion(runId);
   }
+  /** Build a minimal ExpressionContext from run state (for job-level if evaluation). */
+  buildExpressionContext(run) {
+    const ctx = {
+      env: run?.env ?? {},
+      trigger: run?.trigger ?? { type: "manual" },
+      inputs: run?.inputs ?? {},
+      steps: {}
+    };
+    if (run) {
+      for (const j of run.jobs) {
+        for (const s of j.steps) {
+          if (s.status === "success" && s.spec.id) {
+            ctx.steps[s.spec.id] = { outputs: s.outputs ?? {} };
+          }
+        }
+      }
+    }
+    return ctx;
+  }
+  /** Evaluate a job-level `if:` expression. Strips ${{ }} wrapper if present. */
+  evaluateJobIf(condition, ctx) {
+    const raw = condition.trim().replace(/^\$\{\{\s*/, "").replace(/\s*\}\}$/, "");
+    return evaluateExpression(raw, ctx);
+  }
+  /** Mark a job as skipped (success) and release any jobs blocked on it. */
+  async skipJob(runId, job) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    await this.stateStore.updateJob(runId, job.id, (draft) => {
+      draft.status = "success";
+      draft.startedAt = now;
+      draft.finishedAt = now;
+    });
+    this.logger.info("Job skipped: if condition false", { runId, jobId: job.id, condition: job.if });
+    const downstream = await this.stateStore.releaseBlockedJobs(runId, job.jobName);
+    const run = await this.stateStore.getRun(runId);
+    const exprCtx = this.buildExpressionContext(run);
+    for (const downstreamJob of downstream) {
+      if (downstreamJob.if && !this.evaluateJobIf(downstreamJob.if, exprCtx)) {
+        await this.skipJob(runId, downstreamJob);
+      } else {
+        await this.scheduler.enqueueJob(runId, downstreamJob, downstreamJob.priority ?? "normal");
+        this.logger.info("Unblocked dependent job", { runId, jobId: downstreamJob.id, unlockedBy: job.jobName });
+      }
+    }
+  }
   /**
    * Check if all jobs in a run are completed and update run status accordingly.
    */
@@ -947,7 +1038,7 @@ var WorkflowEngine = class {
       return;
     }
     if (allSuccess) {
-      await this.stateStore.updateRun(runId, (draft) => {
+      const updated = await this.stateStore.updateRun(runId, (draft) => {
         draft.status = "success";
         draft.finishedAt = (/* @__PURE__ */ new Date()).toISOString();
         return draft;
@@ -965,10 +1056,24 @@ var WorkflowEngine = class {
         runId,
         payload: { status: "success", name: run.name }
       });
+      if (updated) {
+        await this.snapshotTerminalRun(updated);
+      }
     } else if (anyFailed) {
-      await this.stateStore.updateRun(runId, (draft) => {
+      const failedJob = run.jobs.find((j) => j.status === "failed");
+      const updated = await this.stateStore.updateRun(runId, (draft) => {
         draft.status = "failed";
         draft.finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+        if (failedJob?.error) {
+          draft.result = {
+            status: "failed",
+            summary: `Job ${failedJob.jobName} failed`,
+            error: {
+              message: failedJob.error.message,
+              details: failedJob.error.stack ? { stack: failedJob.error.stack } : void 0
+            }
+          };
+        }
         return draft;
       });
       this.logger.info("Workflow run failed", { runId });
@@ -984,6 +1089,9 @@ var WorkflowEngine = class {
         runId,
         payload: { status: "failed", name: run.name }
       });
+      if (updated) {
+        await this.snapshotTerminalRun(updated);
+      }
     }
   }
   /**
@@ -1215,22 +1323,14 @@ var WorkflowEngine = class {
   /**
    * Move permanently failed job to Dead Letter Queue.
    */
-  async moveToDLQ(runId, jobId, error) {
-    this.logger.warn("Job moved to DLQ after max retries", { runId, jobId });
-    await this.stateStore.updateRun(runId, (draft) => {
-      draft.status = "dlq";
-      draft.result = {
-        status: "dlq",
-        summary: `Job ${jobId} failed after max retries`,
-        error: {
-          message: error.message,
-          details: {
-            stack: error.stack
-          }
-        }
-      };
-      draft.finishedAt = (/* @__PURE__ */ new Date()).toISOString();
-    });
+  /**
+   * Record a dead-letter entry for a job that exhausted its retries. This is an
+   * observability artifact only — it does NOT change the run status. The run
+   * outcome is decided by checkRunCompletion (→ 'failed'). 'dlq' as a run status
+   * is reserved for infrastructure failures and is no longer set here (B-029).
+   */
+  async deadLetterJob(runId, jobId, error) {
+    this.logger.warn("Job dead-lettered after max retries", { runId, jobId });
     const dlqKey = `workflow:dlq:${runId}:${jobId}`;
     const run = await this.stateStore.getRun(runId);
     const job = run?.jobs.find((j) => j.id === jobId);
@@ -1250,10 +1350,6 @@ var WorkflowEngine = class {
       7 * 24 * 60 * 60 * 1e3
       // TTL 7 days
     );
-    const updatedRun = await this.stateStore.getRun(runId);
-    if (updatedRun) {
-      await this.publishRunEvent(EVENT_NAMES.run.failed, updatedRun);
-    }
   }
   async updateRun(runId, mutator) {
     const updated = await this.stateStore.updateRun(runId, mutator);
@@ -1280,9 +1376,41 @@ var WorkflowEngine = class {
         status === "failed" ? EVENT_NAMES.run.failed : status === "cancelled" ? EVENT_NAMES.run.cancelled : EVENT_NAMES.run.finished,
         updated
       );
+      await this.snapshotTerminalRun(updated);
     }
     return updated;
   }
+  /**
+   * Persist a snapshot for a run that just reached a terminal state, so it
+   * can be replayed from any step later (`replayRun`, used by both
+   * `workflow runs restart --from-step` and `rerun --failed-only`). Only
+   * 'success'/'failed' carry meaningful step output data worth snapshotting.
+   *
+   * Shared by finalizeRun() and checkRunCompletion() — checkRunCompletion is
+   * the run-completion path actually driven by the worker in production, so
+   * without this call here, no snapshot is ever created outside of tests
+   * that call finalizeRun() directly (issue #263).
+   */
+  async snapshotTerminalRun(run) {
+    if (run.status !== "success" && run.status !== "failed") {
+      return;
+    }
+    const stepOutputs = {};
+    for (const job of run.jobs) {
+      for (const step of job.steps) {
+        if (step.outputs && Object.keys(step.outputs).length > 0) {
+          stepOutputs[step.id] = step.outputs;
+        }
+      }
+    }
+    await this.snapshotStorage.createSnapshot(run, stepOutputs, run.env ?? {}).catch((err) => {
+      this.logger.error(
+        "Failed to create run snapshot \u2014 restart --from-step and rerun --failed-only will not work for this run",
+        err instanceof Error ? err : new Error(String(err)),
+        { runId: run.id, status: run.status }
+      );
+    });
+  }
   async nextJob() {
     return this.scheduler.dequeueJob();
   }
@@ -1303,13 +1431,13 @@ var WorkflowEngine = class {
   /**
    * Publish a log entry for real-time streaming to Studio UI.
    */
-  async publishLog(runId, jobId, stepId, entry) {
+  async publishLog(runId, jobId, stepId, entry, stepName) {
     await this.events.publish({
       type: EVENT_NAMES.log.appended,
       runId,
       jobId,
       stepId,
-      payload: entry
+      payload: stepName ? { ...entry, stepName } : entry
     });
   }
   /**
@@ -1363,16 +1491,22 @@ var WorkflowEngine = class {
       restoredRun.env = snapshot.env;
     }
     if (options.fromStepId) {
+      const stepExists = restoredRun.jobs.some(
+        (job) => job.steps.some((s) => s.id === options.fromStepId)
+      );
+      if (!stepExists) {
+        throw new Error(`Step not found: ${options.fromStepId}`);
+      }
+    }
+    if (options.fromStepId) {
+      let foundStep = false;
       for (const job of restoredRun.jobs) {
-        let foundStep = false;
         for (const step of job.steps) {
           if (step.id === options.fromStepId) {
             foundStep = true;
-            if (step.status !== "queued") {
-              step.status = "queued";
-              step.startedAt = void 0;
-              step.finishedAt = void 0;
-            }
+            step.status = "queued";
+            step.startedAt = void 0;
+            step.finishedAt = void 0;
             continue;
           }
           if (!foundStep) {
@@ -1396,16 +1530,41 @@ var WorkflowEngine = class {
         }
       }
     }
-    restoredRun.status = "running";
-    restoredRun.startedAt = restoredRun.startedAt ?? (/* @__PURE__ */ new Date()).toISOString();
-    restoredRun.finishedAt = void 0;
-    await this.stateStore.saveRun(restoredRun);
-    await this.scheduler.scheduleRun(restoredRun);
-    this.logger.info("Run replayed from snapshot", {
-      runId,
+    const isJobComplete = (job) => job.steps.every((s) => s.status === "success" || s.status === "skipped");
+    for (const job of restoredRun.jobs) {
+      if (!job.needs || job.needs.length === 0) {
+        job.blocked = false;
+        job.pendingDependencies = [];
+        continue;
+      }
+      const pendingDeps = job.needs.filter((depName) => {
+        const depJob = restoredRun.jobs.find((j) => j.jobName === depName);
+        return depJob !== void 0 && !isJobComplete(depJob);
+      });
+      job.pendingDependencies = pendingDeps;
+      job.blocked = pendingDeps.length > 0;
+    }
+    const newRunId = randomUUID();
+    const newNow = (/* @__PURE__ */ new Date()).toISOString();
+    const newRun = {
+      ...restoredRun,
+      id: newRunId,
+      status: "queued",
+      createdAt: newNow,
+      queuedAt: newNow,
+      startedAt: void 0,
+      finishedAt: void 0,
+      durationMs: void 0,
+      result: void 0
+    };
+    await this.stateStore.saveRun(newRun);
+    await this.scheduler.scheduleRun(newRun);
+    this.logger.info("Run replayed as new run from snapshot", {
+      originalRunId: runId,
+      newRunId,
       fromStepId: options.fromStepId
     });
-    return restoredRun;
+    return newRun;
   }
   /**
    * Delete a snapshot
@@ -1688,11 +1847,82 @@ var ArtifactMerger = class {
   }
 };
 
+// src/manifest-converter.ts
+var ManifestConverter = class {
+  convertWorkflowHandler(pluginId, handler, pluginRoot) {
+    const id = `${pluginId}/${handler.id}`;
+    return {
+      kind: "workflow",
+      id,
+      source: "manifest",
+      pluginId,
+      manifestPath: pluginRoot,
+      name: handler.describe ?? handler.id,
+      description: handler.describe,
+      tags: ["plugin", pluginId],
+      triggers: [{ type: "manual" }],
+      handler: handler.handler,
+      status: "active",
+      permissions: handler.permissions,
+      input: handler.input,
+      output: handler.output
+    };
+  }
+  convertJobHandler(pluginId, handler, pluginRoot) {
+    const id = `${pluginId}:job:${handler.id}`;
+    return {
+      kind: "job",
+      id,
+      source: "manifest",
+      pluginId,
+      manifestPath: pluginRoot,
+      name: handler.describe ?? handler.id,
+      description: handler.describe,
+      tags: ["plugin", "job", pluginId],
+      triggers: [{ type: "manual" }],
+      handler: handler.handler,
+      status: "active",
+      permissions: handler.permissions,
+      input: handler.input,
+      output: handler.output
+    };
+  }
+  convertCronSchedule(pluginId, cronDecl, pluginRoot) {
+    const id = `${pluginId}:cron:${cronDecl.id}`;
+    const schedule = {
+      cron: cronDecl.schedule,
+      enabled: cronDecl.enabled ?? true
+    };
+    return {
+      kind: "cron",
+      id,
+      source: "manifest",
+      pluginId,
+      manifestPath: pluginRoot,
+      name: cronDecl.describe ?? cronDecl.id,
+      description: cronDecl.describe,
+      tags: ["plugin", "cron", pluginId],
+      triggers: [
+        {
+          type: "schedule",
+          config: { cron: cronDecl.schedule, timezone: cronDecl.timezone }
+        }
+      ],
+      handler: void 0,
+      schedule,
+      status: cronDecl.enabled ?? true ? "active" : "disabled",
+      permissions: cronDecl.permissions
+    };
+  }
+};
+
 // src/manifest-scanner.ts
+var CACHE_KEY_WORKFLOWS = "manifest-scanner:v1:workflows";
 var ManifestScanner = class {
   cliApi;
   platform;
   cacheTtlMs;
+  converter = new ManifestConverter();
   constructor(options) {
     this.cliApi = options.cliApi;
     this.platform = options.platform;
@@ -1700,13 +1930,14 @@ var ManifestScanner = class {
   }
   /**
    * Scan all installed plugins for workflows and jobs.
+   * Purpose: listing — populates the REST API GET /api/v1/workflows catalog.
+   * (CronDiscovery in daemon handles scheduling — different output, different consumer.)
    *
    * Returns unified WorkflowRuntime representations.
    */
   async scanPlugins() {
-    const cacheKey = "manifest-scanner:workflows";
     if (this.platform.cache) {
-      const cached = await this.platform.cache.get(cacheKey);
+      const cached = await this.platform.cache.get(CACHE_KEY_WORKFLOWS);
       if (cached) {
         this.platform.logger?.debug("ManifestScanner: Using cached workflows", { count: cached.length });
         return cached;
@@ -1738,11 +1969,11 @@ var ManifestScanner = class {
       }
       try {
         if (converter === "workflow") {
-          workflows.push(this.convertWorkflowHandler(entity.ref.pluginId, entity.declaration, root));
+          workflows.push(this.converter.convertWorkflowHandler(entity.ref.pluginId, entity.declaration, root));
         } else if (converter === "job") {
-          workflows.push(this.convertJobHandler(entity.ref.pluginId, entity.declaration, root));
+          workflows.push(this.converter.convertJobHandler(entity.ref.pluginId, entity.declaration, root));
         } else {
-          workflows.push(this.convertCronSchedule(entity.ref.pluginId, entity.declaration, root));
+          workflows.push(this.converter.convertCronSchedule(entity.ref.pluginId, entity.declaration, root));
         }
       } catch (err) {
         this.platform.logger?.warn("ManifestScanner: Failed to convert entity", {
@@ -1781,91 +2012,10 @@ var ManifestScanner = class {
       templates: templatesCount
     });
     if (this.platform.cache) {
-      await this.platform.cache.set(cacheKey, workflows, this.cacheTtlMs);
+      await this.platform.cache.set(CACHE_KEY_WORKFLOWS, workflows, this.cacheTtlMs);
     }
     return workflows;
   }
-  /**
-   * Convert workflow handler declaration to WorkflowRuntime.
-   */
-  convertWorkflowHandler(pluginId, handler, pluginRoot) {
-    const id = `${pluginId}/${handler.id}`;
-    return {
-      id,
-      source: "manifest",
-      pluginId,
-      manifestPath: pluginRoot,
-      name: handler.describe ?? handler.id,
-      description: handler.describe,
-      tags: ["plugin", pluginId],
-      triggers: [
-        { type: "manual" }
-        // Workflow handlers can always be triggered manually
-      ],
-      handler: handler.handler,
-      status: "active",
-      permissions: handler.permissions,
-      input: handler.input,
-      output: handler.output
-    };
-  }
-  /**
-   * Convert job handler declaration to WorkflowRuntime.
-   */
-  convertJobHandler(pluginId, handler, pluginRoot) {
-    const id = `${pluginId}:job:${handler.id}`;
-    return {
-      id,
-      source: "manifest",
-      pluginId,
-      manifestPath: pluginRoot,
-      name: handler.describe ?? handler.id,
-      description: handler.describe,
-      tags: ["plugin", "job", pluginId],
-      triggers: [
-        { type: "manual" }
-        // Job handlers are invoked on-demand via ctx.api.jobs.submit()
-      ],
-      handler: handler.handler,
-      status: "active",
-      permissions: handler.permissions,
-      input: handler.input,
-      output: handler.output
-    };
-  }
-  /**
-   * Convert cron schedule declaration to WorkflowRuntime.
-   */
-  convertCronSchedule(pluginId, cronDecl, pluginRoot) {
-    const id = `${pluginId}:cron:${cronDecl.id}`;
-    const schedule = {
-      cron: cronDecl.schedule,
-      enabled: cronDecl.enabled ?? true
-    };
-    return {
-      id,
-      source: "manifest",
-      pluginId,
-      manifestPath: pluginRoot,
-      name: cronDecl.describe ?? cronDecl.id,
-      description: cronDecl.describe,
-      tags: ["plugin", "cron", pluginId],
-      triggers: [
-        {
-          type: "schedule",
-          config: { cron: cronDecl.schedule, timezone: cronDecl.timezone }
-        }
-      ],
-      // Note: Cron schedules reference a job type to execute
-      // The actual handler path comes from the job declaration
-      handler: void 0,
-      // Will be resolved at execution time via job type
-      schedule,
-      status: cronDecl.enabled ?? true ? "active" : "disabled",
-      permissions: cronDecl.permissions
-    };
-  }
-  // Legacy convertLegacyJob method removed - use cron schedules instead
   /**
    * Scan all installed plugins for job handlers only.
    *
@@ -1895,7 +2045,7 @@ var ManifestScanner = class {
    */
   async clearCache() {
     if (this.platform.cache) {
-      await this.platform.cache.delete("manifest-scanner:workflows");
+      await this.platform.cache.delete(CACHE_KEY_WORKFLOWS);
       this.platform.logger?.debug("ManifestScanner: Cache cleared");
     }
   }
@@ -2007,7 +2157,10 @@ var WorkflowRepository = class {
    * Delete workflow.
    */
   async delete(id) {
-    const path = this.getWorkflowPath(id);
+    const path = await this.getWorkflowPath(id);
+    if (!path) {
+      throw new Error(`Invalid workflow ID for deletion: ${id}`);
+    }
     try {
       await this.platform.storage.delete(path);
       this.platform.logger?.info("WorkflowRepository: Deleted workflow", { id });
@@ -2078,21 +2231,22 @@ var WorkflowRepository = class {
       status
     });
   }
-  getWorkflowPath(id) {
+  async getWorkflowPath(id) {
+    if (id.includes("/") || id.includes("\\") || id.includes("..") || id.startsWith(".")) {
+      return null;
+    }
     const ymlPath = join(this.absoluteStorageDir, `${id}.yml`);
     const yamlPath = join(this.absoluteStorageDir, `${id}.yaml`);
-    if (existsSync(ymlPath)) {
-      return ymlPath;
-    }
-    return yamlPath;
+    return access(ymlPath).then(() => ymlPath).catch(() => yamlPath);
   }
   async saveWorkflow(id, workflow) {
-    const path = this.getWorkflowPath(id);
+    const path = await this.getWorkflowPath(id);
+    if (!path) {
+      throw new Error(`Invalid workflow ID for storage: ${id}`);
+    }
     const yaml = stringify(workflow, { indent: 2 });
     try {
-      if (!existsSync(this.absoluteStorageDir)) {
-        await mkdir(this.absoluteStorageDir, { recursive: true });
-      }
+      await mkdir(this.absoluteStorageDir, { recursive: true });
       await writeFile(path, yaml, "utf-8");
     } catch (error) {
       this.platform.logger?.error(
@@ -2104,17 +2258,17 @@ var WorkflowRepository = class {
     }
   }
   async loadWorkflow(id) {
-    const path = this.getWorkflowPath(id);
+    const path = await this.getWorkflowPath(id);
+    if (!path) {
+      return null;
+    }
     try {
-      if (!existsSync(path)) {
-        return null;
-      }
       const content = await readFile(path, "utf-8");
       const parsed = parse(content);
       if (parsed.id && parsed.spec && parsed.createdAt) {
-        return parsed;
+        return { ...parsed, id };
       }
-      const spec = {
+      const candidateSpec = {
         name: parsed.name,
         version: parsed.version || "1.0.0",
         description: parsed.description,
@@ -2125,8 +2279,20 @@ var WorkflowRepository = class {
         env: parsed.env,
         secrets: parsed.secrets
       };
+      const validation = WorkflowSpecSchema.safeParse(candidateSpec);
+      if (!validation.success) {
+        this.platform.logger?.warn(
+          `WorkflowRepository: skipping invalid workflow "${id}" \u2014 ${validation.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`,
+          { id, path }
+        );
+        return null;
+      }
+      const spec = validation.data;
       const stored = {
-        id: parsed.id || id,
+        // The filename is the canonical id for file-based workflows. Using the
+        // inner `id:` here made list() report an id that get()/getWorkflowPath()
+        // (which resolve by filename) could not find → POST /runs 404 (B-016).
+        id,
         spec,
         createdAt: (/* @__PURE__ */ new Date()).toISOString(),
         updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2147,9 +2313,6 @@ var WorkflowRepository = class {
   }
   async listWorkflowFiles() {
     try {
-      if (!existsSync(this.absoluteStorageDir)) {
-        return [];
-      }
       const files = await readdir(this.absoluteStorageDir);
       return files.filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
     } catch (error) {
@@ -2212,7 +2375,9 @@ var WorkflowRepository = class {
       // Store full spec for execution
       input: spec,
       // Expose declared input schema for REST API / Studio UI
-      inputSchema: spec.inputs
+      inputSchema: spec.inputs,
+      version: spec.version,
+      updatedAt: stored.updatedAt
     };
   }
 };
@@ -2265,15 +2430,30 @@ var WorkflowService = class {
   }
   /**
    * Get workflow by ID (from either source).
+   *
+   * Lookup order:
+   * 1. Standalone by filename-derived id (canonical, fast path)
+   * 2. Standalone by `name:` field — allows `--workflow-id=dev-cycle` even
+   *    when the file is named `03-dev-cycle.yml` (F8 ergonomics fix)
+   * 3. Manifest-based by id
+   * 4. Manifest-based by name field
    */
   async get(id) {
     const standalone = await this.repository.get(id);
     if (standalone) {
       return standalone;
     }
+    const allStandalone = await this.repository.list();
+    const byName = allStandalone.find((w) => w.name === id);
+    if (byName) {
+      return byName;
+    }
     const manifestWorkflows = await this.scanner.scanPlugins();
     const manifest = manifestWorkflows.find((w) => w.id === id);
-    return manifest ?? null;
+    if (manifest) {
+      return manifest;
+    }
+    return manifestWorkflows.find((w) => w.name === id) ?? null;
   }
   /**
    * Create standalone workflow.
@@ -2417,163 +2597,6 @@ var WorkflowService = class {
     this.platform.logger?.info("WorkflowService: Manifest cache cleared");
   }
 };
-
-// src/workflow-schedule-manager.ts
-var WorkflowScheduleManager = class {
-  cronManager;
-  workflowService;
-  executor;
-  platform;
-  constructor(options) {
-    this.cronManager = options.cronManager;
-    this.workflowService = options.workflowService;
-    this.executor = options.executor;
-    this.platform = options.platform;
-  }
-  /**
-   * Register all scheduled workflows with CronManager.
-   *
-   * Scans both manifest-based jobs and standalone workflows with schedules.
-   */
-  async registerAll() {
-    const workflows = await this.workflowService.listAll();
-    const scheduled = workflows.filter(
-      (w) => w.schedule && w.schedule.enabled && w.status === "active"
-    );
-    this.platform.logger?.info("WorkflowScheduleManager: Registering scheduled workflows", {
-      total: workflows.length,
-      scheduled: scheduled.length
-    });
-    await Promise.all(scheduled.map((workflow) => this.register(workflow)));
-  }
-  /**
-   * Register single workflow schedule.
-   */
-  async register(workflow) {
-    if (!workflow.schedule || !workflow.schedule.enabled) {
-      this.platform.logger?.warn("WorkflowScheduleManager: Cannot register workflow without schedule", {
-        id: workflow.id
-      });
-      return;
-    }
-    const cronId = this.getCronId(workflow.id);
-    const schedule = workflow.schedule.cron;
-    this.cronManager.register(cronId, schedule, async (context) => {
-      this.platform.logger?.info("WorkflowScheduleManager: Executing scheduled workflow", {
-        workflowId: workflow.id,
-        workflowName: workflow.name,
-        runCount: context.runCount
-      });
-      try {
-        const result = await this.executor.execute({
-          workflowId: workflow.id,
-          trigger: "schedule",
-          input: {}
-        });
-        this.platform.logger?.info("WorkflowScheduleManager: Workflow execution started", {
-          workflowId: workflow.id,
-          runId: result.runId
-        });
-      } catch (error) {
-        this.platform.logger?.error(
-          "WorkflowScheduleManager: Workflow execution failed",
-          error instanceof Error ? error : void 0,
-          {
-            workflowId: workflow.id,
-            workflowName: workflow.name
-          }
-        );
-      }
-    });
-    this.platform.logger?.debug("WorkflowScheduleManager: Registered workflow", {
-      workflowId: workflow.id,
-      schedule
-    });
-  }
-  /**
-   * Unregister workflow schedule.
-   */
-  async unregister(workflowId) {
-    const cronId = this.getCronId(workflowId);
-    this.cronManager.unregister(cronId);
-    this.platform.logger?.debug("WorkflowScheduleManager: Unregistered workflow", {
-      workflowId
-    });
-  }
-  /**
-   * Re-register all schedules (refresh).
-   *
-   * Useful after workflow changes or service restart.
-   */
-  async refresh() {
-    const allJobs = this.cronManager.list();
-    for (const job of allJobs) {
-      if (job.id.startsWith("workflow:")) {
-        this.cronManager.unregister(job.id);
-      }
-    }
-    await this.registerAll();
-    this.platform.logger?.info("WorkflowScheduleManager: Refreshed all schedules");
-  }
-  /**
-   * Get next run time for scheduled workflow.
-   */
-  getNextRun(workflowId) {
-    const cronId = this.getCronId(workflowId);
-    const job = this.cronManager.list().find((j) => j.id === cronId);
-    return job?.nextRun ?? null;
-  }
-  /**
-   * Get last run time for scheduled workflow.
-   */
-  getLastRun(workflowId) {
-    const cronId = this.getCronId(workflowId);
-    const job = this.cronManager.list().find((j) => j.id === cronId);
-    return job?.lastRun ?? null;
-  }
-  /**
-   * Pause scheduled workflow.
-   */
-  pause(workflowId) {
-    const cronId = this.getCronId(workflowId);
-    this.cronManager.pause(cronId);
-    this.platform.logger?.info("WorkflowScheduleManager: Paused workflow schedule", {
-      workflowId
-    });
-  }
-  /**
-   * Resume paused workflow schedule.
-   */
-  resume(workflowId) {
-    const cronId = this.getCronId(workflowId);
-    this.cronManager.resume(cronId);
-    this.platform.logger?.info("WorkflowScheduleManager: Resumed workflow schedule", {
-      workflowId
-    });
-  }
-  /**
-   * List all scheduled workflows.
-   */
-  listScheduled() {
-    return this.cronManager.list().filter((job) => job.id.startsWith("workflow:")).map((job) => ({
-      workflowId: this.getWorkflowId(job.id),
-      schedule: job.schedule,
-      status: job.status,
-      lastRun: job.lastRun,
-      nextRun: job.nextRun,
-      runCount: job.runCount
-    }));
-  }
-  // ============================================================================
-  // Private helpers
-  // ============================================================================
-  getCronId(workflowId) {
-    return `workflow:${workflowId}`;
-  }
-  getWorkflowId(cronId) {
-    return cronId.replace("workflow:", "");
-  }
-};
 var WorkflowRegistry = class {
   constructor(options) {
     this.options = options;
@@ -3121,6 +3144,6 @@ var JobManager = class {
   }
 };
 
-export { ArtifactMerger, ConcurrencyManager, EnvSecretProvider, EventBusBridge, JobManager, ManifestScanner, RunCoordinator, RunSnapshotStorage, Scheduler, StateStore, WorkflowEngine, WorkflowLoader, WorkflowRegistry, WorkflowRepository, WorkflowScheduleManager, WorkflowService, calculateBackoff, createDefaultSecretProvider, shouldRetry };
+export { ArtifactMerger, ConcurrencyManager, EnvSecretProvider, EventBusBridge, JobManager, ManifestConverter, ManifestScanner, RunCoordinator, RunSnapshotStorage, Scheduler, StateStore, WorkflowEngine, WorkflowLoader, WorkflowRegistry, WorkflowRepository, WorkflowService, calculateBackoff, createDefaultSecretProvider, shouldRetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map