specpi 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.20.0 - 2026-09-09
+
+- Add opt-in `structural_search` with pinned ast-grep 0.45.3, protected explicit source selection, bounded output and subprocess cleanup, and exact-call approval in Strict mode. Enable with `specpi update --structural-search=on`, then restart Pi.
+- Add `browser_accessibility` with axe-core 4.13.0 for the current browser state, fixed WCAG profiles, bounded violations and incomplete findings, and existing browser cancellation. Update the managed browser runtime to provision the scanner.
+- Stage, smoke, verify and roll back structural runtime changes with the installer; preserve enablement and modified runtimes, qualify native hosts in CI, and keep downloaded binaries out of the npm artifact. An unparseable owned configuration is reported with its path instead of aborting `plan`, and only an explicit `--structural-search` selection rewrites it.
+- Fix structural-search merge findings: preserve non-binary runtime changes using full-tree ownership checks, restore prior runtimes before failed cleanup, bound serialized enablement configuration, and dismiss expired/cancelled Strict approvals.
+
 ## 0.19.1 - 2026-09-08
 
 - Allow Pi's exact public Copilot catalog identification headers during delegation, fixing Copilot → Anthropic → Copilot switches that were incorrectly rejected as runtime provider overrides. Reconstruct headers independently in the child; retain runtime-auth, extension-provider and other header restrictions. Restart Pi after updating the harness.

package/README.md

@@ -32,6 +32,8 @@ SpecPi extends Pi with chat, review tools, and focused delegation. Its principle
 - **Focused delegation.** One agent makes changes. Up to two read-only subagents help investigate and review. [Research and design](https://tannermidd.github.io/SpecPi/single-agent/)
 - **Background tasks.** Start an approved dev server, test suite, or watch build, inspect bounded output, and stop it without blocking other work.
 - **Review as you work.** Track changed files, inspect diffs, check pages in a browser, and review risky commands.
+- **Structural search.** Opt into bounded ast-grep patterns over selected code with `specpi update --structural-search=on`. [Usage and limits](docs/structural-search.md)
+- **Accessibility checks.** Scan the current browser state for automated WCAG and optional best-practice findings. [Browser verification](docs/browser-testing.md)
 - **Improvements you choose.** Record recurring problems, select one with `/harness-improvement`, and test the change before calling it done.
 
 Problem collection is off by default. Its records stay on your machine. Pi connects to your chosen model provider.
@@ -49,7 +51,7 @@ specpi doctor
 
 Preview the changes, confirm the install, then check the setup. Restart Pi when finished.
 
-To pin this release, use `npm install --global specpi@0.19.1`.
+To pin this release, use `npm install --global specpi@0.20.0`.
 
 Delegation is enabled at startup. Use `/delegate off` to turn it off.
 
@@ -63,7 +65,7 @@ Chat beside your code, attach files, and switch conversations.
 
 In VS Code, find **SpecPi Chat** by **tannermidd** in Extensions and install it. Open **SpecPi** in the Activity Bar, then **Connect Pi**.
 
-Chat 0.4.1 shows a compact delegation strip only while workers run or settle, and opens workspace image links in the image viewer. SpecPi 0.19.1 fixes delegation when switching GitHub Copilot models in the same chat, including Luna → Opus → Luna. Update the harness and use **Restart Pi** to load the fix; this patch does not require a Chat update. Later model switches do not require a restart. New Chat sessions start with Guard off; use `/guard guard` or `/guard strict` to enable it.
+Chat 0.4.4 shows a compact delegation strip only while workers run or settle, and opens workspace image links in the image viewer. SpecPi 0.19.1 fixes delegation when switching GitHub Copilot models in the same chat, including Luna → Opus → Luna. Update the harness and use **Restart Pi** to load the fix; this patch does not require a Chat update. Later model switches do not require a restart. New Chat sessions start with Guard off; use `/guard guard` or `/guard strict` to enable it.
 
 ## Go further
 

package/SECURITY_MODEL.md

@@ -183,6 +183,8 @@ Completion Challenge activation and structured results are bounded to the curren
 
 ## Browser isolation
 
+The fixed `browser_accessibility` operation loads pinned axe-core/Playwright packages from the private browser runtime and scans an already open page. It exposes no model-supplied JavaScript, custom rules or exclusions. Results retain bounded rule guidance and target examples, not raw HTML/check payloads; selectors and URL paths can still contain private data and normal tool results may persist in Pi history. Findings include incomplete checks, profile/tags, viewport and scan timestamps. Navigation invalidates the result; dynamic DOM changes are not an atomic snapshot. Cancellation uses the existing browser teardown path. No automatic accessibility artifact or new external scanning service is introduced. The historical browser capability validator retains its original contract; installer/doctor request a separate additional accessibility smoke within the same browser launch.
+
 SpecPi launches managed Chromium in a fresh Playwright context. It does not attach to a personal browser profile or load the user's cookies, saved passwords, or extensions. Browser pages still execute untrusted content and can reach URLs available to the host.
 
 Snapshots, screenshots, page text, downloads, console output, and visual baselines may contain sensitive information. Default artifacts remain in SpecPi's private state directory. Explicit output publication is bounded and atomic, and existing artifacts or baselines are not replaced without explicit overwrite authorization.
@@ -193,6 +195,14 @@ Keyboard, native-selection, and condition-wait tools accept bounded declarative
 
 The browser is not an operating-system or network sandbox. Use a container or VM for hostile applications and dedicated test accounts instead of personal authenticated sessions.
 
+## Structural search
+
+Structural search is disabled until explicitly selected. The owned `specpi/tool-integrations.json` file stores nonsecret enablement; plan does not mutate it, updates back it up and roll it back with managed state, and uninstall preserves it. Unparseable content does not abort the non-mutating plan and does not silently enable anything: install and update stop and name the file unless an explicit `--structural-search` selection rewrites it, and the prior bytes go to the operation backup first. A configuration that is a link or not a bounded regular file stays a hard failure that no selection rewrites. The extension itself treats any unreadable configuration as disabled. Runtime acquisition is private, pinned, script-free and transactional. Configuration output is checked against the same 16 KiB bound as reads before mutation, with compact JSON fallback. Doctor checks source/runtime integrity before its offline fixture; unverified or modified prior runtime directories are preserved rather than deleted. Runtime ownership now binds the acquired tree's contents, paths, directories, permissions and link targets; the tree fingerprint does not traverse links, and the marker is checked separately. Legacy binary-only markers remain unverified. Retirement rechecks the tree before deletion. Rollback quarantines the new runtime and restores the prior directory before attempting recursive cleanup, reporting any retained quarantine. No global executable search or PATH injection is used.
+
+The parent captures explicit selected source with the existing snapshot path/private-store/link/descriptor/digest checks. A parent-only byte callback rechecks the original digest and clears its buffer after parsing. Existing workers gain no tool or byte API route. Files are capped at 1 MiB, selection at 8 MiB/200 files, pattern at 4 KiB, returned evidence at 24 KiB, raw stdout at 2 MiB and stderr at 8 KiB per call. Source bytes go to a reviewed native parser over stdin; only a neutral configuration is written to private scratch. Files containing secrets under ordinary source names are not automatically detectable.
+
+Native execution uses a fixed argument array, `shell: false`, an absolute private binary, explicit neutral ast-grep configuration and minimal environment. No rewrite, rule import, custom grammar or arbitrary executable is exposed. Guard admission is source-bound and repeated before parsing; Strict uses exact-call approval, Off does not remove tool restrictions, and Locked/ambiguous state denies. Session/policy changes cancel queued work and invalidate pending authorization; approval dialogs receive the operation signal and remaining timeout. Pi 0.84.4 releases cancelled RPC approvals locally but does not send remote dismissal events; clients expire them using the forwarded timeout, and late replies cannot authorize cancelled work. A parser that does not confirm termination blocks further starts until cleanup and reload. These controls are not OS containment: trusted same-user native code and extensions retain host privileges.
+
 ## Website and automation
 
 The GitHub Pages workflow publishes the checked-in `site/` directory only after the shared browser test job succeeds for that checked-out revision. The loopback rendered-site server rejects traversal and symlink escapes. Tests block third-party requests, use a synthetic clipboard, and upload only public-site failure screenshots with three-day retention; no visual baselines are created automatically. Required browser commands fail rather than skip when prerequisites are unavailable. Strict no-emit browser type checking uses local pinned development declarations; third-party declaration bodies and other extension implementations are outside that scoped gate.
@@ -211,7 +221,7 @@ Chat allows up to 90 seconds for an initial read-only RPC readiness probe before
 
 The webview loads only packaged scripts/styles under a strict content security policy, forbids network resources, and renders model/tool/file text without interpreting embedded HTML. Images use validated data URLs under `img-src data:`; remote image URLs are never fetched by the webview. HTTP(S) links, including external image links, require a human click and pass through VS Code's external-link API. Clicked code references use a separate host action: paths are parsed, checked against the selected workspace, canonicalized, and restricted to regular non-sensitive files before VS Code opens the file and reveals a clamped line/range. Clicked workspace Markdown image references, and ordinary file links or inline references ending in PNG, JPEG, GIF or WebP extensions, use the same path boundary and the image validator before a preview is returned. The extension suffix chooses the viewer, not whether the file is safe or valid. Arbitrary command and URI handlers are not executed. Raw paths preserve literal percent signs; Markdown link destinations and explicit local file URLs are decoded once before filesystem validation.
 
-Text/code context requires an explicit file/selection action, is size-bounded, rejects binary and known sensitive paths, and checks canonical workspace containment. Workspace file suggestions enumerate a bounded set of names; choosing a suggestion invokes the same attachment validation before reading contents. Dropped workspace URIs are validated independently of their browser representation. Native image selection, clipboard images, and dropped image files are explicit attachment actions and may supply images from outside the selected workspace; filesystem image sources still require ordinary files and pass sensitive-path checks. Pi-state names such as `auth`, `trust`, `sessions`, `missions`, and `history` are reserved inside `.pi`, Chat-owned storage, and the configured Pi agent directory (including its canonical target), not arbitrary source directories. Global credential/key patterns remain blocked, including `auth.json`. Relative `PI_CODING_AGENT_DIR` overrides retain conservative name blocking because they resolve in the child workspace; use an absolute path or `~/…` to obtain directory-scoped filtering. These filename checks and format validators are not content-based secret detectors. Manually typed messages, ordinary files, and images may contain sensitive content, and the extension does not promise image metadata removal. Prompts and attachments are sent to the provider selected in Pi when the user sends them.
+Text/code context comes from an explicit attachment action or the enabled editor-selection offer when the user sends a message. The offer carries positions and document version, not source text; send-time collection preserves the exact selected characters and rejects a changed document. Context is size-bounded, rejects binary and known sensitive paths, and checks canonical workspace containment. Workspace file suggestions enumerate a bounded set of names; choosing a suggestion invokes the same attachment validation before reading contents. Root `.gitignore` filtering uses the bounded 64 KiB UTF-8 attachment reader with canonical containment, private-path, hard-link, and identity checks, and refuses symlinks and special files before opening. An unsafe or unavailable ignore file stops the operation; it does not silently disable filtering. Glob matching uses dynamic programming with bounded work rather than backtracking glob regexes. Malformed character classes invalidate only their own rule. Folder attachments contain directory metadata only, capped at 200 displayed entries / 16 KiB and 1,000 scanned entries across the snapshot (including hidden entries), with an explicit truncation notice. These output/work bounds do not guarantee filesystem I/O latency. Dropped workspace URIs are validated independently of their browser representation. Native image selection, clipboard images, and dropped image files are explicit attachment actions and may supply images from outside the selected workspace; filesystem image sources still require ordinary files and pass sensitive-path checks. Pi-state names such as `auth`, `trust`, `sessions`, `missions`, and `history` are reserved inside `.pi`, Chat-owned storage, and the configured Pi agent directory (including its canonical target), not arbitrary source directories. Global credential/key patterns remain blocked, including `auth.json`. Relative `PI_CODING_AGENT_DIR` overrides retain conservative name blocking because they resolve in the child workspace; use an absolute path or `~/…` to obtain directory-scoped filtering. These filename checks and format validators are not content-based secret detectors. Manually typed messages, ordinary files, and images may contain sensitive content, and the extension does not promise image metadata removal. Prompts and attachments are sent to the provider selected in Pi when the user sends them.
 
 Image content is checked for supported PNG, JPEG, GIF, or WebP structure, declared MIME agreement, dimensions, and bounded base64 size. Each image is limited to 5 MiB, 16,384 pixels per side, and 40 million pixels. A prompt permits eight mixed attachments and 20 MiB of image bytes. The display retains at most 32 images / 20 MiB and reports omitted content; this is separate from Pi's persisted history. RPC records and buffered writes have independent 64 MiB caps. Recognized oversized history responses with a matching pending request are drained without accumulating the remaining bytes, then rejected without terminating Pi. The sidebar reports omitted history and remains usable; other oversized protocol records terminate the connection. A large historical transcript can exceed the RPC cap even when its original prompts were individually valid. Media caches remain in memory, are referenced by opaque identifiers while streaming, and are released as content is no longer retained. No remote image fetch, image processing service, or new image dependency is introduced. Pi/provider image limits and behavior remain upstream contracts.
 

package/THIRD_PARTY.md

@@ -1,5 +1,9 @@
 # Third-party components
 
+Structural search privately installs `@ast-grep/cli` **0.45.3**, its matching platform-specific native binary package, and `detect-libc` **2.1.2**, under the exact `structural-runtime/package-lock.json` graph. These packages use MIT licenses. Installation uses `npm ci --ignore-scripts`; SpecPi resolves the pinned platform binary directly and does not execute the CLI's postinstall copier, invoke a global `sg`, download a fallback or modify PATH. Source: [ast-grep](https://github.com/ast-grep/ast-grep). Windows x64, macOS x64/arm64 and Linux glibc x64 are the implemented platform mappings; CI and offline fixture smokes qualify the corresponding hosts.
+
+Browser accessibility adds `@axe-core/playwright` **4.13.0** and `axe-core` **4.13.0** to the existing locked browser runtime, retaining Playwright **1.62.1**. Both Deque packages are MPL-2.0, remain unmodified, and retain their installed license/source notices. SpecPi's npm artifact ships dependency manifests/locks, not vendored scanner code; npm acquires the packages during confirmed browser setup. Source: [axe-core](https://github.com/dequelabs/axe-core), [Playwright integration](https://github.com/dequelabs/axe-core-npm). The fixed scanner runs in the existing isolated Chromium context, with no new external accessibility service.
+
 SpecPi Chat is a separate VS Code extension built with the public VS Code Webview View API and Pi `0.84.4`'s documented RPC protocol. VS Code and the installed Pi runtime retain their upstream licenses; neither is bundled in the VSIX. The extension and its ZIP/VSIX packager use Node built-ins and first-party source only, with no added runtime or development dependency. Its tests reuse the repository's pinned Playwright and Pi packages. Provider authentication, requests, billing, and normal Pi background behavior remain owned by the configured Pi runtime.
 
 Chat's provider Limits row recognizes the public RPC `setStatus` presentation contracts of `@llblab/pi-codex-usage` **0.9.3** (`aa-codex-usage`) and `@sreetej510/pi-usage` **0.9.9** (`provider-usage`). Public source was checked at commits `1a97ee5560c5d7dd3b99ce34e2dcfe456592f8a0` and `9dee3b590f736c723011e3bc3717b3f0d6e8072b`, respectively. Tests reproduce their status/notification contracts through synthetic local Pi RPC, not live accounts or upstream provider requests. Text retains each plugin's quota semantics rather than converting or aggregating measurements. Neither plugin is bundled in the VSIX; this compatibility change does not install pi-usage or change SpecPi's existing package pins. Plugins retain ownership of authentication, caching, refresh/backoff, and explicit reset-consumption confirmation.

package/browser-runtime/package-lock.json

@@ -9,6 +9,8 @@
       "version": "0.1.0",
       "license": "MIT",
       "dependencies": {
+        "@axe-core/playwright": "4.13.0",
+        "axe-core": "4.13.0",
         "pixelmatch": "7.2.0",
         "playwright": "1.62.1",
         "pngjs": "7.0.0"
@@ -17,6 +19,27 @@
         "node": ">=22.19.0"
       }
     },
+    "node_modules/@axe-core/playwright": {
+      "version": "4.13.0",
+      "resolved": "https://registry.npmjs.org/@axe-core/playwright/-/playwright-4.13.0.tgz",
+      "integrity": "sha512-6YLx+kxXu5GJceG4ozFg+33a2EMTdjYwWGloJ3sb9Kta5pp+ZNS53uxGVog5JetIY8s++P5UrtX+cri+u0VAVg==",
+      "license": "MPL-2.0",
+      "dependencies": {
+        "axe-core": "~4.13.0"
+      },
+      "peerDependencies": {
+        "playwright-core": ">= 1.0.0"
+      }
+    },
+    "node_modules/axe-core": {
+      "version": "4.13.0",
+      "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.13.0.tgz",
+      "integrity": "sha512-UzGt8zg7Ny8djbYMhxl2zuEevVa7r2gJjYY5Lwr1xM7+XU2nd6CkIWFTVcCIbAP63vSz71NaVyyuSk9lHKcy0A==",
+      "license": "MPL-2.0",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/fsevents": {
       "version": "2.3.2",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",

package/browser-runtime/package.json

@@ -5,6 +5,8 @@
   "description": "Pinned local browser runtime managed by the SpecPi installer",
   "license": "MIT",
   "dependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "axe-core": "4.13.0",
     "pixelmatch": "7.2.0",
     "playwright": "1.62.1",
     "pngjs": "7.0.0"

package/docs/browser-testing.md

@@ -1,5 +1,17 @@
 # Browser application testing
 
+## Accessibility
+
+`browser_accessibility` scans the already open isolated page using `@axe-core/playwright` and axe-core 4.13.0. Open the page, perform the relevant interaction, wait for the intended visible state, scan, repair and repeat the same scan. It does not launch a blank browser. Continue keyboard, focus and functional checks; automated results are not certification.
+
+Optional input: `include` (CSS selector matching exactly one region), `profile` (`wcag22aa`, the default, or `best-practice` to add those checks), `maxFindings` (default 50, maximum 100 per category) and `timeoutMs` (default 15000, 1000–30000 including queueing). The WCAG profile uses `wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa` and `wcag22aa`. There are no custom scripts/checks, rule suppressions or exclusion lists. Invalid or ambiguous scope fails without broadening the scan.
+
+Results separate violations and incomplete checks, identify profile/tags, scan ID/timestamps, sanitized location and viewport, and return total counts plus explicit truncation within 24 KiB. Navigation invalidates the scan. Dynamic content is not an atomic snapshot; inaccessible frames and closed shadow roots can limit coverage. No raw HTML/check payloads or automatic scan files are retained, but selectors/paths can contain sensitive data and normal results may remain in Pi history. Cancellation uses the existing browser teardown/recovery path.
+
+The managed browser lock includes the scanner. Run `specpi update` without browser/package skip flags to provision it. Missing scanner packages affect accessibility availability; existing screenshots and browser interactions can still work. Installer/doctor extend their offline browser smoke with a known unnamed button and a corrected control, without changing the historical wishlist validator's default smoke. Real Chromium tests exercise label, contrast, ARIA and repaired dynamic states at desktop/tablet/mobile sizes.
+
+The offline fixtures also verify unnamed controls in a same-origin iframe and an open shadow root. The closed-root control is not reported and remains an explicit coverage limitation; cross-origin frame coverage is not qualified by these fixtures. Queue expiry and cancellation discard the browser, and reopening restores scanning. These seeded-page results do not establish coverage of arbitrary applications or replace keyboard and assistive-technology review.
+
 ## Agent workflow
 
 1. `browser_open` opens an HTTP(S) page in isolated Chromium; `browser_snapshot` exposes bounded rendered text and namespaced control references.
@@ -47,7 +59,7 @@ npm run check:pi-package
 
 ### Scoped types
 
-`tsconfig.browser.json` checks exactly `extensions/browser/index.ts`, `diagnostics.ts`, `interactions.ts`, `lifecycle.ts`, and the `core.d.mts` boundary, with strict checking and no emit. It uses real pinned Pi, TypeBox, Playwright and Node declaration packages from development dependencies. Browser runtime imports remain lazy; Playwright imports in the extension are type-only. The `.mjs` image/runtime helper has narrow declarations backed by existing helper/runtime tests and an export-inventory regression; its JavaScript implementation is **not** fully type-checked. `skipLibCheck` skips third-party declarations, not first-party browser implementation errors. Other extensions remain syntax-checked, not advertised as type-checked. A negative fixture proves invalid key and Playwright API argument types fail without generated JavaScript.
+`tsconfig.browser.json` checks browser `index.ts`, `accessibility.ts`, `diagnostics.ts`, `interactions.ts` and `lifecycle.ts`, plus the background and structural registration files and their narrow declaration boundaries, with strict checking and no emit. It uses real pinned Pi, TypeBox, Playwright and Node declarations. Browser runtime imports remain lazy; Playwright imports in the extension are type-only. The `.mjs` implementations have focused runtime tests and are **not** fully type-checked. `skipLibCheck` skips third-party declarations, not the selected first-party implementations. Other extensions remain syntax-checked, not advertised as type-checked. A negative fixture proves invalid key and Playwright API argument types fail without generated JavaScript.
 
 ### Rendered site
 

package/docs/structural-search.md

@@ -0,0 +1,40 @@
+# Structural search
+
+`structural_search` is an opt-in, read-only ast-grep 0.45.3 tool. It matches code structures across formatting changes. It does not resolve types/references, edit code or replace literal search for comments, strings and filenames.
+
+Enable it through the installer, then restart Pi:
+
+```sh
+specpi plan --structural-search=on
+specpi update --structural-search=on
+```
+
+For a fresh installation use `install`. `--yes` confirms installation but does not opt into structural search by itself. Omission preserves the existing choice. `--skip-package-install` and `--skip-tool-install` skip acquisition without disabling an existing runtime. Direct `pi install npm:specpi` does not provision the runtime; use the SpecPi installer for setup.
+
+```json
+{
+    "language": "typescript",
+    "pattern": "pi.registerTool($OPTIONS)",
+    "paths": ["extensions/browser/index.ts"],
+    "maxResults": 50,
+    "timeoutMs": 10000
+}
+```
+
+JavaScript (`.js`, `.mjs`, `.cjs`), JSX, TypeScript (`.ts`, `.mts`, `.cts`), TSX and Python are supported. Select explicit relative files under the active working root, using ordinary discovery tools first. Directories, globs, custom grammars/configuration and rewriting are unavailable. A pattern with multiple independent statements may be rejected; syntax recovery can also accept malformed patterns, so inspect matches and retain project-native checks.
+
+Limits are 200 files, 8 MiB of selected source in aggregate, 1 MiB per file, 6 KiB encoded path selection, 4 KiB pattern, 100 returned matches, 512 bytes per snippet and 24 KiB per result. Selection metadata must fit half the result budget; narrow long path lists when necessary. The default deadline is 10 seconds, configurable from 1–30 seconds including queueing and approval. There is one active parser and at most one queued request. Raw parser output is capped at 2 MiB, diagnostics at 8 KiB per call. Cleanup may take one additional second; unconfirmed cleanup blocks further parser starts until resolved and the extension is reloaded.
+
+Results include source digests, searched/requested counts, ranges, engine version and explicit truncation. Lines and UTF-8 byte columns are one-based; end positions are exclusive. Columns are calculated from original source bytes, not the CLI's character-oriented display columns. A partial, timed-out, cancelled or unavailable result is not proof that other matches do not exist. Captured on-disk bytes exclude unsaved editor buffers and are not an atomic filesystem snapshot.
+
+The parser receives selected source over stdin, a fixed argument list, a neutral configuration and a minimal environment. It runs from private temporary scratch containing configuration only. Source and results are not written to that scratch. The existing selected-source boundary rejects private namespaces, credentials, path escapes, links and hardlinks. It cannot detect secrets embedded in ordinary source. Returned snippets can persist in normal Pi conversation history.
+
+Guard and Off permit these bounded reads; Strict asks for the exact call. The approval receives the operation cancellation signal and remaining timeout. Terminal prompts dismiss on cancellation; Pi 0.84.4 releases cancelled RPC approvals server-side but sends no remote dismissal event, so clients may display them until the forwarded timeout expires. Late answers cannot authorize the cancelled call. Locked or ambiguous Guard state denies. If Guard is absent, the same source/input limits remain. Policy, root and enablement are rechecked before parsing. A denial must not be retried through a different tool. Existing read-only workers do not gain structural-search access.
+
+Enablement lives in `<agentDir>/specpi/tool-integrations.json`. The installer preserves unrelated fields, backs up the owned file before changes and rolls it back on failure. Serialized configuration must also fit the 16 KiB reader limit: the installer uses compact JSON when needed and rejects output that still exceeds the limit before changing configuration or runtimes. If that file becomes unparseable, `plan` reports it and continues without mutating anything, while `install` and `update` stop and name the file; repair or remove it, or pass `--structural-search=on` or `--structural-search=off` to rewrite it from the backed-up original. A configuration that is a link or not a bounded regular file remains a hard failure that no selection rewrites. The private runtime has an exact npm lockfile, script-free acquisition and binary/full-tree checksums; no global PATH entry is added. Doctor checks integrity and runs an offline fixture smoke. The initial native platforms are Windows x64, macOS x64/arm64 and Linux glibc x64; other combinations report unavailable.
+
+Disable with `specpi update --structural-search=off`, then restart Pi. Intact owned runtimes are removed transactionally. Modified/unverified runtimes are preserved with a warning; replacement preserves them outside the active runtime path. The tree check covers file contents, paths, directories, permissions and link targets without traversing links, and is repeated before retired-tree deletion. Older ownership markers without a tree checksum are unverified and preserved. Rollback quarantines the new runtime and restores the prior directory before recursive cleanup; a cleanup failure reports the retained quarantine path. Uninstall preserves enablement configuration and user evidence. Trusted native executables still run with the user's permissions; these controls are not an OS sandbox.
+
+Development verification uses `npm run setup:structural` followed by `npm run test:structural`. This installs only the locked native test runtime in `.specpi-test/structural-runtime/`. Installer tests use disposable Pi directories and skip external acquisition.
+
+Six synthetic lookup trials on Windows x64 / Node 24.18.0 on September 9, 2026 covered call sites, constructors, filesystem calls, JSX/TSX components and Python calls. Each fixture contained two valid structures with different formatting plus one comment/string decoy. All 12 expected matches were found with no false positives; each response was 669–707 bytes and took 32–48 ms in that single run. A simple fixed-string `rg` query per fixture found six valid matches, missed six formatting variants and returned six decoys (37–85 bytes, 24–33 ms per query). This demonstrates the intended syntax-sensitive use case, not superiority over carefully constructed regex/manual inspection or measured agent productivity. Literal search remains faster and smaller in these trials; structural search remains opt-in.

package/extensions/browser/accessibility.ts

@@ -0,0 +1,155 @@
+import { createRequire } from "node:module";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import type { Page } from "playwright";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { sanitizeDiagnostic, sanitizeUrl } from "./diagnostics.ts";
+
+export const ACCESSIBILITY_VERSION = "4.13.0";
+export const MAX_ACCESSIBILITY_BYTES = 24 * 1024;
+export class AccessibilityError extends Error {}
+const tags = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];
+export const AccessibilityParams = Type.Object(
+    {
+        include: Type.Optional(Type.String({ minLength: 1, maxLength: 1000 })),
+        profile: Type.Optional(StringEnum(["wcag22aa", "best-practice"] as const)),
+        maxFindings: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+        timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, maximum: 30000 })),
+    },
+    { additionalProperties: false },
+);
+type Finding = {
+    id: string;
+    impact?: string | null;
+    help: string;
+    helpUrl: string;
+    nodes: Array<{ target: unknown }>;
+};
+type Analysis = {
+    testEngine: { version: string };
+    violations: Finding[];
+    incomplete: Finding[];
+    passes: unknown[];
+    inapplicable: unknown[];
+};
+type Options = { include?: string; profile?: "wcag22aa" | "best-practice"; maxFindings?: number };
+type Builder = { withTags(tags: string[]): Builder; include(selector: string): Builder; analyze(): Promise<Analysis> };
+
+export function reduceAccessibility(raw: Analysis, maxFindings = 50) {
+    const severity = ["critical", "serious", "moderate", "minor", "unknown"];
+    // Rank an unrecognized impact as "unknown" so ordering matches the value that is reported.
+    const rank = (impact?: string | null) => {
+        const index = severity.indexOf(impact ?? "unknown");
+
+        return index === -1 ? severity.indexOf("unknown") : index;
+    };
+
+    const reduce = (findings: Finding[]) =>
+        [...findings]
+            .sort((a, b) => rank(a.impact) - rank(b.impact) || a.id.localeCompare(b.id))
+            .slice(0, maxFindings)
+            .map((finding) => ({
+                rule: sanitizeDiagnostic(finding.id, 100),
+                impact: severity.includes(finding.impact ?? "") ? finding.impact : "unknown",
+                guidance: sanitizeDiagnostic(finding.help, 300),
+                helpUrl: sanitizeUrl(finding.helpUrl),
+                affectedNodes: finding.nodes.length,
+                targets: finding.nodes.slice(0, 3).map((node) => sanitizeDiagnostic(JSON.stringify(node.target), 200)),
+            }));
+    const result = {
+        violations: reduce(raw.violations),
+        incomplete: reduce(raw.incomplete),
+        totals: {
+            violations: raw.violations.length,
+            incomplete: raw.incomplete.length,
+            passes: raw.passes.length,
+            inapplicable: raw.inapplicable.length,
+        },
+        truncated: false,
+    };
+    // Reserve space for page/state metadata. Keep both categories represented.
+    while (Buffer.byteLength(JSON.stringify(result)) > MAX_ACCESSIBILITY_BYTES - 4096) {
+        const list = result.violations.length >= result.incomplete.length ? result.violations : result.incomplete;
+        if (!list.length) {
+            break;
+        }
+
+        list.pop();
+    }
+
+    result.truncated =
+        result.violations.length < raw.violations.length || result.incomplete.length < raw.incomplete.length;
+
+    return result;
+}
+
+export async function scanAccessibility(page: Page, runtimeDir: string, options: Options = {}) {
+    let BuilderClass: new (options: { page: Page }) => Builder;
+    try {
+        const require = createRequire(path.join(runtimeDir, "package.json"));
+        if (
+            require("axe-core/package.json").version !== ACCESSIBILITY_VERSION ||
+            JSON.parse(
+                fs.readFileSync(
+                    path.join(runtimeDir, "node_modules", "@axe-core", "playwright", "package.json"),
+                    "utf8",
+                ),
+            ).version !== ACCESSIBILITY_VERSION
+        ) {
+            throw new Error("Unexpected scanner version");
+        }
+
+        BuilderClass = require("@axe-core/playwright").default;
+    } catch {
+        throw new AccessibilityError(
+            "Accessibility scanner unavailable. Run specpi update without --skip-browser-install.",
+        );
+    }
+
+    const scanId = crypto.randomUUID();
+    let navigated = false;
+    const onNavigation = () => {
+        navigated = true;
+    };
+
+    page.on("framenavigated", onNavigation);
+    const startedAt = new Date().toISOString();
+    try {
+        if (options.include && (await page.locator(`css=${options.include}`).count()) !== 1) {
+            throw new AccessibilityError("Accessibility scope must match exactly one region.");
+        }
+
+        const effectiveTags = options.profile === "best-practice" ? [...tags, "best-practice"] : [...tags];
+        const builder = new BuilderClass({ page }).withTags(effectiveTags);
+        if (options.include) {
+            builder.include(options.include);
+        }
+
+        const result = await builder.analyze();
+        if (navigated || page.isClosed()) {
+            throw new AccessibilityError(
+                "Accessibility scan became stale during navigation. Scan the current state again.",
+            );
+        }
+
+        return {
+            status: "complete",
+            scanId,
+            scannerVersion: result.testEngine.version,
+            url: sanitizeUrl(page.url()),
+            viewport: page.viewportSize(),
+            scope: options.include ? sanitizeDiagnostic(options.include, 500) : "page",
+            profile: options.profile ?? "wcag22aa",
+            tags: effectiveTags,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            ...reduceAccessibility(result, options.maxFindings),
+            limitations:
+                "Automated checks of the observed DOM state only; dynamic changes, inaccessible frames and closed shadow roots may limit coverage. Incomplete checks need review. A clean result is not accessibility certification.",
+        };
+    } finally {
+        page.off("framenavigated", onNavigation);
+    }
+}

package/extensions/browser/index.ts

@@ -6,6 +6,7 @@ import type { Browser, BrowserContext, Page } from "playwright";
 import { Check } from "typebox/value";
 import { BrowserDiagnostics, DIAGNOSTIC_CATEGORIES } from "./diagnostics.ts";
 import { BrowserCleanupError, settleBrowserCleanup } from "./lifecycle.ts";
+import { AccessibilityError, AccessibilityParams, scanAccessibility } from "./accessibility.ts";
 import {
     PressParams,
     SelectionParams,
@@ -417,9 +418,12 @@ export default function browserExtension(pi: ExtensionAPI) {
                     throw new Error("Invalid browser tool parameters.");
                 }
 
-                const bounded = ["browser_press", "browser_select_option", "browser_wait_for"].includes(
-                    definition.name,
-                );
+                const bounded = [
+                    "browser_press",
+                    "browser_select_option",
+                    "browser_wait_for",
+                    "browser_accessibility",
+                ].includes(definition.name);
                 const controller = new AbortController();
                 const originalSignal = args[2];
                 const signal = AbortSignal.any([
@@ -430,7 +434,10 @@ export default function browserExtension(pi: ExtensionAPI) {
                 const timer = bounded
                     ? setTimeout(
                           () => controller.abort(),
-                          interactionTimeout((args[1] as { timeoutMs?: number }).timeoutMs),
+                          interactionTimeout(
+                              (args[1] as { timeoutMs?: number }).timeoutMs ??
+                                  (definition.name === "browser_accessibility" ? 15000 : undefined),
+                          ),
                       )
                     : undefined;
                 try {
@@ -506,6 +513,35 @@ export default function browserExtension(pi: ExtensionAPI) {
         }
     }
 
+    register({
+        name: "browser_accessibility",
+        label: "Browser Accessibility",
+        description:
+            "Check the current isolated browser page for automated accessibility violations and incomplete checks. Open and interact with the page first; this does not certify accessibility.",
+        parameters: AccessibilityParams,
+        async execute(_id, params, signal) {
+            if (!state.page || state.page.isClosed()) {
+                throw new Error("Open a page with browser_open before running accessibility checks.");
+            }
+
+            try {
+                const result = await cancellable(() => scanAccessibility(state.page!, runtimeDir, params), signal);
+
+                return { content: [{ type: "text", text: JSON.stringify(result) }], details: {} };
+            } catch (error) {
+                if (error instanceof BrowserCleanupError || signal?.aborted) {
+                    throw error;
+                }
+
+                if (error instanceof AccessibilityError) {
+                    throw error;
+                }
+
+                throw new Error("Accessibility analysis failed. Check the page, scope and runtime, then retry.");
+            }
+        },
+    });
+
     register({
         name: "browser_open",
         label: "Browser Open",

package/extensions/browser/smoke.mjs

@@ -2,6 +2,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { createRequire } from "node:module";
 import { comparePngBuffers, loadBrowserRuntime } from "./core.mjs";
 
 const runtimeDir = process.argv[2];
@@ -40,7 +41,34 @@ try {
         throw new Error("Changed browser visual comparison was not detected.");
     }
 
+    if (process.argv.includes("--accessibility")) {
+        const require = createRequire(path.join(path.resolve(runtimeDir), "package.json"));
+        const AxeBuilder = require("@axe-core/playwright").default;
+        if (require("axe-core/package.json").version !== "4.13.0") {
+            throw new Error("Accessibility runtime version mismatch.");
+        }
+
+        await page.setContent(
+            '<!doctype html><html lang="en"><title>Fixture</title><main><button></button></main></html>',
+        );
+        const broken = await new AxeBuilder({ page }).withTags(["wcag2a"]).analyze();
+        if (!broken.violations.some((finding) => finding.id === "button-name")) {
+            throw new Error("Accessibility smoke missed an unnamed button.");
+        }
+
+        await page.setContent(
+            '<!doctype html><html lang="en"><title>Fixture</title><main><button>Save</button></main></html>',
+        );
+        const fixed = await new AxeBuilder({ page }).withTags(["wcag2a"]).analyze();
+        if (fixed.violations.some((finding) => finding.id === "button-name")) {
+            throw new Error("Accessibility smoke did not recognize the repair.");
+        }
+    }
+
     console.log(`Browser smoke passed: ${baseline.length} byte PNG; exact and changed visual comparisons verified`);
+    if (process.argv.includes("--accessibility")) {
+        console.log("ACCESSIBILITY_SMOKE=passed");
+    }
 } finally {
     await browser?.close().catch(() => {});
     await fs.rm(tempDir, { recursive: true, force: true });

package/extensions/command-guard/index.ts

@@ -185,7 +185,20 @@ export default function registerCommandGuard(
     state.onModeChanged = () => pi.events?.emit("specpi:guard-policy-changed", { reason: "guard policy changed" });
     let backgroundSubscription: (() => void) | undefined;
     let guardStateSubscription: (() => void) | undefined;
+    let structuralSubscription: (() => void) | undefined;
     const subscribeGuardState = () => {
+        structuralSubscription ??= pi.events?.on?.("specpi:structural-admission", (request: any) => {
+            request?.reply?.({
+                mode: state.mode,
+                generation: state.generation,
+                action:
+                    !state.ready || state.startupFailed || state.mode === "locked"
+                        ? "deny"
+                        : state.mode === "strict"
+                          ? "ask"
+                          : "allow",
+            });
+        });
         if (!backgroundSubscription) {
             backgroundSubscription = pi.events?.on?.("specpi:background-admission", (request: any) => {
                 if (typeof request?.reply !== "function") {
@@ -240,6 +253,23 @@ export default function registerCommandGuard(
 
     subscribeGuardState();
     const backgroundSource = fileURLToPath(new URL("../background-tasks/index.ts", import.meta.url));
+    const structuralSource = fileURLToPath(new URL("../structural-search/index.ts", import.meta.url));
+    const ownsStructuralTool = (name: string): boolean => {
+        if (name !== "structural_search") {
+            return false;
+        }
+
+        const matches = pi.getAllTools?.().filter((tool) => tool.name === name) ?? [];
+        const source = matches.length === 1 ? matches[0].sourceInfo?.path : undefined;
+        if (typeof source !== "string" || !path.isAbsolute(source)) {
+            return false;
+        }
+
+        return process.platform === "win32"
+            ? path.resolve(source).toLowerCase() === path.resolve(structuralSource).toLowerCase()
+            : path.resolve(source) === path.resolve(structuralSource);
+    };
+
     const ownsBackgroundTool = (name: string): boolean => {
         if (!["background_start", "background_list", "background_logs", "background_stop"].includes(name)) {
             return false;
@@ -352,6 +382,8 @@ export default function registerCommandGuard(
         reset();
         backgroundSubscription?.();
         backgroundSubscription = undefined;
+        structuralSubscription?.();
+        structuralSubscription = undefined;
         if (typeof guardStateSubscription === "function") {
             guardStateSubscription();
             guardStateSubscription = undefined;
@@ -513,7 +545,7 @@ export default function registerCommandGuard(
             // Check Pi's current registration provenance, not a tool name or cached handshake.
             // Genuine background tools validate again in execute; cleanup remains usable under a lock.
             // A missing or replaced registration retains normal Strict/locked enforcement.
-            if (ownsBackgroundTool(name)) {
+            if (ownsBackgroundTool(name) || ownsStructuralTool(name)) {
                 return;
             }
 

package/extensions/delegation/snapshot.mjs

@@ -457,6 +457,26 @@ export function createSnapshot(root, paths, options = {}) {
 
     return Object.freeze({
         sources,
+        // Parent-only parser seam. Worker brokers still expose only list/read/search.
+        // Read through the same bindings and require the originally captured digest.
+        async withSourceBytes(id, consume) {
+            ensureOpen();
+            const record = byId.get(id);
+            if (!record || typeof consume !== "function") {
+                fail("byte reader rejected");
+            }
+
+            const bytes = readBoundFile(canonicalRoot, record.relative, record.original, MAX_BYTES);
+            try {
+                if (hash(bytes) !== record.digest) {
+                    fail("source changed");
+                }
+
+                return await consume(bytes);
+            } finally {
+                bytes.fill(0);
+            }
+        },
         read(id, startLine = 1, maxLines = 200) {
             ensureOpen();
             const record = byId.get(id);

package/extensions/structural-search/config.d.mts

@@ -0,0 +1,7 @@
+export declare function integrationsFile(agentDir: string): string;
+export declare function serializeIntegrations(value: unknown, file: string): string;
+export declare function readIntegrations(agentDir: string): {
+    schema: 1;
+    structuralSearch: { enabled: boolean };
+    [key: string]: unknown;
+};