@hraness/slopcamera 3.10.0 → 3.10.2

package/PRIVACY.md

@@ -53,3 +53,18 @@ from vulnerability reports.
 
 Report suspected vulnerabilities through GitHub private vulnerability
 reporting at https://github.com/hraness/slopcamera/security/advisories/new.
+
+## Website analytics
+
+The public slopcamera.com website sends cookieless page views, page exits,
+performance measurements, explicit link and install-copy actions, missing-page
+reports, and rate-limited redacted client errors to PostHog. It keeps no person
+profiles, analytics cookies, or session recordings and respects Do Not Track.
+Public campaign parameters are retained; other query values and credentials
+are removed. Sensitive paths collapse to `/private` and their campaign
+attribution is removed. Preview builds and the inert preview page send nothing.
+
+The site checks the shared regional analytics policy service. Analytics
+waits for acceptance where that policy requires consent, or when the region is
+unknown. Elsewhere it can run without cookies before a visitor responds.
+A stored refusal or Do Not Track keeps analytics off.

package/README.md

@@ -34,11 +34,11 @@ for prompt-only hosted images; model usage is billed separately.
 ## Install SlopCamera
 
 Install [Bun 1.3.14 or newer](https://bun.sh), then install the
-[SlopCamera v3.9.2 release](https://github.com/hraness/slopcamera/releases/tag/v3.9.2)
+[SlopCamera v3.10.1 release](https://github.com/hraness/slopcamera/releases/tag/v3.10.1)
 and its matching Agent Skill:
 
 ```sh
-bun add --global https://github.com/hraness/slopcamera/releases/download/v3.9.2/hraness-slopcamera-3.9.2.tgz
+bun add --global https://github.com/hraness/slopcamera/releases/download/v3.10.1/hraness-slopcamera-3.10.1.tgz
 slopcamera skill install --target agents
 ```
 

package/apps/desktop/application/operation.ts

@@ -4,7 +4,7 @@ import type { z } from "zod";
 
 import type { ApplicationContext } from "./context";
 
-export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.10.0" as const;
+export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.10.2" as const;
 
 export const OPERATION_KINDS = [
   "scene.audit",

package/apps/desktop/cli/commands.ts

@@ -365,7 +365,7 @@ import {
   workflowRunStore,
 } from "./workflow-runs";
 
-export const SLOPCAMERA_VERSION = "3.10.0";
+export const SLOPCAMERA_VERSION = "3.10.2";
 
 // Legacy direct renders predate per-target output contracts. Keep them
 // bounded generously enough for long-form production while preventing one

package/apps/desktop/cli/html-overlay-kqueue.ts

@@ -0,0 +1,184 @@
+import { fstatSync, lstatSync, type BigIntStats } from "node:fs";
+import { endianness } from "node:os";
+import { basename, join } from "node:path";
+import { ApplicationError } from "../application/errors";
+
+export interface BrowserWatchIdentity {
+  readonly path: string;
+  readonly dev: string;
+  readonly ino: string;
+  readonly mode: number;
+  readonly size?: string;
+  readonly ctimeNs?: string;
+  readonly mtimeNs?: string;
+  readonly uid?: string;
+  readonly gid?: string;
+  readonly nlink?: string;
+}
+
+const metadataKeys = ["size", "ctimeNs", "mtimeNs", "uid", "gid", "nlink"] as const;
+function matchesIdentity(details: BigIntStats, identity: BrowserWatchIdentity): boolean {
+  return details.dev.toString() === identity.dev && details.ino.toString() === identity.ino
+    && Number(details.mode & 0o177777n) === identity.mode
+    && metadataKeys.every(key => identity[key] === undefined || details[key].toString() === identity[key]);
+}
+
+interface WatchTarget {
+  readonly absolute: string;
+  readonly identity: BrowserWatchIdentity;
+  readonly label: string;
+  readonly kind: "anchor" | "container" | "payload" | "runtime-root";
+}
+
+/** Kernel vnode notes persist until read, including writes whose bytes were restored. */
+export async function createBrowserRuntimeKqueue(options: {
+  readonly anchor: string;
+  readonly anchorIdentity: BrowserWatchIdentity;
+  readonly container: string;
+  readonly containerIdentity: BrowserWatchIdentity;
+  readonly runtimeRoot: string;
+  readonly identities: readonly BrowserWatchIdentity[];
+}): Promise<{ poll: (mutations: Set<string>) => void; close: () => void }> {
+  if (process.platform !== "darwin") throw new ApplicationError("unavailable", "Browser vnode watches require macOS.");
+  if (!["arm64", "x64"].includes(process.arch) || endianness() !== "LE") throw new ApplicationError("unavailable", "Unsupported browser vnode watch ABI.");
+  const { dlopen, FFIType: T, ptr } = await import("bun:ffi");
+  const native = dlopen("/usr/lib/libSystem.B.dylib", {
+    kqueue: { args: [], returns: T.i32 },
+    kevent64: { args: [T.i32, T.ptr, T.i32, T.ptr, T.i32, T.u32, T.ptr], returns: T.i32 },
+    open: { args: [T.ptr, T.i32], returns: T.i32 },
+    close: { args: [T.i32], returns: T.i32 },
+    fcntl: { args: [T.i32, T.i32, T.i32], returns: T.i32 },
+    getrlimit: { args: [T.i32, T.ptr], returns: T.i32 },
+    fgetattrlist: { args: [T.i32, T.ptr, T.ptr, T.u64, T.u32], returns: T.i32 },
+  });
+  const targets: WatchTarget[] = [
+    { absolute: options.anchor, identity: options.anchorIdentity, label: "<snapshot-anchor>", kind: "anchor" },
+    { absolute: options.container, identity: options.containerIdentity, label: "<snapshot-container>", kind: "container" },
+    ...options.identities.map(identity => ({ absolute: identity.path === "." ? options.runtimeRoot : join(options.runtimeRoot, identity.path), identity, label: identity.path, kind: identity.path === "." ? "runtime-root" as const : "payload" as const })),
+  ];
+  let queue = -1;
+  let closed = false;
+  let closeFailure: unknown;
+  let failure: unknown;
+  const descriptors = new Map<number, WatchTarget>();
+  const payloadAccess = new Map<number, { atimeNs: bigint; readonly flags: number }>();
+  const immutableFlags = (descriptor: number): number => {
+    // Darwin attrlist: five attribute groups, requesting only ATTR_CMN_FLAGS.
+    const request = Buffer.alloc(24), result = Buffer.alloc(8);
+    request.writeUInt16LE(5, 0);
+    request.writeUInt32LE(0x00040000, 4);
+    if (native.symbols.fgetattrlist(descriptor, ptr(request), ptr(result), 8n, 0) !== 0
+      || result.readUInt32LE(0) !== 8) {
+      throw new ApplicationError("unavailable", "Browser vnode immutable flags could not be read completely.");
+    }
+    return result.readUInt32LE(4);
+  };
+  const close = () => {
+    if (closed) { if (closeFailure !== undefined) throw closeFailure; return; }
+    // A failed close may already have released its numeric descriptor. Never
+    // retry it: the number could belong to a different resource afterwards.
+    closed = true;
+    let failed = false;
+    for (const descriptor of descriptors.keys()) {
+      if (native.symbols.close(descriptor) === 0) descriptors.delete(descriptor);
+      else failed = true;
+    }
+    if (queue !== -1) {
+      if (native.symbols.close(queue) === 0) queue = -1;
+      else failed = true;
+    }
+    if (failed) {
+      closeFailure = new ApplicationError("unavailable", "Browser vnode descriptor collection is unproven.", { unresolvedDescriptors: descriptors.size + (queue === -1 ? 0 : 1) });
+      throw closeFailure;
+    }
+    native.close();
+  };
+  const reject = (message: string): never => { throw new ApplicationError("conflict", message); };
+  try {
+    const limits = new BigUint64Array(2);
+    // RLIMIT_NOFILE; never modify process or host resource limits.
+    if (targets.length > 8192 || native.symbols.getrlimit(8, ptr(limits)) !== 0 || limits[0]! < BigInt(targets.length + 64)) {
+      reject("Insufficient bounded descriptor capacity for complete browser vnode watches.");
+    }
+    queue = native.symbols.kqueue();
+    if (queue < 0) reject("Could not create browser vnode event queue.");
+    if (native.symbols.fcntl(queue, 2, 1) !== 0) reject("Could not prevent browser vnode queue inheritance.");
+    for (const target of targets) {
+      const path = Buffer.from(`${target.absolute}\0`);
+      // O_EVTONLY | O_SYMLINK | O_CLOEXEC. Symlinks bind their own vnode.
+      const descriptor = native.symbols.open(ptr(path), 0x8000 | 0x200000 | 0x1000000);
+      if (descriptor < 0) reject(`Could not open browser vnode watch: ${target.label}`);
+      descriptors.set(descriptor, target);
+      const details = fstatSync(descriptor, { bigint: true });
+      const identity = target.identity;
+      if (!matchesIdentity(details, identity)) {
+        reject(`Browser vnode identity changed before registration: ${target.label}`);
+      }
+      if (target.kind === "payload" && details.isFile()) {
+        payloadAccess.set(descriptor, { atimeNs: details.atimeNs, flags: immutableFlags(descriptor) });
+      }
+      const change = Buffer.alloc(48);
+      const receipt = Buffer.alloc(48);
+      change.writeBigUInt64LE(BigInt(descriptor), 0);
+      change.writeInt16LE(-4, 8); // EVFILT_VNODE
+      change.writeUInt16LE(1 | 0x20 | 0x40, 10); // EV_ADD | EV_CLEAR | EV_RECEIPT
+      // Unrelated children of /private/tmp are not this snapshot. Its own
+      // replacement/revocation/attribute changes remain observed; container
+      // and all payload directories independently retain child-write notes.
+      change.writeUInt32LE(target.kind === "anchor" ? 0x69 : 0x7f, 12);
+      const count = native.symbols.kevent64(queue, ptr(change), 1, ptr(receipt), 1, 1, null);
+      if (count !== 1 || receipt.readBigUInt64LE(0) !== BigInt(descriptor)
+        || receipt.readInt16LE(8) !== -4 || !(receipt.readUInt16LE(10) & 0x4000)
+        || receipt.readBigInt64LE(16) !== 0n) reject(`Browser vnode registration failed: ${target.label}`);
+    }
+    return {
+      close,
+      poll(mutations) {
+        if (failure !== undefined) throw failure;
+        if (closed) reject("Browser vnode event queue was closed before verification.");
+        try {
+          // One pending entry per registered vnode; aggregate flags are sticky
+          // in the caller before the next read can clear kernel state.
+          const output = Buffer.alloc(48 * targets.length);
+          const count = native.symbols.kevent64(queue, null, 0, ptr(output), targets.length, 1, null);
+          if (count < 0 || count > targets.length) reject("Browser vnode event queue could not be read completely.");
+          for (let index = 0; index < count; index += 1) {
+            const offset = index * 48;
+            const descriptor = Number(output.readBigUInt64LE(offset));
+            const target = descriptors.get(descriptor);
+            const flags = output.readUInt16LE(offset + 10);
+            const notes = output.readUInt32LE(offset + 12);
+            if (target === undefined) throw new ApplicationError("conflict", "Browser vnode event has an unknown descriptor.");
+            if (output.readInt16LE(offset + 8) !== -4 || flags & (0x4000 | 0x8000) || notes === 0 || notes & ~0x7f) {
+              reject("Browser vnode event queue returned an untrusted event.");
+            }
+            // Preserve the existing launch-managed app-root ATTRIB exception.
+            // No WRITE/RENAME/DELETE/LINK combination becomes a metadata event.
+            if (target.kind === "runtime-root" && notes === 8) {
+              mutations.add(`change:${basename(options.runtimeRoot)}`);
+              continue;
+            }
+            const access = payloadAccess.get(descriptor);
+            if (target.kind === "payload" && notes === 8 && access !== undefined
+              && (access.flags & 2) !== 0 && metadataKeys.every(key => target.identity[key] !== undefined)) {
+              const details = fstatSync(descriptor, { bigint: true });
+              const pathDetails = lstatSync(target.absolute, { bigint: true });
+              // mmap can emit pure ATTRIB for access-time updates on immutable
+              // files. Original ctime and all status identity remain fixed:
+              // restored flags, xattrs, permissions, and times still reject.
+              // The renderer also retains its full content-manifest checks.
+              if (details.isFile() && pathDetails.isFile()
+                && matchesIdentity(details, target.identity) && matchesIdentity(pathDetails, target.identity)
+                && details.atimeNs > access.atimeNs && pathDetails.atimeNs >= details.atimeNs
+                && immutableFlags(descriptor) === access.flags) {
+                access.atimeNs = pathDetails.atimeNs;
+                continue;
+              }
+            }
+            mutations.add(`vnode-${String(notes)}:${target.label}`);
+          }
+        } catch (error) { failure = error; throw error; }
+      },
+    };
+  } catch (error) { close(); throw error; }
+}

package/apps/desktop/cli/html-overlay-renderer.ts

@@ -23,6 +23,9 @@ import { basename, dirname, join } from "node:path";
 
 import { z } from "zod";
 
+import { verifyStableBrowserWatcherBaseline } from "./html-overlay-watcher-baseline";
+import { createBrowserRuntimeKqueue } from "./html-overlay-kqueue";
+
 import {
   chromium,
   type Browser,
@@ -389,10 +392,14 @@ interface SnapshotAnchorIdentity {
 interface SnapshotPathIdentity {
   readonly ctimeNs: string;
   readonly dev: string;
+  readonly gid: string;
   readonly ino: string;
   readonly mode: number;
+  readonly mtimeNs: string;
+  readonly nlink: string;
   readonly path: string;
   readonly size: string;
+  readonly uid: string;
 }
 
 interface SnapshotDirectChildIdentity {
@@ -543,10 +550,14 @@ async function captureBrowserRuntimeSnapshotIdentity(
     identities.push({
       ctimeNs: details.ctimeNs.toString(),
       dev: details.dev.toString(),
+      gid: details.gid.toString(),
       ino: details.ino.toString(),
       mode: Number(details.mode & 0o177777n),
+      mtimeNs: details.mtimeNs.toString(),
+      nlink: details.nlink.toString(),
       path: entry.path,
       size: details.size.toString(),
+      uid: details.uid.toString(),
     });
   }
   return identities;
@@ -567,10 +578,14 @@ async function captureBrowserRuntimeSnapshotContainerIdentity(
   return {
     ctimeNs: details.ctimeNs.toString(),
     dev: details.dev.toString(),
+    gid: details.gid.toString(),
     ino: details.ino.toString(),
     mode: Number(details.mode & 0o177777n),
+    mtimeNs: details.mtimeNs.toString(),
+    nlink: details.nlink.toString(),
     path: "<snapshot-container>",
     size: details.size.toString(),
+    uid: details.uid.toString(),
   };
 }
 
@@ -1456,8 +1471,10 @@ export async function removeBrowserRuntimeSnapshot(
 async function assertNoBrowserRuntimeMutationEvents(
   mutations: ReadonlySet<string>,
   label: string,
+  poll?: () => void,
 ): Promise<void> {
   await new Promise<void>(resolve => setImmediate(resolve));
+  poll?.();
   if (mutations.size > 0) {
     throw new ApplicationError(
       "conflict",
@@ -2009,6 +2026,7 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
     let browserRuntimeSnapshot: PreparedBrowserRuntimeSnapshot | undefined;
     const browserRuntimeWatchers: FSWatcher[] = [];
     const browserRuntimeMutations = new Set<string>();
+    let kernelWatcher: Awaited<ReturnType<typeof createBrowserRuntimeKqueue>> | undefined;
     let renderFailure: Readonly<{ error: unknown }> | undefined;
     let renderResult: HtmlOverlayFrameRenderResult | undefined;
     let gpuEvidence: HtmlOverlayGpuEvidence | undefined;
@@ -2020,94 +2038,126 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
         signal,
       );
       browserRuntimeSnapshot = preparedBrowserRuntime;
+      let watcherVersion = 0;
+      let watcherFailure: Error | undefined;
       const runtimeName = basename(preparedBrowserRuntime.runtimeRoot);
       const snapshotName = basename(preparedBrowserRuntime.directory);
-      const anchorWatcher = watch(
-        preparedBrowserRuntime.anchorPath,
-        { persistent: false },
-        (eventType, filename) => {
-          const path = filename?.toString() ?? "<snapshot-anchor>";
-          if (path === snapshotName) {
-            browserRuntimeMutations.add(`anchor-${eventType}:${path}`);
-          }
-        },
-      );
-      anchorWatcher.on("error", error => {
-        browserRuntimeMutations.add(`anchor-watch-error:${error.message}`);
-      });
-      browserRuntimeWatchers.push(anchorWatcher);
-      const containerWatcher = watch(
-        preparedBrowserRuntime.directory,
-        { persistent: false, recursive: process.platform === "darwin" },
-        (eventType, filename) => {
-          const path = filename?.toString().replaceAll("\\", "/")
-            ?? "<snapshot-container>";
-          if (
-            path === "home"
-            || path.startsWith("home/")
-            || path === "tmp"
-            || path.startsWith("tmp/")
-          ) return;
-          if (path === runtimeName && eventType === "change") {
-            // Gatekeeper may change the app root's first-launch metadata. The
-            // immutable parent and its exact ctime identity independently
-            // prove that this pathname was never removed or replaced.
-            return;
-          }
-          if (
-            request.browserRuntime.provenance.kind === "test-only-unverified"
-            && request.browserRuntime.manifest.layout === "single-executable"
-            && path === runtimeName
-            && eventType === "rename"
-          ) {
-            // Darwin reports synthetic rename events for accesses to the
-            // test-only single-file fixture. Production rejects this layout;
-            // its exact path identity still detects fixture substitution.
-            return;
-          }
-          if (path === runtimeName || path.startsWith(`${runtimeName}/`)) {
+      if (process.platform === "darwin") {
+        kernelWatcher = await createBrowserRuntimeKqueue({
+          anchor: preparedBrowserRuntime.anchorPath,
+          anchorIdentity: preparedBrowserRuntime.anchorIdentity,
+          container: preparedBrowserRuntime.directory,
+          containerIdentity: preparedBrowserRuntime.containerIdentity,
+          runtimeRoot: preparedBrowserRuntime.runtimeRoot,
+          identities: preparedBrowserRuntime.identity,
+        });
+      } else {
+        const anchorWatcher = watch(
+          preparedBrowserRuntime.anchorPath,
+          { persistent: false },
+          (eventType, filename) => {
+            const path = filename?.toString() ?? "<snapshot-anchor>";
+            if (path === snapshotName) {
+              watcherVersion += 1;
+              browserRuntimeMutations.add(`anchor-${eventType}:${path}`);
+            }
+          },
+        );
+        anchorWatcher.on("error", error => {
+          watcherFailure = error;
+          browserRuntimeMutations.add(`anchor-watch-error:${error.message}`);
+        });
+        browserRuntimeWatchers.push(anchorWatcher);
+        const containerWatcher = watch(
+          preparedBrowserRuntime.directory,
+          { persistent: false, recursive: false },
+          (eventType, filename) => {
+            const path = filename?.toString().replaceAll("\\", "/")
+              ?? "<snapshot-container>";
+            if (
+              path === "home"
+              || path.startsWith("home/")
+              || path === "tmp"
+              || path.startsWith("tmp/")
+            ) return;
+            if (path === runtimeName && eventType === "change") {
+              // Gatekeeper may change the app root's first-launch metadata. The
+              // immutable parent and its exact ctime identity independently
+              // prove that this pathname was never removed or replaced.
+              return;
+            }
+            if (
+              request.browserRuntime.provenance.kind === "test-only-unverified"
+              && request.browserRuntime.manifest.layout === "single-executable"
+              && path === runtimeName
+              && eventType === "rename"
+            ) {
+              // Darwin reports synthetic rename events for accesses to the
+              // test-only single-file fixture. Production rejects this layout;
+              // its exact path identity still detects fixture substitution.
+              return;
+            }
+            watcherVersion += 1;
+            if (path === runtimeName || path.startsWith(`${runtimeName}/`)) {
+              browserRuntimeMutations.add(`${eventType}:${path}`);
+              return;
+            }
             browserRuntimeMutations.add(`${eventType}:${path}`);
-            return;
-          }
-          browserRuntimeMutations.add(`${eventType}:${path}`);
-        },
-      );
-      containerWatcher.on("error", error => {
-        browserRuntimeMutations.add(`watch-error:${error.message}`);
-      });
-      browserRuntimeWatchers.push(containerWatcher);
-      await new Promise<void>(resolve => setTimeout(resolve, 25));
-      if (signal.aborted) throw cancellationReason(signal);
-      // FSEvents can deliver the just-created direct-child notification after
-      // both watches attach. Clear that bounded baseline before re-verifying
-      // every manifest and path identity. A swap during this window changes
-      // the already-captured container ctime and therefore fails below.
-      browserRuntimeMutations.clear();
+          },
+        );
+        containerWatcher.on("error", error => {
+          watcherFailure = error;
+          browserRuntimeMutations.add(`watch-error:${error.message}`);
+        });
+        browserRuntimeWatchers.push(containerWatcher);
+      }
       let browser: Browser | undefined;
       let browserFailure: Readonly<{ error: unknown }> | undefined;
       try {
-        await verifyBrowserRuntimeSnapshot(
-          preparedBrowserRuntime,
-          request.browserRuntime,
-          "immediately before launch",
-          signal,
-        );
-        await assertBrowserRuntimeSnapshotIdentity(
-          preparedBrowserRuntime,
-          request.browserRuntime.manifest.entries,
-          "immediately before launch",
-          signal,
-        );
-        await assertBrowserRuntimeSnapshotContainerIdentity(
-          preparedBrowserRuntime,
-          "immediately before launch",
-          signal,
-        );
-        await assertBrowserRuntimeSnapshotAnchorIdentity(
-          preparedBrowserRuntime,
-          "immediately before launch",
+        // Delayed preparation notifications can arrive during full verification.
+        // Recheck the SAME pre-wait identities until one pass is stable. Nothing
+        // after the synchronous baseline commit is discarded.
+        const baselineOptions = {
           signal,
-        );
+          version: () => watcherVersion,
+          failure: () => watcherFailure,
+          quietMs: process.platform === "darwin" ? 2_000 : 25,
+          deadlineMs: 10_000,
+          verify: async () => {
+            await verifyBrowserRuntimeSnapshot(
+              preparedBrowserRuntime,
+              request.browserRuntime,
+              "immediately before launch",
+              signal,
+            );
+            await assertBrowserRuntimeSnapshotIdentity(
+              preparedBrowserRuntime,
+              request.browserRuntime.manifest.entries,
+              "immediately before launch",
+              signal,
+            );
+            await assertBrowserRuntimeSnapshotContainerIdentity(
+              preparedBrowserRuntime,
+              "immediately before launch",
+              signal,
+            );
+            await assertBrowserRuntimeSnapshotAnchorIdentity(
+              preparedBrowserRuntime,
+              "immediately before launch",
+              signal,
+            );
+          },
+          commit: () => { browserRuntimeMutations.clear(); },
+        };
+        if (kernelWatcher !== undefined) {
+          // Vnode notes begin at registration, not an asynchronous history
+          // stream. Never clear a payload event, including during baseline.
+          await baselineOptions.verify();
+          kernelWatcher.poll(browserRuntimeMutations);
+        } else {
+          await verifyStableBrowserWatcherBaseline(baselineOptions);
+        }
+        kernelWatcher?.poll(browserRuntimeMutations);
         discardProvenLaunchManagedRootMetadataEvent(
           browserRuntimeMutations,
           runtimeName,
@@ -2115,6 +2165,7 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
         await assertNoBrowserRuntimeMutationEvents(
           browserRuntimeMutations,
           "before browser launch",
+          () => kernelWatcher?.poll(browserRuntimeMutations),
         );
         const launchedBrowser = await boundedBrowserStep(
           async () => {
@@ -2174,6 +2225,7 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
           "during browser launch",
           signal,
         );
+        kernelWatcher?.poll(browserRuntimeMutations);
         discardProvenLaunchManagedRootMetadataEvent(
           browserRuntimeMutations,
           runtimeName,
@@ -2181,6 +2233,7 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
         await assertNoBrowserRuntimeMutationEvents(
           browserRuntimeMutations,
           "during browser launch",
+          () => kernelWatcher?.poll(browserRuntimeMutations),
         );
         const contextContract = HTML_OVERLAY_RENDERER_CONTRACT.browserContext;
         const context = await boundedBrowserStep(
@@ -2475,6 +2528,7 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
         "through browser shutdown",
         signal,
       );
+      kernelWatcher?.poll(browserRuntimeMutations);
       discardProvenLaunchManagedRootMetadataEvent(
         browserRuntimeMutations,
         runtimeName,
@@ -2482,6 +2536,7 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
       await assertNoBrowserRuntimeMutationEvents(
         browserRuntimeMutations,
         "through browser shutdown",
+        () => kernelWatcher?.poll(browserRuntimeMutations),
       );
       renderResult = {
         ...(gpuEvidence === undefined ? {} : { gpuEvidence }),
@@ -2496,6 +2551,12 @@ export class PlaywrightHtmlOverlayRenderer implements HtmlOverlayRenderer {
         .catch(() => undefined);
     } finally {
       for (const watcher of browserRuntimeWatchers) watcher.close();
+      try { kernelWatcher?.close(); } catch (error) {
+        renderFailure = { error: new ApplicationError("unavailable", "Browser vnode watch cleanup failed; frames were not published.", {
+          cause: error,
+          ...(renderFailure === undefined ? {} : { renderFailure: renderFailure.error }),
+        }) };
+      }
       if (browserRuntimeSnapshot !== undefined) {
         if (browserShutdownRequired) {
           const retainedError = new ApplicationError("unavailable", "HTML overlay browser shutdown is unproven; its active runtime snapshot was retained and frames were not published.", {

package/apps/desktop/cli/html-overlay-watcher-baseline.ts

@@ -0,0 +1,65 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+interface BaselineClock {
+  readonly now: () => number;
+  readonly wait: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+}
+
+const clock: BaselineClock = {
+  now: () => performance.now(),
+  wait: async (milliseconds, signal) => { await delay(milliseconds, undefined, { signal }); },
+};
+
+/** Drain asynchronous preparation notifications before revalidating the saved identities. */
+interface BrowserWatcherBaselineOptions {
+  readonly signal: AbortSignal;
+  readonly version: () => number;
+  readonly failure: () => Error | undefined;
+  readonly quietMs: number;
+  readonly deadlineMs: number;
+  readonly clock?: BaselineClock;
+}
+
+export async function settleBrowserWatcherBaseline(options: BrowserWatcherBaselineOptions): Promise<void> {
+  const timing = options.clock ?? clock;
+  const started = timing.now();
+  let lastActivity = started;
+  let observedVersion = options.version();
+  for (;;) {
+    options.signal.throwIfAborted();
+    const failure = options.failure();
+    if (failure !== undefined) throw failure;
+    const now = timing.now();
+    const version = options.version();
+    if (version !== observedVersion) {
+      observedVersion = version;
+      lastActivity = now;
+    }
+    if (now - started >= options.deadlineMs) {
+      throw new Error("Browser runtime filesystem notifications did not settle before launch.");
+    }
+    if (now - lastActivity >= options.quietMs) return;
+    await timing.wait(Math.min(50, options.quietMs - (now - lastActivity), options.deadlineMs - (now - started)), options.signal);
+  }
+}
+
+/** Every discarded notification batch must precede a stable, complete identity check. */
+export async function verifyStableBrowserWatcherBaseline(options: BrowserWatcherBaselineOptions & {
+  readonly verify: () => Promise<void>;
+  readonly commit: () => void;
+}): Promise<void> {
+  for (let pass = 0; pass < 3; pass += 1) {
+    await settleBrowserWatcherBaseline(options);
+    const version = options.version();
+    await options.verify();
+    options.signal.throwIfAborted();
+    const failure = options.failure();
+    if (failure !== undefined) throw failure;
+    if (options.version() === version) {
+      // No await may separate the stable-generation check from arming the guard.
+      options.commit();
+      return;
+    }
+  }
+  throw new Error("Browser runtime filesystem notifications changed during all three verification passes.");
+}