okengine 0.22.0 → 0.23.0

package/site/content/docs/reference/fx.mdx

@@ -240,12 +240,13 @@ elements.
 
 ## AI
 
-| Signature                                             | Records                   | Returns                                                                                                  |
-| ----------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `fx.ask(prompt, input?, { via?, tools?, maxSteps? })` | `ask` (+ `call` per tool) | Object validated against the prompt's `out`                                                              |
-| `fx.run(agent, input?)`                               | `ask`                     | Agent result                                                                                             |
-| `fx.stream(model, { prompt?, data?, via? })`          | `ask`                     | `AsyncIterable<string>` — real driver stream; cancels via ambient `fx.signal` (HTTP disconnect included) |
-| `fx.search(embed, query, { topK? })`                  | `read`                    | Matches from the index/embed                                                                             |
+| Signature                                             | Records                   | Returns                                                                                                                             |
+| ----------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `fx.ask(prompt, input?, { via?, tools?, maxSteps? })` | `ask` (+ `call` per tool) | Object validated against the prompt's `out`                                                                                         |
+| `fx.run(agent, input?)`                               | `ask`                     | Agent result                                                                                                                        |
+| `fx.stream(model, { prompt?, data?, via? })`          | `ask`                     | `AsyncIterable<string>` — real driver stream; cancels via ambient `fx.signal` (HTTP disconnect included)                            |
+| `fx.search(embed, query, { topK? })`                  | `read`                    | Matches from the index/embed                                                                                                        |
+| `fx.decide(decision, input)`                          | `decide`                  | `$.<question>.how` is `auto`, `reviewed`, or `abstained`. `audited` is a boolean flag, not a `how`. Abstain makes the value `null`. |
 
 AI calls are nondeterministic: journaling is forced on and auto-cache disabled around them. `tools` are Flow refs — each model tool call goes through `fx.call` (same capability and Runs path).
 

package/src/auth/api-key-sql.test.ts

@@ -44,4 +44,48 @@ describe("api-key SQL persist", () => {
     expect(other.keys.get("key_sql")?.creatorId).toBe("u1");
     expect(other.keys.get("key_sql")?.hash).toBe(created.row.hash);
   });
+
+  test("authenticate reloads an oke_ secret missing from memory", async () => {
+    const { authenticateApiKey } = await import("./api-keys.ts");
+    const rows = new Map<string, Record<string, unknown>>();
+    const sql: ApiKeySqlExec = {
+      async execute(_q, params) {
+        const id = String(params[0]);
+        rows.set(id, {
+          id,
+          plane: params[1],
+          hash: params[2],
+          name: params[3],
+          scopes: params[4],
+          expires_at: params[5],
+          rate_limit: params[6],
+          ip_allowlist: params[7],
+          creator_id: params[8],
+          creator_scopes: params[9],
+          created_at: params[10],
+          last_used_at: params[11],
+          revoked_at: params[12],
+        });
+      },
+      async all() {
+        return [...rows.values()];
+      },
+    };
+    const writer = createApiKeyStore({ pepper: "shared" });
+    bindApiKeySqlPersist(writer, sql);
+    const created = await createApiKey(writer, {
+      plane: "user",
+      name: "Auth Test",
+      scopes: ["member"],
+      creatorId: "user_admin",
+      creatorScopes: ["member"],
+      id: "key_live",
+    });
+    const reader = createApiKeyStore({ pepper: "shared" });
+    bindApiKeySqlPersist(reader, sql);
+    expect(reader.keys.size).toBe(0);
+    const row = await authenticateApiKey(reader, created.secret);
+    expect(row?.id).toBe("key_live");
+    expect(reader.keys.has("key_live")).toBe(true);
+  });
 });

package/src/auth/api-key-sql.ts

@@ -97,6 +97,7 @@ export function bindApiKeySqlPersist(
   table: string = AUTH_TABLES.apiKeys,
 ): void {
   store.persist = (row) => persistApiKeyRow(sql, row, table);
+  store.reload = () => hydrateApiKeyStore(sql, store, table);
 }
 
 /** Runtime that can open the app's shared primary SQL connection. */

package/src/auth/api-keys.ts

@@ -85,6 +85,11 @@ export interface ApiKeyStore {
   pepper?: string;
   /** Optional write-through persist (SQL). */
   persist?: (row: ApiKeyRow) => void | Promise<void>;
+  /**
+   * Reload rows from the durable table. `oke dev` keeps Console and the app
+   * in separate processes; a miss on an `oke_` secret refreshes this cache.
+   */
+  reload?: () => void | Promise<void>;
   /** Sliding-window hits for per-key rateLimit (subject = key id). */
   rateHits?: Map<string, number[]>;
 }
@@ -202,20 +207,33 @@ export async function authenticateApiKey(
   const now = options.now ?? (() => Date.now());
   const pepper = store.pepper ?? DEFAULT_PEPPER;
   const hash = await hashApiKeySecret(secret, pepper);
-  for (const row of store.keys.values()) {
-    if (row.hash !== hash) continue;
-    if (row.revokedAt !== null) return null;
-    if (row.expiresAt !== null && row.expiresAt <= now()) return null;
-    if (row.ipAllowlist.length > 0) {
-      const allowed = await allowlistAllowsIp(row.ipAllowlist, options.ip, options.lookup);
-      if (!allowed) return null;
+  let row = matchApiKeyHash(store, hash);
+  if (!row && secret.startsWith("oke_") && store.reload) {
+    try {
+      await store.reload();
+    } catch {
+      // Durable read missed — the in-memory miss still stands.
     }
-    if (row.rateLimit && !takeKeyRate(store, row.id, row.rateLimit, now())) return null;
-    row.lastUsedAt = now();
-    await persistRow(store, row);
-    return row;
+    row = matchApiKeyHash(store, hash);
+  }
+  if (!row) return null;
+  if (row.revokedAt !== null) return null;
+  if (row.expiresAt !== null && row.expiresAt <= now()) return null;
+  if (row.ipAllowlist.length > 0) {
+    const allowed = await allowlistAllowsIp(row.ipAllowlist, options.ip, options.lookup);
+    if (!allowed) return null;
+  }
+  if (row.rateLimit && !takeKeyRate(store, row.id, row.rateLimit, now())) return null;
+  row.lastUsedAt = now();
+  await persistRow(store, row);
+  return row;
+}
+
+function matchApiKeyHash(store: ApiKeyStore, hash: string): ApiKeyRow | undefined {
+  for (const row of store.keys.values()) {
+    if (row.hash === hash) return row;
   }
-  return null;
+  return undefined;
 }
 
 /**

package/src/auth/config.ts

@@ -4,6 +4,7 @@
  * Better Auth is inspiration for shape only; this is OKE-native.
  */
 
+import { createEnv } from "../runtime/primitives.ts";
 import type { PasswordHashOptions } from "../runtime/types.ts";
 import type { SessionStore } from "./sessions.ts";
 import { createApiKeyStore, type ApiKeyStore } from "./api-keys.ts";
@@ -226,9 +227,12 @@ export function mintDevAuthSecret(): string {
 export function resolveGateAuth(options: ResolveGateAuthOptions): ResolvedGateAuth {
   const { auth, env } = options;
   const isProd = env === "prod" || env === "production";
-  let secret = auth.secret;
+  let secret = auth.secret?.trim() ?? "";
   let secretMinted = false;
-  if (!secret || secret.length === 0) {
+  if (secret.length === 0) {
+    secret = createEnv().get("OKE_AUTH_SECRET")?.trim() ?? "";
+  }
+  if (secret.length === 0) {
     if (isProd) {
       throw new Error(
         "gate.auth: secret is required in production (set gate.auth.secret or OKE_AUTH_SECRET)",

package/src/auth/gate-auth.test.ts

@@ -21,13 +21,33 @@ afterEach(() => {
 });
 
 describe("gate.auth — config", () => {
+  const prevAuthSecret = process.env.OKE_AUTH_SECRET;
+
+  afterEach(() => {
+    if (prevAuthSecret === undefined) delete process.env.OKE_AUTH_SECRET;
+    else process.env.OKE_AUTH_SECRET = prevAuthSecret;
+  });
+
   test("prod without secret fails", () => {
+    delete process.env.OKE_AUTH_SECRET;
     expect(() =>
       resolveGateAuth({ auth: { emailAndPassword: { enabled: true } }, env: "prod" }),
     ).toThrow(/secret is required/);
   });
 
+  test("OKE_AUTH_SECRET is the pepper when gate.auth.secret is omitted", () => {
+    process.env.OKE_AUTH_SECRET = "shared-dev-pepper";
+    const resolved = resolveGateAuth({
+      auth: { emailAndPassword: { enabled: true } },
+      env: "dev",
+    });
+    expect(resolved.secret).toBe("shared-dev-pepper");
+    expect(resolved.secretMinted).toBe(false);
+    expect(resolved.apiKeyStore.pepper).toBe("shared-dev-pepper");
+  });
+
   test("dev mints secret", () => {
+    delete process.env.OKE_AUTH_SECRET;
     const resolved = resolveGateAuth({
       auth: { emailAndPassword: { enabled: true } },
       env: "dev",

package/src/cli/agents-md.test.ts

@@ -0,0 +1,25 @@
+/**
+ * Commands named in the agent contract must exist on the CLI.
+ */
+
+import { readFileSync } from "node:fs";
+import { describe, expect, test } from "bun:test";
+import { commandNames } from "./registry.ts";
+
+describe("AGENTS.md commands", () => {
+  test("every oke command mentioned in AGENTS.md is registered", () => {
+    const text = readFileSync(new URL("../../AGENTS.md", import.meta.url), "utf8");
+    const registered = new Set(commandNames());
+    const mentioned = new Set<string>();
+    for (const match of text.matchAll(/`oke ([a-z][a-z0-9-]*)/g)) {
+      const name = match[1];
+      if (name) mentioned.add(name);
+    }
+    expect(mentioned.has("eval")).toBe(true);
+    expect(mentioned.has("decide")).toBe(true);
+    expect(text).not.toContain("oke decide certify");
+    for (const name of mentioned) {
+      expect(registered.has(name)).toBe(true);
+    }
+  });
+});

package/src/cli/ask-vault-gaps.test.ts

@@ -3,12 +3,14 @@
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
+import { EventEmitter } from "node:events";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { resetRequiredEnvNames, resetSecrets } from "../elements/vault/declare.ts";
 import { resetBindings } from "../kernel/on.ts";
-import { maybeAskVaultGaps, probeVaultGaps } from "./ask-vault-gaps.ts";
+import { maybeAskVaultGaps, probeVaultGaps, secretPromptWrite } from "./ask-vault-gaps.ts";
+import { promptHidden } from "./vault-secure-input.ts";
 
 const OKE = resolve(import.meta.dir, "../index.ts");
 
@@ -93,6 +95,41 @@ describe("maybeAskVaultGaps", () => {
   });
 });
 
+describe("secretPromptWrite", () => {
+  test("keeps the mask on the prompt line", async () => {
+    const stdin = new EventEmitter() as EventEmitter & {
+      setRawMode?: (mode: boolean) => void;
+      off?: (event: string, listener: (...args: unknown[]) => void) => EventEmitter;
+    };
+    stdin.setRawMode = () => undefined;
+    stdin.off = (event: string | symbol, listener: (...args: unknown[]) => void) => {
+      stdin.removeListener(event, listener);
+      return stdin;
+    };
+    const shown: string[] = [];
+    const echoed: string[] = [];
+    const pending = promptHidden("Enter value for OPENROUTER_API_KEY: ", {
+      stdin,
+      write: secretPromptWrite(
+        (text) => shown.push(text),
+        (text) => echoed.push(text),
+      ),
+      exit: () => {
+        throw new Error("exit should not run");
+      },
+    });
+    await Promise.resolve();
+    stdin.emit("data", "sk");
+    stdin.emit("data", "\r");
+    expect(await pending).toBe("sk");
+    expect(shown).toHaveLength(1);
+    expect(shown[0]).toContain("Enter value for OPENROUTER_API_KEY: ");
+    expect(shown[0]?.endsWith("\n")).toBe(false);
+    expect(echoed.join("")).toBe("**\n");
+    expect(shown.join("")).not.toContain("*");
+  });
+});
+
 describe("probeVaultGaps", () => {
   test("sees secrets on oke({ secrets }) after consume drains the registry", async () => {
     const dir = mkdtempSync(join(tmpdir(), "probe-vault-"));

package/src/cli/ask-vault-gaps.ts

@@ -14,7 +14,7 @@ import { buildVaultBootChain, normalizeVaultDriverId } from "../elements/vault/b
 import { createVaultRuntime, VaultBootError, type VaultGap } from "../elements/vault/runtime.ts";
 import type { OkeOptions } from "../kernel/app.ts";
 import { requiredEnvRegistry, secretRegistry } from "../kernel/element-registries.ts";
-import { formatCliChrome } from "../term.ts";
+import { formatCliChrome, formatStatusLine } from "../term.ts";
 import { loadOkeConfig } from "./load-config.ts";
 import { openEnvStore } from "./vault-cmd.ts";
 import { promptHidden } from "./vault-secure-input.ts";
@@ -147,6 +147,35 @@ function unionSecrets(
   return out;
 }
 
+/**
+ * Writer for {@link promptHidden} during `oke dev`.
+ *
+ * The question is one chrome row with no trailing newline, so mask
+ * characters stay on that row. Echo (`*`, backspace, Enter) goes straight
+ * to stdout: `formatCliChrome` would turn each `*` into its own `│` line,
+ * and the anchored board would count each of those writes as a new row.
+ *
+ * @param sink - Line-oriented stdout (the dev board wrapper)
+ * @param echo - Raw echo. Defaults to `process.stdout.write`
+ */
+export function secretPromptWrite(
+  sink: (text: string) => void,
+  echo: (text: string) => void = (text) => {
+    process.stdout.write(text);
+  },
+): (text: string) => void {
+  let opened = false;
+  return (text: string) => {
+    if (!opened) {
+      opened = true;
+      const line = formatStatusLine(text);
+      sink(line.endsWith("\n") ? line.slice(0, -1) : line);
+      return;
+    }
+    echo(text);
+  };
+}
+
 /**
  * After compose hydrate (and usually schema push), fill Vault boot gaps
  * one-by-one into `.env.local`. Skips when non-TTY or no gaps.
@@ -175,7 +204,11 @@ export async function maybeAskVaultGaps(options: AskVaultGapsOptions): Promise<n
   const envPath = resolve(cwd, options.envFile ?? ".env.local");
   const store = await openEnvStore(envPath);
   const read =
-    options.readSecret ?? ((prompt: string) => promptHidden(prompt, { write: chromeWrite }));
+    options.readSecret ??
+    ((prompt: string) =>
+      promptHidden(prompt, {
+        write: secretPromptWrite(write),
+      }));
 
   const remaining: VaultGap[] = [];
   for (const gap of gaps) {

package/src/cli/decide.ts

@@ -0,0 +1,174 @@
+/**
+ * `oke decide promote` — fetch the operator candidate and write the lockfile.
+ * The command does not recompute a certificate.
+ */
+
+import { join, resolve } from "node:path";
+import {
+  DECISION_LOCK_FILENAME,
+  lockFromCandidate,
+  parseDecisionLockfile,
+  type DecisionLockfile,
+} from "../elements/ai/decisions/certificate.ts";
+import { DECISION_EXPORT_WARNING } from "../elements/ai/decisions/export.ts";
+
+/** Options for {@link promoteDecision}. */
+export interface PromoteDecisionOptions {
+  readonly name: string;
+  /** Origin of the running app, including scheme and port. */
+  readonly origin: string;
+  /** Lockfile path. Defaults to `oke-decisions.lock.json` in the app root. */
+  readonly lockPath?: string;
+  /** Operator credential header value (`Authorization`). */
+  readonly authorization?: string;
+  /** Injected fetch. Defaults to the global fetch. */
+  readonly fetcher?: (input: string, init?: RequestInit) => Promise<Response>;
+  /** Existing lockfile body. When omitted, the file is read if it exists. */
+  readonly current?: DecisionLockfile;
+}
+
+/**
+ * Fetch one candidate and write it into the app lockfile.
+ *
+ * @param options - Decision name, origin, and credentials
+ */
+export async function promoteDecision(options: PromoteDecisionOptions): Promise<DecisionLockfile> {
+  const fetcher = options.fetcher ?? fetch;
+  const url = `${options.origin.replace(/\/$/, "")}/_oke/decisions/${encodeURIComponent(options.name)}/candidate`;
+  const headers = new Headers();
+  if (options.authorization) headers.set("authorization", options.authorization);
+  const res = await fetcher(url, { headers });
+  if (!res.ok) {
+    throw new Error(`oke decide promote: ${res.status} from ${url}`);
+  }
+  const candidate: unknown = await res.json();
+  const root = resolve(process.env["OKE_ROOT_DIR"] ?? ".");
+  const path = resolve(options.lockPath ?? join(root, DECISION_LOCK_FILENAME));
+  let current = options.current;
+  if (!current) {
+    const file = Bun.file(path);
+    if (await file.exists()) current = parseDecisionLockfile(await file.json());
+  }
+  const next = lockFromCandidate(options.name, candidate, current);
+  const { persistDecisionDrift } = await import("../elements/ai/decisions/labels.ts");
+  persistDecisionDrift(options.name, false);
+  await Bun.write(path, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+/** Options for {@link exportDecisionLabelsFile}. */
+export interface ExportDecisionLabelsOptions {
+  readonly name: string;
+  /** Origin of the running app, including scheme and port. */
+  readonly origin: string;
+  /** File the JSONL is written to. */
+  readonly out: string;
+  /** Operator credential header value (`Authorization`). */
+  readonly authorization?: string;
+  /** Tenant the operator is exporting. A mismatch is rejected by the app. */
+  readonly tenant?: string;
+  /** Injected fetch. Defaults to the global fetch. */
+  readonly fetcher?: (input: string, init?: RequestInit) => Promise<Response>;
+  /** Where the production-data warning is printed. Defaults to stdout. */
+  readonly write?: (text: string) => void;
+}
+
+/**
+ * Fetch reviewed labels and write seed JSONL. Prints that the file holds production data.
+ *
+ * @param options - Decision name, origin, and output path
+ */
+export async function exportDecisionLabelsFile(
+  options: ExportDecisionLabelsOptions,
+): Promise<void> {
+  const fetcher = options.fetcher ?? fetch;
+  const url = new URL(
+    `/_oke/decisions/${encodeURIComponent(options.name)}/labels`,
+    options.origin.endsWith("/") ? options.origin : `${options.origin}/`,
+  );
+  if (options.tenant) url.searchParams.set("tenant", options.tenant);
+  const headers = new Headers();
+  if (options.authorization) headers.set("authorization", options.authorization);
+  const res = await fetcher(url.toString(), { headers });
+  if (!res.ok) {
+    throw new Error(`oke decide labels: ${res.status} from ${url}`);
+  }
+  const body = (await res.json()) as { lines?: string; data?: { lines?: string } };
+  const lines = body.data?.lines ?? body.lines ?? "";
+  const write = options.write ?? ((text: string) => process.stdout.write(text));
+  write(`${DECISION_EXPORT_WARNING}\n`);
+  await Bun.write(options.out, lines);
+}
+
+/**
+ * `oke decide labels <name> --export`.
+ *
+ * @param name - Decision name
+ * @param rest - Flags after the name
+ */
+async function exportLabelsCommand(name: string | undefined, rest: string[]): Promise<number> {
+  if (!name || !rest.includes("--export")) {
+    console.error("oke decide: expected `oke decide labels <name> --export`");
+    return 1;
+  }
+  let origin = process.env.OKE_ORIGIN ?? "http://127.0.0.1:6530";
+  let out = `${name}.labels.jsonl`;
+  let authorization = process.env.OKE_OPERATOR_AUTHORIZATION;
+  let tenant: string | undefined;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--origin") origin = rest[++i] ?? origin;
+    else if (arg === "--out") out = rest[++i] ?? out;
+    else if (arg === "--authorization") authorization = rest[++i];
+    else if (arg === "--tenant") tenant = rest[++i];
+  }
+  await exportDecisionLabelsFile({
+    name,
+    origin,
+    out,
+    ...(authorization !== undefined ? { authorization } : {}),
+    ...(tenant !== undefined ? { tenant } : {}),
+  });
+  return 0;
+}
+
+/**
+ * CLI entry for `oke decide`.
+ *
+ * @param args - Remaining argv after `decide`
+ */
+export async function decideCli(args: string[]): Promise<number> {
+  const [sub, name, ...rest] = args;
+  if (sub === "--help" || sub === "-h" || !sub) {
+    console.log(`oke decide promote <name> [--origin URL] [--lock path]
+oke decide labels <name> --export [--out file] [--origin URL]
+
+promote fetches the operator candidate and writes oke-decisions.lock.json.
+labels --export writes reviewed labels as seed JSONL. The file contains production data.
+`);
+    return sub ? 0 : 1;
+  }
+  if (sub === "labels") return exportLabelsCommand(name, rest);
+  if (sub !== "promote" || !name) {
+    console.error(
+      "oke decide: expected `oke decide promote <name>` or `oke decide labels <name> --export`",
+    );
+    return 1;
+  }
+  let origin = process.env.OKE_ORIGIN ?? "http://127.0.0.1:6530";
+  let lockPath: string | undefined;
+  let authorization = process.env.OKE_OPERATOR_AUTHORIZATION;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--origin") origin = rest[++i] ?? origin;
+    else if (arg === "--lock") lockPath = rest[++i];
+    else if (arg === "--authorization") authorization = rest[++i];
+  }
+  await promoteDecision({
+    name,
+    origin,
+    ...(lockPath !== undefined ? { lockPath } : {}),
+    ...(authorization !== undefined ? { authorization } : {}),
+  });
+  return 0;
+}

package/src/cli/decision-lock-watch.test.ts

@@ -0,0 +1,45 @@
+/**
+ * `oke dev` reloads the decision lockfile without a restart.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DECISION_LOCK_FILENAME,
+  getDecisionLock,
+  resetDecisionCertificates,
+} from "../elements/ai/decisions/certificate.ts";
+import { watchDecisionLockfile } from "./decision-lock-watch.ts";
+
+describe("decision lockfile watch", () => {
+  test("a change calls setDecisionLock without restarting", async () => {
+    resetDecisionCertificates();
+    const root = await mkdtemp(join(tmpdir(), "oke-lock-"));
+    const path = join(root, DECISION_LOCK_FILENAME);
+    await Bun.write(
+      path,
+      `${JSON.stringify({ decisions: { triage: { model: "m", questions: {} } } })}\n`,
+    );
+    let listener: ((event: "rename" | "change", filename: string | null) => void) | undefined;
+    const watch = watchDecisionLockfile(root, (_path, _options, next) => {
+      listener = next;
+      return { close() {} };
+    });
+    listener?.("change", DECISION_LOCK_FILENAME);
+    await watch.flushed();
+    expect(getDecisionLock()?.decisions.triage?.model).toBe("m");
+
+    await Bun.write(
+      path,
+      `${JSON.stringify({ decisions: { route: { model: "n", questions: {} } } })}\n`,
+    );
+    listener?.("change", DECISION_LOCK_FILENAME);
+    await watch.flushed();
+    expect(getDecisionLock()?.decisions.route?.model).toBe("n");
+    expect(getDecisionLock()?.decisions.triage).toBeUndefined();
+    watch.close();
+    resetDecisionCertificates();
+  });
+});

package/src/cli/decision-lock-watch.ts

@@ -0,0 +1,51 @@
+/**
+ * `oke dev` reloads `oke-decisions.lock.json` without restarting.
+ * Production reads the file once, at boot.
+ */
+
+import { watch } from "node:fs";
+import {
+  DECISION_LOCK_FILENAME,
+  loadDecisionLockfile,
+} from "../elements/ai/decisions/certificate.ts";
+
+/** Handle for the lockfile watcher. */
+export interface DecisionLockWatch {
+  close(): void;
+  /** Resolves after the latest reload this watcher started. */
+  flushed(): Promise<void>;
+}
+
+/**
+ * Install `setDecisionLock` whenever the lockfile changes.
+ *
+ * @param root - App root
+ * @param watchFs - Injected watch. The dev server uses `node:fs` on the root.
+ */
+export function watchDecisionLockfile(
+  root: string,
+  watchFs?: (
+    path: string,
+    options: { readonly recursive: true },
+    listener: (event: "rename" | "change", filename: string | null) => void,
+  ) => { close(): void },
+): DecisionLockWatch {
+  let pending: Promise<void> = Promise.resolve();
+  const reload = (): void => {
+    pending = loadDecisionLockfile(root).then(
+      () => undefined,
+      () => undefined,
+    );
+  };
+  if (watchFs) {
+    const handle = watchFs(`${root}/${DECISION_LOCK_FILENAME}`, { recursive: true }, () => {
+      reload();
+    });
+    return { close: () => handle.close(), flushed: () => pending };
+  }
+  const handle = watch(root, (_event, filename) => {
+    if (filename?.toString() !== DECISION_LOCK_FILENAME) return;
+    reload();
+  });
+  return { close: () => handle.close(), flushed: () => pending };
+}