@hienlh/ppm 0.23.13 → 0.23.15

package/src/services/design/share/design-share-notifier.ts

@@ -0,0 +1,192 @@
+import type { DesignCommentGuestView } from "../../../shared/design-comment-thread-types.ts";
+import { createLogger } from "../../logger.ts";
+import { notificationService, type BroadcastOptions, type NotificationPayload } from "../../notification.service.ts";
+import { truncateText } from "../../notification-format.ts";
+import { projectNameForPath } from "../../project-name-for-path.ts";
+import { isValidDesignSlug } from "../design-slug.ts";
+import { loadManifest } from "../design-store.service.ts";
+import type { ResolvedShareLink } from "./design-share-resolve.ts";
+
+const log = createLogger("design-share");
+
+/**
+ * Tells the owner that reviewers wrote on a shared design: one notification per link that
+ * folds every comment and reply written before it went out ("3 new comments on Landing
+ * from Alice, Bob"). Two limits apply on top of the notification delay. Waiting
+ * notifications share a coalesce key per link, so the newest replaces the older ones. And
+ * a link is told at most once per {@link FLOOR_MS}, even with the delay at "right away",
+ * so a busy review cannot turn into a stream of pushes: writes inside the floor are folded
+ * into one summary sent when it ends.
+ *
+ * Reviewer names and bodies are untrusted. They are reduced to one line of plain text and
+ * capped here; each channel then escapes what it shows (Telegram HTML) or sends it as
+ * plain text (push, ntfy without markdown).
+ */
+
+export const FLOOR_MS = 60_000;
+const NAMES_SHOWN = 3;
+const EXCERPT_MAX = 200;
+const TITLE_MAX = 80;
+const NAME_MAX = 40;
+/** Per-write names kept per link; the count goes on past it, the "and N more" stops growing. */
+const NAMES_KEPT = 500;
+
+export interface GuestWrite { name: string; body: string }
+
+interface LinkState {
+  linkId: string;
+  projectPath: string;
+  slug: string;
+  title: string;
+  /** Writes not yet told, and the reviewer name of each (oldest first, capped). */
+  count: number;
+  names: string[];
+  excerpt: string;
+  lastSentAt: number;
+  floorTimer: ReturnType<typeof setTimeout> | null;
+}
+
+export interface DesignShareNotifierDeps {
+  broadcast: (type: "design_review", payload: NotificationPayload, opts: BroadcastOptions) => Promise<unknown>;
+  floorMs: number;
+  now: () => number;
+  titleOf: (designDir: string, slug: string) => Promise<string>;
+}
+
+// Control characters, line breaks and bidi controls become spaces: one line, read as written.
+const UNSAFE = /[\p{Cc}\p{Zl}\p{Zp}\p{Bidi_Control}]+/gu;
+
+export function plainLine(text: string, max: number): string {
+  return truncateText(text.replace(UNSAFE, " ").replace(/\s+/g, " "), max);
+}
+
+/** "Alice", "Alice and Bob", "Alice, Bob and Carol", "Alice, Bob, Carol and 2 more". */
+export function formatReviewerNames(names: readonly string[]): string {
+  const unique = [...new Set(names)];
+  if (unique.length <= 1) return unique[0] ?? "a reviewer";
+  if (unique.length <= NAMES_SHOWN) return `${unique.slice(0, -1).join(", ")} and ${unique.at(-1)}`;
+  return `${unique.slice(0, NAMES_SHOWN).join(", ")} and ${unique.length - NAMES_SHOWN} more`;
+}
+
+async function manifestTitle(designDir: string, slug: string): Promise<string> {
+  return (await loadManifest(designDir, slug)).manifest.title;
+}
+
+export class DesignShareNotifier {
+  private readonly links = new Map<string, LinkState>();
+  private readonly deps: DesignShareNotifierDeps;
+
+  constructor(deps: Partial<DesignShareNotifierDeps> = {}) {
+    this.deps = {
+      broadcast: (type, payload, opts) => notificationService.broadcast(type, payload, opts),
+      floorMs: FLOOR_MS,
+      now: () => Date.now(),
+      titleOf: manifestTitle,
+      ...deps,
+    };
+  }
+
+  /** Count one reviewer write. Never throws and never waits on a channel. */
+  async noteGuestWrite(resolved: Pick<ResolvedShareLink, "link" | "designDir">, write: GuestWrite): Promise<void> {
+    const { link } = resolved;
+    let title = link.slug;
+    try {
+      title = (await this.deps.titleOf(resolved.designDir, link.slug)) || link.slug;
+    } catch { /* the slug still names the design */ }
+
+    // Everything from here on is synchronous, so two writes arriving together cannot both
+    // pass the floor.
+    const now = this.deps.now();
+    this.prune(now);
+    let state = this.links.get(link.id);
+    if (!state) {
+      state = {
+        linkId: link.id, projectPath: link.projectPath, slug: link.slug, title: "",
+        count: 0, names: [], excerpt: "", lastSentAt: -Infinity, floorTimer: null,
+      };
+      this.links.set(link.id, state);
+    }
+    state.title = plainLine(title, TITLE_MAX);
+    state.count++;
+    if (state.names.length < NAMES_KEPT) state.names.push(plainLine(write.name, NAME_MAX) || "a reviewer");
+    state.excerpt = plainLine(write.body, EXCERPT_MAX);
+
+    if (state.floorTimer) return;
+    const wait = state.lastSentAt + this.deps.floorMs - now;
+    if (wait > 0) {
+      const waiting = state;
+      waiting.floorTimer = setTimeout(() => {
+        waiting.floorTimer = null;
+        this.flush(waiting);
+      }, wait);
+      return;
+    }
+    this.flush(state);
+  }
+
+  /** Links with something waiting, for tests. */
+  pendingCount(): number {
+    let n = 0;
+    for (const state of this.links.values()) if (state.count > 0) n++;
+    return n;
+  }
+
+  private flush(state: LinkState): void {
+    if (state.count === 0) return;
+    const told = { count: state.count, names: state.names.length };
+    const forget = () => {
+      state.count = Math.max(0, state.count - told.count);
+      state.names.splice(0, told.names);
+    };
+    this.deps.broadcast("design_review", this.payloadOf(state), {
+      coalesceKey: `design-share:${state.linkId}`,
+      onSend: () => {
+        state.lastSentAt = this.deps.now();
+        forget();
+      },
+    })
+      .then((outcome) => {
+        // Switched off: nothing will ever tell these writes, so they are not carried over.
+        if (outcome === "off" || outcome === "seen") forget();
+      })
+      .catch((e) => log.warn(`Reviewer notification for link ${state.linkId} failed: ${(e as Error).message}`));
+  }
+
+  private payloadOf(state: LinkState): NotificationPayload {
+    const project = projectNameForPath(state.projectPath) ?? "";
+    const n = state.count;
+    return {
+      title: "New design feedback",
+      body: `${n} new comment${n === 1 ? "" : "s"} on ${state.title} from ${formatReviewerNames(state.names)}`,
+      detail: state.excerpt || undefined,
+      detailStyle: "quote",
+      project,
+      sessionId: "",
+      ...(project && isValidDesignSlug(state.slug) && {
+        path: `/project/${encodeURIComponent(project)}/design/${state.slug}`,
+      }),
+    };
+  }
+
+  /** Drop links with nothing waiting whose floor is over, so the map holds only live reviews. */
+  private prune(now: number): void {
+    for (const [id, state] of this.links) {
+      if (state.count === 0 && !state.floorTimer && now - state.lastSentAt >= this.deps.floorMs) this.links.delete(id);
+    }
+  }
+}
+
+export const designShareNotifier = new DesignShareNotifier();
+
+/**
+ * After a reviewer's comment or reply was stored: count it for the owner's notification.
+ * Fire and forget — the reviewer's answer never waits on it.
+ */
+export function notifyGuestWrite(
+  resolved: ResolvedShareLink, thread: DesignCommentGuestView, kind: "comment" | "reply",
+): void {
+  const entry = kind === "comment" ? thread : thread.replies.findLast((r) => r.mine);
+  if (!entry || entry.author.kind !== "guest") return;
+  void designShareNotifier.noteGuestWrite(resolved, { name: entry.author.name, body: entry.body })
+    .catch((e) => log.warn(`Reviewer notification for link ${resolved.link.id} failed: ${(e as Error).message}`));
+}

package/src/services/design/share/design-share-rate-limit.ts

@@ -0,0 +1,71 @@
+import { createSlidingWindowLimiter, type LimitRefusal, type WindowRule } from "../../sliding-window-limiter.ts";
+
+/**
+ * Request budgets of the public share routes, each counted on its own so one kind of
+ * traffic cannot starve another: loading a design's files does not use up comment polls.
+ *
+ * Per client key (see `design-share-client-key.ts`):
+ * - `assets`: the shared design's files, 1200 a minute — a 100-file design loaded by ten
+ *   reviewers who all share the `local` key still fits;
+ * - `api`: the page, link info and comment reads, 120 a minute;
+ * - writes: one per 500 ms and 20 a minute, per reviewer key on that address;
+ * Per link, whoever writes: 30 writes a minute, so forging client keys gains nothing.
+ *
+ * Each map keeps at most {@link MAX_CLIENT_KEYS} keys, dropping the least recently used.
+ */
+
+const MINUTE = 60_000;
+export const MAX_CLIENT_KEYS = 2048;
+
+export const SHARE_BUDGETS = {
+  assets: { windowMs: MINUTE, max: 1200, granularityMs: 1000 },
+  api: { windowMs: MINUTE, max: 120, granularityMs: 1000 },
+  clientWrites: { windowMs: MINUTE, max: 20, minIntervalMs: 500 },
+  linkWrites: { windowMs: MINUTE, max: 30 },
+} as const satisfies Record<string, WindowRule>;
+
+/** Test seam: the clock every share budget reads. */
+export const shareRateClock = { now: (): number => Date.now() };
+
+const limiters = {
+  assets: createSlidingWindowLimiter(SHARE_BUDGETS.assets, { maxKeys: MAX_CLIENT_KEYS }),
+  api: createSlidingWindowLimiter(SHARE_BUDGETS.api, { maxKeys: MAX_CLIENT_KEYS }),
+  clientWrites: createSlidingWindowLimiter(SHARE_BUDGETS.clientWrites, { maxKeys: MAX_CLIENT_KEYS }),
+  linkWrites: createSlidingWindowLimiter(SHARE_BUDGETS.linkWrites, { maxKeys: MAX_CLIENT_KEYS }),
+};
+
+export type ShareReadBudget = "assets" | "api";
+
+/** Counts one read; answers how long to wait (ms) when over budget, else 0. */
+export function takeShareRead(budget: ShareReadBudget, clientKey: string): number {
+  return limiters[budget].take(clientKey, shareRateClock.now())?.retryMs ?? 0;
+}
+
+/** Whether this client may write now, counting nothing (checked before the code is looked up). */
+export function checkShareClientWrite(clientKey: string): number {
+  return limiters.clientWrites.check(clientKey, shareRateClock.now())?.retryMs ?? 0;
+}
+
+/** Counts one write against both the client and the link, or neither when either is over. */
+export function takeShareWrite(clientKey: string, linkId: string): number {
+  const now = shareRateClock.now();
+  const refusals = [limiters.clientWrites.check(clientKey, now), limiters.linkWrites.check(linkId, now)]
+    .filter((r): r is LimitRefusal => r !== null);
+  if (refusals.length) return Math.max(...refusals.map((r) => r.retryMs));
+  limiters.clientWrites.record(clientKey, now);
+  limiters.linkWrites.record(linkId, now);
+  return 0;
+}
+
+/** Keys currently tracked per budget (tests). */
+export function shareLimiterSizes(): Record<keyof typeof limiters, number> {
+  return {
+    assets: limiters.assets.size, api: limiters.api.size,
+    clientWrites: limiters.clientWrites.size, linkWrites: limiters.linkWrites.size,
+  };
+}
+
+/** Forget every count (tests). */
+export function resetShareRateLimits(): void {
+  for (const limiter of Object.values(limiters)) limiter.reset();
+}

package/src/services/design/share/design-share-resolve.ts

@@ -0,0 +1,31 @@
+import type { DesignSnapshotInfo } from "../../../shared/design-types.ts";
+import { readSnapshotInfo } from "../design-snapshot-history.ts";
+import { codeMatches, hashCode, SHARE_CODE_RE } from "./design-share-code.ts";
+import { getShareLinkByCodeHash, type ShareLinkRecord } from "./design-share-links-store.ts";
+import { designDirOrNull, shareAuthEnabled } from "./design-share-link-rules.ts";
+
+export interface ResolvedShareLink {
+  link: ShareLinkRecord;
+  /** Real path of the design folder. */
+  designDir: string;
+  /** The pinned snapshot, which exists. */
+  snapshot: DesignSnapshotInfo;
+}
+
+/**
+ * The link a guest's code opens, or null for every reason it does not: sign-in off, an
+ * unknown or retired code, revoked, expired (by server time), or a design or snapshot that
+ * is gone. The reasons are not told apart, so a guest learns nothing from a refusal.
+ */
+export async function resolveShareCode(code: string): Promise<ResolvedShareLink | null> {
+  if (!SHARE_CODE_RE.test(code) || !shareAuthEnabled()) return null;
+  const link = getShareLinkByCodeHash(hashCode(code));
+  // The hash matching is not enough: after the secret is replaced, an old code still hashes
+  // to its row, and that link is `needs-new-code` until the owner issues one.
+  if (!link || !codeMatches(code, link.id, link.codeVersion)) return null;
+  if (link.revokedAt !== null || (link.expiresAt !== null && link.expiresAt <= Date.now())) return null;
+  const designDir = await designDirOrNull(link.projectPath, link.slug);
+  const snapshot = designDir ? await readSnapshotInfo(designDir, link.snapshotId) : null;
+  if (!designDir || !snapshot) return null;
+  return { link, designDir, snapshot };
+}

package/src/services/mcp-http-endpoint.ts

@@ -49,14 +49,24 @@ export function createMcpHttpHandler<B extends { sessionId: string }>(opts: {
   /** The 401 body's message when no valid token is presented. */
   tokenRequired: string;
   resolveToken: (token: string | null) => B | null;
-  tools: readonly Json[];
-  /** A `tools/call` result for a tool named in `tools`. */
-  callTool: (binding: B, name: string, args: unknown) => Promise<Json>;
+  /** The tools, or a function giving them as they are now (a description naming what exists). */
+  tools: readonly Json[] | (() => readonly Json[]);
+  /**
+   * Why a tool in `tools` is off right now, or null. An off tool is left out of `tools/list`, and
+   * a chat that listed it before it went off gets this as the call's error result.
+   */
+  unavailable?: (name: string) => string | null;
+  /**
+   * A `tools/call` result for a tool named in `tools`. `signal` is the call's HTTP request: it
+   * aborts when the provider gives up on the call, e.g. because the user stopped the turn.
+   */
+  callTool: (binding: B, name: string, args: unknown, signal: AbortSignal) => Promise<Json>;
 }) {
-  const names = new Set(opts.tools.map((t) => t.name));
+  const toolList = (): readonly Json[] => (typeof opts.tools === "function" ? opts.tools() : opts.tools);
+  const offReason = (name: string): string | null => opts.unavailable?.(name) ?? null;
   const log = createLogger(opts.serverName);
 
-  async function dispatch(binding: B, msg: Json): Promise<Json> {
+  async function dispatch(binding: B, msg: Json, signal: AbortSignal): Promise<Json> {
     const id = msg.id;
     const params = (msg.params && typeof msg.params === "object" ? msg.params : {}) as Json;
     switch (msg.method) {
@@ -71,12 +81,15 @@ export function createMcpHttpHandler<B extends { sessionId: string }>(opts: {
       case "ping":
         return rpcResult(id, {});
       case "tools/list":
-        return rpcResult(id, { tools: opts.tools });
-      case "tools/call":
-        if (typeof params.name !== "string" || !names.has(params.name)) {
+        return rpcResult(id, { tools: toolList().filter((t) => !offReason(String(t.name))) });
+      case "tools/call": {
+        if (typeof params.name !== "string" || !toolList().some((t) => t.name === params.name)) {
           return rpcError(id, -32602, `Unknown tool: ${String(params.name).slice(0, 60)}`);
         }
-        return rpcResult(id, await opts.callTool(binding, params.name, params.arguments));
+        const off = offReason(params.name);
+        if (off) return rpcResult(id, textResult(off, true));
+        return rpcResult(id, await opts.callTool(binding, params.name, params.arguments, signal));
+      }
       default:
         return rpcError(id, -32601, "Method not found");
     }
@@ -105,7 +118,7 @@ export function createMcpHttpHandler<B extends { sessionId: string }>(opts: {
     // A notification (`notifications/initialized`) or a response to a request of ours: no body.
     if (!("id" in message) || message.id === null) return c.body(null, 202);
     try {
-      return c.json(await dispatch(binding, message));
+      return c.json(await dispatch(binding, message, c.req.raw.signal));
     } catch (e) {
       // Answered as a 200, so the access log records a success.
       log.error(`${String(message.method).slice(0, 60)} failed (session ${binding.sessionId}): ${(e as Error).message}`);

package/src/services/mysql.service.ts

@@ -885,6 +885,10 @@ class MysqlService {
       const wrote = resultSets.length === 0 && WRITE_STATEMENT.test(sqlCode(text, "mysql", splitOptions));
       return { resultSets, ...(wrote ? { rowsAffected: answer.affected } : {}), notices: [] };
     };
+    const transactionOpen = async () => {
+      const [status] = await conn.query<ResultSetHeader>("DO 0");
+      return (Number(status.serverStatus) & SERVER_STATUS_IN_TRANS) !== 0;
+    };
     return {
       splitOptions,
       run: (text, maxRows) => this.inQueryStatement(text, () => runStatement(text, maxRows)),
@@ -892,11 +896,11 @@ class MysqlService {
         if (running) void this.killQuery(connectionString, conn.threadId);
       },
       rollbackOpenTransaction: async () => {
-        const [status] = await conn.query<ResultSetHeader>("DO 0");
-        if ((Number(status.serverStatus) & SERVER_STATUS_IN_TRANS) === 0) return false;
+        if (!(await transactionOpen())) return false;
         await conn.query("ROLLBACK");
         return true;
       },
+      transactionOpen,
       close: async () => {
         if (ended) return;
         ended = true;

package/src/services/notification-format.ts

@@ -3,6 +3,7 @@
  * tested without a bot, a browser or a clock.
  */
 import type { NotificationPayload } from "./notification.service.ts";
+import { dbExecuteApprovalInput } from "../shared/db-ai-tools.ts";
 
 const DETAIL_MAX = 300;
 
@@ -17,11 +18,14 @@ export function escapeTelegramHtml(text: string): string {
 }
 
 /**
- * Where a notification opens PPM: the session's chat when there is one.
+ * Where a notification opens PPM: the event's own path when it names one, else the
+ * session's chat when there is one.
  * `project` must be the project's NAME — the app resolves `/project/<x>` by name, and
  * a path there falls back to whichever project sorts first.
  */
-export function notificationPath(payload: Pick<NotificationPayload, "project" | "sessionId" | "providerId">): string {
+export function notificationPath(payload: Pick<NotificationPayload, "project" | "sessionId" | "providerId" | "path">): string {
+  // Only a path inside the app: `//host` and `/\host` would leave PPM's origin.
+  if (payload.path && /^\/(?![/\\])/.test(payload.path)) return payload.path;
   if (!payload.project) return "/";
   const base = `/project/${encodeURIComponent(payload.project)}`;
   if (!payload.sessionId) return base;
@@ -56,6 +60,10 @@ export function describeApprovalInput(tool: string, input: unknown): Pick<Notifi
   if (!input || typeof input !== "object") return {};
   const i = input as Record<string, unknown>;
 
+  // A database change: the AI's reason, not the SQL, which may quote the rows it changes.
+  const db = dbExecuteApprovalInput(tool, input);
+  if (db) return db.reason ? { detail: db.reason, detailStyle: "quote" } : {};
+
   if (tool === "AskUserQuestion" && Array.isArray(i.questions)) {
     const questions = i.questions as Array<{ question?: unknown }>;
     const first = typeof questions[0]?.question === "string" ? questions[0].question : "";

package/src/services/notification-link.ts

@@ -10,7 +10,7 @@ import { notificationPath } from "./notification-format.ts";
  * that is plain HTTP on an insecure origin, where the browser turns off notifications,
  * the clipboard and the other permissions PPM asks for, while localhost counts as secure.
  */
-export async function notificationLink(payload: Pick<NotificationPayload, "project" | "sessionId" | "providerId">): Promise<string> {
+export async function notificationLink(payload: Pick<NotificationPayload, "project" | "sessionId" | "providerId" | "path">): Promise<string> {
   const baseUrl = tunnelService.getTunnelUrl() ?? await tailscaleUrl() ?? `http://localhost:${ppmPublicPort()}`;
   return `${baseUrl.replace(/\/$/, "")}${notificationPath(payload)}`;
 }

package/src/services/notification.service.ts

@@ -25,6 +25,8 @@ export interface NotificationPayload {
   /** How Telegram shows `detail`: quoted prose, or a code block for commands and paths. */
   detailStyle?: "quote" | "code";
   deviceName?: string;
+  /** Where the notification opens PPM, for an event that is not a chat ("/project/<p>/design/<slug>"). */
+  path?: string;
 }
 
 export interface BroadcastOptions {
@@ -34,12 +36,27 @@ export interface BroadcastOptions {
    * out: schedules and Jira have no "seen" state.
    */
   stillUnseen?: () => boolean;
+  /**
+   * For an event with no session: one waiting notification per key, the newer replacing
+   * the older, as sessions already are. Also the device tag, so a newer notification
+   * replaces the older one on the device too.
+   */
+  coalesceKey?: string;
+  /**
+   * Called the moment the notification goes out — synchronously inside `broadcast` when
+   * there is no delay — and never for one that is switched off, replaced or seen. Lets a
+   * caller that folds several events into one notification know which of them were told.
+   */
+  onSend?: () => void;
 }
 
+/** What became of one broadcast. Callers that only fire and forget can ignore it. */
+export type BroadcastOutcome = "sent" | "off" | "replaced" | "seen";
+
 const URGENT: ReadonlySet<NotificationType> = new Set(["approval_request", "question"]);
 
 export class NotificationService {
-  /** At most one waiting notification per session: a newer event about it replaces the older one. */
+  /** At most one waiting notification per session (or coalesce key): a newer event replaces the older one. */
   private pending = new Map<string, () => void>();
 
   /** @param msPerSecond test seam — the delay setting is in seconds. */
@@ -58,22 +75,26 @@ export class NotificationService {
    * The old rule was "send to Telegram only while no browser is connected", which meant
    * never: a PPM tab left open anywhere, even in the background, kept it silent.
    */
-  broadcast(type: NotificationType, payload: NotificationPayload, opts: BroadcastOptions = {}): Promise<void> {
+  broadcast(type: NotificationType, payload: NotificationPayload, opts: BroadcastOptions = {}): Promise<BroadcastOutcome> {
     const settings = resolveNotificationSettings(configService.get("notifications"));
     if (!settings.events[type]) {
       log.debug(`Notification ${type} not sent: switched off`);
-      return Promise.resolve();
+      return Promise.resolve("off");
+    }
+    const tag = opts.coalesceKey;
+    if (settings.delay_seconds === 0) {
+      sent(opts);
+      return this.deliver(type, payload, tag).then(() => "sent");
     }
-    if (settings.delay_seconds === 0) return this.deliver(type, payload);
 
-    const key = payload.sessionId || null;
+    const key = payload.sessionId || opts.coalesceKey || null;
     if (key) this.pending.get(key)?.();
-    return new Promise<void>((resolve) => {
+    return new Promise<BroadcastOutcome>((resolve) => {
       const cancel = () => {
         clearTimeout(timer);
         if (key && this.pending.get(key) === cancel) this.pending.delete(key);
-        log.debug(`Notification ${type} session=${key} not sent: replaced by a newer one`);
-        resolve();
+        log.debug(`Notification ${type} key=${key} not sent: replaced by a newer one`);
+        resolve("replaced");
       };
       const timer = setTimeout(() => {
         if (key && this.pending.get(key) === cancel) this.pending.delete(key);
@@ -82,16 +103,17 @@ export class NotificationService {
           unseen = opts.stillUnseen ? opts.stillUnseen() : true;
         } catch { /* cannot tell — better one notification too many than a missed approval */ }
         if (!unseen) {
-          log.debug(`Notification ${type} session=${key ?? "-"} not sent: seen within ${settings.delay_seconds}s`);
-          return resolve();
+          log.debug(`Notification ${type} key=${key ?? "-"} not sent: seen within ${settings.delay_seconds}s`);
+          return resolve("seen");
         }
-        this.deliver(type, payload).finally(resolve);
+        sent(opts);
+        this.deliver(type, payload, tag).finally(() => resolve("sent"));
       }, settings.delay_seconds * this.msPerSecond);
       if (key) this.pending.set(key, cancel);
     });
   }
 
-  private async deliver(type: NotificationType, event: NotificationPayload): Promise<void> {
+  private async deliver(type: NotificationType, event: NotificationPayload, coalesceKey?: string): Promise<void> {
     const settings = resolveNotificationSettings(configService.get("notifications"));
     const payload: NotificationPayload = { ...event, providerId: event.providerId || providerOf(event.sessionId) };
     const deviceName = (configService.get("device_name") as string) || "PPM";
@@ -110,7 +132,7 @@ export class NotificationService {
             project: payload.project,
             sessionId: payload.sessionId,
             sessionTitle: payload.sessionTitle,
-            notificationType: type === "schedule" || type === "jira" ? "done" : type,
+            notificationType: type === "schedule" || type === "jira" || type === "design_review" ? "done" : type,
           });
         })
         .catch(() => {}),
@@ -125,8 +147,10 @@ export class NotificationService {
             body,
             path: notificationPath(payload),
             // Same tag = the newer notification replaces the older one on the device. Right for a
-            // session; wrong for two Jira hits that land in the same millisecond.
-            tag: payload.sessionId ? `ppm-${payload.sessionId}` : `ppm-${type}-${crypto.randomUUID()}`,
+            // session or a coalesce key; wrong for two Jira hits that land in the same millisecond.
+            tag: payload.sessionId ? `ppm-${payload.sessionId}`
+              : coalesceKey ? `ppm-${coalesceKey}`
+              : `ppm-${type}-${crypto.randomUUID()}`,
             project: payload.project,
             sessionId: payload.sessionId,
             providerId: payload.providerId ?? "",
@@ -188,6 +212,14 @@ function ntfyFailure(e: unknown, config: NtfyConfig | null): string {
   return msg.split(config.server).join(host).split(config.topic).join("[topic]");
 }
 
+function sent(opts: BroadcastOptions): void {
+  try {
+    opts.onSend?.();
+  } catch (e) {
+    log.warn(`onSend failed: ${(e as Error).message}`);
+  }
+}
+
 /** Sessions PPM created or resumed have their provider recorded; others have no row. */
 function providerOf(sessionId: string): string | undefined {
   if (!sessionId) return undefined;

package/src/services/ppm-password.ts

@@ -0,0 +1,26 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { configService } from "./config.service.ts";
+
+/**
+ * PPM's password — the auth token a browser logs in with — typed again to approve a write on
+ * a database: an AI's `db_execute`, or a Query tab run with write access once.
+ *
+ * Typing it proves a person is at the screen, because an AI cannot type into PPM's page. It is
+ * not a secret the AI lacks: the token sits in `ppm.db`, readable by any process of this OS
+ * user, a chat's shell included. That is the trade the user chose over a separate password.
+ */
+
+/** Approving asks for the password; PPM run without auth has none to ask for. */
+export function ppmPasswordRequired(): boolean {
+  const auth = configService.get("auth");
+  return !!auth.enabled && !!auth.token;
+}
+
+const digest = (value: string): Buffer => createHash("sha256").update(value, "utf8").digest();
+
+/** Whether `typed` is PPM's password; always true when none is required. Constant-time. */
+export function checkPpmPassword(typed: unknown): boolean {
+  if (!ppmPasswordRequired()) return true;
+  if (typeof typed !== "string" || typed.length === 0 || typed.length > 1_000) return false;
+  return timingSafeEqual(digest(typed), digest(configService.get("auth").token));
+}

package/src/services/project-name-for-path.ts

@@ -0,0 +1,18 @@
+import { resolve } from "node:path";
+import { configService } from "./config.service.ts";
+
+/**
+ * A project folder in the one spelling every comparison uses: resolved, and lower-cased on
+ * Windows, where `C:\Users\Me\App` and `c:\users\me\app` are the same folder. Stored beside
+ * the path in any table queried by project, because SQL `=` is case-sensitive.
+ */
+export function projectKey(projectPath: string): string {
+  const abs = resolve(projectPath);
+  return process.platform === "win32" ? abs.toLowerCase() : abs;
+}
+
+/** Registered project whose folder is `projectPath`, or null. Case-folded on Windows. */
+export function projectNameForPath(projectPath: string): string | null {
+  const target = projectKey(projectPath);
+  return configService.get("projects").find((p) => projectKey(p.path) === target)?.name ?? null;
+}

package/src/services/query-audit/query-audit.service.ts

@@ -5,9 +5,10 @@ import { truncateResult, capBytes, MAX_RESULT_BYTES } from "./result-truncate.ts
  * "filter" is SQL the grid's column filters build — a real query, but not one the user typed;
  * "structure" is DDL from the table editor's Save and the tree's table commands; "export" is the
  * read behind a file Export wrote, every row of it; "import" is one uploaded file written into a
- * table, with the table changes its Action made.
+ * table, with the table changes its Action made; "ai" is SQL an AI chat ran through PPM's
+ * database tools (`db_query`, and `db_execute` once the user approved it).
  */
-export type QuerySource = "editor" | "grid" | "cli" | "filter" | "structure" | "export" | "import";
+export type QuerySource = "editor" | "grid" | "cli" | "filter" | "structure" | "export" | "import" | "ai";
 export type QueryActor = "human" | "agent" | "cli";
 export type QueryOperation = "select" | "insert" | "update" | "delete" | "script" | "other";
 export type QueryStatus = "ok" | "error" | "blocked";
@@ -60,7 +61,8 @@ export interface QueryLogFilter {
   /** A database file's entries: they carry no connection id, only the file's path as the name. */
   fileConnection?: string;
   status?: QueryStatus;
-  source?: QuerySource;
+  /** One source, or any of several. */
+  source?: QuerySource | readonly QuerySource[];
   from?: string;
   to?: string;
   search?: string;
@@ -115,7 +117,8 @@ function buildWhere(filter: QueryLogFilter): { clause: string; params: unknown[]
   if (filter.connectionId != null) { conditions.push("connection_id = ?"); params.push(filter.connectionId); }
   if (filter.fileConnection != null) { conditions.push("connection_id IS NULL AND connection_name = ?"); params.push(filter.fileConnection); }
   if (filter.status) { conditions.push("status = ?"); params.push(filter.status); }
-  if (filter.source) { conditions.push("source = ?"); params.push(filter.source); }
+  if (typeof filter.source === "string") { conditions.push("source = ?"); params.push(filter.source); }
+  else if (filter.source?.length) { conditions.push(`source IN (${filter.source.map(() => "?").join(", ")})`); params.push(...filter.source); }
   if (filter.from) { conditions.push("created_at >= ?"); params.push(filter.from); }
   if (filter.to) { conditions.push("created_at <= ?"); params.push(filter.to); }
   if (filter.search) { conditions.push("sql LIKE ?"); params.push(`%${filter.search}%`); }