okengine 0.11.2 → 0.13.0

package/src/cli/ai-setup/prompts.ts

@@ -250,7 +250,7 @@ async function askSelfHostedGpuPath(
 ): Promise<AiSetupApplyInput | null> {
   const port = provider === "vllm" ? 8000 : 30000;
   const image =
-    provider === "vllm" ? "vllm/vllm-openai:v0.26.0" : "lmsysorg/sglang:v0.5.16-runtime";
+    provider === "vllm" ? "vllm/vllm-openai:v0.27.1" : "lmsysorg/sglang:v0.5.17-runtime";
   const model = await text({
     message: "Hugging Face model id",
     placeholder: "Qwen/Qwen3-0.6B",

package/src/cli/ask-seed.test.ts

@@ -32,6 +32,33 @@ describe("maybeAskSeed", () => {
     }
   });
 
+  test("re-asks when the seed identity changes", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "ask-seed-"));
+    try {
+      mkdirSync(join(dir, "src", "db", "seed"), { recursive: true });
+      writeFileSync(join(dir, "src", "db", "seed", "index.ts"), "export default {};\n");
+      mkdirSync(join(dir, ".oke"), { recursive: true });
+      writeFileSync(
+        join(dir, PROJECT_STATE_REL),
+        `${JSON.stringify({ seededAt: "2026-01-01T00:00:00.000Z", seed: "notes" }, null, 2)}\n`,
+      );
+      let calls = 0;
+      await maybeAskSeed({
+        cwd: dir,
+        env: "test",
+        stdinIsTTY: true,
+        confirmFn: async () => true,
+        seedFn: async () => {
+          calls += 1;
+          return 0;
+        },
+      });
+      expect(calls).toBe(1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   test("asks once then writes .oke/state.json seededAt", async () => {
     const dir = mkdtempSync(join(tmpdir(), "ask-seed-"));
     try {

package/src/cli/ask-seed.ts

@@ -4,8 +4,9 @@
 
 import { confirm, isCancel } from "@clack/prompts";
 import type { ConfigEnv } from "../config/index.ts";
+import { resolveSeedIdentity, seedPromptMessage } from "../elements/store/seed.ts";
 import { formatCliChrome } from "../term.ts";
-import { resolveSeedModulePath, runSeed } from "./db-seed.ts";
+import { loadSeedDef, resolveSeedModulePath, runSeed } from "./db-seed.ts";
 import { isProjectSeeded, markProjectSeeded } from "./project-state.ts";
 
 /** @deprecated Use `.oke/state.json` `seededAt` via {@link isProjectSeeded}. */
@@ -26,8 +27,9 @@ export interface AskSeedOptions {
 }
 
 /**
- * After a successful `oke db push`, ask once whether to seed sample data.
- * Skips when non-TTY, already seeded, or no seed module.
+ * After a successful `oke db push`, ask once whether to seed this app
+ * (`defineSeed({ name })` or the project folder). Skips when non-TTY,
+ * already seeded for that identity, or no seed module.
  *
  * @param options - Project / env / injectables
  */
@@ -37,11 +39,13 @@ export async function maybeAskSeed(options: AskSeedOptions): Promise<void> {
   if (!tty) return;
 
   const cwd = options.cwd;
-  if (await isProjectSeeded(cwd)) return;
-
   const seedPath = await resolveSeedModulePath(cwd);
   if (!(await Bun.file(seedPath).exists())) return;
 
+  const def = await loadSeedDef(cwd).catch(() => undefined);
+  const identity = resolveSeedIdentity(def, cwd);
+  if (await isProjectSeeded(cwd, identity.name)) return;
+
   const write = options.write ?? ((t) => process.stdout.write(t));
   const chromeWrite = (t: string) => write(formatCliChrome(t));
   const ok =
@@ -49,7 +53,7 @@ export async function maybeAskSeed(options: AskSeedOptions): Promise<void> {
       ? await options.confirmFn()
       : await (async () => {
           const value = await confirm({
-            message: "Run oke db seed (essential + sample data)?",
+            message: seedPromptMessage(identity),
             initialValue: true,
           });
           if (isCancel(value)) return false;
@@ -73,6 +77,6 @@ export async function maybeAskSeed(options: AskSeedOptions): Promise<void> {
       }));
   const code = await seed(cwd, options.env);
   if (code === 0) {
-    await markProjectSeeded(cwd);
+    await markProjectSeeded(cwd, { seed: identity.name });
   }
 }

package/src/cli/attach-host-console.test.ts

@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { userPrincipal } from "../auth/planes.ts";
+import { projectAiPanel } from "../console/server/ai.ts";
+import type { ConsoleState } from "../console/server/state.ts";
+import { resetAiDecls } from "../elements/ai.ts";
+import { resetFlowSeq } from "../kernel/flow.ts";
+import { resetBindings } from "../kernel/on.ts";
+import { attachHostToConsole } from "./attach-host-console.ts";
+
+const OKE = resolve(import.meta.dir, "../index.ts");
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetAiDecls();
+});
+
+describe("attachHostToConsole", () => {
+  test("wires invoke-as and the host store onto Console state", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-attach-"));
+    const entry = join(dir, "app.ts");
+    await writeFile(
+      entry,
+      `
+import { oke, on, flow, http, gate, store } from ${JSON.stringify(OKE)};
+const db = store.sql("db");
+export const ping = on(
+  http.get("/ping").gate.public,
+  flow("main.ping", { do: () => ({ ok: true }) }),
+);
+export const app = oke({
+  name: "attach-host",
+  stores: [db],
+  gate: { policies: [gate.public] },
+}).adopt({ ping });
+`,
+    );
+
+    const state = { invokeUserFlow: null, storeRuntime: null } as unknown as ConsoleState;
+    const ingested: Array<{ event?: { flow?: string } }> = [];
+    const attached = await attachHostToConsole({
+      entry,
+      cwd: dir,
+      state,
+      runsBridge: {
+        url: "http://console.test/console/runs/ingest",
+        secret: "test-ingest",
+        fetch: async (_url, init) => {
+          ingested.push(JSON.parse(String(init?.body ?? "{}")) as { event?: { flow?: string } });
+          return new Response(null, { status: 204 });
+        },
+      },
+    });
+    expect(attached).not.toBeNull();
+    expect(state.invokeUserFlow).toBeTypeOf("function");
+    expect(state.storeRuntime).toBeTruthy();
+
+    const result = await state.invokeUserFlow!({
+      flowId: "main.ping",
+      body: {},
+      principal: userPrincipal({ userId: "u1", verified: true }),
+      operatorId: "op",
+    });
+    expect(result.status).toBe(200);
+    expect(result.output).toEqual({ ok: true });
+    expect(ingested.some((row) => row.event?.flow === "main.ping")).toBe(true);
+    await attached!.stop();
+    expect(state.invokeUserFlow).toBeNull();
+  });
+
+  test("binds host aiRuntime so Console projection sees a journaled ask", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-attach-ai-"));
+    const entry = join(dir, "app.ts");
+    await writeFile(
+      entry,
+      `
+import { oke, on, flow, http, gate, ai } from ${JSON.stringify(OKE)};
+const smart = ai.model("smart", { provider: "mock" });
+smart.prompt("ticket-triage", { version: 2 });
+export const ping = on(
+  http.get("/ping").gate.public,
+  flow("main.ping", {
+    effects: { asks: ["ticket-triage"] },
+    do: (_input, fx) => fx.ask("ticket-triage", { subject: "hello" }),
+  }),
+);
+export const app = oke({
+  name: "attach-ai",
+  gate: { policies: [gate.public] },
+}).adopt({ ping });
+`,
+    );
+
+    const state = {
+      invokeUserFlow: null,
+      storeRuntime: null,
+      aiRuntime: null,
+    } as unknown as ConsoleState;
+    const attached = await attachHostToConsole({ entry, cwd: dir, state });
+    expect(attached).not.toBeNull();
+    expect(state.aiRuntime).toBeTruthy();
+
+    const result = await state.invokeUserFlow!({
+      flowId: "main.ping",
+      body: {},
+      principal: userPrincipal({ userId: "u1", verified: true }),
+      operatorId: "op",
+    });
+    expect(result.status).toBe(200);
+
+    const projection = projectAiPanel({
+      manifest: null,
+      aiRuntime: state.aiRuntime,
+    });
+    expect(projection.journal.length).toBeGreaterThan(0);
+    expect(projection.journal[0]!.prompt).toBe("ticket-triage");
+    expect(projection.journal[0]!.inputTokens).toBeGreaterThan(0);
+    expect(projection.versions.length).toBeGreaterThan(0);
+    await attached!.stop();
+  });
+
+  test("returns null when the entry is not a bootable app", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-attach-empty-"));
+    const entry = join(dir, "app.ts");
+    await writeFile(entry, "export {}\n");
+    const state = { invokeUserFlow: null, storeRuntime: null } as unknown as ConsoleState;
+    const attached = await attachHostToConsole({ entry, cwd: dir, state });
+    expect(attached).toBeNull();
+    expect(state.invokeUserFlow).toBeNull();
+  });
+});

package/src/cli/attach-host-console.ts

@@ -0,0 +1,100 @@
+/**
+ * Bind the host `oke()` app into Console so Store / Call API use the live
+ * compose runtime — not the Manifest memory sandbox.
+ *
+ * `oke dev` serves Console in the parent and the app in a child. Without
+ * this attach, `console.flows.invoke` fails closed (`InvokeDenied`),
+ * Store SQL queries an empty memory `sql:db`, and Call API runs never
+ * reach Traces.
+ */
+
+import { pathToFileURL } from "node:url";
+import { bindHostInvokeUserFlow } from "../console/server/invoke-user-flow.ts";
+import { bindAiRuntime, type ConsoleState } from "../console/server/state.ts";
+import type { OkeApp } from "../kernel/app.ts";
+import { findAppWithPlugins } from "../elements/store/load-plugin-tables.ts";
+import type { RunsConsoleBridgeTarget } from "../runs/bridge-to-console.ts";
+
+/** Stop handle for the in-process host boot. */
+export interface AttachedHost {
+  readonly stop: () => Promise<void>;
+}
+
+/** Options for {@link attachHostToConsole}. */
+export interface AttachHostToConsoleOptions {
+  /** Absolute app entry (`src/app.ts`). */
+  readonly entry: string;
+  /** Project root (effects extract + compose URLs). */
+  readonly cwd: string;
+  /** Live Console state to mutate. */
+  readonly state: ConsoleState;
+  /**
+   * Host → Console WideEvent ingest (`oke dev` Traces). Without this,
+   * Call API execute records only in the in-process host and never
+   * appears next to child-process clock ticks.
+   */
+  readonly runsBridge?: RunsConsoleBridgeTarget;
+}
+
+/**
+ * Import and boot the host app in-process (no scheduler / no listen).
+ * Wires invoke-as and replaces the memory store sandbox with the host store.
+ *
+ * @param options - Entry, cwd, Console state
+ * @returns Stop handle, or `null` when the entry is not a bootable app
+ */
+export async function attachHostToConsole(
+  options: AttachHostToConsoleOptions,
+): Promise<AttachedHost | null> {
+  const mod = (await import(pathToFileURL(options.entry).href)) as Record<string, unknown>;
+  const host = findBootableApp(mod);
+  if (!host) return null;
+
+  const docker = process.env.OKE_DOCKER === "1" || Boolean(process.env.OKE_AI_URL?.trim());
+  // Seed / an earlier import may have booted this singleton with `test` + mock.
+  // Call API must use the live compose driver — stop and boot again.
+  if (host.booted) await host.stop();
+  await host.boot({
+    env: docker ? "dev" : "test",
+    docker,
+    startScheduler: false,
+    rootDir: options.cwd,
+    ...(options.runsBridge !== undefined ? { runsBridge: options.runsBridge } : {}),
+  });
+
+  options.state.invokeUserFlow = bindHostInvokeUserFlow(host);
+  const store = host.elements?.store ?? host.bootResult?.store;
+  if (store) options.state.storeRuntime = store;
+  const vault = host.elements?.vault ?? host.bootResult?.vault;
+  if (vault) options.state.vaultRuntime = vault;
+  const ai = host.elements?.ai ?? host.bootResult?.ai;
+  if (ai) bindAiRuntime(options.state, ai);
+
+  return {
+    stop: async () => {
+      options.state.invokeUserFlow = null;
+      await host.stop();
+    },
+  };
+}
+
+function findBootableApp(mod: Record<string, unknown>): OkeApp | undefined {
+  const plugged = findAppWithPlugins(mod);
+  if (plugged && isBootableApp(plugged)) return plugged;
+  for (const key of ["app", "default", ...Object.keys(mod)]) {
+    const value = mod[key];
+    if (isBootableApp(value)) return value;
+  }
+  return undefined;
+}
+
+function isBootableApp(value: unknown): value is OkeApp {
+  if (!value || typeof value !== "object") return false;
+  const o = value as { boot?: unknown; stop?: unknown; execute?: unknown; bindings?: unknown };
+  return (
+    typeof o.boot === "function" &&
+    typeof o.stop === "function" &&
+    typeof o.execute === "function" &&
+    Array.isArray(o.bindings)
+  );
+}

package/src/cli/console-cmd.test.ts

@@ -0,0 +1,81 @@
+/**
+ * `oke console claim-code` — reads `.oke/claim-code`.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mintClaimCode, writeClaimCodeArtifact } from "../console/server/claim.ts";
+import { consoleClaimCode } from "./console-cmd.ts";
+import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
+
+describe("oke console claim-code", () => {
+  const dirs: string[] = [];
+  afterEach(() => {
+    for (const d of dirs.splice(0)) {
+      try {
+        rmSync(d, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+    }
+  });
+
+  test("prints the mirrored code", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "oke-cli-claim-"));
+    dirs.push(cwd);
+    let t = 2_000_000;
+    const state = mintClaimCode(() => t);
+    writeClaimCodeArtifact(cwd, state);
+    const out: string[] = [];
+    const err: string[] = [];
+    const code = await consoleClaimCode({
+      cwd,
+      now: () => t,
+      write: (s) => out.push(s),
+      writeErr: (s) => err.push(s),
+    });
+    expect(code).toBe(EXIT_OK);
+    expect(out.join("").trim()).toBe(state.code);
+    expect(err.join("")).toContain("expires in");
+  });
+
+  test("json includes remainingMs", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "oke-cli-claim-"));
+    dirs.push(cwd);
+    let t = 2_000_000;
+    const state = mintClaimCode(() => t);
+    writeClaimCodeArtifact(cwd, state);
+    const out: string[] = [];
+    const code = await consoleClaimCode({
+      cwd,
+      now: () => t,
+      json: true,
+      write: (s) => out.push(s),
+      writeErr: () => {},
+    });
+    expect(code).toBe(EXIT_OK);
+    const body = JSON.parse(out.join("")) as {
+      ok: boolean;
+      code: string;
+      remainingMs: number;
+    };
+    expect(body.ok).toBe(true);
+    expect(body.code).toBe(state.code);
+    expect(body.remainingMs).toBe(state.expiresAt - t);
+  });
+
+  test("missing mirror exits runtime", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "oke-cli-claim-"));
+    dirs.push(cwd);
+    const err: string[] = [];
+    const code = await consoleClaimCode({
+      cwd,
+      write: () => {},
+      writeErr: (s) => err.push(s),
+    });
+    expect(code).toBe(EXIT_RUNTIME);
+    expect(err.join("")).toContain("No claim code");
+  });
+});

package/src/cli/console-cmd.ts

@@ -0,0 +1,107 @@
+/**
+ * `oke console claim-code` — print the local DX claim mirror from `.oke/claim-code`.
+ */
+
+import { resolve } from "node:path";
+import { claimCodeArtifactPath, readClaimCodeArtifact } from "../console/server/claim.ts";
+import { wantsJson } from "./args.ts";
+import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
+
+/** Options for {@link consoleClaimCode}. */
+export interface ConsoleClaimCodeOptions {
+  /** Project root (defaults to `process.cwd()`). */
+  readonly cwd?: string;
+  /** Clock (injectable for tests). */
+  readonly now?: () => number;
+  /** Write stdout (defaults to process.stdout). */
+  readonly write?: (text: string) => void;
+  /** Write hints / errors (defaults to stderr). */
+  readonly writeErr?: (text: string) => void;
+  /** Emit only JSON on stdout. */
+  readonly json?: boolean;
+}
+
+/**
+ * Print the active setup claim code written by the last Console boot.
+ *
+ * @param options - Cwd / writers
+ * @returns Exit code
+ */
+export async function consoleClaimCode(options: ConsoleClaimCodeOptions = {}): Promise<number> {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const writeErr = options.writeErr ?? ((t) => process.stderr.write(t));
+  const json = options.json ?? false;
+  const now = options.now ?? Date.now;
+  const result = readClaimCodeArtifact(cwd, now);
+
+  if (!result.ok) {
+    const hint =
+      result.reason === "expired"
+        ? "Claim code expired (30 min TTL). Restart `oke dev` (or the Console kernel) for a new one."
+        : result.reason === "invalid"
+          ? `Invalid claim mirror at ${result.path}. Restart Console to mint a fresh code.`
+          : `No claim code at ${claimCodeArtifactPath(cwd)}. Start Console with setup open (\`oke dev\`), then retry.`;
+    if (json) {
+      write(
+        `${JSON.stringify({ ok: false, error: result.reason, path: result.path, hint }, null, 2)}\n`,
+      );
+    } else {
+      writeErr(`oke console claim-code: ${hint}\n`);
+    }
+    return EXIT_RUNTIME;
+  }
+
+  const remainingMs = Math.max(0, result.artifact.expiresAt - now());
+  if (json) {
+    write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          code: result.artifact.code,
+          expiresAt: result.artifact.expiresAt,
+          mintedAt: result.artifact.mintedAt,
+          remainingMs,
+          path: result.path,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return EXIT_OK;
+  }
+
+  write(`${result.artifact.code}\n`);
+  writeErr(`expires in ${Math.ceil(remainingMs / 60_000)} min · mirrored from ${result.path}\n`);
+  return EXIT_OK;
+}
+
+/**
+ * CLI entry for `oke console …`.
+ *
+ * @param args - Argv after `console`
+ */
+export async function consoleCli(args: string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === "--help" || sub === "-h") {
+    console.log(`oke console claim-code [--json|-j]
+
+Print the first-admin claim code mirrored to .oke/claim-code by Console boot.
+`);
+    return EXIT_OK;
+  }
+  if (sub !== "claim-code") {
+    console.error(`Unknown console subcommand: ${sub}`);
+    console.error("Run `oke console --help` for usage.");
+    return EXIT_RUNTIME;
+  }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    console.log(`oke console claim-code [--json|-j]
+
+Print the first-admin claim code mirrored to .oke/claim-code by Console boot.
+Requires a running (or recently started) Console with setup still open.
+`);
+    return EXIT_OK;
+  }
+  return consoleClaimCode({ json: wantsJson(rest) });
+}

package/src/cli/db-seed.ts

@@ -9,6 +9,7 @@ import type { ConfigEnv, OkeConfig } from "../config/index.ts";
 import {
   normalizeSeedFns,
   resolveSeedCategory,
+  resolveSeedIdentity,
   type SeedDef,
   type SeedFn,
   type UpsertStatus,
@@ -295,6 +296,12 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
   let stop: (() => Promise<void>) | undefined;
   try {
     const def = options.seedDef ?? (await loadSeedDef(cwd, options.seedPath));
+    const identity = resolveSeedIdentity(def, cwd);
+    write(
+      identity.description
+        ? `oke db seed: ${identity.name} — ${identity.description}\n`
+        : `oke db seed: ${identity.name}\n`,
+    );
     const session = options.createFx
       ? await options.createFx()
       : await bootSeedFx(cwd, env, options.entry, loaded?.config);
@@ -375,9 +382,13 @@ function instrumentUpsertHandle<T>(handle: T, tally: SeedTally): T {
       if (prop === "upsert") {
         return async (...args: unknown[]) => {
           const result = await orig(...args);
-          if (result.status === "upserted") tally.upserted += 1;
-          else if (result.status === "changed") tally.changed += 1;
-          else if (result.status === "already-existed") tally.alreadyExisted += 1;
+          const status =
+            result && typeof result === "object" && "status" in result
+              ? (result as { status: UpsertStatus }).status
+              : undefined;
+          if (status === "upserted") tally.upserted += 1;
+          else if (status === "changed") tally.changed += 1;
+          else if (status === "already-existed") tally.alreadyExisted += 1;
           return result;
         };
       }

package/src/cli/db.test.ts

@@ -14,6 +14,7 @@ import {
   dbCli,
   emitAbstractSchemaPrestep,
   executeSeedDef,
+  runSeedFns,
   runDb,
   runGenerate,
   runPush,
@@ -116,12 +117,18 @@ describe("oke db", () => {
   });
 
   test("missing_hints exits runtime", async () => {
+    const out: string[] = [];
     const code = await runDb("push", {
-      pushFn: async () => ({ status: "missing_hints", unresolved: [] }),
-      write: () => {},
+      pushFn: async () => ({
+        status: "missing_hints",
+        unresolved: [{ sql: "DROP TABLE leftover" }],
+      }),
+      write: (t) => out.push(t),
       skipEmit: true,
     });
     expect(code).toBe(EXIT_RUNTIME);
+    expect(out.join("")).toContain("missing_hints");
+    expect(out.join("")).toContain("DROP TABLE leftover");
   });
 
   test("resolveDrizzleConfigPath uses db.config from oke.config", async () => {
@@ -516,6 +523,34 @@ describe("oke db seed", () => {
     expect(out.join("")).toContain("oke db seed:");
   });
 
+  test("runSeedFns ignores void index upserts when tallying", async () => {
+    const out: string[] = [];
+    const fx = {
+      store: (ref: unknown) =>
+        ref === "sql"
+          ? { upsert: async () => ({ status: "changed" as const }) }
+          : { upsert: async () => undefined },
+    } as unknown as ReturnType<typeof createFx>;
+    await runSeedFns(
+      "dev",
+      [
+        async function volume(seedFx) {
+          const sql = seedFx.store("sql" as never) as unknown as {
+            upsert: () => Promise<unknown>;
+          };
+          const index = seedFx.store("index" as never) as unknown as {
+            upsert: () => Promise<unknown>;
+          };
+          await sql.upsert();
+          await index.upsert();
+        },
+      ],
+      fx,
+      (t) => out.push(t),
+    );
+    expect(out.join("")).toContain("dev volume — upserted 0 · changed 1 · already-existed 0");
+  });
+
   test("executeSeedDef is the category source of truth", async () => {
     const order: string[] = [];
     const out: string[] = [];

package/src/cli/db.ts

@@ -579,6 +579,30 @@ function parseConfigEnv(value: string | undefined): ConfigEnv | undefined {
   return undefined;
 }
 
+/**
+ * Print drizzle-kit `unresolved` statements so `missing_hints` is actionable.
+ *
+ * @param unresolved - Kit payload (strings or `{ sql | statement | message }`)
+ */
+function formatUnresolvedHints(unresolved: readonly unknown[] | undefined): string {
+  if (!unresolved || unresolved.length === 0) return "";
+  const lines: string[] = [];
+  for (const item of unresolved) {
+    if (typeof item === "string") {
+      lines.push(`  ${item}`);
+      continue;
+    }
+    if (item && typeof item === "object") {
+      const rec = item as Record<string, unknown>;
+      const text = rec.sql ?? rec.statement ?? rec.message;
+      lines.push(`  ${typeof text === "string" ? text : JSON.stringify(item)}`);
+      continue;
+    }
+    lines.push(`  ${String(item)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
 function reportKitResult(verb: string, result: DbKitResult, write: (text: string) => void): number {
   if (result.status === "ok" || result.status === "no_changes") {
     write(`oke db ${verb}: ${result.status}\n`);
@@ -588,6 +612,8 @@ function reportKitResult(verb: string, result: DbKitResult, write: (text: string
     write(
       `oke db ${verb}: missing_hints — resolve destructive changes manually (not auto-applied)\n`,
     );
+    const detail = formatUnresolvedHints(result.unresolved);
+    if (detail) write(detail);
     return EXIT_RUNTIME;
   }
   write(