@hienlh/ppm 0.23.14 → 0.23.15

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}%`); }

package/src/services/remote-desktop/access-unit-assembler.ts

@@ -2,13 +2,17 @@
  * Groups the raw NAL units from `NalSplitter` into WebCodecs-ready access units.
  *
  * `VideoDecoder` decodes one access unit (one frame) per `EncodedVideoChunk`, not one
- * NAL — feeding SPS/PPS/slice as three separate chunks throws or corrupts decode. libx264
- * (no B-frames, `-bf 0`) emits at most one slice NAL per frame, optionally preceded by
- * SPS/PPS on a keyframe, so an AU boundary is simply "the next VCL NAL after we already
- * buffered one" — everything non-VCL (SPS/PPS/AUD/SEI) that arrived first attaches to the
- * AU it precedes.
+ * NAL — feeding SPS/PPS/slice as three separate chunks throws or corrupts decode. With no
+ * B-frames (`-bf 0`) an AU boundary is "the next slice that opens a new picture after we
+ * already buffered one" (`startsPicture`) — everything non-VCL (SPS/PPS/AUD/SEI) that arrived
+ * first attaches to the AU it precedes.
+ *
+ * A frame may be several slices, and all of them belong in its one chunk. Cutting at *every*
+ * slice — this file's rule until #48 — turned x264's `tune=zerolatency` output into ~17 chunks a
+ * frame: Chrome decoded none of them ("Decoding error.", a black canvas) and a Wayland host
+ * reported a solid green one.
  */
-import { NalSplitter, nalType, isVclNal, NAL_TYPE_IDR, NAL_TYPE_SPS, NAL_TYPE_PPS } from "./nal-splitter.ts";
+import { NalSplitter, nalType, isVclNal, startsPicture, NAL_TYPE_IDR, NAL_TYPE_SPS, NAL_TYPE_PPS } from "./nal-splitter.ts";
 
 export interface AccessUnit {
   /** Annex-B encoded bytes (start codes + NAL payloads) — one `EncodedVideoChunk` worth. */
@@ -48,7 +52,7 @@ export class AccessUnitAssembler {
       else if (type === NAL_TYPE_PPS) this.pps = nal;
 
       const vcl = isVclNal(nal);
-      if (vcl && this.pendingHasVcl) {
+      if (this.pendingHasVcl && startsPicture(nal)) {
         const au = this.flush();
         if (au) aus.push(au);
       }

package/src/services/remote-desktop/nal-splitter.ts

@@ -19,12 +19,25 @@ export function nalType(nal: Uint8Array): number {
   return (nal[0] ?? 0) & 0x1f;
 }
 
-/** A slice NAL starts a new access unit; SPS/PPS/AUD/SEI attach to whichever AU follows them. */
+/** A slice NAL — picture data, as opposed to SPS/PPS/AUD/SEI. */
 export function isVclNal(nal: Uint8Array): boolean {
   const t = nalType(nal);
   return t === NAL_TYPE_SLICE_NON_IDR || t === NAL_TYPE_IDR;
 }
 
+/**
+ * Whether a slice NAL opens a new picture rather than continuing the one already open.
+ *
+ * An encoder may cut one frame into several slices — x264 does under `tune=zerolatency`, one per
+ * thread, measured at ~17 per 1080p frame on a 24-thread host. Every slice after the first names
+ * the macroblock it starts at, and `first_mb_in_slice` is the slice header's first field: an
+ * Exp-Golomb number, in which only 0 is coded as a single leading 1 bit. The byte after the NAL
+ * header can never hold an emulation-prevention byte (that needs two zero bytes before it).
+ */
+export function startsPicture(nal: Uint8Array): boolean {
+  return isVclNal(nal) && ((nal[1] ?? 0) & 0x80) !== 0;
+}
+
 /** `Bun.spawn` stdout chunks type as `Uint8Array<ArrayBufferLike>` (could in principle back
  *  onto a SharedArrayBuffer), while `new Uint8Array(n)` types as the narrower
  *  `Uint8Array<ArrayBuffer>` — pin everything here to the wider type so a plain chunk and our

package/src/services/remote-desktop/remote-desktop-capture-wayland.ts

@@ -36,8 +36,8 @@ import { createLogger } from "../logger.ts";
 
 const log = createLogger("remote-desktop");
 
-/** Which GStreamer elements this host actually has. Probed once — `gst-inspect-1.0` is ~40 ms
- *  and this sits on the session-start path. */
+/** Which GStreamer elements this host actually has. Remembered once nothing is missing, for the
+ *  checklist; a capture asks afresh every time it starts. */
 export interface GstElements {
   /** `gst-launch-1.0` itself. */
   launch: string | null;
@@ -51,6 +51,10 @@ export interface GstElements {
 }
 
 let cachedElements: GstElements | null = null;
+/** The probe under way. Whoever asks meanwhile shares it instead of spawning four more
+ *  `gst-inspect-1.0`: a host missing anything is probed on every call, and right after a package
+ *  install a cold plugin registry makes each probe take seconds. */
+let probing: Promise<GstElements> | null = null;
 
 async function hasElement(name: string): Promise<boolean> {
   try {
@@ -63,26 +67,41 @@ async function hasElement(name: string): Promise<boolean> {
   }
 }
 
-export async function gstElements(force = false): Promise<GstElements> {
+/** How the host is asked. A test stands in for it: `Bun.which` and `Bun.spawn` resolve through
+ *  the PATH this process started with, which a test cannot change. */
+export interface GstProbe {
+  launch: () => string | null;
+  has: (element: string) => Promise<boolean>;
+}
+
+const HOST_PROBE: GstProbe = { launch: () => Bun.which("gst-launch-1.0"), has: hasElement };
+
+/** `force` passes over a remembered answer, never a probe already under way: that one is asking
+ *  the host now. */
+export async function gstElements(force = false, probe: GstProbe = HOST_PROBE): Promise<GstElements> {
   if (cachedElements && !force) return cachedElements;
-  const launch = Bun.which("gst-launch-1.0");
-  if (!launch) {
-    cachedElements = { launch: null, pipewiresrc: false, vapostproc: false, vah264enc: false, x264enc: false };
-    return cachedElements;
-  }
-  const [pipewiresrc, vapostproc, vah264enc, x264enc] = await Promise.all([
-    hasElement("pipewiresrc"),
-    hasElement("vapostproc"),
-    hasElement("vah264enc"),
-    hasElement("x264enc"),
-  ]);
-  cachedElements = { launch, pipewiresrc, vapostproc, vah264enc, x264enc };
-  return cachedElements;
+  probing ??= probeElements(probe).finally(() => { probing = null; });
+  return probing;
+}
+
+async function probeElements(probe: GstProbe): Promise<GstElements> {
+  const launch = probe.launch();
+  const [pipewiresrc, vapostproc, vah264enc, x264enc] = launch
+    ? await Promise.all([probe.has("pipewiresrc"), probe.has("vapostproc"), probe.has("vah264enc"), probe.has("x264enc")])
+    : [false, false, false, false];
+  const els = { launch, pipewiresrc, vapostproc, vah264enc, x264enc };
+  // Only a host with nothing left to install is remembered. Anything missing may be installed
+  // while PPM runs, and the GPU pair replaces the x264 fallback the moment it appears: caching
+  // the first answer kept a host that had just installed vah264enc on x264 until PPM restarted,
+  // and made the checklist's "PPM re-checks automatically" untrue (#48).
+  cachedElements = launch && pipewiresrc && vapostproc && vah264enc ? els : null;
+  return els;
 }
 
 /** Drop the probe cache, so a package installed while PPM is running is picked up. */
 export function _resetGstElements(): void {
   cachedElements = null;
+  probing = null;
 }
 
 /** `"4M"` / `"1500k"` / `"800000"` → kbps, which is what every GStreamer encoder takes.
@@ -135,9 +154,12 @@ export function buildWaylandCaptureArgs(
     "!", `video/x-raw,framerate=${fps}/1`,
     "!", ...convert,
     "!", ...encode,
-    "!", "h264parse",
-    // Annex-B with one buffer per access unit — exactly the shape `AccessUnitAssembler` and the
-    // RTSP remux both expect, and the same bytes ffmpeg's `-f h264 pipe:1` produces.
+    // Annex-B straight from the encoder — exactly the shape `AccessUnitAssembler` and the RTSP
+    // remux both expect, and the same bytes ffmpeg's `-f h264 pipe:1` produces. No `h264parse`:
+    // both encoders already emit byte-stream with SPS/PPS ahead of every IDR (measured), and the
+    // parser lives in gst-plugins-bad, which a host with x264enc (gst-plugins-ugly) need not have
+    // — there every session died at start with `no element "h264parse"` behind a checklist that
+    // said ready (#48).
     "!", "video/x-h264,stream-format=byte-stream,alignment=au",
     "!", "fdsink", "fd=1",
   ];
@@ -168,7 +190,7 @@ export interface WaylandCaptureOptions extends StartCaptureOptions {
  *  through the PATH this process started with, which a test cannot change. */
 export interface WaylandCaptureDeps {
   startPortal?: typeof startPortalScreenCast;
-  elements?: () => Promise<GstElements>;
+  elements?: (force: boolean) => Promise<GstElements>;
 }
 
 /**
@@ -180,7 +202,11 @@ export async function startWaylandCapture(
   opts: WaylandCaptureOptions,
   { startPortal = startPortalScreenCast, elements = gstElements }: WaylandCaptureDeps = {},
 ): Promise<CaptureHandle> {
-  const els = await elements();
+  // Asked afresh, not read from what the checklist remembered: a complete answer is kept for the
+  // life of the process, so a GPU encoder gone since (a driver update, a removed package) would
+  // fail every session at start until PPM restarted. One probe is ~30 ms with a warm registry. A
+  // respawn asks too — it opens a portal session of its own anyway.
+  const els = await elements(true);
   if (!els.launch) {
     throw new CaptureUnavailableError("gst-launch-1.0 is not installed (Wayland capture needs GStreamer)");
   }

package/src/services/remote-desktop/remote-desktop-encoder-args.ts

@@ -59,10 +59,12 @@ export function captureEncoderArgs(
       // assumptions hold unchanged.
       return ["-c:v", "h264_videotoolbox", "-realtime", "1", "-prio_speed", "1", "-allow_sw", "1", ...common];
     default:
-      // libx264 low-latency. `-tune zerolatency` enables sliced-threads (multi-slice NALs);
-      // access-unit-assembler.ts assumes one slice/frame, so force it back with sliced-threads=0.
+      // libx264 low-latency. `-tune zerolatency` threads *within* a frame (one slice per
+      // thread, which the AU assembler keeps together). Never `sliced-threads=0`: x264 then
+      // threads *across* frames and holds one frame per thread — measured ~1.1 s later per frame
+      // than single-threaded on a 24-thread host.
       return ["-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency",
-        "-profile:v", "main", "-level", "4.0", "-x264-params", "sliced-threads=0:slices=1",
+        "-profile:v", "main", "-level", "4.0",
         "-bufsize", "1M", ...common];
   }
 }

package/src/services/session-file-baselines/session-file-baselines.service.ts

@@ -194,6 +194,54 @@ export function listBaselines(sessionId: string): FileBaseline[] {
     .sort((a, b) => order(a) - order(b) || a.path.localeCompare(b.path));
 }
 
+/** Per session directory, each record's path and capture order: records never change, so each is parsed once. */
+const recordIndex = new Map<string, Map<string, { path: string; order: number }>>();
+const INDEXES_KEPT = 64;
+
+/**
+ * The paths the session has a "before" for, oldest capture first — `listBaselines` without
+ * parsing every record on every call. A session that touched thousands of files holds tens of
+ * MB of them, and the list asks for these on every request.
+ */
+export function baselinePaths(sessionId: string): string[] {
+  const dir = sessionDir(sessionId);
+  if (!dir) return [];
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith(".json"));
+  } catch {
+    recordIndex.delete(dir);
+    return [];
+  }
+  const known = recordIndex.get(dir) ?? new Map<string, { path: string; order: number }>();
+  recordIndex.delete(dir);
+  recordIndex.set(dir, known);
+  if (recordIndex.size > INDEXES_KEPT) recordIndex.delete(recordIndex.keys().next().value!);
+  const present = new Set(names);
+  for (const name of known.keys()) if (!present.has(name)) known.delete(name);
+  for (const name of names) {
+    if (known.has(name)) continue;
+    const rec = parseRecord(join(dir, name));
+    if (rec) known.set(name, { path: rec.path, order: order(rec) });
+  }
+  return [...known.values()].sort((a, b) => a.order - b.order || a.path.localeCompare(b.path)).map((r) => r.path);
+}
+
+/**
+ * How many files the session has a "before" for, from the directory listing alone: cheap enough
+ * to ask after every turn, where `listBaselines` parses every record (a session that touched
+ * thousands of files holds tens of MB of them).
+ */
+export function countBaselines(sessionId: string): number {
+  const dir = sessionDir(sessionId);
+  if (!dir) return 0;
+  try {
+    return readdirSync(dir).filter((n) => n.endsWith(".json")).length;
+  } catch {
+    return 0;
+  }
+}
+
 /**
  * Whether PPM keeps anything the session itself wrote: a "before" (`<hash>.json`) or a file's
  * history (`history/`). Review marks and undo journals are the user's answers, not its writes.