@toist/aja 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 All notable changes to `@toist/aja` are recorded here.
 
+## 0.8.0 — 2026-05-08
+
+Major refactor: `@toist/aja` is now the SQLite host package, with the
+execution kernel extracted to `@toist/core`.
+
+**New:**
+
+- `createSqliteRuntime({ rootDir, ... })` — durable runtime constructor.
+  Owns lock acquisition, migrations, db handle opening, store wiring,
+  registry projection, resource resolution. Returns a `ToistRuntime`
+  with `close()`.
+- `mountApi(runtime, options): Hono` factory replaces module-level
+  state in `server.ts`. `startRunner` builds a runtime then calls
+  `mountApi`.
+- `loadFilesystemResources(rootDir)` — reads `toist.yml`, performs
+  `${env:VAR}` and `${env:VAR:-default}` substitution, fails closed
+  at config-load time on missing required vars.
+- `kindAllowlist` field in `instance.json` filters the registry
+  projection at construction time. Glob support (`agent.*`).
+- `StartRunnerOptions.storage: "sqlite" | "memory"` flag.
+- `StartRunnerOptions.runtime?: ToistRuntime` late-bound injection.
+- `HostedRuntime` interface (extends `ToistRuntime` with optional
+  `close`, `adminDb`, `pipelinesDir`).
+- `createFilesystemPipelineStore({ rootDir, registry, watch })` for
+  YAML pipeline loading + watching.
+- `POST /api/runs` async ad-hoc spec-run endpoint.
+- `GET /api/runs/:id/events` SSE event stream.
+- `client.pipelines.runSpec(spec, payload)` and `client.runs.events(runId)`.
+- `/manifest` response carries `version` + `schema` URL for stable
+  downstream consumption.
+
+**Removed:**
+
+- `db-handles.ts`, `config.ts` (process-global `setRootDir` etc.),
+  `runtime.ts` (`createProcessRuntime`). Replaced by explicit
+  `createSqliteRuntime`.
+- Local `pipeline.ts`, `hitl.ts`, `runs.ts`, `kinds/{control,data,db,hitl,
+  http,runs,transform,types}.ts` — all moved to `@toist/core`.
+  `@toist/aja` re-exports the kernel surface.
+- Filesystem `resources/*.yaml` loader (replaced by `toist.yml`).
+
+**Renamed:**
+
+- `instance.ts` → `instance-metadata.ts` (frees the name for a possible
+  future `@toist/instance` package).
+
+**New dependency:** `@toist/core@0.8.0`.
+
 ## 0.7.1 — 2026-05-06
 
 Fix @toist/aja cross-package dependency versions not being bumped by release script
@@ -77,7 +125,7 @@ monorepo per Phase F W2 and shipped to the Gitea npm registry per W3.
 
 - Public API: `startRunner(options): Promise<RunnerHandle>`,
   `register(...kinds)`, `getKind(id)`, `manifest()`. See instance-spec at
-  https://toist.in for the full contract.
+  https://toist.in/docs for the full contract.
 - HTTP server (Hono on Bun) — mounts API at `/api/*` and serves the
   bundled UI from `@toist/ui`'s `distDir` at `/`.
 - Pipeline dispatcher with HITL-aware suspendable executor (per-node

package/README.md

@@ -0,0 +1,62 @@
+# `@toist/aja`
+
+Durable Toist host surface: SQLite runtime, HTTP runner, UI mount, filesystem helpers, and the typed runner client.
+
+```ts
+import { startRunner } from "@toist/aja"
+
+await startRunner({
+  rootDir: import.meta.dir,
+  port: 3000,
+})
+```
+
+## Main exports
+
+- `startRunner(options)`
+- `createSqliteRuntime(options)`
+- `createFilesystemPipelineStore({ rootDir, watch? })`
+- `loadFilesystemResources(rootDir)`
+- `createRunnerClient({ baseUrl })`
+- convenience re-exports from `@toist/core`
+
+## Client quickstart
+
+```ts
+import { createRunnerClient } from "@toist/aja"
+
+const client = createRunnerClient({ baseUrl: "http://localhost:3000" })
+const started = await client.pipelines.runSpec(spec, { name: "world" })
+for await (const event of client.runs.events(started.id)) {
+  console.log(event.type)
+}
+```
+
+## Runtime layout
+
+With `startRunner({ rootDir, port })`, the runner:
+
+- loads pipelines from `<rootDir>/pipelines`
+- stores runtime state under `<rootDir>/data`
+- reads resources from `<rootDir>/toist.yml`
+- serves UI + API from one Bun process
+
+## `/manifest`
+
+`GET /api/manifest` returns stable JSON for tooling:
+
+```json
+{
+  "version": 1,
+  "schema": "https://toist.in/schemas/manifest-v1.json",
+  "kinds": []
+}
+```
+
+## Resources
+
+`loadFilesystemResources(rootDir)` reads `toist.yml` and resolves `${env:VAR}` and `${env:VAR:-fallback}` substitutions.
+
+## When to use `@toist/aja`
+
+Use it when you want a durable single-tenant runner with HTTP APIs. For in-process execution without the server, import `@toist/core` directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toist/aja",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -14,15 +14,17 @@
   "files": [
     "src/",
     "migrations/",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "README.md"
   ],
   "scripts": {
     "dev": "bun --watch src/server.ts",
     "smoke:client": "bun test/client-smoke.ts"
   },
   "dependencies": {
-    "@toist/spec": "0.7.1",
-    "@toist/ui": "0.7.1",
+    "@toist/core": "0.8.0",
+    "@toist/spec": "0.8.0",
+    "@toist/ui": "0.8.0",
     "hono": "^4.7.7",
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.8.4"

package/src/cache-db.ts

@@ -1,17 +1,9 @@
 // 2121
-// Cache database — separate file from runtime.db so its drop-recreate
-// semantics (TTL makes content valueless) do not entangle runtime durability.
-//
-// Schema is owned and bootstrapped by makeCache() in cache.ts. No migrations
-// here: cache table can be dropped or recreated freely.
-
 import { Database } from "bun:sqlite"
 import { mkdirSync } from "node:fs"
 import { dirname } from "node:path"
-import { cacheDbPath } from "./config.ts"
 
-export function openCacheDb(): Database {
-  const path = cacheDbPath()
+export function openCacheDb(path: string): Database {
   mkdirSync(dirname(path), { recursive: true })
   return new Database(path, { create: true })
 }

package/src/cli.ts

@@ -9,7 +9,7 @@
 import { existsSync, readFileSync } from "node:fs"
 import { dirname, isAbsolute, resolve } from "node:path"
 import YAML from "yaml"
-import { register, startRunner } from "./index.ts"
+import { createSqliteRuntime, register, startRunner } from "./index.ts"
 
 // ---------------------------------------------------------------------------
 // Config schema
@@ -22,8 +22,8 @@ interface ToistConfig {
   root?: string
   /** Pipeline YAML directory. Default: <root>/pipelines */
   pipelines?: string
-  /** Resource YAML directory. Default: <root>/resources */
-  resources?: string
+  /** Resource path override (legacy). Default: <root>/resources */
+  resources?: string | Record<string, Record<string, unknown>>
   /** Data directory (SQLite files). Default: <root>/data */
   data?: string
   /** TypeScript kind files to import and register before starting. */
@@ -59,7 +59,7 @@ if (args.includes("--help") || args.includes("-h")) {
   console.log("Environment:")
   console.log("  TOIST_PORT / PORT        Override port from config")
   console.log("")
-  console.log("Full docs: https://toist.in")
+  console.log("Full docs: https://toist.in/docs")
   process.exit(0)
 }
 
@@ -113,7 +113,7 @@ const cfg        = (YAML.parse(raw) ?? {}) as ToistConfig
 const root = cfg.root ? resolve(configDir, cfg.root) : configDir
 
 const pipelineDir = resolvePath(configDir, root, cfg.pipelines, "pipelines")
-const resourceDir = resolvePath(configDir, root, cfg.resources, "resources")
+const resourceDir = resolvePath(configDir, root, typeof cfg.resources === "string" ? cfg.resources : undefined, "resources")
 const dataDir     = resolvePath(configDir, root, cfg.data,      "data")
 const port        = Number(process.env.TOIST_PORT ?? process.env.PORT ?? cfg.port ?? 3000)
 
@@ -135,13 +135,19 @@ if (cfg.kinds && cfg.kinds.length > 0) {
   }
 }
 
+void cfg.disableMcp
+
+const runtime = await createSqliteRuntime({
+  rootDir: root,
+  pipelinesDir: pipelineDir,
+  resourcesDir: resourceDir,
+  dataDir,
+})
+
 await startRunner({
   port,
-  rootDir:      root,
-  pipelineDir,
-  resourceDir,
-  dataDir,
-  disableUi:    cfg.disableUi    ?? false,
+  rootDir: root,
+  runtime,
+  disableUi: cfg.disableUi ?? false,
   disableWatch: cfg.disableWatch ?? false,
-  disableMcp:   cfg.disableMcp   ?? false,
 })

package/src/client.ts

@@ -5,6 +5,7 @@
 // that want to drive the runner over its HTTP API without hard-coding paths.
 
 import type { NodeKindManifest, ValidateResult } from "@toist/spec"
+import type { ToistEvent } from "@toist/core"
 
 export interface RunnerClientOptions {
   /** Runner API base URL. Accepts either the API root
@@ -74,6 +75,12 @@ export type PipelineRunResponse =
   | { id: number; pipeline: string; status: "suspended"; suspendedAt: string; task: PipelineTaskRef; steps: StepResult[] }
   | { id: number; pipeline: string; status: "error"; error: string }
 
+export interface AsyncRunStartResponse {
+  id: number
+  pipeline: string
+  status: "running"
+}
+
 export interface RunListItem {
   id: number
   pipeline: string
@@ -161,12 +168,14 @@ export interface RunnerClient {
     create(yaml: string): Promise<PipelineSaveResult>
     update(id: string, yaml: string): Promise<PipelineSaveResult>
     run(id: string, payload?: Record<string, unknown>): Promise<PipelineRunResponse>
+    runSpec(spec: unknown, payload?: Record<string, unknown>): Promise<AsyncRunStartResponse>
   }
   runs: {
     list(opts?: { pipeline?: string; limit?: number }): Promise<RunListItem[]>
     get(id: number): Promise<RunListItem>
     nodes(id: number): Promise<RunNodeOutput[]>
     logs(id: number): Promise<RunLogLine[]>
+    events(id: number): AsyncIterable<ToistEvent>
   }
   tasks: {
     list(opts?: { status?: string; runId?: number; assignee?: string; limit?: number }): Promise<TaskListItem[]>
@@ -234,6 +243,10 @@ export function createRunnerClient(options: RunnerClientOptions): RunnerClient {
         method: "POST",
         body: json(payload),
       }),
+      runSpec: (spec, payload = {}) => request<AsyncRunStartResponse>("/runs", {
+        method: "POST",
+        body: json({ spec, payload }),
+      }),
     },
 
     runs: {
@@ -241,6 +254,7 @@ export function createRunnerClient(options: RunnerClientOptions): RunnerClient {
       get:   (id) => request<RunListItem>(`/runs/${id}`),
       nodes: (id) => request<RunNodeOutput[]>(`/runs/${id}/nodes`),
       logs:  (id) => request<RunLogLine[]>(`/runs/${id}/logs`),
+      events: (id) => streamEvents(f, `${base}/runs/${id}/events`, options.headers),
     },
 
     tasks: {
@@ -303,3 +317,65 @@ async function readJsonOrText(response: Response): Promise<unknown> {
   try { return JSON.parse(text) }
   catch { return text }
 }
+
+function streamEvents(
+  f: typeof fetch,
+  url: string,
+  extraHeaders?: HeadersInit,
+): AsyncIterable<ToistEvent> {
+  return {
+    [Symbol.asyncIterator]() {
+      let reader: ReadableStreamDefaultReader<Uint8Array> | null = null
+      let buffer = ""
+      const decoder = new TextDecoder()
+      const queue: ToistEvent[] = []
+      let finished = false
+
+      async function ensureReader() {
+        if (reader) return reader
+        const headers = new Headers(extraHeaders)
+        headers.set("accept", "text/event-stream")
+        const response = await f(url, { headers })
+        if (!response.ok) {
+          const body = await readJsonOrText(response)
+          throw new RunnerHttpError(response.status, response.statusText, body)
+        }
+        if (!response.body) throw new Error("runner returned no SSE body")
+        reader = response.body.getReader()
+        return reader
+      }
+
+      async function pump(): Promise<void> {
+        const r = await ensureReader()
+        while (queue.length === 0 && !finished) {
+          const { value, done } = await r.read()
+          if (done) {
+            finished = true
+            return
+          }
+          buffer += decoder.decode(value, { stream: true })
+          let boundary = buffer.indexOf("\n\n")
+          while (boundary !== -1) {
+            const frame = buffer.slice(0, boundary)
+            buffer = buffer.slice(boundary + 2)
+            const data = frame
+              .split("\n")
+              .filter((line) => line.startsWith("data:"))
+              .map((line) => line.slice(5).trim())
+              .join("\n")
+            if (data) queue.push(JSON.parse(data) as ToistEvent)
+            boundary = buffer.indexOf("\n\n")
+          }
+        }
+      }
+
+      return {
+        async next(): Promise<IteratorResult<ToistEvent>> {
+          await pump()
+          if (queue.length > 0) return { value: queue.shift()!, done: false }
+          return { value: undefined as never, done: true }
+        },
+      }
+    },
+  }
+}

package/src/data-db.ts

@@ -1,21 +1,9 @@
 // 2121
-// Domain data store. The instance owns the schema entirely — every table here
-// is created by a pipeline (via db.insert) or by a domain migration the project
-// chooses to add. Platform never writes to this DB directly.
-//
-// Kinds receive this as `ctx.db`. Pipelines write to it (db.insert), read
-// from it (db.query), or any custom domain kind interacts with it as needed.
-//
-// Location: <dataDir>/data.db (per context/instance-spec.md §3 — the host's
-// schema-on-write domain DB lives in data/ alongside runtime.db and cache.db).
-
 import { Database } from "bun:sqlite"
 import { mkdirSync } from "node:fs"
 import { dirname } from "node:path"
-import { dataDbPath } from "./config.ts"
 
-export function openDataDb(): Database {
-  const path = dataDbPath()
+export function openDataDb(path: string): Database {
   mkdirSync(dirname(path), { recursive: true })
   return new Database(path, { create: true })
 }

package/src/index.ts

@@ -9,6 +9,9 @@
 
 // Lifecycle entry — what hosts call to start an instance.
 export { startRunner, type StartRunnerOptions, type RunnerHandle } from "./startRunner.ts"
+export { createSqliteRuntime, type CreateSqliteRuntimeOptions } from "./sqlite-runtime.ts"
+export { loadFilesystemResources } from "./resources-fs.ts"
+export { createFilesystemPipelineStore, type FilesystemPipelineStore } from "./pipeline-store.ts"
 
 // Typed HTTP client — what external hosts/tools use to drive an instance.
 export {
@@ -22,6 +25,7 @@ export {
   type StepResult,
   type PipelineTaskRef,
   type PipelineRunResponse,
+  type AsyncRunStartResponse,
   type RunListItem,
   type RunNodeOutput,
   type RunLogLine,
@@ -31,15 +35,44 @@ export {
   type ResourceRecord,
 } from "./client.ts"
 
-// Kind registration — must be called before startRunner.
-export { register, getKind, manifest } from "./kinds/index.ts"
+// Kernel convenience re-exports.
+export {
+  builtinKinds,
+  createRegistry,
+  createMemoryRuntime,
+  createEventStream,
+  runSpec,
+  register,
+  getKind,
+  manifest,
+} from "@toist/core"
 
 // Type re-exports from @toist/spec, so a host that imports only
 // @toist/aja doesn't need a second package on its dependency list when
 // it only writes kinds (rather than authoring pipeline-format tooling).
+export type {
+  ToistRuntime,
+  ResumableRuntime,
+  RunLedger,
+  TaskStore,
+  LogStore,
+  NodeOutputStore,
+  ResourceResolver,
+  KindRegistry,
+  RunCtx,
+  RunOutcome,
+  RunOptions,
+  ToistEvent,
+  EventSink,
+  RunSpecOptions,
+  RunSpecResult,
+} from "@toist/core"
+
 export type {
   NodeKind,
   NodeKindManifest,
+  DataHandle,
+  DataStatement,
   ParamDef,
   PortDef,
   ExecContext,

package/src/instance-metadata.ts

@@ -0,0 +1,48 @@
+// 2121
+// Per-instance metadata: what kind of platform-instance this is (which
+// customer, what tier, what teasers to surface), distinct from the runtime
+// state in runtime.db.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+export interface Teaser {
+  id:           string
+  title:        string
+  description?: string
+  category?:    string
+}
+
+export interface Instance {
+  platformVersion?: string
+  instanceName?:    string
+  tier?:            string
+  kindAllowlist?:   string[]
+  teasers:          Teaser[]
+}
+
+const DEFAULTS: Instance = { teasers: [] }
+
+// Re-read on every call. instance.json is tiny and changes rarely; the cost
+// is negligible and avoids stale-cache surprises when the file is edited.
+export function loadInstance(rootDir: string): Instance {
+  const path = join(rootDir, "instance.json")
+  if (!existsSync(path)) return DEFAULTS
+
+  try {
+    const raw = readFileSync(path, "utf8")
+    const parsed = JSON.parse(raw) as Partial<Instance>
+    return {
+      platformVersion: parsed.platformVersion,
+      instanceName: parsed.instanceName,
+      tier: parsed.tier,
+      kindAllowlist: Array.isArray(parsed.kindAllowlist)
+        ? parsed.kindAllowlist.filter((value): value is string => typeof value === "string")
+        : undefined,
+      teasers: Array.isArray(parsed.teasers) ? parsed.teasers : [],
+    }
+  } catch (err) {
+    console.warn(`[instance] failed to read ${path}:`, (err as Error).message)
+    return DEFAULTS
+  }
+}

package/src/kinds/index.ts

@@ -1,66 +1,28 @@
 // 2121
-import type { NodeKind, NodeKindManifest } from "./types.ts"
-import { dataJson, dataMerge } from "./data.ts"
-import { transformFilter, transformMap, transformSort, transformAggregate } from "./transform.ts"
-import { dbInsert, dbQuery } from "./db.ts"
-import { httpFetch, httpPost } from "./http.ts"
-import { trigger, sink } from "./control.ts"
-import { humanInput } from "./hitl.ts"
-import { runsLastOutput, runsNodeOutput, pipelineRun } from "./runs.ts"
+// Aja-side kind registry shim.
+//
+// Builtins and registry implementation now live in @toist/core. Aja keeps
+// this module so existing local imports and custom kind registration patterns
+// continue to work during the package carve-out.
 
-const builtins: NodeKind<any, any>[] = [
-  trigger,
-  sink,
-  dataJson,
-  dataMerge,
-  transformFilter,
-  transformMap,
-  transformSort,
-  transformAggregate,
-  dbInsert,
-  dbQuery,
-  httpFetch,
-  httpPost,
-  humanInput,
-  runsLastOutput,
-  runsNodeOutput,
-  pipelineRun,
-]
+export {
+  builtinKinds,
+  createRegistry,
+  register,
+  getKind,
+  manifest,
+} from "@toist/core"
 
-export const registry: Map<string, NodeKind<any, any>> = new Map(builtins.map((k) => [k.id, k]))
+export type {
+  NodeKind,
+  NodeKindManifest,
+  DataHandle,
+  DataStatement,
+  ParamDef,
+  PortDef,
+  ExecContext,
+  PlatformCtx,
+} from "@toist/spec"
 
-/**
- * Register one or more custom domain kinds. Domain projects edit
- * `runner/src/kinds/custom.ts` (created by `platform init`) and call
- * `register(...)` there with their own kinds. Builtin kinds and domain kinds
- * live in the same registry — `getKind(id)` resolves both transparently.
- *
- * Re-registering an existing id replaces the previous entry; useful for hot
- * iteration but warn loudly so accidental shadows are visible.
- */
-export function register(...kinds: NodeKind<any, any>[]): void {
-  for (const k of kinds) {
-    if (registry.has(k.id) && !builtins.find((b) => b.id === k.id)) {
-      console.warn(`[kinds] re-registering "${k.id}" — previous registration replaced`)
-    }
-    registry.set(k.id, k)
-  }
-}
-
-export function getKind(id: string): NodeKind<any, any> | undefined {
-  return registry.get(id)
-}
-
-export function manifest(): NodeKindManifest[] {
-  return [...registry.values()].map(({ run: _e, ...rest }) => rest)
-}
-
-export type { NodeKind, NodeKindManifest, ParamDef, PortDef, ExecContext, PlatformCtx } from "./types.ts"
-
-// Side-effect import: domain kinds register themselves when this module loads.
-// Dynamic import + top-level await defers custom.ts evaluation until AFTER
-// `registry` and `register` are initialised — a static `import "./custom.ts"`
-// gets hoisted ahead of the const init, putting `registry` in the temporal
-// dead zone when custom.ts calls register(). The dynamic form runs at
-// statement position, after init, breaking the cycle.
+// Preserve the old side-effect registration hook for domain kinds.
 await import("./custom.ts")

package/src/lock.ts

@@ -1,64 +1,38 @@
 // 2121
-// Single-leader runner lock. Prevents two runner processes from racing on
-// migrations, scheduled cron-wheel firings, or HITL resume dispatch.
-//
-// The lock guards the data/ directory using a sentinel lockfile at
-// data/.lock. proper-lockfile creates a holder directory that includes mtime;
-// stale locks (from a crashed previous process) are detected after `stale` ms
-// and overtaken automatically.
-//
-// Watch-mode reload tolerance: bun --watch SIGTERMs the old process before
-// spawning the new one. The cleanup handlers below release the lock on
-// SIGTERM/SIGINT/exit. Async lock acquisition with retries handles the brief
-// window where the old process has not yet released.
-
 import lockfile from "proper-lockfile"
 import { mkdirSync } from "node:fs"
-import { dataDir, lockfilePath } from "./config.ts"
 
-let release: (() => Promise<void>) | null = null
+export interface AcquireRunnerLockOptions {
+  dir: string
+  lockfilePath: string
+}
 
-export async function acquireRunnerLock(): Promise<void> {
-  const dir = dataDir()
-  const lockPath = lockfilePath()
-  mkdirSync(dir, { recursive: true })
+export async function acquireRunnerLock(opts: AcquireRunnerLockOptions): Promise<() => Promise<void>> {
+  mkdirSync(opts.dir, { recursive: true })
 
-  try {
-    release = await lockfile.lock(dir, {
-      lockfilePath: lockPath,
-      realpath: false,
-      stale: 10_000,
-      retries: { retries: 5, factor: 2, minTimeout: 100, maxTimeout: 1000 },
-    })
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err)
-    console.error(`[runner] failed to acquire ${lockPath}: ${msg}`)
-    console.error(`[runner] another runner appears live. Stop it first; only one runner per project is allowed.`)
-    process.exit(1)
-  }
+  let release = await lockfile.lock(opts.dir, {
+    lockfilePath: opts.lockfilePath,
+    realpath: false,
+    stale: 10_000,
+    retries: { retries: 5, factor: 2, minTimeout: 100, maxTimeout: 1000 },
+  })
 
-  const cleanup = (): void => {
-    if (!release) return
-    const r = release
-    release = null
-    r().catch(() => { /* best-effort */ })
+  let released = false
+  const cleanup = async () => {
+    if (released) return
+    released = true
+    const current = release
+    release = async () => {}
+    try {
+      await current()
+    } catch {
+      // best-effort cleanup on process exit / stop
+    }
   }
 
-  process.on("exit",    cleanup)
-  process.on("SIGTERM", () => { cleanup(); process.exit(0) })
-  process.on("SIGINT",  () => { cleanup(); process.exit(0) })
-}
+  process.on("exit", () => { void cleanup() })
+  process.on("SIGTERM", () => { void cleanup() })
+  process.on("SIGINT", () => { void cleanup() })
 
-/** Release the runner lock explicitly. Used by `startRunner`'s graceful
- *  `stop()` path. Idempotent: no-op if the lock is not held. The signal
- *  cleanup handlers installed by acquireRunnerLock remain in place. */
-export async function releaseRunnerLock(): Promise<void> {
-  if (!release) return
-  const r = release
-  release = null
-  try {
-    await r()
-  } catch {
-    // best-effort — surfacing this would mask the actual stop reason
-  }
+  return cleanup
 }