@k2b/cloud 0.33.0 → 0.34.0

package/src/contracts/app.ts

@@ -2,7 +2,7 @@ import type { Sync } from "@k2b/sync";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
-import type { DashboardWidgetPresentation, DashboardWidgetSize } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize, WidgetSettingsDeclaration } from "./widgets";
 
 /**
  * One link entry contributed by an app to the global legal/info footer
@@ -73,9 +73,12 @@ export type AppPresentationTranslation = {
   widgets?: Readonly<Record<string, AppWidgetTranslation>>;
 };
 
+/** Translated widget presentation, keyed by stable widget, setting, and option identifiers. */
 export type AppWidgetTranslation = {
   title?: string;
   description?: string;
+  /** Setting presentation keyed by setting name, with option labels keyed by option value. */
+  settings?: Readonly<Record<string, { label?: string; placeholder?: string; options?: Readonly<Record<string, string>> }>>;
 };
 
 export type AppPresentationCatalog = {
@@ -163,6 +166,7 @@ export type AppMeta = {
  */
 export type AppNavBadge = { count: number };
 
+/** A widget endpoint and its board presentation; the handler owns resource authorization. */
 export type WidgetEndpoint = {
   /** Unique-within-the-app id, e.g. "open-requests". */
   id: string;
@@ -179,6 +183,8 @@ export type WidgetEndpoint = {
   sizes?: readonly DashboardWidgetSize[];
   /** Size the widget starts in, one of `sizes`. Defaults to the largest offered size. */
   defaultSize?: DashboardWidgetSize;
+  /** Optional per-entry settings; handlers must work without them and authorize selected resources. */
+  settings?: WidgetSettingsDeclaration;
   /**
    * Put the widget on the default board of everyone who may see it and list it under "Suggested for you" in the
    * gallery. Suggest only widgets that are useful without any setup.

package/src/contracts/capabilities.ts

@@ -15,6 +15,8 @@ export const CAPABILITY_PROTOCOL_VERSION = 2 as const;
 export const CAPABILITY_MAX_REQUEST_BYTES = 256 * 1024;
 export const CAPABILITY_MAX_RESULT_BYTES = 256 * 1024;
 export const CAPABILITY_MAX_CATALOG_BYTES = 2 * 1024 * 1024;
+export const CAPABILITY_QUALIFIED_ID_MAX_LENGTH = 180;
+export const CLOUD_RESOURCE_ID_MAX_LENGTH = 512;
 
 export const CAPABILITY_FRAMEWORK_ERROR_CODES = {
   appUnavailable: "APP_UNAVAILABLE",
@@ -75,18 +77,20 @@ export const CapabilityLocalIdSchema = z
 export const CapabilityQualifiedIdSchema = z
   .string()
   .min(3)
-  .max(180)
+  .max(CAPABILITY_QUALIFIED_ID_MAX_LENGTH)
   .regex(CAPABILITY_QUALIFIED_ID_PATTERN, "Expected a namespaced capability id such as contacts.contact");
 
 export const CloudResourceRefSchema = z
   .object({
     type: CapabilityQualifiedIdSchema.describe("Namespaced resource type declared by the owning app."),
-    id: z.string().min(1).max(512).describe("Stable app-owned resource identifier."),
+    id: z.string().min(1).max(CLOUD_RESOURCE_ID_MAX_LENGTH).describe("Stable app-owned resource identifier."),
   })
   .strict();
 
 export type CloudResourceRef = z.infer<typeof CloudResourceRefSchema>;
 
+export { cloudResourceHref } from "./resource-href";
+
 export const CloudResourceReferenceSchema = CloudResourceRefSchema.extend({
   title: z.string().min(1).max(500).optional().describe("Optional current user-facing resource label."),
   preview: z.string().max(2000).optional().describe("Optional short plain-text context for the resource."),
@@ -95,6 +99,13 @@ export const CloudResourceReferenceSchema = CloudResourceRefSchema.extend({
 
 export type CloudResourceReference = z.infer<typeof CloudResourceReferenceSchema>;
 
+// Consumer permalinks may encode all 512 UTF-16 units of an id (up to 4,608 characters).
+export const CloudResourceHrefSchema = z.string().min(1).max(8192).regex(CLOUD_PATH_PATTERN);
+
+export const LinkedCloudResourceReferenceSchema = CloudResourceReferenceSchema.extend({
+  href: z.union([CloudResourceHrefSchema, z.url({ protocol: /^https?$/ }).max(8192)]).optional(),
+}).strict();
+
 export const CapabilitySemanticLinkSchema = z
   .object({
     rel: z.enum(["open", "edit", "status", "preview", "download"]).describe("Semantic relationship; clients decide how to present it."),
@@ -219,7 +230,10 @@ export const capabilityResultSchema = <T extends z.ZodType>(
       data,
       stream: CapabilityStreamSchema.optional(),
       summary: z.string().trim().min(1).max(500).optional(),
-      refs: z.array(CloudResourceReferenceSchema).max(100).optional(),
+      refs: z
+        .array(options?.consumer ? LinkedCloudResourceReferenceSchema : CloudResourceReferenceSchema)
+        .max(100)
+        .optional(),
       page: CapabilityPageSchema.optional(),
       links: z.array(CapabilitySemanticLinkSchema).max(20).optional(),
       presentation: options?.consumer
@@ -241,8 +255,14 @@ export const capabilityResultSchema = <T extends z.ZodType>(
       }
     }) as unknown as z.ZodType<CapabilityResult<z.output<T>>>;
 
-export const capabilityResultJsonSchema = (dataSchema: Record<string, unknown>): Record<string, unknown> =>
-  z.toJSONSchema(capabilityResultSchema(z.fromJSONSchema(structuredClone(dataSchema))), { io: "output" }) as Record<string, unknown>;
+export const capabilityResultJsonSchema = (
+  dataSchema: Record<string, unknown>,
+  options?: { consumer?: boolean },
+): Record<string, unknown> =>
+  z.toJSONSchema(capabilityResultSchema(z.fromJSONSchema(structuredClone(dataSchema)), options), { io: "output" }) as Record<
+    string,
+    unknown
+  >;
 
 export const CapabilityErrorSchema = z
   .object({

package/src/contracts/registry.ts

@@ -2,7 +2,7 @@ import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPre
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
-import type { DashboardWidgetPresentation, DashboardWidgetSize } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize, WidgetSettingsDeclaration } from "./widgets";
 
 /**
  * App-registry entry type. Populated internally by `defineApp()` + the
@@ -54,6 +54,8 @@ export type AppRegistryLegalLink = {
 
 /** A widget declaration as the registry carries it; see `WidgetEndpoint`. Older apps send only `id` and `path`. */
 export type AppRegistryWidget = {
+  /** Per-entry setting declaration, validated again when listed. */
+  settings?: WidgetSettingsDeclaration;
   id: string;
   /** Absolute path on the app's HTTP service, e.g. "/api/quotes/widget/random". */
   path: string;

package/src/contracts/resource-href.ts

@@ -0,0 +1,7 @@
+import type { CloudResourceRef } from "./capabilities";
+
+/**
+ * The permanent Cloud path of a resource. The fixed `~` keeps the ids `.` and `..` from being read as dot segments.
+ * This module stays free of runtime imports: the `cld` host loads it at startup.
+ */
+export const cloudResourceHref = (ref: CloudResourceRef): string => `/open/${ref.type}/~${encodeURIComponent(ref.id)}`;

package/src/contracts/widgets.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { CAPABILITY_QUALIFIED_ID_MAX_LENGTH, CLOUD_RESOURCE_ID_MAX_LENGTH, type CloudResourceRef } from "./capabilities";
 
 /**
  * Widget JSON contract — what an app's widget endpoint must return when the
@@ -64,6 +65,59 @@ export type DashboardWidgetSize = (typeof DASHBOARD_WIDGET_SIZES)[number];
 export const WIDGET_TITLE_MAX_LENGTH = 80;
 /** Longest declared widget description, in characters: one sentence in the widget gallery. */
 export const WIDGET_DESCRIPTION_MAX_LENGTH = 200;
+/**
+ * Core signs `widget.read:<widgetId>`; the invocation token's OperationSchema limits operations to 200 characters
+ * matching /^[a-z][a-z0-9:._-]*$/ (services/identity/invocation-token.ts). Longer IDs or other characters cannot be invoked.
+ */
+export const WIDGET_ID_MAX_LENGTH = 188;
+/** `<appId>/<widgetId>`; the invocation token's audience rule limits app IDs to 80 characters. */
+export const WIDGET_KEY_MAX_LENGTH = 80 + 1 + WIDGET_ID_MAX_LENGTH;
+
+/** Maximum settings a widget can declare. */
+export const WIDGET_SETTINGS_MAX_FIELDS = 4;
+/** Maximum setting name length, matching /^[a-z][a-zA-Z0-9]{0,31}$/. */
+export const WIDGET_SETTING_NAME_MAX_LENGTH = 32;
+/** Maximum options in a choice setting; at least one is required. */
+export const WIDGET_SETTING_MAX_OPTIONS = 6;
+/** Maximum text setting length, also used when no maxLength is declared. */
+export const WIDGET_SETTING_TEXT_MAX_LENGTH = 200;
+/** Maximum board entries in one widget stream request. */
+export const WIDGET_REQUEST_MAX_ENTRIES = 100;
+/** Maximum board entry identifier length, in characters. */
+export const WIDGET_REQUEST_MAX_ID_LENGTH = 120;
+const jsonCodeUnitMaxBytes = "\\u001f".length;
+const resourceRefMaxBytes =
+  '{"type":"","id":""}'.length + CAPABILITY_QUALIFIED_ID_MAX_LENGTH + CLOUD_RESOURCE_ID_MAX_LENGTH * jsonCodeUnitMaxBytes;
+const settingMemberMaxBytes = '"":'.length + WIDGET_SETTING_NAME_MAX_LENGTH + resourceRefMaxBytes;
+const settingsMaxBytes = "{}".length + WIDGET_SETTINGS_MAX_FIELDS * settingMemberMaxBytes + (WIDGET_SETTINGS_MAX_FIELDS - 1) * ",".length;
+const sizeNameMaxBytes = Math.max(...DASHBOARD_WIDGET_SIZES.map((size) => size.length));
+const requestEntryMaxBytes =
+  '{"id":"","key":"","size":"","settings":}'.length +
+  WIDGET_REQUEST_MAX_ID_LENGTH * jsonCodeUnitMaxBytes +
+  WIDGET_KEY_MAX_LENGTH +
+  sizeNameMaxBytes +
+  settingsMaxBytes;
+/**
+ * Largest compact JSON POST body in UTF-8: 100 entries with maximum IDs, keys, size names and four settings.
+ * Free-form entry and resource IDs need up to six bytes per UTF-16 code unit (e.g. `\u001f`); keys, size names,
+ * setting names and resource types are ASCII. A resource reference is larger than 200 text characters at six bytes
+ * each. Include every object's punctuation and the commas between entries and settings.
+ */
+export const WIDGET_REQUEST_MAX_BYTES =
+  '{"widgets":['.length + WIDGET_REQUEST_MAX_ENTRIES * requestEntryMaxBytes + (WIDGET_REQUEST_MAX_ENTRIES - 1) * ",".length + "]}".length;
+
+/** A widget's editable setting; resource values carry identity, never authorization. */
+export type WidgetSettingField =
+  | { kind: "choice"; label: string; options: readonly { label: string; value: string }[]; default?: string }
+  | { kind: "resource"; label: string; type: string }
+  | { kind: "toggle"; label: string; default?: boolean }
+  | { kind: "text"; label: string; placeholder?: string; maxLength?: number };
+/** Settings keyed by short camelCase names, shared by discovery and request validation. */
+export type WidgetSettingsDeclaration = Readonly<Record<string, WidgetSettingField>>;
+/** A validated setting value; a handler must still authorize every resource reference. */
+export type WidgetSettingValue = string | boolean | CloudResourceRef;
+/** Validated widget settings; handlers must also work when values are missing. */
+export type WidgetSettings = Readonly<Record<string, WidgetSettingValue>>;
 
 export const isDashboardWidgetSize = (value: unknown): value is DashboardWidgetSize =>
   DASHBOARD_WIDGET_SIZES.some((size) => size === value);
@@ -89,10 +143,15 @@ export const fitWidgetSize = (
   widget: { sizes: readonly DashboardWidgetSize[]; defaultSize: DashboardWidgetSize },
 ): DashboardWidgetSize => (isDashboardWidgetSize(requested) && widget.sizes.includes(requested) ? requested : widget.defaultSize);
 
-/** What the dashboard asks a widget handler for, read with `getWidgetRequest(c)`. */
+/**
+ * What the dashboard asks a widget handler for, read with `getWidgetRequest(c)`. Settings are validated against the
+ * declaration; handlers must still authorize every chosen resource and work without settings.
+ */
 export type WidgetRequest = {
   /** The size the widget is shown in, always one the widget declares. */
   size: DashboardWidgetSize;
+  /** Declared, validated values with choice and toggle defaults filled. */
+  settings: WidgetSettings;
 };
 
 export const WidgetAccentSchema = z
@@ -237,12 +296,27 @@ export const widgetKey = (appId: string, widgetId: string): string => `${appId}/
 export type WidgetStreamStatus = "ok" | "empty" | "forbidden" | "timeout" | "error";
 
 /**
- * One line of `GET /api/widgets/v1` (`application/x-ndjson`): `start` names the widgets Core asks, in registry
- * order; one `widget` line follows per widget in the order they finish; `done` closes the stream. Every widget named
- * in `start` gets exactly one line.
+ * One line of `GET` or `POST /api/widgets/v1` (`application/x-ndjson`). GET names widget keys in registry order; POST
+ * names entry ids in request order. One `widget` line follows per entry in the order they finish; `done` closes the
+ * stream. Every name in `start` gets exactly one line. Only POST widget lines include a board entry id.
  */
 export type WidgetStreamLine =
   | { type: "start"; widgets: string[] }
-  | { type: "widget"; key: string; status: "ok"; widget: WidgetResponse; ms: number }
-  | { type: "widget"; key: string; status: Exclude<WidgetStreamStatus, "ok">; ms: number }
+  | {
+      type: "widget";
+      /** Board entry id, set only for POST entries. */
+      id?: string;
+      key: string;
+      status: "ok";
+      widget: WidgetResponse;
+      ms: number;
+    }
+  | {
+      type: "widget";
+      /** Board entry id, set only for POST entries. */
+      id?: string;
+      key: string;
+      status: Exclude<WidgetStreamStatus, "ok">;
+      ms: number;
+    }
   | { type: "done"; status: "complete" | "partial" };

package/src/desktop/index.ts

@@ -304,8 +304,9 @@ let sqlInstance: DesktopSql | null = null;
 
 const getSql = (): DesktopSql => {
   if (sqlInstance) return sqlInstance;
-  const req = runtimeRequire();
-  if (!req || typeof window !== "undefined") throw new Error("desktop.sql is only available in the Bun desktop process.");
+  // Checked before `runtimeRequire`: its `Function` probe would report a `script-src` violation under a CSP without 'unsafe-eval'.
+  const req = typeof window === "undefined" ? runtimeRequire() : null;
+  if (!req) throw new Error("desktop.sql is only available in the Bun desktop process.");
   const requireFn = req as (id: string) => unknown;
 
   const { Database } = requireFn("bun:sqlite") as { Database: new (path: string) => any };

package/src/desktop/solid.tsx

@@ -1,5 +1,5 @@
 import { suppressTextSelection } from "@k2b/ui";
-import { deserialize as deserializeProps, serialize as serializeProps } from "seroval";
+import { fromJSON, toJSON } from "seroval";
 import type { Component, JSX, ParentProps } from "solid-js";
 import { children, createContext, createMemo, createSignal, For, onCleanup, onMount, Show, useContext } from "solid-js";
 import { Dynamic, Portal } from "solid-js/web";
@@ -48,7 +48,7 @@ export const defineDesktopWindows = <Definitions extends Record<string, DesktopW
       ({
         kind: desktopWindowDescriptorKind,
         name,
-        props: serializeProps(props ?? {}),
+        props: JSON.stringify(toJSON(props ?? {})),
       }) satisfies DesktopWindowDescriptor as unknown as JSX.Element;
   }
 
@@ -69,12 +69,14 @@ export function DesktopWindowHost<Definitions extends Record<string, DesktopWind
   const descriptor = createMemo(() => nativeDescriptor());
   const component = createMemo(() => {
     const current = descriptor();
-    return current ? props.windows.__desktopWindowDefinitions[current.name] : null;
+    if (!current) return null;
+    // The name comes from the URL: only a registered window resolves, never an inherited member such as `constructor`.
+    const definitions = props.windows.__desktopWindowDefinitions;
+    return Object.hasOwn(definitions, current.name) ? definitions[current.name] : null;
   });
   const windowProps = createMemo(() => {
     const current = descriptor();
-    if (!current) return {};
-    return deserializeProps<Record<string, unknown>>(current.props);
+    return current && component() ? fromJSON<Record<string, unknown>>(JSON.parse(current.props)) : {};
   });
 
   return createMemo(() => {

package/src/server/widget-request.ts

@@ -1,8 +1,24 @@
 import type { Context } from "hono";
-import { type DashboardWidgetSize, fitWidgetSize, resolveWidgetSizes, type WidgetRequest } from "../contracts/widgets";
+import { parseWidgetSettings } from "../_internal/widget-settings";
+import {
+  type DashboardWidgetSize,
+  fitWidgetSize,
+  resolveWidgetSizes,
+  type WidgetRequest,
+  type WidgetSettingsDeclaration,
+} from "../contracts/widgets";
 
 /** The query parameter Core uses to ask a widget handler for one size. */
 export const WIDGET_SIZE_PARAM = "size";
+/** The query parameter Core uses to send one entry's validated settings. */
+export const WIDGET_SETTINGS_PARAM = "settings";
+/**
+ * Bun's default maximum request head is 16 KiB (a 17,000-character query was verified to return 431). The invocation
+ * JWT uses up to 4 KiB (IDENTITY_MAX_COMPACT_TOKEN_BYTES), and the path and other forwarded headers use about 1–2 KiB,
+ * leaving headroom for 8 KiB of URL-encoded settings. Core measures that encoding and never forwards more. A decoded
+ * value is never longer than its encoding, so the app never drops settings Core sends; longer input counts as missing.
+ */
+export const WIDGET_SETTINGS_PARAM_MAX_LENGTH = 8 * 1024;
 
 const requests = new WeakMap<Request, WidgetRequest>();
 
@@ -12,9 +28,21 @@ const requests = new WeakMap<Request, WidgetRequest>();
  */
 export const setWidgetRequest = (
   c: Context,
-  declaration: { sizes?: readonly DashboardWidgetSize[]; defaultSize?: DashboardWidgetSize },
+  declaration: { sizes?: readonly DashboardWidgetSize[]; defaultSize?: DashboardWidgetSize; settings?: WidgetSettingsDeclaration },
 ): WidgetRequest => {
-  const request = { size: fitWidgetSize(c.req.query(WIDGET_SIZE_PARAM), resolveWidgetSizes(declaration)) };
+  const param = c.req.query(WIDGET_SETTINGS_PARAM);
+  let raw: unknown;
+  if (param !== undefined && param.length <= WIDGET_SETTINGS_PARAM_MAX_LENGTH) {
+    try {
+      raw = JSON.parse(param);
+    } catch {
+      /* Malformed settings are treated as missing values. */
+    }
+  }
+  const request = {
+    size: fitWidgetSize(c.req.query(WIDGET_SIZE_PARAM), resolveWidgetSizes(declaration)),
+    settings: parseWidgetSettings(declaration.settings, raw),
+  };
   requests.set(c.req.raw, request);
   return request;
 };
@@ -22,6 +50,7 @@ export const setWidgetRequest = (
 /**
  * What the dashboard asks this widget handler for. `size` is always one of the sizes the widget declares; return the
  * content that fits it, for example only the one number in `small`. Outside a dashboard invocation, such as a request
- * to the handler's own public route, the request is `large`, the height every widget had before sizes existed.
+ * to the handler's own public route, the request is `{ size: "large", settings: {} }`. Settings are validated against
+ * the declaration. The handler must still authorize every chosen resource on every call and work without settings.
  */
-export const getWidgetRequest = (c: Context): WidgetRequest => requests.get(c.req.raw) ?? { size: "large" };
+export const getWidgetRequest = (c: Context): WidgetRequest => requests.get(c.req.raw) ?? { size: "large", settings: {} };

package/src/services/app-approval.ts

@@ -296,7 +296,8 @@ export const createAppApprovalService = (
           UPDATE auth.app_devices d SET action_wake_at=now(), action_wake_ref=${approvalId}::uuid
           WHERE d.id IN (
             SELECT device.id FROM auth.app_devices device JOIN approvals.requests r ON r.approver_user_id=device.user_id
-            WHERE r.id=${approvalId}::uuid AND r.status='pending' AND r.expires_at > now()
+            JOIN auth.users u ON u.id=r.approver_user_id
+            WHERE r.id=${approvalId}::uuid AND r.status='pending' AND r.expires_at > now() AND r.approver_auth_epoch=u.auth_epoch
               AND EXISTS (SELECT 1 FROM ai.pending_actions p JOIN ai.turns t ON t.id=p.turn_id
                 WHERE p.approval_id=r.id AND p.status='pending' AND t.run_config->>'signedInSession' IS NULL)
               AND device.issuer=${cfg.issuer} AND device.revoked_at IS NULL AND device.push_token IS NOT NULL
@@ -661,7 +662,8 @@ export const createAppApprovalService = (
       };
       const result = (state: string) => ({ state, pollAfterSeconds: limits.pollSeconds });
       if (!hold) return result((await read()).state);
-      // Listen before the first read so a decision committed in between still wakes this request.
+      // Listen before the first read so a decision committed in between usually wakes this request.
+      // live() has no subscription-ready barrier, so the hint is best effort; the deadline re-read is the guarantee.
       const waiting = new AbortController();
       const ended = new Promise((resolve) => waiting.signal.addEventListener("abort", resolve, { once: true }));
       const stop = () => waiting.abort();

package/src/services/approvals/index.ts

@@ -72,6 +72,8 @@ export type ApprovalRequest = {
   reviewDigest: string;
   status: ApprovalStatus;
   decidedVia: ApprovalDecisionChannel | null;
+  decidedDeviceId: string | null;
+  approverAuthEpoch: string | null;
   decidedAt: Date | null;
   consumedAt: Date | null;
   createdAt: Date;
@@ -83,11 +85,23 @@ const columns = () => sql`id, app_id AS "appId", action, approval_scope AS "appr
   requester_kind AS "requesterKind", requester_ref AS "requesterRef", requester_app_id AS "requesterAppId",
   requester_title AS "requesterTitle", subject_id AS "subjectId", approver_user_id AS "approverUserId",
   assurance, sentence, details, args_digest AS "argsDigest", review_digest AS "reviewDigest", status,
+  decided_device_id AS "decidedDeviceId", approver_auth_epoch::text AS "approverAuthEpoch",
   decided_via AS "decidedVia", decided_at AS "decidedAt", consumed_at AS "consumedAt",
   created_at AS "createdAt", expires_at AS "expiresAt"`;
 
 const transaction = <T>(db: SQL | undefined, run: (tx: SQL) => Promise<T>): Promise<T> => (db && db !== sql ? run(db) : sql.begin(run));
 
+const lockDecider = async (tx: SQL, userId: string, deviceId: string | null) => {
+  // User before device before request: sign-out everywhere updates the user first, then devices.
+  const [user] = await tx<{ epoch: string }[]>`SELECT auth_epoch::text AS epoch FROM auth.users WHERE id=${userId}::uuid FOR SHARE`;
+  const [device] =
+    deviceId === null
+      ? []
+      : await tx`SELECT 1 FROM auth.app_devices
+    WHERE id=${deviceId}::uuid AND user_id=${userId}::uuid AND revoked_at IS NULL FOR SHARE`;
+  return { epoch: user?.epoch ?? null, deviceActive: !!device };
+};
+
 export type ApprovalRequestResult = { ok: true; id: string } | { ok: false; code: "CONFLICT" };
 /**
  * Records the question once per requester reference. Asking again, for example after a worker restart, returns the
@@ -103,10 +117,10 @@ export const request = async (input: ApprovalRequestInput, db?: SQL): Promise<Ap
   return transaction(db, async (tx): Promise<ApprovalRequestResult> => {
     const [row] = await tx<{ id: string }[]>`
       INSERT INTO approvals.requests (app_id, action, approval_scope, requester_kind, requester_ref, requester_app_id,
-        requester_title, subject_id, approver_user_id, assurance, sentence, details, args_digest, review_digest, expires_at)
+        requester_title, subject_id, approver_user_id, approver_auth_epoch, assurance, sentence, details, args_digest, review_digest, expires_at)
       VALUES (${input.appId}, ${input.action}, ${input.approvalScope ?? null}, ${input.requester.kind}, ${input.requester.ref},
         ${input.requester.appId}, ${input.requester.title ?? null}, ${input.subjectId}::uuid, ${input.approverUserId}::uuid,
-        ${input.assurance}, ${input.sentence}, ${JSON.stringify(input.review ?? null)}::text::jsonb,
+        (SELECT auth_epoch FROM auth.users WHERE id=${input.approverUserId}::uuid), ${input.assurance}, ${input.sentence}, ${JSON.stringify(input.review ?? null)}::text::jsonb,
         ${approvalArgsDigest(input.input)}, ${approvalReviewDigest(input.review)}, now() + (${expiresInMs} * interval '1 millisecond'))
       ON CONFLICT (requester_kind, requester_ref) DO NOTHING
       RETURNING id
@@ -115,6 +129,7 @@ export const request = async (input: ApprovalRequestInput, db?: SQL): Promise<Ap
     const [open] = await tx<{ id: string }[]>`SELECT id FROM approvals.requests
       WHERE requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref}
         AND status='pending' AND expires_at > now() AND subject_id=${input.subjectId}::uuid
+        AND approver_auth_epoch=(SELECT auth_epoch FROM auth.users WHERE id=${input.approverUserId}::uuid)
         AND approver_user_id=${input.approverUserId}::uuid AND app_id=${input.appId} AND action=${input.action}`;
     return open ? { ok: true, id: open.id } : { ok: false, code: "CONFLICT" };
   });
@@ -137,12 +152,9 @@ export const decide = async (
   db?: SQL,
 ): Promise<ApprovalDecisionResult> => {
   const result = await transaction(db, async (tx): Promise<ApprovalDecisionResult> => {
-    // Lock the device before the request so revocation and the decision serialize.
-    if (actor.deviceId !== undefined) {
-      const [device] = await tx`SELECT 1 FROM auth.app_devices
-        WHERE id=${actor.deviceId}::uuid AND user_id=${actor.userId}::uuid AND revoked_at IS NULL FOR SHARE`;
-      if (!device) return { ok: false, code: "NOT_FOUND" };
-    }
+    // Lock the approver and device before the request so revocation and decisions serialize.
+    const decider = await lockDecider(tx, actor.userId, actor.deviceId ?? null);
+    if (actor.deviceId !== undefined && !decider.deviceActive) return { ok: false, code: "NOT_FOUND" };
     const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
       WHERE id=${id}::uuid AND approver_user_id=${actor.userId}::uuid FOR UPDATE`;
     if (!row) return { ok: false, code: "NOT_FOUND" };
@@ -151,8 +163,9 @@ export const decide = async (
     const [won] = rejectOnly
       ? []
       : await tx<ApprovalRequest[]>`
-      UPDATE approvals.requests SET status=${status}, decided_via=${actor.via}, decided_at=now()
+      UPDATE approvals.requests SET status=${status}, decided_via=${actor.via}, decided_device_id=${actor.deviceId ?? null}::uuid, decided_at=now()
       WHERE id=${id}::uuid AND approver_user_id=${actor.userId}::uuid AND status='pending' AND expires_at > now()
+        AND approver_auth_epoch=${decider.epoch}::bigint
       RETURNING ${columns()}
     `;
     if (won) {
@@ -178,7 +191,8 @@ export const decide = async (
     }
     if (row.status === "pending") {
       const [expired] = await tx<{ id: string }[]>`UPDATE approvals.requests SET status='expired'
-        WHERE id=${id}::uuid AND status='pending' AND expires_at <= now() RETURNING id`;
+        WHERE id=${id}::uuid AND status='pending'
+          AND (expires_at <= now() OR approver_auth_epoch IS DISTINCT FROM ${decider.epoch}::bigint) RETURNING id`;
       return { ok: false, code: expired || !rejectOnly ? "EXPIRED" : "REJECT_ONLY" };
     }
     if (
@@ -194,7 +208,7 @@ export const decide = async (
 
 export type ApprovalConsumeResult =
   | { ok: true }
-  | { ok: false; code: "NOT_FOUND" | "NOT_APPROVED" | "ALREADY_CONSUMED" | "INPUT_CHANGED" | "REVIEW_CHANGED" };
+  | { ok: false; code: "NOT_FOUND" | "NOT_APPROVED" | "ALREADY_CONSUMED" | "INPUT_CHANGED" | "REVIEW_CHANGED" | "REVOKED" };
 export const consume = async (
   id: string,
   input: { input: unknown; review: CapabilityActionReview | null; requester: { kind: ApprovalRequesterKind; ref: string } },
@@ -203,11 +217,26 @@ export const consume = async (
   const argsDigest = approvalArgsDigest(input.input),
     reviewDigest = approvalReviewDigest(input.review);
   return transaction(db, async (tx): Promise<ApprovalConsumeResult> => {
+    const [initial] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
+      WHERE id=${id}::uuid AND requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref}`;
+    if (!initial) return { ok: false, code: "NOT_FOUND" };
+    if (initial.status === "consumed") return { ok: false, code: "ALREADY_CONSUMED" };
+    if (initial.status !== "approved") return { ok: false, code: "NOT_APPROVED" };
+    const decider = await lockDecider(tx, initial.approverUserId, initial.decidedDeviceId);
     const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
       WHERE id=${id}::uuid AND requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref} FOR UPDATE`;
     if (!row) return { ok: false, code: "NOT_FOUND" };
     if (row.status === "consumed") return { ok: false, code: "ALREADY_CONSUMED" };
     if (row.status !== "approved") return { ok: false, code: "NOT_APPROVED" };
+    if (
+      (row.decidedVia === "cloud_login" && row.decidedDeviceId === null) ||
+      (row.decidedDeviceId !== null && !decider.deviceActive) ||
+      row.approverAuthEpoch === null ||
+      row.approverAuthEpoch !== decider.epoch
+    ) {
+      await tx`UPDATE approvals.requests SET status='cancelled' WHERE id=${id}::uuid AND status='approved'`;
+      return { ok: false, code: "REVOKED" };
+    }
     if (row.argsDigest !== argsDigest || row.reviewDigest !== reviewDigest) {
       await tx`UPDATE approvals.requests SET status='cancelled' WHERE id=${id}::uuid AND status='approved'`;
       return { ok: false, code: row.argsDigest !== argsDigest ? "INPUT_CHANGED" : "REVIEW_CHANGED" };

package/src/services/approvals/list.ts

@@ -33,6 +33,7 @@ export type PendingApprovalRow = {
 // Start with this person's indexed pending rows; a Studio page alone cannot continue a chat.
 const openRequests = (approverUserId: string, id?: string) => sql`SELECT r.* FROM approvals.requests r
   WHERE r.approver_user_id=${approverUserId}::uuid AND r.status='pending' AND r.expires_at > now()
+    AND r.approver_auth_epoch=(SELECT auth_epoch FROM auth.users WHERE id=${approverUserId}::uuid)
     AND (${id ?? null}::uuid IS NULL OR r.id=${id ?? null}::uuid)
     AND EXISTS (SELECT 1 FROM ai.pending_actions p WHERE p.approval_id=r.id AND p.status='pending')`;
 const matches = (appId?: string, link?: string) => sql`

package/src/services/approvals/migrate.ts

@@ -38,4 +38,14 @@ export const migrateApprovals = async (): Promise<void> => {
   END $$`.simple();
   await sql`CREATE INDEX IF NOT EXISTS approvals_requests_pending ON approvals.requests(approver_user_id, created_at) WHERE status='pending'`.simple();
   await sql`CREATE INDEX IF NOT EXISTS approvals_requests_expiry ON approvals.requests(expires_at)`.simple();
+  await sql`ALTER TABLE approvals.requests ADD COLUMN IF NOT EXISTS decided_device_id UUID`.simple();
+  // Backfill pending rows once at column creation; approved rows and older-release rows keep NULL and count as ended.
+  await sql`DO $$ BEGIN
+    IF NOT EXISTS (SELECT 1 FROM information_schema.columns
+      WHERE table_schema='approvals' AND table_name='requests' AND column_name='approver_auth_epoch') THEN
+      ALTER TABLE approvals.requests ADD COLUMN approver_auth_epoch BIGINT;
+      UPDATE approvals.requests r SET approver_auth_epoch=u.auth_epoch FROM auth.users u
+        WHERE u.id=r.approver_user_id AND r.status='pending';
+    END IF;
+  END $$`.simple();
 };

package/src/services/pdf/markdown.ts

@@ -127,19 +127,23 @@ hr { border: 0; border-top: 1px solid #d1d5db; margin: .9em 0; }
 };
 
 /**
- * Markdown info blocks print as the calm NoticeCard: a light tint per tone, no
- * border, and the preset's own text colour, so they stay readable on paper.
+ * Markdown callouts print with a light tint and no border. The inline icon
+ * and title use print-safe tone ink; the body keeps the preset's text colour.
  * The tints are a step stronger than on screen because paper and printers wash
  * them out. Every preset and application document shares them.
  */
 const INFO_BLOCK_PRINT_CSS = `
 .k2b-sr-only { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
 .k2b-notice-card { margin: 0 0 1em; padding: .85em 1.05em; border-radius: .8em; background: var(--notice-tint); break-inside: avoid; print-color-adjust: exact; -webkit-print-color-adjust: exact; }
-.k2b-notice-card[data-tone="neutral"] { --notice-tint: #f1f2f4; }
-.k2b-notice-card[data-tone="info"] { --notice-tint: #e9f1fe; }
-.k2b-notice-card[data-tone="success"] { --notice-tint: #e6f6ee; }
-.k2b-notice-card[data-tone="warning"] { --notice-tint: #fcf2da; }
-.k2b-notice-card[data-tone="danger"] { --notice-tint: #fcebeb; }
+.k2b-notice-card[data-tone="neutral"] { --notice-tint: #f1f2f4; --notice-ink: #4b5563; }
+.k2b-notice-card[data-tone="info"] { --notice-tint: #e9f1fe; --notice-ink: #1d4ed8; }
+.k2b-notice-card[data-tone="success"] { --notice-tint: #e6f6ee; --notice-ink: #15803d; }
+.k2b-notice-card[data-tone="warning"] { --notice-tint: #fcf2da; --notice-ink: #92400e; }
+.k2b-notice-card[data-tone="danger"] { --notice-tint: #fcebeb; --notice-ink: #b91c1c; }
+.k2b-callout { display: grid; grid-template-columns: 1.25em minmax(0, 1fr); column-gap: .7em; }
+.k2b-callout > * { grid-column: 2; }
+.k2b-callout > .k2b-callout__icon { grid-column: 1; grid-row: 1 / span 2; width: 1.25em; height: 1lh; color: var(--notice-ink); }
+.k2b-callout > .k2b-notice-card__title { color: var(--notice-ink); }
 .k2b-notice-card__title { margin: 0 0 .25em; font-weight: 600; }
 .k2b-notice-card__body > :first-child { margin-top: 0; }
 .k2b-notice-card__body > :last-child { margin-bottom: 0; }