@cosmicdrift/kumiko-framework 0.158.2 → 0.159.1

package/src/api/auth-routes.ts

@@ -16,17 +16,11 @@ import {
   type AuthSessionStatus,
   CSRF_COOKIE_NAME,
   getUser,
-  type PatResolver,
+  type TokenVerifier,
 } from "./auth-middleware";
 import type { JwtHelper } from "./jwt";
 import { generateToken } from "./tokens";
 
-// Cookie lifetime must track the JWT's exp claim — both are issued together,
-// both reference the same session. jwt.ts's createJwtHelper hardcodes
-// setExpirationTime("24h"); if that ever becomes configurable this constant
-// follows it.
-const JWT_TTL_SECONDS = 24 * 60 * 60;
-
 // Resolves the Secure cookie flag. Locked off in dev/test so Playwright
 // against http://localhost:… can actually receive the cookie. Production
 // flips it on — browsers drop Secure cookies on http, so a misconfigured
@@ -48,6 +42,10 @@ function setAuthCookies(
     csrfToken: string;
     sameSite: "lax" | "strict";
     domain?: string | undefined;
+    // Cookie lifetime must track the JWT's exp claim — both are issued
+    // together, both reference the same session. Callers pass jwt.ttlSeconds
+    // so the two never drift apart.
+    ttlSeconds: number;
   },
 ): void {
   const sameSite = opts.sameSite === "strict" ? "Strict" : "Lax";
@@ -55,7 +53,7 @@ function setAuthCookies(
     secure: cookieSecure(),
     sameSite,
     path: "/",
-    maxAge: JWT_TTL_SECONDS,
+    maxAge: opts.ttlSeconds,
     ...(opts.domain !== undefined && { domain: opts.domain }),
   } as const;
 
@@ -262,14 +260,11 @@ export type AuthRoutesConfig = {
   // at login, check it here on every request. Leaving this empty disables
   // the revocation path — old JWTs stay valid until they expire naturally.
   sessionChecker?: SessionChecker;
-  // When true, a JWT WITHOUT a sid is rejected. Use during deploy-rollouts
-  // once all fresh JWTs emit a sid and the legacy stateless tokens are
-  // expected to have expired. Default false keeps old tokens working.
-  sessionStrictMode?: boolean;
-  // Resolves bearer Personal Access Tokens (PAT_TOKEN_PREFIX) into a
-  // SessionUser, consulted BEFORE jwt.verify. Wired by the
-  // personal-access-tokens feature; unwired = PAT auth disabled.
-  patResolver?: PatResolver;
+  // Resolves bearer tokens (any registered auth-foundation `tokenVerifier`
+  // provider — PAT today, future JWT-provider), consulted BEFORE jwt.verify.
+  // Wired by run-prod-app/run-dev-app when at least one provider feature is
+  // mounted; unwired = no non-JWT bearer auth.
+  tokenVerifier?: TokenVerifier;
   // Per-token request-rate limiter for PAT-authenticated requests, keyed by
   // the token id (SessionUser.pat.tokenId). Cookie/JWT requests are unaffected.
   // Reuses the LoginRateLimiter shape (a generic keyed check/reset limiter).
@@ -288,6 +283,12 @@ export type AuthRoutesConfig = {
   passwordReset?: PasswordResetConfig;
   // Email-verification flow. Symmetric to passwordReset.
   emailVerification?: EmailVerificationConfig;
+  // Account-unlock flow (#1266). When wired, POST
+  // /auth/request-account-unlock + /auth/confirm-account-unlock are
+  // mounted as public routes. Confirm needs no extra body field
+  // (token-only, like email-verification) — the handler only clears the
+  // Redis lockout state, no entity write.
+  accountUnlock?: AccountUnlockConfig;
   // Self-Signup (Magic-Link). Wenn wired, mountet POST
   // /auth/signup-request + /auth/signup-confirm. Confirm returnt JWT-
   // Cookie + Session-Body wie login.
@@ -358,6 +359,13 @@ export type EmailVerificationConfig = {
   confirmHandler: string;
 };
 
+export type AccountUnlockConfig = {
+  requestHandler: string;
+  // Token-only body (mirrors EmailVerificationConfig) — no entity write, so
+  // there's no newPassword-equivalent field.
+  confirmHandler: string;
+};
+
 // Tenant-Invite Magic-Link. Drei Accept-Branches für klare Separation:
 //   - acceptHandler: logged-in User akzeptiert via JWT (Branch 1)
 //   - acceptWithLoginHandler: anon User mit existing email (Branch 2)
@@ -518,7 +526,13 @@ export function createAuthRoutes(
     }
     const token = await jwt.sign(sessionForJwt);
     const csrfToken = generateToken();
-    setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
+    setAuthCookies(c, {
+      token,
+      csrfToken,
+      sameSite: cookieSameSite,
+      domain: cookieDomain,
+      ttlSeconds: jwt.ttlSeconds,
+    });
     return token;
   }
 
@@ -729,6 +743,26 @@ export function createAuthRoutes(
     });
   }
 
+  // Account-unlock mirrors email-verification (token-only confirm body) —
+  // clears the Redis lockout state instead of an entity field, see
+  // confirm-account-unlock.write.ts.
+  if (config.accountUnlock) {
+    const au = config.accountUnlock;
+    registerTokenRequestRoute({
+      api,
+      dispatcher,
+      path: Routes.authRequestAccountUnlock,
+      requestHandler: au.requestHandler,
+    });
+    registerTokenConfirmRoute({
+      api,
+      dispatcher,
+      path: Routes.authConfirmAccountUnlock,
+      confirmHandler: au.confirmHandler,
+      schema: VerifyEmailBody,
+    });
+  }
+
   // Self-Signup (Magic-Link). Request mountet wie reset/verify den
   // silent-success-Pfad mit Token-Mail. Confirm ist anders: returnt
   // SessionUser → die Route mintet JWT + setzt Cookies (Auto-Login

package/src/api/index.ts

@@ -5,10 +5,10 @@ export type {
   AuthMiddlewareOptions,
   AuthSessionChecker,
   AuthSessionStatus,
-  PatResolver,
   TenantExists,
   TenantLifecycleStatusResolver,
   TenantResolver,
+  TokenVerifier,
 } from "./auth-middleware";
 export { authMiddleware, getUser, PAT_TOKEN_PREFIX } from "./auth-middleware";
 export type {
@@ -34,8 +34,8 @@ export {
   etagMatches,
   parseIfNoneMatch,
 } from "./http-cache";
-export type { JwtHelper, JwtPayload } from "./jwt";
-export { createJwtHelper } from "./jwt";
+export type { JwtHelper, JwtKeyring, JwtPayload } from "./jwt";
+export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt";
 export { patAllows, qnMatches } from "./pat-scope";
 export { type RequestContextData, requestContext } from "./request-context";
 export { requestIdMiddleware } from "./request-id-middleware";

package/src/api/jwt.ts

@@ -23,10 +23,82 @@ export type JwtPayload = {
 export type JwtHelper = {
   sign(user: SessionUser): Promise<string>;
   verify(token: string): Promise<JwtPayload>;
+  // The TTL this helper signs tokens with, in seconds — the single source for
+  // callers (e.g. the auth-cookie's maxAge) that must stay coupled to the JWT's exp.
+  readonly ttlSeconds: number;
 };
 
-export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
-  const encodedSecret = new TextEncoder().encode(secret);
+// kid → secret. All entries verify; `signKid` picks the sign-key. Rotation:
+// add the new kid, flip signKid, keep the old kid around until in-flight
+// tokens expire.
+export type JwtKeyring = {
+  readonly keys: Readonly<Record<string, string>>;
+  readonly signKid: string;
+};
+
+type NormalizedKeyring = {
+  readonly verifyKeys: ReadonlyMap<string, Uint8Array>;
+  readonly signKid: string | undefined;
+  readonly signKey: Uint8Array;
+};
+
+function normalizeKeyring(secretOrKeyring: string | JwtKeyring): NormalizedKeyring {
+  if (typeof secretOrKeyring === "string") {
+    const key = new TextEncoder().encode(secretOrKeyring);
+    return { verifyKeys: new Map(), signKid: undefined, signKey: key };
+  }
+
+  const verifyKeys = new Map<string, Uint8Array>();
+  for (const [kid, secret] of Object.entries(secretOrKeyring.keys)) {
+    verifyKeys.set(kid, new TextEncoder().encode(secret));
+  }
+  const signKey = verifyKeys.get(secretOrKeyring.signKid);
+  if (!signKey) {
+    throw new Error(
+      `createJwtHelper: signKid "${secretOrKeyring.signKid}" is not present in the keyring`,
+    );
+  }
+  return { verifyKeys, signKid: secretOrKeyring.signKid, signKey };
+}
+
+// Tokens carry `kid` in the protected header when signed from a keyring — pick the
+// matching verify-key directly. Tokens without `kid` (single-secret form, or in-flight
+// tokens signed before a rotation) fall back to trying every verify-key.
+async function verifyWithKeyring(token: string, keyring: NormalizedKeyring, issuer: string) {
+  const { kid } = jose.decodeProtectedHeader(token);
+  if (typeof kid === "string" && keyring.verifyKeys.size > 0) {
+    const key = keyring.verifyKeys.get(kid);
+    if (!key) {
+      throw new Error(`JWT verification failed: unknown kid "${kid}"`);
+    }
+    return jose.jwtVerify(token, key, { issuer });
+  }
+
+  // ponytail: tries every key in the ring (O(keys) per legacy-token verify) — fine for a
+  // rotation window of a handful of keys, revisit if the keyring ever grows large.
+  const candidates =
+    keyring.verifyKeys.size > 0 ? [...keyring.verifyKeys.values()] : [keyring.signKey];
+  let lastError: unknown;
+  for (const key of candidates) {
+    try {
+      return await jose.jwtVerify(token, key, { issuer });
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  throw lastError instanceof Error
+    ? lastError
+    : new Error("JWT verification failed: no matching key");
+}
+
+const DEFAULT_JWT_TTL_SECONDS = 24 * 60 * 60;
+
+export function createJwtHelper(
+  secretOrKeyring: string | JwtKeyring,
+  issuer = "kumiko",
+  ttlSeconds = DEFAULT_JWT_TTL_SECONDS,
+): JwtHelper {
+  const keyring = normalizeKeyring(secretOrKeyring);
 
   return {
     async sign(user) {
@@ -36,19 +108,27 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
       };
       if (user.claims) body.claims = { ...user.claims };
 
+      const header: jose.JWTHeaderParameters = keyring.signKid
+        ? { alg: "HS256", kid: keyring.signKid }
+        : { alg: "HS256" };
+
+      // iat/exp share one `now` — jose's setIssuedAt()/setExpirationTime(Date)
+      // each read the clock separately, letting `exp - iat` drift by a
+      // second and making TTL-precision tests flaky.
+      const nowSec = Math.floor(Date.now() / 1000);
       const builder = new jose.SignJWT(body)
-        .setProtectedHeader({ alg: "HS256" })
+        .setProtectedHeader(header)
         .setSubject(String(user.id))
         .setIssuer(issuer)
-        .setIssuedAt()
-        .setExpirationTime("24h");
+        .setIssuedAt(nowSec)
+        .setExpirationTime(nowSec + ttlSeconds);
       if (user.sid) builder.setJti(user.sid);
 
-      return builder.sign(encodedSecret);
+      return builder.sign(keyring.signKey);
     },
 
     async verify(token) {
-      const { payload } = await jose.jwtVerify(token, encodedSecret, { issuer });
+      const { payload } = await verifyWithKeyring(token, keyring, issuer);
 
       // defence-in-depth: valid sig ≠ well-formed claims; malformed payload → throw → 401
       const tenantId = parseTenantId(payload["tenantId"]);
@@ -84,5 +164,66 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
       }
       return result;
     },
+    ttlSeconds,
   };
 }
+
+const JWT_KEY_VAR_PATTERN = /^JWT_SECRET_V(\d+)$/;
+const JWT_CURRENT_VERSION_VAR = "JWT_SECRET_CURRENT_VERSION";
+// Mirrors authEmailPasswordEnvSchema's JWT_SECRET.min(32) — HS256 minimum.
+// JWT_SECRET_V<n> bypasses that zod schema entirely (it only validates the
+// plain JWT_SECRET name), so this loader is the only gate for the rotation path.
+const MIN_JWT_SECRET_LENGTH = 32;
+
+function assertMinLength(name: string, value: string): void {
+  if (value.length < MIN_JWT_SECRET_LENGTH) {
+    throw new Error(`[jwt] ${name} must be ≥${MIN_JWT_SECRET_LENGTH} chars (HS256 minimum)`);
+  }
+}
+
+// Env-loader for createJwtHelper's secret-or-keyring param, analog to
+// secrets' loadKeyring: JWT_SECRET_V<n> (+ JWT_SECRET_CURRENT_VERSION picking
+// the active signKid) for rotation, falling back to plain JWT_SECRET when no
+// JWT_SECRET_V<n> is set — so a non-rotating deployment needs no new env vars.
+export function loadJwtSecretOrKeyring(
+  env: Readonly<Record<string, string | undefined>>,
+): string | JwtKeyring {
+  const keys: Record<string, string> = {};
+  for (const [name, value] of Object.entries(env)) {
+    const match = name.match(JWT_KEY_VAR_PATTERN);
+    if (!match || !value) continue;
+    assertMinLength(name, value);
+    // biome-ignore lint/style/noNonNullAssertion: regex group 1 always present
+    keys[`v${match[1]!}`] = value;
+  }
+
+  // skip: no JWT_SECRET_V<n> found — single-secret fallback.
+  if (Object.keys(keys).length === 0) {
+    const secret = env["JWT_SECRET"];
+    if (!secret) {
+      throw new Error(
+        "[jwt] JWT_SECRET not set — set JWT_SECRET for a single key, or " +
+          "JWT_SECRET_V1 (+ JWT_SECRET_CURRENT_VERSION=1) for a rotatable keyring.",
+      );
+    }
+    assertMinLength("JWT_SECRET", secret);
+    return secret;
+  }
+
+  const currentRaw = env[JWT_CURRENT_VERSION_VAR];
+  if (!currentRaw) {
+    throw new Error(
+      `[jwt] ${JWT_CURRENT_VERSION_VAR} not set — explicit current-version required ` +
+        "so adding a new JWT_SECRET_V<n> doesn't auto-promote it to the sign key.",
+    );
+  }
+  const signKid = `v${currentRaw}`;
+  if (!keys[signKid]) {
+    throw new Error(
+      `[jwt] ${JWT_CURRENT_VERSION_VAR}="${currentRaw}" not present in the keyring ` +
+        `(have versions: ${Object.keys(keys).sort().join(", ")}). ` +
+        `Check JWT_SECRET_V${currentRaw} is set.`,
+    );
+  }
+  return { keys, signKid };
+}

package/src/api/pii-leak-guard.ts

@@ -2,7 +2,10 @@ import type { MiddlewareHandler } from "hono";
 import { configuredPiiSubjectKms, PII_CIPHERTEXT_PREFIX } from "../crypto";
 
 const isProductionEnv = () => process.env["NODE_ENV"] === "production";
-const CIPHERTEXT_RE = /kumiko-pii:v1:[^"\s<>\\]*/g;
+// Version-agnostic: catches both the current PII_CIPHERTEXT_PREFIX and any
+// older/decrypt-only format version still present in unmigrated rows.
+const CIPHERTEXT_MARKER = "kumiko-pii:v";
+const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^"\s<>\\]*/g;
 
 // A PII subject ciphertext never belongs in an API response — its presence
 // means a raw DB read (fetchOne/selectMany) leaked to the surface. Dev/test
@@ -19,7 +22,7 @@ export function piiCiphertextResponseGuard(): MiddlewareHandler {
     if (!contentType.includes("application/json")) return;
     const text = await c.res.clone().text();
     // skip: clean response — the common case
-    if (!text.includes(PII_CIPHERTEXT_PREFIX)) return;
+    if (!text.includes(CIPHERTEXT_MARKER)) return;
 
     const detail =
       `[api] JSON response for ${c.req.method} ${c.req.path} contains a PII ciphertext ` +

package/src/api/server.ts

@@ -50,7 +50,7 @@ import { PUBLIC_API_PATHS } from "./api-constants";
 import { type AnonymousAccessConfig, authMiddleware, getUser } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
-import { createJwtHelper, type JwtHelper } from "./jwt";
+import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
@@ -69,8 +69,13 @@ import { createSseRoute } from "./sse-route";
 export type ServerOptions = {
   registry: Registry;
   context: AppContext;
-  jwtSecret: string;
+  jwtSecret: string | JwtKeyring;
   jwtIssuer?: string;
+  // JWT lifetime in seconds. Explicit always wins. When omitted, the default
+  // depends on `auth.sessionChecker`: wired (revocation possible) keeps the
+  // long-lived 24h default; unwired (stateless JWTs, no revocation) drops to
+  // 1h so a leaked stateless token has a much smaller exposure window.
+  jwtTtl?: number;
   dispatcherOptions?: Omit<DispatcherOptions, "lifecycle">;
   systemHooks?: SystemHooks;
   eventDedup?: EventDedup;
@@ -94,6 +99,8 @@ export type ServerOptions = {
     pollIntervalMs?: number;
     batchSize?: number;
     maxAttempts?: number;
+    rearmCooldownMs?: number;
+    maxRearmCount?: number;
     // Opt out of building the dispatcher even if consumers exist — e.g. ops
     // runs a dedicated dispatcher process, or a test needs to control the
     // consumer lifecycle manually.
@@ -238,7 +245,15 @@ export function buildServer(options: ServerOptions): KumikoServer {
     );
   }
 
-  const jwt = createJwtHelper(options.jwtSecret, options.jwtIssuer);
+  // Stateless JWTs (no sessionChecker → no revocation) default to a shorter
+  // TTL than session-backed ones, since a leaked stateless token can't be
+  // revoked and stays valid until it expires. Explicit jwtTtl always wins.
+  const defaultJwtTtl = options.auth?.sessionChecker ? 24 * 60 * 60 : 60 * 60;
+  const jwt = createJwtHelper(
+    options.jwtSecret,
+    options.jwtIssuer,
+    options.jwtTtl ?? defaultJwtTtl,
+  );
   const sseBroker = options.sseBroker ?? createSseBroker();
 
   // Resolve the per-process instance identifier. Prefer explicit
@@ -566,8 +581,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // middleware can reject revoked sids on every request.
   const jwtGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
-    ...(options.auth?.sessionStrictMode ? { strictMode: options.auth.sessionStrictMode } : {}),
-    ...(options.auth?.patResolver ? { patResolver: options.auth.patResolver } : {}),
+    ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
     ...(options.auth?.resolveTenantLifecycleStatus
       ? { resolveTenantLifecycleStatus: options.auth.resolveTenantLifecycleStatus }
       : {}),

package/src/bun-db/__tests__/select-many-retry.test.ts

@@ -0,0 +1,79 @@
+// #1163: Bun.SQL can hand out a closed connection under load (AbortError
+// "The connection was closed."). Pure reads retry exactly once on a fresh
+// pool checkout; tx handles, non-matching errors, and genuine user aborts
+// must NOT retry.
+
+import { describe, expect, test } from "bun:test";
+import { buildEntityTable } from "../../db/table-builder";
+import { selectMany } from "../query";
+
+function closedConnectionError(): Error {
+  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
+}
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin?: () => never;
+  calls: number;
+};
+
+function fakeClient(failures: Error[], opts: { tx?: boolean } = {}): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [{ id: "r1", title: "ok", tenant_id: "t1", inserted_at: null, updated_at: null }];
+    },
+  };
+  // A top-level pool client has begin(); a transaction handle does not.
+  if (!opts.tx)
+    client.begin = () => {
+      throw new Error("not used in test");
+    };
+  return client;
+}
+
+const table = buildEntityTable("note", {
+  fields: { title: { type: "text", required: true } },
+});
+
+describe("selectMany — closed-connection retry (#1163)", () => {
+  test("retries once on AbortError 'connection was closed' and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()]);
+    const rows = await selectMany(db, table);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.title).toBe("ok");
+    expect(db.calls).toBe(2);
+  });
+
+  test("gives up after the single retry when the connection stays closed", async () => {
+    const db = fakeClient([closedConnectionError(), closedConnectionError()]);
+    await expect(selectMany(db, table)).rejects.toThrow("connection was closed");
+    expect(db.calls).toBe(2);
+  });
+
+  test("never retries on a transaction handle (no begin)", async () => {
+    const db = fakeClient([closedConnectionError()], { tx: true });
+    await expect(selectMany(db, table)).rejects.toThrow("connection was closed");
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry a genuine user abort (different message)", async () => {
+    const userAbort = Object.assign(new Error("The operation was aborted."), {
+      name: "AbortError",
+    });
+    const db = fakeClient([userAbort]);
+    await expect(selectMany(db, table)).rejects.toThrow("operation was aborted");
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry generic query errors", async () => {
+    const syntax = Object.assign(new Error("syntax error at or near"), { name: "PostgresError" });
+    const db = fakeClient([syntax]);
+    await expect(selectMany(db, table)).rejects.toThrow("syntax error");
+    expect(db.calls).toBe(1);
+  });
+});

package/src/bun-db/query.ts

@@ -562,6 +562,38 @@ function buildWhereClause(
   return { sqlText: conditions.join(" AND "), values };
 }
 
+// #1163: under load the Bun.SQL pool can hand out a connection the server
+// already closed ("The connection was closed.", AbortError code 20) — no
+// validate-on-checkout exists. One retry re-checks out a fresh connection;
+// safe for pure reads. Tx handles are never retried: their transaction is
+// dead once the connection dropped, and a retry would run on the same dead
+// handle. Detection is name+message (not name alone) so a genuine user
+// abort (AbortSignal cancel) is NOT retried.
+function isClosedConnectionError(err: unknown): boolean {
+  if (err === null || typeof err !== "object") return false;
+  const e = err as { name?: unknown; message?: unknown };
+  return (
+    e.name === "AbortError" &&
+    typeof e.message === "string" &&
+    /connection was closed/i.test(e.message)
+  );
+}
+
+async function unsafeRead<TRow>(
+  db: AnyDb,
+  sqlText: string,
+  params: readonly unknown[],
+): Promise<readonly TRow[]> {
+  const raw = asRawClient(db);
+  try {
+    return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+  } catch (err) {
+    // TransactionSql has savepoint(), only a top-level pool client has begin().
+    if (typeof raw.begin !== "function" || !isClosedConnectionError(err)) throw err;
+    return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+  }
+}
+
 // biome-ignore lint/suspicious/noExplicitAny: opt-in default loosens row type for unannotated test fixtures
 export async function selectMany<TRow = any>(
   db: AnyDb,
@@ -598,7 +630,7 @@ export async function selectMany<TRow = any>(
     }
     sqlText += ` LIMIT ${options.limit}`;
   }
-  const raw = (await asRawClient(db).unsafe(sqlText, values)) as readonly Record<string, unknown>[];
+  const raw = (await unsafeRead(db, sqlText, values)) as readonly Record<string, unknown>[];
   return coerceRows(raw, info) as readonly TRow[];
 }
 
@@ -832,7 +864,7 @@ export async function countWhere(
     sqlText += ` WHERE ${w.sqlText}`;
     values = w.values;
   }
-  const rows = (await asRawClient(db).unsafe(sqlText, values)) as readonly { count: number }[];
+  const rows = (await unsafeRead(db, sqlText, values)) as readonly { count: number }[];
   return rows[0]?.count ?? 0;
 }
 

package/src/consumer-cli.ts

@@ -0,0 +1,87 @@
+// Shared core for the standalone consumer-ops CLI (status | restart).
+//
+// A dead event consumer (halt-on-poison after maxAttempts) previously had no
+// recovery surface in the standalone prod bundle — only raw SQL against
+// kumiko_event_consumers. Mirrors schema-cli.ts's shape (single runXCli(argv,
+// out) entry point, own DB connection) so `kumiko-consumer` ships the same
+// way `kumiko-schema` does.
+
+import { createDbConnection } from "./db";
+import { getConsumerState, restartConsumer } from "./pipeline";
+import { ensureTemporalPolyfill } from "./time";
+
+export type ConsumerCliOut = {
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+};
+
+function parseInstanceIdFlag(argv: readonly string[]): string | undefined {
+  const i = argv.indexOf("--instance-id");
+  return i === -1 ? undefined : argv[i + 1];
+}
+
+export async function runConsumerCli(
+  argv: readonly string[],
+  out: ConsumerCliOut,
+): Promise<number> {
+  // The standalone bundle never runs runProdApp/runDevApp's boot, which is
+  // where Temporal normally gets installed — ConsumerRecoveryState.updatedAt
+  // is a Temporal.Instant, so without this every subcommand throws "Temporal
+  // is not defined" (same failure mode as schema-cli, see its polyfill test).
+  await ensureTemporalPolyfill();
+  const sub = argv[0];
+
+  if (sub !== "status" && sub !== "restart") {
+    out.log("");
+    out.log("  Subcommands:");
+    out.log("    status <name> [--instance-id <id>]   Zeigt Status + Cursor eines Consumers");
+    out.log("    restart <name> [--instance-id <id>]  Reaktiviert einen dead-Consumer (idle)");
+    out.log("");
+    return sub === undefined ? 0 : 1;
+  }
+
+  const name = argv[1];
+  if (!name) {
+    out.err(`  Usage: consumer ${sub} <name> [--instance-id <id>]`);
+    return 1;
+  }
+  const instanceId = parseInstanceIdFlag(argv);
+
+  const dbUrl = process.env["DATABASE_URL"];
+  if (!dbUrl) {
+    out.err("  DATABASE_URL not set.");
+    return 1;
+  }
+  const { db, close } = createDbConnection(dbUrl);
+  try {
+    if (sub === "status") {
+      const state = await getConsumerState(db, name, instanceId);
+      if (!state) {
+        out.err(`  Consumer "${name}" (instance_id="${instanceId ?? "__shared__"}") not found.`);
+        return 1;
+      }
+      out.log("");
+      out.log(`  ${state.name} (instance_id="${state.instanceId}")`);
+      out.log(`    status:      ${state.status}`);
+      out.log(`    cursor:      ${state.lastProcessedEventId}`);
+      out.log(`    attempts:    ${state.attempts}`);
+      out.log(`    rearmCount:  ${state.rearmCount}`);
+      out.log(`    lastError:   ${state.lastError ?? "-"}`);
+      out.log(`    updatedAt:   ${state.updatedAt.toString()}`);
+      out.log("");
+      return 0;
+    }
+
+    // restart
+    const result = await restartConsumer(db, name, instanceId);
+    out.log("");
+    out.log(`  ✓ ${result.name} (instance_id="${result.instanceId}") → ${result.status}`);
+    out.log("");
+    return 0;
+  } catch (e) {
+    out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  } finally {
+    await close();
+  }
+}