spexcode 0.1.6 → 0.2.1

package/README.md

@@ -1,69 +1,127 @@
 <img src="docs/sdd-tuxedo-pooh.png" alt="Writing code vs. authoring a living, executable specification artifact" width="420">
 
-> Spec-driven development gets wrecked by spec drift and spec bloat. SpexCode's bet
-> is to keep the spec the cheap, honest twin of the code — rewritten in place, never
-> a tuxedo of stale ceremony.
+English | [中文](./README.zh-CN.md)
+
+> Spec-driven development fails two ways: the spec drifts out of sync with the code, or it
+> bloats into stale ceremony. SpexCode keeps each spec short and current: rewritten in place
+> and versioned by git, not an accumulating changelog.
 
 **SpexCode** is a spec-driven, self-developing dev tool. Every part of a project becomes a versioned
-*spec node* — a `.spec/**/spec.md` whose body states the part's *present* intent — and **git is the
-database**: a node's version is its count of content commits, and "drift" is governed code that moved
-ahead of its spec. A `spex` CLI plus a live dashboard read all of it straight from git; there is no
+*spec node*: a `.spec/**/spec.md` whose body states the part's present intent. Git is the database:
+a node's version is its count of content commits, and "drift" is governed code that moved ahead of
+its spec. The `spex` CLI and the live dashboard read everything straight from git; there is no
 separate store.
 
-There are two ways to meet SpexCode, and they are kept separate on purpose:
-
-- **[Using SpexCode](#using-spexcode)** — install the `spex` CLI from npm and govern *your own* project.
-- **[Contributing to SpexCode](#contributing-to-spexcode)** — develop the tool itself, in this repo.
+- **[Using SpexCode](#using-spexcode)** — adopt the `spex` CLI and drive it through your coding agent to govern *your own* project.
+- **[Contributing to SpexCode](#contributing-to-spexcode)** — hack on the tool itself, in this repo.
+- **[Working with agents →](https://spexcode.net/working-with-agents/)** — the longer write-up on the docs site.
 
 ---
 
 ## Using SpexCode
 
-You don't clone this repo to *use* SpexCode. Install the published CLI once, then point it at any project.
+You set SpexCode up once (`npm i -g spexcode`, then `spex init` in your repo). After that, the main
+way to use it is by talking to your coding agent. You describe what you want in plain language
+(*"add a spec node for the auth flow", "extract specs for this package", "dispatch a worker to
+implement Y"*) and the agent runs the `spex` CLI for you while you supervise on the board. The
+manual CLI below is the substrate; your agent is the daily interface.
+
+That works because a freshly launched agent already knows SpexCode. `spex init` materializes the
+contract (the spec-node ritual, the commit-before-declare gate, the merge style) into a
+`<!-- spexcode -->` managed block in your repo's `CLAUDE.md`/`AGENTS.md`, which
+**[Claude Code](https://www.anthropic.com/claude-code)** and **Codex** auto-discover as always-on
+context. From there the agent self-serves detail on demand from the built-in manual: `spex guide`
+(the workflow), `spex guide spec` / `spex guide yatsu` (the file formats), and `spex guide config`
+(every `spexcode.json` setting). You can tell it *"run `spex guide config` and set me up a
+launcher"*.
+
+The docs site covers this in full: **[working with agents](https://spexcode.net/working-with-agents/)**
+for the agent-driven workflow, **[getting started](https://spexcode.net/getting-started/)** for the
+setup end to end.
+
+> **It's also just plain tooling.** Strip the agent away and the core is still useful on its own:
+> spec files versioned by git, checked by `spex lint` and shown on a read-only dashboard. No AI,
+> nothing to run but Node and git. The vibe-coding path sits on top of that; it doesn't replace it.
+
+> **Requirements.** Core: **Node ≥ 22** and **git**. Driving SpexCode through an agent (or
+> dispatching workers onto your nodes) also needs **tmux** and an authenticated **Claude Code or
+> Codex** on your PATH. Those agents run commands on your machine, so read
+> [`SECURITY.md`](./docs/SECURITY.md) before exposing the backend.
+
+### Set it up
+
+Install the published CLI once, then adopt it in any project:
 
 ```sh
 npm i -g spexcode      # installs the `spex` command (needs Node ≥ 22)
+cd ~/my-app
+spex init              # additive — never restructures your code
 ```
 
-Adopt it in your project — `spex init` is **additive**, it never restructures your code:
+`spex init` is additive: it seeds a starter **`.spec/`** tree (a root `project` node plus the
+`.config` plugins that define the dev flow), a starter **`spexcode.json`**, and the per-clone
+**git hooks** (a `pre-commit` hook that runs **spec-lint**, blocking on broken spec↔code links, and
+**main-guard**, which blocks direct commits to `main`, plus a `prepare-commit-msg` hook that stamps
+each commit's session attribution). It also **materializes** the harness artifacts that make the
+agent path work: the `<!-- spexcode -->` contract block in `CLAUDE.md`/`AGENTS.md`, and the
+`.claude/` / `.codex/` shims (the `settings.json` hooks) a self-launched agent discovers. Those
+artifacts are generated and gitignored; they are regenerated on each machine, never committed.
+
+Then make it yours — either ask your agent to, or do it by hand: edit `.spec/project/spec.md` to
+describe the project, point `spexcode.json`'s `lint.governedRoots` at your real source dir(s), and
+check the graph:
 
 ```sh
-cd ~/my-app
-spex init              # seed .spec/, a starter spexcode.json, and git hooks — nothing destructive
-# 1. edit .spec/project/spec.md to describe your project
-# 2. point spexcode.json's  lint.governedRoots  at your real source dir(s)
 spex lint              # the "coverage" warnings are your adoption TODO list
 ```
 
-Run it. The backend and the dashboard are **two commands on two ports**, so several projects can run
-side by side on one host (the cwd picks which project is served):
+### Configure it
+
+Two optional JSON files at the repo root hold every setting, split by portability:
+
+- **`spexcode.json`** — *committed, portable*: layout, dashboard identity (`title` + `icon`), lint
+  budgets, and launcher **names**. Facts that are true for the project.
+- **`spexcode.local.json`** — *gitignored, host-specific*: absolute launcher command paths,
+  cert/secret paths, and the private-overlay switch (`private: true`, which makes `spex materialize`
+  leave zero trace in the tracked tree — ignores go to the local git exclude, not the committed
+  `.gitignore` — so you can run SpexCode on a repo you share but don't own). Facts that are true for
+  one machine.
+
+There is no `spex config set` — you (or your agent) edit the files directly. **`spex guide config`**
+is the authoritative manual for every field and which of the two files it belongs in.
+
+### Run it
+
+Start the backend and the dashboard, then open the board:
 
 ```sh
-spex serve --port 8788                       # the backend (API + sessions) for THIS repo
-spex dashboard --port 5174 --api-port 8788   # the board UI, pointed at that backend
+spex serve          # the backend (API + sessions), on :8787
+spex dashboard      # the board UI on :5173, proxying /api to the backend
 ```
 
-Then open <http://localhost:5174>. With no flags, `spex serve` defaults to `:8787` and `spex dashboard`
-to `:5173`.
+Open <http://localhost:5173>.
+
+Both ports are flags (`spex serve --port 8788`, `spex dashboard --port 5174 --api-port 8788`), so
+you can run several projects' boards side by side; the working directory picks which project each
+serves. Give each tab its own identity in that project's `spexcode.json`: `dashboard.title` names it
+and `dashboard.icon` sets the favicon — an emoji (`"🔭"`), an Iconify name (`"mdi:rocket-launch"`),
+or a URL.
 
-Day to day:
+Day to day (the commands your agent runs for you — and that you can run yourself):
 
 | command | what it does |
 | --- | --- |
 | `spex lint` | check the spec↔code graph — coverage, drift, and the living-body rules |
 | `spex watch` | stream session / board transitions as they happen |
-| `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` file-format manuals |
+| `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` / `config` manuals |
 | `spex board` | dump the current board state as JSON |
 
-The spec tree is ground truth and git is its database: every change is a `spec.md` node, **rewritten in
-place** (never a `## vN` changelog) and versioned by its commits.
-
 ---
 
 ## Contributing to SpexCode
 
-This repository *is* the SpexCode source, and it **dogfoods itself**: every change to the tool lands as a
-spec node merged into `main`. Set up a checkout:
+This repository *is* the SpexCode source, and it dogfoods itself: every change to the tool lands as
+a spec node merged into `main`. Set up a checkout:
 
 ```sh
 git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
@@ -72,15 +130,21 @@ npm --prefix spec-dashboard install
 npm run hooks          # install the per-clone git hooks (main-guard + the session-stamp hook)
 ```
 
-The development loop runs from source, with hot-reload — this is what `npm run web` is for, as opposed
-to an installed user's `spex dashboard`:
+The development loop runs from source, with hot reload (`npm run web`, as opposed to an installed
+user's `spex dashboard`):
 
 ```sh
 npm run api            # backend on :8787, hot-reloads on spec-cli/src changes
 npm run web            # the dashboard via Vite (HMR), proxying /api → :8787
 ```
 
-The contribution ritual in one breath: branch `node/<id>` off `main`, make the code change **and** its
-`spec.md` *together*, commit, then `spex session done --propose merge` — a human performs the `--no-ff`
-merge. That ritual, the spec-node model, the lint rules, and the reflexive config system are all spelled
-out in **[`CLAUDE.md`](./CLAUDE.md)** — read it before your first change.
+---
+
+## Credits
+
+SpexCode was first introduced publicly on [LINUX DO](https://linux.do) — thanks to the community
+there for the first round of discussion and feedback.
+
+## License
+
+[MIT](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,135 @@
+<img src="docs/sdd-tuxedo-pooh.png" alt="写代码 vs. 维护一份活的、可执行的规格文档" width="420">
+
+[English](./README.md) | 中文
+
+> Spec 驱动开发通常死于两种方式:spec 和代码脱节,或者膨胀成一堆过时的仪式文档。SpexCode 让每个
+> spec 保持简短、保持当前态:原地重写,由 git 记版本,不做累积式的 changelog。
+
+**SpexCode** 是一个 spec 驱动、用自己开发自己的开发工具。项目的每个部分都是一个带版本的
+*spec 节点*,即一个 `.spec/**/spec.md`,正文描述这个部分当前的意图。git 就是数据库:节点的版本号
+是它的内容 commit 数,"drift" 指被管辖的代码走到了 spec 前面。`spex` CLI 和实时看板直接从 git
+读取这一切,没有第二份存储。
+
+- **[使用 SpexCode](#使用-spexcode)**:安装 `spex` CLI,通过你的 coding agent 治理*你自己的*项目。
+- **[参与开发](#参与开发)**:在本仓库里改进工具本身。
+- **[Working with agents →](https://spexcode.net/working-with-agents/)**:文档站上更完整的介绍。
+
+---
+
+## 使用 SpexCode
+
+SpexCode 只需要设置一次(`npm i -g spexcode`,然后在你的仓库里 `spex init`)。之后的主要用法是和
+你的 coding agent 对话:用自然语言说你要什么(*"给鉴权流程加一个 spec 节点""把这个包的 spec
+提取出来""派一个 worker 去实现 Y"*),agent 替你执行 `spex` CLI,你在看板上盯进度。下面的手动
+CLI 是底座,agent 才是日常界面。
+
+这套之所以成立,是因为新启动的 agent 已经认识 SpexCode。`spex init` 会把整套约定(spec 节点流程、
+先 commit 再声明完成、merge 方式)生成到仓库 `CLAUDE.md`/`AGENTS.md` 里的 `<!-- spexcode -->`
+托管块中,**[Claude Code](https://www.anthropic.com/claude-code)** 和 **Codex** 启动时自动读到。
+更细的内容 agent 自己按需查内置手册:`spex guide`(工作流)、`spex guide spec` /
+`spex guide yatsu`(文件格式)、`spex guide config`(`spexcode.json` 的全部配置项)。你可以直接
+对它说*"跑一下 `spex guide config`,帮我配好 launcher"*。
+
+完整的说明在文档站:**[working with agents](https://spexcode.net/working-with-agents/)** 讲
+agent 驱动的用法,**[getting started](https://spexcode.net/getting-started/)** 从头到尾走一遍安装。
+
+> **抛开 agent,它也是一套普通工具。** 核心部分单独用也成立:git 记版本的 spec 文件,`spex lint`
+> 检查,只读看板展示。不含 AI,除了 Node 和 git 什么都不用跑。vibe coding 的玩法建立在这层之上,
+> 不是替代它。
+
+> **环境要求。** 核心:**Node ≥ 22** 和 **git**。要通过 agent 驱动(或者往节点上派 worker),
+> 还需要 **tmux** 和 PATH 里已登录的 **Claude Code 或 Codex**。这些 agent 会在你的机器上执行
+> 命令,对外暴露后端之前请先读 [`SECURITY.md`](./docs/SECURITY.md)。
+
+### 安装
+
+装一次发布版 CLI,然后在任何项目里接入:
+
+```sh
+npm i -g spexcode      # 安装 spex 命令(需要 Node ≥ 22)
+cd ~/my-app
+spex init              # 纯增量,不会动你的代码结构
+```
+
+`spex init` 是增量式的:生成一棵起始 **`.spec/`** 树(根 `project` 节点,加上定义开发流程的
+`.config` 插件)、一份起始 **`spexcode.json`**、每个 clone 各自的 **git hooks**(`pre-commit`
+跑 **spec-lint**,spec↔code 链接坏了会拦下;**main-guard** 拦截直接向 `main` 的提交;
+`prepare-commit-msg` 给每个 commit 盖 session 归属戳)。同时生成 agent 路径需要的产物:
+`CLAUDE.md`/`AGENTS.md` 里的 `<!-- spexcode -->` 契约块,以及 `.claude/`、`.codex/` 的
+settings hooks。这些产物是生成物,已被 gitignore,每台机器各自重新生成,不进版本库。
+
+然后把它变成你的项目,让 agent 改或者自己动手都行:编辑 `.spec/project/spec.md` 描述项目,把
+`spexcode.json` 的 `lint.governedRoots` 指向真实源码目录,再检查一遍:
+
+```sh
+spex lint              # coverage 警告就是你的接入 TODO 清单
+```
+
+### 配置
+
+仓库根目录两个可选的 JSON 文件承载全部设置,按可移植性分开:
+
+- **`spexcode.json`**:提交进仓库,可移植。布局、看板标识(`title` + `icon`)、lint 预算、
+  launcher 的**名字**。对整个项目成立的事实。
+- **`spexcode.local.json`**:gitignore,单机。launcher 命令的绝对路径、证书和密钥路径、私有覆盖
+  开关(`private: true`,让 `spex materialize` 在被跟踪的文件里不留任何痕迹,ignore 写进本地
+  git exclude 而不是提交的 `.gitignore`,适合你参与但不拥有的仓库)。只对这台机器成立的事实。
+
+没有 `spex config set`,你(或你的 agent)直接编辑文件。每个字段的含义、该放哪个文件,
+**`spex guide config`** 是权威手册。
+
+### 运行
+
+启动后端和看板,打开页面:
+
+```sh
+spex serve          # 后端(API + sessions),:8787
+spex dashboard      # 看板 UI,:5173,/api 代理到后端
+```
+
+打开 <http://localhost:5173>。
+
+两个端口都是参数(`spex serve --port 8788`、`spex dashboard --port 5174 --api-port 8788`),
+多个项目的看板可以并排跑,工作目录决定各自服务哪个项目。每个标签页的身份在各自项目的
+`spexcode.json` 里配:`dashboard.title` 定名字,`dashboard.icon` 定 favicon,emoji(`"🔭"`)、
+Iconify 名字(`"mdi:rocket-launch"`)或 URL 都行。
+
+日常命令(agent 替你跑,你也可以自己跑):
+
+| 命令 | 作用 |
+| --- | --- |
+| `spex lint` | 检查 spec↔code 图:coverage、drift、living 规则 |
+| `spex watch` | 实时输出 session / 看板的状态变化 |
+| `spex guide` | 打印完整工作流,以及 `spec.md` / `yatsu.md` / `config` 手册 |
+| `spex board` | 以 JSON 输出当前看板状态 |
+
+---
+
+## 参与开发
+
+这个仓库就是 SpexCode 的源码,而且它 dogfood 自己:工具的每个改动都以 spec 节点的形式合入
+`main`。搭一个开发环境:
+
+```sh
+git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
+npm --prefix spec-cli install
+npm --prefix spec-dashboard install
+npm run hooks          # 安装每个 clone 各自的 git hooks(main-guard + session 戳)
+```
+
+开发循环直接跑源码,带热重载(开发用 `npm run web`,区别于安装用户的 `spex dashboard`):
+
+```sh
+npm run api            # 后端 :8787,spec-cli/src 改动即热重载
+npm run web            # Vite 起看板(HMR),/api 代理到 :8787
+```
+
+---
+
+## 致谢
+
+SpexCode 的首次公开介绍发在 [LINUX DO](https://linux.do),感谢佬友们的第一轮讨论和反馈。
+
+## License
+
+[MIT](./LICENSE)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",
@@ -24,12 +24,11 @@
     "node": ">=22"
   },
   "scripts": {
-    "api": "npm --prefix spec-cli run serve",
-    "web": "npm --prefix spec-dashboard run dev",
-    "lint": "npm --prefix spec-cli run -s lint",
-    "seed": "bash scripts/seed-spec-history.sh",
+    "api": "cd spec-cli && npm run serve",
+    "web": "cd spec-dashboard && npm run dev",
+    "lint": "cd spec-cli && npm run -s lint",
     "hooks": "bash scripts/install-hooks.sh",
-    "prepublishOnly": "node scripts/prepublish.mjs",
+    "prepack": "node scripts/prepack.mjs",
     "postinstall": "node -e \"try{require('fs').readdirSync('node_modules/node-pty/prebuilds').forEach(d=>{try{require('fs').chmodSync('node_modules/node-pty/prebuilds/'+d+'/spawn-helper',0o755)}catch{}})}catch{}\""
   },
   "dependencies": {

package/spec-cli/README.md

@@ -0,0 +1,86 @@
+<img src="docs/sdd-tuxedo-pooh.png" alt="Writing code vs. authoring a living, executable specification artifact" width="420">
+
+> Spec-driven development gets wrecked by spec drift and spec bloat. SpexCode's bet
+> is to keep the spec the cheap, honest twin of the code — rewritten in place, never
+> a tuxedo of stale ceremony.
+
+**SpexCode** is a spec-driven, self-developing dev tool. Every part of a project becomes a versioned
+*spec node* — a `.spec/**/spec.md` whose body states the part's *present* intent — and **git is the
+database**: a node's version is its count of content commits, and "drift" is governed code that moved
+ahead of its spec. A `spex` CLI plus a live dashboard read all of it straight from git; there is no
+separate store.
+
+There are two ways to meet SpexCode, and they are kept separate on purpose:
+
+- **[Using SpexCode](#using-spexcode)** — install the `spex` CLI from npm and govern *your own* project.
+- **[Contributing to SpexCode](#contributing-to-spexcode)** — develop the tool itself, in this repo.
+
+---
+
+## Using SpexCode
+
+You don't clone this repo to *use* SpexCode. Install the published CLI once, then point it at any project.
+
+```sh
+npm i -g spexcode      # installs the `spex` command (needs Node ≥ 22)
+```
+
+Adopt it in your project — `spex init` is **additive**, it never restructures your code:
+
+```sh
+cd ~/my-app
+spex init              # seed .spec/, a starter spexcode.json, and git hooks — nothing destructive
+# 1. edit .spec/project/spec.md to describe your project
+# 2. point spexcode.json's  lint.governedRoots  at your real source dir(s)
+spex lint              # the "coverage" warnings are your adoption TODO list
+```
+
+Run it. The backend and the dashboard are **two commands on two ports**, so several projects can run
+side by side on one host (the cwd picks which project is served):
+
+```sh
+spex serve --port 8788                       # the backend (API + sessions) for THIS repo
+spex dashboard --port 5174 --api-port 8788   # the board UI, pointed at that backend
+```
+
+Then open <http://localhost:5174>. With no flags, `spex serve` defaults to `:8787` and `spex dashboard`
+to `:5173`.
+
+Day to day:
+
+| command | what it does |
+| --- | --- |
+| `spex lint` | check the spec↔code graph — coverage, drift, and the living-body rules |
+| `spex watch` | stream session / board transitions as they happen |
+| `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` file-format manuals |
+| `spex board` | dump the current board state as JSON |
+
+The spec tree is ground truth and git is its database: every change is a `spec.md` node, **rewritten in
+place** (never a `## vN` changelog) and versioned by its commits.
+
+---
+
+## Contributing to SpexCode
+
+This repository *is* the SpexCode source, and it **dogfoods itself**: every change to the tool lands as a
+spec node merged into `main`. Set up a checkout:
+
+```sh
+git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
+npm --prefix spec-cli install
+npm --prefix spec-dashboard install
+npm run hooks          # install the per-clone git hooks (main-guard + the session-stamp hook)
+```
+
+The development loop runs from source, with hot-reload — this is what `npm run web` is for, as opposed
+to an installed user's `spex dashboard`:
+
+```sh
+npm run api            # backend on :8787, hot-reloads on spec-cli/src changes
+npm run web            # the dashboard via Vite (HMR), proxying /api → :8787
+```
+
+The contribution ritual in one breath: branch `node/<id>` off `main`, make the code change **and** its
+`spec.md` *together*, commit, then `spex session done --propose merge` — a human performs the `--no-ff`
+merge. That ritual, the spec-node model, the lint rules, and the reflexive config system are all spelled
+out in **[`CLAUDE.md`](./CLAUDE.md)** — read it before your first change.

package/spec-cli/bin/spex.mjs

@@ -3,6 +3,7 @@
 // run the TypeScript CLI directly. After `npm link` (or a global install) `spex lint` works anywhere.
 import { spawn } from 'node:child_process'
 import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 
@@ -11,9 +12,20 @@ import { dirname, join } from 'node:path'
 // `spex` work from any cwd (agents, git hooks) against this package's code, operating on the cwd.
 const pkg = join(dirname(fileURLToPath(import.meta.url)), '..') // spec-cli/
 const cli = join(pkg, 'src', 'cli.ts')
-// tsx lives in spec-cli/node_modules in the dev monorepo, but at the PUBLISHED package root's
-// node_modules (one level up: spec-cli is a subdir of the `spexcode` tarball) when installed. Try both.
+// tsx lives in spec-cli/node_modules in the dev monorepo, but npm may hoist it above the installed
+// `spexcode` package in a real consumer project. Try local candidates first, then let Node resolve upward
+// from spec-cli so project-local and global installs work the same way.
 const tsxCandidates = [join(pkg, 'node_modules', '.bin', 'tsx'), join(pkg, '..', 'node_modules', '.bin', 'tsx')]
-const tsx = tsxCandidates.find(existsSync) ?? tsxCandidates[0]
+function resolveTsx() {
+  const local = tsxCandidates.find(existsSync)
+  if (local) return local
+  try {
+    const req = createRequire(join(pkg, 'package.json'))
+    return join(dirname(req.resolve('tsx/package.json')), 'dist', 'cli.mjs')
+  } catch {
+    return tsxCandidates[0]
+  }
+}
+const tsx = resolveTsx()
 spawn(tsx, [cli, ...process.argv.slice(2)], { stdio: 'inherit' })
   .on('exit', (code) => process.exit(code ?? 0))

package/spec-cli/hooks/dispatch.sh

@@ -17,10 +17,12 @@
 #       the harness propagates. Pure bash, no node boot on the hot path (node runs only inside the gate, only
 #       on actual change). cwd = the project/worktree. $SPEX (abs tsx+cli) is inherited from the shim env.
 set -u
-# args: `<harness> <Event>`. A harness id as $1 (claude|codex) is consumed; otherwise we keep $1 as the event
-# and default the harness to claude — so a stale shim still rendered as `dispatch.sh <Event>` keeps working.
+# args: `<harness> <Event>`. A harness id as $1 (claude|codex|plugin) is consumed; otherwise we keep $1 as the
+# event and default the harness to claude — so a stale shim still rendered as `dispatch.sh <Event>` keeps working.
+# `plugin` is the bundle form ([[plugin-harness]]): it parses payloads as the claude family in harness.sh (z-code/
+# Claude share Claude's tool names + file_path), so it joins the claude branch there via the default case.
 harness=claude
-case "${1:-}" in claude|codex) harness="$1"; shift ;; esac
+case "${1:-}" in claude|codex|plugin) harness="$1"; shift ;; esac
 event="${1:?usage: dispatch.sh <harness> <Event>}"
 export SPEXCODE_HARNESS="$harness"
 # the harness.sh path (the adapter's shell mirror) — sibling of this script; hook handlers source it, and we
@@ -38,11 +40,21 @@ rt="$(cd "$proj" 2>/dev/null && hp_runtime_dir)" || rt=""
 cur="$( (cd "$proj" 2>/dev/null && hp_config_hash) )"
 if [ -n "$rt" ] && [ -n "$cur" ] && [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then
   mkdir -p "$rt" 2>/dev/null
-  ( flock 9
-    if [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then   # re-check: a sibling dispatch may have just rendered
-      ( cd "$proj" && ${SPEX:-spex} materialize >/dev/null 2>&1 )
-    fi
-  ) 9>"$rt/.materialize.lock"
+  # POSIX-portable mutex: mkdir is atomic on every POSIX fs, so it serializes the render with NO dependency on
+  # util-linux `flock` (absent on macOS — where it silently no-op'd, letting concurrent sessions race the write).
+  # Spin on `mkdir` with a bounded wait; after ~10s (200 * 0.05s, well above the ~0.85s materialize) treat the
+  # dir as orphaned by a dead entrant and clear it, so a stale lock can never deadlock a launch. Held only across
+  # the re-check + render, released right after.
+  lockd="$rt/.materialize.lock.d"
+  _lk=0
+  until mkdir "$lockd" 2>/dev/null; do
+    _lk=$((_lk+1)); [ "$_lk" -ge 200 ] && { rm -rf "$lockd" 2>/dev/null; _lk=0; }
+    sleep 0.05
+  done
+  if [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then   # re-check: a sibling dispatch may have just rendered
+    ( cd "$proj" && ${SPEX:-spex} materialize >/dev/null 2>&1 )
+  fi
+  rmdir "$lockd" 2>/dev/null
 fi
 
 # --- (2) dispatch ---------------------------------------------------------------------------------------

package/spec-cli/hooks/harness.sh

@@ -6,6 +6,9 @@
 # HERE; the hook scripts stay harness-agnostic and just call hp_* (the one place Claude's tool names appear in
 # shell, plus codex's Bash-command mapping). The session-id + global-store resolution is harness-agnostic and
 # lives here too, so the six hooks no longer each repeat the git-common-dir → project-key dance.
+# SPEXCODE_HARNESS is claude|codex|plugin: `plugin` is the bundle form ([[plugin-harness]]) and its host (z-code/
+# Claude) shares Claude's payload shape, so every `case "$SPEXCODE_HARNESS"` below routes it through the claude
+# branch via the default case — there is no separate `plugin)` arm to maintain.
 
 # the string value of a top-level JSON string field (first match). Harness-agnostic — both harnesses' payloads
 # carry session_id / tool_name as plain string fields. $1 = payload, $2 = field name. The value is scanned as a
@@ -54,13 +57,16 @@ hp_field() {
 }
 
 # the session id from a payload (both harnesses use session_id).
-# the GOVERNED record id the launcher baked into the session env (SPEXCODE_SESSION_ID) wins over the harness's
-# own payload session_id. This is what lets a dashboard-launched CODEX session feed its governed record: codex
-# mints its OWN thread id (un-pinnable), so the record can't be keyed by it — instead the launcher keys the
-# record by a SpexCode id and exports it into the launch, and every hook resolves THAT. Claude's payload id is
-# already the record id, so the env (= same value) is a harmless no-op there. A self-launched agent sets no
-# env → falls back to the payload session_id (its own non-governed record). One resolver, both harnesses.
-hp_session_id() { printf '%s' "${SPEXCODE_SESSION_ID:-$(hp_field "$1" session_id)}"; }
+# Codex hooks run inside ONE shared per-project app-server. That process can inherit the FIRST launched
+# session's SPEXCODE_SESSION_ID, so on codex the payload session_id (the acting thread id) must win and then
+# hp_store_dir aliases it to the governed record. Claude's payload id already equals its governed record id,
+# so preferring SPEXCODE_SESSION_ID there preserves the launcher's pinned id path.
+hp_session_id() {
+  case "$SPEXCODE_HARNESS" in
+    codex) hp_field "$1" session_id ;;
+    *)     printf '%s' "${SPEXCODE_SESSION_ID:-$(hp_field "$1" session_id)}" ;;
+  esac
+}
 
 # the per-PROJECT GLOBAL runtime dir (mirrors spec-cli/src/layout.ts `runtimeRoot`): <store>/projects/<enc>,
 # keyed by the project (dirname of the ABSOLUTE git-common-dir, so the answer is identical from main or any
@@ -75,10 +81,11 @@ hp_runtime_dir() {
 
 # the per-session GLOBAL store dir for a session id — <runtime>/sessions/<id> (sibling of the per-project
 # runtime above). Echoes the dir; returns non-zero (echoing nothing) when git can't resolve.
-# ALIAS resolution: a codex hook fires from the shared per-PROJECT app-server process, whose env carries NO
-# SPEXCODE_SESSION_ID, so hp_session_id falls back to the payload session_id = the codex THREAD id — NOT the
-# SpexCode record id the dir is keyed by. So when no record sits at <id> directly, find the one record that
-# captured this id as `harness_session_id` (the backend stored it at thread/start, before the first tool turn).
+# ALIAS resolution: a codex hook fires from the shared per-PROJECT app-server process, whose env may carry a
+# stale SPEXCODE_SESSION_ID from the first launched codex session. hp_session_id therefore returns the acting
+# payload session_id on codex: the codex THREAD id, NOT the SpexCode record id the dir is keyed by. So when no
+# record sits at <id> directly, find the one record that captured this id as `harness_session_id` (the backend
+# stored it at thread/start, before the first tool turn).
 # A grep over the few session.json files — no jq on the hot path; the trailing quote anchors the value so a
 # thread id can't match a longer one as a prefix. Direct hit wins; a miss with no alias echoes the direct path
 # unchanged, so the caller's `[ -e "$rec" ]` still no-ops gracefully. Mirrors layout.ts `readAliasedRawRecord`.