okengine 0.21.1 → 0.23.0

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

@@ -1,7 +1,7 @@
 ---
 title: "Reference"
 description: "Lookup pages — CLI, config, fx, errors, security, and plugins."
-icon: "BookMarked"
+icon: "BookBookmark"
 source: "docs/spec/unified-theory.md"
 ---
 
@@ -23,6 +23,11 @@ Dense tables and command lists. Reach for these when you already know what you a
   />
   <Card title="fx" description="The complete fx surface and effects." href="/docs/reference/fx" />
   <Card title="Errors" description="OKE codes, denials, fixes." href="/docs/reference/errors" />
+  <Card
+    title="Idempotency"
+    description="One Idempotency-Key, one execution."
+    href="/docs/reference/idempotency"
+  />
   <Card
     title="Security"
     description="Host, Origin, planes, MCP posture."

package/site/content/docs/reference/meta.json

@@ -1,6 +1,6 @@
 {
   "title": "Reference",
-  "icon": "BookMarked",
+  "icon": "BookBookmark",
   "pages": [
     "index",
     "cli",
@@ -8,6 +8,7 @@
     "environment-variables",
     "fx",
     "errors",
+    "idempotency",
     "security",
     "i18n",
     "plugins",

package/site/content/docs/understand/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Understand",
   "icon": "Compass",
-  "pages": ["the-architecture", "try-it"]
+  "pages": ["the-architecture", "routing", "try-it"]
 }

package/site/content/docs/{elements/flow → understand}/routing.mdx

@@ -588,28 +588,29 @@ plus a handwritten `http.get("/links")`.
 
 ## Learn more
 
+- [The Architecture](/docs/understand/the-architecture) — derived routes, no hand-written table
+- [Try it](/docs/understand/try-it) — scaffold, run, and hit a stamped path
 - [HTTP](/docs/elements/flow/http) — verbs, envelopes, `http.resource`, live SSE
 - [Client](/docs/client/calling) — `api.links.get`, REST vs RPC, `$routes`
 - [Errors](/docs/reference/errors) — OKE1040 · OKE1030 · OKE1041 · OKE1045 · OKE1070 · OKE1072
-- [The Architecture](/docs/understand/the-architecture) — derived routes, no hand-written table
 - [Gate](/docs/elements/gate) — `.gate(...)` / `.public()` on the same trigger
 
 ## Next
 
 <Cards>
   <Card
-    title="HTTP"
-    description="REST verbs, RFC 10008 QUERY, CRUD mounts, and live SSE on Flow."
-    href="/docs/elements/flow/http"
+    title="The Architecture"
+    description="One law, eight elements, derived Manifest — where routes come from."
+    href="/docs/understand/the-architecture"
   />
   <Card
-    title="Client"
-    description="Typed caller — createClient, envelopes, REST from $routes."
-    href="/docs/client/calling"
+    title="Try it"
+    description="Scaffold shorter, run oke dev, and call a stamped path."
+    href="/docs/understand/try-it"
   />
   <Card
-    title="Consumers"
-    description="Signal workers, named Clock jobs, and SQL CDC — one Flow species."
-    href="/docs/elements/flow/consumers"
+    title="HTTP"
+    description="REST verbs, RFC 10008 QUERY, CRUD mounts, and live SSE on Flow."
+    href="/docs/elements/flow/http"
   />
 </Cards>

package/site/content/docs/understand/the-architecture.mdx

@@ -27,11 +27,11 @@ app.post("/signup", async (req, res) => {
 
 It works. It ships. Then a traffic spike, a silent failure, a compliance question, and a double-submit turn those four lines into six files — endpoint, queue, worker, Redis connection, mail client, audit table — that never agreed with each other about anything.
 
-**A payment webhook.** A provider confirms a charge. Mark the order paid. Simple — until the provider retries the same webhook twice during a network hiccup, and "mark the order paid" needs to somehow know it already ran.
+**A payment webhook.** A provider confirms a charge. Mark the order paid. The provider retries the same event during a hiccup. That attempt is a second run, visible in `fx.runs`. The fix is one line: a unique constraint or upsert on the provider's event id.
 
 **A nightly report.** Summarize yesterday's activity and email it to managers. Trivial — until a manager's access gets revoked at 11:58pm and the report that runs at midnight has no idea the permission it checked when the feature was built isn't the permission that holds right now.
 
-Three teams. Three domains. Nobody on any of them talked to the other two. And all three land on the identical fork: **something has to happen later, exactly once, provably — and nothing in the original four lines said what "provably" would end up costing.**
+Three teams. Three domains. Nobody on any of them talked to the other two. And all three land on the identical fork: **something has to happen later, and the original four lines never said where the retry, the receipt, or the duplicate would be visible.** The door makes that visible. The fix is one line.
 
 ### Follow one all the way through
 
@@ -49,7 +49,7 @@ The endpoint is fast again. It's also no longer one system — it's an endpoint,
 
 <SixSystemsDrift />
 
-From here the same pattern repeats on a longer clock. A support ticket reveals a job failed silently — nobody had configured retries, so you add them, and now a specific number (3? 5? with what backoff?) lives in a file that nobody will remember the reasoning for in six weeks. Compliance asks for proof of every email sent — you add a table written to from inside the worker, and now that worker has two jobs instead of one, quietly capable of disagreeing with itself if the second write fails. Someone double-clicks submit — two jobs enqueue, two emails send, and idempotency becomes a fact that has to live in two systems that were never introduced to each other.
+From here the same pattern repeats on a longer clock. A support ticket reveals a job failed silently — nobody had configured retries, so you add them, and now a specific number (3? 5? with what backoff?) lives in a file that nobody will remember the reasoning for in six weeks. Compliance asks for proof of every email sent — you add a table written to from inside the worker, and now that worker has two jobs instead of one, quietly capable of disagreeing with itself if the second write fails. Someone double-clicks submit — two jobs enqueue, two emails send. The duplicate is two runs. The fix is one line, a unique constraint or upsert, not a second protocol shared by a queue and a database.
 
 None of these were mistakes. Each one was the correct call, made by a competent engineer, in direct response to something that actually happened.
 
@@ -74,7 +74,7 @@ OKE removes the disagreement by removing the choice. It's one rule, in two parts
 
 **First: every trigger reduces to the same shape.** An HTTP request, a scheduled tick, a queue message, a database change — whatever wakes the code up, what follows has one identical anatomy: `on(Trigger) → Effects`. Not four systems that happen to look similar. One system, with four ways to wake it up.
 
-**Second: every effect passes through one door.** Nothing is allowed to touch a database, send an email, check a permission, or read the clock on its own — all of it goes through a single surface. Not because that's tidier. Because it's the only way retries, auditing, idempotency, and permission checks stop being infrastructure every team reinvents at the exact moment they get burned by not having it.
+**Second: every effect passes through one door.** Nothing is allowed to touch a database, send an email, check a permission, or read the clock on its own — all of it goes through a single surface. The Manifest lists every effect. Least privilege is enforced at runtime. Every run is recorded in `fx.runs`. Durability is one line in a known place — `signal.once` retries, or `durable` plus `fx.step` — not a new system.
 
 <FlowShape />
 
@@ -193,7 +193,9 @@ do: async (input, fx) => {
 };
 ```
 
-This one rule is what made the month-8 drift above avoidable: if `fx` is the only door, retries, auditing, and idempotency stop being separate systems teams build by hand, and become properties of the one boundary everything already passes through.
+This one rule is what made the month-8 drift visible: every effect is in the Manifest, every run is in `fx.runs`, and a duplicate is a second run you can see.
+A retried HTTP call can send one `Idempotency-Key`, so that retry runs once.
+A provider event still needs a unique constraint, because the provider does not send that header.
 
 ### Putting the five pieces together
 
@@ -223,14 +225,14 @@ export const signup = on(
 
 Nothing about the code above looks more complicated than the four lines that started the drift — because it isn't. The difference only shows up when the same pressure from that timeline hits it. Every fork was really the same question — _is this safe to retry, safe to audit, safe to run twice?_ — and now it has one home:
 
-| Then: a new system per incident                                      | Now: one door, fixed answer                                             |
-| -------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| **Week 2 spike** — hand-build a queue + worker to run the send later | Running later, safely, is asked of the trigger or the effect itself     |
-| **Month 2 silence** — a retry count in a worker nobody remembers     | Retries are a property of the `fx` boundary every effect passes through |
-| **Month 4 audit** — a `sent_emails` table written by hand from a job | What was sent is already known — nothing sends outside `fx`             |
-| **Month 6 double-submit** — dedup split across a queue and a DB      | One call through one door — no second path for a duplicate              |
+| Then: a new system per incident                                      | Now: the door makes it visible, and the fix is one line                                                                                                                                                                                                                                                            |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Week 2 spike** — hand-build a queue + worker to run the send later | The send is a Signal consumer. The Manifest lists it. The run is in `fx.runs`.                                                                                                                                                                                                                                     |
+| **Month 2 silence** — a retry count in a worker nobody remembers     | The retry count lives on `signal.once` (default 3) or on `durable` + `fx.step`, which skips a step already journaled. A failed HTTP request is not retried by `fx`.                                                                                                                                                |
+| **Month 4 audit** — a `sent_emails` table written by hand from a job | The send is an effect in the Manifest and a run in `fx.runs`. Channel records a receipt. The default receipt ledger is process-local memory.                                                                                                                                                                       |
+| **Month 6 double-submit** — dedup split across a queue and a DB      | A retry of one call runs once when it sends `Idempotency-Key`. Two submits are two calls unless the app passes the same key. Provider webhooks still need a unique constraint on the provider's event id, because providers do not send that header. `{ key }` serializes `once` per key. It does not deduplicate. |
 
-None of that required new code beyond what's above. It required the four lines to already be the kind of thing where those questions have a fixed answer, instead of a new one invented per team, per incident.
+The door makes each of those problems visible, and the fix is one line in a known place. The signup sample is safe to run twice once the user row has a unique constraint or an upsert. The second attempt is a second run in `fx.runs`.
 
 ### Five kinds of trigger
 

package/site/content/docs/understand/try-it.mdx

@@ -405,7 +405,7 @@ test("creates a user", async () => {
 bun test # [!code focus]
 ```
 
-`createTestApp` swaps every driver behind `fx` for a deterministic one.
+`createTestApp` swaps every driver behind `fx` for a deterministic one. It stamps Manifest tokens. Inline flows that are not an app pass `capability: "open"`.
 
 </Step>
 
@@ -762,7 +762,7 @@ return await fx.ask(triage, { message }); // [!code focus]
 
 ## Learn more
 
-- [Routing](/docs/elements/flow/routing) — when to omit the path, `list` / `create` / `get` filenames
+- [Routing](/docs/understand/routing) — when to omit the path, `list` / `create` / `get` filenames
 - [Flow](/docs/elements/flow) — one species; `fx` is the door
 - [Signal](/docs/elements/signal) — `once` / `broadcast` / `live`
 - [Store](/docs/elements/store) — SQL, KV, files, search
@@ -775,7 +775,7 @@ return await fx.ask(triage, { message }); // [!code focus]
   <Card
     title="Routing"
     description="File-tree stamps, many-routes files, and reserved leaves."
-    href="/docs/elements/flow/routing"
+    href="/docs/understand/routing"
   />
   <Card title="Flow" description="on(trigger) → do through fx." href="/docs/elements/flow" />
   <Card title="Signal" description="Move work off the request." href="/docs/elements/signal" />

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/competitor-mention-removal.test.ts

@@ -11,8 +11,8 @@ import { join } from "node:path";
 
 const ROOT = join(import.meta.dir, "../..");
 
-/** Forbidden peer name — split so this file does not match itself. */
-const FORBIDDEN_HONO = ["Ho", "no"].join("");
+/** Word-boundary router peer — `-F` false-positives on `Honored` / `canHonor`. */
+const FORBIDDEN_HONO = ["\\b", "Ho", "no", "\\b"].join("");
 /** Forbidden peer name. */
 const FORBIDDEN_ELYSIA = ["Ely", "sia"].join("");
 /** Forbidden peer name (covers Enc + ore.ts). */
@@ -104,7 +104,7 @@ function assertZeroGitGrepRegex(pattern: string, ignorePrefixes: readonly string
 
 describe("named competitor mention removal gate", () => {
   test("tracked tree has zero mentions of the thin multi-runtime router peer", () => {
-    assertZeroGitGrepFixed(FORBIDDEN_HONO);
+    assertZeroGitGrepRegex(FORBIDDEN_HONO);
   });
 
   test("tracked tree has zero mentions of the Bun-first peer framework", () => {