specpi 0.10.0

package/SECURITY_MODEL.md

@@ -0,0 +1,107 @@
+# SpecPi Security Model
+
+This document describes SpecPi's architecture-level security assumptions, enforcement boundaries, and residual risks. It complements the public vulnerability-reporting policy in [SECURITY.md](SECURITY.md). Exact third-party versions and licenses are maintained in [THIRD_PARTY.md](THIRD_PARTY.md).
+
+## Threat model
+
+### Assets
+
+SpecPi aims to preserve:
+
+- user files, Git work, and host stability;
+- Pi configuration, credentials, sessions, history, and trust decisions;
+- SpecPi-managed files, backups, manifests, checksums, and enforcement code;
+- local wishlist evidence, experiment metadata and patches, session-branch workflow records, and browser artifacts;
+- the confidentiality and integrity of reports, prompts, commands, and paths that SpecPi does not need to persist.
+
+### Untrusted inputs and actors
+
+SpecPi expects model-generated tool calls, repository content, web content, downloaded package metadata, and browser page output to be potentially hostile or malformed. A dependency, extension, project configuration, approved script, or direct user command is more powerful than ordinary model output and may cross boundaries SpecPi cannot enforce.
+
+### Trusted components
+
+SpecPi ultimately trusts the invoking user and operating-system account, the Pi runtime, explicitly installed packages and extensions, project and user configuration treated by Pi as trusted, package registries and upstream publishers used during installation, and commands or scripts the user approves. These are trust assumptions, not claims that every component is independently verified.
+
+### Security goals
+
+SpecPi seeks to make installation explicit and reversible, avoid private Pi state it does not need, preserve unrelated configuration, prevent exact-provider policy from silently weakening, block confirmed catastrophic model operations at supported tool seams, keep local improvement evidence local, and isolate browser QA from the user's personal browser profile.
+
+### Non-goals
+
+SpecPi is not an operating-system sandbox and does not claim to contain a compromised host, user account, Pi runtime, trusted extension, approved script, dependency, custom tool, or already-running process. It cannot prevent every credential read, data transfer, destructive operation, prompt-injection effect, time-of-check/time-of-use race, or action outside its documented interception points. Use operating-system permissions, least privilege, protected credentials, containers, or virtual machines when stronger isolation is required.
+
+## Installer and managed state
+
+SpecPi is configuration and executable extension code for Pi and runs with the invoking user's permissions. Installing the public npm package adds the `specpi` CLI to npm-managed state but does not run SpecPi installation, download external tools, or mutate Pi state; the package defines no npm install lifecycle script. The installer prints a plan and requires confirmation unless `--yes` is supplied. `plan` is non-mutating. Installation and update merge documented settings leaves, preserve unrelated packages and configuration, and modify AGENTS and shell files only inside SpecPi marker blocks.
+
+The canonical npm route is an installer-CLI distribution. Direct `pi install npm:specpi` loads packaged extensions, skills, and themes but bypasses the managed installer, so it does not provide managed instructions, supporting packages, browser runtime acquisition, optional tools, shell integration, backups, or ownership records. Pi-bundled runtime modules are optional peers and are not copied into the tarball. Release automation validates the packed artifact, requires a matching immutable version and release tag, publishes only from a protected environment, and requests npm provenance through short-lived GitHub OIDC credentials.
+
+Before replacing managed resources, SpecPi creates bounded backups, stages writes, promotes files atomically where supported, records checksums and ownership in a private manifest, and rolls configuration files back when a core installation step fails. It does not persistently copy complete Pi settings or shell startup files. Symlink, lock, ownership, and malformed-state checks fail closed where the installer cannot prove a supported mutation.
+
+SpecPi never reads Pi authentication files, provider credentials, sessions, history, missions, or trust decisions as part of installation or local improvement reporting. It does not commit, push, publish, or create remote resources.
+
+When Pi is missing, a confirmed bootstrap can install the pinned Pi package globally with lifecycle scripts disabled. Existing compatible Pi installations are preserved. Pi packages are installed through Pi's package mechanism, and the browser runtime is installed from SpecPi's reviewed lockfile before atomic promotion and launch smoke testing. SpecPi does not install Playwright operating-system dependencies.
+
+Global package installations, upstream package-manager effects, downloaded caches, and optional tools are external system state. A later SpecPi failure does not necessarily remove them, and uninstall preserves them. The optional DonSeTch package performs its own binary acquisition and remains outside SpecPi's rollback boundary. The canonical inventory is in [THIRD_PARTY.md](THIRD_PARTY.md).
+
+## Command Guard
+
+Command Guard is a pre-execution policy layer for model-initiated Pi tool calls. It covers Pi's documented `bash`, `powershell`, `read`, `write`, and `edit` tools. Other extensions, custom or MCP tools, direct user `!command` and `!!command` escapes, approved scripts, and process execution outside these seams are not contained.
+
+Interactive top-level sessions choose one session-only mode:
+
+- **Guard** denies confirmed host-wide catastrophe and enforcement tampering, asks before destructive Git operations, and stays quiet for determinate non-catastrophic work.
+- **Strict** additionally asks about mutation, execution, recognized sensitive reads, elevation, network activity, and uncatalogued tools.
+- **Off** is a twice-confirmed direct-user escape hatch limited to the current session.
+
+Guard is not general change control. Determinate calls may delete project or user data, publish, deploy, install software, transfer data, change services, or reach outside the workspace. Git work destruction is the deliberate broader approval boundary because it can discard or rewrite work that local rollback cannot recover.
+
+The guard analyzes Bash/POSIX and cmd command structure conservatively and uses installed PowerShell parser APIs without evaluating the command. It resolves protected paths using lexical and canonical information where available and carries working-directory changes through supported command sequences. Confirmed catastrophic payloads remain immutable denials. Analysis, parser, payload, or path uncertainty asks for approval when interactive UI is available and denies without UI; uncertainty cannot silently approve a call.
+
+Approvals are exact-call and session-scoped. Every call is reanalyzed before an approval can satisfy it, and approval never overrides a critical denial. Only a structurally proven lock-worthy critical mutation locks subsequent execution; parser uncertainty, syntax mismatch, fallback classification, and refused reads deny the current call without permanently stranding the session. Session lifecycle changes and guard-mode changes clear transient approval state.
+
+The guard keeps mode, lock, counters, parser cache, and approval hashes only in memory. It does not persist or upload raw commands, arguments, paths, working directories, parser output, prompts, or approvals. Display excerpts are bounded and redact common secret-bearing forms.
+
+Static analysis cannot resolve every alias, generated command, script body, plugin, encoding, runtime expansion, symlink race, or interpreter behavior. Recognized private-path reads receive narrow protection, but arbitrary scripts or shell syntax can still read credentials. An allowed or approved command runs with the user's full permissions. `specpi doctor` verifies installed checksums and deterministic policy smoke behavior, not universal command safety.
+
+## Local improvement state
+
+Capability-gap collection is disabled until the user makes an explicit local on/off choice. When enabled, SpecPi stores bounded sanitized summaries and salted hashes used to measure distinct tasks, sessions, and projects. It does not read prompts, source files, sessions, history, credentials, provider authentication, or trust decisions to construct reports, and it never uploads wishlist state.
+
+Improvement journals may contain sanitized acceptance evidence, verification gates, repository-relative changed-file names, version data, and bounded reopen context. Raw source content and complete settings snapshots are not part of those records.
+
+Sanitization is defense in depth, not a guarantee that every plain-language identity or sensitive fact can be detected. Users should keep summaries general and inspect reports and local issue drafts before sharing them.
+
+Wishlist evidence does not authorize implementation. `/harness-improvement` requires one explicit human selection, and retirement requires the repository check plus supported closed validators. Failed verification leaves the item selected. Validator identifiers resolve through a closed allowlist rather than being interpreted as commands.
+
+Wishlist state, archives, and browser artifacts can survive uninstall so uninstall does not silently destroy user evidence. Stop Pi and review retained state before manual removal. Archive and reset operations use checksummed snapshots and recoverable transactions; unverified abandoned locks are not reclaimed automatically.
+
+## Workflow controls
+
+The Scope Drift Monitor is task-scope governance, not a filesystem sandbox. It preflights direct `write` and `edit` paths and compares bounded Git worktree snapshots around tools. Shell commands, scripts, custom tools, concurrent processes, very large dirty sets, changes made and reverted within one call, filesystem timestamp behavior on oversized files, and non-Git sessions can reduce or bypass its observations. The snapshot a tool finishes on becomes the baseline for the next tool, so a change made outside any tool call is attributed to whichever tool runs next rather than going unseen; only `read`, which cannot mutate the worktree, is skipped. Interactive users choose deny, allow-once, or scope expansion for direct out-of-scope calls. Headless and post-hoc findings remain advisory and pending rather than fabricating human consent. `/scope accept` acknowledges a finding without widening the contract, `/scope add` is the only verb that widens it, and `/scope recheck` clears snapshot uncertainty only as a deliberate human act. Git reports paths verbatim under `-z`, so a filename may contain newlines or other control characters; every path SpecPi reports back through the system prompt, tool results, or the UI is percent-escaped first so a hostile filename cannot forge a line of guidance. Scope entries, changed relative paths, and pending findings are copied into the active Pi session branch so an appended record cannot be rewritten later; raw tool input, command text, output, and source are not copied into workflow state.
+
+Guided Experiment Worktrees use explicit extension commands and fixed Git argv, so their internal `pi.exec` calls are outside Command Guard's model-tool interception. SpecPi therefore requires its own confirmations before creation, overwrite, and removal, revalidates the registered worktree and common Git directory before destructive removal, and never automatically reclaims an abandoned registry lock or missing worktree. A directory Git no longer tracks as a worktree can only have its registry record released; SpecPi leaves those files in place for the human rather than deleting them. Recovery re-reads `git worktree list` and revalidates the record's repository inside the registry lock immediately before it mutates state, so an external Git operation performed while a recovery prompt is open cannot cause a stale answer to drop a live record or adopt a replaced directory. Experiments are detached from a recorded `HEAD`; dirty base changes stay in place and are excluded. Patch export uses a temporary Git index and can invoke repository-configured Git clean filters through `git add -A`; trusted repository configuration remains part of the trust boundary. Status and export measure from the recorded base commit rather than the worktree's current HEAD, so work the human commits inside an experiment stays visible to status, reaches the patch, and triggers the discard confirmation. Git writes the patch file itself so its bytes are preserved exactly, including text that is not valid UTF-8. A patch output that appears after the existence check is claimed exclusively rather than overwritten, so an unapproved replacement fails closed. Ignored files are outside both Git status and `git add -A`, so they never appear in a patch; SpecPi counts and names them before an export or a discard, but a discarded ignored file is not recoverable. SpecPi does not launch a writer, create a branch or commit, merge, apply a patch, or alter remotes.
+
+The private experiment registry stores canonical repository and worktree paths, base commit IDs, bounded user-authored hypotheses, acceptance checks, non-goals, lifecycle state, and timestamps under `<agent-dir>/specpi/experiments`. Exported patches contain source changes by design and may be sensitive. SpecPi requests `0700` directories and `0600` files, but Windows ignores POSIX modes, so on that platform these artifacts are protected by the user profile's own access control rather than by the requested mode. Experiment metadata and patches are user evidence and survive uninstall unless explicitly removed. Registry writes are atomic and ownership-locked, but a crash, filesystem failure, external `git worktree` operation, malicious Git configuration, symlink race, or manual state edit can require `/experiment recover` or direct human repair.
+
+Completion Challenge activation and structured results are bounded to the current Pi session branch. An activation that the agent turn ends without answering expires with that turn, so its instruction never carries into later work. An expiry is recorded distinctly from `/challenge clear`, so an unanswered challenge never retires the last completed card. The extension records changed relative paths, active scope summaries, matching experiment acceptance metadata, and tool failure counts observed during the task; it does not scan unrelated historical sessions, prompts, source, or raw tool output. A deterministic gate rejects a ready verdict when its own submission reports unresolved requirements, contradictions, validation gaps, or pending scope drift. When the change snapshot was indeterminate the facts the review received may be incomplete, so a ready verdict must disclose that residual risk; the condition is permanent outside a Git worktree, so it is required disclosure rather than an unreachable verdict. The underlying analysis is still produced by the same model and context, so it can omit a requirement, misunderstand evidence, or rationalize a false positive. The card is a review aid, not independent validation, authorization, or a completion lock.
+
+## Browser isolation
+
+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.
+
+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.
+
+## Website and automation
+
+The GitHub Pages workflow publishes the checked-in `site/` directory. Its deploy job uses read-only repository contents access plus the Pages and identity-token permissions required for deployment. The local installer does not invoke that workflow or upload local configuration or state.
+
+Repository checks, smoke tests, checksums, closed capability validators, and browser comparisons provide evidence for documented behavior. They reduce regression risk but do not prove the absence of vulnerabilities or establish cryptographic provenance for dependencies and releases.
+
+## Supply-chain assumptions
+
+SpecPi pins reviewed executable package versions and the browser dependency graph. These controls improve repeatability and make version changes reviewable. They do not prove that a registry, publisher account, package artifact, downloaded browser, GitHub Action tag, or invoking host is uncompromised. Releases are not described as reproducible or cryptographically signed unless a future release adds and documents those mechanisms.
+
+Users should review tagged source, installation plans, dependency changes, and security advisories; use protected branches and least-privilege automation when maintaining a fork; and upgrade promptly when SpecPi or an upstream project publishes relevant security guidance.

package/THIRD_PARTY.md

@@ -0,0 +1,61 @@
+# Third-party components
+
+When Pi is absent, SpecPi can install the reviewed `@earendil-works/pi-coding-agent@0.84.4` npm package globally after confirmation. The package provides the `pi` executable, is installed with lifecycle scripts disabled, retains its upstream license, and remains external system state after SpecPi uninstall.
+
+SpecPi pins but does not vendor these Pi packages:
+
+- `pi-web-access@0.25.0`
+- `@juicesharp/rpiv-ask-user-question@2.7.1`
+- `@llblab/pi-codex-usage@0.9.3`
+- `@tunnckocore/pi-gpt-fast-mode@0.4.0`
+- `@narumitw/pi-goal@0.54.3`
+
+They retain their own copyright and license terms. Pi downloads them from npm when the installer runs `pi install`. SpecPi does not patch, fork, vendor, or use unsupported deep imports from these packages.
+
+The published `specpi` npm package declares the Pi host runtime modules its extensions import as optional peer dependencies, each at Pi's documented `"*"` range:
+
+- `@earendil-works/pi-coding-agent` — extension API, theme, markdown, and highlighting helpers
+- `@earendil-works/pi-ai` — the `StringEnum` tool-schema helper
+- `@earendil-works/pi-tui` — terminal component, key, and width primitives
+- `typebox` — the unscoped TypeBox package Pi bundles, used for tool input schemas
+
+They retain their own copyright and license terms. SpecPi never vendors, bundles, or installs them; the Pi host supplies them at extension load time through loader aliases. Pi disables peer resolution for managed package installs, so a peer range would not enforce the host version there. Marking the peers optional also keeps an ordinary npm CLI installation from adding a second copy beside or inside SpecPi. The full managed installation enforces its supported Pi floor through the installer's `MIN_PI_VERSION` compatibility check, and the limited direct Pi mode documents the same host prerequisite.
+
+SpecPi also installs these exact browser-runtime packages from the reviewed `browser-runtime/package-lock.json`:
+
+- `playwright@1.62.1` and `playwright-core@1.62.1` — Apache-2.0
+- `pixelmatch@7.2.0` — ISC
+- `pngjs@7.0.0` — MIT
+- optional `fsevents@2.3.2` on macOS — MIT
+
+Playwright downloads its matching Chromium build into SpecPi's private runtime directory. Chromium retains its upstream BSD and third-party component licenses. None of these executables are installed globally.
+
+Repository development uses these exact, project-local formatting and linting packages:
+
+- `prettier@3.9.6` — MIT
+- `eslint@10.9.1` — MIT
+- `@stylistic/eslint-plugin@5.10.0` — MIT
+- `@typescript-eslint/parser@8.68.0` — MIT
+- `typescript@6.0.3` — Apache-2.0
+
+They are development-only dependencies, are not shipped by the SpecPi installer, and enforce the repository's JavaScript and TypeScript readability rules.
+
+The GitHub Pages site vendors the Latin subsets of IBM Plex Sans and IBM Plex Mono. Copyright © 2017 IBM Corp. with Reserved Font Name "Plex". The font files are distributed under the SIL Open Font License 1.1; the required license text is included at `site/fonts/LICENSE.txt`.
+
+The npm release workflow installs `npm@11.19.1` as its pinned publishing client. npm is distributed under the Artistic License 2.0 and runs only on the ephemeral GitHub-hosted release runner.
+
+Repository automation uses these official GitHub Actions. General CI and Pages workflows track the listed major versions; the npm publishing workflow pins exact reviewed commit SHAs so the OIDC job does not execute mutable action tags:
+
+- `actions/checkout@v4`
+- `actions/setup-node@v4`
+- `actions/configure-pages@v5`
+- `actions/upload-pages-artifact@v4`
+- `actions/deploy-pages@v4`
+- `actions/upload-artifact@v4`
+- `actions/download-artifact@v4`
+
+They retain their own copyright and license terms. These actions receive only the permissions declared in their respective workflows.
+
+The optional DonSeTch CLI is distributed under AGPL-3.0-only and is not bundled in this repository. When selected during installation, SpecPi installs `donsetch@3.4.0` globally through npm; that package downloads and verifies its platform binary. The included skill documents how to invoke it.
+
+Git is not bundled and retains its own license. SpecPi's in-house `/files` extension uses Pi's built-in themed renderers and invokes Git directly when repository status or diffs are available.

package/browser-runtime/package-lock.json

@@ -0,0 +1,86 @@
+{
+  "name": "specpi-browser-runtime",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "specpi-browser-runtime",
+      "version": "0.1.0",
+      "license": "MIT",
+      "dependencies": {
+        "pixelmatch": "7.2.0",
+        "playwright": "1.62.1",
+        "pngjs": "7.0.0"
+      },
+      "engines": {
+        "node": ">=22.19.0"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/pixelmatch": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/pixelmatch/-/pixelmatch-7.2.0.tgz",
+      "integrity": "sha512-xhcb4yHu9sM/G7foGzoLtXYcC0zHEaOXXjRKhGup0fw78Nf2Tkiapv4EQyMzrbcmQPsllAI7DbFY2UT7PlI9Pg==",
+      "license": "ISC",
+      "dependencies": {
+        "pngjs": "^7.0.0"
+      },
+      "bin": {
+        "pixelmatch": "bin/pixelmatch"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.62.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.62.1.tgz",
+      "integrity": "sha512-0M+L3LAD8/nm554LOla9Ayx0j0tmFZ0FBcoQ7F1VuVHpM/XpiC8RcDzBQB8W5+hA8L22THxELzeF+2WcUzvcLg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.62.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.62.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.62.1.tgz",
+      "integrity": "sha512-wPYSwEBJY9GHraISXqyqtx0na0LpO3XEX7jNDhntbex7tzUS7kLnZsOlFruFJB4Hi/rhDMjXGqHewDZ68nYZVw==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/pngjs": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-7.0.0.tgz",
+      "integrity": "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.19.0"
+      }
+    }
+  }
+}

package/browser-runtime/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "specpi-browser-runtime",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Pinned local browser runtime managed by the SpecPi installer",
+  "license": "MIT",
+  "dependencies": {
+    "pixelmatch": "7.2.0",
+    "playwright": "1.62.1",
+    "pngjs": "7.0.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/extensions/browser/core.mjs

@@ -0,0 +1,306 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const VIEWPORT_PRESETS = Object.freeze({
+    desktop: Object.freeze({ width: 1440, height: 900 }),
+    tablet: Object.freeze({ width: 834, height: 1112 }),
+    mobile: Object.freeze({ width: 390, height: 844 }),
+});
+
+export const DEFAULT_DIFF_THRESHOLD = 0.1;
+export const DEFAULT_MAX_DIFF_PIXEL_RATIO = 0.01;
+export const MAX_VIEWPORT_PIXELS = 8_000_000;
+export const MAX_CAPTURE_PIXELS = 8_000_000;
+export const MAX_CAPTURE_DIMENSION = 8_192;
+export const MAX_PNG_BYTES = 25 * 1024 * 1024;
+export const MAX_INLINE_IMAGE_BYTES = 5 * 1024 * 1024;
+
+export function normalizeBrowserUrl(value) {
+    const raw = String(value ?? "").trim();
+    if (!raw) {
+        throw new Error("A browser URL is required.");
+    }
+
+    const candidate = /^(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?(?:\/|$)/i.test(raw) ? `http://${raw}` : raw;
+    let url;
+    try {
+        url = new URL(candidate);
+    } catch {
+        throw new Error(`Invalid browser URL: ${raw}`);
+    }
+
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("Browser URLs must use http: or https:.");
+    }
+
+    return url.href;
+}
+
+export function resolveViewport({ preset, width, height } = {}) {
+    if (width !== undefined || height !== undefined) {
+        if (
+            !Number.isInteger(width) ||
+            !Number.isInteger(height) ||
+            width < 200 ||
+            height < 200 ||
+            width > 4096 ||
+            height > 4096
+        ) {
+            throw new Error("Custom viewport width and height must both be integers from 200 to 4096.");
+        }
+
+        if (width * height > MAX_VIEWPORT_PIXELS) {
+            throw new Error(`Custom viewport exceeds the ${MAX_VIEWPORT_PIXELS.toLocaleString()} pixel limit.`);
+        }
+
+        return { width, height };
+    }
+
+    const name = preset ?? "desktop";
+    const viewport = VIEWPORT_PRESETS[name];
+    if (!viewport) {
+        throw new Error(`Unknown viewport preset: ${name}`);
+    }
+
+    return { ...viewport };
+}
+
+export function resolveUserPath(cwd, value, label = "path") {
+    const raw = String(value ?? "")
+        .trim()
+        .replace(/^@/, "");
+    if (!raw) {
+        throw new Error(`${label} is required.`);
+    }
+
+    return path.isAbsolute(raw) ? path.normalize(raw) : path.resolve(cwd, raw);
+}
+
+export function assertDistinctPaths(entries) {
+    const seen = new Map();
+    for (const [label, file] of entries) {
+        const normalized = path.resolve(file);
+        let canonical = normalized;
+        try {
+            canonical = fs.realpathSync(normalized);
+        } catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+
+            try {
+                canonical = path.join(fs.realpathSync(path.dirname(normalized)), path.basename(normalized));
+            } catch {}
+        }
+
+        let identity = canonical;
+        try {
+            const stat = fs.statSync(normalized);
+            identity = `inode:${stat.dev}:${stat.ino}`;
+        } catch {}
+
+        const previous = seen.get(identity) || seen.get(canonical);
+        if (previous) {
+            throw new Error(`${label} must not alias ${previous}: ${normalized}`);
+        }
+
+        seen.set(identity, label);
+        seen.set(canonical, label);
+    }
+}
+
+export function sanitizeArtifactSegment(value) {
+    const normalized = String(value ?? "session")
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+
+    return normalized.slice(0, 80) || "session";
+}
+
+export function makeArtifactPath(agentDir, sessionId, kind, extension = "png") {
+    const dir = path.join(agentDir, "specpi", "browser-artifacts", sanitizeArtifactSegment(sessionId));
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stamp = new Date().toISOString().replaceAll(":", "").replaceAll(".", "-");
+    const suffix = Math.random().toString(16).slice(2, 10);
+
+    return path.join(dir, `${sanitizeArtifactSegment(kind)}-${stamp}-${suffix}.${extension}`);
+}
+
+export async function publishBuffer(file, data, { overwrite = false, signal } = {}) {
+    if (signal?.aborted) {
+        throw new Error("Browser operation aborted.");
+    }
+
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    const temporary = path.join(
+        path.dirname(file),
+        `.${path.basename(file)}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`,
+    );
+    try {
+        await fs.promises.writeFile(temporary, data, { mode: 0o600, flag: "wx" });
+        if (signal?.aborted) {
+            throw new Error("Browser operation aborted.");
+        }
+
+        if (overwrite) {
+            await fs.promises.rename(temporary, file);
+        } else {
+            try {
+                await fs.promises.link(temporary, file);
+            } catch (error) {
+                if (error.code === "EEXIST") {
+                    throw new Error(
+                        `Output already exists: ${file}. Pass overwrite=true only when replacement is intended.`,
+                    );
+                }
+
+                throw error;
+            }
+
+            await fs.promises.unlink(temporary);
+        }
+    } finally {
+        await fs.promises.rm(temporary, { force: true }).catch(() => {});
+    }
+}
+
+export function getAgentDir(extensionUrl) {
+    if (process.env.PI_CODING_AGENT_DIR) {
+        return path.resolve(process.env.PI_CODING_AGENT_DIR);
+    }
+
+    return path.resolve(path.dirname(fileURLToPath(extensionUrl)), "../..");
+}
+
+export async function loadBrowserRuntime(runtimeDir) {
+    const packageJson = path.join(runtimeDir, "package.json");
+    if (!fs.existsSync(packageJson)) {
+        throw new Error(
+            `SpecPi browser runtime is not installed at ${runtimeDir}. Run specpi update without --skip-browser-install.`,
+        );
+    }
+
+    const require = createRequire(packageJson);
+    const previousBrowsersPath = process.env.PLAYWRIGHT_BROWSERS_PATH;
+    process.env.PLAYWRIGHT_BROWSERS_PATH = path.join(runtimeDir, "browsers");
+    try {
+        const playwright = require("playwright");
+        const { PNG } = require("pngjs");
+        const pixelmatchPath = require.resolve("pixelmatch");
+        const pixelmatchModule = await import(pathToFileURL(pixelmatchPath).href);
+
+        return { playwright, PNG, pixelmatch: pixelmatchModule.default };
+    } finally {
+        if (previousBrowsersPath === undefined) {
+            delete process.env.PLAYWRIGHT_BROWSERS_PATH;
+        } else {
+            process.env.PLAYWRIGHT_BROWSERS_PATH = previousBrowsersPath;
+        }
+    }
+}
+
+export function readPngDimensions(buffer, label = "PNG") {
+    if (
+        !Buffer.isBuffer(buffer) ||
+        buffer.length < 24 ||
+        buffer.toString("hex", 0, 8) !== "89504e470d0a1a0a" ||
+        buffer.toString("ascii", 12, 16) !== "IHDR"
+    ) {
+        throw new Error(`${label} is not a valid PNG.`);
+    }
+
+    const width = buffer.readUInt32BE(16);
+    const height = buffer.readUInt32BE(20);
+    if (
+        !width ||
+        !height ||
+        width > MAX_CAPTURE_DIMENSION ||
+        height > MAX_CAPTURE_DIMENSION ||
+        width * height > MAX_CAPTURE_PIXELS
+    ) {
+        throw new Error(`${label} dimensions ${width}x${height} exceed browser image limits.`);
+    }
+
+    return { width, height };
+}
+
+export function assertPngResourceBounds(buffer, label = "PNG") {
+    if (buffer.length > MAX_PNG_BYTES) {
+        throw new Error(`${label} exceeds the ${MAX_PNG_BYTES} byte compressed-size limit.`);
+    }
+
+    return readPngDimensions(buffer, label);
+}
+
+function boundedPngWrite(PNG, image, label) {
+    const buffer = PNG.sync.write(image);
+    if (buffer.length > MAX_PNG_BYTES) {
+        throw new Error(`${label} exceeds the ${MAX_PNG_BYTES} byte compressed-size limit.`);
+    }
+
+    return buffer;
+}
+
+export function comparePngBuffers(baselineBuffer, currentBuffer, { PNG, pixelmatch }, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_DIFF_THRESHOLD;
+    const maxDiffPixelRatio = options.maxDiffPixelRatio ?? DEFAULT_MAX_DIFF_PIXEL_RATIO;
+    if (typeof threshold !== "number" || threshold < 0 || threshold > 1) {
+        throw new Error("threshold must be between 0 and 1.");
+    }
+
+    if (typeof maxDiffPixelRatio !== "number" || maxDiffPixelRatio < 0 || maxDiffPixelRatio > 1) {
+        throw new Error("maxDiffPixelRatio must be between 0 and 1.");
+    }
+
+    assertPngResourceBounds(baselineBuffer, "Baseline PNG");
+    assertPngResourceBounds(currentBuffer, "Current PNG");
+
+    const baseline = PNG.sync.read(baselineBuffer);
+    const current = PNG.sync.read(currentBuffer);
+    const dimensionsMatch = baseline.width === current.width && baseline.height === current.height;
+    if (!dimensionsMatch) {
+        const width = Math.max(baseline.width, current.width);
+        const height = Math.max(baseline.height, current.height);
+        if (width * height > MAX_CAPTURE_PIXELS) {
+            throw new Error("Dimension-mismatch diff would exceed browser image limits.");
+        }
+
+        const diff = new PNG({ width, height });
+        diff.data.fill(255);
+        for (let offset = 1; offset < diff.data.length; offset += 4) {
+            diff.data[offset] = 0;
+            diff.data[offset + 1] = 0;
+        }
+
+        return {
+            pass: false,
+            dimensionsMatch,
+            baseline: { width: baseline.width, height: baseline.height },
+            current: { width: current.width, height: current.height },
+            diffPixels: Math.max(baseline.width * baseline.height, current.width * current.height),
+            diffPixelRatio: 1,
+            diffBuffer: boundedPngWrite(PNG, diff, "Diff PNG"),
+            threshold,
+            maxDiffPixelRatio,
+        };
+    }
+
+    const diff = new PNG({ width: current.width, height: current.height });
+    const diffPixels = pixelmatch(baseline.data, current.data, diff.data, current.width, current.height, { threshold });
+    const pixelCount = current.width * current.height;
+    const diffPixelRatio = pixelCount === 0 ? 0 : diffPixels / pixelCount;
+
+    return {
+        pass: diffPixelRatio <= maxDiffPixelRatio,
+        dimensionsMatch,
+        baseline: { width: baseline.width, height: baseline.height },
+        current: { width: current.width, height: current.height },
+        diffPixels,
+        diffPixelRatio,
+        diffBuffer: boundedPngWrite(PNG, diff, "Diff PNG"),
+        threshold,
+        maxDiffPixelRatio,
+    };
+}