@redflow/client 0.0.3 → 0.0.4

package/INTERNALS.md

@@ -0,0 +1,238 @@
+# redflow internals
+
+This document describes how `@redflow/client` works internally in production terms.
+
+## Design model
+
+- Durable state lives in Redis.
+- Handlers and workflow code live in process memory (per worker process).
+- The runtime is queue-based and crash-recoverable.
+- Delivery semantics are at-least-once at run level.
+- Step API provides deterministic replay/caching to avoid repeating completed work.
+
+## Main components
+
+- **Workflow registry (in-memory):** built via `defineWorkflow(...)`.
+- **Client (`RedflowClient`):** enqueue runs, inspect state, cancel runs, sync metadata.
+- **Worker runtime:** executes queued runs, retries failures, promotes scheduled runs.
+- **Cron scheduler:** leader-elected loop that creates cron runs.
+
+## Registry and metadata sync
+
+`startWorker({ app, ... })` always calls `syncRegistry(registry, { app })` before loops start.
+
+What `syncRegistry` writes per workflow:
+
+- `workflow:<name>` hash:
+  - `name`
+  - `queue`
+  - `maxConcurrency` (default `1`)
+  - `app` (required ownership scope for cleanup)
+  - `updatedAt`
+  - `cronJson`
+  - `retriesJson`
+  - `cronIdsJson`
+- `workflows` set (all known workflow names)
+- cron definitions in `cron:def` and schedule in `cron:next`
+
+### Stale cleanup
+
+Before writing new metadata, sync removes stale workflow metadata when all are true:
+
+- workflow exists in Redis,
+- workflow is missing in current registry,
+- workflow `app` equals current `app`,
+- workflow is older than grace period (`30s`).
+
+Cleanup removes:
+
+- `workflow:<name>` metadata hash,
+- `workflows` set membership,
+- associated cron entries (`cron:def`, `cron:next`).
+
+It does **not** delete historical runs.
+
+## Redis keyspace
+
+Key builders are in `src/internal/keys.ts`.
+
+- `workflows`
+- `workflow:<name>`
+- `workflow-runs:<name>`
+- `runs:created`
+- `runs:status:<status>`
+- `run:<runId>`
+- `run:<runId>:steps`
+- `run:<runId>:lease`
+- `q:<queue>:ready`
+- `q:<queue>:processing`
+- `q:<queue>:scheduled`
+- `cron:def`
+- `cron:next`
+- `lock:cron`
+- `idempo:<encodedWorkflow>:<encodedKey>`
+
+## Run lifecycle
+
+Statuses:
+
+- `scheduled`
+- `queued`
+- `running`
+- terminal: `succeeded`, `failed`, `canceled`
+
+### Enqueue
+
+Enqueue uses `ENQUEUE_RUN_LUA` atomically:
+
+- creates run hash,
+- writes indexes (`runs:created`, `runs:status:*`, `workflow-runs:*`),
+- pushes to ready queue or scheduled ZSET,
+- applies idempotency mapping if key was provided.
+
+Idempotency key TTL defaults to `7 days`.
+
+### Processing
+
+Worker loop uses `LMOVE`/`BLMOVE` from `ready` -> `processing`.
+
+For each claimed run:
+
+1. Acquire lease (`run:<id>:lease`) with periodic renewal.
+2. Validate current run status.
+3. If `queued`, enforce `maxConcurrency` for that workflow.
+4. Transition `queued -> running` atomically.
+5. Execute handler with step engine.
+6. Finalize to terminal status atomically.
+7. Remove from `processing`.
+
+If lease is lost, current worker aborts and does not finalize.
+
+### Reaper
+
+Reaper scans `processing` lists. For runs without active lease:
+
+- removes from `processing`,
+- pushes back to `ready`.
+
+This recovers from worker crashes.
+
+### Scheduled promoter
+
+Promoter pops due items from `q:<queue>:scheduled` (`ZPOPMIN` batch), then:
+
+- transitions `scheduled -> queued`,
+- pushes to `ready`.
+
+Future items are put back.
+
+## maxConcurrency
+
+`maxConcurrency` is per workflow, default `1`.
+
+### For regular queued runs
+
+When a worker picks a `queued` run:
+
+- it counts current `running` runs for the same workflow,
+- if count >= `maxConcurrency`, run is atomically moved from `processing` back to end of `ready`.
+
+So non-cron runs are delayed (not dropped).
+
+### For cron runs
+
+Cron loop also checks running count before enqueue.
+
+- if count >= `maxConcurrency`, that cron tick is skipped,
+- next cron tick is still scheduled normally.
+
+## Cron scheduler
+
+- Leader election via Redis lock `lock:cron`.
+- Only lock holder schedules cron runs.
+- Loop pops earliest `cronId` from `cron:next`.
+- If due:
+  - parses `cron:def` payload,
+  - enforces `maxConcurrency`,
+  - enqueues run via `runByName` (or skips),
+  - computes next fire time and stores in `cron:next`.
+
+Cron uses "reschedule from now" behavior (no catch-up burst if stale timestamp was in the past).
+
+## Step engine semantics
+
+Inside handler, `step` API has three primitives.
+
+### `step.run(...)`
+
+- Step state is persisted in `run:<id>:steps` hash under `step.name`.
+- If step already `succeeded`, cached output is returned.
+- Duplicate step names in one execution are rejected.
+- Step timeout and cancellation are supported.
+
+### `step.runWorkflow(...)`
+
+- Enqueues child workflow with deterministic idempotency by default:
+  - `parentRunId + stepName + childWorkflowName`.
+- Waits for child completion.
+- Waiting is bounded by step `timeoutMs` (if set), otherwise unbounded until cancellation.
+- Inline assist: if child is queued on a queue this worker handles, worker may execute child inline to avoid self-deadlock with low concurrency.
+
+### `step.emitWorkflow(...)`
+
+- Enqueues child workflow and returns child `runId`.
+- Supports child as workflow object or workflow name string.
+- Uses deterministic idempotency default based on parent run and step name.
+
+## Retry model
+
+- `maxAttempts` is workflow-level (`retries.maxAttempts`), default `1`.
+- Retry delay uses exponential backoff + jitter.
+- Non-retryable classes:
+  - input validation errors,
+  - unknown workflow,
+  - output serialization errors,
+  - cancellation,
+  - explicit `NonRetriableError`.
+- Retry scheduling is atomic (`scheduleRetry` Lua): status/index update + queue scheduled ZSET write in one script.
+
+## Cancellation
+
+`cancelRun(runId)`:
+
+- sets `cancelRequestedAt` + optional reason,
+- if run is `queued`/`scheduled`, attempts immediate transition to `canceled` and cleanup,
+- if run is `running`, cancellation is cooperative via `AbortSignal` polling in worker.
+
+Terminal finalize script ensures consistent indexes and terminal status.
+
+## Idempotency vs step cache
+
+- **Idempotency:** deduplicates run creation (`key -> runId`) with TTL.
+- **Step cache:** deduplicates completed step execution within one parent run.
+
+They solve different failure windows and are intentionally both used.
+
+## Multi-worker behavior
+
+- Many workers can process same prefix/queues.
+- Cron scheduling is single-leader.
+- Processing/recovery is shared via Redis lists + leases.
+- `maxConcurrency` is enforced globally against Redis `running` index.
+
+## Operational notes
+
+Recommended for production:
+
+- Use stable `prefix` per environment.
+- Use explicit `app` per service role for safe metadata cleanup.
+- Set `maxConcurrency` intentionally for long workflows.
+- Keep queue ownership clear (avoid workers consuming queues for workflows they do not register).
+- Use idempotency keys for external trigger endpoints.
+
+## Current guarantees and limitations
+
+- Run execution is at-least-once.
+- Step cache reduces replay but cannot provide global exactly-once side effects.
+- `maxConcurrency` is enforced via runtime checks against Redis state; it is robust in practice but not a strict distributed semaphore proof.
+- `handle.result({ timeoutMs })` timeout affects caller waiting only, not run execution itself.

package/README.md

@@ -2,6 +2,8 @@
 
 Redis-backed workflow runtime for Bun.
 
+Deep internal details: `INTERNALS.md`
+
 ## Warning
 
 This project is still in early alpha stage.
@@ -147,13 +149,14 @@ const output = await handle.result({ timeoutMs: 90_000 });
 
 ## Start a worker
 
-Import workflows, then run `startWorker()`.
+Import workflows, then run `startWorker({ app: ... })`.
 
 ```ts
 import { startWorker } from "@redflow/client";
 import "./workflows";
 
 const worker = await startWorker({
+  app: "billing-worker",
   url: process.env.REDIS_URL,
   prefix: "redflow:prod",
   concurrency: 4,
@@ -164,6 +167,7 @@ Explicit queues + runtime tuning:
 
 ```ts
 const worker = await startWorker({
+  app: "billing-worker",
   url: process.env.REDIS_URL,
   prefix: "redflow:prod",
   queues: ["critical", "io", "analytics"],
@@ -178,6 +182,21 @@ const worker = await startWorker({
 
 ## Workflow options examples
 
+### maxConcurrency
+
+`maxConcurrency` limits concurrent `running` runs per workflow. Default is `1`.
+
+```ts
+defineWorkflow(
+  "heavy-sync",
+  {
+    queue: "ops",
+    maxConcurrency: 1,
+  },
+  async () => ({ ok: true }),
+);
+```
+
 ### Cron
 
 ```ts
@@ -194,6 +213,8 @@ defineWorkflow(
 );
 ```
 
+Cron respects `maxConcurrency`: if the limit is reached, that cron tick is skipped.
+
 ### onFailure
 
 ```ts
@@ -281,10 +302,10 @@ const output = await handle.result({ timeoutMs: 30_000 });
 console.log(output);
 ```
 
-### Registry sync ownership
+### Registry sync app id
 
 ```ts
 import { getDefaultRegistry } from "@redflow/client";
 
-await client.syncRegistry(getDefaultRegistry(), { owner: "billing-service" });
+await client.syncRegistry(getDefaultRegistry(), { app: "billing-service" });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redflow/client",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "main": "src/index.ts",
   "module": "src/index.ts",

package/src/client.ts

@@ -37,10 +37,10 @@ export type CreateClientOptions = {
 
 export type SyncRegistryOptions = {
   /**
-   * Workflows are pruned only when they were last synced by the same owner.
-   * Set a stable service id (for example, app name) to enable safe stale cleanup.
+   * Stable application id used for stale workflow metadata cleanup.
+   * Workflows are pruned only when they were last synced by the same app.
    */
-  owner?: string;
+  app: string;
 };
 
 export function defaultPrefix(): string {
@@ -249,16 +249,6 @@ function encodeCompositePart(value: string): string {
   return `${value.length}:${value}`;
 }
 
-function defaultRegistryOwner(): string {
-  const envOwner = process.env.REDFLOW_SYNC_OWNER?.trim();
-  if (envOwner) return envOwner;
-
-  const argvOwner = process.argv[1]?.trim();
-  if (argvOwner) return argvOwner;
-
-  return "redflow:unknown-owner";
-}
-
 function parseEnqueueScriptResult(value: unknown): { kind: "created" | "existing"; runId: string } | null {
   if (Array.isArray(value) && value.length === 1 && Array.isArray(value[0])) {
     return parseEnqueueScriptResult(value[0]);
@@ -309,6 +299,11 @@ function isValidDate(value: Date): boolean {
   return value instanceof Date && Number.isFinite(value.getTime());
 }
 
+function normalizeMaxConcurrency(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return 1;
+  return Math.floor(value);
+}
+
 export class RedflowClient {
   constructor(
     public readonly redis: RedisClient,
@@ -356,9 +351,11 @@ export class RedflowClient {
     const retries = safeJsonTryParse<any>(data.retriesJson ?? null) as any;
     const updatedAt = Number(data.updatedAt ?? "0");
     const queue = data.queue ?? "default";
+    const maxConcurrency = normalizeMaxConcurrency(Number(data.maxConcurrency ?? "1"));
     return {
       name,
       queue,
+      maxConcurrency,
       cron: Array.isArray(cron) && cron.length > 0 ? cron : undefined,
       retries,
       updatedAt,
@@ -606,17 +603,21 @@ export class RedflowClient {
     }
   }
 
-  async syncRegistry(registry: WorkflowRegistry, options?: SyncRegistryOptions): Promise<void> {
+  async syncRegistry(registry: WorkflowRegistry, options: SyncRegistryOptions): Promise<void> {
     const defs = registry.list();
     const syncStartedAt = nowMs();
-    const owner = options?.owner?.trim() || defaultRegistryOwner();
+    const app = options.app.trim();
+    if (!app) {
+      throw new Error("syncRegistry requires a non-empty options.app");
+    }
     const registeredNames = new Set(defs.map((def) => def.options.name));
 
-    await this.cleanupStaleWorkflows(registeredNames, syncStartedAt, owner);
+    await this.cleanupStaleWorkflows(registeredNames, syncStartedAt, app);
 
     for (const def of defs) {
       const name = def.options.name;
       const queue = def.options.queue ?? "default";
+      const maxConcurrency = normalizeMaxConcurrency(def.options.maxConcurrency);
       const cron = def.options.cron ?? [];
       const retries = def.options.retries ?? {};
       const updatedAt = nowMs();
@@ -653,6 +654,7 @@ export class RedflowClient {
           id: cronId,
           workflow: name,
           queue,
+          maxConcurrency,
           expression: c.expression,
           timezone: c.timezone,
           inputJson: safeJsonStringify(cronInput),
@@ -671,7 +673,8 @@ export class RedflowClient {
       const meta: Record<string, string> = {
         name,
         queue,
-        owner,
+        maxConcurrency: String(maxConcurrency),
+        app,
         updatedAt: String(updatedAt),
         cronJson: safeJsonStringify(cron),
         retriesJson: safeJsonStringify(retries),
@@ -722,7 +725,7 @@ export class RedflowClient {
   private async cleanupStaleWorkflows(
     registeredNames: Set<string>,
     syncStartedAt: number,
-    owner: string,
+    app: string,
   ): Promise<void> {
     const existingNames = await this.redis.smembers(keys.workflows(this.prefix));
 
@@ -730,8 +733,8 @@ export class RedflowClient {
       if (registeredNames.has(existingName)) continue;
 
       const workflowKey = keys.workflow(this.prefix, existingName);
-      const workflowOwner = (await this.redis.hget(workflowKey, "owner")) ?? "";
-      if (!workflowOwner || workflowOwner !== owner) {
+      const workflowApp = (await this.redis.hget(workflowKey, "app")) ?? "";
+      if (!workflowApp || workflowApp !== app) {
         continue;
       }
 

package/src/types.ts

@@ -32,6 +32,11 @@ export type OnFailureContext = {
 export type DefineWorkflowOptions<TSchema extends ZodTypeAny | undefined = ZodTypeAny | undefined> = {
   name: string;
   queue?: string;
+  /**
+   * Maximum concurrently running runs for this workflow.
+   * Default: 1.
+   */
+  maxConcurrency?: number;
   schema?: TSchema;
   cron?: CronTrigger[];
   retries?: WorkflowRetries;
@@ -167,6 +172,7 @@ export type ListedRun = {
 export type WorkflowMeta = {
   name: string;
   queue: string;
+  maxConcurrency: number;
   cron?: CronTrigger[];
   retries?: WorkflowRetries;
   updatedAt: number;

package/src/worker.ts

@@ -19,6 +19,8 @@ import { getDefaultRegistry, type WorkflowRegistry } from "./registry";
 import type { OnFailureContext, RunStatus, StepApi, StepStatus } from "./types";
 
 export type StartWorkerOptions = {
+  /** Stable application id used for registry sync stale-cleanup scoping. */
+  app: string;
   redis?: RedisClient;
   url?: string;
   prefix?: string;
@@ -74,18 +76,32 @@ redis.call("lpush", KEYS[2], ARGV[1])
 return 1
 `;
 
-export async function startWorker(options?: StartWorkerOptions): Promise<WorkerHandle> {
-  const registry = options?.registry ?? getDefaultRegistry();
-  const prefix = options?.prefix ?? defaultPrefix();
-  const ownsBaseRedis = !options?.redis && !!options?.url;
-  const baseRedis = options?.redis ?? (options?.url ? new BunRedisClient(options.url) : defaultRedis);
+const REQUEUE_DUE_TO_CONCURRENCY_LUA = `
+if redis.call("lrem", KEYS[1], 1, ARGV[1]) <= 0 then
+  return 0
+end
+
+redis.call("rpush", KEYS[2], ARGV[1])
+return 1
+`;
+
+export async function startWorker(options: StartWorkerOptions): Promise<WorkerHandle> {
+  const app = options.app.trim();
+  if (!app) {
+    throw new Error("startWorker requires a non-empty options.app");
+  }
+
+  const registry = options.registry ?? getDefaultRegistry();
+  const prefix = options.prefix ?? defaultPrefix();
+  const ownsBaseRedis = !options.redis && !!options.url;
+  const baseRedis = options.redis ?? (options.url ? new BunRedisClient(options.url) : defaultRedis);
   const syncClient = createClient({ redis: baseRedis, prefix });
 
-  const queues = options?.queues ?? deriveQueuesFromRegistry(registry);
-  const concurrency = Math.max(1, options?.concurrency ?? 1);
-  const leaseMs = Math.max(100, options?.runtime?.leaseMs ?? 5000);
-  const blmoveTimeoutSec = options?.runtime?.blmoveTimeoutSec ?? 1;
-  const reaperIntervalMs = options?.runtime?.reaperIntervalMs ?? 500;
+  const queues = options.queues ?? deriveQueuesFromRegistry(registry);
+  const concurrency = Math.max(1, options.concurrency ?? 1);
+  const leaseMs = Math.max(100, options.runtime?.leaseMs ?? 5000);
+  const blmoveTimeoutSec = options.runtime?.blmoveTimeoutSec ?? 1;
+  const reaperIntervalMs = options.runtime?.reaperIntervalMs ?? 500;
 
   const abort = new AbortController();
   const tasks: Promise<void>[] = [];
@@ -111,7 +127,7 @@ export async function startWorker(options?: StartWorkerOptions): Promise<WorkerH
   };
 
   try {
-    await syncClient.syncRegistry(registry);
+    await syncClient.syncRegistry(registry, { app });
 
     // Worker loops (blocking BLMOVE). Use dedicated connections per slot.
     for (let i = 0; i < concurrency; i++) {
@@ -222,6 +238,11 @@ function encodeIdempotencyPart(value: string): string {
   return `${value.length}:${value}`;
 }
 
+function normalizeMaxConcurrency(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return 1;
+  return Math.floor(value);
+}
+
 function defaultStepWorkflowIdempotencyKey(parentRunId: string, stepName: string, childWorkflowName: string): string {
   return `stepwf:${encodeIdempotencyPart(parentRunId)}:${encodeIdempotencyPart(stepName)}:${encodeIdempotencyPart(childWorkflowName)}`;
 }
@@ -396,6 +417,8 @@ async function processRun(args: {
     }
 
     const workflowName = run.workflow ?? "";
+    const def = workflowName ? registry.get(workflowName) : undefined;
+    const maxConcurrency = normalizeMaxConcurrency(def?.options.maxConcurrency);
     const maxAttempts = Number(run.maxAttempts ?? "1");
     const cancelRequestedAt = run.cancelRequestedAt ? Number(run.cancelRequestedAt) : 0;
     if (cancelRequestedAt > 0) {
@@ -406,7 +429,26 @@ async function processRun(args: {
 
     const startedAt = run.startedAt && run.startedAt !== "" ? Number(run.startedAt) : nowMs();
 
-    if (currentStatus === "queued") {
+    if (currentStatus === "queued" && def) {
+      const runningCount = await countRunningRunsForWorkflow({
+        redis,
+        prefix,
+        workflowName,
+        stopAt: maxConcurrency,
+      });
+
+      if (runningCount >= maxConcurrency) {
+        await redis.send("EVAL", [
+          REQUEUE_DUE_TO_CONCURRENCY_LUA,
+          "2",
+          processingKey,
+          keys.queueReady(prefix, queue),
+          runId,
+        ]);
+        await sleep(25);
+        return;
+      }
+
       const movedToRunning = await client.transitionRunStatusIfCurrent(runId, "queued", "running", startedAt);
       if (!movedToRunning) {
         // Most likely canceled between dequeue and start transition.
@@ -433,7 +475,6 @@ async function processRun(args: {
       return;
     }
 
-    const def = registry.get(workflowName);
     if (!def) {
       const errorJson = makeErrorJson(new UnknownWorkflowError(workflowName));
       await client.finalizeRun(runId, { status: "failed", errorJson, finishedAt: nowMs() });
@@ -902,6 +943,27 @@ async function reaperLoop(args: {
   }
 }
 
+async function countRunningRunsForWorkflow(args: {
+  redis: RedisClient;
+  prefix: string;
+  workflowName: string;
+  stopAt?: number;
+}): Promise<number> {
+  const { redis, prefix, workflowName, stopAt } = args;
+  const runningRunIds = await redis.zrevrange(keys.runsStatus(prefix, "running"), 0, -1);
+  let count = 0;
+
+  for (const runId of runningRunIds) {
+    const runWorkflow = await redis.hget(keys.run(prefix, runId), "workflow");
+    if (runWorkflow !== workflowName) continue;
+
+    count += 1;
+    if (typeof stopAt === "number" && count >= stopAt) return count;
+  }
+
+  return count;
+}
+
 async function cronSchedulerLoop(args: {
   redis: RedisClient;
   client: RedflowClient;
@@ -976,7 +1038,17 @@ async function cronSchedulerLoop(args: {
               continue;
             }
 
-            await client.runByName(workflow, input, { queueOverride: queue });
+            const cronMaxConcurrency = normalizeMaxConcurrency(def.maxConcurrency);
+            const runningCount = await countRunningRunsForWorkflow({
+              redis,
+              prefix,
+              workflowName: workflow,
+              stopAt: cronMaxConcurrency,
+            });
+
+            if (runningCount < cronMaxConcurrency) {
+              await client.runByName(workflow, input, { queueOverride: queue });
+            }
 
             // Schedule next run.
             let nextAt: number | null = null;

package/tests/bugfixes.test.ts

@@ -219,7 +219,7 @@ test("crash recovery: attempt is not double-incremented", async () => {
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -282,9 +282,9 @@ test("crash recovery: re-processing a running run does not bump attempt", async
   await redis.lpush(keys.queueReady(prefix, queue), runId);
 
   // Sync registry before starting worker
-  await client.syncRegistry(getDefaultRegistry());
+  await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -325,7 +325,7 @@ test("retry: run is atomically transitioned to scheduled with queue entry", asyn
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -426,7 +426,7 @@ test(
     const queue = "q_batch_promote";
     const countKey = `${prefix}:t:batchPromoteCount`;
 
-    const wf = defineWorkflow("batch-promote-wf", {queue }, async ({ step }) => {
+    const wf = defineWorkflow("batch-promote-wf", {queue, maxConcurrency: 5 }, async ({ step }) => {
       await step.run({ name: "do" }, async () => {
         await redis.incr(countKey);
         return true;
@@ -440,7 +440,7 @@ test(
       handles.push(await wf.run({}, { runAt: new Date(Date.now() + 200) }));
     }
 
-    const worker = await startWorker({
+    const worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: [queue],
@@ -527,7 +527,7 @@ test("duplicate step name: throws a clear error", async () => {
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -567,7 +567,7 @@ test("unique step names: work normally", async () => {
     return { sum: a + b + c };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -610,7 +610,7 @@ test(
       },
     );
 
-    const worker = await startWorker({
+    const worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: [queue],
@@ -661,7 +661,7 @@ test(
       },
     );
 
-    const worker = await startWorker({
+    const worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: [queue],
@@ -719,7 +719,7 @@ test("status indexes: consistent through full lifecycle", async () => {
   let queuedMembers = await redis.zrange(`${prefix}:runs:status:queued`, 0, -1);
   expect(queuedMembers.includes(handle.id)).toBe(true);
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],

package/tests/fixtures/worker-crash.ts

@@ -32,6 +32,7 @@ defineWorkflow(
 );
 
 await startWorker({
+  app: "test-fixture-crash",
   url,
   prefix,
   queues: [queue],

package/tests/fixtures/worker-recover.ts

@@ -34,6 +34,7 @@ defineWorkflow(
 );
 
 const worker = await startWorker({
+  app: "test-fixture-recover",
   url,
   prefix,
   queues: [queue],

package/tests/redflow.e2e.test.ts

@@ -52,7 +52,7 @@ test("manual run: succeeds and records steps", async () => {
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q1"],
@@ -82,7 +82,7 @@ test("runAt: scheduled -> promoted -> executed", async () => {
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q2"],
@@ -120,7 +120,7 @@ test("runAt: cleared after retry exhaustion final failure", async () => {
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q2_retry_fail"],
@@ -153,7 +153,7 @@ test("NonRetriableError: skips retries and fails immediately on attempt 1", asyn
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_non_retriable"],
@@ -196,7 +196,7 @@ test("onFailure: called after retry exhaustion with correct context", async () =
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_on_failure_1"],
@@ -239,7 +239,7 @@ test("onFailure: called immediately with NonRetriableError", async () => {
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_on_failure_2"],
@@ -283,7 +283,7 @@ test("onFailure: NOT called on cancellation", async () => {
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_on_failure_3"],
@@ -333,7 +333,7 @@ test("cron: creates runs and executes workflow", async () => {
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q4"],
@@ -352,6 +352,75 @@ test("cron: creates runs and executes workflow", async () => {
   redis.close();
 });
 
+test("cron: skips when workflow already running", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const manualCountKey = `${prefix}:t:cronSkipManualCount`;
+  const cronCountKey = `${prefix}:t:cronSkipCronCount`;
+
+  defineWorkflow(
+    "cron-skip-running-wf",
+    {
+      queue: "q4_skip",
+      cron: [{ expression: "*/5 * * * * *", input: { source: "cron" } }],
+    },
+    async ({ input, step }) => {
+      await step.run({ name: "record-source" }, async () => {
+        const source = (input as { source?: string } | null | undefined)?.source;
+        if (source === "cron") {
+          await redis.incr(cronCountKey);
+        } else {
+          await redis.incr(manualCountKey);
+        }
+        return true;
+      });
+
+      await step.run({ name: "hold" }, async () => {
+        await new Promise((resolve) => setTimeout(resolve, 6500));
+        return true;
+      });
+
+      return { ok: true };
+    },
+  );
+
+  const worker = await startWorker({ app: "test-app",
+    redis,
+    prefix,
+    queues: ["q4_skip"],
+    concurrency: 2,
+    runtime: { leaseMs: 500 },
+  });
+
+  try {
+    const manualHandle = await client.emitWorkflow("cron-skip-running-wf", { source: "manual" });
+
+    await waitFor(
+      async () => Number((await redis.get(manualCountKey)) ?? "0") >= 1,
+      { timeoutMs: 5000, label: "manual run started" },
+    );
+
+    // Wait long enough for one cron tick while manual run is still executing.
+    await new Promise((resolve) => setTimeout(resolve, 5500));
+    const cronWhileManualRunning = Number((await redis.get(cronCountKey)) ?? "0");
+    expect(cronWhileManualRunning).toBe(0);
+
+    await manualHandle.result({ timeoutMs: 15_000 });
+
+    // Cron should resume once the running instance is gone.
+    await waitFor(
+      async () => Number((await redis.get(cronCountKey)) ?? "0") >= 1,
+      { timeoutMs: 10_000, label: "cron resumed after manual run" },
+    );
+  } finally {
+    await worker.stop();
+    redis.close();
+  }
+}, { timeout: 30_000 });
+
 test("step.runWorkflow: auto idempotency and override are forwarded to child runs", async () => {
   const prefix = testPrefix();
   const redis = new RedisClient(redisServer.url);
@@ -388,7 +457,7 @@ test("step.runWorkflow: auto idempotency and override are forwarded to child run
     return { auto, custom };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_rw_parent", "q_rw_child"],
@@ -451,7 +520,7 @@ test("step.runWorkflow: child workflow executes once across parent retries", asy
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_rw_retry_parent", "q_rw_retry_child"],
@@ -508,7 +577,7 @@ test("step.runWorkflow: same queue avoids self-deadlock with concurrency 1", asy
     return await step.runWorkflow({ name: "call-child" }, child, {});
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_rw_single"],
@@ -552,7 +621,7 @@ test("step.emitWorkflow: supports workflow name strings", async () => {
     return { childRunId };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_emit_name_parent", "q_emit_name_child"],
@@ -606,7 +675,7 @@ test("retries: step results are cached across attempts", async () => {
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q5"],
@@ -654,7 +723,7 @@ test("retries: run queued before worker start keeps workflow maxAttempts", async
   const queuedState = await client.getRun(handle.id);
   expect(queuedState?.maxAttempts).toBe(2);
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q5_before_sync"],
@@ -687,7 +756,7 @@ test("step timeout: run fails and error is recorded", async () => {
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q6"],
@@ -737,7 +806,7 @@ test("cancellation: scheduled/queued/running", async () => {
 
   // Scheduled cancel.
   {
-    const worker = await startWorker({
+    const worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: ["q7"],
@@ -773,7 +842,7 @@ test("cancellation: scheduled/queued/running", async () => {
 
   // Running cancel.
   {
-    const worker = await startWorker({
+    const worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: ["q7"],
@@ -856,7 +925,7 @@ test("cancel race: queued cancel before start does not execute handler", async (
 
   let worker: Awaited<ReturnType<typeof startWorker>> | null = null;
   try {
-    worker = await startWorker({
+    worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: [queue],
@@ -977,7 +1046,7 @@ test("idempotencyKey: same key returns same run id and executes once", async ()
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q9"],
@@ -1015,7 +1084,7 @@ test("idempotencyKey: delayed TTL refresh cannot fork duplicate runs", async ()
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q9_race_fix"],
@@ -1063,7 +1132,7 @@ test("enqueue: producer-side zadd failure does not leave runs orphaned", async (
   setDefaultClient(client);
 
   const wf = defineWorkflow("enqueue-atomic", {queue: "q_enqueue_atomic" }, async () => ({ ok: true }));
-  await client.syncRegistry(getDefaultRegistry());
+  await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
   const originalZadd = redis.zadd.bind(redis);
   let injected = false;
@@ -1082,7 +1151,7 @@ test("enqueue: producer-side zadd failure does not leave runs orphaned", async (
     redis.zadd = originalZadd;
   }
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_enqueue_atomic"],
@@ -1107,7 +1176,7 @@ test("idempotencyKey: delimiter-like workflow/key pairs do not collide", async (
   const wfA = defineWorkflow("idem:a", {queue: "q9a" }, async () => ({ workflow: "idem:a" }));
   const wfB = defineWorkflow("idem:a:b", {queue: "q9b" }, async () => ({ workflow: "idem:a:b" }));
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q9a", "q9b"],
@@ -1150,7 +1219,7 @@ test("idempotencyTtl: short TTL expires and allows a new run with same key", asy
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_idem_ttl"],
@@ -1199,7 +1268,7 @@ test("input validation: invalid input fails once and is not retried", async () =
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q11"],
@@ -1234,7 +1303,7 @@ test("unknown workflow: run fails and is not retried", async () => {
   const redis = new RedisClient(redisServer.url);
   const client = createClient({ redis, prefix });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["qx"],
@@ -1287,7 +1356,7 @@ test("cancel during step: run becomes canceled and step error kind is canceled",
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q12"],
@@ -1345,7 +1414,7 @@ test("terminal run re-queued is ignored (no re-execution)", async () => {
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -1393,7 +1462,7 @@ test("lease+reaper: long running step is not duplicated", async () => {
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -1438,8 +1507,8 @@ test(
     },
   );
 
-  const w1 = await startWorker({ redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
-  const w2 = await startWorker({ redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
+  const w1 = await startWorker({ app: "test-app", redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
+  const w2 = await startWorker({ app: "test-app", redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
 
   await new Promise((r) => setTimeout(r, 3500));
   const count = Number((await redis.get(counterKey)) ?? "0");
@@ -1505,7 +1574,7 @@ test(
       },
     );
 
-    const worker = await startWorker({
+    const worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: ["q_parent", "q_child"],
@@ -1560,7 +1629,7 @@ test(
     const queuedMembers = await redis.zrange(queuedIndex, 0, -1);
     expect(queuedMembers.includes(handle.id)).toBe(true);
 
-    const worker = await startWorker({
+    const worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: [queue],
@@ -1606,7 +1675,7 @@ test(
       cron: [{ expression: "*/1 * * * * *" }],
     }, async () => ({ ok: true }));
 
-    await client.syncRegistry(getDefaultRegistry());
+    await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
     const workflowKey = `${prefix}:workflow:${name}`;
     const cronIdsJson = await redis.hget(workflowKey, "cronIdsJson");
@@ -1624,7 +1693,7 @@ test(
       queue: "q_update",
     }, async () => ({ ok: true }));
 
-    await client.syncRegistry(getDefaultRegistry());
+    await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
     expect(await redis.hget(`${prefix}:cron:def`, cronId)).toBeNull();
     const cronNext2 = await redis.zrange(`${prefix}:cron:next`, 0, -1);
@@ -1658,7 +1727,7 @@ test(
       },
     );
 
-    const worker = await startWorker({
+    const worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: [queue],
@@ -1708,8 +1777,8 @@ test(
       },
     );
 
-    const w1 = await startWorker({ redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
-    const w2 = await startWorker({ redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
+    const w1 = await startWorker({ app: "test-app", redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
+    const w2 = await startWorker({ app: "test-app", redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
 
     await waitFor(
       async () => Number((await redis.get(counterKey)) ?? "0") >= 1,
@@ -1744,7 +1813,7 @@ test("listRuns: status + workflow filters are applied together", async () => {
     throw new Error("expected failure");
   });
 
-  const worker = await startWorker({ redis, prefix, queues: [queue], runtime: { leaseMs: 500 } });
+  const worker = await startWorker({ app: "test-app", redis, prefix, queues: [queue], runtime: { leaseMs: 500 } });
 
   const successHandle = await succeeds.run({});
   const failHandle = await fails.run({});
@@ -1795,7 +1864,7 @@ test("cron trigger ids: same custom id in two workflows does not collide", async
     async () => ({ ok: true }),
   );
 
-  await client.syncRegistry(getDefaultRegistry());
+  await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
   const idsA = JSON.parse((await redis.hget(`${prefix}:workflow:cron-id-a`, "cronIdsJson")) ?? "[]") as string[];
   const idsB = JSON.parse((await redis.hget(`${prefix}:workflow:cron-id-b`, "cronIdsJson")) ?? "[]") as string[];
@@ -1823,7 +1892,7 @@ test("syncRegistry: cron trigger with explicit null input preserves null payload
     async () => ({ ok: true }),
   );
 
-  await client.syncRegistry(getDefaultRegistry());
+  await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
   const workflowKey = `${prefix}:workflow:${workflowName}`;
   const cronIds = JSON.parse((await redis.hget(workflowKey, "cronIdsJson")) ?? "[]") as string[];
@@ -1854,7 +1923,7 @@ test("syncRegistry: invalid cron expression removes existing next schedule for s
     async () => ({ ok: true }),
   );
 
-  await client.syncRegistry(getDefaultRegistry());
+  await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
   const cronIds = JSON.parse((await redis.hget(workflowKey, "cronIdsJson")) ?? "[]") as string[];
   expect(cronIds.length).toBe(1);
@@ -1870,7 +1939,7 @@ test("syncRegistry: invalid cron expression removes existing next schedule for s
     async () => ({ ok: true }),
   );
 
-  await client.syncRegistry(getDefaultRegistry());
+  await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
   const after = await redis.zrange(cronNextKey, 0, -1);
   expect(after.includes(cronId)).toBe(false);
@@ -1891,7 +1960,7 @@ test("syncRegistry: removes stale workflow metadata (cron)", async () => {
     async () => ({ ok: true }),
   );
 
-  await client.syncRegistry(getDefaultRegistry());
+  await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
   const workflowKey = `${prefix}:workflow:${workflowName}`;
   const cronIds = JSON.parse((await redis.hget(workflowKey, "cronIdsJson")) ?? "[]") as string[];
@@ -1903,7 +1972,7 @@ test("syncRegistry: removes stale workflow metadata (cron)", async () => {
   // Force stale age beyond grace period and sync an empty registry.
   await redis.hset(workflowKey, { updatedAt: "1" });
   __unstableResetDefaultRegistryForTests();
-  await client.syncRegistry(getDefaultRegistry());
+  await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
   expect((await redis.smembers(`${prefix}:workflows`)).includes(workflowName)).toBe(false);
   expect(await redis.hget(workflowKey, "queue")).toBeNull();
@@ -1914,37 +1983,37 @@ test("syncRegistry: removes stale workflow metadata (cron)", async () => {
   redis.close();
 });
 
-test("syncRegistry: stale cleanup is isolated by owner", async () => {
+test("syncRegistry: stale cleanup is isolated by app", async () => {
   const prefix = testPrefix();
   const redis = new RedisClient(redisServer.url);
   const client = createClient({ redis, prefix });
 
   __unstableResetDefaultRegistryForTests();
-  defineWorkflow("owner-a-wf", {queue: "qa",
+  defineWorkflow("app-a-wf", {queue: "qa",
       cron: [{ id: "a", expression: "*/30 * * * * *" }],
     },
     async () => ({ ok: true }),
   );
-  await client.syncRegistry(getDefaultRegistry(), { owner: "svc-a" });
+  await client.syncRegistry(getDefaultRegistry(), { app: "svc-a" });
 
   __unstableResetDefaultRegistryForTests();
-  defineWorkflow("owner-b-wf", {queue: "qb",
+  defineWorkflow("app-b-wf", {queue: "qb",
       cron: [{ id: "b", expression: "*/30 * * * * *" }],
     },
     async () => ({ ok: true }),
   );
-  await client.syncRegistry(getDefaultRegistry(), { owner: "svc-b" });
+  await client.syncRegistry(getDefaultRegistry(), { app: "svc-b" });
 
-  await redis.hset(`${prefix}:workflow:owner-a-wf`, { updatedAt: "1" });
-  await redis.hset(`${prefix}:workflow:owner-b-wf`, { updatedAt: "1" });
+  await redis.hset(`${prefix}:workflow:app-a-wf`, { updatedAt: "1" });
+  await redis.hset(`${prefix}:workflow:app-b-wf`, { updatedAt: "1" });
 
   __unstableResetDefaultRegistryForTests();
-  await client.syncRegistry(getDefaultRegistry(), { owner: "svc-a" });
+  await client.syncRegistry(getDefaultRegistry(), { app: "svc-a" });
 
-  expect(await redis.hget(`${prefix}:workflow:owner-a-wf`, "queue")).toBeNull();
-  expect(await redis.hget(`${prefix}:workflow:owner-b-wf`, "queue")).not.toBeNull();
-  expect((await redis.smembers(`${prefix}:workflows`)).includes("owner-a-wf")).toBe(false);
-  expect((await redis.smembers(`${prefix}:workflows`)).includes("owner-b-wf")).toBe(true);
+  expect(await redis.hget(`${prefix}:workflow:app-a-wf`, "queue")).toBeNull();
+  expect(await redis.hget(`${prefix}:workflow:app-b-wf`, "queue")).not.toBeNull();
+  expect((await redis.smembers(`${prefix}:workflows`)).includes("app-a-wf")).toBe(false);
+  expect((await redis.smembers(`${prefix}:workflows`)).includes("app-b-wf")).toBe(true);
 
   redis.close();
 });
@@ -1957,7 +2026,7 @@ test("cancelRun: terminal runs are unchanged", async () => {
 
   const wf = defineWorkflow("cancel-terminal", {queue: "q_cancel_terminal" }, async () => ({ ok: true }));
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_cancel_terminal"],
@@ -1992,7 +2061,7 @@ test("output serialization: non-JSON output fails once and is not stuck", async
     async () => ({ bad: 1n }),
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_serial"],
@@ -2047,7 +2116,7 @@ test("retry step sequence: new steps keep monotonic order after cached steps", a
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_seq"],
@@ -2078,7 +2147,7 @@ test("listRuns: negative offset is clamped to zero", async () => {
   setDefaultClient(client);
 
   const wf = defineWorkflow("offset-wf", {queue: "q_offset" }, async () => ({ ok: true }));
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_offset"],
@@ -2142,7 +2211,7 @@ test("error serialization: non-serializable thrown values do not wedge a run", a
     },
   );
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: ["q_bigint"],
@@ -2185,7 +2254,7 @@ test("cron trigger ids: delimiter-like custom ids do not collide", async () => {
     async () => ({ ok: true }),
   );
 
-  await client.syncRegistry(getDefaultRegistry());
+  await client.syncRegistry(getDefaultRegistry(), { app: "test-app" });
 
   const idsA = JSON.parse((await redis.hget(`${prefix}:workflow:wf:a`, "cronIdsJson")) ?? "[]") as string[];
   const idsB = JSON.parse((await redis.hget(`${prefix}:workflow:wf:a:b`, "cronIdsJson")) ?? "[]") as string[];
@@ -2219,7 +2288,7 @@ test("idempotencyKey: stale pointer is recovered instead of returning missing ru
 
   const wf = defineWorkflow(workflowName, {queue }, async () => ({ ok: true }));
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -2262,7 +2331,7 @@ test("idempotencyKey: partial existing run is repaired and executed", async () =
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -2314,7 +2383,7 @@ test("syncRegistry: duplicate custom cron ids in one workflow are rejected", asy
     async () => ({ ok: true }),
   );
 
-  await expect(client.syncRegistry(getDefaultRegistry())).rejects.toThrow("Duplicate cron trigger id");
+  await expect(client.syncRegistry(getDefaultRegistry(), { app: "test-app" })).rejects.toThrow("Duplicate cron trigger id");
 
   redis.close();
 });
@@ -2331,7 +2400,7 @@ test("scheduled promoter: stale scheduled entry does not resurrect terminal run"
     return { ok: true };
   });
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -2398,7 +2467,7 @@ test(
 
     let worker: Awaited<ReturnType<typeof startWorker>> | null = null;
     try {
-      worker = await startWorker({
+      worker = await startWorker({ app: "test-app",
         redis,
         prefix,
         queues: [queue],
@@ -2449,7 +2518,7 @@ test(
 
     let worker: Awaited<ReturnType<typeof startWorker>> | null = null;
     try {
-      worker = await startWorker({
+      worker = await startWorker({ app: "test-app",
         redis,
         prefix,
         queues: [queue],
@@ -2492,7 +2561,7 @@ test("workflow names ending with ':runs' do not collide with workflow run indexe
 
   expect(keys.workflow(prefix, "keyspace-base:runs")).not.toBe(keys.workflowRuns(prefix, "keyspace-base"));
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -2537,7 +2606,7 @@ test("cancelRun race: near-finish cancellation settles as canceled", async () =>
     return await originalFinalizeRun.call(this, runId, args);
   }) as RedflowClient["finalizeRun"];
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -2600,7 +2669,7 @@ test("cancelRun race: cancellation requested during finalize wins over success",
     return await originalFinalizeRun.call(this, runId, args);
   }) as RedflowClient["finalizeRun"];
 
-  const worker = await startWorker({
+  const worker = await startWorker({ app: "test-app",
     redis,
     prefix,
     queues: [queue],
@@ -2650,7 +2719,7 @@ test(
       await new Promise<never>(() => {});
     });
 
-    const worker = await startWorker({
+    const worker = await startWorker({ app: "test-app",
       redis,
       prefix,
       queues: [queue],