@strav/queue 0.4.31 → 1.0.0-alpha.4

package/README.md

@@ -0,0 +1,243 @@
+# @strav/queue
+
+Background-job primitives for Strav 1.0 — the `Job` base class, the `JobRegistry`, the `Queue` contract, and a synchronous in-process driver. Postgres-backed `DatabaseQueue` + `Worker` + `Scheduler` land in follow-up M3 slices.
+
+> **Status: 1.0.0-alpha — queue package functionally complete.** Contract layer + `SyncQueue` + `DatabaseQueue` (queue-until-commit) + `Worker` (SKIP LOCKED + backoff + atomic-move-to-failed) + `Scheduler` (cron + `onOneServer`) + `failedJobsSchema` all shipped. Only the `queue:retry` / `queue:flush` console commands remain — they wait on `@strav/cli` (M4).
+
+## Install
+
+```bash
+bun add @strav/queue
+```
+
+Peer dep: `@strav/kernel` (already in the workspace).
+
+## Defining a Job
+
+Subclass `Job<TPayload>`, declare a stable `static jobName`, implement `handle(ctx)`:
+
+```ts
+import { Job, type JobContext } from '@strav/queue'
+import { inject } from '@strav/kernel'
+
+@inject()
+export class SendWelcomeEmail extends Job<{ userId: string }> {
+  static override readonly jobName = 'mail.welcome'
+
+  constructor(
+    private readonly users: UserRepository,
+    private readonly mail: MailManager,
+  ) {
+    super()
+  }
+
+  async handle(ctx: JobContext<{ userId: string }>): Promise<void> {
+    const user = await this.users.findOrFail(ctx.payload.userId)
+    await this.mail.send(new WelcomeEmail(user))
+  }
+}
+```
+
+The Worker constructs the Job via the container — so `@inject()`-marked subclasses get their dependencies the same way Repositories + controllers do. The payload arrives on `JobContext.payload` (after JSON round-trip through the queue backend).
+
+### Configuration
+
+Optional static overrides — the Worker reads these per-attempt:
+
+```ts
+class SendWelcomeEmail extends Job<...> {
+  static override readonly jobName = 'mail.welcome'
+  static override readonly maxAttempts = 5
+  static override readonly timeout = 30          // seconds
+  static override readonly queue = 'mail'        // named queue
+  static override backoff(attempt: number): number {
+    return Math.min(60, 2 ** attempt)            // seconds before next retry
+  }
+}
+```
+
+Omitted fields fall back to driver defaults.
+
+### `failed(ctx)` hook
+
+Fires when a `handle()` attempt throws — both on intermediate retryable failures AND on the final failure. Useful for routing to a dead-letter, posting to Slack, etc.:
+
+```ts
+async failed(ctx: JobFailedContext<{ userId: string }>): Promise<void> {
+  await slack.post(`Welcome email failed for ${ctx.payload.userId}: ${(ctx.error as Error).message}`)
+}
+```
+
+A throw from `failed()` is logged but doesn't change the retry decision.
+
+## Registering jobs
+
+`JobRegistry` maps `jobName` strings back to Job classes — the Worker uses it to deserialize the queue row's `type` column into a class to instantiate.
+
+### Explicit
+
+```ts
+import { JobRegistry } from '@strav/queue'
+import { SendWelcomeEmail } from '../app/Jobs/send_welcome_email.ts'
+
+const registry = new JobRegistry().registerAll([SendWelcomeEmail, /* ... */])
+```
+
+### Auto-discovery
+
+`discover(pattern)` uses `Bun.Glob` to scan files, dynamically imports each, and registers every export that satisfies `isJobClass()`. Same shape as `SchemaRegistry.discover` in `@strav/database`.
+
+```ts
+await registry.discover('app/Jobs/**/*.ts')
+```
+
+Re-exports of the same class (barrel patterns) dedupe by identity; two DIFFERENT classes sharing a `jobName` throw `ConfigError`.
+
+## Dispatching
+
+`Queue` is an interface with three methods:
+
+```ts
+queue.dispatch(JobClass, payload, opts?)       // returns jobId (ULID)
+queue.dispatchLater(at, JobClass, payload, opts?)
+queue.dispatchSync(JobClass, payload)          // run in-process, no persistence
+```
+
+`dispatchLater`'s `at` is either a `Date` (absolute) or a positive number of seconds from now. Past dates / zero clamp to "now". Negative numbers throw.
+
+`opts.queue` and `opts.attempts` override the JobClass defaults.
+
+## SyncQueue — in-process driver
+
+The V1 driver for tests and single-process dev. Instantiates the Job via the container, builds a `JobContext`, calls `handle()` synchronously. No persistence, no retries — if `handle()` throws, the throw propagates.
+
+```ts
+import { Application } from '@strav/kernel'
+import { SyncQueue } from '@strav/queue'
+
+const app = new Application()
+const queue = new SyncQueue({ container: app, logger: app.resolve(Logger) })
+
+await queue.dispatch(SendWelcomeEmail, { userId: 'u-1' })   // runs immediately
+```
+
+`dispatchLater` under `SyncQueue` ignores the delay (still runs immediately) but validates the delay shape — so callers can't pass `-5` here and have it silently work, only to fail on `DatabaseQueue` later.
+
+## DatabaseQueue — Postgres-backed driver
+
+The production driver. `dispatch` writes a `strav_jobs` row; the Worker (next M3 slice) picks it up via `SELECT FOR UPDATE SKIP LOCKED`. Apps register `jobSchema` with their `SchemaRegistry` and migrate the table.
+
+```ts
+import { Application, EventBus } from '@strav/kernel'
+import { DatabaseProvider, PostgresDatabase, SchemaRegistry } from '@strav/database'
+import { DatabaseQueue, jobSchema } from '@strav/queue'
+
+// In SchemasProvider (or wherever you register schemas):
+registry.registerAll([jobSchema, /* … */])
+
+// In QueueProvider:
+new DatabaseQueue({
+  db: app.resolve(PostgresDatabase),
+  container: app,
+  logger: app.resolve(Logger),
+})
+```
+
+### Queue-until-commit
+
+When `dispatch` is called inside `UnitOfWork.run(...)` or `TenantManager.withTenant(...)`, the INSERT routes through the ambient transaction. Atomic with the surrounding work:
+
+```ts
+await uow.run(async () => {
+  await userRepo.create({ email })
+  await queue.dispatch(SendWelcomeEmail, { userId: '...' })
+  // If the transaction commits, both the user row AND the queue row
+  // are visible. If it rolls back, neither exists.
+})
+```
+
+This is the M3 spike from the spec — Postgres's transactional atomicity gives us the semantic for free. See [`docs/queue/api.md`](../../docs/queue/api.md#queue-until-commit-semantics) for the full mechanics.
+
+### Delay mechanics
+
+`dispatchLater` computes delays in Postgres (`now() + interval 'N seconds'`) so the Worker reads `available_at` from the same DB clock the dispatcher wrote against — no clock-skew bugs.
+
+## Worker — the consumer side
+
+Polls `strav_jobs`, claims via `SELECT FOR UPDATE SKIP LOCKED`, runs `handle()` with a per-attempt timeout, deletes on success, retries with backoff on failure.
+
+```ts
+import { Worker } from '@strav/queue'
+
+const worker = new Worker({
+  db: app.resolve(PostgresDatabase),
+  registry: app.resolve(JobRegistry),
+  container: app,
+  logger: app.resolve(Logger),
+  queues: ['default'],
+  pollInterval: 1000,      // ms between empty polls
+  timeoutSeconds: 60,      // per-attempt timeout
+})
+
+const controller = new AbortController()
+process.on('SIGTERM', () => controller.abort())
+process.on('SIGINT',  () => controller.abort())
+
+await worker.run(controller.signal)
+```
+
+`SKIP LOCKED` is the load-bearing primitive — multiple Worker processes can poll the same queue concurrently without picking the same row. Scale horizontally by running more processes.
+
+Default backoff: exponential with ±25% jitter, capped at 300 seconds. Per-job override via `static backoff(attempt: number)`, per-Worker via `defaultBackoff`. Jitter prevents thundering-herd retries when many jobs fail simultaneously.
+
+`processOne()` (single-shot) is also exposed — useful for tests + one-off CLI invocations.
+
+## Scheduler — cron-driven dispatch
+
+```ts
+import { Scheduler, dailyAt, everyMinutes, hourly } from '@strav/queue'
+
+const scheduler = new Scheduler({
+  queue: app.resolve(Queue),
+  tenants: app.resolve(TenantManager),
+})
+
+scheduler
+  .schedule({ job: CleanupOldSessions, cron: hourly() })
+  .schedule({ job: GenerateNightlyReports, cron: dailyAt('02:00'), oneServer: true })
+  .schedule({ job: SyncStripe, cron: everyMinutes(15), oneServer: true })
+
+const controller = new AbortController()
+process.on('SIGTERM', () => controller.abort())
+process.on('SIGINT',  () => controller.abort())
+await scheduler.run(controller.signal)
+```
+
+`oneServer: true` uses `TenantManager.withLock` to acquire a fleet-wide advisory lock + `strav_scheduler_runs.last_run_at` to track which tick boundary already dispatched. Only one server in the fleet dispatches per tick — exactly-once across however many scheduler processes you run.
+
+Register `schedulerRunsSchema` alongside `jobSchema` in your `SchemaRegistry` so `generateMigration` picks up the table.
+
+Cron matching is UTC-based for predictability. Helper builders cover the common cases (`everyMinute`, `everyMinutes`, `hourly`, `daily`, `dailyAt`) — reach for `cron(expression)` directly when you need weekly / monthly / arbitrary expressions.
+
+## Failed jobs — `strav_failed_jobs` dead-letter
+
+When `Worker.processOne()` exhausts a job's `max_attempts`, the row moves from `strav_jobs` to `strav_failed_jobs` atomically (INSERT + DELETE in one transaction). Apps inspect this table to triage what blew up:
+
+```sql
+SELECT job_name, exception, attempts, failed_at
+FROM strav_failed_jobs
+WHERE job_name = 'mail.welcome'
+ORDER BY failed_at DESC;
+```
+
+Register `failedJobsSchema` alongside `jobSchema` + `schedulerRunsSchema` so `generateMigration` picks up the table:
+
+```ts
+registry.registerAll([userSchema, jobSchema, schedulerRunsSchema, failedJobsSchema])
+```
+
+The `queue:retry` / `queue:flush` console commands (bulk re-enqueue / drop) ship with `@strav/cli` in M4. Until then, retry by hand: SELECT the failed row, INSERT into `strav_jobs` with the same payload, DELETE from `strav_failed_jobs`.
+
+## What's NOT here yet
+
+- **`queue:retry` / `queue:flush` console commands** — bulk operations on the `strav_failed_jobs` table. Waits on `@strav/cli` in M4.

package/package.json

@@ -1,38 +1,30 @@
 {
   "name": "@strav/queue",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.4",
+  "description": "Strav queue layer — Job + JobRegistry + dispatch contract; backends ship as drivers",
   "type": "module",
-  "description": "Background job processing and task scheduling for the Strav framework",
-  "license": "MIT",
-  "keywords": [
-    "bun",
-    "framework",
-    "typescript",
-    "strav",
-    "queue",
-    "scheduler"
-  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "files": [
-    "src/",
-    "package.json",
-    "tsconfig.json",
-    "CHANGELOG.md"
+    "src",
+    "README.md"
   ],
-  "exports": {
-    ".": "./src/index.ts",
-    "./queue": "./src/queue/index.ts",
-    "./queue/*": "./src/queue/*.ts",
-    "./scheduler": "./src/scheduler/index.ts",
-    "./scheduler/*": "./src/scheduler/*.ts",
-    "./providers": "./src/providers/index.ts",
-    "./providers/*": "./src/providers/*.ts"
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/cli": "1.0.0-alpha.4",
+    "@strav/database": "1.0.0-alpha.4",
+    "@strav/kernel": "1.0.0-alpha.4"
   },
   "peerDependencies": {
-    "@strav/kernel": "0.4.31",
-    "@strav/database": "0.4.31"
+    "@types/bun": ">=1.3.14"
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  }
+  "devDependencies": null
 }

package/src/console/index.ts

@@ -0,0 +1,10 @@
+// Console subsystem — queue + scheduler commands + QueueConsoleProvider.
+
+export { QueueConsoleProvider } from './queue_console_provider.ts'
+export { QueueFailed } from './queue_failed.ts'
+export { QueueFlush } from './queue_flush.ts'
+export { QueueRetry } from './queue_retry.ts'
+export { QueueWork } from './queue_work.ts'
+export { SchedulerList } from './scheduler_list.ts'
+export { SchedulerRun } from './scheduler_run.ts'
+export { SchedulerWork } from './scheduler_work.ts'

package/src/console/queue_console_provider.ts

@@ -0,0 +1,32 @@
+/**
+ * `QueueConsoleProvider` — declares the queue + scheduler console commands.
+ *
+ * Apps add it to `bootstrap/providers.ts` alongside whatever provider binds
+ * `Worker` + `Scheduler` (apps wire those — see `docs/queue/guides/console.md`).
+ *
+ * The provider doesn't bind Worker/Scheduler itself because their
+ * construction is app-specific (queue names, registered jobs, scheduler
+ * entries) — too much variance for a sensible default.
+ */
+
+import { ConsoleProvider } from '@strav/cli'
+import { QueueFailed } from './queue_failed.ts'
+import { QueueFlush } from './queue_flush.ts'
+import { QueueRetry } from './queue_retry.ts'
+import { QueueWork } from './queue_work.ts'
+import { SchedulerList } from './scheduler_list.ts'
+import { SchedulerRun } from './scheduler_run.ts'
+import { SchedulerWork } from './scheduler_work.ts'
+
+export class QueueConsoleProvider extends ConsoleProvider {
+  override readonly name = 'console.queue'
+  override readonly commands = [
+    QueueWork,
+    QueueFailed,
+    QueueRetry,
+    QueueFlush,
+    SchedulerWork,
+    SchedulerList,
+    SchedulerRun,
+  ] as const
+}

package/src/console/queue_failed.ts

@@ -0,0 +1,57 @@
+/**
+ * `bun strav queue:failed` — list rows in the dead-letter table.
+ *
+ * Reads `strav_failed_jobs` directly via the bound `Database`. The
+ * Worker moves terminal failures here (atomic INSERT + DELETE from
+ * `strav_jobs`); this command surfaces them for triage.
+ */
+
+import { Command, ExitCode } from '@strav/cli'
+import { PostgresDatabase } from '@strav/database'
+
+interface FailedRow {
+  id: string
+  queue: string
+  job_name: string
+  attempts: number
+  failed_at: Date | string
+  exception: string
+}
+
+export class QueueFailed extends Command {
+  static signature = 'queue:failed'
+  static description = 'List jobs in the dead-letter table.'
+  static providers = ['config', 'logger', 'database']
+
+  override async execute(): Promise<number> {
+    const db = this.app.resolve(PostgresDatabase)
+    const rows = await db.query<FailedRow>(
+      `SELECT id, queue, job_name, attempts, failed_at, exception
+         FROM "strav_failed_jobs"
+         ORDER BY failed_at DESC`,
+    )
+
+    if (rows.length === 0) {
+      this.info('No failed jobs.')
+      return ExitCode.Success
+    }
+
+    this.table(
+      ['ID', 'Queue', 'Job', 'Attempts', 'Failed at', 'Error'],
+      rows.map((r) => [
+        r.id,
+        r.queue,
+        r.job_name,
+        String(r.attempts),
+        (r.failed_at instanceof Date ? r.failed_at : new Date(r.failed_at)).toISOString(),
+        firstLine(r.exception),
+      ]),
+    )
+    return ExitCode.Success
+  }
+}
+
+function firstLine(text: string): string {
+  const newline = text.indexOf('\n')
+  return newline === -1 ? text : text.slice(0, newline)
+}

package/src/console/queue_flush.ts

@@ -0,0 +1,41 @@
+/**
+ * `bun strav queue:flush [--queue=name] [--force]` — drop pending jobs.
+ *
+ * `DELETE FROM strav_jobs` (optionally filtered by queue name). Confirms
+ * before running unless `--force` is set. Doesn't touch
+ * `strav_failed_jobs` — the dead-letter table is separate and managed
+ * via `queue:retry` / a separate operator-driven cleanup.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { PostgresDatabase } from '@strav/database'
+
+export class QueueFlush extends Command {
+  static signature = 'queue:flush {--queue=} {--force}'
+  static description = 'Delete pending jobs (optionally filtered by --queue).'
+  static providers = ['config', 'logger', 'database']
+
+  override async execute({ flags }: ExecuteArgs): Promise<number> {
+    const queue = typeof flags.queue === 'string' && flags.queue.length > 0 ? flags.queue : null
+
+    if (flags.force !== true) {
+      const ok = await this.confirm(
+        queue
+          ? `Delete every pending job on queue "${queue}"? This is irreversible.`
+          : 'Delete EVERY pending job across all queues? This is irreversible.',
+      )
+      if (!ok) {
+        this.info('Aborted.')
+        return ExitCode.Success
+      }
+    }
+
+    const db = this.app.resolve(PostgresDatabase)
+    const deleted = queue
+      ? await db.execute(`DELETE FROM "strav_jobs" WHERE queue = $1`, [queue])
+      : await db.execute(`DELETE FROM "strav_jobs"`)
+
+    this.success(`Deleted ${deleted} pending job(s)${queue ? ` from queue "${queue}"` : ''}.`)
+    return ExitCode.Success
+  }
+}

package/src/console/queue_retry.ts

@@ -0,0 +1,68 @@
+/**
+ * `bun strav queue:retry <id>` or `--all` — re-enqueue failed jobs.
+ *
+ * Copies the failed row(s) back into `strav_jobs` (attempts reset to 0,
+ * available_at = now()) and deletes them from `strav_failed_jobs` — all
+ * inside one transaction so a crash mid-move can't lose rows or
+ * double-enqueue.
+ *
+ * `<id>` re-enqueues exactly one job; `--all` re-enqueues every row in
+ * the dead-letter table. Without either, the command errors out with a
+ * usage message.
+ */
+
+import { Command, type ExecuteArgs, ExitCode, UsageError } from '@strav/cli'
+import { PostgresDatabase } from '@strav/database'
+import { ulid } from '@strav/kernel'
+
+interface FailedRow {
+  id: string
+  queue: string
+  job_name: string
+  payload: unknown
+}
+
+export class QueueRetry extends Command {
+  static signature = 'queue:retry {id?} {--all}'
+  static description = 'Re-enqueue a failed job by id, or every failed job with --all.'
+  static providers = ['config', 'logger', 'database']
+
+  override async execute({ args, flags }: ExecuteArgs): Promise<number> {
+    const all = flags.all === true
+    const id = args.id
+    if (!all && (id === undefined || id.length === 0)) {
+      throw new UsageError('queue:retry needs an <id> or the --all flag')
+    }
+    if (all && id !== undefined && id.length > 0) {
+      throw new UsageError('queue:retry: pass an <id> OR --all, not both')
+    }
+
+    const db = this.app.resolve(PostgresDatabase)
+    const moved = await db.transaction(async (tx) => {
+      const rows = all
+        ? await tx.query<FailedRow>(`SELECT id, queue, job_name, payload FROM "strav_failed_jobs"`)
+        : await tx.query<FailedRow>(
+            `SELECT id, queue, job_name, payload FROM "strav_failed_jobs" WHERE id = $1`,
+            [id],
+          )
+      for (const row of rows) {
+        await tx.execute(
+          `INSERT INTO "strav_jobs" (id, queue, job_name, payload, attempts, max_attempts, available_at, reserved_at, created_at, updated_at)
+             VALUES ($1, $2, $3, $4, 0, 3, now(), NULL, now(), now())`,
+          [ulid(), row.queue, row.job_name, row.payload],
+        )
+        await tx.execute(`DELETE FROM "strav_failed_jobs" WHERE id = $1`, [row.id])
+      }
+      return rows
+    })
+
+    if (moved.length === 0) {
+      if (all) this.info('No failed jobs to retry.')
+      else this.warn(`No failed job with id "${id}".`)
+      return ExitCode.Success
+    }
+    this.success(`Re-enqueued ${moved.length} job(s).`)
+    for (const row of moved) this.line(`  ↻ ${row.id}  ${row.job_name}`)
+    return ExitCode.Success
+  }
+}

package/src/console/queue_work.ts

@@ -0,0 +1,85 @@
+/**
+ * `bun strav queue:work [--max=N]` — drain jobs forever (or up to N).
+ *
+ * Resolves the container-bound `Worker`. Apps construct the `Worker` in
+ * their provider (it needs `db`, `registry`, `container`, plus the
+ * `queues` slice config) — the command just drives it.
+ *
+ * Signal handling: registers `SIGINT` + `SIGTERM` listeners that abort
+ * the worker's loop. The Worker's own graceful-shutdown semantics
+ * (drain in-flight jobs, release SKIP LOCKED rows) handle the rest.
+ *
+ * `--max=N` exits after N completed jobs — useful for hosted runtimes
+ * (Render workers, supervised tasks) that prefer "exit cleanly so the
+ * supervisor restarts you" over an unbounded loop. When N is set we
+ * loop on `processOne()` so we can count cleanly; otherwise we hand
+ * off to `worker.run(signal)`.
+ */
+
+import { Command, type ExecuteArgs, ExitCode, UsageError } from '@strav/cli'
+import { Worker } from '../worker.ts'
+
+export class QueueWork extends Command {
+  static signature = 'queue:work {--queue=default} {--max=}'
+  static description = 'Run a queue worker until interrupted (or --max=N jobs).'
+  // Boot the full default list — the Worker pulls Database, JobRegistry,
+  // Logger, and any app-registered services through the container at
+  // resolution time.
+
+  override async execute({ flags }: ExecuteArgs): Promise<number> {
+    const maxStr = flags.max
+    let max: number | null = null
+    if (typeof maxStr === 'string' && maxStr.length > 0) {
+      const parsed = Number.parseInt(maxStr, 10)
+      if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new UsageError(`--max must be a positive integer (got "${maxStr}")`)
+      }
+      max = parsed
+    }
+
+    const worker = this.app.resolve(Worker)
+    const controller = new AbortController()
+    const sigint = () => controller.abort()
+    const sigterm = () => controller.abort()
+    process.once('SIGINT', sigint)
+    process.once('SIGTERM', sigterm)
+
+    this.info(`Worker started — queue=${flags.queue}${max !== null ? `, max=${max}` : ''}.`)
+    try {
+      if (max === null) {
+        await worker.run(controller.signal)
+      } else {
+        // Bounded loop — `processOne()` returns null when nothing's claimable;
+        // sleep briefly so we don't spin-poll an empty queue.
+        let processed = 0
+        while (processed < max && !controller.signal.aborted) {
+          const result = await worker.processOne()
+          if (result === null) {
+            await sleep(1000, controller.signal)
+            continue
+          }
+          processed++
+        }
+        this.info(`Stopped after ${processed} job(s).`)
+      }
+      return ExitCode.Success
+    } finally {
+      process.off('SIGINT', sigint)
+      process.off('SIGTERM', sigterm)
+    }
+  }
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms)
+    signal.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer)
+        resolve()
+      },
+      { once: true },
+    )
+  })
+}

package/src/console/scheduler_list.ts

@@ -0,0 +1,27 @@
+/**
+ * `bun strav scheduler:list` — table of every registered scheduled entry.
+ *
+ * Read-only / pure introspection — never dispatches.
+ */
+
+import { Command, ExitCode } from '@strav/cli'
+import { Scheduler } from '../scheduler.ts'
+
+export class SchedulerList extends Command {
+  static signature = 'scheduler:list'
+  static description = 'List registered scheduler entries.'
+
+  override execute(): number {
+    const scheduler = this.app.resolve(Scheduler)
+    const entries = scheduler.all()
+    if (entries.length === 0) {
+      this.info('No schedules registered.')
+      return ExitCode.Success
+    }
+    this.table(
+      ['Name', 'Cron', 'Job', 'OneServer'],
+      entries.map((e) => [e.name, e.cron.expression, e.job.jobName, e.oneServer ? 'yes' : 'no']),
+    )
+    return ExitCode.Success
+  }
+}

package/src/console/scheduler_run.ts

@@ -0,0 +1,31 @@
+/**
+ * `bun strav scheduler:run <name>` — force-dispatch one named entry on demand.
+ *
+ * Bypasses the cron expression. When the entry was registered with
+ * `oneServer: true`, the advisory lock + run-tracking row still apply,
+ * so two `scheduler:run` invocations from different machines can't
+ * double-dispatch.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { Scheduler } from '../scheduler.ts'
+
+export class SchedulerRun extends Command {
+  static signature = 'scheduler:run {name}'
+  static description = 'Force-run one named schedule entry.'
+
+  override async execute({ args }: ExecuteArgs): Promise<number> {
+    const name = args.name
+    if (!name) return ExitCode.UsageError // unreachable: bindArgv already enforced
+
+    const scheduler = this.app.resolve(Scheduler)
+    try {
+      await scheduler.runEntry(name)
+    } catch (err) {
+      this.error((err as Error).message)
+      return ExitCode.UsageError
+    }
+    this.success(`Dispatched "${name}".`)
+    return ExitCode.Success
+  }
+}