okengine 0.22.0 → 0.23.1

package/site/content/docs/elements/store/index.mdx

@@ -226,7 +226,7 @@ export default defineConfig({
   images: {
     store: {
       sql: "postgres:18-alpine",
-      kv: "redis:8-alpine",
+      kv: "docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0",
       files: "rustfs/rustfs:1.0.0",
     },
   },

package/site/content/docs/elements/store/kv.mdx

@@ -544,11 +544,11 @@ writes (`set` · `delete`). Declare the same refs when you hand-write
 
 ## Drivers
 
-| Driver                                       | Runs as                          | Best for                           |
-| -------------------------------------------- | -------------------------------- | ---------------------------------- |
-| `redis`                                      | Docker Redis / Valkey-compatible | Dev + prod default                 |
-| `memory`                                     | Process map                      | Test default                       |
-| Durable (`postgres` / `pglite` via `oke_kv`) | Shared SQL URL                   | Namespaces that must outlive Redis |
+| Driver                                       | Runs as                           | Best for                           |
+| -------------------------------------------- | --------------------------------- | ---------------------------------- |
+| `redis`                                      | Dragonfly by default (Redis-wire) | Dev + prod default                 |
+| `memory`                                     | Process map                       | Test default                       |
+| Durable (`postgres` / `pglite` via `oke_kv`) | Shared SQL URL                    | Namespaces that must outlive Redis |
 
 Defaults: `redis` / `memory` / `redis` (dev / test / prod). Pin overrides in
 `oke.config.ts`; image pins stay under `images.store.kv` — the driver id stays

package/site/content/docs/plugins/otp.mdx

@@ -22,9 +22,9 @@ app-owned delivery across the channels you declare.
 </Callout>
 
 <Callout type="info" title="fx.sendOtp vs otp()">
-  `fx.sendOtp` / `fx.verifyOtp` are raw Channel capabilities — no `.plug()`. Direct use means you
-  build routes, sessions, rates, and storage yourself. `otp()` provider mode wraps that path; skip
-  it and call the raw methods in your own flow without losing the provider connection.
+  `fx.sendOtp` / `fx.verifyOtp` / `fx.deliverOtp` are supported Channel methods. Direct use means
+  you build routes, sessions, rates, and storage yourself. `otp()` provider mode wraps that path.
+  The `mena` plugin (`menaChannels`) is an additional way to open the same providers.
 </Callout>
 
 ## Quick start

package/site/content/docs/recipes/dragonfly.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Dragonfly"
-description: "Multi-threaded Redis-wire runtime — OKE_STORE_KV_PASSWORD, memlock ulimit, no maxmemory-policy flag."
+description: "Default store.kv image — multi-threaded Redis-wire runtime, memlock ulimit, OKE_STORE_KV_PASSWORD."
 icon: "Zap"
 source: "docs/spec/unified-theory.md"
 ---
 
-Dragonfly is a multi-threaded, memory-efficient reimplementation of the Redis protocol —
-same `redis://` wire format, different engine. Slots behind the same `redis` driver with
-zero Flow changes.
+Dragonfly is the default `store.kv` image in `dev` and `prod`: a multi-threaded Redis-protocol engine.
+Same `redis://` wire format and the same `redis` driver, so Flows do not change.
+Pin Redis or Valkey when you want those engines instead.
 
 <Callout title="The one rule">
   Driver id stays `redis`. Dragonfly is an image choice — every KV call through `fx.store` behaves
@@ -23,7 +23,7 @@ zero Flow changes.
 
 ```typescript title="oke.config.ts"
 images: {
-  "store.kv": "docker.dragonflydb.io/dragonflydb/dragonfly",
+  "store.kv": "docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0",
 },
 ```
 

package/site/content/docs/recipes/index.mdx

@@ -51,15 +51,15 @@ Driver id stays `redis` for every image below.
 
 <Cards>
   <Card
-    title="Redis"
-    description="Default store.kv — requirepass + maxmemory."
-    href="/docs/recipes/redis"
+    title="Dragonfly"
+    description="Default store.kv — multi-threaded Redis-wire runtime."
+    href="/docs/recipes/dragonfly"
   />
   <Card title="Valkey" description="BSD-licensed Redis-wire fork." href="/docs/recipes/valkey" />
   <Card
-    title="Dragonfly"
-    description="Multi-threaded Redis-wire runtime."
-    href="/docs/recipes/dragonfly"
+    title="Redis"
+    description="Opt-in Redis Open Source — requirepass + maxmemory."
+    href="/docs/recipes/redis"
   />
 </Cards>
 

package/site/content/docs/recipes/postgres.mdx

@@ -106,11 +106,11 @@ Scale out with [PgDog](/docs/recipes/pgdog) so `N × Bun.SQL pool` does not exha
   Recreate `store-sql` after a recipe change — the data volume can stay.
 </Callout>
 
-| Step    | What you do                                                       |
-| ------- | ----------------------------------------------------------------- |
-| Preload | Recipe already sets `shared_preload_libraries=pg_stat_statements` |
-| Create  | `CREATE EXTENSION IF NOT EXISTS pg_stat_statements`               |
-| Console | Store → SQL band → **Performance**                                |
+| Step    | What you do                                                            |
+| ------- | ---------------------------------------------------------------------- |
+| Preload | Recipe already sets `shared_preload_libraries=pg_stat_statements`      |
+| Create  | `oke db push` runs `CREATE EXTENSION IF NOT EXISTS pg_stat_statements` |
+| Console | Store → SQL band → **Performance**                                     |
 
 Default `postgres:18-alpine` does **not** ship `hypopg` / `index_advisor`. Pin the
 opt-in image when you want Suggest indexes:
@@ -137,8 +137,8 @@ set. Re-run `oke dev` so the stack writes `.env.local`, or export
 <Accordion title="PgStatStatementsNotPreloaded">
 
 The Console Performance view needs the library preloaded **and** the extension
-created. Recreate `store-sql` so the new `command` applies, then run
-`CREATE EXTENSION IF NOT EXISTS pg_stat_statements`.
+created. Recreate `store-sql` so the new `command` applies, then run `oke db push`
+(or open Performance again — it creates the extension when preload is already on).
 
 Existing clusters that started before this recipe change keep the old
 postmaster flags until recreate.
@@ -167,5 +167,9 @@ Postgres refusing auth.
 <Cards>
   <Card title="PgDog" description="Add pooling in front of Postgres." href="/docs/recipes/pgdog" />
   <Card title="Neon" description="A managed alternative." href="/docs/providers/neon" />
-  <Card title="Redis" description="The default store.kv image." href="/docs/recipes/redis" />
+  <Card
+    title="Dragonfly"
+    description="The default store.kv image."
+    href="/docs/recipes/dragonfly"
+  />
 </Cards>

package/site/content/docs/recipes/redis.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Redis"
-description: "Default store.kv image — OKE_STORE_KV_PASSWORD, maxmemory policy, ephemeral data, REDIS_URL."
+description: "Opt-in store.kv image — OKE_STORE_KV_PASSWORD, maxmemory policy, ephemeral data, REDIS_URL."
 icon: "Zap"
 source: "docs/spec/unified-theory.md"
 ---
 
-Redis is the default `store.kv` image in `dev` and `prod`. `oke docker` matches image
-references containing `redis` or `keydb` and derives a password-required server — no
-unauthenticated instance.
+Redis is an opt-in `store.kv` image. The default pin is [Dragonfly](/docs/recipes/dragonfly).
+`oke docker` matches image references containing `redis` or `keydb` and derives a
+password-required server — no unauthenticated instance.
 
 <Callout title="The one rule">
   The driver id stays `redis` for every Redis-wire image — Redis, Valkey, Dragonfly, or a managed

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

@@ -134,7 +134,8 @@ Override app / console / mcp listen ports in `oke.config.ts` `ports` — see
 | `docker`     | Derive compose · clean leftover stacks                       | `--prod\|-p`, `--out`, `--config`, `--manifest`; sub `clean`                                                                                              |
 | `images`     | List / pin digests                                           | `list` · `pin`                                                                                                                                            |
 | `build`      | Tree-shaken bundle                                           | `--target\|-t bun\|node\|edge`, `--entry`, `--outdir`                                                                                                     |
-| `eval`       | Prompt eval sets (CI gate)                                   | `--manifest`                                                                                                                                              |
+| `eval`       | Prompt eval sets (CI gate)                                   | `--manifest`, `--certify` (decision seed certificate; prompt evals stay as they are)                                                                      |
+| `decide`     | Write a decision lockfile from the operator candidate        | `promote <name>` (`--origin`, `--lock`)                                                                                                                   |
 | `ai`         | Configure AI driver + models                                 | `setup` (`--provider`, `--chat`, `--vision`, `--embed`, `--yes`)                                                                                          |
 | `branch`     | Fork journaled state                                         | `<name>`, `--at\|-a`                                                                                                                                      |
 | `replay`     | Re-invoke a past Flow from Runs                              | `--request-id\|-r`, `--entry`, `--dry-run`, `--live`                                                                                                      |

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

@@ -136,11 +136,13 @@ sql: {
 },
 ```
 
-| Field      | Type              | Meaning                                     |
-| ---------- | ----------------- | ------------------------------------------- |
-| `url`      | connection string | Overrides the env-var resolution            |
-| `pool`     | `{ max?, min? }`  | SQL pool sizing                             |
-| `replicas` | `string[]`        | Read-only routing targets (read flows only) |
+| Field      | Type              | Meaning                                                                           |
+| ---------- | ----------------- | --------------------------------------------------------------------------------- |
+| `url`      | connection string | Overrides the env-var resolution                                                  |
+| `pool`     | `{ max?, min? }`  | `max` is the Bun.SQL pool size. Unset keeps 8. `min` is accepted and not applied  |
+| `replicas` | `string[]`        | Read-only flows use these URLs. Each replica opens its own pool at the same `max` |
+
+A store `max` of 20 does not share a pool another part of the process already opened at 8. Writes stay on the primary.
 
 ## images
 
@@ -150,7 +152,7 @@ Nested pins by element role — vendor choice lives here, never in driver ids:
 images: {
   store: {
     sql: "postgres:18-alpine",
-    kv: "redis:8-alpine",
+    kv: "docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0",
     files: "rustfs/rustfs:1.0.0",
   },
   channel: { email: "axllent/mailpit:v1.31.2" },
@@ -161,7 +163,7 @@ images: {
 
 Omitted image keys mean no container for that role. When both `store.sql` and `pgdog` are pinned, `DATABASE_URL` points at PgDog — see [Store](/docs/elements/store#multiple-environments).
 
-For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays `redis`.
+For `store.kv`, pin Dragonfly (default), Redis, or Valkey — driver id stays `redis`.
 `{ durable: true }` KV lives in SQL (`oke_kv` on `DATABASE_URL`), not a second Redis image.
 
 Compose does not manage AI inference — [OpenRouter](/docs/recipes/openrouter) or BYO

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

@@ -158,7 +158,13 @@ on(
 | `fx.auth.upsertTenantRole({ tenantId, roleName, scopes })`                     | `write` `auth:tenants`  | Application scopes only — `console:*` is unknown_scope                                             |
 
 `fx.call` starts the callee with an **empty** `fx.auth` (fail-closed) and propagates `fx.tenant.id`.
-Read `fx.principal` for audit — it does not copy into `fx.auth`.
+Read `fx.principal` for audit — it does not copy into `fx.auth`. Passing a Flow handle types
+`input` and the result. A string name stays `Promise<unknown>`.
+
+`fx.store(db).transaction(async (tx) => { … })` pins one SQL connection. `fx.emit` inside the
+callback stages on the signal outbox and publishes after commit. A throw rolls that batch back.
+`fx.store(db).run(builder)` runs a Drizzle builder through `toSQL()`. Joins stay on that builder;
+the hand-rolled chain does not grow a join API. Inference still records every joined table.
 
 <Callout>
   Gates never consult `fx.principal`. `return fx.fail(...)` is a `FlowFailure`; an unhandled `throw`
@@ -240,12 +246,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).
 
@@ -280,9 +287,11 @@ Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`. A `"d"` is 86_400
 
 ## Cache
 
-Read-only flows cache automatically from inferred or ledgered `reads` — no
-`fx.cache` call and no `cache:` default on the flow. Writes invalidate those
-keys. Use `cache: false` to opt out, or `cache: "30s"` for a TTL.
+Pure store-read flows cache by default. A send, emit, fetch, vault read, ask,
+decide, or `fx.call` is never cached. The key includes tenant, locale, scopes,
+and membership roles. Writes through `fx` invalidate those keys. `cache: false`
+always disables. `oke({ cache: { auto: false } })` turns the default off.
+Cross-instance invalidation and out-of-band writes are not covered.
 
 `fx.cache` is the manual (tier-3) surface:
 

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/auth/tenants.ts

@@ -359,3 +359,20 @@ export function tenantScopesForMember(
   const role = store.roles.get(roleKey(tenantId, member.role));
   return role?.scopes ?? [];
 }
+
+/**
+ * Membership role name for the tier-1 cache key.
+ *
+ * Same member lookup as {@link tenantScopesForMember}. Not an authorization input.
+ *
+ * @param store - Tenant store
+ * @param tenantId - Tenant id
+ * @param userId - User id
+ */
+export function tenantRoleForMember(
+  store: TenantStore,
+  tenantId: string,
+  userId: string,
+): string | null {
+  return getMember(store, tenantId, userId)?.role ?? null;
+}

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) {