refactor: close the remaining unguarded type assertions

Types the event-queue iterator's TReturn as undefined so the terminal
result needs no cast; declares the isError field the pi runtime reads by
duck-typing; binds socket to a local const in the daemon transport;
replaces the @ts-ignore on the optional sharp import with a non-literal
specifier so src/ still typechecks where sharp was not installed.

Adds src/util/guards.ts as the single home for narrowing over unknown —
isRecord plus scalar/array readers — and converts the two private
isObject copies in cdp/types.ts and daemon/protocol.ts along with every
inline `as Record<string, unknown>` in domains/js.ts and domains/render.ts.

Gives Accessibility.getFullAXTree a real result schema, closing the last
unvalidated CDP boundary: only nodeId is required, every object carries
additionalProperties, and each AX value stays Unknown, so the tree
decodes as a whole or fails as a whole rather than being filtered.

Guards the five tool-result `details` readers, the daemon attach
response, the persisted session state, the browser-namespace flag, and
the fs errno narrowing, each feeding an already-present failure path.

The daemon-transport socket binding is not a bug fix: send() runs
synchronously inside sendWithTimeout's promise executor, so socket cannot
be reassigned between the check and the write. It removes the assertion
and makes the write immune to a later refactor that adds an await.

Two assertions survive by design and are documented in the task report:
the never->unknown re-widening in util/tool.ts, which the type-erased
tool registry makes unavoidable, and the AsyncFunction constructor lookup
in domains/js.ts, which JavaScript exposes no typed binding for.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

1 files changed, 16 insertions, 19 deletions

diff --git a/src/domains/snapshot.ts b/src/domains/snapshot.ts
index ec5c894..c015203 100644
--- a/src/domains/snapshot.ts
+++ b/src/domains/snapshot.ts
@@ -3,12 +3,14 @@ import { Type } from "typebox";
 import { Container, Image, type ImageTheme, Markdown, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import type { CdpSession } from "../cdp/session";
+import type { AxNodeResult } from "../cdp/commands";
 import { type Box, boxOf } from "./box";
 import { cdpCall } from "./cdp-call";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
 import { screenshotPath } from "../util/paths";
+import { asBoolean, asNumber, asRecord, asString } from "../util/guards";
 
 const SnapshotArgs = Type.Object({
   includeScreenshot: Type.Optional(
@@ -28,20 +30,8 @@ const SnapshotArgs = Type.Object({
   ),
 });
 
-// Raw shapes from CDP Accessibility.getFullAXTree. Cast at this boundary only.
-type AxValue = { value?: unknown };
-export type RawAxNode = {
-  nodeId: string;
-  parentId?: string;
-  childIds?: ReadonlyArray<string>;
-  ignored?: boolean;
-  role?: AxValue;
-  name?: AxValue;
-  value?: AxValue;
-  description?: AxValue;
-  properties?: ReadonlyArray<{ name?: string; value?: AxValue }>;
-  backendDOMNodeId?: number;
-};
+export type RawAxNode = AxNodeResult;
+type AxValue = NonNullable<RawAxNode["role"]>;
 
 export type SlimNode = {
   role: string;
@@ -322,7 +312,7 @@ export const snapshotTool = defineBrowserTool({
     // 1. AX tree
     const axRes = await cdpCall(client, "Accessibility.getFullAXTree", {});
     if (!axRes.success) return axRes;
-    const rawNodes = (axRes.data as { nodes: ReadonlyArray<RawAxNode> }).nodes;
+    const rawNodes = axRes.data.nodes;
 
     // 2. Page url/title
     const piRes = await client.pageInfo();
@@ -412,10 +402,17 @@ export const snapshotTool = defineBrowserTool({
   },
 
   renderResult(result, expanded, theme) {
-    const details = result.details as
-      | (SnapshotDetails & { summary?: string; ok?: boolean })
-      | undefined;
-    if (!details) return new Text(theme.fg("error", "snapshot: no details"), 0, 0);
+    const raw = asRecord(result.details);
+    if (raw === undefined) return new Text(theme.fg("error", "snapshot: no details"), 0, 0);
+    const details = {
+      nodeCount: asNumber(raw["nodeCount"]),
+      truncated: asBoolean(raw["truncated"]),
+      fullOutputPath: asString(raw["fullOutputPath"]),
+      screenshotPath: asString(raw["screenshotPath"]),
+      url: asString(raw["url"]),
+      title: asString(raw["title"]),
+      summary: asString(raw["summary"]),
+    };
 
     const titleLine = details.title ? ` "${details.title}"` : "";
     const summary = details.summary ?? "";