@nightowlsdev/runner-background

`createBackgroundRunner({ engine, storage, backend })` returns the core `Runner` whose durable task body loops `engine.run`/`engine.resume`, opening a parkable waitpoint (keyed by `followupId`) on each `ask` suspend so a human-in-the-loop turn can park (default `askTimeout` 7d) and resume across process death; `run()` streams live progress over Supabase Realtime rather than an HTTP task stream. The whole vendor surface reduces to a 3-verb `DurableBackend` seam (enqueueRun / createWaitpoint / completeWaitpoint), with three implementations: `createTriggerBackend` (Trigger.dev v4 waitpoints, with `runDurableTask` + `registerBackgroundSwarm`/`getRegisteredSwarm` for the deployed task), `createVercelBackend` (Vercel Workflow hooks, host-injected callables), and an in-memory backend for hermetic tests. `@trigger.dev/sdk` and `workflow` are optional peers (wire exactly one). FR-061: the Vercel Workflow durable body now ships in-package, so instead of hand-writing the workflow you import `swarmWorkflow` from the `@nightowlsdev/runner-background/vercel-workflow` subpath, and `createVercelBackend` gains a `cancelRun` when you inject a `cancelWorkflow` callable; long segments still need Trigger, because a single `@workflow/next` step tops out around 800s. FR-064: `reapStuckRuns` returns the count it actually REAPED (not the rows it selected) and takes an `onReapError({ runId, error })` callback, so a host learns which runs are still stuck instead of losing them in an aggregate. It asserts the backend is the single retry owner. It never imports `@mastra/*` and re-exports no Mastra types (the engine wall).

runner-background is the DURABLE runner for a core swarm: it runs a turn inside durable background infrastructure (Trigger.dev v4 or Vercel Workflow) so an `ask`-suspended, human-in-the-loop run can park for hours or days and resume across process death. createBackgroundRunner({ engine, storage, backend }) returns the same core Runner interface, but instead of streaming the engine's iterable to the caller, the turn executes in the vendor's infra and the HTTP caller streams live progress over Realtime by subscribing to the persisted swarm_events. The whole vendor surface reduces to a three-verb DurableBackend seam, and it ships two production backends, an in-memory one for hermetic tests, a stuck-run reaper, and a timer-less recurrence plane.

createBackgroundRunner returns a Runner whose durable task body is a loop. engine.run(input, ctx) streams events; on an `ask` tool suspend the engine saves the Mastra snapshot to Postgres, sets the run suspended, and emits swarm.question. The body only READS that event to detect the suspend (it never re-appends — the engine is the sole event writer), opens backend.createWaitpoint keyed by the followupId (plus an FR-065 per-suspension salt so a re-suspended followup can't be woken with a prior suspension's completed token), persists the waitpoint id, and parks. When the host calls resume, the waitpoint resolves, the body calls engine.resume and loops; it terminates only on a terminal status. run() enqueues then yields storage.events.subscribe(runId) for live Realtime progress; resume() authorizes against storage.runs.findSuspended(ctx.tenantId, followupId), completes the waitpoint, and streams the durable continuation.

The wiring above builds ONE dedicated task. That is not the only supported shape. A durable body can be embedded in an existing, NON-scaffolded Trigger task by calling buildTaskBody({ engine, storage, backend }) directly inside that task's own run(), with the swarm registry bypassed entirely. This is supported: a host bolting durable agents onto a fleet of pre-existing background jobs does not have to restructure them into thin callers that enqueue() into one dedicated task. Nothing about the task handle is special — park() is a wait.forToken with no task affinity, maxDuration is never read by any runtime code, and the §12 single-retry-owner assert validates the host-process option object rather than the Trigger task's own retry config.

CONSTRAINT 1 — retry.maxAttempts must be 1 on any task hosting a durable body, and this is safety-critical rather than a scaffold preference. Trigger counts the first execution as an attempt, so maxAttempts: 1 is precisely what DISABLES reattempts. A task-level retry re-drives engine.run from scratch with no idempotency guard on runId, and storage.runs.create no-ops on conflict WITHOUT throwing, so the retry proceeds silently into a full fresh generation. The runner's ownership cell protects less than its name suggests: it gates runner-owned orchestration writes and waitpoint attachment only. The re-driven ENGINE independently writes its own events and its own status transitions (suspended / done / failed) after that losing create, without consulting the cell at all — so a retry can overwrite or duplicate persisted state, not merely emit a harmless duplicate event. Worse, the waitpoint's identity is `${runId}:${toolCallId}` and toolCallId is minted fresh by a re-drive, so a retry produces a new followupId, a new createWaitpoint key and a new token, and ORPHANS the original park's attached token — one run left advertising two answerable asks, one of which nothing is driving. The package's own test suite proves this split rather than asserting it in prose.

CONSTRAINT 2 — getRegisteredSwarm() is an unkeyed, last-write-wins singleton scoped to one loaded module instance. Its factory and cache are unkeyed module-scope globals, and registerBackgroundSwarm replaces the factory and clears the cache, so whichever registration runs last within that runtime/module instance wins (do not assume every vendor task bundle necessarily shares one). A host embedding many tasks should register the swarm ONCE and call buildTaskBody directly in every other task, bypassing the registry — never call registerBackgroundSwarm more than once per deployed bundle or module instance, because the second call silently redefines what every other task resolves.

CONSTRAINT 3 — cancelRun's native-kill tag is enqueue-side only, and a manually-triggered task CAN stamp it itself. createTriggerBackend().enqueueRun stamps ngorun-<runId> on the vendor run and cancelRun finds and kills the run by that tag; a task you trigger yourself is not tagged by that path, so stamp the same tag from inside your own run() with tags.add(). That is the fix, not merely a caveat. Without it native cancellation finds nothing tagged, the task receives NO cancellation signal at all and keeps running — a correctness and side-effect hazard, not just wasted compute. Its tool side effects continue, and it can subsequently overwrite the already-written failed / run_cancelled row with suspended, done, or another terminal while emitting later events; the earlier cancel write is not protected against that overwrite. Runner.cancel would then have recorded that it tried to cancel while nothing actually stopped. The tradeoff this trades TO, not just away from: stamping the tag makes the ENTIRE hosting Trigger run hard-cancellable, not just the agent's parked step — Runner.cancel ends in a real vendor kill of whatever run carries the tag. This integration wires no graceful handling by default, though Trigger v4 does give a cancelled task an aborted signal and an onCancel hook that may await cleanup for up to 30s before termination, which a host needing that can wire independently. On a host task that also does its own pre-existing work, an agent-level STOP can now terminate that job mid pre-work, mid agent execution, or after the agent returns but before your own post-work commits. There is no way to make a parked agent cancellable without this; keep the hosting task's pre/post work idempotent or compensable, and stamp the tag as late as reasonably possible — immediately before buildTaskBody's body(), not at the top of run() — to narrow (not eliminate) the window.

CONSTRAINT 4 — this shape effectively requires a waitpoint-capable storage implementation, not an arbitrary StorageAdapter. attachWaitpoint / getWaitpoint / clearWaitpoint are OPTIONAL on the public storage type, so an adapter without them satisfies the contract and still breaks this path: token attachment silently optional-chains to a no-op; resume optional-chains the read back and falls back to the followupId as the token id — valid for the Vercel backend, where the hook key IS the followupId, but NOT Trigger's own generated waitpoint_* token id, so a resume can complete the WRONG token and be falsely acknowledged as successful; and without clearWaitpoint a consumed token stays advertised as live. recordSuspend is required as well, or the followup is never resumable at all. Plainly: pattern (B) requires the conformant @nightowlsdev/storage-supabase implementation, which carries the followup/waitpoint migration — not any StorageAdapter implementation.

The one thing bypassing the registry costs you is that resolveTaskBodyArgs' field list stops carrying options on your behalf — pass bugCapture, release, maxReparks, compactDeltas, messageSearch and askTimeout to buildTaskBody yourself.

messageSearch: { plane, indexOnDriveEnd? } indexes the conversation's new messages after a durable drive completes. The plane is @nightowlsdev/storage-supabase's createMessageSearch({ pool, embedder, embedderTag, dimensions }); this package mirrors only the one method it calls (indexContainer — it never reads), so it takes on no dependency on pgvector or an embedder. indexOnDriveEnd defaults to TRUE: unlike compactDeltas, indexing only ever inserts into its own tables, so it deletes nothing a host might be treating as an audit trail.

This is the ONLY place a durable turn's messages get indexed. @nightowlsdev/runner-nextjs indexes when an INTERACTIVE turn ends, and it cannot cover the durable path: its runEnd fires at ENQUEUE, before the run has written a single message. A run driven here has no request behind it at all, so the drive's end is its only terminal. A deployment running both wires both, and the overlap is safe — the plane owns its own budget, cursor and per-(org, container, model) lock, so concurrent calls on one conversation serialize inside it rather than racing.

It is CONTAINED by construction. The call is awaited (nothing is waiting on this worker's latency, and a detached promise in a task body can be cut short the instant the task resolves) inside its own try/catch at the drive's finally, and every failure — a wrong-dimension schema, an embedder outage, an unwired table, a contended lock — is swallowed with a log. A throwing indexer can never fail the run, the resume, or the drive: the message is the product.

⚠ On the DEPLOYED Trigger path, set it on the registered swarm too. createTriggerBackend().enqueueRun ignores the task body it is handed — it only triggers the deployed task with { input, ctx }, and that task rebuilds its body from getRegisteredSwarm() inside Trigger's infra. A messageSearch passed only to createBackgroundRunner therefore reaches the in-process path and nothing on the deployed one: configured, documented, and inert. BackgroundSwarm carries the same field for exactly this reason, as bugCapture, release, maxReparks and compactDeltas each did before it — and as askTimeout does after it (FR-075, the sixth field to ride this hand-maintained seam and the fifth wave to do so — and the one that genuinely shipped inert, in 2.13.0). The Vercel Workflow path runs it as a 'use step'.