glasspane-harness 0.6.2 → 0.6.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 opencode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+<h1 align="center">
+  <code>glasspane-harness</code>
+</h1>
+
+<p align="center">
+  <a href="README.md"><strong>English</strong></a> ·
+  <a href="README.zh-CN.md"><strong>简体中文</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/glasspane-harness"><img src="https://img.shields.io/npm/dt/glasspane-harness?label=Downloads&style=for-the-badge&color=2ea44f&logo=npm&logoColor=white" alt="npm downloads"></a>
+  <img src="https://img.shields.io/dynamic/json?url=https%3A%2F%2Fregistry.npmjs.org%2Fglasspane-harness%2Flatest&query=version&label=version&color=brightgreen" alt="version">
+  <a href="https://github.com/jingzhao-l/glasspane-harness/actions/workflows/ci.yml"><img src="https://github.com/jingzhao-l/glasspane-harness/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow" alt="License"></a>
+  <img src="https://img.shields.io/badge/macOS-13%2B-blue?logo=apple&logoColor=white" alt="macOS 13+">
+  <a href="https://github.com/jingzhao-l/glasspane-harness"><img src="https://img.shields.io/github/stars/jingzhao-l/glasspane-harness?style=social&label=Star" alt="Stars"></a>
+</p>
+
+<p align="center">
+  <img src="assets/banner.svg" alt="GlassPane Harness — evidence-honest GUI verification for macOS apps" width="720">
+</p>
+
+---
+
+**The problem.** An AI agent driving a real macOS app cannot honestly say whether the UI
+did what it asked. It sees its own tool output, guesses from prose, and reports success.
+Screenshots don't help: they show *a* moment, not a *change*, and they cannot say whether
+the change was caused by the click.
+
+**GlassPane Harness** is a coding agent (an [opencode](https://github.com/anomalyco/opencode) upstream fork
+fork) wired to a Swift verification engine through a native `gp_*` tool surface. Every
+action is measured — accessibility-tree diff, pixel diff, crash and responsiveness
+signals — and the engine reports **its own** attribution (`strong` / `soft` / `none`,
+circuit-breaker level, pass / fail / inconclusive). The harness transcribes; it never
+invents a verdict. Verified calls are appended to a hash-chained decision log, and a
+compaction hook re-injects the session's evidence anchors so summarising can never quietly
+drop the audit chain.
+
+The engine is [GlassPane](https://github.com/jingzhao-l/GlassPane). The harness is the
+agent side of it.
+
+## This is a complete coding agent, not a stripped one
+
+The verification wiring is the point of this fork, but it is **additive**. Everything
+upstream opencode does, this harness still does — same agents, same tools, same models, same
+permissions, same LSP and MCP support, same TUI and web app, same SDK and plugin API.
+Nothing was cut to make room for the kernel.
+
+That is a measured claim, not a promise. The fork tracks upstream
+[anomalyco/opencode](https://github.com/anomalyco/opencode) at a pinned tag, and
+`harness/tools/fork-diff.mjs` compares every file in this tree against that tag on every
+change:
+
+```
+fork-diff vs v1.18.32: 6527/6687 byte-identical, 51 edited, 55 added, 54 deleted
+```
+
+Roughly 98% of the upstream tree is byte-for-byte upstream. The edits are concentrated in
+config/paths/branding, the `gp_*` tool surface, the kernel binding, the compaction hook,
+and the packaging scripts. The deleted files are upstream's own publish plumbing for
+channels this product does not use (ghcr images, AUR, a Homebrew tap, a hosted console
+account) — plus, in 0.4.0, the first-party account surface described below.
+
+What "additive" means in practice: if upstream ships a feature in a later release, this
+fork can take it, because the feature is still here to take.
+
+### One exception, and it is deliberate: no account, bring your own key
+
+Upstream lets you `auth login` to an opencode account, which unlocks opencode's own
+model gateway (a first-party provider in the catalog) and remote session sharing. This
+product has no such account, so that surface is removed rather than shipped broken:
+
+- upstream's `opencode` provider entry is filtered out of the model catalog
+- `auth login` / `logout` / `switch`, the `/org` command and the org switcher are gone
+- the `/experimental/console*` endpoints and the console-managed-provider state are gone
+- session sharing to opencode's upstream cloud is gone (`share` / `autoshare` config keys too)
+
+**Everything else in the catalog is untouched.** Anthropic, OpenAI, Google, GitHub
+Copilot, Amazon Bedrock, Azure, OpenRouter and the rest are all still there — hundreds of
+models — and each one is unlocked by **your own API key**, supplied by environment
+variable, by the config file with an `{env:NAME}` template, or by the TUI's `/connect`
+dialog. There is nothing to sign up for and nothing to log into. See
+[`docs/models-and-keys.md`](docs/models-and-keys.md).
+
+## Product surfaces
+
+| Surface | What you get | How it ships |
+|---|---|---|
+| **CLI + TUI** | The agent in your terminal: interactive TUI, `run` for one-shot tasks, `serve` for headless clients | the `glasspane-harness` / `gp-harness` binaries, npm + one-click installer |
+| **Web app** (embedded) | Browser UI served by the binary itself — no second process, no separate deploy | embedded in the binary (`--skip-embed-web-ui` for a CLI-only build) |
+| **Docs** | This repository's `docs/` — install, tools, evidence, migration, troubleshooting | in-repo markdown (canonical; versioned with the code) |
+| **SDKs** | TypeScript SDK and the plugin SDK for building your own `gp_*`-style tools | workspace packages, shipped with the tree |
+
+Not shipped, on purpose: the upstream hosted console / enterprise stack (a private harness
+has no use for an organisation-and-quota back office), the Electron desktop app (a second
+batch — it needs signing and notarisation accounts), and the upstream docs *site*
+(upstream's Astro/Starlight tree) is **gone from this repository**; the documentation is
+`docs/`, and the console/enterprise/stats trees went with it. They were never part of
+this product, and keeping them meant keeping someone else's product surface in our repo.
+
+## Install
+
+```bash
+# npm (recommended)
+npm install -g glasspane-harness
+
+# or bun
+bun add -g glasspane-harness
+
+# or one-click (npm first, GitHub release asset as fallback)
+curl -fsSL https://raw.githubusercontent.com/jingzhao-l/glasspane-harness/main/scripts/install.sh | bash
+```
+
+Two commands are installed: **`glasspane-harness`** and the short alias **`gp-harness`**.
+
+**macOS only.** The engine, the permission model and the evidence pipeline exist only on
+macOS, so the npm distribution is macOS-only too: the package declares `os: darwin` and
+npm refuses the install elsewhere instead of handing you a binary that cannot run. There
+is no Linux or Windows build, by decision, not by omission.
+
+Prerequisites: macOS 13+ (Apple silicon or Intel), and — for the `gp_*` tools — the **GlassPane** background
+service running with Accessibility granted ([install GlassPane](https://github.com/jingzhao-l/GlassPane);
+the installer prints the exact next steps). Without the engine every `gp_*` call answers
+`GP_E_ENGINE_UNREACHABLE` with a remedy — that is the engine's word, not the installer's.
+
+If npm's global prefix is not writable, use
+`npm install -g --prefix "$HOME/.local" glasspane-harness` and put `~/.local/bin` on PATH;
+the installer detects that failure and prints this remedy itself.
+
+## Quick start
+
+```bash
+glasspane-harness                                  # interactive TUI (the embedded web UI is served too)
+glasspane-harness run "attach to Notes, type a heading, then tell me whether the UI proved it"
+glasspane-harness serve --port 4096                # headless server; the web app is served from it
+glasspane-harness --help
+```
+
+The first thing to ask any session for is `gp_probe_status`: it reports the engine
+version, advertised capabilities and permission state — and every remedy the tool surface
+emits points back at it.
+
+## The `gp_*` tool surface
+
+| Tool | What it does | Permission |
+|---|---|---|
+| `gp_probe_status` | engine self-report: version, capabilities, accessibility / input-monitoring / screen-recording / developer-tools state | prompts (diagnostic entry point) |
+| `gp_attach` | attach to a running app by bundle id or pid | prompts |
+| `gp_observe` | snapshot the attached window's accessibility tree (digest, node count) | prompts |
+| `gp_act` | perform one accessibility action and return what the engine observed changing (op id ties it to an evidence pack) | prompts (moves a real app) |
+| `gp_diagnose` | classify an operation from its pack (contaminated / out-of-band / callback / pre-existing / no-change) | prompts |
+| `gp_last_evidence` | fetch the evidence pack the engine archived for an operation | prompts |
+
+Whether a method exists is read from the running engine (`hello.capabilities`) — the list
+is never hard-coded here, because it grows upstream of this file. Full reference:
+[`docs/tools.md`](docs/tools.md).
+
+## The evidence discipline
+
+1. **Judgement stays in Swift.** Attribution, diagnosis class, circuit-breaker level and
+   the pass / fail / inconclusive outcome are computed by the GlassPane engine. The
+   harness transcribes; it never derives. A CI ratchet fails when a tool surface grows a
+   threshold, a pixel verdict or a pass/fail synthesis.
+2. **What the model reads is what the engine said.** Error codes and agent-executable
+   remedies go into the tool's `output` string, not only into metadata.
+3. **The audit chain is a product feature.** Verified calls are appended to a hash-chained
+   decision log (op id ↔ entry hash); the fixed points re-compute the chain with two
+   independent hashers, so the ledger can be verified without trusting the writer.
+4. **Compaction may not erase evidence.** The compaction hook injects the session's
+   evidence anchors into the summarisation prompt; absence is stated as arithmetic
+   (`gp_* calls: N · decisions recorded: M`), never assumed.
+
+Details: [`docs/evidence.md`](docs/evidence.md).
+
+## Documentation
+
+- [`docs/install.md`](docs/install.md) — install paths, permissions, verification
+- [`docs/models-and-keys.md`](docs/models-and-keys.md) — the model catalog and how to supply
+  your own API keys
+- [`docs/tools.md`](docs/tools.md) — the `gp_*` surface, argument by argument
+- [`docs/evidence.md`](docs/evidence.md) — attribution, diagnosis, the decision log
+- [`docs/migrate-from-opencode.md`](docs/migrate-from-opencode.md) — what the fork changed versus upstream
+  customisation changed, and what deliberately stayed
+- [`docs/release.md`](docs/release.md) — cutting a release, and the npm trusted-publisher
+  setup
+- [`docs/kernel-integration.md`](docs/kernel-integration.md) — the shared kernel, why it is
+  not on npm, and how much of the two-way integration exists today
+- [`docs/troubleshooting.md`](docs/troubleshooting.md) — engine unreachable, permission
+  denials, the `GP_E_*` codes
+- [`FORK.md`](FORK.md) / [`SYNCLOG.md`](SYNCLOG.md) — the fork's coordinates, discipline
+  and per-batch measurements; [`NOTICE`](NOTICE) — attribution;
+  [`CHANGELOG.md`](CHANGELOG.md) — what shipped in each version
+
+## Development
+
+```bash
+bun install                # workspace (on TLS-intercepting networks bun needs
+                           # NODE_EXTRA_CA_CERTS — see FORK.md)
+bun run typecheck           # per package
+bun test --timeout 30000    # fixed-point tests (from packages/opencode)
+bun run build --single      # product build: CLI + TUI + embedded web app
+```
+
+The repo-side gates live in the GlassPane repository under `harness/` (hook-liveness,
+fork-diff, kernel-vendor, tool-surface, surface-semantics, product-surface,
+brand-surface); their rationale, negative controls and known boundaries are documented in
+`harness/README.md`. Every customisation commit carries the `[gp]` prefix.
+
+## License & attribution
+
+MIT, like upstream. `LICENSE` is upstream's, unchanged; [`NOTICE`](NOTICE) records what
+this fork changed and where the code came from. Upstream:
+[anomalyco/opencode](https://github.com/anomalyco/opencode) `v1.18.32` © SST — without
+them this product does not exist, and `FORK.md` exists so that claim stays true for
+every future sync.
+

package/README.zh-CN.md

@@ -0,0 +1,173 @@
+<h1 align="center">
+  <code>glasspane-harness</code>
+</h1>
+
+<p align="center">
+  <a href="README.zh-CN.md"><strong>简体中文</strong></a> ·
+  <a href="README.md"><strong>English</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/glasspane-harness"><img src="https://img.shields.io/npm/dt/glasspane-harness?label=Downloads&style=for-the-badge&color=2ea44f&logo=npm&logoColor=white" alt="npm downloads"></a>
+  <img src="https://img.shields.io/dynamic/json?url=https%3A%2F%2Fregistry.npmjs.org%2Fglasspane-harness%2Flatest&query=version&label=version&color=brightgreen" alt="version">
+  <a href="https://github.com/jingzhao-l/glasspane-harness/actions/workflows/ci.yml"><img src="https://github.com/jingzhao-l/glasspane-harness/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow" alt="License"></a>
+  <img src="https://img.shields.io/badge/macOS-13%2B-blue?logo=apple&logoColor=white" alt="macOS 13+">
+  <a href="https://github.com/jingzhao-l/glasspane-harness"><img src="https://img.shields.io/github/stars/jingzhao-l/glasspane-harness?style=social&label=Star" alt="Stars"></a>
+</p>
+
+<p align="center">
+  <img src="assets/banner.svg" alt="GlassPane Harness — 证据诚实的 macOS 应用 GUI 验证 harness" width="720">
+</p>
+
+---
+
+**问题。** 一个驱动真实 macOS 应用的 AI agent，没法诚实地说清界面到底有没有按它要求的动。
+它只看得见自己的工具输出，于是靠散文猜测、报成功。截图也不解决问题：截图给的是**某个瞬间**，
+不是**某次变化**，更说不清这次变化是不是那次点击造成的。
+
+**GlassPane Harness** 是一个编码 agent（[opencode](https://github.com/anomalyco/opencode)
+的 fork），通过原生 `gp_*` 工具面接到 Swift 验证引擎上。每次动作都被测量——辅助功能树 diff、
+像素 diff、崩溃与响应性信号——然后由引擎给出**它自己的**归因（`strong` / `soft` / `none`、
+熔断级、pass / fail / inconclusive）。harness 只转录，不自己下结论。成包的验证调用进哈希链
+决策日志；压缩钩子会把会话的证据锚点重新注入压缩提示词，摘要再长也丢不掉审计链。
+
+引擎是 [GlassPane](https://github.com/jingzhao-l/GlassPane)，harness 是它的 agent 侧。
+
+## 这是一个完整的编程 harness，不是被削过头的 fork
+
+验证接线是这次分叉的落点，但它是**加法**：上游 opencode 会做的每一件事，这个 harness 都会做——
+同样的 agent、工具、模型、权限，同样的 LSP 与 MCP 支持，同样的 TUI 与 web 应用，同样的
+SDK 与 plugin API。为了塞下内核，没有任何功能被砍掉。
+
+这句话是**量出来的**，不是承诺。分叉锚定上游
+[anomalyco/opencode](https://github.com/anomalyco/opencode) 的某个 tag，
+`harness/tools/fork-diff.mjs` 每次改动都会把本树与那个 tag 逐文件对比：
+
+```
+fork-diff vs v1.18.32: 6527/6687 byte-identical, 51 edited, 55 added, 54 deleted
+```
+
+上游树约 98% 逐字节保持上游原样。改动集中在 config/paths/品牌、`gp_*` 工具面、内核绑定、
+压缩钩子和打包脚本；删掉的是上游**自己的**发布管道（ghcr 镜像、AUR、Homebrew tap、
+托管 console 账号）——外加 0.4.0 里下面说的第一方账号面。
+
+"加法"在实践中的含义：上游后续版本发布的功能，这个 fork 接得住——因为功能还在那里。
+
+### 唯一的例外，而且是刻意的：没有账号，自带 API key
+
+上游可以 `auth login` 登录 opencode 账号，用来解锁 opencode 自家的模型网关（目录里的第一方
+provider）和云端会话分享。本产品没有这个账号，所以这片面是**删掉**而不是留一个跑不通的壳：
+
+- 上游目录里的 `opencode` provider 条目被过滤掉
+- `auth login` / `logout` / `switch`、`/org` 命令、组织切换器全部移除
+- `/experimental/console*` 端点与 console 托管 provider 状态全部移除
+- 分享会话到上游 opencode 云端的能力移除（`share` / `autoshare` 配置键一并移除）
+
+**目录里其他一切都原封不动。** Anthropic、OpenAI、Google、GitHub Copilot、Amazon Bedrock、
+Azure、OpenRouter 等等全在——几百个模型——每一个都用**你自己的 API key** 解锁：环境变量、
+配置文件里的 `{env:NAME}` 模板，或 TUI 的 `/connect` 对话框。不用注册、不用登录。见
+[`docs/models-and-keys.md`](docs/models-and-keys.md)。
+
+## 产品面
+
+| 产品面 | 你拿到什么 | 怎么发 |
+|---|---|---|
+| **CLI + TUI** | 终端里的 agent：交互式 TUI、`run` 一次性任务、`serve` 无头服务 | `glasspane-harness` / `gp-harness` 二进制，npm + 一键安装器 |
+| **Web 应用**（内嵌） | 二进制自己服务的浏览器界面——没有第二个进程、不单独部署 | 嵌进二进制（`--skip-embed-web-ui` 出纯 CLI 构建） |
+| **文档** | 本仓 `docs/`——安装、工具面、证据、迁移、排障 | 仓内 markdown（canonical，与代码同版本） |
+| **SDK** | TypeScript SDK 与 plugin SDK，用来写自己的 `gp_*` 式工具 | 工作区包，随树发布 |
+
+**刻意不发**：上游的托管 console / enterprise 栈（私有 harness 不需要"组织与额度后台"这种形态）、
+上游的**文档站**（`packages/web`）——这两片树已**从本仓删除**；本产品的 canonical 文档是 `docs/`。
+它们从来不属于这个产品，把别人的产品面留在自己仓里只会让私有化变成自欺。Electron 桌面 app 保留在
+树里（产品面，第二批——需要签名与公证账号）。
+
+## 安装
+
+```bash
+npm install -g glasspane-harness     # 推荐
+bun add -g glasspane-harness
+curl -fsSL https://raw.githubusercontent.com/jingzhao-l/glasspane-harness/main/scripts/install.sh | bash
+```
+
+会装出两个命令：**`glasspane-harness`** 与短别名 **`gp-harness`**。
+
+**只支持 macOS。** 引擎、权限模型、证据流水线都只存在于 macOS，npm 分发随之收成
+macOS-only：包声明 `os: darwin`，非 macOS 上 npm 直接拒绝安装，而不是给你一个跑不了的
+二进制。**没有 Linux / Windows 构建，这是决定，不是遗漏。**
+
+前提：macOS 13+（Apple silicon 或 Intel）；要用 `gp_*` 工具面还需要 **GlassPane** 后台服务在跑且已授予辅助功能权限
+（[先装 GlassPane](https://github.com/jingzhao-l/GlassPane)，安装器会把下一步说清楚）。没有引擎时，
+每个 `gp_*` 调用只会回 `GP_E_ENGINE_UNREACHABLE` 加一条 remedy——那是引擎的话，不是安装器的。
+
+若 npm 的全局前缀不可写，用 `npm install -g --prefix "$HOME/.local" glasspane-harness` 并把
+`~/.local/bin` 放进 PATH；安装器会自己检测到这种失败并把这条补救打出来。
+
+## 上手
+
+```bash
+glasspane-harness                                  # 交互式 TUI（内嵌 web 应用也会被服务出来）
+glasspane-harness run "attach 到备忘录，打一个标题，然后告诉我 UI 有没有给出证据"
+glasspane-harness serve --port 4096                # 无头服务；web 应用由它提供
+glasspane-harness --help
+```
+
+任何会话里第一件该问的事是 `gp_probe_status`：它报引擎版本、宣称的能力与权限状态——
+工具面里每条 remedy 都指回它。
+
+## `gp_*` 工具面
+
+| 工具 | 作用 | 权限 |
+|---|---|---|
+| `gp_probe_status` | 引擎自报：版本、能力、辅助功能/输入监听/屏幕录制/开发者工具状态 | 询问（诊断入口） |
+| `gp_attach` | 按 bundle id 或 pid 附着到运行中的应用 | 询问 |
+| `gp_observe` | 快照附着窗口的辅助功能树（digest、节点数） | 询问 |
+| `gp_act` | 执行一次辅助功能动作，返回引擎观察到的东西（op id 关联证据包） | 询问（会动真实应用） |
+| `gp_diagnose` | 按证据包给操作定性（污染 / 带外 / 回调 / 既有问题 / 无变化） | 询问 |
+| `gp_last_evidence` | 取回引擎为某次操作归档的证据包 | 询问 |
+
+方法是否存在**从运行中的引擎读**（`hello.capabilities`），本文件不写死清单——那份清单在本文件
+之后还会长。完整参考：[`docs/tools.md`](docs/tools.md)。
+
+## 证据纪律
+
+1. **判定留在 Swift**：归因、诊断类、熔断级、pass / fail / inconclusive 都由 GlassPane 引擎算；
+   harness 只转录、不推导。工具面长出阈值、像素裁决或 pass/fail 合成，CI 棘轮即红。
+2. **模型看到的必须是引擎说过的**：错误码与可执行 remedy 进工具的 `output` 文本，不只塞 metadata。
+3. **审计链是产品功能**：成包调用进哈希链决策日志（op id ↔ entry hash）；固定点用两个独立哈希
+   实现复算链条，账本不必信任写它的那段代码也能验。
+4. **压缩不许抹掉证据**：压缩钩子把证据锚点注入摘要提示词；缺席以算术呈现
+   （`gp_* calls: N · decisions recorded: M`），不许靠默认。
+
+细节：[`docs/evidence.md`](docs/evidence.md)。
+
+## 文档
+
+- [`docs/install.md`](docs/install.md) — 安装通道、权限、自检
+- [`docs/tools.md`](docs/tools.md) — 逐个参数的 `gp_*` 参考
+- [`docs/evidence.md`](docs/evidence.md) — 归因、诊断、决策日志
+- [`docs/migrate-from-opencode.md`](docs/migrate-from-opencode.md) — 相对上游改了什么、刻意留了什么
+- [`docs/troubleshooting.md`](docs/troubleshooting.md) — 引擎不可达、权限拒绝、`GP_E_*` 码表
+- [`FORK.md`](FORK.md) / [`SYNCLOG.md`](SYNCLOG.md) — 分叉坐标、纪律、每批实测数字；
+  [`NOTICE`](NOTICE) — 署名；[`CHANGELOG.md`](CHANGELOG.md) — 每个版本发了什么
+
+## 开发
+
+```bash
+bun install                # 工作区（被 TLS 拦截的网络上 bun 需要 NODE_EXTRA_CA_CERTS，见 FORK.md）
+bun run typecheck
+bun test --timeout 30000    # 固定点测试（在 packages/opencode 里跑）
+bun run build --single      # 产品构建：CLI + TUI + 内嵌 web 应用
+```
+
+仓侧的闸住在 GlassPane 仓的 `harness/`（hook-liveness、fork-diff、kernel-vendor、
+tool-surface、surface-semantics、product-surface、brand-surface），理由、反向控制与已知边界
+写在 `harness/README.md`。我们每个定制提交都带 `[gp]` 前缀。
+
+## 许可与署名
+
+MIT，与上游一致。`LICENSE` 是上游原文未改，[`NOTICE`](NOTICE) 记录本 fork 改了什么、代码来自哪里。
+上游：[anomalyco/opencode](https://github.com/anomalyco/opencode) `v1.18.32` © SST——没有他们就没有
+这个产品，而 `FORK.md` 的存在是为了让这句话在未来的每次同步后仍然成立。
+

package/bin/glasspane-harness.exe

@@ -0,0 +1,10 @@
+echo "Error: glasspane-harness's postinstall script was not run." >&2
+echo "" >&2
+echo "This occurs when using --ignore-scripts during installation, or when using a" >&2
+echo "package manager like pnpm that does not run postinstall scripts by default." >&2
+echo "" >&2
+echo "To fix this, run the postinstall script manually:" >&2
+echo "  cd node_modules/glasspane-harness && node postinstall.mjs" >&2
+echo "" >&2
+echo "Or reinstall glasspane-harness without the --ignore-scripts flag." >&2
+exit 1

package/package.json

@@ -1 +1,50 @@
-{"name":"glasspane-harness","version":"0.6.2"}
+{
+  "name": "glasspane-harness",
+  "description": "GlassPane Harness — evidence-honest GUI verification harness for macOS apps (opencode fork with GlassPane's native gp_* tool surface)",
+  "keywords": [
+    "glasspane",
+    "harness",
+    "gui-testing",
+    "macos",
+    "accessibility",
+    "evidence",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jingzhao-l/glasspane-harness.git"
+  },
+  "homepage": "https://github.com/jingzhao-l/glasspane-harness#readme",
+  "bugs": {
+    "url": "https://github.com/jingzhao-l/glasspane-harness/issues"
+  },
+  "bin": {
+    "glasspane-harness": "./bin/glasspane-harness.exe",
+    "gp-harness": "./bin/glasspane-harness.exe"
+  },
+  "scripts": {
+    "postinstall": "node ./postinstall.mjs"
+  },
+  "version": "0.6.4",
+  "license": "MIT",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "funding": "https://github.com/sponsors/jingzhao-l",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "sideEffects": false,
+  "optionalDependencies": {
+    "glasspane-harness-darwin-arm64": "0.6.4",
+    "glasspane-harness-darwin-x64": "0.6.4"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+import childProcess from "child_process"
+import fs from "fs"
+import os from "os"
+import path from "path"
+import { createRequire } from "module"
+import { fileURLToPath } from "url"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, "package.json"), "utf8"))
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+}
+const archMap = {
+  x64: "x64",
+  arm64: "arm64",
+  arm: "arm",
+}
+
+const platform = platformMap[os.platform()] ?? os.platform()
+const arch = archMap[os.arch()] ?? os.arch()
+// Product identity lives in product.json at the repo root; product-surface.mjs
+// keeps these constants in step with it (this file ships inside the npm wrapper).
+const base = `glasspane-harness-${platform}-${arch}`
+const sourceBinary = platform === "windows" ? "glasspane-harness.exe" : "glasspane-harness"
+const targetBinary = path.join(__dirname, "bin", "glasspane-harness.exe")
+
+function supportsAvx2() {
+  if (arch !== "x64") return false
+
+  if (platform === "linux") {
+    try {
+      return /(^|\s)avx2(\s|$)/i.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "darwin") {
+    try {
+      const result = childProcess.spawnSync("sysctl", ["-n", "hw.optional.avx2_0"], {
+        encoding: "utf8",
+        timeout: 1500,
+      })
+      if (result.status !== 0) return false
+      return (result.stdout || "").trim() === "1"
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "windows") {
+    const command =
+      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
+
+    for (const executable of ["powershell.exe", "pwsh.exe", "pwsh", "powershell"]) {
+      try {
+        const result = childProcess.spawnSync(executable, ["-NoProfile", "-NonInteractive", "-Command", command], {
+          encoding: "utf8",
+          timeout: 3000,
+          windowsHide: true,
+        })
+        if (result.status !== 0) continue
+        const output = (result.stdout || "").trim().toLowerCase()
+        if (output === "true" || output === "1") return true
+        if (output === "false" || output === "0") return false
+      } catch {
+        continue
+      }
+    }
+  }
+
+  return false
+}
+
+function isMusl() {
+  if (platform !== "linux") return false
+
+  try {
+    if (fs.existsSync("/etc/alpine-release")) return true
+  } catch {
+    // Ignore filesystem probes that are blocked by the host.
+  }
+
+  try {
+    const result = childProcess.spawnSync("ldd", ["--version"], { encoding: "utf8" })
+    return `${result.stdout || ""}${result.stderr || ""}`.toLowerCase().includes("musl")
+  } catch {
+    return false
+  }
+}
+
+function packageNames() {
+  const baseline = arch === "x64" && !supportsAvx2()
+
+  if (platform === "linux") {
+    if (isMusl()) {
+      if (arch === "x64")
+        return baseline
+          ? [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+          : [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+      return [`${base}-musl`, base]
+    }
+
+    if (arch === "x64")
+      return baseline
+        ? [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+        : [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+    return [base, `${base}-musl`]
+  }
+
+  if (arch === "x64") return baseline ? [`${base}-baseline`, base] : [base, `${base}-baseline`]
+  return [base]
+}
+
+function resolveBinary(name) {
+  const packageJsonPath = require.resolve(`${name}/package.json`)
+  const binaryPath = path.join(path.dirname(packageJsonPath), "bin", sourceBinary)
+  if (!fs.existsSync(binaryPath)) throw new Error(`Binary not found at ${binaryPath}`)
+  return binaryPath
+}
+
+function installPackage(name) {
+  const version = packageJson.optionalDependencies?.[name]
+  if (!version) return
+
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), "glasspane-harness-install-"))
+  try {
+    const result = childProcess.spawnSync(
+      "npm",
+      ["install", "--ignore-scripts", "--no-save", "--loglevel=error", "--prefix", temp, `${name}@${version}`],
+      { stdio: "inherit", windowsHide: true },
+    )
+    if (result.status !== 0) return
+    const packageDir = path.join(temp, "node_modules", name)
+    copyBinary(path.join(packageDir, "bin", sourceBinary), targetBinary)
+    return true
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true })
+  }
+}
+
+function copyBinary(source, target) {
+  if (!fs.existsSync(source)) throw new Error(`Binary not found at ${source}`)
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  if (fs.existsSync(target)) fs.unlinkSync(target)
+  try {
+    fs.linkSync(source, target)
+  } catch {
+    fs.copyFileSync(source, target)
+  }
+  fs.chmodSync(target, 0o755)
+}
+
+function verifyBinary() {
+  const result = childProcess.spawnSync(targetBinary, ["--version"], {
+    encoding: "utf8",
+    stdio: "ignore",
+    windowsHide: true,
+  })
+  return result.status === 0
+}
+
+function main() {
+  for (const name of packageNames()) {
+    try {
+      copyBinary(resolveBinary(name), targetBinary)
+      if (verifyBinary()) return
+    } catch {
+      if (installPackage(name) && verifyBinary()) return
+    }
+  }
+
+  throw new Error(
+    `It seems your package manager failed to install the right glasspane-harness CLI package. Try manually installing ${packageNames()
+      .map((name) => JSON.stringify(name))
+      .join(" or ")}.`,
+  )
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(error.message)
+  process.exit(1)
+}